@counterfact-labs/cli 0.2.6 → 0.2.9

package/dist/contract/console.js

@@ -1,10 +1,12 @@
 import { z } from "zod";
-import { findingAudienceSchema, fixDeltaSchema, fixFactsSchema } from "../analysis-core/data/finding-types.js";
-import { inspectFixSchema, otherSiteSchema, rawFindingSchema } from "../analysis-core/analysis/schemas.js";
-import { sourceNotesSchema } from "../analysis-core/analysis/source-notes/types.js";
-import { parseAnalysisSize } from "../analysis-core/conventions/analysis-fit.js";
+import { parseAnalysisSize } from "../analysis-core/contracts/analysis-size.js";
 import { canonicalUuidSchema as uuid, matchingFindingNumbers, numberedFindingsSchema } from "./findings.js";
-import { RESULT_CHECK_LIMITS, validIntakeText } from "../analysis-core/contracts/relay-analysis.js";
+import { publicReportSchema } from "../analysis-core/contracts/relay-analysis.js";
+import { PLANNED_INPUT_BYTES } from "../analysis-core/requests/planned-limits.js";
+import { projectArchitectureSchema } from "./project-architecture.js";
+import { intakeFinding as localFindingSchema, nonblankText as text, RESULT_CHECK_LIMITS, validIntakeText } from "../analysis-core/contracts/intake-finding.js";
+export { localFindingSchema };
+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 +15,17 @@ 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;
+export const ADD_TO_ANALYSIS_HEADER = "x-counterfact-add-to-analysis";
 /** 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.addToAnalysisId ? { [ADD_TO_ANALYSIS_HEADER]: uuid.parse(metadata.addToAnalysisId) } : {}),
+        ...(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 +34,10 @@ 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)),
+        ...(headers.get(ADD_TO_ANALYSIS_HEADER) === null ? {} : { addToAnalysisId: uuid.parse(headers.get(ADD_TO_ANALYSIS_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 !== ""));
@@ -42,7 +51,7 @@ export const localStartRequestSchema = z.strictObject({
 export const localStartResponseSchema = z.strictObject({ jobId: uuid, projectId: uuid });
 export const relayPlanSchema = z.strictObject({
     bundleVersion: id, bundleHash: z.string().regex(/^[a-f0-9]{64}$/), relayVersion: id,
-    calls: z.array(z.strictObject({ routeId: id, model: id, calls: count(512), maxInputBytes: count(800_000),
+    calls: z.array(z.strictObject({ routeId: id, model: id, calls: count(512), maxInputBytes: count(PLANNED_INPUT_BYTES),
         maxInputTokens: count(200_000), maxOutputTokens: count(64_000) })).min(1).max(64)
         .refine(calls => new Set(calls.map(call => call.routeId)).size === calls.length && calls.reduce((sum, call) => sum + call.calls, 0) <= 512),
 });
@@ -84,44 +93,19 @@ export const consoleIntakeResultSchema = z.strictObject({
 export const LOCAL_FINDINGS_BODY_LIMIT = 2 * 1024 * 1024;
 export const LOCAL_FINDINGS_QUOTE_LIMIT = RESULT_CHECK_LIMITS.quoteBytes;
 export const LOCAL_FINDINGS_TEXT_LIMIT = RESULT_CHECK_LIMITS.textBytes;
-function shortFindingFields(value) {
-    if (typeof value === "string")
-        return Buffer.byteLength(value, "utf8") <= LOCAL_FINDINGS_TEXT_LIMIT;
-    return value === null || typeof value !== "object" || Object.values(value).every(shortFindingFields);
-}
-const quote = z.string().refine(value => Buffer.byteLength(value, "utf8") <= LOCAL_FINDINGS_QUOTE_LIMIT);
-const text = z.string().min(1).refine(value => value.trim().length > 0);
-const delta = fixDeltaSchema.extend({
-    nodes: z.array(fixDeltaSchema.shape.nodes.element.strict()),
-    edges: z.array(fixDeltaSchema.shape.edges.element.strict()),
-}).strict();
-const fix = inspectFixSchema.extend({
-    ...fixFactsSchema.shape,
-    targetFiles: z.array(inspectFixSchema.shape.targetFiles.element.strict()),
-    delta: delta.nullable(),
-}).strict();
-const notes = sourceNotesSchema.extend({
-    sites: z.array(sourceNotesSchema.shape.sites.element.extend({ keyPhrase: quote }).strict()),
-    counterEvidence: z.array(sourceNotesSchema.shape.counterEvidence.element.extend({ excerpt: quote }).strict()),
-}).strict();
-export const localFindingSchema = rawFindingSchema.extend({
-    audience: findingAudienceSchema.optional(),
-    summary: z.string().nullable(),
-    category: rawFindingSchema.shape.category.removeCatch(),
-    question: rawFindingSchema.shape.question.removeCatch().nullable(),
-    siteRepo: text.nullable(),
-    site: rawFindingSchema.shape.site.unwrap().strict().nullable(),
-    excerpt: quote.nullable(),
-    otherSites: z.array(otherSiteSchema.extend({ repo: text, excerpt: otherSiteSchema.shape.excerpt.pipe(quote) }).strict()),
-    fixes: z.array(fix).min(1),
-    sourceNotes: notes.nullable().optional(),
-}).strict().refine(shortFindingFields);
 const payload = z.strictObject({
     checkId: z.uuid(), projectId: z.uuid(), reservationId: uuid.optional(),
+    addToAnalysisId: uuid.optional(),
+    coverage: z.strictObject({ skippedFiles: z.array(z.strictObject({ path: localStartPath,
+            reason: publicReportSchema.shape.refusedFiles.element.shape.reason })),
+        readPaths: z.array(localStartPath) }).optional(),
+    findingAssessments: z.array(z.strictObject({ fingerprint: z.string().max(8192), support: z.enum(["complete", "incomplete"]),
+        confidence: z.enum(["sure", "not sure"]), weak: z.boolean(), reason: z.string().max(4096) })).optional(),
     agent: z.strictObject({
         repository: text.max(4096), commit: z.string().regex(/^(?:[a-f\d]{40}|[a-f\d]{64})$/i).nullable(),
         files: z.array(z.strictObject({ path: text.max(4096), hash: z.string().regex(/^[a-f\d]{64}$/i) })).min(1),
     }),
+    architecture: projectArchitectureSchema.optional(),
     findings: z.array(localFindingSchema), bundleVersion: text.max(128), relayVersion: text.max(128), counterfactLocalVersion: text.max(128),
 }).refine(validIntakeText);
 // Original JSON size is checked before a shared schema can trim text or apply defaults.

package/dist/contract/engine.js

@@ -3,7 +3,7 @@ import { ANALYSIS_PROTOCOL, analysisCapabilities } from "../analysis-core/contra
 import { stableStringify } from "../analysis-core/llm/stable-json.js";
 import { workloadHardware } from "../gatekeeper/trust/schema.js";
 import { kmsKeyName } from "../transport/kms.js";
-export const ENGINE_ABI = 1;
+export const ENGINE_ABI = 2;
 export const ENGINE_SPAWNER_CONTRACT = 1;
 const hash = z.string().regex(/^[0-9a-f]{64}$/);
 const version = z.string().min(1).max(128).regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/);

package/dist/contract/messages.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { analysisRelease } from "./engine.js";
-import { executionRequest } from "../analysis-core/contracts/requests.js";
+import { executionRequest } from "../analysis-core/contracts/execution-request.js";
+import { PLANNED_INPUT_BYTES } from "../analysis-core/requests/planned-limits.js";
 import { compactJwtPattern, hexChallenge } from "./attestation.js";
 export { PRODUCTION_EVIDENCE_VERSION, RELAY_CHANNEL_AUDIENCE, RELAY_PORT, RELAY_URL, RELAY_HEALTH_PATH, RELAY_HEALTH_URL, GOOGLE_ATTESTATION_ISSUER, MAX_ATTESTATION_BYTES, attestationChallenge, productionEvidence, evidenceBinding, googleAttestationClaims, observedAttestationClaims, probeAttestationClaims, attestationClaims } from "./attestation.js";
 /**
@@ -66,14 +67,14 @@ const outputCount = z.number().int().nonnegative().max(64_000);
 /** A reservation lookup establishes the owner without reserving spend or contacting the model provider. */
 export const reservationCheck = z.object({ action: z.literal("check"), ...billingScope }).strict();
 export const reservationIdentity = z.object({ clientId: z.string().min(1).max(128) }).strict();
-export const callCounts = z.object({ inputBytes: z.number().int().positive().max(800_000),
+export const callCounts = z.object({ inputBytes: z.number().int().positive().max(PLANNED_INPUT_BYTES),
     inputTokens: inputCount.positive(), maxOutputTokens: outputCount.positive() }).strict();
 export const authorizationRequest = z.object({ action: z.literal("authorize"), ...billingScope,
     routeId: billingId, templateId: billingId, answerFormatId: billingId, model: billingId, ...callCounts.shape }).strict();
 export const callAuthorization = z.object({ attemptId: z.uuid(), model: billingId, role: z.enum(["required", "optional"]),
     /** Stable opaque owner supplied only by the authenticated authorization service. */
     clientId: reservationIdentity.shape.clientId,
-    deadline: z.iso.datetime(), countLimits: z.object({ maxInputBytes: z.number().int().positive().max(800_000),
+    deadline: z.iso.datetime(), countLimits: z.object({ maxInputBytes: z.number().int().positive().max(PLANNED_INPUT_BYTES),
         maxInputTokens: inputCount.positive(), maxOutputTokens: outputCount.positive() }).strict() }).strict();
 export const providerUsage = z.object({ kind: z.enum(["actual", "estimated", "unpaid"]),
     outcome: z.enum(["success", "unknown", "retryable_failure", "terminal_provider_failure", "schema_refusal", "leak_refusal"]),

package/dist/contract/project-architecture.js

@@ -0,0 +1 @@
+export { PROJECT_ARCHITECTURE_BYTES, projectArchitectureSchema, projectArchitecture } from "../analysis-core/analysis/project-architecture.js";

package/dist/contract/scope-choice.js

@@ -0,0 +1,98 @@
+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";
+// Coverage wording stays here so the CLI and MCP cannot make 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 MULTI_ENTRY_CHOOSE_SCOPE_MESSAGE = "These agent files are too many or too large for one analysis. 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 ENTRY_GROUP_LABEL = "Several agent files and their imports";
+export const ENTRY_GROUP_DESCRIPTION = "Read the agent files and their project imports listed below. Leave the other selected files out of this analysis.";
+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 ANALYSIS_TOO_LARGE_MESSAGE = "This analysis is too large to run at once. Choose one agent file or a smaller folder, such as one agent's folder.";
+/** Recovery may offer a file only when this run accepts file selections. */
+export function selectionRefusalMessage(message, fileMode) {
+    if (!fileMode && message === INVALID_SELECTION_MESSAGE)
+        return "Choose a folder inside this project, or start Claude Code or Codex in the folder you want to analyze.";
+    if (!fileMode && message === ANALYSIS_TOO_LARGE_MESSAGE)
+        return "This analysis is too large to run at once. Choose a smaller folder, such as one agent's folder.";
+    return message;
+}
+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 OMITTED_FILES_CAPTION = "Files 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 function scopeChoiceWording(choice, fits) {
+    const group = (choice.scope.entries ?? []).filter(entry => choice.includes.includes(entry)).length > 1;
+    const entryOnly = choice.scope.imports === "none" || Array.isArray(choice.scope.imports) && choice.scope.imports.length === 0;
+    const fullImports = choice.scope.imports === "all" || choice.coverage === "entry-imports";
+    return {
+        label: group ? ENTRY_GROUP_LABEL : entryOnly ? ENTRY_ONLY_LABEL : fullImports ? ENTRY_IMPORTS_LABEL : SELECTED_IMPORTS_LABEL,
+        description: entryOnly && fits === false ? SINGLE_FILE_TOO_LARGE_MESSAGE
+            : (group ? ENTRY_GROUP_DESCRIPTION : entryOnly ? ENTRY_ONLY_DESCRIPTION : fullImports ? ENTRY_IMPORTS_DESCRIPTION : SELECTED_IMPORTS_DESCRIPTION)
+                .replace("{entry}", () => choice.scope.entry),
+    };
+}
+export const scopeChoiceSchema = provenScopeChoiceSchema.safeExtend({
+    label: z.enum([ENTRY_ONLY_LABEL, SELECTED_IMPORTS_LABEL, ENTRY_IMPORTS_LABEL, ENTRY_GROUP_LABEL]),
+    description: z.string().min(1).max(8192),
+    // Local measurement can prove a group fits; ordinary run admission checks it again.
+    fits: z.union([z.boolean(), z.literal("unknown")]),
+}).refine(choice => {
+    const { label, description } = scopeChoiceWording(choice, choice.fits);
+    return choice.label === label && choice.description === description;
+});
+export const chooseScopeResultSchema = z.strictObject({
+    kind: z.literal("choose_scope"), text: z.enum([CHOOSE_SCOPE_MESSAGE, MULTI_ENTRY_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()
+                .refine(text => [CHOOSE_SCOPE_MESSAGE, MULTI_ENTRY_CHOOSE_SCOPE_MESSAGE].some(message => text.startsWith(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,40 @@
+import { CHOOSE_SCOPE_MESSAGE, MULTI_ENTRY_CHOOSE_SCOPE_MESSAGE, scopeChoiceWording, 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 && !options.allowCurrent)
+            return [];
+        seen.add(key);
+        const { label, description } = scopeChoiceWording(choice, knownOversized ? false : "unknown");
+        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: membership.kind === "file" && membership.entries ? MULTI_ENTRY_CHOOSE_SCOPE_MESSAGE : CHOOSE_SCOPE_MESSAGE, snapshot: membership.snapshot,
+        entry: membership.kind === "file" && !membership.entries ? membership.entry : null, coverageComplete: membership.completeness.complete,
+        frontierCount: membership.completeness.frontierCount, choices, imports, refusedEdges: membership.refusedEdges };
+}

package/dist/gatekeeper/cli-api.js

@@ -1,7 +1,8 @@
-import { cliRefusals, refusalExitCode } from "../contract/cli-refusals.js";
+import { cliRefusals, localFailure, refusalExitCode } from "../contract/cli-refusals.js";
 import { CLI_VERSION } from "../contract/cli-version.js";
 import { consoleSchemeAllowed } from "../contract/console-url.js";
 import { cliApiMessages } from "../contract/cli-api-messages.js";
+import { selectionRefusalMessage } from "../contract/scope-choice.js";
 import { emailSignInMessages } from "../contract/email-sign-in-messages.js";
 import { CLI_BODY_LIMIT } from "../cli/api-types.js";
 import { findingNumberParamsSchema } from "../contract/findings.js";
@@ -20,6 +21,9 @@ export class ApiError extends Error {
         this.reason = reason;
     }
 }
+export class SavedSignInError extends ApiError {
+    constructor() { super(0, "invalid_request", cliApiMessages.unreadable_sign_in_terminal, 0, "invalid_request"); }
+}
 const emailRoutes = {
     "email/start": { fields: ["email"], successStatus: 202, failures: { invalid_email: 400 }, jsonCooldown: true },
     "email/verify": { fields: ["email", "code", "clientName"], successStatus: 200,
@@ -27,6 +31,49 @@ const emailRoutes = {
 };
 // Longer cooldowns keep the server's delay but use the sentence without a duration.
 const MAX_DISPLAYED_EMAIL_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+const transportErrorCodes = new Set([
+    "ECONNREFUSED", "ECONNRESET", "ECONNABORTED", "EPIPE", "ENETUNREACH", "ENETDOWN", "EHOSTUNREACH", "EHOSTDOWN",
+    "ENETRESET", "EADDRNOTAVAIL", "EPROTO", "ENOTFOUND", "EAI_AGAIN", "EAI_FAIL", "ETIMEDOUT", "ETIMEOUT", "ESERVFAIL", "ENODATA",
+    // Certificate verification can fail without an SSL or TLS prefix.
+    "UNABLE_TO_GET_ISSUER_CERT", "UNABLE_TO_GET_CRL", "UNABLE_TO_DECRYPT_CERT_SIGNATURE",
+    "UNABLE_TO_DECRYPT_CRL_SIGNATURE", "UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY", "CERT_SIGNATURE_FAILURE",
+    "CRL_SIGNATURE_FAILURE", "CERT_NOT_YET_VALID", "CERT_HAS_EXPIRED", "CRL_NOT_YET_VALID", "CRL_HAS_EXPIRED",
+    "ERROR_IN_CERT_NOT_BEFORE_FIELD", "ERROR_IN_CERT_NOT_AFTER_FIELD", "ERROR_IN_CRL_LAST_UPDATE_FIELD",
+    "ERROR_IN_CRL_NEXT_UPDATE_FIELD", "DEPTH_ZERO_SELF_SIGNED_CERT", "SELF_SIGNED_CERT_IN_CHAIN",
+    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY", "UNABLE_TO_VERIFY_LEAF_SIGNATURE", "CERT_CHAIN_TOO_LONG", "CERT_REVOKED",
+    "NO_ISSUER_PUBLIC_KEY", "PATH_LENGTH_EXCEEDED", "INVALID_PURPOSE", "CERT_UNTRUSTED", "CERT_REJECTED",
+    "SUBJECT_ISSUER_MISMATCH", "AKID_SKID_MISMATCH", "AKID_ISSUER_SERIAL_MISMATCH", "KEYUSAGE_NO_CERTSIGN",
+    "UNABLE_TO_GET_CRL_ISSUER", "UNHANDLED_CRITICAL_EXTENSION", "KEYUSAGE_NO_CRL_SIGN",
+    "UNHANDLED_CRITICAL_CRL_EXTENSION", "INVALID_NON_CA", "PROXY_PATH_LENGTH_EXCEEDED",
+    "KEYUSAGE_NO_DIGITAL_SIGNATURE", "PROXY_CERTIFICATES_NOT_ALLOWED", "INVALID_EXTENSION",
+    "INVALID_POLICY_EXTENSION", "NO_EXPLICIT_POLICY", "DIFFERENT_CRL_SCOPE", "UNSUPPORTED_EXTENSION_FEATURE",
+    "UNNESTED_RESOURCE", "PERMITTED_VIOLATION", "EXCLUDED_VIOLATION", "SUBTREE_MINMAX", "APPLICATION_VERIFICATION",
+    "UNSUPPORTED_CONSTRAINT_TYPE", "UNSUPPORTED_CONSTRAINT_SYNTAX", "UNSUPPORTED_NAME_SYNTAX",
+    "CRL_PATH_VALIDATION_ERROR", "PATH_LOOP", "SUITE_B_INVALID_VERSION", "SUITE_B_INVALID_ALGORITHM",
+    "SUITE_B_INVALID_CURVE", "SUITE_B_INVALID_SIGNATURE_ALGORITHM", "SUITE_B_LOS_NOT_ALLOWED",
+    "SUITE_B_CANNOT_SIGN_P_384_WITH_P_256", "HOSTNAME_MISMATCH", "EMAIL_MISMATCH", "IP_ADDRESS_MISMATCH",
+    "DANE_NO_MATCH", "EE_KEY_TOO_SMALL", "CA_KEY_TOO_SMALL", "CA_MD_TOO_WEAK", "NO_VALID_SCTS",
+    "PROXY_SUBJECT_NAME_VIOLATION", "OCSP_VERIFY_NEEDED", "OCSP_VERIFY_FAILED", "OCSP_CERT_UNKNOWN",
+    "UNSUPPORTED_SIGNATURE_ALGORITHM", "SIGNATURE_ALGORITHM_MISMATCH", "SIGNATURE_ALGORITHM_INCONSISTENCY",
+    "INVALID_CA", "PATHLEN_INVALID_FOR_NON_CA", "PATHLEN_WITHOUT_KU_KEY_CERT_SIGN",
+    "KU_KEY_CERT_SIGN_INVALID_FOR_NON_CA", "ISSUER_NAME_EMPTY", "SUBJECT_NAME_EMPTY",
+    "MISSING_AUTHORITY_KEY_IDENTIFIER", "MISSING_SUBJECT_KEY_IDENTIFIER", "EMPTY_SUBJECT_ALT_NAME",
+    "EMPTY_SUBJECT_SAN_NOT_CRITICAL", "CA_BCONS_NOT_CRITICAL", "AUTHORITY_KEY_IDENTIFIER_CRITICAL",
+    "SUBJECT_KEY_IDENTIFIER_CRITICAL", "CA_CERT_MISSING_KEY_USAGE", "EXTENSIONS_REQUIRE_VERSION_3",
+    "EC_KEY_EXPLICIT_PARAMS", "RPK_UNTRUSTED",
+]);
+function transportFailed(error, depth = 0) {
+    if (!(error instanceof Error) || depth > 4)
+        return false;
+    if ("code" in error && typeof error.code === "string") {
+        if (error.code === "ERR_INVALID_URL" || error.code === "UND_ERR_INVALID_ARG")
+            return false;
+        if (transportErrorCodes.has(error.code) || /^(?:UND_ERR_|ERR_SSL_|ERR_TLS_|EAI_|CERT_|CRL_)/.test(error.code))
+            return true;
+    }
+    return transportFailed(error.cause, depth + 1)
+        || error instanceof AggregateError && error.errors.some((cause) => transportFailed(cause, depth + 1));
+}
 function retryAfterMs(value, rejectNegativeSeconds = false) {
     if (!value)
         return undefined;
@@ -97,11 +144,13 @@ export class ApiClient {
     token;
     fetcher;
     signal;
+    classifyTransportErrors;
     baseUrl;
-    constructor(baseUrl, token, fetcher = fetch, signal) {
+    constructor(baseUrl, token, fetcher = fetch, signal, classifyTransportErrors = true) {
         this.token = token;
         this.fetcher = fetcher;
         this.signal = signal;
+        this.classifyTransportErrors = classifyTransportErrors;
         let url;
         try {
             url = new URL(baseUrl);
@@ -132,6 +181,15 @@ export class ApiClient {
         }
         if (body !== undefined)
             headers["content-type"] = "application/json";
+        // Fetch also validates headers locally. Keep that failure outside the transport catch.
+        if (this.classifyTransportErrors) {
+            try {
+                new Headers(headers);
+            }
+            catch {
+                throw new SavedSignInError();
+            }
+        }
         const serialized = body === undefined ? undefined : JSON.stringify(safeBody);
         if (serialized !== undefined && Buffer.byteLength(serialized, "utf8") > CLI_BODY_LIMIT) {
             throw new ApiError(413, "body_too_large", cliRefusals.body_too_large);
@@ -151,8 +209,14 @@ export class ApiClient {
                     redirect: "error", signal: controller.signal,
                 });
             }
-            catch {
+            catch (error) {
                 throwIfAborted();
+                // Fetch can refuse locally before creating a request, so rejection alone is not transport evidence.
+                if (this.classifyTransportErrors && !controller.signal.aborted && !transportFailed(error)) {
+                    if (localFailure(error))
+                        throw error;
+                    throw new ApiError(0, "request_failed", cliApiMessages.request_failed);
+                }
                 throw new ApiError(0, "unreachable", cliApiMessages.unreachable, 0, "console_unreachable");
             }
             throwIfAborted();
@@ -190,4 +254,6 @@ export class ApiClient {
     }
 }
 export function errorCode(error) { return refusalExitCode(error instanceof ApiError ? error.code : undefined); }
-export function errorText(error) { return error instanceof Error ? error.message : cliApiMessages.request_failed; }
+export function errorText(error, fileMode = true) {
+    return selectionRefusalMessage(localFailure(error)?.message ?? (error instanceof Error ? error.message : cliApiMessages.request_failed), fileMode);
+}

package/dist/gatekeeper/console.js

@@ -1,8 +1,9 @@
 import { consoleSchemeAllowed } from "../contract/console-url.js";
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
+import { z } from "zod";
 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 +12,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,10 +43,21 @@ 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);
+/** Strict older consoles accept optional metadata only after explicitly advertising it. */
+export function consoleCapabilities(mode) {
+    return {
+        skippedFiles: "skippedFiles" in mode && mode.skippedFiles === true,
+        findingActivity: "findingActivity" in mode && mode.findingActivity === true,
+        architecture: "architecture" in mode && mode.architecture === true,
+    };
+}
 /** Only this client may send repository metadata, content-free lifecycle or findings-only intake payloads to the console. */
 export class ConsoleClient {
     #url;
@@ -54,15 +69,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;
@@ -78,6 +93,13 @@ export class ConsoleClient {
         }
         return this.#send("/api/cli/checks", input, localStartRequestSchema, localStartResponseSchema, LOCAL_START_BODY_LIMIT, { statuses: [201], headers: { ...headers, [LOCAL_START_EXECUTION_HEADER.name]: LOCAL_START_EXECUTION_HEADER.value }, context: "start" });
     }
+    async capabilities() {
+        const mode = await this.#send("/api/cli/checks/mode", {}, z.object({}), z.object({ skippedFiles: z.boolean().optional() }).passthrough(), 1024, { method: "GET", context: "start" });
+        return consoleCapabilities(mode);
+    }
+    async supportsSkippedFiles() {
+        return (await this.capabilities()).skippedFiles;
+    }
     create(input) {
         return this.#lifecycle({ ...input, action: "create" }, consoleCreatedSchema);
     }
@@ -93,8 +115,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 +142,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;
@@ -133,18 +156,22 @@ export class ConsoleClient {
             };
             const destination = new URL(path, this.#url);
             const request = (destination.protocol === "https:" ? httpsRequest : httpRequest)(destination, {
-                method: "POST", agent: false, rejectUnauthorized: true, maxHeaderSize: 16 * 1024,
+                method: options.method ?? "POST", agent: false, rejectUnauthorized: true, maxHeaderSize: 16 * 1024,
                 headers: { "x-counterfact-cli-version": CLI_VERSION, authorization: `Bearer ${this.#token}`, "content-type": "application/json", accept: "application/json",
-                    "content-length": body.length, "accept-encoding": "identity",
+                    "content-length": options.method === "GET" ? 0 : body.length, "accept-encoding": "identity",
                     ...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 +180,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()));
-            request.end(body);
-        }).catch(error => { throw new ConsoleError(error instanceof ConsoleError ? error.code : "unavailable", options.context); });
+            const timer = setTimeout(() => { finish(interrupted()); request.destroy(); }, this.#timeoutMs);
+            request.on("error", () => finish(interrupted()));
+            request.end(options.method === "GET" ? undefined : body);
+        }).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 } : {}); });
     }
 }