@counterfact-labs/cli 0.2.4 → 0.2.5

package/dist/cli/relay-preparation.js

@@ -1,30 +1,53 @@
 import { randomUUID } from "node:crypto";
+import { join, relative, sep } from "node:path";
 import { outsideLoadersEnabled } from "../analysis-core/settings.js";
+import { resolveFolderPath } from "../adapters/folder-path.js";
 import { readLocalFolder } from "../adapters/files.js";
-import { snapshotProvenance } from "../adapters/snapshot.js";
+import { snapshotProvenance, sameFileHashes } from "../adapters/snapshot.js";
 import { validateClientRelease } from "../adapters/release.js";
 import { prepareRelayPlan } from "../adapters/relay-plan.js";
+import { AgentChoiceError } from "../contract/agent-choice.js";
 import { COMMITTED_FILES_MESSAGE } from "../contract/cli-refusals.js";
+import { INVALID_PROPOSAL_MESSAGE } from "../contract/agent-proposal.js";
 import { repositoryFacts } from "./git.js";
 /** Absolute checkout paths stay local; repository facts own the start's commit. */
 export function buildRelayStartPayload(facts, files) {
     const { remoteUrl, relPath, folderName, branch, commit, dirty } = facts;
     return { execution: "local", remoteUrl, relPath, folderName, branch, commit, dirty, files };
 }
+export function committedFilesOnly(settings) {
+    return settings.CF_LOCAL_COMMITTED_ONLY === "1";
+}
 /** Recovery can reuse signature validation without reading the folder again. */
 export async function prepareRelayCheck(folder, options, validated = validateClientRelease(options.release, options.settings)) {
-    const { bundle, tools } = validated;
+    const { bundle, tools, settings } = validated;
     options.signal?.throwIfAborted();
     // Discovery must agree with Git before publishing repository-relative captures.
     const earlyFacts = outsideLoadersEnabled(options.settings) ? await (options.facts ?? repositoryFacts)(folder) : undefined;
     options.signal?.throwIfAborted();
     const read = await readLocalFolder(options.settings, folder, options.trialAdmission, { captureSnapshot: true,
+        proposal: options.proposal,
         ...(earlyFacts ? { expectedRepositoryRoot: earlyFacts.repoRoot ?? null } : {}) });
+    if (read.proposalCounts?.fromProposal === 0 && read.proposalCounts.rejected > 0)
+        throw new Error(INVALID_PROPOSAL_MESSAGE);
+    if (read.agentChoice) {
+        const cwd = await resolveFolderPath(options.cwd ?? process.cwd());
+        const launchPath = (path) => relative(cwd, join(read.sourceBase ?? folder, path)).split(sep).join("/") || ".";
+        throw new AgentChoiceError({ ...read.agentChoice,
+            candidates: read.agentChoice.candidates.map(candidate => ({
+                folder: launchPath(candidate.folder), reason: launchPath(candidate.reason),
+            })),
+        });
+    }
     const source = { ...read, files: Object.freeze({ ...read.files }) };
-    const provenance = await snapshotProvenance(source.sourceBase ?? folder, source.snapshot, source.sourceBase ? { selectionFolder: folder } : undefined);
-    if (options.expectedCommit !== undefined && provenance.commit !== options.expectedCommit)
+    const provenance = await snapshotProvenance(source.sourceBase ?? folder, source.snapshot, { selectionFolder: folder, committedOnly: committedFilesOnly(options.settings) });
+    if (options.expectedCommit === null) {
+        if (!sameFileHashes(options.expectedFiles ?? [], source.snapshot))
+            throw new Error(COMMITTED_FILES_MESSAGE);
+    }
+    else if (options.expectedCommit !== undefined && provenance.commit !== options.expectedCommit)
         throw new Error(COMMITTED_FILES_MESSAGE);
-    const { plan, files } = prepareRelayPlan({ bundle, tools, settings: options.settings, relayVersion: options.release.relayVersion, source });
+    const { plan, files } = prepareRelayPlan({ bundle, tools, settings, relayVersion: options.release.relayVersion, source });
     options.signal?.throwIfAborted();
     const facts = earlyFacts ?? await (options.facts ?? repositoryFacts)(folder);
     options.signal?.throwIfAborted();

package/dist/cli/result-check.js

@@ -0,0 +1,68 @@
+import { publicFinding, resultCheckFinding, RESULT_CHECK_LIMITS } from "../analysis-core/contracts/relay-analysis.js";
+import { findingSitesInOrder } from "../analysis-core/findings/sites.js";
+import { localFindingSchema } from "../contract/console.js";
+function evidenceQuotes(finding, repoKey) {
+    const primary = finding.site ? { repo: finding.siteRepo ?? repoKey, ...finding.site, excerpt: finding.excerpt } : null;
+    const sites = findingSitesInOrder(primary, finding.otherSites);
+    const quotes = [];
+    function add(site, text) {
+        if (typeof text === "string")
+            quotes.push({ repo: site.repo, path: site.path, text });
+    }
+    add(primary ?? {}, finding.excerpt);
+    finding.otherSites.forEach(site => add(site, site.excerpt));
+    for (const note of finding.sourceNotes?.sites ?? []) {
+        if (note.keyPhrase !== "")
+            add(sites[note.index] ?? {}, note.keyPhrase);
+    }
+    for (const site of finding.sourceNotes?.counterEvidence ?? [])
+        add(site, site.excerpt);
+    return quotes;
+}
+/** The intake boundary and offline measurement use exactly the same evidence decision. */
+export function checkIntakeFindings(findings, context, onInvalidQuote) {
+    const accepted = [], acceptedIndexes = [];
+    const originals = new Map();
+    function original(path) {
+        if (!originals.has(path)) {
+            const captured = context.files[path];
+            try {
+                originals.set(path, typeof captured === "string" ? captured : new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(captured));
+            }
+            catch {
+                originals.set(path, null);
+            }
+        }
+        return originals.get(path);
+    }
+    let quotes = 0, droppedQuotes = 0, invalidQuotes = 0, schemaDroppedFindings = 0, capDroppedFindings = 0;
+    findings.forEach((finding, index) => {
+        const parsed = publicFinding.safeParse(finding);
+        const evidence = parsed.success ? evidenceQuotes(parsed.data, context.repoKey) : [];
+        quotes += evidence.length;
+        const invalid = evidence.filter(quote => {
+            const source = quote.repo === context.repoKey && typeof quote.path === "string" && Object.hasOwn(context.files, quote.path)
+                ? original(quote.path) : null;
+            const invalid = !quote.text.length || source === null || !source.includes(quote.text);
+            if (invalid)
+                onInvalidQuote?.({ text: quote.text, source });
+            return invalid;
+        }).length;
+        invalidQuotes += invalid;
+        const schemaValid = parsed.success && resultCheckFinding.safeParse(parsed.data).success && localFindingSchema.safeParse(parsed.data).success;
+        if (!schemaValid)
+            schemaDroppedFindings++;
+        if (index >= RESULT_CHECK_LIMITS.findings)
+            capDroppedFindings++;
+        if (!schemaValid || !parsed.success || invalid || index >= RESULT_CHECK_LIMITS.findings) {
+            // Removing one supporting quote could change the claim or invalidate source-note indices.
+            droppedQuotes += evidence.length;
+        }
+        else {
+            accepted.push(parsed.data);
+            acceptedIndexes.push(index);
+        }
+    });
+    return { findings: accepted, acceptedIndexes, droppedFindings: findings.length - accepted.length, quotes, droppedQuotes, invalidQuotes,
+        schemaDroppedFindings, capDroppedFindings };
+}

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-refusals.js

@@ -5,6 +5,8 @@ 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.";
+// 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.";
 /** Shared public refusals keep mode admission and reservation errors consistent. */
 export const cliRefusals = {
     folder_too_large: FOLDER_TOO_LARGE_MESSAGE,
@@ -12,6 +14,7 @@ export const cliRefusals = {
     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.",

package/dist/contract/cli-version.js

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

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/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) });