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(cost): enforce scan budgets from verified usage (#465)
Michael D'Angeloc9cb6b4bca13
diff --git a/plugins/codex-security/mcp-app/tests/test_workbench_database.ts b/plugins/codex-security/mcp-app/tests/test_workbench_database.tsindex ac108f1a4..ffad1b5c9 100644--- a/plugins/codex-security/mcp-app/tests/test_workbench_database.ts+++ b/plugins/codex-security/mcp-app/tests/test_workbench_database.ts@@ -199,7 +199,7 @@ for (const previewVersion of [58, 59]) {}for (const { missingVersions, legacyCheckpoint, mainReader } of [- { missingVersions: [57, 58, 59, 60], legacyCheckpoint: 0, mainReader: false },+ { missingVersions: [57], legacyCheckpoint: 0, mainReader: false },{ missingVersions: [], legacyCheckpoint: 47, mainReader: false },{ missingVersions: [], legacyCheckpoint: 47, mainReader: true },{ missingVersions: [], legacyCheckpoint: 48, mainReader: false },@@ -227,6 +227,7 @@ for (const { missingVersions, legacyCheckpoint, mainReader } of [migrations.filter(({ version }) =>+ version <= 57 &&!missingVersions.includes(version) &&!(firstMissing && version >= firstMissing && version <= 56),)@@ -365,8 +366,7 @@ for (const { missingVersions, legacyCheckpoint, mainReader } of [});}-test("worker thread history survives retry, replay, and worker retirement", (t) => {- const database = memory(t, 49);+function insertRunningWorker(database: DatabaseSync) {insertScan(database);database.exec(`INSERT INTO deep_scan_runs (@@ -379,6 +379,30 @@ test("worker thread history survives retry, replay, and worker retirement", (t)) VALUES ('worker', 'scan', 'discovery', 'running', '/synthetic/prompt.md','/synthetic/output', 1, 'first-thread', 'created', 'updated');`);+}++test("legacy retries can reuse a recorded thread and still verify usage", (t) => {+ for (const thread of ["first-thread", "retry-thread", null]) {+ const database = memory(t, 62);+ insertRunningWorker(database);+ database+ .prepare(+ "UPDATE deep_scan_workers SET attempt = 3, started_at = 'started', sdk_thread_id = ?",+ )+ .run(thread);+ if (thread === null) database.exec("DELETE FROM deep_scan_worker_threads");+ applyMigrations(database);+ assert.equal(+ database.prepare("SELECT worker_usage_gap FROM deep_scan_runs").get()+ ?.worker_usage_gap,+ thread === null ? 1 : 0,+ );+ }+});++test("worker thread history survives retry, replay, and worker retirement", (t) => {+ const database = memory(t, 49);+ insertRunningWorker(database);applyMigrations(database);database.exec(`UPDATE deep_scan_workers SET sdk_thread_id = 'retry-thread', attempt = 2;diff --git a/plugins/codex-security/requirements-test.txt b/plugins/codex-security/requirements-test.txtindex e005b00f3..1790db5ab 100644--- a/plugins/codex-security/requirements-test.txt+++ b/plugins/codex-security/requirements-test.txt@@ -1,4 +1,5 @@# Development test and lint dependencies; install from the repository root.+backports.zstd==1.8.0; python_version < "3.14"jsonschema==4.26.0packaging==26.3pytest==9.2.0diff --git a/plugins/codex-security/scripts/deep_scan_workbench.py b/plugins/codex-security/scripts/deep_scan_workbench.pyindex 635963ca3..77beac07d 100644--- a/plugins/codex-security/scripts/deep_scan_workbench.py+++ b/plugins/codex-security/scripts/deep_scan_workbench.py@@ -1327,11 +1327,14 @@ def upsert_deep_scan_worker(if error_message is None and args.status != "succeeded":error_message = existing["error_message"]started_at = existing["started_at"] or (timestamp if args.status == "running" else None)+ thread_id = optional_text(args.sdk_thread_id, maximum=512)+ if thread_id is None and attempt == existing["attempt"]:+ thread_id = existing["sdk_thread_id"]connection.execute("""UPDATE deep_scan_workersSET status = ?, result_manifest_path = ?, attempt = ?,- sdk_thread_id = COALESCE(?, sdk_thread_id),+ sdk_thread_id = ?,completion_sequence = ?, merge_state = ?,error_message = ?,started_at = ?, completed_at = ?, updated_at = ?@@ -1341,7 +1344,7 @@ def upsert_deep_scan_worker(args.status,result_manifest_path or existing["result_manifest_path"],attempt,- optional_text(args.sdk_thread_id, maximum=512),+ thread_id,completion_sequence,merge_state,error_message,diff --git a/plugins/codex-security/scripts/workbench_cli.py b/plugins/codex-security/scripts/workbench_cli.pyindex acd772c35..5c1c532bb 100644--- a/plugins/codex-security/scripts/workbench_cli.py+++ b/plugins/codex-security/scripts/workbench_cli.py@@ -199,6 +199,9 @@ def parse_args(description: str, *, inspection_only: bool = False) -> argparse.Nadd_command("rename-scan", "--scan-id", "--name")+ read_scan_usage = add_command("read-scan-usage", "--scan-id", "--thread-id")+ read_scan_usage.add_argument("--validation-thread-id")+add_command("get-scan-feedback", "--scan-id")update_scan_context = add_command("update-scan-context", "--scan-id")diff --git a/plugins/codex-security/scripts/workbench_db.py b/plugins/codex-security/scripts/workbench_db.pyindex e1661a406..d1936c4ec 100644--- a/plugins/codex-security/scripts/workbench_db.py+++ b/plugins/codex-security/scripts/workbench_db.py@@ -1030,6 +1030,17 @@ def complete_scan()+def read_scan_usage(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:+ # Validation can finish after the scan's recorded completion timestamp.+ return scan_usage.collect_scan_usage(+ connection,+ require_scan(connection, args.scan_id),+ thread_id=args.thread_id,+ validation_thread_id=args.validation_thread_id,+ completed_at=now(),+ )++def finalize_scan_usage(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:scan_id = require_uuid(args.scan_id, "scan-id")with scan_completion_lock(scan_id):@@ -3210,7 +3221,9 @@ def main(*, before_archive: Callable[[], None] | None = None) -> None:print(json.dumps(result, allow_nan=False, sort_keys=True))returnwith closing(- connect(deferred=args.command in {"get-scan", "list-scans", "database-info"})+ connect(+ deferred=args.command in {"get-scan", "read-scan-usage", "list-scans", "database-info"}+ )) as connection:remediation_state.require_available(connection, args, require_scan)handlers = {@@ -3230,6 +3243,7 @@ def main(*, before_archive: Callable[[], None] | None = None) -> None:"register-cli-scan": partial(register_cli_scan, before_archive=before_archive),"set-scan-thread": set_scan_thread,"set-scan-cost-limit": set_scan_cost_limit,+ "read-scan-usage": read_scan_usage,"finalize-scan-usage": finalize_scan_usage,"list-global-findings": native_indexes.list_global_findings,"list-repositories": native_indexes.list_repositories,diff --git a/plugins/codex-security/scripts/workbench_scan_usage.py b/plugins/codex-security/scripts/workbench_scan_usage.pyindex 01b4d6e64..04eef1c1b 100644--- a/plugins/codex-security/scripts/workbench_scan_usage.py+++ b/plugins/codex-security/scripts/workbench_scan_usage.py@@ -10,10 +10,11 @@ import reimport sqlite3import sysimport uuid+from contextlib import contextmanagerfrom dataclasses import dataclassfrom datetime import datetime, timezonefrom pathlib import Path-from typing import Any, Mapping+from typing import Any, BinaryIO, Iterator, Mappingfrom urllib.parse import quoteTOKEN_FIELDS = {@@ -90,6 +91,7 @@ def collect_scan_usage(scan: sqlite3.Row,*,thread_id: str | None = None,+ validation_thread_id: str | None = None,completed_at: str | None = None,completed_turn_id: str | None = None,) -> dict[str, Any]:@@ -102,7 +104,11 @@ def collect_scan_usage(roots = _scan_root_thread_ids(connection, scan, thread_id)parent_ids = set(_scan_root_thread_ids(connection, scan, thread_id, include_workers=False))- worker_directories = _scan_worker_directories(connection, scan)+ if validation_thread_id:+ roots.append(validation_thread_id)+ parent_ids.add(validation_thread_id)+ warnings: set[str] = set()+ worker_directories = _scan_worker_directories(connection, scan, warnings)if not roots and not worker_directories:return _unavailable_usage("scan_thread_unavailable")@@ -116,7 +122,6 @@ def collect_scan_usage(if started_at is None:return _unavailable_usage("scan_window_unavailable")- warnings: set[str] = set()try:sessions, missing_thread_ids = _discover_rollout_sessions(state_database,@@ -177,7 +182,7 @@ def collect_scan_usage(for key, snapshot in usage.rate_limits.items():if key not in rate_limits or snapshot["observedAt"] > rate_limits[key]["observedAt"]:rate_limits[key] = snapshot- if "token_usage_unavailable" in usage.warnings:+ if usage.warnings & {"token_usage_unavailable", "token_breakdown_unavailable"}:missing_thread_ids.add(session.thread_id)continuerole = by_role["parent" if session.thread_id in parent_ids else "workers"]@@ -192,9 +197,12 @@ def collect_scan_usage(return _unavailable_usage("scan_thread_unavailable", warnings=warnings)thread_count = sum(role["threadCount"] for role in by_role.values())if not thread_count:- return _unavailable_usage(- "token_usage_unavailable", warnings=warnings, rate_limits=rate_limits+ reason = (+ "token_breakdown_unavailable"+ if "token_breakdown_unavailable" in warnings+ else "token_usage_unavailable")+ return _unavailable_usage(reason, warnings=warnings, rate_limits=rate_limits)if any(usage["cachedInputTokens"] + usage["cacheWriteInputTokens"] > usage["inputTokens"]@@ -276,19 +284,35 @@ def _scan_execution_thread_ids(connection: sqlite3.Connection, scan: sqlite3.Row)-def _scan_worker_directories(connection: sqlite3.Connection, scan: sqlite3.Row) -> set[str]:+def _scan_worker_directories(+ connection: sqlite3.Connection, scan: sqlite3.Row, warnings: set[str]+) -> dict[str, bool]:if scan["mode"] != "deep":- return set()+ return {}+ if connection.execute(+ "SELECT 1 FROM deep_scan_runs WHERE scan_id = ? AND worker_usage_gap = 1", (scan["id"],)+ ).fetchone():+ warnings.add("worker_thread_unavailable")artifacts = Path(scan["scan_dir"]) / "artifacts"- # Finding comparisons start independent sessions before the batch checkpoint is saved.- return {str(artifacts / "deep_discovery")} | {- row["artifact_dir"] if row["kind"] == "discovery" else str(artifacts)- for row in connection.execute(- "SELECT kind, artifact_dir FROM deep_scan_workers "- "WHERE scan_id = ? AND kind IN ('discovery', 'dedup')",- (scan["id"],),- )- }+ # Comparison turns run in this directory without a discovery worker row.+ directories = {str(artifacts / "deep_discovery"): False}+ for row in connection.execute(+ "SELECT kind, artifact_dir, started_at, sdk_thread_id, attempt FROM deep_scan_workers "+ "WHERE scan_id = ? AND kind IN ('discovery', 'dedup')",+ (scan["id"],),+ ):+ if row["kind"] == "discovery":+ if row["sdk_thread_id"] and row["attempt"] == 1:+ continue # The first attempt already has an exact thread identity.+ # An attempt that started without a saved ID must be found by its assigned cwd.+ missing_thread = bool(row["started_at"] and not row["sdk_thread_id"])+ directories[row["artifact_dir"]] = missing_thread+ else:+ directories[str(artifacts)] = False+ if row["attempt"] > 1 and row["started_at"] and not row["sdk_thread_id"]:+ # Retries share a cwd. A rollout from an older attempt cannot prove the new one.+ warnings.add("worker_thread_unavailable")+ return directoriesdef _codex_state_database() -> Path | None:@@ -333,7 +357,7 @@ def _discover_rollout_sessions(roots: list[str],warnings: set[str],*,- worker_directories: set[str],+ worker_directories: dict[str, bool],scan_directory: Path | None = None,started_at: datetime,completed_at: datetime | None,@@ -354,11 +378,11 @@ def _discover_rollout_sessions(if not required.issubset(columns):raise ValueError("Codex state graph does not expose the required thread columns.")if table == "threads" and worker_directories and not {"cwd", "created_at"} <= columns:- worker_directories = set()+ worker_directories = {}warnings.add("worker_directories_unavailable")sessions: dict[str, RolloutSession] = {}missing_thread_ids: set[str] = set()- root_ids = dict.fromkeys(roots)+ root_ids: dict[str, str | None] = dict.fromkeys(roots)started_millisecond = started_at.replace(microsecond=started_at.microsecond // 1000 * 1000)completed_timestamp = int(completed_at.timestamp()) if completed_at is not None else Nonedirectory_expression = "cwd"@@ -369,9 +393,14 @@ def _discover_rollout_sessions("codex_security_path_key", 1, _normalized_windows_path, deterministic=True)directory_expression = "codex_security_path_key(cwd)"- worker_directories = {_normalized_windows_path(value) for value in worker_directories}+ worker_directories = {+ _normalized_windows_path(path): required+ for path, required in worker_directories.items()+ }if scan_directory is not None:scan_directory = Path(_normalized_windows_path(scan_directory))+ unmatched = {path for path, required in worker_directories.items() if required}+ directory_sources = {path: {path} for path in worker_directories}if worker_directories and scan_directory and ".previous-" in scan_directory.name:# Archived files move, but session working directories describe where execution ran.# Confirm the original output with an already-bound session before including peers.@@ -384,7 +413,7 @@ def _discover_rollout_sessions()}relatives = {- Path(path).relative_to(scan_directory)+ Path(path).relative_to(scan_directory): pathfor path in worker_directoriesif Path(path).is_relative_to(scan_directory)}@@ -392,23 +421,24 @@ def _discover_rollout_sessions(if marker.start() == 0:continueoriginal = scan_directory.with_name(scan_directory.name[: marker.start()])- candidates = {original / relative for relative in relatives}+ candidates = {original / relative: path for relative, path in relatives.items()}# Older archives kept absolute discovery paths in their original directory.if (original in bound_directories- or candidates & bound_directories+ or candidates.keys() & bound_directoriesor any(Path(path).is_relative_to(original) for path in worker_directories)):- worker_directories = worker_directories | {str(path) for path in candidates}- for directory in sorted(worker_directories):+ for candidate, path in candidates.items():+ directory_sources.setdefault(str(candidate), set()).add(path)+ for directory in sorted(directory_sources):for row in database.execute("SELECT id FROM threads WHERE cwd IS NOT NULL "f"AND {directory_expression} = ? AND created_at >= ? ""AND (? IS NULL OR created_at <= ?) ORDER BY id",(directory, int(started_at.timestamp()), completed_timestamp, completed_timestamp),):- root_ids[row["id"]] = None- for root in root_ids:+ root_ids[row["id"]] = directory+ for root, directory in root_ids.items():row = database.execute("SELECT id, rollout_path FROM threads WHERE id = ?",(root,),@@ -424,7 +454,7 @@ def _discover_rollout_sessions(continueif root not in roots:try:- with path.open("rb") as source:+ with _open_rollout(path) as source:metadata = json.loads(source.readline())except (OSError, ValueError):missing_thread_ids.add(root)@@ -443,6 +473,8 @@ def _discover_rollout_sessions()):continue+ if directory is not None:+ unmatched.difference_update(directory_sources[directory])sessions[root] = RolloutSession(root, None, path)descendants = database.execute("""@@ -500,6 +532,8 @@ def _discover_rollout_sessions(warnings.add("rollout_unavailable")continuesessions[child_id] = RolloutSession(child_id, parent_id, path)+ if unmatched:+ warnings.add("worker_thread_unavailable")return list(sessions.values()), missing_thread_idsfinally:database.close()@@ -512,6 +546,13 @@ def _rollout_path(value: object) -> Path | None:if not candidate.is_absolute():return Nonetry:+ try:+ candidate.lstat()+ except FileNotFoundError:+ # Native cold storage may compress an indexed JSONL file in place.+ if candidate.suffix != ".jsonl":+ return None+ candidate = candidate.with_suffix(".jsonl.zst")resolved = candidate.resolve(strict=True)if not resolved.is_file():return None@@ -528,6 +569,32 @@ def _rollout_path(value: object) -> Path | None:return None+@contextmanager+def _open_rollout(path: Path, *, verify_end: bool = False) -> Iterator[BinaryIO]:+ if path.suffix != ".zst":+ with path.open("rb") as source:+ yield source+ return+ try:+ from compression import zstd # Python 3.14++ except ImportError:+ try:+ from backports import zstd+ except ImportError:+ raise OSError(+ "Compressed Codex rollouts require Python 3.14+ or backports.zstd."+ ) from None+ try:+ with zstd.open(path, "rb") as source:+ yield source+ # A requested completion turn may stop parsing before the frame checksum.+ if verify_end:+ while source.read(64 * 1024):+ pass+ except (zstd.ZstdError, EOFError) as error:+ raise ValueError("Invalid compressed Codex rollout.") from error++def _read_rollout_usage(session: RolloutSession,*,@@ -540,8 +607,13 @@ def _read_rollout_usage(total = result.tokenswarnings = result.warningsprevious = _empty_token_usage()+ previous_cache_writes_reported = True+ prefix_unclassified = 0+ prefix_missing_cache: set[str] = set()+ ambiguous_legacy_cache = Falseboundary_reached = Falselegacy_usage = _empty_token_usage()+ completed_legacy_usage = _empty_token_usage()response_usage: dict[str, int] | None = Noneobserved_response_usage = _empty_token_usage()response_ids: set[str] = set()@@ -561,7 +633,7 @@ def _read_rollout_usage(and (completed_turn_id is None or turn_id != completed_turn_id))- with session.path.open("rb") as source:+ with _open_rollout(session.path, verify_end=True) as source:for line_number, raw_line in enumerate(source, start=1):if not raw_line.endswith(b"\n"):warnings.add("rollout_record_incomplete")@@ -623,7 +695,14 @@ def _read_rollout_usage(elif event.get("type") == "event_msg" and payload.get("type") == "token_count":inherited_usage = _token_snapshot(payload)if inherited_usage is not None:- previous = inherited_usage+ missing_cache = _missing_cache_fields(payload)+ baseline = _retain_cache_baseline(previous, inherited_usage, missing_cache)+ if baseline is None:+ warnings.add("token_breakdown_unavailable")+ else:+ previous = baseline+ prefix_unclassified = _uncached_input(baseline)+ prefix_missing_cache = missing_cacheif not boundary_reached:continueif event.get("type") == "event_msg" and payload.get("type") == "task_started":@@ -641,6 +720,11 @@ def _read_rollout_usage(_add_token_usage(total, response_usage if response_usage is not None else legacy_usage)+ if response_usage is None:+ _add_token_usage(completed_legacy_usage, legacy_usage)+ if ambiguous_legacy_cache:+ warnings.add("token_breakdown_unavailable")+ ambiguous_legacy_cache = Falselegacy_usage = _empty_token_usage()response_usage = Noneif payload.get("turn_id") != current_turn_id:@@ -759,25 +843,91 @@ def _read_rollout_usage(if timestamp is None or snapshot is None:warnings.add("token_record_invalid")continue+ reset = snapshot["totalTokens"] < previous["totalTokens"]+ if reset:+ prefix_unclassified = 0+ missing_cache = _missing_cache_fields(payload)+ cache_writes_reported = "cacheWriteInputTokens" not in missing_cache+ baseline = _retain_cache_baseline(previous, snapshot, missing_cache)+ if baseline is None:+ if not past_scan_end(timestamp, current_turn_id):+ warnings.add("token_breakdown_unavailable")+ continue+ if baseline is previous:+ cache_writes_reported = previous_cache_writes_reported and cache_writes_reported+ refines_classification = (+ baseline["inputTokens"] >= previous["inputTokens"]+ and baseline["outputTokens"] >= previous["outputTokens"]+ and baseline["cachedInputTokens"] >= previous["cachedInputTokens"]+ and baseline["cacheWriteInputTokens"] >= previous["cacheWriteInputTokens"]+ and (+ (not previous_cache_writes_reported and cache_writes_reported)+ or baseline["cachedInputTokens"] > previous["cachedInputTokens"]+ or baseline["cacheWriteInputTokens"] > previous["cacheWriteInputTokens"]+ )+ )+ previous_cache_writes_reported = cache_writes_reporteddelta = {- key: value - previous[key] if value >= previous[key] else value+ key: value if reset or value < previous[key] else value - previous[key]for key, value in snapshot.items()}- previous = snapshot+ previous = baselineif past_scan_end(timestamp, current_turn_id):continueif isinstance(current_turn_id, str):measured_turns.add(current_turn_id)if timestamp < started_at:+ prefix_unclassified = _uncached_input(baseline)+ prefix_missing_cache = missing_cachecontinueif completed_turn_id is not None and current_turn_id == completed_turn_id:completed_turn_measured = Trueresult.tokens_updated_at = max(result.tokens_updated_at or timestamp, timestamp)- if delta["totalTokens"] <= 0:+ delta["totalTokens"] = delta["inputTokens"] + delta["outputTokens"]+ if delta["totalTokens"] <= 0 and not refines_classification:continue+ cache_write_capacity = (+ _uncached_input(legacy_usage) + delta["inputTokens"]+ if refines_classification+ else delta["inputTokens"]+ )+ # Late cumulative cache details can classify an earlier legacy turn.+ completed_capacity = (+ _uncached_input(completed_legacy_usage)+ if refines_classification and response_usage is None+ else 0+ )+ if (+ prefix_unclassified > 0+ and refines_classification+ and (+ any(delta[key] > 0 for key in prefix_missing_cache)+ # Even explicit counters can revise earlier input when the+ # newly classified tokens exceed all in-scan capacity.+ or delta["cachedInputTokens"] + delta["cacheWriteInputTokens"]+ > cache_write_capacity + completed_capacity+ )+ ):+ # The newly classified tokens could have occurred before this scan.+ ambiguous_legacy_cache = True+ for key in ("cacheWriteInputTokens", "cachedInputTokens"):+ current = min(delta[key], cache_write_capacity)+ completed = min(delta[key] - current, completed_capacity)+ if completed and ambiguous_legacy_cache:+ warnings.add("token_breakdown_unavailable")+ delta[key] = current+ cache_write_capacity -= current+ completed_capacity -= completed+ completed_legacy_usage[key] += completed+ total[key] += completed+ delta["reasoningOutputTokens"] = min(+ delta["reasoningOutputTokens"], delta["outputTokens"]+ )_add_token_usage(legacy_usage, delta)_add_token_usage(total, response_usage if response_usage is not None else legacy_usage)+ if response_usage is None and ambiguous_legacy_cache:+ warnings.add("token_breakdown_unavailable")if not boundary_reached:warnings.add("thread_ownership_unavailable")elif result.tokens_updated_at is None and not direct_control_session:@@ -848,6 +998,47 @@ def valid_account_rate_limit(value: object) -> bool:return True+def _missing_cache_fields(payload: Mapping[str, Any]) -> set[str]:+ usage = payload["info"]["total_token_usage"]+ missing: set[str] = set()+ if "cached_input_tokens" not in usage:+ missing.add("cachedInputTokens")+ if "cache_write_input_tokens" not in usage and "cache_write_tokens" not in usage:+ missing.add("cacheWriteInputTokens")+ return missing+++def _uncached_input(usage: dict[str, int]) -> int:+ return usage["inputTokens"] - usage["cachedInputTokens"] - usage["cacheWriteInputTokens"]+++def _retain_cache_baseline(+ previous: dict[str, int], snapshot: dict[str, int], missing: set[str]+) -> dict[str, int] | None:+ baseline = snapshot+ if (+ missing+ and snapshot["inputTokens"] >= previous["inputTokens"]+ and snapshot["outputTokens"] >= previous["outputTokens"]+ ):+ baseline = {**snapshot, **{key: previous[key] for key in missing}}+ if (+ baseline["cachedInputTokens"] + baseline["cacheWriteInputTokens"]+ > baseline["inputTokens"]+ ):+ return None+ if (+ baseline["inputTokens"] == previous["inputTokens"]+ and baseline["outputTokens"] == previous["outputTokens"]+ and (+ baseline["cachedInputTokens"] < previous["cachedInputTokens"]+ or baseline["cacheWriteInputTokens"] < previous["cacheWriteInputTokens"]+ )+ ):+ return previous+ return baseline++def _session_parent_thread_id(payload: Mapping[str, Any]) -> str | None:source = payload.get("source")if isinstance(source, dict):diff --git a/plugins/codex-security/shared/workbench-migrations.json b/plugins/codex-security/shared/workbench-migrations.jsonindex 3ad24c4fb..987ff1e61 100644--- a/plugins/codex-security/shared/workbench-migrations.json+++ b/plugins/codex-security/shared/workbench-migrations.json@@ -508,5 +508,14 @@"UPDATE scans SET launch_plugin_version = json_extract(recipe_json, '$.pluginVersion')\nWHERE launch_plugin_version IS NULL AND CASE WHEN json_valid(recipe_json) THEN\n json_type(recipe_json, '$.pluginVersion') = 'text'\n AND trim(json_extract(recipe_json, '$.pluginVersion'), char(9, 10, 11, 12, 13, 32)) <> ''\nEND;","CREATE VIEW scan_lifecycles AS\nSELECT scans.id AS scan_id, json_object(\n 'scanId', scans.id,\n 'mode', CASE WHEN launch_kind = 'import' THEN 'import' ELSE scans.mode END,\n 'startedAt', scans.started_at,\n 'status', CASE WHEN canceled_at IS NOT NULL THEN 'canceled'\n WHEN scans.status = 'complete' THEN 'completed' ELSE scans.status END,\n 'finishedAt', COALESCE(canceled_at, completed_at),\n 'hasReportableFindings', json(CASE\n WHEN scans.status = 'complete' AND canceled_at IS NULL\n THEN (SELECT CASE WHEN reportable_findings_count > 0 THEN 'true' ELSE 'false' END\n FROM scan_progress WHERE scan_id = scans.id) END),\n 'surface', launch_surface,\n 'packageVersion', launch_package_version,\n 'pluginVersion', launch_plugin_version,\n 'mock', json(CASE WHEN launch_kind = 'mock' THEN 'true'\n WHEN launch_kind IS NOT NULL THEN 'false' END)\n) AS snapshot\nFROM scans;"]+ },+ {+ "version": 63,+ "name": "retain unverified Deep Scan worker attempts",+ "statements": [+ "ALTER TABLE deep_scan_runs ADD COLUMN worker_usage_gap INTEGER NOT NULL DEFAULT 0 CHECK (worker_usage_gap IN (0, 1));",+ "UPDATE deep_scan_runs SET worker_usage_gap = 1\nWHERE scan_id IN (\n SELECT w.scan_id FROM deep_scan_workers AS w\n WHERE w.kind IN ('discovery', 'dedup') AND w.attempt > 1\n AND w.started_at IS NOT NULL AND w.sdk_thread_id IS NULL\n AND NOT EXISTS (SELECT 1 FROM deep_scan_worker_threads AS t\n WHERE t.scan_id = w.scan_id AND t.worker_id = w.id)\n);",+ "CREATE TRIGGER retain_unverified_deep_scan_worker_attempt\nAFTER UPDATE OF attempt ON deep_scan_workers\nWHEN NEW.attempt > OLD.attempt AND OLD.started_at IS NOT NULL\n AND OLD.sdk_thread_id IS NULL AND OLD.kind IN ('discovery', 'dedup')\nBEGIN\n UPDATE deep_scan_runs SET worker_usage_gap = 1 WHERE scan_id = OLD.scan_id;\nEND;"+ ]}]diff --git a/plugins/codex-security/tests/test_checkpoint_schema.py b/plugins/codex-security/tests/test_checkpoint_schema.pyindex 5d9121c61..c66456c2d 100644--- a/plugins/codex-security/tests/test_checkpoint_schema.py+++ b/plugins/codex-security/tests/test_checkpoint_schema.py@@ -59,7 +59,8 @@ def test_frozen_checkpoint_head_migration_preserves_scan_state(if legacy_checkpoint and version == 57else (version, name, sql)for version, name, sql in migrations- if version not in omitted_versions+ if version <= 57+ and version not in omitted_versionsand not (legacy_checkpoint and version in (54, 55, 56))and not (legacy_checkpoint in (47, 48, 50, 52, 53) and version in (52, 53))and not (legacy_checkpoint in (47, 48, 50) and version in (50, 51))@@ -120,12 +121,11 @@ def test_frozen_checkpoint_head_migration_preserves_scan_state(migrate(connection, migrations)after = [dict(row) for row in connection.execute("SELECT * FROM scans ORDER BY id")]for original, updated in zip(before, after, strict=True):- retained_heads = updated.pop("retained_checkpoint_heads_json")- assert retained_heads == original.get("retained_checkpoint_heads_json")- original.pop("retained_checkpoint_heads_json", None)- if "source_scopes_json" not in original:- source_scopes = updated.pop("source_scopes_json")- assert source_scopes is None+ # Existing scan values survive the upgrade. Later nullable columns+ # have no launch or recovery metadata to backfill for these rows.+ for column in updated.keys() - original.keys():+ added_value = updated.pop(column)+ assert added_value is Noneassert updated == originalconnection.execute(diff --git a/plugins/codex-security/tests/test_workbench_deep_scan.py b/plugins/codex-security/tests/test_workbench_deep_scan.pyindex 7b44c6bd3..7210c92b7 100644--- a/plugins/codex-security/tests/test_workbench_deep_scan.py+++ b/plugins/codex-security/tests/test_workbench_deep_scan.py@@ -127,6 +127,8 @@ def test_target_admission_reads_one_entry_without_looking_up_its_type(def restore_v53_schema(state_dir: Path) -> None:with sqlite3.connect(state_dir / "workbench.sqlite3") as connection:+ connection.execute("DROP TRIGGER retain_unverified_deep_scan_worker_attempt")+ connection.execute("ALTER TABLE deep_scan_runs DROP COLUMN worker_usage_gap")connection.execute("DROP TRIGGER classify_legacy_scan_recipe")connection.execute("DROP VIEW scan_lifecycles")connection.execute("ALTER TABLE scans DROP COLUMN launch_kind")diff --git a/plugins/codex-security/tests/test_workbench_scan_usage.py b/plugins/codex-security/tests/test_workbench_scan_usage.pyindex 22343b250..bc51ee690 100644--- a/plugins/codex-security/tests/test_workbench_scan_usage.py+++ b/plugins/codex-security/tests/test_workbench_scan_usage.py@@ -923,6 +923,193 @@ def test_completion_includes_cached_and_cache_write_tokens()+ "cache_field", ["cached_input_tokens", "cache_write_input_tokens", "cache_write_tokens"]+)+ ("snapshots", "expected_input", "expected_cache"),+ [+ ([(100, 50), (100, None), (100, 50)], 100, 50),+ ([(100, 100), (200, None), (200, 100)], 200, 100),+ ([(100, 40), (200, None), (300, 60)], 300, 60),+ ([(100, 40), (20, None), (100, 20)], 200, 60),+ ([(100, 40), (200, 20), (300, 30)], 300, 70),+ ([(100, None), (100, 50)], 100, 50),+ ],+ ids=[+ "same-total",+ "increasing",+ "new-writes",+ "epoch-reset",+ "explicit-decrease",+ "initial-omission",+ ],+)+def test_completion_retains_cache_baseline_across_omissions(+ tmp_path: Path,+ cache_field: str,+ snapshots: list[tuple[int, int | None]],+ expected_input: int,+ expected_cache: int,+) -> None:+ fixture = _start_scan(tmp_path)+ counted = fixture.started_at + timedelta(microseconds=1)+ events = []+ is_cache_read = cache_field == "cached_input_tokens"+ for input_tokens, cache_tokens in snapshots:+ event = _token_event(counted, input_tokens, 0)+ reported = event["payload"]["info"]["total_token_usage"]+ reported.pop("cached_input_tokens" if is_cache_read else "cache_write_input_tokens")+ if cache_tokens is not None:+ reported[cache_field] = cache_tokens+ events.append(event)+ parent = _rollout(tmp_path, "scan-parent", events)+ _state_graph(fixture.environment, {"scan-parent": parent}, [])++ usage = _complete_scan(fixture)["scan"]["usage"]++ assert (+ usage.items()+ >= {+ "coverage": "complete",+ "source": "codex_rollout",+ **_counts(+ expected_input,+ expected_cache if is_cache_read else 0,+ 0,+ cache_write_input_tokens=0 if is_cache_read else expected_cache,+ ),+ "threadCount": 1,+ }.items()+ )++[email protected]("recovered", [False, True])+def test_inconsistent_partial_cache_snapshot_cannot_establish_a_baseline(+ scan_usage, tmp_path: Path, recovered: bool+) -> None:+ started = datetime.fromisoformat("2026-01-01T00:00:00+00:00")+ initial = _token_event(started, 100, 0, cached_input_tokens=80)+ partial = _token_event(started, 100, 0)+ partial_usage = partial["payload"]["info"]["total_token_usage"]+ del partial_usage["cached_input_tokens"]+ partial_usage["cache_write_input_tokens"] = 50+ events = [initial, partial]+ if recovered:+ latest = _token_event(started, 140, 0, cached_input_tokens=80)+ latest["payload"]["info"]["total_token_usage"]["cache_write_input_tokens"] = 60+ events.append(latest)+ result = _measure_rollout(+ scan_usage, _rollout(tmp_path, "scan-parent", events), started, started+ )+ assert result.warnings == {"token_breakdown_unavailable"}+ assert result.tokens == _counts(+ 140 if recovered else 100, 80, 0, cache_write_input_tokens=60 if recovered else 0+ )++[email protected]("category", ["cached_input_tokens", "cache_write_input_tokens"])[email protected]("missing", [None, "refined", "other"])[email protected]("new_input", [0, 1000])+def test_late_cache_classification_only_excludes_ambiguous_categories(+ tmp_path: Path, category: str, missing: str | None, new_input: int+) -> None:+ fixture = _start_scan(tmp_path)+ counted = fixture.started_at + timedelta(microseconds=1)+ prefix = _token_event(fixture.started_at - timedelta(seconds=1), 1000, 0)+ owned = _token_event(counted, 2000, 0)+ refined = _token_event(counted, 2000 + new_input, 0)+ if missing is not None:+ other = (+ "cache_write_input_tokens"+ if category == "cached_input_tokens"+ else "cached_input_tokens"+ )+ absent = category if missing == "refined" else other+ for event in (prefix, owned, refined):+ del event["payload"]["info"]["total_token_usage"][absent]+ refined["payload"]["info"]["total_token_usage"][category] = 1000+ _state_graph(+ fixture.environment,+ {+ "scan-parent": _rollout(tmp_path, "scan-parent", [prefix, owned, refined]),+ "child": _rollout(+ tmp_path, "child", [_token_event(counted, 30, 5)], parent_thread_id="scan-parent"+ ),+ },+ [("scan-parent", "child")],+ )+ usage = fixture.command("read-scan-usage", "--thread-id", "scan-parent")+ ambiguous = missing == "refined"+ assert usage["coverage"] == ("partial" if ambiguous else "complete")+ assert usage["totalTokens"] == (35 if ambiguous else 1035 + new_input)+ assert usage["byRole"]["parent"]["threadCount"] == (0 if ambiguous else 1)+ assert usage.get("warnings", []) == (["token_breakdown_unavailable"] if ambiguous else [])++[email protected]("previous_native", [False, True])[email protected]("current_native", [False, True])+def test_legacy_cache_refinement_survives_turn_boundaries(+ scan_usage, tmp_path: Path, previous_native: bool, current_native: bool+) -> None:+ started = datetime.fromisoformat("2026-01-01T00:00:00+00:00")+ initial = _token_event(started, 100, 10)+ initial["payload"]["info"]["total_token_usage"].pop("cache_write_input_tokens")+ refined = _token_event(started, 100, 10, cached_input_tokens=20)+ refined["payload"]["info"]["total_token_usage"]["cache_write_input_tokens"] = 30+ later = _token_event(started, 150, 20, cached_input_tokens=20)+ later["payload"]["info"]["total_token_usage"]["cache_write_input_tokens"] = 30+ events = [+ _event(started, "event_msg", {"type": "task_started", "turn_id": "previous"}),+ initial,+ ]+ if previous_native:+ events.append(+ _response_event(+ started,+ "scan-parent",+ "previous",+ 100,+ 10,+ turn_id="previous",+ cached_input_tokens=7,+ )+ )+ events.extend(+ [+ _event(started, "event_msg", {"type": "task_started", "turn_id": "current"}),+ refined,+ ]+ )+ if current_native:+ events.append(+ _response_event(+ started,+ "scan-parent",+ "current",+ 50,+ 10,+ turn_id="current",+ cached_input_tokens=5,+ )+ )+ events.append(later)+ events.extend(+ _event(started, "event_msg", {"type": "task_complete", "turn_id": turn})+ for turn in ("previous", "current")+ )+ parent = _rollout(tmp_path, "scan-parent", events)+ result = _measure_rollout(scan_usage, parent, started, started)++ assert result.tokens == _counts(+ 150,+ (7 if previous_native else 20) + (5 if current_native else 0),+ 20,+ cache_write_input_tokens=0 if previous_native else 30,+ )+ assert result.warnings == set()++def test_completion_excludes_separately_inherited_worker_snapshots(tmp_path: Path) -> None:fixture = _start_scan(tmp_path)counted = fixture.started_at + timedelta(microseconds=1)@@ -1231,6 +1418,7 @@ def test_completion_counts_deep_worker_retries_and_descendants(tmp_path: Path) -fixture.environment,{"scan-parent": _rollout(tmp_path, "scan-parent", [_token_event(counted, 10, 3)]),+ "comparison": _rollout(tmp_path, "comparison", [_token_event(counted, 50, 5)]),"sdk-worker": _rollout(tmp_path, "sdk-worker", [_token_event(counted, 20, 5)]),"sdk-child": _rollout(tmp_path,@@ -1242,14 +1430,19 @@ def test_completion_counts_deep_worker_retries_and_descendants(tmp_path: Path) -},[("sdk-worker", "sdk-child")],)+ with sqlite3.connect(Path(fixture.environment["CODEX_SQLITE_HOME"]) / "state_5.sqlite") as db:+ db.execute(+ "UPDATE threads SET cwd = ?, created_at = ? WHERE id = 'comparison'",+ (str(fixture.scan_dir / "artifacts" / "deep_discovery"), int(counted.timestamp())),+ )usage = _complete_scan(fixture)["scan"]["usage"]assert (usage.items()>= {"coverage": "complete","source": "codex_rollout",- **_counts(67, 0, 13),- "threadCount": 4,+ **_counts(117, 0, 18),+ "threadCount": 5,}.items())@@ -1498,12 +1691,149 @@ def test_metadata_only_deep_owner_requires_direct_control_originator(}-def test_usage_has_no_separate_workbench_command(workbench_api, monkeypatch, capsys) -> None:- monkeypatch.setattr(sys, "argv", ["workbench_db.py", "get-scan-usage"])- with pytest.raises(SystemExit) as rejected:- workbench_api["parse_args"]("workbench")- assert rejected.value.code == 2- assert "invalid choice: 'get-scan-usage'" in capsys.readouterr().err+def test_budget_keeps_measured_totals_when_a_started_worker_has_no_thread(tmp_path: Path) -> None:+ fixture = _start_scan(tmp_path, mode="deep")+ counted = fixture.started_at + timedelta(microseconds=1)+ fixture.write_parent_rollout([_token_event(counted, 100, 10)])+ artifact = fixture.scan_dir / "artifacts" / "worker"+ artifact.mkdir(parents=True)+ prompt = artifact / "prompt.md"+ prompt.write_text("Review the fixture.\n", encoding="utf-8")+ upsert_deep_worker(+ fixture.state_dir,+ fixture.scan_id,+ str(uuid.uuid4()),+ "discovery",+ "running",+ str(prompt),+ str(artifact),+ "--attempt",+ "1",+ environment=fixture.environment,+ )+ usage = fixture.command("read-scan-usage", "--thread-id", "scan-parent")+ assert usage["coverage"] == "partial"+ assert usage["totalTokens"] == 110+ assert "worker_thread_unavailable" in usage["warnings"]++[email protected]("resume", [False, True])+def test_budget_distinguishes_fresh_retry_from_resumed_worker(tmp_path: Path, resume: bool) -> None:+ fixture = _start_scan(tmp_path, mode="deep")+ counted = fixture.started_at + timedelta(microseconds=1)+ worker = str(uuid.uuid4())+ artifact = fixture.scan_dir / "artifacts" / "worker"+ artifact.mkdir(parents=True)+ prompt = artifact / "prompt.md"+ prompt.write_text("Review the fixture.", encoding="utf-8")+ parent = _rollout(tmp_path, "scan-parent", [_token_event(counted, 10, 0)])+ earlier = _rollout(tmp_path, "earlier", [_token_event(counted, 100, 0)])+ later = _rollout(tmp_path, "later", [_token_event(counted, 5, 0)])+ _state_graph(+ fixture.environment, {"scan-parent": parent, "earlier": earlier, "later": later}, []+ )+ with sqlite3.connect(Path(fixture.environment["CODEX_SQLITE_HOME"]) / "state_5.sqlite") as db:+ db.execute(+ "UPDATE threads SET cwd = ?, created_at = ? WHERE id = 'earlier'",+ (str(artifact), int(counted.timestamp())),+ )++ def running(attempt: str, *thread: str) -> None:+ upsert_deep_worker(+ fixture.state_dir,+ fixture.scan_id,+ worker,+ "discovery",+ "running",+ str(prompt),+ str(artifact),+ "--attempt",+ attempt,+ *thread,+ environment=fixture.environment,+ )++ running("1", "--sdk-thread-id", "earlier")+ running("2", *(["--sdk-thread-id", "earlier"] if resume else []))+ # Repeat an update without the optional ID, as the worker runner does after an error.+ running("2")++ def assert_usage(total: int) -> None:+ usage = fixture.command("read-scan-usage", "--thread-id", "scan-parent")+ assert usage["coverage"] == ("complete" if resume else "partial")+ assert usage["totalTokens"] == total+ assert ("worker_thread_unavailable" in usage.get("warnings", [])) == (not resume)++ assert_usage(110)+ running("3", "--sdk-thread-id", "later")+ assert_usage(115)++[email protected]_platform[email protected]("truncated", [False, True])[email protected]("indexed_archive", [False, True])+def test_budget_counts_compressed_comparison_or_reports_partial_usage(+ tmp_path: Path, truncated: bool, indexed_archive: bool+) -> None:+ try:+ from compression import zstd+ except ImportError:+ zstd = pytest.importorskip("backports.zstd")+ fixture = _start_scan(tmp_path, mode="deep")+ counted = fixture.started_at + timedelta(microseconds=1)+ parent = _rollout(tmp_path, "scan-parent", [_token_event(counted, 100, 10)])+ comparison = _rollout(tmp_path, "comparison", [_token_event(counted, 10, 5)])+ archive = comparison.with_suffix(".jsonl.zst")+ frames = zstd.compress(comparison.read_bytes()) + zstd.compress(b"")+ archive.write_bytes(frames[:-1] if truncated else frames)+ comparison.unlink()+ _state_graph(+ fixture.environment,+ {"scan-parent": parent, "comparison": archive if indexed_archive else comparison},+ [],+ )+ with sqlite3.connect(Path(fixture.environment["CODEX_SQLITE_HOME"]) / "state_5.sqlite") as db:+ db.execute(+ "UPDATE threads SET cwd = ?, created_at = ? WHERE id = 'comparison'",+ (str(fixture.scan_dir / "artifacts" / "deep_discovery"), int(counted.timestamp())),+ )+ usage = fixture.command("read-scan-usage", "--thread-id", "scan-parent")+ assert usage["coverage"] == ("partial" if truncated else "complete")+ assert usage["totalTokens"] == (110 if truncated else 125)++[email protected]("missing_child", [False, True])+def test_budget_usage_includes_final_receipts_and_validation_after_completion(+ tmp_path: Path, missing_child: bool+) -> None:+ fixture = _start_scan(tmp_path)+ stored = _complete_scan(fixture)["scan"]["usage"]+ after = datetime.now(fixture.started_at.tzinfo)+ _state_graph(+ fixture.environment,+ {+ "scan-parent": _rollout(tmp_path, "scan-parent", [_token_event(after, 8, 2)]),+ "validation": _rollout(tmp_path, "validation", [_token_event(after, 40, 10)]),+ "validation-child": (+ tmp_path / "missing.jsonl"+ if missing_child+ else _rollout(+ tmp_path,+ "validation-child",+ [_token_event(after, 20, 5)],+ parent_thread_id="validation",+ )+ ),+ },+ [("validation", "validation-child")],+ )+ usage = fixture.command(+ "read-scan-usage", "--thread-id", "scan-parent", "--validation-thread-id", "validation"+ )+ assert usage["coverage"] == ("partial" if missing_child else "complete")+ assert usage["totalTokens"] == (60 if missing_child else 85)+ assert usage["byRole"]["parent"]["threadCount"] == 2+ assert fixture.command("get-scan")["scan"]["usage"] == stored@pytest.mark.parametrize("native", [False, True])@@ -1995,7 +2325,7 @@ def test_worker_discovery_matches_platform_path_spelling(state_database,["current-worker"],warnings,- worker_directories={directory},+ worker_directories={directory: False},started_at=started,completed_at=started + timedelta(seconds=1),)diff --git a/plugins/codex-security/tests/test_workbench_setup_and_migrations.py b/plugins/codex-security/tests/test_workbench_setup_and_migrations.pyindex 69566b80a..426494965 100644--- a/plugins/codex-security/tests/test_workbench_setup_and_migrations.py+++ b/plugins/codex-security/tests/test_workbench_setup_and_migrations.py@@ -107,6 +107,7 @@ EXPECTED_MIGRATIONS = [(60, "record classification rubric provenance"),(61, "record scan launch attribution"),(62, "project scan lifecycle snapshots"),+ (63, "retain unverified Deep Scan worker attempts"),]diff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex 5652a2193..8e4608cec 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -477,7 +477,8 @@ coordinator has finished.Costs estimate API-equivalent model usage, not your bill or ChatGPT subscriptionallowance. Use `cost.estimatedUsdRange` for reporting. `maxCostUsd` uses theshort-context estimate; in-flight requests can exceed it. Post-scan prompts run-outside that limit. Matching earlier findings can also make model calls.+outside that limit. With a cost limit, completing the scan requires verifiable+usage for the scan and its workers. Matching earlier findings can also make model calls.See [progress and cost](docs/cli.md#progress-and-cost) for accounting and budget callbacks.### Validate an existing findingdiff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.mdindex 589a3fc96..c41b51bcb 100644--- a/sdk/typescript/docs/cli.md+++ b/sdk/typescript/docs/cli.md@@ -1159,7 +1159,14 @@ attempt. Post-scan prompts run after cost tracking and are outside this limit.Automatic history matching gets at most one extra call with a limit; if morework is needed, the scan is preserved and you can run `scans match --all`.-When Deep discovery has finished at a cost stop, the scan returns a sealed+A scan with a cost limit requires complete token usage for its recorded scan,+worker, and custom validation sessions before the SDK returns a completed result.+Verifying compressed `.jsonl.zst` sessions requires Python 3.14 or later, or+`backports.zstd` installed in the selected Python environment.+Missing or unreadable usage fails budget verification. Without a limit, usage+reporting remains best effort.++When Deep discovery has finished at a cost stop and usage is verified, the scan returns a sealedreport and lists unvalidated candidates as follow-up work. Reaching a configuredlimit with a valid finalized report returns `0` by default, or `1` if findingsmeet a configured failure threshold.diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.tsindex 55e226bd4..81ff82efd 100644--- a/sdk/typescript/src/api.ts+++ b/sdk/typescript/src/api.ts@@ -102,6 +102,7 @@ import {} from "./config.js";import {estimateScanCost,+ readScanBudgetUsage,ScanCostTracker,type ScanCost,type ParentProgressSource,@@ -2043,6 +2044,7 @@ export class CodexSecurity {status: "pending" as "pending" | "running" | "complete",};let completionCost: ScanCost | null = null;+ let validationThreadId: string | undefined;let nativeTurnFailure: string | undefined;let scanTurnStatus: "in_progress" | "completed" | "failed" | null = null;let budgetRecovery: {@@ -2281,9 +2283,7 @@ export class CodexSecurity {);const sqliteHome = workerRuntimeConfig["sqlite_home"];const sqliteEnvironment: Record<string, string> =- mode === "deep" && typeof sqliteHome === "string"- ? { CODEX_SQLITE_HOME: sqliteHome }- : {};+ typeof sqliteHome === "string" ? { CODEX_SQLITE_HOME: sqliteHome } : {};const workerSnapshot: JsonObject = {...workerRuntimeConfig,responses_api_metadata: codexSecurityRequestContext(effectiveConfig, {@@ -2457,11 +2457,7 @@ export class CodexSecurity {notifyObserver(options, "onWorkerStatus")(status);};const reportedInaccessibleSessionLogs = new Set<string>();- const reportTrackingError = (error: unknown): void => {- if (options.maxCostUsd !== undefined) {- costAbortController.abort(error);- return;- }+ const warnTrackingError = (error: unknown): void => {if (isRecord(error) &&(error["code"] === "EACCES" || error["code"] === "EPERM") &&@@ -2477,12 +2473,35 @@ export class CodexSecurity {"onWarning",)(`Could not track scan activity: ${errorMessage(error)}`);};+ const reportTrackingError = (error: unknown): void => {+ if (options.maxCostUsd !== undefined) costAbortController.abort(error);+ else warnTrackingError(error);+ };const tracker = new ScanCostTracker({+ onObservationError: warnTrackingError,codexHome: runtime.codexHome,model,repository: repo,scanDirectory: scanDir,maxCostUsd: options.maxCostUsd,+ readBudgetUsage:+ options.maxCostUsd === undefined+ ? undefined+ : (threadId) =>+ readScanBudgetUsage(+ (args) =>+ workbench(+ {+ ...workbenchOptions,+ signal: signal.aborted ? undefined : signal,+ },+ args,+ ),+ scanId,+ threadId,+ validationThreadId,+ directDeepScan,+ ),onUsage:options.onUsage === undefined? undefined@@ -2733,6 +2752,7 @@ export class CodexSecurity {pluginRoot: runtime.plugin.pluginRoot,environment: {...environmentWithGit(git.environment, git),+ CODEX_HOME: runtime.codexHome,...sqliteEnvironment,CODEX_SECURITY_STATE_DIR: stateDirectory,},@@ -2808,7 +2828,7 @@ export class CodexSecurity {});// The registered recipe now owns the private snapshot, including after completion.savedProviderProfile = undefined;- const scanId = registration["scanId"];+ const registeredScanId = registration["scanId"];const resumeThreadId =options.resumeScanId === undefined? undefined@@ -2816,7 +2836,7 @@ export class CodexSecurity {if (options.resumeScanId !== undefined) {const savedRecipe = registration["recipe"];if (- scanId !== options.resumeScanId ||+ registeredScanId !== options.resumeScanId ||!isRecord(savedRecipe) ||savedRecipe["repository"] !== repo ||typeof resumeThreadId !== "string" ||@@ -2837,7 +2857,7 @@ export class CodexSecurity {savedSession.workingDirectory !== scanDir) {throw new CodexSecurityError(- `The original Codex session for scan ${scanId} is unavailable. Restore its session logs in the original Codex Security state directory before resuming.`,+ `The original Codex session for scan ${registeredScanId} is unavailable. Restore its session logs in the original Codex Security state directory before resuming.`,);}if (typeof registration["sealedProducerVersion"] === "string") {@@ -2882,7 +2902,7 @@ export class CodexSecurity {: undefined;const registeredRevision = registration["targetRevision"];if (- typeof scanId !== "string" ||+ typeof registeredScanId !== "string" ||typeof targetId !== "string" ||registration["scanDir"] !== scanDir ||typeof targetKind !== "string" ||@@ -2902,6 +2922,7 @@ export class CodexSecurity {"The Codex Security workbench returned an invalid scan registration.",);}+ const scanId = registeredScanId;const targetRevision =registeredRevision === "unversioned" ? null : registeredRevision;const registeredFileCount = registration["scopeFileCount"];@@ -3375,6 +3396,13 @@ export class CodexSecurity {outputSchema,})).events,+ onEvent: (event) => {+ if (+ event.type === "thread.started" &&+ typeof event["thread_id"] === "string"+ )+ validationThreadId = event["thread_id"];+ },onReconnect: (message, attempts) =>notifyObserver(options, "onReconnect")(...attempts,@@ -3388,6 +3416,13 @@ export class CodexSecurity {"The custom validation turn did not complete.",);budgetAbortController.abort();+ if (turn.threadId === null && maxCostUsd !== undefined) {+ runPostScan = null;+ throw new CodexSecurityError(+ "Could not verify the cost of the custom validation turn.",+ );+ }+ validationThreadId = turn.threadId ?? undefined;tracker.recordUsage(turn.usage, turn.threadId);await tracker.refresh().catch(reportTrackingError);checkOpen();@@ -3398,17 +3433,18 @@ export class CodexSecurity {}budgetAbortController.abort();const snapshot = await tracker.stop(usage).catch((error: unknown) => {- if (options.maxCostUsd !== undefined) throw error;+ if (options.maxCostUsd !== undefined) {+ runPostScan = null;+ throw error;+ }reportTrackingError(error);return { usage, cost: estimateScanCost(model, usage) };});throwIfAborted(signal, scanDir);- if (options.maxCostUsd !== undefined && snapshot.cost === null) {- notifyObserver(- options,- "onWarning",- )(- "Scan completed, but its cost limit could not be verified because model pricing or token usage is unavailable.",+ if (maxCostUsd !== undefined && snapshot.cost === null) {+ runPostScan = null;+ throw new IncompleteScanError(+ "Could not verify the requested scan cost limit because scan-owned token usage is incomplete.",);}completionCost = snapshot.cost;@@ -3724,6 +3760,10 @@ export class CodexSecurity {}if (failure instanceof ScanCostLimitExceededError &&+ snapshot?.cost &&+ snapshot.cost.estimatedUsd > failure.maxCostUsd &&+ (customValidation.status !== "running" ||+ validationThreadId !== undefined) &&budgetRecovery !== null &&budgetRecovery.threadId !== null &&activeScan !== null &&@@ -3737,7 +3777,7 @@ export class CodexSecurity {"--scan-id",activeScan.id,"--cost-json",- JSON.stringify(snapshot?.cost ?? failure.cost),+ JSON.stringify(snapshot.cost),`--message=${failure.message}`,],);@@ -3755,7 +3795,7 @@ export class CodexSecurity {{status: "completed",model: budgetRecovery.model,- usage: snapshot?.usage ?? null,+ usage: snapshot.usage,},budgetRecovery.threadId,scanDir,@@ -3849,7 +3889,9 @@ export class CodexSecurity {: priorTurnFailure === undefined &&explicitlyCanceled(callerCancellation),priorTurnFailure ?? failure,- snapshot?.cost,+ failure instanceof ScanCostLimitExceededError+ ? failure.cost+ : snapshot?.cost,);activeScan = null;} catch {}diff --git a/sdk/typescript/src/cost.ts b/sdk/typescript/src/cost.tsindex 20b58e365..0de6591c4 100644--- a/sdk/typescript/src/cost.ts+++ b/sdk/typescript/src/cost.ts@@ -1,4 +1,6 @@import { parseJson } from "./value.js";+import type { JsonObject } from "./config.js";+import { workbenchArgs } from "./workbench-arguments.js";import { createHash } from "node:crypto";import { open, readdir, stat } from "node:fs/promises";import { join } from "node:path";@@ -30,6 +32,47 @@ import {export { estimateScanCost, formatUsd, type ScanCost } from "./cost-model.js";+export async function readScanBudgetUsage(+ workbench: (args: readonly string[]) => Promise<JsonObject>,+ scanId: string,+ threadId: string,+ validationThreadId?: string,+ requireWorkerUsage = false,+) {+ const result = await workbench(+ workbenchArgs("read-scan-usage", { scanId, threadId, validationThreadId }),+ );+ const counts = {+ input_tokens: result["inputTokens"],+ cached_input_tokens: result["cachedInputTokens"],+ cache_write_input_tokens: result["cacheWriteInputTokens"],+ output_tokens: result["outputTokens"],+ reasoning_output_tokens: result["reasoningOutputTokens"],+ };+ const usage = Object.values(counts).every(Number.isSafeInteger)+ ? tokenUsage(counts)+ : null;+ const roles = result["byRole"];+ const workers = isRecord(roles) ? roles["workers"] : undefined;+ const coverage = result["coverage"];+ if (+ (coverage !== "complete" && coverage !== "partial") ||+ usage === null ||+ usage.total_tokens !== result["totalTokens"]+ )+ return { usage: null, complete: false };++ const hasWorkers =+ isRecord(workers) &&+ typeof workers["threadCount"] === "number" &&+ workers["threadCount"] > 0;+ // The workbench sums known cache writes but does not record which receipts omitted them.+ return {+ usage: { ...usage, cache_write_input_tokens_reported: false },+ complete: coverage === "complete" && (!requireWorkerUsage || hasWorkers),+ };+}+export interface ScanAccountRateLimitWindow {readonly usedPercent: number;readonly windowMinutes: number | null;@@ -244,6 +287,9 @@ interface ScanCostTrackerOptions {repository?: string;scanDirectory?: string;maxCostUsd?: number;+ readBudgetUsage?: (+ threadId: string,+ ) => ReturnType<typeof readScanBudgetUsage>;expectedFilesTotal?: number;/** Incomplete costs are measured subtotals, usable for spending limits only. */onCost?: (cost: Readonly<ScanCost>, complete: boolean) => void;@@ -254,6 +300,7 @@ interface ScanCostTrackerOptions {onSessionEvent?: (event: ScanSessionEvent) => void;onWorkerEvent?: (event: ScanWorkerEvent) => void;onError?: (error: unknown) => void;+ onObservationError?: (error: unknown) => void;}interface ScanCostSnapshot {@@ -316,6 +363,7 @@ function createSessionUsage(observeUsage: boolean) {export class ScanCostTracker {readonly #options: ScanCostTrackerOptions;+ #lastBudgetPoll = -Infinity;readonly #sessions = new Map<string, SessionUsage>();readonly #receipts = new Map<string, ScanTokenUsage | null>();readonly #workers = new Map<string, number>();@@ -2219,7 +2267,7 @@ export class ScanCostTracker {return;}polling = true;- void this.refresh()+ void this.refresh(true).catch((error: unknown) => {this.#options.onError?.(error);})@@ -2236,9 +2284,28 @@ export class ScanCostTracker {poll();}- public async refresh(): Promise<ScanCostSnapshot> {+ public async refresh(polling = false): Promise<ScanCostSnapshot> {const update = this.#pending.then(async () => {- await this.#readSessions();+ const { readBudgetUsage } = this.#options;+ if (readBudgetUsage === undefined) return this.#readSessions();+ if (this.#threadId === null) return;+ if (+ this.#options.onActivity ||+ this.#options.onProgress ||+ this.#options.onWorkerEvent ||+ this.#options.onSessionEvent ||+ this.#options.onUsageObservation+ ) {+ await this.#readSessions().catch((error) =>+ this.#options.onObservationError?.(error),+ );+ }+ // Reading the indexed graph is more expensive than tailing session activity.+ // Always get fresh usage when stopping, even after a recent live poll.+ if (polling && performance.now() - this.#lastBudgetPoll < 1_000) return;+ const measured = await readBudgetUsage(this.#threadId);+ this.#lastBudgetPoll = performance.now();+ this.#updateCost(measured.usage, measured.complete);});this.#pending = update.catch(() => {});await update;@@ -2254,7 +2321,11 @@ export class ScanCostTracker {} finally {this.#observingWorkers = false;}- if (this.#receipts.size > 0 || this.#snapshot.usage !== null)+ if (+ this.#options.readBudgetUsage ||+ this.#receipts.size > 0 ||+ this.#snapshot.usage !== null+ )return this.#snapshot;const cost = estimateScanCost(this.#options.model, fallbackUsage);this.#snapshot = { usage: fallbackUsage ?? null, cost };@@ -2486,6 +2557,11 @@ export class ScanCostTracker {usage = addTokenUsage(usage, value);}if (observeUsage) this.#reportUsageObservation(usages, complete);+ if (this.#options.readBudgetUsage === undefined)+ this.#updateCost(usage, complete);+ }++ #updateCost(usage: ScanTokenUsage | null, complete: boolean): void {if (!complete) this.#snapshot = { usage: null, cost: null };if (usage === null) return;const cost = estimateScanCost(this.#options.model, usage);diff --git a/sdk/typescript/tests-ts/api-usage.test.ts b/sdk/typescript/tests-ts/api-usage.test.tsindex f2c5f15e5..a7f9b9417 100644--- a/sdk/typescript/tests-ts/api-usage.test.ts+++ b/sdk/typescript/tests-ts/api-usage.test.ts@@ -4,17 +4,26 @@ import { appendFile, mkdir } from "node:fs/promises";import { join } from "node:path";import { setImmediate } from "node:timers/promises";import type { ThreadEvent } from "@openai/codex-sdk";-import { ScanCostTracker } from "../src/cost.js";+import { readScanBudgetUsage, ScanCostTracker } from "../src/cost.js";import { ScanCostLimitExceededError } from "../src/errors.js";import { copyCompletedScan } from "./plugin-root.js";import {+ completedCodex,completedEvents,runEvents,scanRuntimeDependencies,} from "./support/api-events.js";-import { mockWorkbench, TestClient } from "./support/api-client.js";+import {+ measuredScanUsage,+ mockWorkbench,+ TestClient,+} from "./support/api-client.js";import { createApiTestFixtures } from "./support/temporary-directories.js";-import { writeSession } from "./support/usage-rollout.js";+import {+ ownedPythonUsage,+ ownedSdkUsage,+ writeSession,+} from "./support/usage-rollout.js";const { temporaryDirectory, cleanup } = createApiTestFixtures();afterEach(cleanup);@@ -81,8 +90,9 @@ test.each([false, true])(parent: "scan-thread",},);+ let measured = raiseLimit ? 900 : 3_000;const parent = await writeSession(codexHome, "scan-thread", {- input_tokens: raiseLimit ? 900 : 3_000,+ input_tokens: measured,output_tokens: 0,});const limitSaved = Promise.withResolvers<void>();@@ -92,6 +102,9 @@ test.each([false, true])(const client = TestClient.withDependencies({...scanRuntimeDependencies(codexHome, scanDir),runWorkbench: async (_options, args, input) => {+ if (args[0] === "read-scan-usage") {+ return { ...measuredScanUsage(measured, 0, 0), coverage: "partial" };+ }if (args[0] === "set-scan-cost-limit") limitSaved.resolve();return mockWorkbench(args, input);},@@ -105,6 +118,7 @@ test.each([false, true])(await limitSaved.promise;// Resume after the caller adopts the saved limit.await setImmediate();+ measured = 3_000;await appendFile(parent,JSON.stringify({@@ -152,3 +166,108 @@ test.each([false, true])(}},);++test.each([false, true])(+ "completes with an unmeasured worker only when no budget was requested (budgeted=%p)",+ async (budgeted) => {+ const root = await temporaryDirectory();+ const repository = join(root, "repository");+ const codexHome = join(root, "codex-home");+ const scanDir = join(root, "scan");+ await mkdir(repository);+ await writeSession(codexHome, "worker", {}, { parent: "thread-1" });+ const commands: string[] = [];+ const client = TestClient.withDependencies({+ ...scanRuntimeDependencies(codexHome, scanDir),+ createCodex: completedCodex(root),+ runWorkbench: async (_options, args, input) => {+ commands.push(args[0]!);+ if (args[0] === "read-scan-usage") {+ expect(args).toEqual([+ "read-scan-usage",+ "--scan-id",+ "scan_example_001",+ "--thread-id",+ "thread-1",+ ]);+ return { coverage: "partial", missingThreadCount: 1 };+ }+ return mockWorkbench(args, input);+ },+ });+ try {+ // The completed parent supplies a receipt; its worker supplies none.+ const run = client.run(repository, budgeted ? { maxCostUsd: 1 } : {});+ if (budgeted) {+ await expect(run).rejects.toThrow(/cost limit|usage/i);+ expect(commands).not.toContain("prepare-scan-completion");+ expect(commands).toContain("fail-scan");+ } else {+ expect((await run).cost).toBeNull();+ }+ expect(commands.includes("complete-scan")).toBe(!budgeted);+ } finally {+ await client.close();+ }+ },+);++test("a direct scan needs measured workers in addition to its control thread", async () => {+ let workerCount = 0;+ const workbench = async () => ({+ ...ownedPythonUsage,+ coverage: "complete",+ byRole: { workers: { threadCount: workerCount } },+ });+ const read = () =>+ readScanBudgetUsage(workbench, "scan", "controller", undefined, true);+ expect((await read()).complete).toBe(false);+ workerCount = 1;+ expect(await read()).toEqual({+ complete: true,+ usage: { ...ownedSdkUsage, cache_write_input_tokens_reported: false },+ });+});++test("a worker-shaped directory alone cannot exhaust a scan budget", async () => {+ const root = await temporaryDirectory();+ const repository = join(root, "repository");+ const scanDir = join(root, "scan");+ const codexHome = join(root, "codex-home");+ await mkdir(repository);+ await writeSession(+ codexHome,+ "thread-1",+ { input_tokens: 10, output_tokens: 3 },+ {+ cwd: scanDir,+ timestamp: "2026-07-26T10:00:00Z",+ },+ );+ await writeSession(+ codexHome,+ "unrelated",+ { input_tokens: 1_000_000, output_tokens: 0 },+ {+ cwd: join(+ scanDir,+ "artifacts",+ "deep_discovery",+ "workers",+ "other",+ "output",+ ),+ timestamp: "2026-07-26T10:00:01Z",+ },+ );+ const client = TestClient.withDependencies({+ ...scanRuntimeDependencies(codexHome, scanDir),+ createCodex: completedCodex(root),+ });+ try {+ const result = await client.run(repository, { maxCostUsd: 1 });+ expect(result.cost).toMatchObject({ inputTokens: 10, outputTokens: 3 });+ } finally {+ await client.close();+ }+});diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.tsindex 1c16f4ea8..7fdfbb4cf 100644--- a/sdk/typescript/tests-ts/api.test.ts+++ b/sdk/typescript/tests-ts/api.test.ts@@ -88,6 +88,7 @@ import {} from "./plugin-root.js";import {EXTERNAL_PROVIDER_CASES,+ measuredScanUsage,mockScanRegistration,mockWorkbench,shellEnvironmentReference,@@ -3861,13 +3862,12 @@ if __name__ == "__main__":["without", false],["with", true],] as const)(- "handles a session-tracking failure %s an explicit cost limit",+ "warns about unreadable activity logs %s an explicit cost limit",async (_description, enforceCostLimit) => {const { root, repository, codexHome, scanDir } = await scanDirectories();await writeFile(join(codexHome, "sessions"), "not a directory");const commands: string[] = [];const warnings: string[] = [];- let savedFailure: string | undefined;const client = TestClient.withDependencies({...scanRuntimeDependencies(codexHome, scanDir),runWorkbench: async (@@ -3876,7 +3876,6 @@ if __name__ == "__main__":input?: string,): Promise<JsonObject> => {commands.push(args[0]!);- if (args[0] === "fail-scan") savedFailure = args[3];return mockWorkbench(args, input);},createCodex: completedCodex(root),@@ -3887,18 +3886,13 @@ if __name__ == "__main__":onActivity: () => {},onWarning: (warning) => warnings.push(warning),});- if (enforceCostLimit) {- await expect(scan).rejects.toThrow("interrupted");- expect(commands).toContain("fail-scan");- expect(savedFailure).toContain("sessions");- expect(commands).not.toContain("cancel-scan");- } else {- await expect(scan).resolves.toMatchObject({ threadId: "thread-1" });- expect(warnings).toContainEqual(- expect.stringContaining("Could not track scan activity:"),- );- expect(commands).toContain("complete-scan");- }+ await expect(scan).resolves.toMatchObject({ threadId: "thread-1" });+ expect(warnings).toContainEqual(+ expect.stringContaining("Could not track scan activity:"),+ );+ expect(commands.includes("read-scan-usage")).toBe(enforceCostLimit);+ expect(commands).toContain("complete-scan");+ expect(commands).not.toContain("cancel-scan");await client.close();},);@@ -14369,7 +14363,7 @@ if __name__ == "__main__":}});const prices = [- { model: "gpt-6-astra", min: 0.000232, max: 0.000389 },+ { model: "gpt-6-astra", min: 0.000232, max: 0.000429 },{ model: "gpt-5.6-cyber", min: 0.0003275, max: null },];test.each(prices)("tracks live and saved $model costs", async (price) => {@@ -14415,7 +14409,7 @@ if __name__ == "__main__":estimatedUsdRange: { min, max, context: "unknown" },pricing: { serviceTier: "standard", context: "short" },});- expect([result.cost]).toEqual(costs);+ expect(result.cost).toEqual(costs.at(-1)!);const completion = commands.find((args) => args[0] === "complete-scan");expect(completion).toBeDefined();@@ -14555,6 +14549,8 @@ if __name__ == "__main__":resumeThread: () => thread,}),runWorkbench: async (_options, args, input): Promise<JsonObject> => {+ if (args[0] === "read-scan-usage")+ return measuredScanUsage(2_000, 0, 0);if (args[0] === "get-cli-scan-resume")return {scanId,@@ -14790,6 +14786,7 @@ if __name__ == "__main__":{...scanRuntimeDependencies(codexHome, scanDir),prepareRuntime: async () => prepared,+ runWorkbench: recordingWorkbench([], measuredScanUsage(900, 0, 0)),createCodex: codexFactory(async (_input: string, { signal }: { signal: AbortSignal }) => {scanSignal = signal;@@ -14900,6 +14897,7 @@ if __name__ == "__main__":const secondApproval = new Promise<void>((resolve) =>approvals.set(0.016, resolve),);+ let measured = 0;const requests: number[] = [];const commands: Array<readonly string[]> = [];const startThread = mock(() => {@@ -14918,9 +14916,12 @@ if __name__ == "__main__":{ input_tokens: 100, output_tokens: 0 },{ parent: "scan-thread", parentField: "parent_thread_id" },);+ measured = 900;await firstApproval;await appendUsage(path, 1_700);+ measured = 1_800;await secondApproval;+ measured = 2_600;await copyCompletedScan(root);yield {type: "turn.completed",@@ -14940,16 +14941,19 @@ if __name__ == "__main__":let budgetSignal: AbortSignal | undefined;const client = TestClient.withDependencies({...scanRuntimeDependencies(codexHome, scanDir),- runWorkbench: recordingWorkbench(commands),+ runWorkbench: recordingWorkbench(commands, () =>+ measuredScanUsage(measured, 0, 0),+ ),createCodex: () => ({startThread,}),});- const keepAlive = setTimeout(() => {}, 10_000);+ const guard = new AbortController();+ const guardTimer = setTimeout(() => guard.abort(), 15_000);try {const result = await client.run(repository, {maxCostUsd: 0.004,- signal: AbortSignal.timeout(5_000),+ signal: guard.signal,onBudgetApproaching: ({ maxCostUsd, signal }) => {requests.push(maxCostUsd);budgetSignal = signal;@@ -14973,7 +14977,7 @@ if __name__ == "__main__":expect(commands.some(([command]) => command === "fail-scan")).toBe(false);expect(budgetSignal?.aborted).toBe(true);} finally {- clearTimeout(keepAlive);+ clearTimeout(guardTimer);await client.close();}});@@ -14998,6 +15002,7 @@ if __name__ == "__main__":const controller = new AbortController();const commands: Array<readonly string[]> = [];const warnings: string[] = [];+ let measured = 900;let requestCount = 0;const onCost = mock((cost: ScanCost, _limit: number | undefined) => {if (cost.inputTokens === 950) nextCost.resolve();@@ -15007,6 +15012,8 @@ if __name__ == "__main__":...scanRuntimeDependencies(codexHome, scanDir),runWorkbench: async (_options, args, input) => {commands.push(args);+ if (args[0] === "read-scan-usage")+ return measuredScanUsage(measured, 0, 0);if (scenario === "save-failed" && args[0] === "set-scan-cost-limit")throw new Error("Synthetic save failure");if (scenario === "saving" && args[0] === "set-scan-cost-limit")@@ -15037,10 +15044,15 @@ if __name__ == "__main__":return;}await appendUsage(path, 950);+ measured = 950;await nextCost.promise;if (scenario === "canceled") controller.abort();- else await appendUsage(path, 1_200);+ else {+ measured = 1_200;+ await appendUsage(path, 1_200);+ }await (signal.aborted ? undefined : once(signal, "abort"));+ measured = 2_000;await appendUsage(path, 2_000);throw new DOMException("aborted", "AbortError");}@@ -15146,7 +15158,10 @@ if __name__ == "__main__":})!;const client = TestClient.withDependencies({...scanRuntimeDependencies(codexHome, scanDir),- runWorkbench: recordingWorkbench(commands),+ runWorkbench: recordingWorkbench(+ commands,+ measuredScanUsage(1_250, 200, 30),+ ),createCodex: codexFactory(runStreamed),});@@ -15184,8 +15199,12 @@ if __name__ == "__main__":"--thread-id","scan-thread",]);- expect(commands[3]).toEqual(["get-scan", "--scan-id", "scan_example_001"]);- expect(commands[4]).toEqual([+ expect(commands.at(-2)).toEqual([+ "get-scan",+ "--scan-id",+ "scan_example_001",+ ]);+ expect(commands.at(-1)).toEqual(["fail-scan","--scan-id","scan_example_001",@@ -15256,6 +15275,8 @@ if __name__ == "__main__":return { ...mockWorkbench(args, input), lifecycle: registration };}if (args[0] === "fail-scan") return { scan: { lifecycle: terminal } };+ if (args[0] === "read-scan-usage")+ return measuredScanUsage(1_250, 200, 30);if (args[0] !== "complete-budget-exhausted-scan") {return mockWorkbench(args, input);}@@ -15371,14 +15392,13 @@ if __name__ == "__main__":},);- test("saves a budgeted scan with a warning when token usage is unavailable", async () => {+ test("fails a budgeted scan before sealing when token usage is unavailable", async () => {const { root, repository, codexHome, scanDir } = await scanDirectories();- const warnings = mock((_warning: string) => {});const commands: Array<readonly string[]> = [];let threads = 0;const client = TestClient.withDependencies({...scanRuntimeDependencies(codexHome, scanDir),- runWorkbench: recordingWorkbench(commands),+ runWorkbench: recordingWorkbench(commands, { coverage: "unavailable" }),createCodex: (options: CodexOptions) => ({startThread(threadOptions: Parameters<Codex["startThread"]>[0]) {threads++;@@ -15402,26 +15422,22 @@ if __name__ == "__main__":}),});- const result = await client.run(repository, {- maxCostUsd: 1,- ownerSuggestions: true,- onWarning: warnings,- });- expect(result.threadId).toBe("scan-thread");- expect(result.cost).toBeNull();+ await expect(+ client.run(repository, { maxCostUsd: 1, ownerSuggestions: true }),+ ).rejects.toThrow(/could not verify.*cost limit/i);expect(threads).toBe(1);- expect(warnings.mock.calls.map(([value]) => value)).toContain(- "Scan completed, but its cost limit could not be verified because model pricing or token usage is unavailable.",- );- expect(commands.map(([command]) => command)).toEqual([+ expect(commands.some(([name]) => name === "read-scan-usage")).toBe(true);+ expect(+ commands+ .map(([name]) => name)+ .filter((name) => name !== "read-scan-usage"),+ ).toEqual(["register-cli-scan","get-scan-feedback","set-scan-thread",- "prepare-scan-completion",- "complete-scan",- "list-global-findings",+ "get-scan",+ "fail-scan",]);- expect(commands.some((args) => args[0] === "fail-scan")).toBe(false);await client.close();});@@ -18242,13 +18258,18 @@ setInterval(() => {}, 1000);}, 30_000);});-function recordingWorkbench(commands: Array<readonly string[]>) {+function recordingWorkbench(+ commands: Array<readonly string[]>,+ usage?: JsonObject | (() => JsonObject),+) {return async (_options: unknown,args: readonly string[],input?: string,): Promise<JsonObject> => {commands.push(args);+ if (usage && args[0] === "read-scan-usage")+ return typeof usage === "function" ? usage() : usage;return mockWorkbench(args, input);};}diff --git a/sdk/typescript/tests-ts/cost.test.ts b/sdk/typescript/tests-ts/cost.test.tsindex 0f80fc295..aaf880f1d 100644--- a/sdk/typescript/tests-ts/cost.test.ts+++ b/sdk/typescript/tests-ts/cost.test.ts@@ -61,6 +61,34 @@ async function waitFor(check: () => boolean): Promise<void> {afterEach(cleanup);+test("a partial owned subtotal includes spending absent from local session logs", async () => {+ const home = await codexHome();+ const observed: Array<[number, boolean]> = [];+ let complete = false;+ const tracker = new ScanCostTracker({+ codexHome: home,+ model: "gpt-5.6-sol",+ maxCostUsd: 1,+ readBudgetUsage: async () => ({+ usage: { ...ownedSdkUsage, cache_write_input_tokens_reported: false },+ complete,+ }),+ onCost: (cost, coverage) => observed.push([cost.inputTokens, coverage]),+ });+ tracker.start("primary");+ try {+ await tracker.refresh();+ expect(observed).toEqual([[ownedSdkUsage.input_tokens, false]]);+ complete = true;+ // The SDK's parent receipt omits the detached worker's usage.+ const final = await tracker.stop({ input_tokens: 1, output_tokens: 1 });+ expect(final.cost?.inputTokens).toBe(ownedSdkUsage.input_tokens);+ expect(observed.at(-1)).toEqual([ownedSdkUsage.input_tokens, true]);+ } finally {+ await tracker.stop();+ }+});+let costModuleBundle: Promise<string> | undefined;function bundledCostModule(): Promise<string> {costModuleBundle ??= Bun.build({diff --git a/sdk/typescript/tests-ts/support/api-client.ts b/sdk/typescript/tests-ts/support/api-client.tsindex 30586a6ad..d67c080f4 100644--- a/sdk/typescript/tests-ts/support/api-client.ts+++ b/sdk/typescript/tests-ts/support/api-client.ts@@ -125,6 +125,24 @@ export function mockScanRegistration(};}+export function measuredScanUsage(+ inputTokens: number,+ cachedInputTokens: number,+ outputTokens: number,+ reasoningOutputTokens = 0,+): JsonObject {+ return {+ coverage: "complete",+ inputTokens,+ cachedInputTokens,+ cacheWriteInputTokens: 0,+ outputTokens,+ reasoningOutputTokens,+ totalTokens: inputTokens + outputTokens,+ byRole: { workers: { threadCount: 0 } },+ };+}+export function mockWorkbench(args: readonly string[],input?: string,@@ -132,6 +150,7 @@ export function mockWorkbench(if (args[0] === "register-cli-scan") {return mockScanRegistration(args, input);}+ if (args[0] === "read-scan-usage") return measuredScanUsage(10, 2, 3, 1);if (args[0] === "get-scan-feedback") {return {scanId: "scan_example_001",