@counterfact-labs/cli 0.2.4 → 0.2.6

package/dist/cli/sign-in.js

@@ -1,6 +1,13 @@
 import { ApiError } from "./api.js";
 import { readCredentials, saveCredentials } from "./credentials.js";
 import { emailSignInMessages } from "../contract/email-sign-in-messages.js";
+import { cliApiMessages } from "../contract/cli-api-messages.js";
+export class SignInExpiredError extends ApiError {
+    constructor() { super(400, "expired", emailSignInMessages.browser_expired); }
+}
+export class SignInDeniedError extends Error {
+    constructor() { super(emailSignInMessages.cancelled); }
+}
 async function pollSignIn(ctx, device) {
     const until = ctx.now() + device.expiresIn * 1000;
     while (ctx.now() < until) {
@@ -15,12 +22,64 @@ async function pollSignIn(ctx, device) {
         if (poll.status === "denied")
             throw new Error(emailSignInMessages.cancelled);
     }
-    throw new Error("The sign-in code expired. Run counterfact-labs login to try again.");
+    throw new SignInExpiredError();
+}
+async function pollSignInWithRetry(ctx, device) {
+    const until = ctx.now() + device.expiresIn * 1000;
+    const interval = device.interval * 1000;
+    let delay = interval;
+    while (ctx.now() < until) {
+        await ctx.sleep(Math.min(delay, until - ctx.now()));
+        if (ctx.now() >= until)
+            break;
+        let poll;
+        try {
+            poll = await ctx.api.request("device/token", { deviceCode: device.deviceCode }, false, { timeoutMs: Math.min(120_000, until - ctx.now()) });
+        }
+        catch (error) {
+            ctx.signal?.throwIfAborted();
+            if (!(error instanceof ApiError) || !(error.status === 0 || error.status === 408 || error.status === 429
+                || (error.status >= 500 && error.status < 600)))
+                throw error;
+            // A temporary failure cannot tell us whether the user approved the code.
+            delay = Math.max(interval, error.retryAfterMs);
+            continue;
+        }
+        delay = interval;
+        if (!poll)
+            throw new Error(cliApiMessages.invalid_response);
+        if (poll.status === "ok") {
+            // The server has consumed the code, so keep its token even after local expiry.
+            await saveCredentials(ctx.homeDir, ctx.api.baseUrl, poll.token);
+            return "signed_in";
+        }
+        if (poll.status === "expired")
+            break;
+        if (poll.status === "denied")
+            throw new SignInDeniedError();
+    }
+    throw new SignInExpiredError();
 }
 export async function startSignIn(ctx) {
     const device = await ctx.api.request("device", {}, false);
     return { userCode: device.userCode, verificationUri: device.verificationUri,
-        pageUrl: `${device.verificationUri}?code=${encodeURIComponent(device.userCode)}`, done: pollSignIn(ctx, device) };
+        pageUrl: `${device.verificationUri}?code=${encodeURIComponent(device.userCode)}`, retryEnabled: ctx.signInRetry,
+        done: ctx.signInRetry ? pollSignInWithRetry(ctx, device) : pollSignIn(ctx, device) };
+}
+export async function waitForSignIn(flow, signal) {
+    signal.throwIfAborted();
+    let cancel;
+    const cancelled = new Promise((_resolve, reject) => {
+        cancel = () => reject(signal.reason);
+        signal.addEventListener("abort", cancel, { once: true });
+    });
+    // A cancelled tool wait must leave the shared browser sign-in running.
+    try {
+        return await Promise.race([flow.done, cancelled]);
+    }
+    finally {
+        signal.removeEventListener("abort", cancel);
+    }
 }
 export async function signInStatus(ctx) {
     if (!await readCredentials(ctx.homeDir, ctx.api.baseUrl))

package/dist/cli/summary.js

@@ -1,12 +1,19 @@
 import { findingPresentation } from "../analysis-core/findings/presentation.js";
-export function formatSummary(report) {
+import { findingDisplayRows, TEAM_WORKFLOW_HEADING } from "./finding-display.js";
+export function formatSummary(report, options) {
     const lines = ["# Counterfact analysis", "",
         `${report.findings.length} findings; ${report.structures.length} structural proposals.`, ""];
     if (!report.findings.length)
         lines.push("No findings.", "");
-    for (const [index, finding] of report.findings.entries()) {
+    const findings = report.findings.map(finding => {
         const presentation = findingPresentation(finding);
-        lines.push(`## ${index + 1}. ${presentation.displayTitle}`, "");
+        return { ...finding, presentation, title: presentation.displayTitle };
+    });
+    for (const { finding, label, startsTeamGroup } of findingDisplayRows(findings, { ...options, labels: "position" })) {
+        const { presentation } = finding;
+        if (startsTeamGroup)
+            lines.push(`## ${TEAM_WORKFLOW_HEADING}`, "");
+        lines.push(`## ${label}`, "");
         if (presentation.ifLeft)
             lines.push(`If left: ${presentation.ifLeft}`, "");
         lines.push(`Severity: ${finding.severity}; category: ${finding.category ?? "unclassified"}.`, "", finding.cause, "");

package/dist/contract/agent-choice.js

@@ -0,0 +1,15 @@
+export const CHOOSE_AGENT_MESSAGE = "Counterfact couldn't tell which folder holds your agent. Run it again on that folder, for example";
+export const NO_AGENT_MESSAGE = "Counterfact couldn't find an agent prompt in this folder. Pass a folder containing an agent prompt or a model call with a system prompt.";
+/** The local importer supplies the choice; transport keeps its data and wording together. */
+export class AgentChoiceError extends Error {
+    agentChoice;
+    constructor(agentChoice) {
+        const folders = [...new Set(agentChoice.candidates.map(candidate => candidate.folder))];
+        super(agentChoice.kind === "choose_agent" ? [`${CHOOSE_AGENT_MESSAGE} counterfact-labs analyze ${shellArgument(folders[0])}.`, "These folders look like agents:", ...folders].join("\n") : NO_AGENT_MESSAGE);
+        this.agentChoice = agentChoice;
+    }
+}
+/** Folder names must remain literal when a user pastes the suggested command. */
+function shellArgument(folder) {
+    return /^[a-zA-Z0-9_./-]+$/.test(folder) ? folder : `'${folder.replaceAll("'", "'\\''")}'`;
+}

package/dist/contract/agent-proposal.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { importProposalEnabled } from "../analysis-core/index.js";
+export const INVALID_PROPOSAL_MESSAGE = "The proposed agent files couldn't be used, because a path is outside the folder or isn't a file Counterfact can read.";
+export const INVALID_PROPOSAL_FORMAT_MESSAGE = "The proposed agent files couldn't be used, because the proposal needs an agent name and a list of files with supported roles.";
+// Check both path separators so a proposal has the same meaning on every host.
+export const agentProposalSchema = z.object({
+    agentName: z.string().min(1).max(200).regex(/^[^\p{C}\p{Zl}\p{Zp}]+$/u),
+    files: z.array(z.object({
+        path: z.string().min(1).max(512).regex(/^(?![A-Za-z]:)(?![/\\])(?!.*(?:^|[/\\])\.\.(?:[/\\]|$))[^\p{C}\p{Zl}\p{Zp}]+$/u)
+            .describe("Paths are relative to the agent folder."),
+        role: z.enum(["prompt", "tools", "model-calling code", "config", "other"]),
+    })).max(200),
+});
+export const agentProposalInputSchema = z.toJSONSchema(agentProposalSchema);
+delete agentProposalInputSchema.$schema;
+function validateAgentProposal(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = agentProposalSchema.safeParse(value);
+    if (!parsed.success) {
+        const invalidPath = parsed.error.issues.some(issue => issue.path[0] === "files" && issue.path[2] === "path");
+        throw new Error(invalidPath ? INVALID_PROPOSAL_MESSAGE : INVALID_PROPOSAL_FORMAT_MESSAGE);
+    }
+    return parsed.data;
+}
+/** Check the switch before invoking a loader so disabled proposals never open files. */
+export async function loadAgentProposal(load, settings) {
+    if (!importProposalEnabled(settings))
+        return undefined;
+    let value;
+    try {
+        value = await load();
+    }
+    catch {
+        throw new Error("The proposal file couldn't be read as JSON.");
+    }
+    return validateAgentProposal(value);
+}

package/dist/contract/attestation.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+import { allowsRuntimeOverrides, checkRuntimeEnvironment } from "./runtime-environment.js";
+// Identity contracts stay independent of analysis requests so probes cannot load private rules.
+export const compactJwtPattern = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+export const hexChallenge = z.string().length(64).regex(/^[0-9a-f]+$/);
+export const PRODUCTION_EVIDENCE_VERSION = 1;
+export const RELAY_CHANNEL_AUDIENCE = "https://relay.counterfactlabs.com";
+// Passthrough forwarding keeps the non-root workload's listener port unchanged.
+export const RELAY_PORT = 8443;
+export const RELAY_URL = `${RELAY_CHANNEL_AUDIENCE}:${RELAY_PORT}`;
+export const RELAY_HEALTH_PATH = "/health";
+export const RELAY_HEALTH_URL = `${RELAY_URL}${RELAY_HEALTH_PATH}`;
+export const GOOGLE_ATTESTATION_ISSUER = "https://confidentialcomputing.googleapis.com";
+export const MAX_ATTESTATION_BYTES = 32 * 1024;
+export const attestationChallenge = z.object({
+    version: z.literal(PRODUCTION_EVIDENCE_VERSION),
+    challenge: hexChallenge,
+}).strict();
+export const productionEvidence = z.object({
+    version: z.literal(PRODUCTION_EVIDENCE_VERSION),
+    token: z.string().max(MAX_ATTESTATION_BYTES).regex(compactJwtPattern),
+}).strict();
+/** Google's launcher accepts up to six caller nonces, each at most 74 characters. */
+export const evidenceBinding = z.object({
+    audience: z.string().min(1).max(256).regex(/^[A-Za-z0-9:/._-]+$/),
+    nonces: z.array(z.string().min(1).max(74).regex(/^[A-Za-z0-9_:-]+$/)).min(1).max(6),
+}).strict();
+/** Native claims are interpreted only after the PKI chain and token signature are authenticated. */
+export const googleAttestationClaims = z.object({
+    iss: z.literal(GOOGLE_ATTESTATION_ISSUER),
+    aud: z.string(),
+    sub: z.string(),
+    iat: z.number().int(),
+    nbf: z.number().int(),
+    exp: z.number().int(),
+    eat_nonce: z.union([z.string(), z.array(z.string()).min(1).max(6)]),
+    secboot: z.literal(true),
+    dbgstat: z.literal("disabled-since-boot"),
+    oemid: z.literal(11129),
+    hwmodel: z.string(),
+    swname: z.literal("CONFIDENTIAL_SPACE"),
+    swversion: z.array(z.string()).length(1),
+    google_service_accounts: z.array(z.string()).min(1),
+    development: z.never().optional(),
+    identity: z.never().optional(),
+    submods: z.object({
+        confidential_space: z.object({
+            support_attributes: z.array(z.string()),
+            monitoring_enabled: z.object({ memory: z.literal(false) }).passthrough(),
+        }).passthrough(),
+        container: z.object({
+            image_digest: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+            image_signatures: z.array(z.object({
+                key_id: z.string(), signature: z.string().min(1),
+                signature_algorithm: z.literal("RSASSA_PSS_SHA256"),
+            }).passthrough()).min(1),
+            // Google omits override claims when nothing was overridden; only the owned clock rollback setting is allowed.
+            cmd_override: z.array(z.unknown()).length(0).optional(),
+            env_override: z.record(z.string(), z.string()).refine(allowsRuntimeOverrides).optional(),
+            // Real tokens list the container's own environment; the relay's start-up rule decides which settings are allowed.
+            env: z.record(z.string(), z.string()).refine(env => {
+                try {
+                    checkRuntimeEnvironment(env);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }),
+        }).passthrough(),
+    }).passthrough(),
+}).passthrough();
+/** Authenticated observations describe a refused workload without granting it an admitted identity. */
+export const observedAttestationClaims = googleAttestationClaims.extend({
+    dbgstat: z.string(),
+    submods: googleAttestationClaims.shape.submods.extend({
+        container: googleAttestationClaims.shape.submods.shape.container.extend({
+            image_signatures: z.array(googleAttestationClaims.shape.submods.shape.container.shape.image_signatures.element),
+            cmd_override: z.array(z.unknown()).optional(),
+            env_override: z.record(z.string(), z.unknown()).optional(),
+        }),
+    }),
+});
+// Intel TDX omits these arrays for unsigned/debug images; only probes may read absence as "none".
+export const probeAttestationClaims = observedAttestationClaims.extend({
+    submods: observedAttestationClaims.shape.submods.extend({
+        confidential_space: observedAttestationClaims.shape.submods.shape.confidential_space.extend({
+            support_attributes: observedAttestationClaims.shape.submods.shape.confidential_space.shape.support_attributes.default([]),
+        }),
+        container: observedAttestationClaims.shape.submods.shape.container.extend({
+            image_signatures: observedAttestationClaims.shape.submods.shape.container.shape.image_signatures.default([]),
+        }),
+    }),
+});
+/**
+ * Local development claims. These cannot establish production identity; production uses native Google claims.
+ */
+export const attestationClaims = z.object({
+    iss: z.string().url(),
+    /** The relay image's digest. Must be one we published. */
+    imageDigest: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+    /** Hash of the relay's channel public key, so the token is bound to this connection. */
+    channelKeyHash: z.string().regex(/^[0-9a-f]{64}$/),
+    exp: z.number().int(),
+    iat: z.number().int(),
+}).passthrough();

package/dist/contract/cli-api-messages.js

@@ -2,4 +2,6 @@ export const cliApiMessages = Object.freeze({
     unreachable: "Can't reach Counterfact. Try again shortly.",
     invalid_response: "Counterfact returned an invalid response. Try again shortly.",
     request_failed: "The request could not be completed. Try again shortly.",
+    unauthorized: "Not signed in. Run counterfact-labs login.",
+    invalid_console_url: "COUNTERFACT_URL must be an HTTP or HTTPS address without credentials or query fields.",
 });

package/dist/contract/cli-refusals.js

@@ -1,17 +1,28 @@
 import { FOLDER_TOO_LARGE_MESSAGE } from "../analysis-core/errors.js";
+import { cliApiMessages } from "./cli-api-messages.js";
+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 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.";
-/** Shared public refusals keep mode admission and reservation errors consistent. */
+// The console separates over-limit costs from version or route mismatches, so each code gets its own recovery guidance.
+const analysisTooLarge = "This analysis is too large to run at once. Choose a smaller folder, such as one agent's folder.";
+export const localRefusals = {
+    outside_project: "Choose a folder inside this project, or start Claude Code or Codex in the folder you want to analyze.",
+    launch_folder_unavailable: START_FAILURE_MESSAGE,
+    folder_unavailable: START_FAILURE_MESSAGE,
+    repeat_too_soon: FINISH_FAILURE_MESSAGE,
+};
+/** Both console clients use the same public messages for server refusals. */
 export const cliRefusals = {
     folder_too_large: FOLDER_TOO_LARGE_MESSAGE,
     low_balance: "Your balance doesn't cover this analysis. Add credit at https://app.counterfactlabs.com/account?status=low_balance#balance",
     local_checks_paused: "Analyses are paused right now. Try again later.",
     cli_update_required: "Update Counterfact: run npm install -g @counterfact-labs/cli@latest.",
     release_unavailable: unsupportedVersion,
+    plan_over_limit: analysisTooLarge,
     invalid_plan: unsupportedVersion,
     invalid_body: "Counterfact couldn't read this request. Update Counterfact, then try again.",
     body_too_large: "This request is too large. The limit is 2 MB.",
@@ -22,3 +33,60 @@ export const cliRefusals = {
     stale_quote: START_FAILURE_MESSAGE,
 };
 export function refusalExitCode(code) { return code === "low_balance" ? 2 : 1; }
+export class CliRefusalError extends Error {
+    code;
+    constructor(code) {
+        super(Object.hasOwn(localRefusals, code) ? localRefusals[code] : cliRefusals[code]);
+        this.code = code;
+    }
+}
+const otherReasons = {
+    unavailable: "console_unavailable",
+    invalid_configuration: "invalid_configuration",
+    invalid_request: "invalid_request",
+    unauthorized: "unauthorized",
+    not_allowed: "not_allowed",
+    not_found: "not_found",
+    rate_limited: "rate_limited",
+    reservation_closed: "reservation_closed",
+    reservation_closing: "reservation_closing",
+    delivery_incomplete: "delivery_incomplete",
+    check_conflict: "check_conflict",
+    invalid_email: "invalid_email",
+    wrong_code: "wrong_code",
+    expired: "expired",
+    too_many_attempts: "too_many_attempts",
+    email_unavailable: "email_unavailable",
+    request_failed: "request_failed",
+};
+const messageReasons = {
+    [cliRefusals.release_unavailable]: "release_unavailable",
+    [cliApiMessages.invalid_response]: "invalid_response",
+    [emailSignInMessages.browser_sign_in_pending]: "browser_sign_in_pending",
+    [emailSignInMessages.cancelled]: "cancelled",
+};
+const reasonValues = [
+    ...Object.keys(cliRefusals),
+    ...Object.keys(localRefusals),
+    ...Object.values(otherReasons), ...Object.values(messageReasons),
+    "console_unreachable", "invalid_console_url", "relay_unreachable", "results_not_saved",
+];
+const ownedReasons = new Set(reasonValues);
+/** Only fixed reasons may cross the MCP boundary; diagnostics can contain customer data. */
+export function failureReason(error) {
+    if (!(error instanceof Error))
+        return "request_failed";
+    if (error instanceof CliRefusalError)
+        return error.code;
+    if ("reason" in error && typeof error.reason === "string" && ownedReasons.has(error.reason))
+        return error.reason;
+    const code = "code" in error ? error.code : undefined;
+    if (typeof code === "string") {
+        if (Object.hasOwn(cliRefusals, code))
+            return code;
+        if (Object.hasOwn(otherReasons, code))
+            return otherReasons[code];
+        return "request_failed";
+    }
+    return Object.hasOwn(messageReasons, error.message) ? messageReasons[error.message] : "request_failed";
+}

package/dist/contract/cli-version.js

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

package/dist/contract/console.js

@@ -1,10 +1,11 @@
 import { z } from "zod";
-import { fixDeltaSchema, fixFactsSchema } from "../analysis-core/data/finding-types.js";
+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 { canonicalUuidSchema as uuid, matchingFindingNumbers, numberedFindingsSchema } from "./findings.js";
+import { RESULT_CHECK_LIMITS, validIntakeText } from "../analysis-core/contracts/relay-analysis.js";
 export const id = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/);
-const uuid = z.uuid().transform(value => value.toLowerCase());
 const money = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
 const count = (max) => z.number().int().positive().max(max);
 // These data-only boundaries follow the SaaS local start, reservation and findings owners; see docs/provenance.md.
@@ -59,32 +60,35 @@ export const consoleStatusSchema = z.strictObject({
     settlement: z.enum(["unheld", "held", "charged", "released"]),
     reason: z.enum(["service_failure", "required_failure", "authorization_refused", "our_deadline_failure",
         "findings_saved", "required_delivered", "no_required_delivery"]).nullable(),
-    uploadState: z.enum(["saved", "missing"]), analysisId: uuid.optional(), findingIds: z.array(uuid).max(20_000).optional(),
+    uploadState: z.enum(["saved", "missing"]), analysisId: uuid.optional(), findingIds: z.array(uuid).max(RESULT_CHECK_LIMITS.findings).optional(),
+    findings: numberedFindingsSchema.optional(),
     quoteId: z.string().min(1).max(256).optional(), priceMicro: money.nullable(), providerBudgetMicro: money,
     expiresAt: z.iso.datetime(), absoluteExpiresAt: z.iso.datetime().nullable(),
     deadlineClassification: z.enum(["caller_timeout", "our_deadline_failure"]).nullable(),
 }).refine(value => value.uploadState === "saved"
     ? value.analysisId !== undefined && value.findingIds !== undefined
-    : value.analysisId === undefined && value.findingIds === undefined);
+    : value.analysisId === undefined && value.findingIds === undefined && value.findings === undefined)
+    .refine(matchingFindingNumbers);
 export const consoleReservationSchema = consoleStatusSchema.safeExtend({ reservationToken: z.string().min(1).max(256),
     quoteId: z.string().min(1).max(256) });
+/**
+ * One findingId per payload finding, in payload order; optional findings maps those ids to project sequences in any order.
+ * Console must send findings in intake replies and saved status (including seq in status) only when
+ * x-counterfact-cli-version is 0.2.5 or later: older CLIs use strict schemas and reject these fields after a paid save.
+ */
 export const consoleIntakeResultSchema = z.strictObject({
-    checkId: uuid, projectId: uuid, analysisId: uuid, findingIds: z.array(uuid).max(20_000),
+    checkId: uuid, projectId: uuid, analysisId: uuid, findingIds: z.array(uuid).max(RESULT_CHECK_LIMITS.findings),
+    findings: numberedFindingsSchema.optional(),
     settlement: z.enum(["unheld", "held", "charged", "released"]).optional(),
-});
+}).refine(matchingFindingNumbers);
 export const LOCAL_FINDINGS_BODY_LIMIT = 2 * 1024 * 1024;
-export const LOCAL_FINDINGS_QUOTE_LIMIT = 2000;
-export const LOCAL_FINDINGS_TEXT_LIMIT = 4096;
+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);
 }
-function validIntakeText(value) {
-    if (typeof value === "string")
-        return !value.includes(String.fromCharCode(0)) && !/[\uD800-\uDFFF]/u.test(value);
-    return value === null || typeof value !== "object" || Object.values(value).every(validIntakeText);
-}
 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({
@@ -100,7 +104,8 @@ 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();
-const finding = rawFindingSchema.extend({
+export const localFindingSchema = rawFindingSchema.extend({
+    audience: findingAudienceSchema.optional(),
     summary: z.string().nullable(),
     category: rawFindingSchema.shape.category.removeCatch(),
     question: rawFindingSchema.shape.question.removeCatch().nullable(),
@@ -114,10 +119,10 @@ const finding = rawFindingSchema.extend({
 const payload = z.strictObject({
     checkId: z.uuid(), projectId: z.uuid(), reservationId: uuid.optional(),
     agent: z.strictObject({
-        repository: text.max(4096), commit: z.string().regex(/^(?:[a-f\d]{40}|[a-f\d]{64})$/i),
+        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),
     }),
-    findings: z.array(finding), bundleVersion: text.max(128), relayVersion: text.max(128), counterfactLocalVersion: text.max(128),
+    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.
 export const localFindingsPayloadSchema = z.unknown().refine(value => {

package/dist/contract/email-sign-in-messages.js

@@ -1,5 +1,6 @@
 import { cliApiMessages } from "./cli-api-messages.js";
 const rateLimited = "Too many sign-in requests. Try again later.";
+// Holds the sentences both sign-in flows share, so browser expiry lives here too.
 export const emailSignInMessages = Object.freeze({
     invalid_email: "Enter a valid email address.",
     invalid_code: "Enter the code from your email.",
@@ -11,8 +12,11 @@ export const emailSignInMessages = Object.freeze({
         : `Too many sign-in requests. Try again in ${seconds} ${seconds === 1 ? "second" : "seconds"}.`,
     email_unavailable: "Email sign-in isn't available. Use browser sign-in instead.",
     browser_sign_in_pending: "A browser sign-in is still in progress. Finish it before starting email sign-in.",
+    browser_expired: "The sign-in code expired. Run counterfact-labs login to try again.",
     unreachable: cliApiMessages.unreachable,
     invalid_response: cliApiMessages.invalid_response,
     request_failed: cliApiMessages.request_failed,
     cancelled: "Sign-in was cancelled. Run counterfact-labs login to try again.",
+    mcp_expired: "The sign-in code expired. Call sign_in to try again.",
+    mcp_cancelled: "Sign-in was cancelled. Call sign_in to try again.",
 });

package/dist/contract/engine.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { ANALYSIS_PROTOCOL, analysisCapabilities } from "../analysis-core/contracts/relay-analysis.js";
+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_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._-]*$/);
+export const engineIdentity = z.strictObject({
+    abi: z.literal(ENGINE_ABI), protocol: z.literal(ANALYSIS_PROTOCOL), spawnerContract: z.literal(ENGINE_SPAWNER_CONTRACT),
+    engineVersion: version, coreVersion: version, logicCommit: z.string().regex(/^[0-9a-f]{40}$/),
+    programSha256: hash, closureSha256: hash,
+});
+export const engineKeyPolicy = z.strictObject({
+    wrappingKey: z.string().refine(value => { try {
+        kmsKeyName(value);
+        return true;
+    }
+    catch {
+        return false;
+    } }),
+    workloadPolicySha256: hash, hardware: workloadHardware,
+});
+export const enginePin = engineIdentity.extend({ artifactSha256: hash, keyPolicy: engineKeyPolicy }).strict();
+export const analysisRelease = z.strictObject({ engine: enginePin, wire: analysisCapabilities }).refine(value => value.wire.protocol === value.engine.protocol && value.wire.engineVersion === value.engine.engineVersion);
+export function matchEngineKeyPolicy(keyPolicy, release) {
+    const policy = engineKeyPolicy.parse(keyPolicy);
+    if (release.bundleKey !== undefined && policy.wrappingKey !== kmsKeyName(release.bundleKey) ||
+        release.workloadPolicySha256 !== undefined && policy.workloadPolicySha256 !== release.workloadPolicySha256 ||
+        release.workloadPolicy !== undefined && !release.workloadPolicy.hardwareModels.includes(policy.hardware))
+        throw new Error("Invalid engine key policy");
+}
+export function samePin(left, right) {
+    if (!left || !right)
+        return left === right;
+    return stableStringify(enginePin.parse(left)) === stableStringify(enginePin.parse(right));
+}
+/** Historical releases carry no engine. New analysis evidence must be complete and agree at every boundary. */
+export function matchAnalysisRelease(value, pin, bundleVersion) {
+    const parsed = analysisRelease.parse(value);
+    if (!samePin(parsed.engine, pin) || parsed.wire.bundleVersion !== bundleVersion)
+        throw new Error("Analysis release differs");
+}

package/dist/contract/findings.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export const findingSequenceSchema = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+export const canonicalUuidSchema = z.uuid().transform(value => value.toLowerCase());
+export const numberedFindingSchema = z.strictObject({
+    id: canonicalUuidSchema, seq: findingSequenceSchema,
+});
+export const numberedFindingsSchema = z.array(numberedFindingSchema).max(20_000)
+    .refine(values => new Set(values.map(value => value.id)).size === values.length
+    && new Set(values.map(value => value.seq)).size === values.length);
+/** Both intake and recovery status must refer only to their committed finding ids. */
+export function matchingFindingNumbers(value) {
+    if (value.findings === undefined)
+        return true;
+    const ids = new Set(value.findingIds);
+    return value.findings.every(finding => ids.has(finding.id));
+}
+/**
+ * Console route to implement: GET /api/cli/projects/{projectId}/findings/{seq}.
+ * Requires the signed-in bearer token and project access; no body and no charge.
+ * Params: { projectId: UUID, seq: positive decimal integer }. 200: { id: UUID, seq: number }.
+ * 404 means that finding does not exist in this project. The caller then loads
+ * the explanation from the existing GET /api/cli/findings/{id} route, whose
+ * response may add seq: number. Numbers are never resolved across projects.
+ */
+export const findingNumberParamsSchema = z.strictObject({
+    projectId: canonicalUuidSchema, seq: z.string().regex(/^[1-9][0-9]*$/).transform(Number).pipe(findingSequenceSchema),
+});
+export const findingNumberResponseSchema = numberedFindingSchema;

package/dist/contract/fix-requests.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { canonicalUuidSchema, findingSequenceSchema } from "./findings.js";
+/**
+ * Console routes to implement; both require the signed-in CLI bearer token.
+ * GET /api/cli/fix-requests has no body and returns 200 with a JSON array:
+ * [{ findingId: UUID, seq: positive integer, title: string, projectId: UUID,
+ *    requestedAt: ISO-8601 UTC timestamp, repoKey?: string }]. Empty is [].
+ * repoKey is the finding's console repository key, including its scoped folder
+ * when present (for example fictional/support/agents/fern or local:fern).
+ * Older consoles may omit it. Only this user's
+ * unclaimed requests for accessible findings are returned. No charge or writes.
+ *
+ * POST /api/cli/fix-requests/{id}/claim takes JSON {} and returns 200 with
+ * { findingId: UUID, claimed: true }. The path id is the findingId from the list;
+ * there is one waiting request per user and finding, so no separate request id.
+ * Claiming is idempotent for that user, removes it from their waiting list and
+ * never starts analysis, applies edits or charges. Re-requesting a finding makes
+ * it waiting again. A missing or inaccessible request returns 404; unauthenticated
+ * requests return 401. The console owns authorization and atomic claiming.
+ */
+export const waitingFixSchema = z.object({
+    findingId: canonicalUuidSchema, seq: findingSequenceSchema, title: z.string().min(1).max(4096),
+    projectId: canonicalUuidSchema, requestedAt: z.iso.datetime(),
+    repoKey: z.string().min(1).max(4096).refine(value => value.trim().length > 0 && !/[\r\n\u2028\u2029]/.test(value)).optional(),
+});
+export const waitingFixesResponseSchema = z.array(waitingFixSchema).max(20_000)
+    .refine(values => new Set(values.map(value => value.findingId)).size === values.length);
+export const claimFixRequestParamsSchema = z.strictObject({ id: canonicalUuidSchema });
+export const claimFixRequestBodySchema = z.strictObject({});
+export const claimFixRequestResponseSchema = z.strictObject({ findingId: canonicalUuidSchema, claimed: z.literal(true) });