@counterfact-labs/cli 0.2.3 → 0.2.5

package/dist/cli/commands/analyze.js

@@ -1,3 +1,4 @@
+import { loadDevelopmentRelay } from "../development-relay.js";
 import { loadInstalledRelease } from "../../adapters/release.js";
 import { cliRefusals, START_FAILURE_MESSAGE } from "../../contract/cli-refusals.js";
 import { CLI_VERSION } from "../../contract/cli-version.js";
@@ -5,6 +6,11 @@ import { cliApiMessages } from "../../contract/cli-api-messages.js";
 import { ApiError } from "../api.js";
 import { resolveAgentFolder } from "../agent-folder.js";
 import { runRelayCheck } from "../relay-check.js";
+import { GITIGNORE_OUTPUT_NOTICE } from "../../adapters/gitignore-output.js";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { loadAgentProposal } from "../../contract/agent-proposal.js";
+import { formatSavedFindings } from "../finding-display.js";
 // Only a real pause says "paused"; an unreviewed release or an upload-only server cannot start.
 const unavailable = START_FAILURE_MESSAGE;
 function requireLocal(value) {
@@ -25,10 +31,30 @@ function requireLocal(value) {
     if (value.mode !== "local")
         throw new ApiError(503, "unavailable", unavailable);
 }
-export async function analyze(path, _options, ctx) {
+export function parseAnalyzeOptions(args) {
+    let path, proposalFile;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--proposal" && proposalFile === undefined) {
+            const value = args[++index];
+            if (!value || value.startsWith("-"))
+                throw new Error();
+            proposalFile = value;
+        }
+        else if (!arg.startsWith("-") && path === undefined)
+            path = arg;
+        else
+            throw new Error();
+    }
+    return { path: path ?? ".", options: proposalFile === undefined ? {} : { proposalFile } };
+}
+export async function analyze(path, options, ctx) {
     const startup = ctx.startup;
+    const proposal = await loadAgentProposal(async () => options.proposalFile === undefined ? options.proposal
+        : JSON.parse(await readFile(resolve(ctx.cwd ?? process.cwd(), options.proposalFile), "utf8")), startup.settings);
     requireLocal(await ctx.api.request("checks/mode"));
-    const release = ctx.relayRuntime?.release ?? await loadInstalledRelease();
+    const development = startup.transport.CF_RELAY_DEV === "1" ? await loadDevelopmentRelay(startup.transport) : undefined;
+    const release = development?.release ?? ctx.relayRuntime?.release ?? await loadInstalledRelease();
     if (release.projectContext !== "checks")
         throw new Error(unavailable);
     const token = await ctx.token?.();
@@ -48,19 +74,27 @@ export async function analyze(path, _options, ctx) {
     } };
     try {
         return await (ctx.relayRuntime?.run ?? runRelayCheck)(folder, {
-            settings: startup.settings, config, release, connect: ctx.relayRuntime?.connect,
+            settings: startup.settings, config, release, cwd: ctx.cwd, connect: development?.connect ?? ctx.relayRuntime?.connect,
+            ...(proposal ? { proposal } : {}),
             signal: ctx.signal ? AbortSignal.any([controller.signal, ctx.signal]) : controller.signal,
             stdout() { }, stderr() { },
             onStart: () => { ctx.onCheckStart?.(); ctx.write("\r\u001b[2KAnalyzing the agent…"); progressShown = true; },
+            onLocalSaved: result => {
+                if (result.ignoreAdded) {
+                    clearProgress();
+                    ctx.write(GITIGNORE_OUTPUT_NOTICE);
+                }
+            },
             onError: failure => {
+                if (failure.agentChoice)
+                    ctx.onAgentChoice?.(failure.agentChoice);
                 clearProgress();
                 ctx.write(`${failure.message}\n`);
             },
             onSaved: result => {
                 clearProgress();
                 ctx.onCheckComplete?.(result);
-                if (result.findingIds?.length)
-                    ctx.write(`Finding ids: ${result.findingIds.join(", ")}\n`);
+                ctx.write(formatSavedFindings(result, { numbersEnabled: ctx.findingNumbers, audienceEnabled: result.audienceEnabled }));
                 ctx.write(`Full results: ${result.url}\n`);
             },
         });

package/dist/cli/commands/finding.js

@@ -1,6 +1,12 @@
-export async function finding(id, ctx) {
-    const value = await ctx.api.request(`findings/${encodeURIComponent(id)}`);
-    ctx.write(`${value.title}\n${value.explanation}\n`);
+import { loadFinding } from "../finding-lookup.js";
+import { formatFindingNumber } from "../finding-display.js";
+import { findingSequenceSchema } from "../../contract/findings.js";
+export async function finding(id, ctx, options = {}) {
+    const value = await loadFinding(id, ctx.api, options.projectId, options.numbers ?? false);
+    const showNumber = ctx.findingNumbers !== false && findingSequenceSchema.safeParse(value.seq).success;
+    options.onLoaded?.(value);
+    const number = showNumber ? `${formatFindingNumber(value.seq)} ` : "";
+    ctx.write(`${number}${value.title}\n${value.explanation}\n`);
     for (const quote of value.quotes) {
         ctx.write(`\n${quote.path}${quote.line === null ? "" : `:${quote.line}`}\n`);
         if (quote.text !== null)

package/dist/cli/context.js

@@ -6,15 +6,18 @@ import { openBrowser } from "./browser.js";
 import { readCredentials } from "./credentials.js";
 import { userEmail } from "./git.js";
 import { terminalSignInInput } from "./sign-in-input.js";
+import { readFindingSettings } from "./finding-settings.js";
 export function commandContext(options = {}) {
     const startup = readCliSettings(options.env, options.emailSignIn);
     const homeDir = options.homeDir ?? homedir();
     const baseUrl = (options.baseUrl ?? startup.baseUrl ?? DEFAULT_URL).replace(/\/+$/, "");
     const api = new ApiClient(baseUrl, () => readCredentials(homeDir, api.baseUrl), undefined, options.signal);
     const write = options.write ?? (text => { process.stdout.write(text); });
+    const findingSettings = options.findingSettings ?? readFindingSettings(options.env);
     return {
+        findingNumbers: findingSettings.numbersEnabled,
         startup, signal: options.signal, relayRuntime: options.relayRuntime, cwd: options.cwd ?? process.cwd(),
-        token: () => readCredentials(homeDir, api.baseUrl), onCheckComplete: options.onCheckComplete, onCheckStart: options.onCheckStart,
+        token: () => readCredentials(homeDir, api.baseUrl), onCheckComplete: options.onCheckComplete, onCheckStart: options.onCheckStart, onAgentChoice: options.onAgentChoice,
         api, homeDir, write, openBrowser: options.openBrowser ?? openBrowser,
         signInInput: options.signInInput ?? terminalSignInInput(), readEmail: options.readEmail ?? userEmail,
         sleep: options.sleep ?? (async (ms) => { await delay(ms, undefined, { signal: options.signal }); }), now: options.now ?? Date.now,

package/dist/cli/development-relay.js

@@ -0,0 +1,34 @@
+import { createPublicKey } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { cliRefusals } from "../contract/cli-refusals.js";
+import { z } from "zod";
+import { loadDevelopmentRelease } from "../adapters/release.js";
+import { attestationPolicy } from "../gatekeeper/attestation.js";
+import { connectRelay } from "../gatekeeper/connection.js";
+const developmentTrust = z.object({
+    imageDigests: z.array(z.string().regex(/^sha256:[a-f0-9]{64}$/)).min(1),
+    developmentIssuer: z.object({ issuer: z.string().url(), keys: z.array(z.object({
+            kid: z.string().min(1), publicKey: z.string().min(1),
+        }).strict()).min(1) }).strict(),
+}).strict();
+/** Development paths are explicit and never replace the installed production pins. */
+export async function loadDevelopmentRelay(config) {
+    try {
+        if (config.CF_RELAY_DEV !== "1" || !config.CF_RELAY_DEV_TRUST || !config.CF_RELAY_DEV_BUNDLE || !config.CF_RELAY_DEV_RELEASE)
+            throw new Error();
+        const trust = developmentTrust.parse(JSON.parse(await readFile(config.CF_RELAY_DEV_TRUST, "utf8")));
+        const policy = attestationPolicy(config, { ...trust, developmentIssuer: { ...trust.developmentIssuer,
+                keys: trust.developmentIssuer.keys.map(({ kid, publicKey }) => {
+                    const key = createPublicKey(publicKey);
+                    if (key.asymmetricKeyType !== "ed25519")
+                        throw new Error();
+                    return { kid, publicKey: key };
+                }),
+            } });
+        const release = await loadDevelopmentRelease({ bundle: config.CF_RELAY_DEV_BUNDLE, metadata: config.CF_RELAY_DEV_RELEASE });
+        return { release, connect: (url) => connectRelay(url, { development: policy }) };
+    }
+    catch {
+        throw new Error(cliRefusals.release_unavailable);
+    }
+}

package/dist/cli/finding-display.js

@@ -0,0 +1,39 @@
+import { groupByAudience } from "../analysis-core/analysis/schemas.js";
+export const TEAM_WORKFLOW_HEADING = "Team workflow";
+export const formatFindingNumber = (seq) => `F-${seq}`;
+/** Intake returns one id per payload finding in order; the optional number mapping is joined by id. */
+export function savedFindings(result, report) {
+    const numbers = new Map(result.findings?.map(value => [value.id, value]));
+    return result.findingIds.map((id, index) => {
+        const numbered = numbers.get(id), local = report[index];
+        return { id, ...(numbered ? { seq: numbered.seq, number: formatFindingNumber(numbered.seq) } : {}),
+            title: local?.title ?? "", ...(local?.audience === undefined ? {} : { audience: local.audience }) };
+    });
+}
+function findingLine(value, enabled, index, labels, audienceEnabled) {
+    // The off switch preserves the original Markdown summary, including whitespace.
+    if (labels === "position" && !audienceEnabled)
+        return `${index + 1}. ${value.title}`;
+    const title = value.title.replace(/[\r\n\u2028\u2029]+/g, " ");
+    const label = labels === "position" ? `${index + 1}.` : enabled && value.seq !== undefined ? formatFindingNumber(value.seq) : value.id ?? `${index + 1}.`;
+    return `${label}${title ? ` ${title}` : ""}`;
+}
+export function findingDisplayRows(findings, { numbersEnabled = true, audienceEnabled, labels }) {
+    const groups = audienceEnabled ? groupByAudience(findings) : { users: findings, team: [] };
+    return [...groups.users, ...groups.team].map((finding, index) => ({ finding,
+        label: findingLine(finding, numbersEnabled, index, labels, audienceEnabled), startsTeamGroup: groups.team.length > 0 && index === groups.users.length }));
+}
+export function formatSavedFindings(result, options) {
+    if (options.numbersEnabled !== false && result.findings?.some(value => value.seq !== undefined)) {
+        return "Findings:\n" + findingDisplayRows(result.findings, { ...options, labels: "reference" }).map(row => `${row.startsTeamGroup ? `${TEAM_WORKFLOW_HEADING}:\n` : ""}${row.label}\n`).join("");
+    }
+    return result.findingIds?.length ? `Finding ids: ${result.findingIds.join(", ")}\n` : "";
+}
+export function formatWaitingFixes(items, enabled, needsProject) {
+    if (!items.length)
+        return "No waiting fixes.";
+    return "Waiting fixes:\n" + findingDisplayRows(items.map(item => ({ ...item, id: item.findingId })), { numbersEnabled: enabled, audienceEnabled: false, labels: "reference" }).map(({ finding: item, label }) => {
+        const scope = [item.repoKey, ...(enabled && needsProject(item) ? [`project ${item.projectId}`] : [])].filter(Boolean);
+        return `${label}${scope.length ? ` (${scope.join("; ")})` : ""}\n`;
+    }).join("");
+}

package/dist/cli/finding-lookup.js

@@ -0,0 +1,92 @@
+import { canonicalUuidSchema, findingNumberParamsSchema, findingNumberResponseSchema, findingSequenceSchema } from "../contract/findings.js";
+import { cliApiMessages } from "../contract/cli-api-messages.js";
+export const FINDING_PROJECT_MESSAGE = "Give the project for this finding number, which analysis results and the waiting_fixes tool list.";
+export const numberedFindingInputSchema = { type: "object", properties: {
+        id: { type: "string", description: "A finding id, or a number such as F-10." },
+        projectId: { type: "string", description: "The project the finding number belongs to, needed unless this session knows only one project." },
+    }, required: ["id"], additionalProperties: false };
+export function findingNumber(value) {
+    const match = /^F-?([1-9][0-9]*)$/i.exec(value.trim());
+    const seq = match ? Number(match[1]) : undefined;
+    return seq !== undefined && Number.isSafeInteger(seq) ? seq : undefined;
+}
+export class FindingReferences {
+    projects = new Set();
+    analysedProjects = new Set();
+    remember(projectId, source = "analysis") {
+        const canonical = projectId.toLowerCase();
+        this.projects.add(canonical);
+        if (source === "analysis")
+            this.analysedProjects.add(canonical);
+    }
+    // Observed findings cannot prove another project lacks the same historical number.
+    project() { return this.projects.size === 1 ? [...this.projects][0] : undefined; }
+    async resolve(reference, projectId, readWaiting) {
+        const seq = findingNumber(reference);
+        if (projectId || seq === undefined)
+            return projectId;
+        let waiting = [];
+        try {
+            waiting = await readWaiting?.() ?? [];
+        }
+        catch { /* A known project can still resolve a finding when the queue is unavailable. */ }
+        return this.resolveNumber(this.waitingByNumber(waiting).get(seq) ?? []);
+    }
+    projectsNeeded(waiting) {
+        const needed = new Set();
+        for (const matches of this.waitingByNumber(waiting).values()) {
+            const project = this.resolveNumber(matches);
+            for (const item of matches)
+                if (project !== item.projectId.toLowerCase())
+                    needed.add(item.findingId);
+        }
+        return needed;
+    }
+    waitingByNumber(waiting) {
+        const numbers = new Map();
+        for (const item of waiting) {
+            this.remember(item.projectId, "waiting");
+            const matches = numbers.get(item.seq);
+            if (matches)
+                matches.push(item);
+            else
+                numbers.set(item.seq, [item]);
+        }
+        return numbers;
+    }
+    resolveNumber(matches) {
+        if (!matches.length && this.analysedProjects.size === 1)
+            return [...this.analysedProjects][0];
+        if (matches.length !== 1)
+            return this.project();
+        const candidate = matches[0].projectId.toLowerCase();
+        // A queued fix may be older than the project the user just analysed.
+        if (this.analysedProjects.size > 0 && (this.analysedProjects.size !== 1 || !this.analysedProjects.has(candidate)))
+            return undefined;
+        return candidate;
+    }
+}
+export async function loadFinding(reference, api, projectId, numbered = true) {
+    const seq = numbered ? findingNumber(reference) : undefined;
+    let id = reference;
+    if (seq !== undefined) {
+        if (!projectId)
+            throw new Error(FINDING_PROJECT_MESSAGE);
+        const params = findingNumberParamsSchema.safeParse({ projectId, seq: String(seq) });
+        if (!params.success)
+            throw new Error(FINDING_PROJECT_MESSAGE);
+        const result = findingNumberResponseSchema.safeParse(await api.request(`projects/${params.data.projectId}/findings/${params.data.seq}`));
+        if (!result.success || result.data.seq !== seq)
+            throw new Error(cliApiMessages.invalid_response);
+        id = result.data.id;
+    }
+    const value = await api.request(`findings/${encodeURIComponent(id)}`);
+    const canonicalId = canonicalUuidSchema.safeParse(value.id);
+    if (seq !== undefined && (!canonicalId.success || canonicalId.data !== id || value.seq !== undefined && value.seq !== seq)) {
+        throw new Error(cliApiMessages.invalid_response);
+    }
+    if (seq !== undefined)
+        return { ...value, id, seq };
+    const { seq: detailSeq, ...detail } = value;
+    return numbered && detailSeq !== undefined && !findingSequenceSchema.safeParse(detailSeq).success ? detail : value;
+}

package/dist/cli/finding-settings.js

@@ -0,0 +1,5 @@
+import { findingAudienceEnabled } from "../analysis-core/analysis/finding-audience-switch.js";
+export function readFindingSettings(env = process.env, bundle) {
+    return { numbersEnabled: env.CF_FINDING_NUMBERS !== "0", fixesEnabled: env.CF_WAITING_FIXES !== "0",
+        audienceEnabled: findingAudienceEnabled(env, bundle) };
+}

package/dist/cli/fix-requests.js

@@ -0,0 +1,42 @@
+import { waitingFixesResponseSchema, claimFixRequestParamsSchema, claimFixRequestResponseSchema } from "../contract/fix-requests.js";
+import { cliApiMessages } from "../contract/cli-api-messages.js";
+import { ApiError } from "./api.js";
+export const FIX_DISCOVERY_TIMEOUT_MS = 2_000;
+export const fixRequestTools = [
+    { name: "waiting_fixes", description: "Lists the fixes you asked for in the console that are still waiting. It is read-only and free.",
+        annotations: { readOnlyHint: true },
+        inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+    { name: "claim_fix", description: "Marks a waiting fix as taken when you start it, without editing files or running an analysis.",
+        inputSchema: { type: "object", properties: { id: { type: "string", description: "The findingId returned by waiting_fixes." } }, required: ["id"], additionalProperties: false } },
+];
+export async function waitingFixes(api, options = {}) {
+    try {
+        const result = waitingFixesResponseSchema.safeParse(await api.request("fix-requests", undefined, true, options));
+        if (!result.success)
+            throw new Error(cliApiMessages.invalid_response);
+        return result.data;
+    }
+    catch (error) {
+        // An older console has no queue; read-only discovery still works during rollout.
+        if (error instanceof ApiError && error.status === 404)
+            return [];
+        throw error;
+    }
+}
+export async function waitingFixCount(api) {
+    try {
+        return (await waitingFixes(api, { timeoutMs: FIX_DISCOVERY_TIMEOUT_MS })).length;
+    }
+    catch {
+        return 0;
+    }
+}
+export async function claimFix(api, id) {
+    const params = claimFixRequestParamsSchema.safeParse({ id });
+    if (!params.success)
+        throw new Error("Provide a finding id.");
+    const result = claimFixRequestResponseSchema.safeParse(await api.request(`fix-requests/${params.data.id}/claim`, {}));
+    if (!result.success || result.data.findingId !== params.data.id)
+        throw new Error(cliApiMessages.invalid_response);
+    return result.data;
+}

package/dist/cli/intake-payload.js

@@ -1,18 +1,26 @@
+import { resultSafetyCheckEnabled } from "../analysis-core/settings.js";
 import { localFindingsPayloadSchema } from "../contract/console.js";
+import { projectPublicFinding } from "../contract/public-report.js";
+import { checkIntakeFindings } from "./result-check.js";
 import { RESULTS_TOO_LARGE_MESSAGE } from "../contract/cli-refusals.js";
-export function buildIntakePayload(identity, agent, report) {
+export function buildIntakePayload(identity, agent, report, options = {}) {
     const repo = (key) => key === null || key === report.repoKey ? agent.repository : key;
-    const findings = report.findings.map(finding => {
-        // The local report may add presentation fields; the intake accepts cleaned evidence only.
-        const { kind, severity, title, cause, summary, category, question, site, excerpt, otherSites, fixes, sourceNotes } = finding;
-        return { kind, severity, title, cause, summary, category, question, site, excerpt,
-            fixes: fixes.map(({ title, approach, kind, targetFiles, expectedOutcome, summary, impact, confidence, objective, status, blockedBy, alsoFixes, delta }) => ({ title, approach, kind, targetFiles, expectedOutcome, summary, impact, confidence, objective, status, blockedBy, alsoFixes, delta })),
-            siteRepo: repo(finding.siteRepo), otherSites: otherSites.map(site => ({ ...site, repo: repo(site.repo) })),
-            ...(sourceNotes === undefined ? {} : { sourceNotes: sourceNotes && { ...sourceNotes,
-                    counterEvidence: sourceNotes.counterEvidence.map(site => ({ ...site, repo: repo(site.repo) })) } }) };
-    });
+    let findings = report.findings.map(finding => projectPublicFinding(finding, repo));
+    let resultCheck = null;
+    let findingIndexes = report.findings.map((_, index) => index);
+    if (resultSafetyCheckEnabled(options.settings ?? {})) {
+        const captured = options.files;
+        if (!captured)
+            throw new Error("Result check requires a captured file snapshot");
+        const admitted = Object.fromEntries(agent.files.filter(file => Object.hasOwn(captured, file.path))
+            .map(file => [file.path, captured[file.path]]));
+        const { findings: accepted, acceptedIndexes, ...counts } = checkIntakeFindings(findings, { repoKey: agent.repository, files: admitted });
+        findings = accepted;
+        resultCheck = counts;
+        findingIndexes = acceptedIndexes;
+    }
     const result = localFindingsPayloadSchema.safeParse({ ...identity, agent, findings });
     if (!result.success)
         throw new Error(RESULTS_TOO_LARGE_MESSAGE);
-    return result.data;
+    return { payload: result.data, resultCheck, findingIndexes };
 }

package/dist/cli/main.js

@@ -4,13 +4,13 @@ import { realpath } from "node:fs/promises";
 import { errorCode, errorText } from "./api.js";
 import { readEmailSignIn } from "../adapters/settings.js";
 import { commandContext } from "./context.js";
-import { analyze } from "./commands/analyze.js";
+import { analyze, parseAnalyzeOptions } from "./commands/analyze.js";
 import { finding } from "./commands/finding.js";
 import { balance } from "./commands/balance.js";
 import { login, parseLoginOptions } from "./commands/login.js";
 import { logout } from "./commands/logout.js";
 import { serveMcp } from "./mcp.js";
-const usage = "Usage: counterfact-labs analyze [path]\n       counterfact-labs finding <id>\n       counterfact-labs balance | login | logout | mcp\n";
+const usage = "Usage: counterfact-labs analyze [path] [--proposal <json-file>]\n       counterfact-labs finding <id>\n       counterfact-labs balance | login | logout | mcp\n";
 export async function run(args, options = {}) {
     const write = options.write ?? (text => { process.stdout.write(text); });
     const emailSignIn = options.emailSignIn ?? readEmailSignIn(options.env);
@@ -22,9 +22,14 @@ export async function run(args, options = {}) {
             return 0;
         }
         if (command === "analyze") {
-            if (rest.length > 1 || rest.some(arg => arg.startsWith("-")))
+            let parsed;
+            try {
+                parsed = parseAnalyzeOptions(rest);
+            }
+            catch {
                 throw new Error(usage.trimEnd());
-            return await analyze(rest[0] ?? ".", {}, commandContext(commandOptions));
+            }
+            return await analyze(parsed.path, parsed.options, commandContext(commandOptions));
         }
         if (command === "finding" && rest.length === 1 && !rest[0].startsWith("-"))
             return await finding(rest[0], commandContext(commandOptions));

package/dist/cli/mcp.js

@@ -15,11 +15,16 @@ import { emailSignInMessages } from "../contract/email-sign-in-messages.js";
 import { EMAIL_SIGN_IN_TERMS, normalizeSignInEmail, validSignInCode, startEmailSignIn, signInWithCode } from "./email-sign-in.js";
 import { resolveAgentFolder, resolveMcpAgentFolder } from "./agent-folder.js";
 import { suggestedEmail } from "./suggested-email.js";
+import { agentProposalInputSchema } from "../contract/agent-proposal.js";
+import { fixRequestTools, waitingFixes, waitingFixCount, claimFix, FIX_DISCOVERY_TIMEOUT_MS } from "./fix-requests.js";
+import { FINDING_PROJECT_MESSAGE, FindingReferences, numberedFindingInputSchema } from "./finding-lookup.js";
+import { findingDisplayRows, formatFindingNumber, formatWaitingFixes } from "./finding-display.js";
+import { readFindingSettings } from "./finding-settings.js";
 const legacyTools = [
     {
         name: ANALYZE_TOOL_NAME,
         description: "Analyze the agent in a folder on this computer. Each call runs one analysis and charges the user's balance, so call it only when the user asks for an analysis. After edits, suggest an analysis and wait for the user to ask. Prices are listed on the top-up page and website. If the balance doesn't cover the analysis, show the returned message and top-up link.",
-        inputSchema: { type: "object", properties: { path: { type: "string", description: "The agent folder on this computer." } }, required: ["path"], additionalProperties: false },
+        inputSchema: { type: "object", properties: { path: { type: "string", description: "The agent folder on this computer." }, proposal: { ...agentProposalInputSchema, description: "Optional: the files you believe make up the agent, with each file's role. Paths are relative to the agent folder." } }, required: ["path"], additionalProperties: false },
     },
     { name: "get_finding", description: "Get a finding's explanation, quoted lines, and suggested fixes.", inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false } },
     { name: "get_balance", description: "Get the balance and top-up link.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
@@ -35,12 +40,16 @@ class ProtocolError extends Error {
 }
 function object(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
 export async function serveMcp(input, output, options = {}) {
+    const audienceChoice = (options.env ?? process.env).CF_FINDING_AUDIENCE;
     const cwd = options.cwd ?? process.cwd();
     const guarded = (options.env ?? process.env).CF_MCP_PATH_GUARD !== "0";
     const launch = guarded ? resolveFolderPath(cwd).catch(() => null) : Promise.resolve(cwd);
     const lastAnalysis = new Map();
+    const findingSettings = readFindingSettings(options.env);
+    const { numbersEnabled, fixesEnabled } = findingSettings;
+    const references = new FindingReferences();
     const emailSignIn = options.emailSignIn ?? readEmailSignIn(options.env);
-    const tools = emailSignIn ? [...legacyTools.slice(0, 3),
+    const signInTools = emailSignIn ? [...legacyTools.slice(0, 3),
         {
             name: "sign_in_status",
             description: "Check whether this computer is signed in to Counterfact and whether the user has allowed the analysis tool in Claude Code. Use path only to choose the agent folder for the local git email suggestion; otherwise use the launch folder. Analysis permission is always checked in the launch folder. A valid local git email is returned as suggestedEmail. Prefer the signed-in user's email already in your context; otherwise offer suggestedEmail. Ask the user to confirm an address before sending a code. With wait: true, wait only for browser sign-in to finish.",
@@ -65,6 +74,9 @@ export async function serveMcp(input, output, options = {}) {
                 }, required: ["email", "code"], additionalProperties: false },
         },
     ] : legacyTools;
+    const tools = signInTools.map(tool => tool.name === "get_finding" && numbersEnabled ? {
+        ...tool, inputSchema: numberedFindingInputSchema,
+    } : tool).concat(fixesEnabled ? fixRequestTools : []);
     let pendingSignIn;
     const requests = new Map();
     let queue = Promise.resolve();
@@ -76,15 +88,18 @@ export async function serveMcp(input, output, options = {}) {
         if (!object(args))
             throw new ProtocolError(-32602, "Tool arguments must be an object.");
         const name = params.name;
-        const allowed = name === ANALYZE_TOOL_NAME ? ["path"] : name === "get_finding" ? ["id"]
-            : name === "sign_in_status" ? (emailSignIn ? ["wait", "path"] : ["wait"])
-                : emailSignIn && name === "sign_in" ? ["email"] : emailSignIn && name === "sign_in_with_code" ? ["email", "code"] : [];
+        const allowed = name === ANALYZE_TOOL_NAME ? ["path", "proposal"] : name === "get_finding" ? (numbersEnabled ? Object.keys(numberedFindingInputSchema.properties) : ["id"])
+            : name === "claim_fix" ? ["id"]
+                : name === "sign_in_status" ? (emailSignIn ? ["wait", "path"] : ["wait"])
+                    : emailSignIn && name === "sign_in" ? ["email"] : emailSignIn && name === "sign_in_with_code" ? ["email", "code"] : [];
         if (!tools.some(tool => tool.name === name) || Object.keys(args).some(key => !allowed.includes(key)))
             throw new ProtocolError(-32602, "Unknown tool or argument.");
         if (name === ANALYZE_TOOL_NAME && (typeof args.path !== "string" || !args.path.trim()))
             throw new ProtocolError(-32602, "Provide a path.");
         if (name === "get_finding" && (typeof args.id !== "string" || !args.id.trim()))
             throw new ProtocolError(-32602, "Provide a finding id.");
+        if (name === "get_finding" && args.projectId !== undefined && (typeof args.projectId !== "string" || !args.projectId.trim()))
+            throw new ProtocolError(-32602, FINDING_PROJECT_MESSAGE);
         if (name === "sign_in_status" && args.wait !== undefined && typeof args.wait !== "boolean")
             throw new ProtocolError(-32602, "Provide an optional boolean wait.");
         if (name === "sign_in_status" && "path" in args && (typeof args.path !== "string" || !args.path.trim()))
@@ -96,12 +111,30 @@ export async function serveMcp(input, output, options = {}) {
         if (name === "sign_in_with_code" && !validSignInCode(args.code))
             throw new ProtocolError(-32602, emailSignInMessages.invalid_code);
         let text = "", exitCode = 0;
+        let agentChoice;
         let findingIds;
-        let url;
+        let findings, projectId;
+        let loadedFinding;
+        let fixRequests, claimed;
+        let waitingCount;
+        let url, analysisFolder;
+        let started = false;
         let signIn;
         try {
-            const ctx = commandContext({ ...options, emailSignIn, signal, onCheckComplete: result => {
+            const ctx = commandContext({ ...options, env: { ...(options.env ?? process.env), CF_FINDING_AUDIENCE: audienceChoice },
+                emailSignIn, findingSettings, signal, onCheckStart: () => {
+                    started = true;
+                    if (guarded && analysisFolder)
+                        lastAnalysis.set(analysisFolder, ctx.now());
+                    options.onCheckStart?.();
+                }, onAgentChoice: choice => { agentChoice = choice; options.onAgentChoice?.(choice); }, onCheckComplete: result => {
                     findingIds = result.findingIds ?? [];
+                    if (numbersEnabled) {
+                        findings = findingDisplayRows(result.findings ?? [], { numbersEnabled,
+                            audienceEnabled: result.audienceEnabled, labels: "reference" }).map(row => row.finding);
+                        projectId = result.projectId;
+                        references.remember(result.projectId);
+                    }
                     url = result.url;
                     options.onCheckComplete?.(result);
                 }, write: chunk => {
@@ -109,8 +142,23 @@ export async function serveMcp(input, output, options = {}) {
                     if (!chunk.startsWith("\r"))
                         text += chunk;
                 } });
-            if (name === "get_finding")
-                await finding(args.id, ctx);
+            if (name === "waiting_fixes") {
+                const waiting = await waitingFixes(ctx.api);
+                fixRequests = waiting;
+                const projectsNeeded = references.projectsNeeded(waiting);
+                text = formatWaitingFixes(waiting, numbersEnabled, item => projectsNeeded.has(item.findingId));
+            }
+            else if (name === "claim_fix") {
+                claimed = await claimFix(ctx.api, args.id);
+                text = "The fix request is marked as taken.";
+            }
+            else if (name === "get_finding") {
+                const project = numbersEnabled ? await references.resolve(args.id, args.projectId, fixesEnabled ? () => waitingFixes(ctx.api, { timeoutMs: FIX_DISCOVERY_TIMEOUT_MS }) : undefined) : undefined;
+                await finding(args.id, ctx, { projectId: project, numbers: numbersEnabled, onLoaded: value => {
+                        if (numbersEnabled)
+                            loadedFinding = { ...value, ...(value.seq !== undefined ? { number: formatFindingNumber(value.seq) } : {}) };
+                    } });
+            }
             else if (name === "get_balance")
                 await balance(ctx);
             else if (name === "sign_in_status") {
@@ -129,6 +177,8 @@ export async function serveMcp(input, output, options = {}) {
                     }
                 }
                 signIn = { ...await signInStatus(ctx), analyzeToolAllowed: allowed };
+                if (fixesEnabled)
+                    waitingCount = signIn.signedIn ? await waitingFixCount(ctx.api) : 0;
                 text = signIn.signedIn ? "Signed in." : "Not signed in.";
                 if (emailSignIn) {
                     const suggestion = await suggestedEmail(resolveAgentFolder(args.path ?? ".", cwd), ctx.readEmail);
@@ -162,7 +212,7 @@ export async function serveMcp(input, output, options = {}) {
                         signal.addEventListener("abort", cancel, { once: true });
                         try {
                             signal.throwIfAborted();
-                            const flow = await startSignIn(commandContext({ ...options, emailSignIn, homeDir: ctx.homeDir, baseUrl: ctx.api.baseUrl, signal: controller.signal }));
+                            const flow = await startSignIn(commandContext({ ...options, emailSignIn, findingSettings, homeDir: ctx.homeDir, baseUrl: ctx.api.baseUrl, signal: controller.signal }));
                             pending = { flow, controller, opened: false };
                             pendingSignIn = pending;
                             const current = pending;
@@ -190,14 +240,9 @@ export async function serveMcp(input, output, options = {}) {
                 if (guarded && last !== undefined && ctx.now() - last < 10 * 60 * 1000) {
                     throw new Error(FINISH_FAILURE_MESSAGE);
                 }
-                let started = false;
+                analysisFolder = folder;
                 try {
-                    exitCode = await analyze(folder, {}, { ...ctx, onCheckStart: () => {
-                            started = true;
-                            if (guarded)
-                                lastAnalysis.set(folder, ctx.now());
-                            ctx.onCheckStart?.();
-                        } });
+                    exitCode = await analyze(folder, { proposal: args.proposal }, ctx);
                 }
                 finally {
                     if (guarded && started)
@@ -212,7 +257,9 @@ export async function serveMcp(input, output, options = {}) {
         // Some clients (Claude Code among them) give the model only the structured result when one is present, so it
         // repeats the text: without it the model cannot read the result.
         return { content: [{ type: "text", text }], isError: exitCode !== 0,
-            structuredContent: { text, exitCode, ...(findingIds ? { findingIds } : {}), ...(url ? { url } : {}), ...signIn } };
+            structuredContent: { text, exitCode, ...agentChoice, ...(findingIds ? { findingIds } : {}), ...(url ? { url } : {}), ...signIn,
+                ...(findings ? { findings, projectId } : {}), ...(loadedFinding ? { finding: loadedFinding } : {}),
+                ...(fixRequests ? { fixRequests } : {}), ...claimed, ...(waitingCount !== undefined ? { waitingFixes: waitingCount } : {}) } };
     }
     async function respond(message, id, signal) {
         if (signal.aborted)