OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
fix(cli): honor scan budgets across batch attempts and follow-ups (#2592)
Michael D'Angelo6b0d0a7ce12d
diff --git a/docs/project-configuration.md b/docs/project-configuration.mdindex edc61464b..c04333d9c 100644--- a/docs/project-configuration.md+++ b/docs/project-configuration.md@@ -335,7 +335,8 @@ aliases there are errors, while equivalent durations are accepted.`max_cost_usd_per_scan` has the same meaning as `--max-cost`: an estimated limit for onescan attempt. In-flight work may exceed it. It is not a total budget for a batch orfollow-up actions. `fail_on_severity` changes the exit status without filtering the-retained findings.+retained findings. A bounded scan cannot run `--patch` or `--validate`. Select a+finding from the saved scan to patch or validate separately.## Batch and component scans@@ -351,6 +352,12 @@ context, prompts, per-attempt cost and investigation limits, and severity policyas `scan`. The investigation allowance applies independently to each scan, notplanning, result matching, or total campaign time.+Use `--max-total-cost USD` for a whole invocation. It divides the estimate among+explicit components or pending repository attempts, including retries. A tighter+configured per-scan limit still applies. The total limit skips model-based matching+and owner suggestions, including when `scan.owner_suggestions` is enabled. See the [component scan](../sdk/typescript/docs/cli.md#scan-project-components)+and [bulk scan](../sdk/typescript/docs/cli.md#bulk-scans) guides for planning and recovery behavior.+A bulk CSV row's mode and scope override the file's defaults for that repository.Bulk checkouts are clean, shallow snapshots, so bulk scans accept repository orpath scopes. A configured diff or working-tree scope is rejected before workdiff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.mdindex d63838715..427a7c8f5 100644--- a/sdk/typescript/docs/cli.md+++ b/sdk/typescript/docs/cli.md@@ -881,9 +881,15 @@ failed matching return `2`; severity-policy violations return `1`. Retry withThe retry report covers only those components. Each registered component keeps itsscan ID in the summary, including when the scan fails.-`--max-cost` applies per component, excluding planning and matching. `--model`-and `--effort` also apply to matching; `--auth` applies throughout. Planning and-matching reject ambient command providers that conflict with explicit ChatGPT+`--max-cost` applies per component, excluding planning and matching.+Use `--max-total-cost USD` with explicit components to split one estimated+budget among them. The smaller of each component's share and its per-scan+limit applies. Findings stay separate because model-based matching is skipped.+The total limit also skips owner suggestions, including when enabled in project configuration.+Automatic planning and post-scan prompts must run separately.++`--model` and `--effort` also apply to matching. `--auth` applies throughout.+Planning and matching reject ambient command providers that conflict with explicit ChatGPTor API-key auth. SDK-selected command providers retain their authentication.From TypeScript, use `runComponentScans({ repository, outputDir, components })`.@@ -1373,6 +1379,15 @@ codex-security bulk-scan repositories.csv \--output-dir /path/outside/repositories/results --workers 4```+`--max-cost USD` applies per repository attempt. `--max-total-cost USD` divides an+estimated limit among the pending repositories and their possible attempts for+this invocation, including recovery. For example, a $12 limit with three pending+repositories and `--max-attempts 2` reserves up to $2 per attempt. An earlier+overrun reduces the remaining budget for queued attempts. In-flight work can+exceed a limit. The total limit skips model-based matching and owner suggestions,+including during recovery. Run post-scan prompts separately. A resumed scan also respects its saved+limit and includes prior recorded usage in its cost estimate.+Bulk scans use clean shallow checkouts and support repository/path scopes.CSV scopes are literal paths relative to each checkout, including names suchas `~/src`.@@ -2674,7 +2689,10 @@ This explicit option disables Codex filesystem/network enforcement for the patchtask. The container must provide it. There is no automatic fallback; optionalpatch-risk assessment still uses its read-only sandbox.-`scan --patch` runs after a complete scan. `--patch-severity` defaults to `low`;+`scan --patch` runs after a complete scan without a cost limit. A cost-limited+scan saves the findings and skips the interactive patch offer. Use+`codex-security patch --scan SCAN_ID` to patch separately.+`--patch-severity` defaults to `low`;`high` selects high and critical findings. Interactive users can select findingsand add instructions. The interactive finding browser lists critical, high,medium, then low findings, preserving scan order within each severity.diff --git a/sdk/typescript/scripts/package-dist-files.mjs b/sdk/typescript/scripts/package-dist-files.mjsindex 6dc154a36..0575ade4f 100644--- a/sdk/typescript/scripts/package-dist-files.mjs+++ b/sdk/typescript/scripts/package-dist-files.mjs@@ -1,5 +1,6 @@const distModules = ["api",+ "batch-cost","scan-executor","host-protocol","hosted-remediation",diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.tsindex 03023c252..fe9007ce5 100644--- a/sdk/typescript/src/api.ts+++ b/sdk/typescript/src/api.ts@@ -394,6 +394,8 @@ const scanLifecycleSchema = z.object({export type ScanLifecycle = Readonly<z.infer<typeof scanLifecycleSchema>>;export interface ScanOptions extends ScanSettings {+ /** @internal A bounded batch omits unmetered model calls after the scan. */+ skipFindingMatching?: boolean;/** Explicit policy for the initial scan and its workers. */severityRubric?: SeverityRubricSnapshot;/** Markdown policy file to capture when starting a new scan. */@@ -4041,11 +4043,9 @@ export class CodexSecurity {try {const runWorkbench = (args: readonly string[], input?: string) =>workbench(workbenchOptions, args, input);- const previousFindings = await listRepositoryFindings(- runWorkbench,- targetId,- "all",- );+ const previousFindings = options.skipFindingMatching+ ? undefined+ : await listRepositoryFindings(runWorkbench, targetId, "all");if (previousFindings !== undefined) {await matchCompletedScan({scanId,@@ -4068,6 +4068,8 @@ export class CodexSecurity {),...inferenceOptions,});+ }+ if (previousFindings !== undefined || options.skipFindingMatching) {result.repositoryFindings = (await listRepositoryFindings(runWorkbench,targetId,diff --git a/sdk/typescript/src/batch-cost.ts b/sdk/typescript/src/batch-cost.tsnew file mode 100644index 000000000..767c9e843--- /dev/null+++ b/sdk/typescript/src/batch-cost.ts@@ -0,0 +1,63 @@+import { ConfigurationError } from "./errors.js";+import type { ScanCost } from "./cost.js";+import type { ScanSettings } from "./scan-settings.js";++export function batchScanBudget(+ share: number | undefined,+ settings: Pick<+ ScanSettings,+ "maxCostUsd" | "postScanPrompt" | "postScanPromptFile"+ >,+): {+ maxCostUsd?: number;+ skipFindingMatching?: true;+ ownerSuggestions?: false;+} {+ if (share === undefined) return { maxCostUsd: settings.maxCostUsd };+ if (+ settings.postScanPrompt !== undefined ||+ settings.postScanPromptFile !== undefined+ )+ throw new ConfigurationError(+ "--max-total-cost cannot cover a post-scan prompt. Remove the post-scan prompt and run it separately.",+ );+ return {+ maxCostUsd: Math.min(share, settings.maxCostUsd ?? share),+ skipFindingMatching: true,+ ownerSuggestions: false,+ };+}++/** Reserve before dispatch, including in-flight attempts. Charge observed overruns to the remaining pool. */+export class BatchCostPool {+ #remaining: number;+ readonly share: number;++ constructor(totalUsd: number, slots: number) {+ this.#remaining = totalUsd;+ this.share = totalUsd / slots;+ if (!Number.isFinite(this.share) || this.share <= 0)+ throw new ConfigurationError(+ "The total cost limit must allow a positive USD amount per scan attempt.",+ );+ }++ reserve(share = this.share) {+ const maxCostUsd = Math.min(share, this.#remaining);+ if (maxCostUsd <= 0)+ throw new ConfigurationError(+ "The invocation cost limit is exhausted. No further scan attempts can start.",+ );+ this.#remaining -= maxCostUsd;+ let charged = maxCostUsd;+ return {+ maxCostUsd,+ record: (cost: Readonly<ScanCost> | null | undefined) => {+ if (cost && cost.estimatedUsd > charged) {+ this.#remaining -= cost.estimatedUsd - charged;+ charged = cost.estimatedUsd;+ }+ },+ };+ }+}diff --git a/sdk/typescript/src/cli-help.ts b/sdk/typescript/src/cli-help.tsindex d09ebffb2..e161c5bd3 100644--- a/sdk/typescript/src/cli-help.ts+++ b/sdk/typescript/src/cli-help.ts@@ -82,6 +82,7 @@ const VALUE_LABELS: Record<string, string> = {python: "path",codex: "key=value","max-cost": "usd",+ "max-total-cost": "usd","max-time": "minutes","max-time-hours": "hours","fail-on-severity": "level",diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex 17919e6dd..71d8aaab2 100644--- a/sdk/typescript/src/cli.ts+++ b/sdk/typescript/src/cli.ts@@ -228,6 +228,7 @@ import {type JsonValue,} from "./config.js";import { formatUsd, type ScanCost } from "./cost.js";+import { batchScanBudget } from "./batch-cost.js";import {formatScanCost,formatScanCostTokens,@@ -5497,7 +5498,9 @@ export async function main(patch: z.boolean().default(false)- .describe("Patch and verify confirmed findings after the scan."),+ .describe(+ "Patch and verify findings after a scan without a cost limit.",+ ),validate: z.boolean().default(false)@@ -6321,6 +6324,9 @@ export async function main(maxCost: ScanSettingsSchema.shape.maxCostUsd.describe("Stop each component scan if estimated USD cost exceeds AMOUNT.",),+ maxTotalCost: ScanSettingsSchema.shape.maxCostUsd.describe(+ "Divide estimated USD among explicit components for this invocation. Skips model-based finding matching and owner suggestions.",+ ),showCost: SHOW_COST_OPTION,...RUNTIME_OPTION_SCHEMAS,})@@ -6417,6 +6423,7 @@ export async function main(),mode: settings.mode,maxCostUsd: settings.maxCostUsd,+ maxTotalCostUsd: options.maxTotalCost,showCost: options.showCost,clock: dependencies,color: dependencies.environment["NO_COLOR"] === undefined,@@ -6437,6 +6444,7 @@ export async function main(outputDir: settings.outputDir,...(options.auto ? { auto: true } : { components }),planOnly: options.planOnly,+ maxTotalCostUsd: options.maxTotalCost,workers: options.workers,config,scanOptions: {@@ -6447,6 +6455,10 @@ export async function main(planComponents: dependencies.planComponents,matchFindings: dependencies.matchFindings,onPlan: (components) => {+ if (dashboard === null && options.maxTotalCost !== undefined)+ errorOutput.write(+ `codex-security: ${formatUsd(options.maxTotalCost)} total limit for this invocation. Model-based finding matching and owner suggestions are skipped.\n`,+ );for (const component of components)componentNames.set(component.id, component.name);dashboard?.setComponents(components);@@ -6461,7 +6473,9 @@ export async function main(const line = componentScanEventLine(componentName,event,- options.showCost || settings.maxCostUsd !== undefined,+ options.showCost ||+ settings.maxCostUsd !== undefined ||+ options.maxTotalCost !== undefined,settings.auth,);if (line !== null) errorOutput.write(line);@@ -6480,16 +6494,22 @@ export async function main(signal: controller.signal,onProgress: (component) => {if (dashboard !== null) dashboard.updateComponent(component);- else+ else {+ const budget =+ component.status === "started" &&+ component.maxCostUsd !== undefined+ ? ` (${formatUsd(component.maxCostUsd)} per component)`+ : "";errorOutput.write(- `codex-security: ${diagnosticValue(component.name)} ${component.status}${component.error === undefined ? "" : `: ${diagnosticValue(component.error)}`}\n`,+ `codex-security: ${diagnosticValue(component.name)} ${component.status}${budget}${component.error === undefined ? "" : `: ${diagnosticValue(component.error)}`}\n`,);+ }},onComplete: (result) => {dashboard?.finishComponents(result);stopDashboard();errorOutput.write(- `Component scans: ${result.completed} complete, ${result.failed} failed.\n${result.sourceFindingCount} findings → ${result.findingCount} groups${result.deduplication?.status === "failed" ? " (matching failed)" : ""}.\nReport: ${errorMessage(result.reportPath)}\n`,+ `Component scans: ${result.completed} complete, ${result.failed} failed.\n${result.sourceFindingCount} findings → ${result.findingCount} groups${result.deduplication?.status === "failed" ? " (matching failed)" : result.deduplication?.status === "skipped" ? " (matching skipped under total cost limit)" : ""}.\nReport: ${errorMessage(result.reportPath)}\n`,);if (result.retryPlanPath !== undefined)errorOutput.write(@@ -6578,6 +6598,9 @@ export async function main(maxCost: ScanSettingsSchema.shape.maxCostUsd.describe("Stop each repository attempt if estimated USD cost exceeds AMOUNT.",),+ maxTotalCost: ScanSettingsSchema.shape.maxCostUsd.describe(+ "Divide estimated USD among pending repository attempts, including retries, for this invocation. Skips model-based finding matching and owner suggestions.",+ ),...runtimeOptions(() => z.string().min(1)),}),usage: [@@ -6668,6 +6691,10 @@ export async function main().options,]),);+ if (options.maxTotalCost !== undefined)+ errorOutput.write(+ `codex-security: ${formatUsd(options.maxTotalCost)} total limit for this invocation. Model-based finding matching and owner suggestions are skipped.\n`,+ );const result = await runMultiscan({inputPath,outputDir,@@ -6675,6 +6702,7 @@ export async function main(workers: options.workers,mode: settings.mode,maxAttempts: options.maxAttempts,+ maxTotalCostUsd: options.maxTotalCost,...(settings.maxCostUsd === undefined? {}: { maxCostUsd: settings.maxCostUsd }),@@ -6716,6 +6744,7 @@ export async function main(signal: controller.signal,});return {+ alreadyCompleted: true,manifest: contract.manifest,findings: contract.findings,cost:@@ -6769,6 +6798,10 @@ export async function main(try {return await security.run(recipe.repository!, {...pickScanSettings(recipe),+ ...batchScanBudget(+ prompts.maxTotalCostShareUsd,+ recipe,+ ),knowledgeBaseSnapshot: prompts.knowledgeBaseSnapshot,telemetryContext: prompts.telemetryContext,onTelemetry: prompts.onTelemetry,@@ -6787,10 +6820,21 @@ export async function main(}: {}),signal: controller.signal,- onProgress: ({ repository, status, attempt, error, warning }) => {+ onProgress: ({+ repository,+ status,+ attempt,+ maxCostUsd,+ error,+ warning,+ }) => {const detail = error ?? warning;+ const budget =+ maxCostUsd === undefined+ ? ""+ : `, ${formatUsd(maxCostUsd)} per repository attempt`;errorOutput.write(- `codex-security: ${repository} ${status} (attempt ${attempt})${detail === undefined ? "" : `: ${diagnosticValue(detail)}`}\n`,+ `codex-security: ${repository} ${status} (attempt ${attempt}${budget})${detail === undefined ? "" : `: ${diagnosticValue(detail)}`}\n`,);},});@@ -11109,6 +11153,10 @@ async function executeScan(let usageFreshness: string | null = null;let accountLimits: string | null = null;let maxCostUsd = arguments_.maxCostUsd;+ if (maxCostUsd !== undefined && arguments_.patch)+ throw new CodexSecurityError(+ "--patch cannot be combined with a scan cost limit. Run the bounded scan first, then use `codex-security patch --scan SCAN_ID` separately.",+ );const showCost = arguments_.showCost === true || maxCostUsd !== undefined;let phase: string | null = null;const targetWarnings: string[] = [];@@ -12217,6 +12265,7 @@ async function executeScan(try {if (!arguments_.mock &&+ maxCostUsd === undefined &&actionableFindings.length > 0 &&arguments_.patchSeverity === undefined &&progress?.interactive === true &&diff --git a/sdk/typescript/src/component-scan.ts b/sdk/typescript/src/component-scan.tsindex ede16e84c..3dc042d23 100644--- a/sdk/typescript/src/component-scan.ts+++ b/sdk/typescript/src/component-scan.ts@@ -35,12 +35,13 @@ import type {} from "./cost.js";import type { ScanTokenUsage } from "./cost-model.js";import { readThreatModelPath } from "./artifact-export.js";-import { errorMessage } from "./errors.js";+import { errorMessage, ScanCostLimitExceededError } from "./errors.js";import type { Finding } from "./models.js";import type { ScanResult } from "./result.js";import type { ScanActivity } from "./scan-activity.js";import type { DeepScanProgress } from "./scan-progress.js";import type { ScanSettings } from "./scan-settings.js";+import { BatchCostPool, batchScanBudget } from "./batch-cost.js";import type { ScanProgress, ScanWorkerStatus } from "./worker-progress.js";import {matchScanFindingsInternal,@@ -58,6 +59,7 @@ export interface ComponentScanOptions {auto?: boolean;planOnly?: boolean;workers?: number;+ maxTotalCostUsd?: number;config?: CodexSecurityConfig;scanOptions?: Omit<ScanSettings, "target" | "outputDir"> &Pick<ScanOptions, "onMeasurement">;@@ -83,6 +85,7 @@ export interface ComponentReceipt {id: string;name: string;paths: string[];+ maxCostUsd?: number;status: "pending" | "started" | "completed" | "failed";outputDir: string;scanId?: string;@@ -124,7 +127,7 @@ interface CombinedFinding {}export interface ComponentDeduplicationSummary {- status: "completed" | "failed";+ status: "completed" | "failed" | "skipped";confirmedGroups: number;uncertainPairs: number;error?: string;@@ -153,6 +156,18 @@ export async function runComponentScans(throw new Error("Component workers must be a positive integer.");if (Boolean(options.auto) === (options.components !== undefined))throw new Error("Choose exactly one of components or automatic planning.");+ if (options.auto && options.maxTotalCostUsd !== undefined)+ throw new Error(+ "--max-total-cost requires --component or --components-file because automatic planning calls an unmetered model.",+ );+ const pool =+ options.planOnly || options.maxTotalCostUsd === undefined+ ? undefined+ : new BatchCostPool(+ options.maxTotalCostUsd,+ options.components?.length ?? 1,+ );+ const budget = batchScanBudget(pool?.share, options.scanOptions ?? {});const auth = options.scanOptions?.auth;let environment = options.environment;if (auth !== undefined && auth !== "auto") {@@ -215,11 +230,13 @@ export async function runComponentScans(};if (options.planOnly) return base;+ const { maxCostUsd } = budget;const receipts: ComponentReceipt[] = plan.components.map((component, index) => ({...component,id: `component-${index + 1}`,operationId: randomUUID(),+ ...(maxCostUsd === undefined ? {} : { maxCostUsd }),status: "pending",outputDir: join(output, `component-${index + 1}`),}),@@ -246,8 +263,6 @@ export async function runComponentScans(while (!options.signal?.aborted) {const receipt = receipts[next++];if (receipt === undefined) return;- receipt.status = "started";- notify(() => options.onProgress?.(copyReceipt(receipt)));const emit = (event: ComponentScanUpdate): void =>notify(() =>options.onScanEvent?.({ ...event, componentId: receipt.id }),@@ -271,9 +286,17 @@ export async function runComponentScans(onWorkerStatus: (value) => emit({ type: "workers", value }),onWarning: (value) => emit({ type: "warning", value }),};+ let reservation: ReturnType<BatchCostPool["reserve"]> | undefined;try {+ reservation = pool?.reserve(maxCostUsd);+ if (reservation !== undefined)+ receipt.maxCostUsd = reservation.maxCostUsd;+ receipt.status = "started";+ notify(() => options.onProgress?.(copyReceipt(receipt)));const result = await security.run(repository, {...options.scanOptions,+ ...budget,+ maxCostUsd: receipt.maxCostUsd,...observers,onScanRegistered: ({ scanId }) => {receipt.scanId = scanId;@@ -287,6 +310,7 @@ export async function runComponentScans(parentAttemptId,},onMeasurement: (measurement) => {+ reservation?.record(measurement.cost);receipt.measurement = measurement;if (measurement.cost !== null) receipt.cost = measurement.cost;else delete receipt.cost;@@ -294,6 +318,7 @@ export async function runComponentScans(emit({ type: "measurement", value: measurement });},});+ reservation?.record(result.cost);if (result.manifest.scan.status !== "completed")throw new Error(`Component scan ${result.manifest.scan.status}.`);results.set(receipt.id, result);@@ -305,6 +330,8 @@ export async function runComponentScans(if (result.threatModelPath !== null)receipt.threatModelPath = result.threatModelPath;} catch (error) {+ if (error instanceof ScanCostLimitExceededError)+ reservation?.record(error.cost);receipt.status = "failed";receipt.outcome = options.signal?.aborted ? "canceled" : "failed";receipt.error = errorMessage(error);@@ -335,10 +362,10 @@ export async function runComponentScans(notify(() => options.onProgress?.(copyReceipt(receipt)));}}- const { findings, matches, uncertain, related, error } =+ const { findings, matches, uncertain, related, error, skipped } =await deduplicateFindings(receipts, results, { ...options, environment });const deduplication: ComponentDeduplicationSummary = {- status: error === undefined ? "completed" : "failed",+ status: skipped ? "skipped" : error === undefined ? "completed" : "failed",confirmedGroups: matches.length,uncertainPairs: uncertain.length,...(error === undefined ? {} : { error }),@@ -403,7 +430,11 @@ async function deduplicateFindings(results: Map<string, ScanResult>,options: ComponentScanOptions,): Promise<- ScanComparisonResult & { findings: CombinedFinding[]; error?: string }+ ScanComparisonResult & {+ findings: CombinedFinding[];+ error?: string;+ skipped?: boolean;+ }> {const scans = receipts.flatMap((receipt) => {const findings = results.get(receipt.id)?.findings.findings ?? [];@@ -424,6 +455,8 @@ async function deduplicateFindings();const matching: ScanComparisonResult = { matches: [], uncertain: [] };const [first, ...remaining] = scans;+ if (remaining.length && options.maxTotalCostUsd !== undefined)+ return { ...matching, findings, skipped: true };const componentFindings = ({receipt,findings,@@ -525,6 +558,12 @@ function renderReport("# Component scan report","",`${summary.completed} complete, ${summary.failed} failed. ${findings.length} finding groups.`,+ ...(summary.deduplication?.status === "skipped"+ ? [+ "",+ "Cross-component matching skipped under the total cost limit. Findings are listed separately.",+ ]+ : []),...(summary.deduplication?.status === "failed"? ["", `Cross-component matching failed: ${summary.deduplication.error}`]: []),diff --git a/sdk/typescript/src/multiscan.ts b/sdk/typescript/src/multiscan.tsindex 86128bd1a..e46d745a2 100644--- a/sdk/typescript/src/multiscan.ts+++ b/sdk/typescript/src/multiscan.ts@@ -33,6 +33,7 @@ import type { CodexSecurity, ScanOptions } from "./api.js";import type { CodexSecurityConfig, JsonObject } from "./config.js";import { ContractSchemaError, loadContract, readScanFile } from "./contract.js";import type { ScanCost, ScanUsageMeasurement } from "./cost.js";+import { BatchCostPool, batchScanBudget } from "./batch-cost.js";import { deepScanOptions } from "./deep-config.js";import { readThreatModelPath } from "./artifact-export.js";import {@@ -123,6 +124,7 @@ export interface MultiscanOptions extends ScanPromptSettings {scanDir: string,prompts: ScanPromptSettings &Pick<ScanOptions, "onMeasurement" | "onTelemetry"> & {+ maxTotalCostShareUsd?: number;knowledgeBaseSnapshot?: KnowledgeBaseSnapshot;/** @internal Preserve correlation when the resumed SDK has no saved binding. */telemetryContext?: { operationId: string; parentAttemptId?: string };@@ -130,10 +132,12 @@ export interface MultiscanOptions extends ScanPromptSettings {): Promise<| (Pick<ScanResult, "manifest" | "cost" | "findings"> & {usage?: JsonObject;+ alreadyCompleted?: boolean;})| undefined>;maxCostUsd?: number;+ maxTotalCostUsd?: number;// Prompts are shared across modes and prepared from the top-level options.scanOptionsByMode?: Partial<Record<ScanMode, Omit<ScanSettings, keyof ScanPromptSettings>>@@ -147,6 +151,7 @@ export interface MultiscanOptions extends ScanPromptSettings {repository: string;status: "started" | "completed" | "failed";attempt: number;+ maxCostUsd?: number;error?: string;warning?: string;}): void;@@ -432,6 +437,13 @@ async function runCampaign(});if (pending.length === 0) return summarize();+ const pool =+ options.maxTotalCostUsd === undefined+ ? undefined+ : new BatchCostPool(+ options.maxTotalCostUsd,+ pending.length * options.maxAttempts,+ );let next = 0;let receiptTail = Promise.resolve();const worker = async (@@ -442,6 +454,11 @@ async function runCampaign(const task = pending[next++];if (task === undefined) return;const knowledge = knowledgeByMode[task.mode];+ const scanSettings = options.scanOptionsByMode?.[task.mode];+ const budget = batchScanBudget(pool?.share, {+ ...options,+ maxCostUsd: options.maxCostUsd ?? scanSettings?.maxCostUsd,+ });const history = receipts.get(task.id.toLowerCase());let operationId = history?.scan?.operationId;let maxAttempt = history?.maxAttempt ?? 0;@@ -479,9 +496,11 @@ async function runCampaign(let attemptPolicyFailed: boolean | undefined;let cost: Readonly<ScanCost> | null = null;let measurement: Readonly<ScanUsageMeasurement> | null = null;+ let reservation: ReturnType<BatchCostPool["reserve"]> | undefined;let savedUsage: JsonObject | undefined;const observers: Pick<ScanOptions, "onMeasurement" | "onTelemetry"> = {onMeasurement: (value) => {+ reservation?.record(value.cost);measurement = value;cost = value.cost;},@@ -495,11 +514,14 @@ async function runCampaign(let knowledgeBaseFailure = false;let checkoutOccupied = false;try {+ reservation = pool?.reserve(budget.maxCostUsd);+ const maxCostUsd = reservation?.maxCostUsd ?? budget.maxCostUsd;await ensureOutputDirectory(artifactRoot);let result:| (Pick<ScanResult, "manifest" | "cost" | "findings"> &Partial<Pick<ScanResult, "threatModelPath">> & {usage?: JsonObject;+ alreadyCompleted?: boolean;})| undefined;if (@@ -529,6 +551,7 @@ async function runCampaign(repository: task.id,attempt,status: "started",+ maxCostUsd,});if (knowledge?.failure !== undefined) {knowledgeBaseFailure = true;@@ -536,6 +559,9 @@ async function runCampaign(}result = await options.recoverScan(scanDir, {...options,+ ...(options.maxTotalCostUsd === undefined+ ? {}+ : { maxTotalCostShareUsd: maxCostUsd }),knowledgeBaseSnapshot: knowledge?.snapshot,...observers,...(operationId === undefined@@ -545,7 +571,6 @@ async function runCampaign(attemptedResume = result !== undefined;}}- const scanSettings = options.scanOptionsByMode?.[task.mode];if (result === undefined) {if (options.recoverScan !== undefined) attempt = nextAttempt();scanDir = join(artifactRoot, `attempt-${attempt}`);@@ -553,6 +578,7 @@ async function runCampaign(repository: task.id,attempt,status: "started",+ maxCostUsd,});if (options.recoverScan === undefined)await validateOutputDir(scanDir);@@ -633,9 +659,8 @@ async function runCampaign(...(options.postScanPrompt === undefined? {}: { postScanPrompt: options.postScanPrompt }),- ...(options.maxCostUsd === undefined- ? {}- : { maxCostUsd: options.maxCostUsd }),+ ...budget,+ maxCostUsd,...observers,onWarning: (warning) => {runWarnings.push(warning);@@ -653,6 +678,7 @@ async function runCampaign(}threatModelPath = result.threatModelPath;cost = result.cost;+ if (!result.alreadyCompleted) reservation?.record(cost);savedUsage = result.usage;const failureSeverity = scanSettings?.failureSeverity;if (failureSeverity !== undefined) {@@ -667,8 +693,10 @@ async function runCampaign(// Recovery retains its resumable attempt and checkout; SDK telemetry records cancellation.if (options.signal?.aborted && options.recoverScan !== undefined)options.signal.throwIfAborted();+ if (pool && !reservation) exhaustedBudget = true;if (error instanceof ScanCostLimitExceededError) {cost = error.cost;+ reservation?.record(cost);exhaustedBudget = true;}requiresRecovery = error instanceof OutputDirectoryNotEmptyError;diff --git a/sdk/typescript/src/scan-dashboard.ts b/sdk/typescript/src/scan-dashboard.tsindex ecddac4df..41742c2de 100644--- a/sdk/typescript/src/scan-dashboard.ts+++ b/sdk/typescript/src/scan-dashboard.ts@@ -96,6 +96,7 @@ interface ScanDashboardOptions {model?: ScanModelConfiguration;pricingContext?: ScanPricingContext;maxCostUsd?: number;+ maxTotalCostUsd?: number;showCost?: boolean;clock: DashboardClock;color?: boolean;@@ -470,6 +471,7 @@ export class ScanDashboard {...this.#options,presentation: "scan",componentName: receipt.name,+ maxCostUsd: receipt.maxCostUsd ?? this.#options.maxCostUsd,});dashboard.setStage(COMPONENT_STATUS.pending);dashboard.note(`Scope: ${receipt.paths.join(", ")}`);@@ -486,6 +488,8 @@ export class ScanDashboard {const { dashboard } = component;if (receipt.status !== component.receipt.status) {if (receipt.status === "started") {+ if (receipt.maxCostUsd !== undefined)+ dashboard.#options.maxCostUsd = receipt.maxCostUsd;dashboard.#startedAt = this.#options.clock.now();dashboard.setStage("Preparing scan");} else if (receipt.status !== "pending") {@@ -1057,7 +1061,9 @@ export class ScanDashboard {get #showCost(): boolean {return (- this.#options.showCost === true || this.#options.maxCostUsd !== undefined+ this.#options.showCost === true ||+ this.#options.maxCostUsd !== undefined ||+ this.#options.maxTotalCostUsd !== undefined);}@@ -1072,11 +1078,20 @@ export class ScanDashboard {const costs = this.#components.flatMap(({ dashboard }) =>dashboard.#cost === null ? [] : [dashboard.#cost],);- return wrapActivity(- " COST ",- `${costs.length === 0 ? "waiting for usage" : formatScanCosts(costs)}${this.#components.some(({ dashboard }) => dashboard.#usageCoverage !== "complete") ? " (partial)" : ""} · component scans only`,- this.#width(),+ const partial = this.#components.some(+ ({ dashboard }) => dashboard.#usageCoverage !== "complete",);+ const lines = [+ (costs.length ? formatScanCosts(costs) : "waiting for usage") ++ (partial ? " (partial)" : ""),+ "component scans only",+ ];+ if (this.#options.maxTotalCostUsd !== undefined)+ lines.push(`${formatUsd(this.#options.maxTotalCostUsd)} total limit`);+ const perComponent = this.#components[0]?.receipt.maxCostUsd;+ if (perComponent !== undefined)+ lines.push(`up to ${formatUsd(perComponent)} per component`);+ return wrapActivity(" COST ", lines.join(" · "), this.#width());}#width(): number {diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.tsindex bbd042ce3..dde633bd4 100644--- a/sdk/typescript/tests-ts/api.test.ts+++ b/sdk/typescript/tests-ts/api.test.ts@@ -14331,6 +14331,7 @@ if __name__ == "__main__":["semantic matching fails", "matcher", "matcher unavailable"],["the repository index fails", "index", "index unavailable"],["the repository projection is unavailable", "projection", undefined],+ ["a batch cost limit skips unmetered matching", "batch-budget", undefined],["a cost limit still allows false-positive matching", "budget", undefined],["cost-limited matching needs additional context",@@ -14370,7 +14371,9 @@ if __name__ == "__main__":[nativeHeader]: " synthetic-required-header ",}: {};- const limited = failure === "budget" || failure === "budget-context";+ const boundedBatch = failure === "batch-budget";+ const limited =+ boundedBatch || failure === "budget" || failure === "budget-context";const { root, repository, codexHome, scanDir } = await scanDirectories();const current = {findingId: "csf_852f90d6e1177502ff113d4a",@@ -14544,7 +14547,10 @@ if __name__ == "__main__":},{...scanRuntimeDependencies(codexHome, scanDir),- environment: gatewayEnvironment,+ environment: {+ ...gatewayEnvironment,+ CODEX_SECURITY_STATE_DIR: join(root, "state"),+ },prepareRuntime: runtimePreparer(codexHome, () => ({environment: {SYNTHETIC_MATCH_HEADER: "synthetic-comparison-header",@@ -14791,6 +14797,7 @@ if __name__ == "__main__":try {const result = await client.run(repository, {ownerSuggestions: ownerSpy !== undefined,+ skipFindingMatching: boundedBatch,...(limited ? { maxCostUsd: 1 } : {}),cyberAccessProgram: "daybreak_blue",onProgress() {},@@ -14803,7 +14810,7 @@ if __name__ == "__main__":expect(result.repositoryFindings?.map(({ findingId }) => findingId),).toEqual(- failure === "budget"+ failure === "budget" || boundedBatch? ["another-open-finding"]: failure === "dismissed" ||failure === "managed" ||@@ -14811,17 +14818,12 @@ if __name__ == "__main__":? []: undefined,);- expect(modelCalled).toBe(- failure !== "index" && failure !== "projection",- );- expect(observedSingleTurn).toBe(- failure === "index" || failure === "projection" ? undefined : limited,- );+ const expectsModel =+ !boundedBatch && failure !== "index" && failure !== "projection";+ expect(modelCalled).toBe(expectsModel);+ expect(observedSingleTurn).toBe(expectsModel ? limited : undefined);expect(matchingTurns).toBe(- failure === "index" ||- failure === "projection" ||- failure === "matcher" ||- failure === "managed"+ !expectsModel || failure === "matcher" || failure === "managed"? 0: 1,);diff --git a/sdk/typescript/tests-ts/cli-help.test.ts b/sdk/typescript/tests-ts/cli-help.test.tsindex 31c16f2d5..20206562a 100644--- a/sdk/typescript/tests-ts/cli-help.test.ts+++ b/sdk/typescript/tests-ts/cli-help.test.ts@@ -96,6 +96,14 @@ describe("CLI help", () => {expect(text).toContain("<command> --help");});+ test.each(["bulk-scan", "scan-components"])(+ "labels %s cost limits in USD",+ async (command) => {+ const text = await help([command, "--help"]);+ expect(option(text, "--max-total-cost")).toContain("<usd>");+ },+ );+test("shows semantic values, repeatable inputs, choices, and scan defaults", async () => {const text = await help(["scan", "--help"]);expect(text).toContain("Usage: codex-security scan [repository]");diff --git a/sdk/typescript/tests-ts/cli-patch.test.ts b/sdk/typescript/tests-ts/cli-patch.test.tsindex 65f1b35e7..5225df6af 100644--- a/sdk/typescript/tests-ts/cli-patch.test.ts+++ b/sdk/typescript/tests-ts/cli-patch.test.ts@@ -2361,6 +2361,24 @@ describe("scan and patch workflow", () => {}});+ test("shows findings without offering interactive patches on a budgeted scan", async () => {+ const confirmPatchReview = mock(resolving(true));+ const patchEditor = mock(resolving(null));+ const outcome = await runWorkflow(+ ["scan", "--max-cost", "1"],+ { result: resultWithFindings(["high"]) },+ {+ interactive: true,+ configure: (value) =>+ Object.assign(value, { confirmPatchReview, patchEditor }),+ },+ );+ expect(outcome.exitCode).toBe(0);+ expect(outcome.stderr).toContain("FINDINGS");+ expect(confirmPatchReview).not.toHaveBeenCalled();+ expect(patchEditor).not.toHaveBeenCalled();+ });+test("shows normal scan findings before optionally opening patch review", async () => {for (const review of [true, false]) {let opened = false;diff --git a/sdk/typescript/tests-ts/cli-project-config.test.ts b/sdk/typescript/tests-ts/cli-project-config.test.tsindex b1bd29d05..943aabba4 100644--- a/sdk/typescript/tests-ts/cli-project-config.test.ts+++ b/sdk/typescript/tests-ts/cli-project-config.test.ts@@ -392,6 +392,29 @@ test("rerun rejects a blank replacement when scan instructions are required", asexpect(onConfig).not.toHaveBeenCalled();});+test.each(["project", "flag"])(+ "rejects patching before starting a scan with a %s budget",+ async (source) => {+ const input = await fixture({ limits: { max_cost_usd_per_scan: 1 } });+ const onRun = mock(throwing("unexpected scan"));+ const onCodex = mock(throwing("unexpected patch"));+ const stderr = captureCli(main, "stderr");+ const budget =+ source === "project" ? ["-c", input.config] : ["--max-cost", "1"];+ expect(+ await stderr.run(+ ["scan", input.repository, "--patch", ...budget, "--json"],+ dependencies({ onRun, onCodex }),+ ),+ ).toBe(2);+ expect(stderr.text()).toContain(+ "--patch cannot be combined with a scan cost limit",+ );+ expect(onRun).not.toHaveBeenCalled();+ expect(onCodex).not.toHaveBeenCalled();+ },+);+test.each(["instructions_file", "validation_file"] as const)("bulk %s retains directory-link protection for local CSV repositories",async (file) => {diff --git a/sdk/typescript/tests-ts/component-scan.test.ts b/sdk/typescript/tests-ts/component-scan.test.tsindex 2293cb03c..f191d082f 100644--- a/sdk/typescript/tests-ts/component-scan.test.ts+++ b/sdk/typescript/tests-ts/component-scan.test.ts@@ -484,6 +484,69 @@ test("omits a failed component's stale model link while retaining its model", as);});+test.each([+ [9, 2],+ [3, 1],+])(+ "divides a $%i budget across concurrent components",+ async (total, expected) => {+ const paths = await fixture();+ const config = join(paths.root, "settings.yaml");+ await writeFile(config, "scan:\n owner_suggestions: true\n");+ const matchFindings = mock(rejecting("unexpected unmetered model call"));+ const { code, stderr, stdout } = await cli(+ paths,+ [+ ...components.flatMap(({ paths }) => ["--component", paths[0]!]),+ "--config",+ config,+ "--workers",+ "3",+ "--max-cost",+ "2",+ "--max-total-cost",+ String(total),+ ],+ {+ createSecurity: client(async (repository, options) => {+ expect(options.maxCostUsd).toBe(expected);+ expect(options.skipFindingMatching).toBe(true);+ expect(options.ownerSuggestions).toBe(false);+ return completed(repository, options);+ }),+ matchFindings,+ },+ );+ expect(code).toBe(0);+ expect(JSON.parse(stdout)).toMatchObject({+ completed: 3,+ findingCount: 3,+ deduplication: { status: "skipped" },+ });+ expect(stderr).toContain(`$${expected}.00 per component`);+ expect(matchFindings).not.toHaveBeenCalled();+ },+);++test("rejects unmetered planning and post-scan prompts under a total limit", async () => {+ const paths = await fixture();+ const planComponents = mock(rejecting("unexpected planner call"));+ const result = await cli(+ paths,+ ["--auto", "--plan-only", "--max-total-cost", "2"],+ { planComponents },+ );+ expect(result.code).toBe(2);+ expect(result.stderr).toContain("--component or --components-file");+ expect(planComponents).not.toHaveBeenCalled();+ await expect(+ scan(paths, {+ maxTotalCostUsd: 2,+ scanOptions: { postScanPrompt: "Extra turn" },+ }),+ ).rejects.toThrow("post-scan prompt");+});+test("bounds standard scans, continues after failure, and preserves partial results", async () => {const paths = await fixture();let active = 0,@@ -496,6 +559,7 @@ test("bounds standard scans, continues after failure, and preserves partial resuscanOptions: {auth: "chatgpt",scanPrompt: "Check access controls",+ ownerSuggestions: true,maxCostUsd: 3,},onProgress: throwing("optional observer"),@@ -510,6 +574,7 @@ test("bounds standard scans, continues after failure, and preserves partial resumode: "standard",auth: "chatgpt",scanPrompt: "Check access controls",+ ownerSuggestions: true,maxCostUsd: 3,});if (scope(repository, options) === "apps/api")diff --git a/sdk/typescript/tests-ts/multiscan.test.ts b/sdk/typescript/tests-ts/multiscan.test.tsindex 5e42caba6..f290c4dce 100644--- a/sdk/typescript/tests-ts/multiscan.test.ts+++ b/sdk/typescript/tests-ts/multiscan.test.ts@@ -44,6 +44,85 @@ afterEach(cleanup);const testPosix = test.skipIf(process.platform === "win32");describe("multiscan", () => {+ test("divides an invocation budget across pending repositories and retries", async () => {+ const paths = await fixture();+ const source = await repository(paths.root, "source");+ await writeFile(+ paths.input,+ `id,repository,revision+first,${source.path},${source.revision}+second,${source.path},${source.revision}+`,+ );+ const limits: number[] = [];+ const bothStarted = Promise.withResolvers<void>();+ const summary = await runMultiscan(+ options(+ paths,+ client(async (_checkout, scan = {}) => {+ limits.push(scan.maxCostUsd!);+ expect(scan.skipFindingMatching).toBe(true);+ expect(scan.ownerSuggestions).toBe(false);+ if (scan.outputDir!.endsWith("attempt-1")) {+ if (limits.length === 2) bothStarted.resolve();+ await bothStarted.promise;+ throw new Error("Retry this repository");+ }+ return completedScan(scan.outputDir!);+ }),+ {+ maxCostUsd: 12,+ maxTotalCostUsd: 8,+ workers: 2,+ maxAttempts: 2,+ scanOptionsByMode: { standard: { ownerSuggestions: true } },+ },+ ),+ );+ expect(summary).toMatchObject({ completed: 2, failed: 0 });+ expect(limits).toEqual([2, 2, 2, 2]);+ });++ test("charges observed overruns before dispatching queued repository attempts", async () => {+ const paths = await fixture();+ const source = await repository(paths.root, "source");+ const rows = ["first", "second", "third"].map(+ (id) => `${id},${source.path},${source.revision}`,+ );+ await writeFile(+ paths.input,+ ["id,repository,revision", ...rows].join("\n"),+ );+ const limits: number[] = [];+ const summary = await runMultiscan(+ options(+ paths,+ client(async (_repo, scan = {}) => {+ limits.push(scan.maxCostUsd!);+ const estimatedUsd = limits.length === 1 ? 5 : 2;+ throw new ScanCostLimitExceededError(+ scan.maxCostUsd!,+ {+ model: "gpt-5.6-sol",+ inputTokens: 10,+ cachedInputTokens: 0,+ cacheWriteInputTokens: 0,+ outputTokens: 10,+ estimatedUsd,+ },+ scan.outputDir!,+ );+ }),+ { workers: 1, maxAttempts: 1, maxTotalCostUsd: 6 },+ ),+ );+ expect(limits).toEqual([2, 1]);+ expect(summary).toMatchObject({ failed: 3 });+ expect((await results(summary.resultsPath)).at(-1)?.["error"]).toContain(+ "invocation cost limit is exhausted",+ );+ });+test("prepares shared prompt files once while missing sources remain row failures", async () => {const paths = await fixture();const source = await repository(paths.root, "prompt-source");diff --git a/sdk/typescript/tests-ts/scan-resume.test.ts b/sdk/typescript/tests-ts/scan-resume.test.tsindex 7291a05bb..0c4992384 100644--- a/sdk/typescript/tests-ts/scan-resume.test.ts+++ b/sdk/typescript/tests-ts/scan-resume.test.ts@@ -58,6 +58,8 @@ async function interruptedScan(settings: Pick<ScanOptions,| "safetyIdentifier"+ | "maxCostUsd"+ | "ownerSuggestions"| "postScanPrompt"| "auth"| "knowledgeBasePaths"@@ -772,6 +774,50 @@ test.each([false, true])(},);+test.each([+ [undefined, 2],+ [1, 1],+])(+ "applies the invocation share when recovering a scan with saved limit %p",+ async (savedLimit, expected) => {+ const f = await interruptedScan("deep", true, {+ maxCostUsd: savedLimit,+ ownerSuggestions: true,+ });+ const seen: ScanOptions[] = [];+ const deps = dependencies({+ environment: f.environment,+ currentDirectory: f.root,+ onTurn: (_repo, options) => seen.push(options),+ });+ deps.runWorkbench = f.command;+ const { runCli } = createCliTest(main);+ await runCli(+ [+ "bulk-scan",+ f.input,+ "--output-dir",+ f.root,+ "--recover",+ "--max-attempts",+ "2",+ "--max-total-cost",+ "4",+ "--json",+ ],+ deps,+ );+ expect(seen).toMatchObject([+ {+ resumeScanId: f.scanId,+ maxCostUsd: expected,+ skipFindingMatching: true,+ ownerSuggestions: false,+ },+ ]);+ },+);+test("resuming reports a committed cancellation once without another launch", async () => {const f = await interruptedScan();const { stderr, runCli } = createCliTest(main);