Repository navigation
Description
Summary
When a Deep Scan crosses --max-cost (limits.max_cost_usd_per_scan, action input max-cost) after discovery has finished, the remaining candidates are not validated, but the bundle is sealed with scan.status: "completed". The scan contract defines completed as "The requested scan reached normal completion" and says "Only completed supports a completed-scan conclusion". The SARIF export reports executionSuccessful: true, the CLI emits scan.completed and exits 0.
If the same cost stop lands while discovery is still running, the scan ends as scan.failed classification="cost_limit_exceeded" with exit 2 and retained artifacts. So one condition, the estimated cost crossing the limit, is reported either as a failure or as a normal completion, depending only on which phase was running at that moment.
Current behaviour
Checked on npm-v0.8.3 and main at 9b3ce7a. The first case was observed in CI on 0.8.2, and the code path is unchanged since then.
Cost stop during discovery
complete-budget-exhausted-scanrefuses ("Budget-exhausted scan completion requires successfully completed Deep Scan discovery."). The SDK falls through and the scan is stopped as failed.- The CLI emits
scan.failed classification="cost_limit_exceeded" max_cost_usd=… estimated_usd=…and exits2. - This matches the contract: a stopped outcome, with absence of findings treated as inconclusive.
Cost stop after discovery finished (terminal_reason is saturated or capped)
sdk/typescript/src/api.tscatchesScanCostLimitExceededErrorand runsworkbench_db.py complete-budget-exhausted-scan.budget_exhausted_draft(plugins/codex-security/scripts/workbench_saved_results.py) does two things:- It records unvalidated candidates as
needs_follow_upsurfaces, with deferred reasons starting "Validation was deferred because the scan reached its cost limit". - It adds a generic deferred entry with id
scan-cost-limit.
- It records unvalidated candidates as
complete_scan_lockedthen seals the bundle with the default statuscompleted.finalize_scan_contract.pysetsexecution_successful = manifest["scan"]["status"] == "completed", so SARIF reportsexecutionSuccessful: true. The cost warning appears only as atoolExecutionNotificationsmessage.test_budget_exhaustion_preserves_validated_standard_results_without_candidate_ledgersasserts this.test_budget_exhaustion_with_no_candidates_is_honestly_partialseals a cost-stopped scan with zero findings ascomplete; the only marker is thescan-cost-limitdeferred entry.- The CLI emits
scan.completed, which has no stop-reason field, and exits0(or1when findings meet a configured failure threshold), assdk/typescript/docs/cli.mddocuments.readDeepScanStopknows the reason ("Reached the … cost limit. More issues may remain."), but it is printed only in the human summary.
Why it matters
- Automation keyed on
scan.status, SARIFexecutionSuccessful, the exit code, or thescan.completeddiagnostic treats a cost-stopped scan as complete. Today, telling the two apart means string-matching warning or deferred-reason text, or relying on thescan-cost-limitid, which is not documented. - Candidates that were discovered but not validated are not SARIF results. Suppose a SARIF consumer closes alerts that are missing from a newer successful analysis. It can then close alerts this run never re-checked.
- It contradicts the contract's own rule for stopped outcomes: consumers should treat absence of findings as inconclusive.
Proposed change (minimal)
- Do not seal a cost-limit stop as
completed. Keep the sealed report and the deferred candidates exactly as today, but use a stopped status.interrupted("stopped before normal completion … retained artifacts may be partial") already fits, or there could be a dedicated status. The CLI already has a branch for a sealed non-completedresult: it prints "Scan ; available results were retained." and exits2. - If
completedhas to stay for compatibility, add a documented machine-readable stop reason to the sealed manifest and the JSON result, for examplescan.stopReason: "cost_limit". Also reportexecutionSuccessful: falsefor it in SARIF, and include the stop reason in thescan.completed/scan.faileddiagnostic. - Describe both cost-stop outcomes (during discovery, after discovery) in one place: the
scan.statustable inplugins/codex-security/references/scan-contract.mdand the--max-costsection ofsdk/typescript/docs/cli.md.
Either 1 or 2 would let consumers tell "stopped at the cost limit" from "finished" without parsing text.
Activity
mldangelo-oai commentedon Nov 15, 2026
I reproduced this on both a fresh scan and a resumed one. On main, hitting the cost limit after discovery produced a completed manifest, successful SARIF, and exit 0. #2492 corrects all three and exits 2.
There’s one recovery case to fix before closing this. When a database write failed after the report was sealed, SARIF kept the synthetic finding but the workbench showed zero findings. Retrying should bring the workbench back in sync with the sealed report. I’m keeping this open with #2492.