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: label incomplete scan usage and show measurement times (#1640)
ianw-oai03c7359e153c
diff --git a/plugins/codex-security/references/final-report.md b/plugins/codex-security/references/final-report.mdindex 7cc973d3d..b513fa918 100644--- a/plugins/codex-security/references/final-report.md+++ b/plugins/codex-security/references/final-report.md@@ -30,7 +30,11 @@ During a host-backed scan, checkpoint saved findings and pending candidates withOn a confirmed failure or explicit cancellation, the workbench preserves saved results without marking the scan successful. Report validated findings separately from pending candidates and describe scope limitations and remaining work. Use the retained report and exports; do not start additional model work after cancellation or replace saved results with a no-findings response.-After `complete_codex_security_scan` succeeds, include its returned `usage.totalTokens`, `usage.inputTokens`, and `usage.cachedInputTokens` only when `usage.coverage` is `complete`. When `usage.completion.finalized` is `false`, leave the token total to the host: it finalizes usage after this turn ends, including the final response. Do not quote the preliminary count as a final total or an "at least" estimate. For other partial or unavailable measurements, say that the full token count is unavailable rather than reporting zero or estimating a cost. Token usage is workbench metadata, not a reason to modify sealed scan artifacts or the deterministic report.+After `complete_codex_security_scan` succeeds, report its latest `usage`. When `usage.completion.finalized` is `false`, leave the token total to the host: it finalizes usage after this turn ends, including the final response. Do not quote that preliminary count as a final total or an "at least" estimate. Otherwise, report total tokens, input tokens (including cached input), and cached input tokens. Label partial coverage as "at least X tokens; some usage unavailable" and explain its warnings. If usage is unavailable, say so instead of reporting zero. Retain any separate cost estimate.++Include the parent/worker split when `byRole` is present. Use `window` and `tokensUpdatedAt` to explain the measured period. For account allowance, use the latest `accountRateLimits` entry for each limit and quote its `observedAt`. These account-wide readings can include other work. Use window duration to identify weekly limits, not the primary/secondary label. Empty readings or null windows mean allowance was not observed. Saved readings are historical. This metadata provides no conversion between tokens, estimated API cost, and subscription allowance.++Token usage is workbench metadata. Do not modify sealed scan artifacts or the deterministic report to add it.Before workbench-owned Standard or workbench-backed diff completion, require `record_codex_security_scan_draft` to succeed. Before Deep completion, require the coordinator to return the parent scan's already-authored canonical manifest; do not submit another draft or rerun worker phases. Explicitly SDK-owned workflows verify their canonical JSON before the SDK finalizes it. Completion validates and seals existing canonical artifacts and generates `report.md`; it does not create missing artifacts or run skipped scan phases.diff --git a/plugins/codex-security/scripts/workbench_db.py b/plugins/codex-security/scripts/workbench_db.pyindex 2548ed7b4..1a741c885 100644--- a/plugins/codex-security/scripts/workbench_db.py+++ b/plugins/codex-security/scripts/workbench_db.py@@ -1639,13 +1639,15 @@ def complete_scan_locked(context["targetWarnings"] = target_warningsreturn context- if cost_json is None:- measured_usage = scan_usage.collect_scan_usage(+ cost_fields = scan_usage.stored_scan_cost_fields(cost_json)+ if "usage" not in cost_fields:+ cost_fields["usage"] = scan_usage.collect_scan_usage(connection,scan,thread_id=thread_id,completed_at=completion_timestamp,)+ measured_usage = cost_fields["usage"]if thread_id is not None and turn_id is not None:measured_usage["completion"] = {"threadId": thread_id,@@ -1654,11 +1656,10 @@ def complete_scan_locked(}if measured_usage["coverage"] == "complete":measured_usage["coverage"] = "partial"- measured_usage["warnings"] = [- *measured_usage.get("warnings", []),- "turn_in_progress",- ]- cost_json = parse_scan_cost(scan_usage.measured_scan_cost_json(measured_usage))+ measured_usage["warnings"] = sorted(+ {*measured_usage.get("warnings", []), "turn_in_progress"}+ )+ cost_json = parse_scan_cost(json.dumps(cost_fields))connection.execute("BEGIN IMMEDIATE")with connection:timestamp = manifest["scan"]["completedAt"]diff --git a/plugins/codex-security/scripts/workbench_scan_usage.py b/plugins/codex-security/scripts/workbench_scan_usage.pyindex e46a52cac..bec4a8572 100644--- a/plugins/codex-security/scripts/workbench_scan_usage.py+++ b/plugins/codex-security/scripts/workbench_scan_usage.py@@ -4,6 +4,7 @@ from __future__ import annotationsimport argparseimport json+import mathimport osimport reimport sqlite3@@ -34,6 +35,14 @@ class RolloutSession:path: Path+@dataclass+class RolloutUsage:+ tokens: dict[str, int]+ warnings: set[str]+ tokens_updated_at: datetime | None+ rate_limits: dict[str, dict[str, Any]]++def stored_scan_cost_fields(value: str | None) -> dict[str, Any]:"""Project measured usage without changing the existing legacy cost contract."""@@ -50,12 +59,6 @@ def stored_scan_cost_fields(value: str | None) -> dict[str, Any]:}-def measured_scan_cost_json(usage: Mapping[str, Any]) -> str:- """Keep usage in the already-migrated scans.cost_json column."""-- return json.dumps({"usage": dict(usage)}, separators=(",", ":"), allow_nan=False)--def reconcile_completed_scan_cost(connection: sqlite3.Connection,scan: sqlite3.Row,@@ -86,9 +89,10 @@ def collect_scan_usage(completed_at: str | None = None,completed_turn_id: str | None = None,) -> dict[str, Any]:- """Count only complete, attributable rollout events inside this scan's window."""+ """Count attributable receipts and flag observable gaps inside the scan window."""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 not roots and not worker_directories:return _unavailable_usage("scan_thread_unavailable")@@ -98,7 +102,8 @@ def collect_scan_usage(return _unavailable_usage("codex_state_unavailable")started_at = _timestamp(scan["started_at"])- stopped_at = _timestamp(completed_at or scan["completed_at"])+ observed_at = datetime.now(timezone.utc)+ stopped_at = _timestamp(completed_at or scan["completed_at"]) or observed_atif started_at is None:return _unavailable_usage("scan_window_unavailable")@@ -118,7 +123,9 @@ def collect_scan_usage(if not sessions:return _unavailable_usage("scan_thread_unavailable", warnings=warnings)- total = _empty_token_usage()+ by_role = {role: {**_empty_token_usage(), "threadCount": 0} for role in ("parent", "workers")}+ rate_limits: dict[str, dict[str, Any]] = {}+ tokens_updated_at = Noneaccepted_thread_ids: set[str] = set()excluded_thread_ids: set[str] = set()for session in sessions:@@ -133,7 +140,7 @@ def collect_scan_usage(warnings.add("thread_lineage_incomplete")continuetry:- session_usage, session_warnings = _read_rollout_usage(+ usage = _read_rollout_usage(session,started_at=started_at,completed_at=stopped_at,@@ -143,27 +150,51 @@ def collect_scan_usage(missing_thread_ids.add(session.thread_id)warnings.add("rollout_unavailable")continue- if "thread_outside_scan_window" in session_warnings:+ if "thread_outside_scan_window" in usage.warnings:excluded_thread_ids.add(session.thread_id)continue- warnings.update(session_warnings)- if "thread_identity_mismatch" in session_warnings or (- "thread_ownership_unavailable" in session_warnings+ warnings.update(usage.warnings)+ if "thread_identity_mismatch" in usage.warnings or (+ "thread_ownership_unavailable" in usage.warnings):missing_thread_ids.add(session.thread_id)continueaccepted_thread_ids.add(session.thread_id)- _add_token_usage(total, session_usage)+ role = by_role["parent" if session.thread_id in parent_ids else "workers"]+ _add_token_usage(role, usage.tokens)+ role["threadCount"] += 1+ if usage.tokens_updated_at is not None:+ tokens_updated_at = max(+ tokens_updated_at or usage.tokens_updated_at, usage.tokens_updated_at+ )+ for key, snapshot in usage.rate_limits.items():+ if key not in rate_limits or snapshot["observedAt"] > rate_limits[key]["observedAt"]:+ rate_limits[key] = snapshotif not accepted_thread_ids:return _unavailable_usage("scan_thread_unavailable", warnings=warnings)+ if any(+ usage["cachedInputTokens"] + usage["cacheWriteInputTokens"] > usage["inputTokens"]+ or usage["totalTokens"] != usage["inputTokens"] + usage["outputTokens"]+ for usage in by_role.values()+ ):+ return _unavailable_usage("token_breakdown_unavailable", warnings=warnings)++ if completed_turn_id is not None and tokens_updated_at is not None:+ stopped_at = max(stopped_at, tokens_updated_at)result: dict[str, Any] = {"coverage": "partial" if missing_thread_ids or warnings else "complete","source": "codex_rollout",- **total,+ **{key: sum(role[key] for role in by_role.values()) for key in TOKEN_FIELDS.values()},"threadCount": len(accepted_thread_ids),+ "byRole": by_role,+ "window": {"startedAt": started_at.isoformat(), "endedAt": stopped_at.isoformat()},+ "observedAt": observed_at.isoformat(),+ "accountRateLimits": [rate_limits[key] for key in sorted(rate_limits)],}+ if tokens_updated_at is not None:+ result["tokensUpdatedAt"] = tokens_updated_at.isoformat()if missing_thread_ids:result["missingThreadCount"] = len(missing_thread_ids)if warnings:@@ -177,6 +208,7 @@ def _scan_root_thread_ids(supplied_thread_id: str | None,*,include_owner_threads: bool = True,+ include_workers: bool = True,) -> list[str]:candidates: list[str | None] = [supplied_thread_id]if include_owner_threads:@@ -190,7 +222,7 @@ def _scan_root_thread_ids().fetchone()if workspace is not None:candidates.append(workspace["thread_id"])- if scan["mode"] == "deep":+ if include_workers and scan["mode"] == "deep":candidates.extend(row["sdk_thread_id"]for row in connection.execute(@@ -440,9 +472,10 @@ def _read_rollout_usage(started_at: datetime,completed_at: datetime | None,completed_turn_id: str | None = None,-) -> tuple[dict[str, int], set[str]]:- total = _empty_token_usage()- warnings: set[str] = set()+) -> RolloutUsage:+ result = RolloutUsage(_empty_token_usage(), set(), None, {})+ total = result.tokens+ warnings = result.warningsprevious = _empty_token_usage()boundary_reached = Falselegacy_usage = _empty_token_usage()@@ -451,6 +484,10 @@ def _read_rollout_usage(response_ids: set[str] = set()current_turn_id: str | None = Nonecompleted_turn_measured = False+ started_turns: set[str] = set()+ open_turns: set[str] = set()+ closed_turns: set[str] = set()+ measured_turns: set[str] = set()with session.path.open("rb") as source:for line_number, raw_line in enumerate(source, start=1):@@ -473,16 +510,16 @@ def _read_rollout_usage(if line_number == 1:if event.get("type") != "session_meta" or not isinstance(payload, dict):warnings.add("thread_identity_mismatch")- return total, warnings+ return resultrecorded_id = payload.get("id") or payload.get("session_id")if recorded_id != session.thread_id:warnings.add("thread_identity_mismatch")- return total, warnings+ return resultrecorded_parent = _session_parent_thread_id(payload)if session.parent_thread_id is not None:if recorded_parent != session.parent_thread_id:warnings.add("thread_identity_mismatch")- return total, warnings+ return resultboundary_reached = (session.parent_thread_id is Noneand not recorded_parent@@ -497,21 +534,21 @@ def _read_rollout_usage(task_started_at = _timestamp(event.get("timestamp"))if task_started_at is None:warnings.add("thread_ownership_unavailable")- return total, warnings+ return resultif task_started_at < started_at or (completed_at is not Noneand task_started_at > completed_atand payload.get("turn_id") != completed_turn_id):warnings.add("thread_outside_scan_window")- return total, warnings+ return resultboundary_reached = True- current_turn_id = payload.get("turn_id")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- continue+ if not boundary_reached:+ continueif event.get("type") == "event_msg" and payload.get("type") == "task_started":if (completed_turn_id is not None@@ -527,7 +564,41 @@ def _read_rollout_usage(if payload.get("turn_id") != current_turn_id:observed_response_usage = _empty_token_usage()current_turn_id = payload.get("turn_id")+ timestamp = _timestamp(event.get("timestamp"))+ if not isinstance(current_turn_id, str) or not current_turn_id or timestamp is None:+ warnings.add("turn_record_invalid")+ elif (+ completed_at is None+ or timestamp <= completed_at+ or current_turn_id == completed_turn_id+ ):+ started_turns.add(current_turn_id)+ open_turns.add(current_turn_id)continue+ if event.get("type") == "event_msg" and payload.get("type") in {+ "task_complete",+ "turn_aborted",+ }:+ timestamp = _timestamp(event.get("timestamp"))+ terminal_turn_id = payload.get("turn_id") or current_turn_id+ if (+ not isinstance(terminal_turn_id, str)+ or not terminal_turn_id+ or timestamp is None+ ):+ warnings.add("turn_record_invalid")+ elif (+ completed_at is None+ or timestamp <= completed_at+ or terminal_turn_id == completed_turn_id+ ):+ open_turns.discard(terminal_turn_id)+ if timestamp >= started_at:+ if terminal_turn_id in started_turns:+ closed_turns.add(terminal_turn_id)+ if payload.get("type") == "turn_aborted":+ # Later successful work does not recover interrupted request usage.+ warnings.add("turn_interrupted")if (completed_turn_id is not Noneand event.get("type") == "event_msg"@@ -576,11 +647,16 @@ def _read_rollout_usage(response_usage = _empty_token_usage()if current_turn_id is None:current_turn_id = payload.get("turn_id")+ if isinstance(current_turn_id, str):+ open_turns.add(current_turn_id)if response_id in response_ids:continueresponse_ids.add(response_id)_add_token_usage(observed_response_usage, usage)turn_usage = _usage_counts(payload.get("turn_token_usage"))+ receipt_turn_id = payload.get("turn_id")+ if isinstance(receipt_turn_id, str):+ measured_turns.add(receipt_turn_id)if timestamp < started_at:if turn_usage is not None:observed_response_usage = turn_usage@@ -591,10 +667,30 @@ def _read_rollout_usage(turn_usage[key] > observed_response_usage[key] for key in TOKEN_FIELDS.values()):warnings.add("token_record_incomplete")+ result.tokens_updated_at = max(result.tokens_updated_at or timestamp, timestamp)_add_token_usage(response_usage, usage)continueif event.get("type") != "event_msg" or payload.get("type") != "token_count":continue+ timestamp = _timestamp(event.get("timestamp"))+ in_window = (+ timestamp is not None+ and timestamp >= started_at+ and (+ completed_at is None+ or timestamp <= completed_at+ or (completed_turn_id is not None and current_turn_id == completed_turn_id)+ )+ )+ if in_window:+ rate_limits = _rate_limit_snapshot(payload.get("rate_limits"), timestamp)+ if rate_limits is not None:+ key = rate_limits["limitId"]+ if (+ key not in result.rate_limits+ or rate_limits["observedAt"] >= result.rate_limits[key]["observedAt"]+ ):+ result.rate_limits[key] = rate_limitsif "info" in payload and payload["info"] is None:continuetimestamp = _timestamp(event.get("timestamp"))@@ -607,15 +703,18 @@ def _read_rollout_usage(for key, value in snapshot.items()}previous = snapshot- if timestamp < started_at:- continueis_completion_turn = (completed_turn_id is not None and current_turn_id == completed_turn_id)if completed_at is not None and timestamp > completed_at and not is_completion_turn:continue+ if isinstance(current_turn_id, str):+ measured_turns.add(current_turn_id)+ if timestamp < started_at:+ continueif is_completion_turn:completed_turn_measured = True+ result.tokens_updated_at = max(result.tokens_updated_at or timestamp, timestamp)if delta["totalTokens"] <= 0:continue_add_token_usage(legacy_usage, delta)@@ -623,9 +722,70 @@ def _read_rollout_usage(_add_token_usage(total, response_usage if response_usage is not None else legacy_usage)if not boundary_reached:warnings.add("thread_ownership_unavailable")+ if completed_turn_id is not None:+ open_turns.discard(completed_turn_id)+ if open_turns:+ warnings.add("turn_in_progress")+ if boundary_reached and result.tokens_updated_at is None:+ warnings.add("token_record_missing")+ if closed_turns - measured_turns:+ warnings.add("token_record_missing")if completed_turn_id is not None and not completed_turn_measured:warnings.add("completion_turn_unavailable")- return total, warnings+ return result+++def _rate_limit_snapshot(value: object, timestamp: datetime) -> dict[str, Any] | None:+ if not isinstance(value, dict):+ return None+ result: dict[str, Any] = {+ "limitId": value.get("limit_id") or "codex",+ "observedAt": timestamp.isoformat(),+ }+ for name in ("primary", "secondary"):+ window = value.get(name)+ if window is None:+ result[name] = None+ continue+ if not isinstance(window, dict):+ return None+ result[name] = {+ "usedPercent": window.get("used_percent"),+ "windowMinutes": window.get("window_minutes"),+ "resetsAt": window.get("resets_at"),+ }+ return result if valid_account_rate_limit(result) else None+++def valid_account_rate_limit(value: object) -> bool:+ if not isinstance(value, dict) or set(value) != {+ "limitId",+ "observedAt",+ "primary",+ "secondary",+ }:+ return False+ if not isinstance(value["limitId"], str) or _timestamp(value["observedAt"]) is None:+ return False+ for name in ("primary", "secondary"):+ window = value[name]+ if window is None:+ continue+ if not isinstance(window, dict) or set(window) != {+ "usedPercent",+ "windowMinutes",+ "resetsAt",+ }:+ return False+ percent = window["usedPercent"]+ if type(percent) not in (int, float) or not math.isfinite(percent):+ return False+ if any(+ window[key] is not None and type(window[key]) is not int+ for key in ("windowMinutes", "resetsAt")+ ):+ return False+ return Truedef _session_parent_thread_id(payload: Mapping[str, Any]) -> str | None:diff --git a/plugins/codex-security/scripts/workbench_validation.py b/plugins/codex-security/scripts/workbench_validation.pyindex 6ca8889a7..e210a58a5 100644--- a/plugins/codex-security/scripts/workbench_validation.py+++ b/plugins/codex-security/scripts/workbench_validation.py@@ -16,10 +16,11 @@ from typing import Any# Some plugin hosts launch Python with safe-path isolation enabled.sys.path.insert(0, str(Path(__file__).resolve().parent))import finalize_scan_contract as finalizer-from workbench_scan_usage import TOKEN_FIELDS+from workbench_scan_usage import TOKEN_FIELDS, valid_account_rate_limitfrom workbench_scan_usage import (_reject_nonstandard_json_number as reject_nonstandard_json_number,)+from workbench_scan_usage import _timestamp as usage_timestampreject_non_finite_json = finalizer._reject_non_finite_json@@ -128,6 +129,11 @@ def _valid_measured_scan_usage(usage: object) -> bool:"missingThreadCount","warnings","completion",+ "byRole",+ "window",+ "observedAt",+ "tokensUpdatedAt",+ "accountRateLimits",*SCAN_USAGE_TOKEN_KEYS,}if thread_count == 0 or not set(usage).issubset(allowed_keys):@@ -144,6 +150,36 @@ def _valid_measured_scan_usage(usage: object) -> bool:return Falseif coverage == "partial" and not (warnings or missing):return False+ for field in ("observedAt", "tokensUpdatedAt"):+ if field in usage and usage_timestamp(usage[field]) is None:+ return False+ if "window" in usage:+ window = usage["window"]+ if not isinstance(window, dict) or set(window) != {"startedAt", "endedAt"}:+ return False+ start, end = (usage_timestamp(window[key]) for key in ("startedAt", "endedAt"))+ if start is None or end is None or start > end:+ return False+ if "byRole" in usage:+ roles = usage["byRole"]+ keys = {*SCAN_USAGE_TOKEN_KEYS, "threadCount"}+ if not isinstance(roles, dict) or set(roles) != {"parent", "workers"}:+ return False+ if any(+ not isinstance(role, dict)+ or set(role) != keys+ or any(type(role[key]) is not int or role[key] < 0 for key in keys)+ for role in roles.values()+ ):+ return False+ if any(sum(role[key] for role in roles.values()) != usage[key] for key in keys):+ return False+ if "accountRateLimits" in usage:+ limits = usage["accountRateLimits"]+ if not isinstance(limits, list) or not all(+ valid_account_rate_limit(limit) for limit in limits+ ):+ return Falsereturn Truediff --git a/plugins/codex-security/skills/deep-security-scan/SKILL.md b/plugins/codex-security/skills/deep-security-scan/SKILL.mdindex d282da8ab..1718954c1 100644--- a/plugins/codex-security/skills/deep-security-scan/SKILL.md+++ b/plugins/codex-security/skills/deep-security-scan/SKILL.md@@ -75,6 +75,6 @@ After the coordinator returns the canonical manifest and all three unsealed pareDetailed finding write-ups and hardening proposals remain optional, exactly as in an ordinary Standard scan; invoke `$codex-security:vulnerability-writeup` or `$codex-security:propose-security-hardening` only when the corresponding additional output is requested. Read `get_codex_security_completed_scan` only when requested structured or benchmark output actually requires the full sealed documents.-Return user-facing or benchmark output only after completion succeeds and the generated `report.md` exists. Link the report and canonical artifacts. Include measured total, input, and cached input token counts only when coverage is complete; leave pending usage to the host's end-of-turn finalization and identify other incomplete counts as unavailable. Never report a preliminary count as a final total or an "at least" estimate. If the configured time limit elapsed before any source review completed, explain that no source review finished and retain any saved findings or pending work; do not claim the repository is free of vulnerabilities. An empty finding set with completed review is the ordinary Codex Security no-findings result, not permission to skip completion.+Return user-facing or benchmark output only after completion succeeds and the generated `report.md` exists. Link the report and canonical artifacts. Report usage according to `../../references/final-report.md`. If the configured time limit elapsed before any source review completed, explain that no source review finished and retain any saved findings or pending work; do not claim the repository is free of vulnerabilities. An empty finding set with completed review is the ordinary Codex Security no-findings result, not permission to skip completion.If canonical coordinator artifacts are missing or malformed, stop and surface the exact blocker without calling completion, fabricating a report, or claiming success. If completion fails, surface its exact MCP error without retrying, canceling, failing the durable scan, or returning final, no-findings, structured, or benchmark output. Leave resumable work running and preserve its handoff claim. On explicit cancellation, call `cancel_codex_security_scan` and do not accept later scan progress or success. The host may preserve a final in-flight checkpoint after worker cleanup without resuming analysis. Never edit repository files, widen the target, expose internal worker bookkeeping unless requested, or call `fail_codex_security_scan` merely because a waiter detached, a turn ended, workers are still active, or partial artifacts exist.diff --git a/plugins/codex-security/tests/test_finalize_scan_contract.py b/plugins/codex-security/tests/test_finalize_scan_contract.pyindex cb0f9d26e..4874ac41a 100644--- a/plugins/codex-security/tests/test_finalize_scan_contract.py+++ b/plugins/codex-security/tests/test_finalize_scan_contract.py@@ -155,10 +155,7 @@ The extraction root is not enforced."targetId": "target_sha256_example","displayName": "example/repo","revision": "deadbeef",- "snapshotDigest": (- "codex-security-snapshot/v1:sha256:"- "0000000000000000000000000000000000000000000000000000000000000000"- ),+ "snapshotDigest": "codex-security-snapshot/v1:sha256:" + "0" * 64,},"allowedTargetKinds": ["git_worktree"],"scope": {"includePaths": ["src/"], "excludePaths": []},diff --git a/plugins/codex-security/tests/test_workbench_scan_history.py b/plugins/codex-security/tests/test_workbench_scan_history.pyindex ec9b67a9f..67e56ba29 100644--- a/plugins/codex-security/tests/test_workbench_scan_history.py+++ b/plugins/codex-security/tests/test_workbench_scan_history.py@@ -524,7 +524,8 @@ def test_cli_scan_history_persists_per_scan_cost(tmp_path: Path, context_reporti"SELECT cost_json FROM scans WHERE id = ?", (scan["scanId"],)).fetchone()assert stored is not None- assert json.loads(stored[0]) == cost+ assert json.loads(stored[0]) == {"cost": cost, "usage": listed["scans"][0]["usage"]}+ assert listed["scans"][0]["usage"]["coverage"] == "unavailable"def test_cli_scan_completion_persists_authoritative_cost_after_plugin_completion(diff --git a/plugins/codex-security/tests/test_workbench_scan_usage.py b/plugins/codex-security/tests/test_workbench_scan_usage.pyindex 11126db43..26e133918 100644--- a/plugins/codex-security/tests/test_workbench_scan_usage.py+++ b/plugins/codex-security/tests/test_workbench_scan_usage.py@@ -165,6 +165,7 @@ def _rollout(parent_thread_id: str | None = None,recorded_thread_id: str | None = None,include_task_start: bool = True,+ include_task_complete: bool = True,include_task_start_timestamp: bool = True,task_started_at: datetime | None = None,session_started_at: datetime | None = None,@@ -198,6 +199,14 @@ def _rollout()records.append(event)records.extend(events)+ if events and parent_thread_id is not None and include_task_complete:+ records.append(+ {+ "timestamp": events[-1]["timestamp"],+ "type": "event_msg",+ "payload": {"type": "task_complete"},+ }+ )rollout.write_text("".join(f"{json.dumps(item, separators=(',', ':'))}\n" for item in records),encoding="utf-8",@@ -365,16 +374,20 @@ def test_completion_counts_native_responses_and_compaction_without_legacy_duplic_token_event(counted, 170, 17),compaction,_response_event(counted, "scan-parent", "last", 30, 4, turn_usage=(90, 9)),+ _event(counted, "event_msg", {"type": "task_complete"}),],)_state_graph(fixture.environment, {"scan-parent": parent}, [])- assert _complete_scan(fixture)["scan"]["usage"] == {- "coverage": "complete",- "source": "codex_rollout",- **_counts(140, 0, 14),- "threadCount": 1,- }+ assert (+ _complete_scan(fixture)["scan"]["usage"].items()+ >= {+ "coverage": "complete",+ "source": "codex_rollout",+ **_counts(140, 0, 14),+ "threadCount": 1,+ }.items()+ )@pytest.mark.parametrize(@@ -411,17 +424,20 @@ def test_legacy_compaction_usage_is_unverifiable_only_inside_scan_window(else _token_event(started, 10, 1),]events.insert(0 if scope == "before" else len(events), marker)+ events.append(_event(completed, "event_msg", {"type": "task_complete"}))parent = _rollout(tmp_path, "scan-parent", events)helper = runpy.run_path(str(Path(__file__).resolve().parents[1] / "scripts/workbench_scan_usage.py"))- usage, warnings = helper["_read_rollout_usage"](+ measurement = helper["_read_rollout_usage"](helper["RolloutSession"]("scan-parent", None, parent),started_at=started,completed_at=completed,completed_turn_id="turn-scan-parent" if scope == "completion_turn" else None,)+ usage = measurement.tokens+ warnings = measurement.warningsassert usage == _counts(10, 0, 1)assert warnings == ({"compaction_usage_unavailable"} if expected_warning else set())@@ -437,17 +453,20 @@ def test_legacy_compaction_warning_survives_a_later_native_turn(tmp_path: Path)_event(started, "compacted", {"message": "Summary.", "replacement_history": []}),_event(started, "event_msg", {"type": "task_started", "turn_id": "native-turn"}),_response_event(started, "scan-parent", "native", 20, 2, turn_id="native-turn"),+ _event(started, "event_msg", {"type": "task_complete"}),],)helper = runpy.run_path(str(Path(__file__).resolve().parents[1] / "scripts/workbench_scan_usage.py"))- usage, warnings = helper["_read_rollout_usage"](+ measurement = helper["_read_rollout_usage"](helper["RolloutSession"]("scan-parent", None, parent),started_at=started,completed_at=started,)+ usage = measurement.tokens+ warnings = measurement.warningsassert usage == _counts(30, 0, 3)assert warnings == {"compaction_usage_unavailable"}@@ -472,6 +491,7 @@ def test_native_usage_respects_scan_window_and_preserves_cache_details(tmp_path:_token_event(before, 100, 10),response,_token_event(started, 120, 12),+ _event(completed, "event_msg", {"type": "task_complete"}),_response_event(completed + timedelta(seconds=1),"scan-parent",@@ -486,11 +506,13 @@ def test_native_usage_respects_scan_window_and_preserves_cache_details(tmp_path:str(Path(__file__).resolve().parents[1] / "scripts/workbench_scan_usage.py"))- usage, warnings = helper["_read_rollout_usage"](+ measurement = helper["_read_rollout_usage"](helper["RolloutSession"]("scan-parent", None, parent),started_at=started,completed_at=completed,)+ usage = measurement.tokens+ warnings = measurement.warningsassert usage == _counts(20, 3, 2, cache_write_input_tokens=4)assert warnings == set()@@ -510,11 +532,13 @@ def test_native_worker_usage_excludes_inherited_totals_and_survives_resume(tmp_powned,inherited,_token_event(started, 1_020, 102),+ _event(started, "event_msg", {"type": "task_complete"}),_event(started, "event_msg", {"type": "task_started", "turn_id": "resumed-turn"}),_response_event(started, "scan-worker", "resumed-response", 30, 3, turn_id="resumed-turn"),_token_event(started, 1_050, 105),+ _event(started, "event_msg", {"type": "task_complete"}),_event(started, "event_msg", {"type": "task_started", "turn_id": "legacy-turn"}),_token_event(started, 1_060, 106),],@@ -525,11 +549,13 @@ def test_native_worker_usage_excludes_inherited_totals_and_survives_resume(tmp_pstr(Path(__file__).resolve().parents[1] / "scripts/workbench_scan_usage.py"))- usage, warnings = helper["_read_rollout_usage"](+ measurement = helper["_read_rollout_usage"](helper["RolloutSession"]("scan-worker", "scan-parent", worker),started_at=started,completed_at=started,)+ usage = measurement.tokens+ warnings = measurement.warningsassert usage == _counts(60, 0, 6)assert warnings == set()@@ -554,6 +580,7 @@ def test_native_usage_only_marks_receipt_gaps_inside_scan_window(tmp_path: Path,turn_usage=(baseline, 0),),_response_event(started, "scan-parent", "counted", 30, 0, turn_usage=(in_window, 0)),+ _event(started, "event_msg", {"type": "task_complete"}),_response_event(started + timedelta(seconds=1),"scan-parent",@@ -568,11 +595,13 @@ def test_native_usage_only_marks_receipt_gaps_inside_scan_window(tmp_path: Path,str(Path(__file__).resolve().parents[1] / "scripts/workbench_scan_usage.py"))- usage, warnings = helper["_read_rollout_usage"](+ measurement = helper["_read_rollout_usage"](helper["RolloutSession"]("scan-parent", None, parent),started_at=started,completed_at=started,)+ usage = measurement.tokens+ warnings = measurement.warningsassert usage == _counts(30, 0, 0)assert warnings == ({"token_record_incomplete"} if gap == "inside" else set())@@ -595,17 +624,20 @@ def test_native_usage_continues_cumulative_baseline_when_recovering_same_turn(turn_started,_response_event(started, "scan-parent", "recovered", 20, 2, turn_usage=(30, 3)),_token_event(started, 30, 3),+ _event(started, "event_msg", {"type": "task_complete"}),],)helper = runpy.run_path(str(Path(__file__).resolve().parents[1] / "scripts/workbench_scan_usage.py"))- usage, warnings = helper["_read_rollout_usage"](+ measurement = helper["_read_rollout_usage"](helper["RolloutSession"]("scan-parent", None, parent),started_at=started,completed_at=started,)+ usage = measurement.tokens+ warnings = measurement.warningsassert usage == _counts(30, 0, 3)assert warnings == set()@@ -630,11 +662,13 @@ def test_native_usage_preserves_partial_measurement_warnings(tmp_path: Path, faistr(Path(__file__).resolve().parents[1] / "scripts/workbench_scan_usage.py"))- usage, warnings = helper["_read_rollout_usage"](+ measurement = helper["_read_rollout_usage"](helper["RolloutSession"]("scan-parent", None, parent),started_at=started,completed_at=started,)+ usage = measurement.tokens+ warnings = measurement.warningsassert usage == (_counts(20, 0, 2) if failure == "missing_receipt" else _counts(10, 0, 1))assert warnings == {@@ -642,7 +676,8 @@ def test_native_usage_preserves_partial_measurement_warnings(tmp_path: Path, faiif failure == "missing_receipt"else "rollout_record_incomplete"if failure == "truncated"- else "token_record_invalid"+ else "token_record_invalid",+ "turn_in_progress",}@@ -697,7 +732,18 @@ def test_completion_counts_only_scan_owned_parent_and_descendants("threadCount": 3,}assert completed["scan"]["mode"] == mode- assert completed["scan"]["usage"] == expected+ usage = completed["scan"]["usage"]+ assert usage.items() >= expected.items()+ assert usage["byRole"] == {+ "parent": {**_counts(50, 25, 15), "threadCount": 1},+ "workers": {**_counts(38, 12, 10), "threadCount": 2},+ }+ assert datetime.fromisoformat(usage["window"]["startedAt"]) == fixture.started_at+ assert datetime.fromisoformat(usage["tokensUpdatedAt"]) == counted+ assert datetime.fromisoformat(usage["observedAt"]) >= datetime.fromisoformat(+ usage["window"]["endedAt"]+ )+ expected = usageassert completed["workspace"]["results"]["usage"] == expectedassert "byModel" not in completed["scan"]["usage"]assert (@@ -750,12 +796,15 @@ def test_completion_includes_cached_and_cache_write_tokens(usage = _complete_scan(fixture)["scan"]["usage"]- assert usage == {- "coverage": "complete",- "source": "codex_rollout",- **_counts(120, 30, 15, cache_write_input_tokens=12),- "threadCount": 1,- }+ assert (+ usage.items()+ >= {+ "coverage": "complete",+ "source": "codex_rollout",+ **_counts(120, 30, 15, cache_write_input_tokens=12),+ "threadCount": 1,+ }.items()+ )def test_completion_excludes_separately_inherited_worker_snapshots(tmp_path: Path) -> None:@@ -784,12 +833,15 @@ def test_completion_excludes_separately_inherited_worker_snapshots(tmp_path: Pat[("scan-parent", "first-worker"), ("scan-parent", "second-worker")],)usage = _complete_scan(fixture)["scan"]["usage"]- assert usage == {- "coverage": "complete",- "source": "codex_rollout",- **_counts(240, 65, 42),- "threadCount": 3,- }+ assert (+ usage.items()+ >= {+ "coverage": "complete",+ "source": "codex_rollout",+ **_counts(240, 65, 42),+ "threadCount": 3,+ }.items()+ )def test_completion_ignores_worker_families_started_before_scan(tmp_path: Path) -> None:@@ -816,12 +868,15 @@ def test_completion_ignores_worker_families_started_before_scan(tmp_path: Path){"scan-parent": parent, "old-worker": worker, "old-descendant": descendant},[("scan-parent", "old-worker"), ("old-worker", "old-descendant")],)- assert _complete_scan(fixture)["scan"]["usage"] == {- "coverage": "complete",- "source": "codex_rollout",- **_counts(10, 0, 0),- "threadCount": 1,- }+ assert (+ _complete_scan(fixture)["scan"]["usage"].items()+ >= {+ "coverage": "complete",+ "source": "codex_rollout",+ **_counts(10, 0, 0),+ "threadCount": 1,+ }.items()+ )@pytest.mark.parametrize(@@ -908,12 +963,15 @@ def test_completion_reads_usage_from_literal_home(def test_completion_reports_unavailable_without_fabricating_zero(tmp_path: Path) -> None:fixture = _start_scan(tmp_path)usage = _complete_scan(fixture)["scan"]["usage"]- assert usage == {- "coverage": "unavailable",- "source": "codex_rollout",- "threadCount": 0,- "warnings": ["codex_state_unavailable"],- }+ assert (+ usage.items()+ >= {+ "coverage": "unavailable",+ "source": "codex_rollout",+ "threadCount": 0,+ "warnings": ["codex_state_unavailable"],+ }.items()+ )assert "totalTokens" not in usage@@ -944,12 +1002,15 @@ def test_completion_rejects_non_system_rollout_symlink(tmp_path: Path) -> None:symlink = canonical.with_name("linked-rollout.jsonl")symlink.symlink_to(canonical)_state_graph(fixture.environment, {"scan-parent": symlink}, [])- assert _complete_scan(fixture)["scan"]["usage"] == {- "coverage": "unavailable",- "source": "codex_rollout",- "threadCount": 0,- "warnings": ["rollout_unavailable", "scan_thread_unavailable"],- }+ assert (+ _complete_scan(fixture)["scan"]["usage"].items()+ >= {+ "coverage": "unavailable",+ "source": "codex_rollout",+ "threadCount": 0,+ "warnings": ["rollout_unavailable", "scan_thread_unavailable"],+ }.items()+ )def test_completion_counts_deep_sdk_workers_and_descendants(tmp_path: Path) -> None:@@ -986,12 +1047,15 @@ def test_completion_counts_deep_sdk_workers_and_descendants(tmp_path: Path) -> N[("sdk-worker", "sdk-child")],)usage = _complete_scan(fixture)["scan"]["usage"]- assert usage == {- "coverage": "complete",- "source": "codex_rollout",- **_counts(37, 0, 10),- "threadCount": 3,- }+ assert (+ usage.items()+ >= {+ "coverage": "complete",+ "source": "codex_rollout",+ **_counts(37, 0, 10),+ "threadCount": 3,+ }.items()+ )@pytest.mark.parametrize("owner_first", [True, False])@@ -1044,22 +1108,39 @@ def test_usage_counts_registered_worker_when_its_parent_rollout_is_missing(completed_at=counted.isoformat(),)- assert usage == {- "coverage": "partial",- "source": "codex_rollout",- **_counts(37, 0, 10),- "threadCount": 3,- "missingThreadCount": 1,- "warnings": ["rollout_unavailable"],- }+ assert (+ usage.items()+ >= {+ "coverage": "partial",+ "source": "codex_rollout",+ **_counts(37, 0, 10),+ "threadCount": 3,+ "missingThreadCount": 1,+ "warnings": ["rollout_unavailable"],+ }.items()+ )-def test_completion_preserves_explicit_legacy_cost(tmp_path: Path) -> None:[email protected]("delayed_cache_counts", [False, True])+def test_completion_preserves_explicit_legacy_cost(+ tmp_path: Path, delayed_cache_counts: bool+) -> None:fixture = _start_scan(tmp_path)counted = fixture.started_at + timedelta(microseconds=1)_state_graph(fixture.environment,- {"scan-parent": _rollout(tmp_path, "scan-parent", [_token_event(counted, 15, 6)])},+ {+ "scan-parent": _rollout(+ tmp_path,+ "scan-parent",+ [+ _token_event(fixture.started_at - timedelta(seconds=1), 100, 0),+ _token_event(+ counted, 115, 6, cached_input_tokens=100 if delayed_cache_counts else 0+ ),+ ],+ )+ },[],)cost = {@@ -1082,7 +1163,12 @@ def test_completion_preserves_explicit_legacy_cost(tmp_path: Path) -> None:environment=fixture.environment,)["scan"]assert completed["cost"] == cost- assert "usage" not in completed+ if delayed_cache_counts:+ assert completed["usage"]["coverage"] == "unavailable"+ assert completed["usage"]["warnings"] == ["token_breakdown_unavailable"]+ assert "totalTokens" not in completed["usage"]+ else:+ assert completed["usage"]["totalTokens"] == 21def test_usage_is_returned_by_completion_without_an_extra_command(tmp_path: Path) -> None:@@ -1135,14 +1221,17 @@ def test_host_finalizes_exact_completion_turn_without_changing_artifacts()initial = _complete_scan(fixture, "--thread-id", "scan-parent", "--turn-id", turn_id)["scan"]completion = {"threadId": "scan-parent", "turnId": turn_id, "finalized": False}- assert initial["usage"] == {- "coverage": "partial",- "source": "codex_rollout",- **_counts(30, 0, 5),- "threadCount": 2,- "warnings": ["turn_in_progress"],- "completion": completion,- }+ assert (+ initial["usage"].items()+ >= {+ "coverage": "partial",+ "source": "codex_rollout",+ **_counts(30, 0, 5),+ "threadCount": 2,+ "warnings": ["turn_in_progress"],+ "completion": completion,+ }.items()+ )sealed_files = {name: (fixture.scan_dir / name).read_bytes()for name in ("scan-manifest.json", "findings.json", "coverage.json", "report.md")@@ -1188,13 +1277,18 @@ def test_host_finalizes_exact_completion_turn_without_changing_artifacts(*arguments,environment=fixture.environment,)["scan"]- assert finalized["usage"] == {- "coverage": "complete",- "source": "codex_rollout",- **_counts(110, 0, 14),- "threadCount": 2,- "completion": {**completion, "finalized": True},- }+ assert (+ finalized["usage"].items()+ >= {+ "coverage": "complete",+ "source": "codex_rollout",+ **_counts(110, 0, 14),+ "threadCount": 2,+ "completion": {**completion, "finalized": True},+ }.items()+ )+ assert datetime.fromisoformat(finalized["usage"]["tokensUpdatedAt"]) == late+ assert datetime.fromisoformat(finalized["usage"]["window"]["endedAt"]) == latelater_events = [_event(late, "event_msg", {"type": "task_complete", "turn_id": turn_id}),_event(late, "event_msg", {"type": "task_started", "turn_id": "later-turn"}),@@ -1207,12 +1301,14 @@ def test_host_finalizes_exact_completion_turn_without_changing_artifacts(helper = runpy.run_path(str(Path(__file__).resolve().parents[1] / "scripts/workbench_scan_usage.py"))- measured, warnings = helper["_read_rollout_usage"](+ measurement = helper["_read_rollout_usage"](helper["RolloutSession"]("scan-parent", None, parent),started_at=fixture.started_at,completed_at=datetime.fromisoformat(stopped_at.replace("Z", "+00:00")),completed_turn_id=turn_id,)+ measured = measurement.tokens+ warnings = measurement.warningsassert measured == _counts(90, 0, 11)assert warnings == set()assert (@@ -1260,16 +1356,19 @@ def test_host_final_usage_preserves_missing_worker_warning(turn_status,environment=fixture.environment,)["scan"]["usage"]- assert usage == {- "coverage": "partial",- "source": "codex_rollout",- **_counts(10, 0, 2),- "threadCount": 1,- "missingThreadCount": 1,- "warnings": ["rollout_unavailable"]- + ([] if turn_status == "completed" else [f"scan_turn_{turn_status}"]),- "completion": {"threadId": "scan-parent", "turnId": turn_id, "finalized": True},- }+ assert (+ usage.items()+ >= {+ "coverage": "partial",+ "source": "codex_rollout",+ **_counts(10, 0, 2),+ "threadCount": 1,+ "missingThreadCount": 1,+ "warnings": ["rollout_unavailable"]+ + ([] if turn_status == "completed" else [f"scan_turn_{turn_status}"]),+ "completion": {"threadId": "scan-parent", "turnId": turn_id, "finalized": True},+ }.items()+ )def test_host_final_usage_retries_a_locked_native_database_without_losing_counts(@@ -1310,13 +1409,16 @@ def test_host_final_usage_retries_a_locked_native_database_without_losing_counts*arguments,environment=fixture.environment,)["scan"]["usage"]- assert finalized == {- "coverage": "complete",- "source": "codex_rollout",- **_counts(30, 0, 5),- "threadCount": 1,- "completion": {**initial["completion"], "finalized": True},- }+ assert (+ finalized.items()+ >= {+ "coverage": "complete",+ "source": "codex_rollout",+ **_counts(30, 0, 5),+ "threadCount": 1,+ "completion": {**initial["completion"], "finalized": True},+ }.items()+ )def test_host_final_usage_recovers_initially_unavailable_records(tmp_path: Path) -> None:@@ -1367,7 +1469,10 @@ def test_host_final_usage_does_not_invent_an_unrecorded_completion_turn(tmp_path"scan-parent": _rollout(tmp_path,"scan-parent",- [_response_event(fixture.started_at, "scan-parent", "earlier-response", 10, 2)],+ [+ _response_event(fixture.started_at, "scan-parent", "earlier-response", 10, 2),+ _event(fixture.started_at, "event_msg", {"type": "task_complete"}),+ ],)},[],@@ -1525,12 +1630,15 @@ def test_completion_recovers_replaced_deep_worker_threads(tmp_path: Path, worker],)usage = _complete_scan(fixture)["scan"]["usage"]- assert usage == {- "coverage": "complete",- "source": "codex_rollout",- **_counts(67, 0, 18),- "threadCount": 4,- }+ assert (+ usage.items()+ >= {+ "coverage": "complete",+ "source": "codex_rollout",+ **_counts(67, 0, 18),+ "threadCount": 4,+ }.items()+ )@pytest.mark.cross_platform@@ -1594,3 +1702,364 @@ def test_worker_discovery_matches_platform_path_spelling(assert {session.thread_id for session in sessions} == expected_threadsassert missing == set()assert warnings == set()+++def test_completion_uses_latest_account_snapshot_across_owned_sessions(tmp_path: Path) -> None:+ fixture = _start_scan(tmp_path)+ first = fixture.started_at + timedelta(microseconds=1)+ latest = first + timedelta(microseconds=1)++ def allowance(timestamp: datetime, percent: int, limit: str = "codex") -> dict[str, Any]:+ return _event(+ timestamp,+ "event_msg",+ {+ "type": "token_count",+ "info": None,+ "rate_limits": {+ "limit_id": limit,+ "primary": {+ "used_percent": percent,+ "window_minutes": 10080,+ "resets_at": 1800000000,+ },+ "secondary": None,+ },+ },+ )++ parent = _rollout(+ tmp_path,+ "scan-parent",+ [+ _token_event(first, 10, 3),+ allowance(first, 6),+ allowance(first, 2, "another-limit"),+ allowance(first + timedelta(days=1), 99),+ ],+ )+ worker = _rollout(+ tmp_path,+ "worker",+ [+ _token_event(first, 20, 5),+ allowance(latest, 69),+ allowance(first, 6),+ ],+ parent_thread_id="scan-parent",+ )+ unrelated = _rollout(tmp_path, "unrelated", [allowance(latest, 100)])+ _state_graph(+ fixture.environment,+ {+ "scan-parent": parent,+ "worker": worker,+ "unrelated": unrelated,+ },+ [("scan-parent", "worker")],+ )++ completed = _complete_scan(fixture)+ usage = completed["scan"]["usage"]+ assert usage["coverage"] == "complete"+ assert usage["totalTokens"] == 38+ assert datetime.fromisoformat(usage["tokensUpdatedAt"]) == first+ limits = {item["limitId"]: item for item in usage["accountRateLimits"]}+ assert limits["codex"] == {+ "limitId": "codex",+ "observedAt": latest.isoformat(),+ "primary": {"usedPercent": 69, "windowMinutes": 10080, "resetsAt": 1800000000},+ "secondary": None,+ }+ assert limits["another-limit"]["primary"]["usedPercent"] == 2++[email protected]("terminal", [None, "task_complete", "turn_aborted"])+def test_completion_marks_worker_without_token_receipt_partial(+ tmp_path: Path, terminal: str | None+) -> None:+ fixture = _start_scan(tmp_path)+ counted = fixture.started_at + timedelta(microseconds=1)+ parent = _rollout(tmp_path, "scan-parent", [_token_event(counted, 12, 3)])+ worker = _rollout(+ tmp_path,+ "worker",+ [_event(counted, "event_msg", {"type": terminal})] if terminal else [],+ parent_thread_id="scan-parent",+ task_started_at=counted,+ include_task_complete=False,+ )+ _state_graph(+ fixture.environment, {"scan-parent": parent, "worker": worker}, [("scan-parent", "worker")]+ )++ usage = _complete_scan(fixture)["scan"]["usage"]+ assert usage["coverage"] == "partial"+ expected_warnings = {"token_record_missing"}+ if terminal is None:+ expected_warnings.add("turn_in_progress")+ elif terminal == "turn_aborted":+ expected_warnings.add("turn_interrupted")+ assert set(usage["warnings"]) == expected_warnings+ assert usage["totalTokens"] == 15+ assert usage["threadCount"] == 2+ assert usage["byRole"]["workers"] == {**_counts(0, 0, 0), "threadCount": 1}+ assert usage["accountRateLimits"] == []+++def test_completion_marks_in_flight_usage_partial_even_with_earlier_receipts(+ tmp_path: Path,+) -> None:+ fixture = _start_scan(tmp_path)+ counted = fixture.started_at + timedelta(microseconds=1)+ parent = _rollout(+ tmp_path,+ "scan-parent",+ [+ _event(counted, "event_msg", {"type": "task_started", "turn_id": "scan-turn"}),+ _token_event(counted, 12, 3),+ _event(counted + timedelta(days=1), "event_msg", {"type": "task_complete"}),+ ],+ )+ _state_graph(fixture.environment, {"scan-parent": parent}, [])+ usage = _complete_scan(fixture)["scan"]["usage"]+ assert usage["coverage"] == "partial"+ assert usage["totalTokens"] == 15+ assert usage["warnings"] == ["turn_in_progress"]++[email protected]("gap", ["aborted", "in_progress", "completed_without_receipt"])+def test_completion_preserves_receipts_when_later_worker_usage_is_missing(+ tmp_path: Path, gap: str+) -> None:+ fixture = _start_scan(tmp_path)+ counted = fixture.started_at + timedelta(microseconds=1)+ parent = _rollout(tmp_path, "scan-parent", [_token_event(counted, 12, 3)])+ events = [_response_event(counted, "worker", "measured-response", 20, 5)]+ if gap == "aborted":+ events.append(_event(counted, "event_msg", {"type": "turn_aborted"}))+ expected_warning = "turn_interrupted"+ elif gap == "completed_without_receipt":+ events.extend(+ [+ _event(counted, "event_msg", {"type": "task_complete"}),+ _event(counted, "event_msg", {"type": "task_started", "turn_id": "later-turn"}),+ _event(counted, "event_msg", {"type": "task_complete", "turn_id": "later-turn"}),+ ]+ )+ expected_warning = "token_record_missing"+ else:+ expected_warning = "turn_in_progress"+ worker = _rollout(+ tmp_path,+ "worker",+ events,+ parent_thread_id="scan-parent",+ include_task_complete=False,+ )+ _state_graph(+ fixture.environment, {"scan-parent": parent, "worker": worker}, [("scan-parent", "worker")]+ )++ usage = _complete_scan(fixture)["scan"]["usage"]+ assert usage["coverage"] == "partial"+ assert usage["warnings"] == [expected_warning]+ assert usage["totalTokens"] == 40+ assert usage["byRole"]["workers"]["totalTokens"] == 25++[email protected]("worker", [False, True])[email protected]("terminal", ["task_complete", "turn_aborted"])[email protected]("receipt", ["none", "native", "legacy", "zero"])+def test_closed_turn_coverage_survives_later_success(+ tmp_path: Path, worker: bool, terminal: str, receipt: str+) -> None:+ started = datetime.fromisoformat("2026-01-01T00:00:00+00:00")+ thread_id = "worker" if worker else "scan-parent"+ parent_id = "scan-parent" if worker else None+ events = [_event(started, "event_msg", {"type": "task_started", "turn_id": "first"})]+ if receipt in {"native", "zero"}:+ events.append(+ _response_event(+ started,+ thread_id,+ "first-response",+ 20 if receipt == "native" else 0,+ 3 if receipt == "native" else 0,+ turn_id="first",+ )+ )+ elif receipt == "legacy":+ events.append(_token_event(started, 20, 3))+ events.extend(+ [+ _event(started, "event_msg", {"type": terminal, "turn_id": "first"}),+ _event(started, "event_msg", {"type": "task_started", "turn_id": "second"}),+ _response_event(started, thread_id, "second-response", 10, 2, turn_id="second"),+ _event(started, "event_msg", {"type": "task_complete", "turn_id": "second"}),+ ]+ )+ rollout = _rollout(+ tmp_path, thread_id, events, parent_thread_id=parent_id, include_task_start=False+ )+ helper = runpy.run_path(+ str(Path(__file__).resolve().parents[1] / "scripts/workbench_scan_usage.py")+ )+ measurement = helper["_read_rollout_usage"](+ helper["RolloutSession"](thread_id, parent_id, rollout),+ started_at=started,+ completed_at=started,+ )+ usage, warnings = measurement.tokens, measurement.warnings+ assert usage == (_counts(30, 0, 5) if receipt in {"native", "legacy"} else _counts(10, 0, 2))+ assert warnings == ({"token_record_missing"} if receipt == "none" else set()) | (+ {"turn_interrupted"} if terminal == "turn_aborted" else set()+ )++[email protected]("receipt", [False, True])[email protected]("native", [False, True])+def test_closed_turn_coverage_retains_before_window_receipt_evidence(+ tmp_path: Path, receipt: bool, native: bool+) -> None:+ started = datetime.fromisoformat("2026-01-01T00:00:01+00:00")+ before = started - timedelta(seconds=1)+ events = [_event(before, "event_msg", {"type": "task_started", "turn_id": "first"})]+ if receipt:+ events.append(+ _response_event(before, "scan-parent", "before", 20, 3, turn_id="first")+ if native+ else _token_event(before, 20, 3)+ )+ events.extend(+ [+ _event(started, "event_msg", {"type": "task_complete", "turn_id": "first"}),+ _event(started, "event_msg", {"type": "task_started", "turn_id": "second"}),+ _response_event(started, "scan-parent", "counted", 10, 2, turn_id="second"),+ _event(started, "event_msg", {"type": "task_complete", "turn_id": "second"}),+ ]+ )+ rollout = _rollout(tmp_path, "scan-parent", events)+ helper = runpy.run_path(+ str(Path(__file__).resolve().parents[1] / "scripts/workbench_scan_usage.py")+ )+ measurement = helper["_read_rollout_usage"](+ helper["RolloutSession"]("scan-parent", None, rollout),+ started_at=started,+ completed_at=started,+ )+ usage, warnings = measurement.tokens, measurement.warnings+ assert usage == _counts(10, 0, 2)+ assert warnings == (set() if receipt else {"token_record_missing"})+++def test_closed_turn_coverage_accepts_delayed_receipt_for_same_turn(tmp_path: Path) -> None:+ started = datetime.fromisoformat("2026-01-01T00:00:00+00:00")+ rollout = _rollout(+ tmp_path,+ "scan-parent",+ [+ _event(started, "event_msg", {"type": "task_started", "turn_id": "first"}),+ _event(started, "event_msg", {"type": "task_complete", "turn_id": "first"}),+ _response_event(started, "scan-parent", "late", 10, 2, turn_id="first"),+ ],+ )+ helper = runpy.run_path(+ str(Path(__file__).resolve().parents[1] / "scripts/workbench_scan_usage.py")+ )+ measurement = helper["_read_rollout_usage"](+ helper["RolloutSession"]("scan-parent", None, rollout),+ started_at=started,+ completed_at=started,+ )+ usage, warnings = measurement.tokens, measurement.warnings+ assert usage == _counts(10, 0, 2)+ assert warnings == set()+++def test_closed_turn_coverage_preserves_interruption_after_same_turn_resumes(+ tmp_path: Path,+) -> None:+ started = datetime.fromisoformat("2026-01-01T00:00:00+00:00")+ rollout = _rollout(+ tmp_path,+ "scan-parent",+ [+ _event(started, "event_msg", {"type": "task_started", "turn_id": "same-turn"}),+ _event(started, "event_msg", {"type": "turn_aborted", "turn_id": "same-turn"}),+ _event(started, "event_msg", {"type": "task_started", "turn_id": "same-turn"}),+ _response_event(started, "scan-parent", "recovered", 10, 2, turn_id="same-turn"),+ _event(started, "event_msg", {"type": "task_complete", "turn_id": "same-turn"}),+ ],+ )+ helper = runpy.run_path(+ str(Path(__file__).resolve().parents[1] / "scripts/workbench_scan_usage.py")+ )+ measurement = helper["_read_rollout_usage"](+ helper["RolloutSession"]("scan-parent", None, rollout),+ started_at=started,+ completed_at=started,+ )+ usage, warnings = measurement.tokens, measurement.warnings+ assert usage == _counts(10, 0, 2)+ assert warnings == {"turn_interrupted"}+++def test_closed_turn_coverage_ignores_inherited_and_outside_window_interruptions(+ tmp_path: Path,+) -> None:+ started = datetime.fromisoformat("2026-01-01T00:00:00+00:00")+ before = started - timedelta(seconds=1)+ after = started + timedelta(seconds=1)+ rollout = _rollout(+ tmp_path,+ "worker",+ [+ _response_event(started, "worker", "counted", 10, 2),+ _event(started, "event_msg", {"type": "task_complete", "turn_id": "turn-worker"}),+ _event(after, "event_msg", {"type": "task_started", "turn_id": "later"}),+ _event(after, "event_msg", {"type": "turn_aborted", "turn_id": "later"}),+ ],+ parent_thread_id="scan-parent",+ copied_events=[+ _event(before, "event_msg", {"type": "turn_aborted", "turn_id": "inherited"}),+ ],+ )+ helper = runpy.run_path(+ str(Path(__file__).resolve().parents[1] / "scripts/workbench_scan_usage.py")+ )+ measurement = helper["_read_rollout_usage"](+ helper["RolloutSession"]("worker", "scan-parent", rollout),+ started_at=started,+ completed_at=started,+ )+ usage, warnings = measurement.tokens, measurement.warnings+ assert usage == _counts(10, 0, 2)+ assert warnings == set()+++def test_completion_marks_closed_turn_without_receipt_partial(tmp_path: Path) -> None:+ fixture = _start_scan(tmp_path)+ counted = fixture.started_at + timedelta(microseconds=1)+ parent = _rollout(+ tmp_path,+ "scan-parent",+ [+ _event(counted, "event_msg", {"type": "task_started", "turn_id": "empty"}),+ _event(counted, "event_msg", {"type": "task_complete", "turn_id": "empty"}),+ _event(counted, "event_msg", {"type": "task_started", "turn_id": "measured"}),+ _response_event(counted, "scan-parent", "response", 10, 2, turn_id="measured"),+ _event(counted, "event_msg", {"type": "task_complete", "turn_id": "measured"}),+ ],+ )+ _state_graph(fixture.environment, {"scan-parent": parent}, [])+ assert (+ _complete_scan(fixture)["scan"]["usage"].items()+ >= {+ "coverage": "partial",+ "source": "codex_rollout",+ **_counts(10, 0, 2),+ "threadCount": 1,+ "warnings": ["token_record_missing"],+ }.items()+ )diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.mdindex 483cc292a..a38995e4f 100644--- a/sdk/typescript/docs/cli.md+++ b/sdk/typescript/docs/cli.md@@ -374,6 +374,13 @@ Legacy completeness values affect neither.Bulk and component summaries report completed and failed scans without an`incomplete` count. Component matching errors have status `failed`.+Usage coverage is separate from execution status. A recorded interruption or a+closed turn without a numeric usage receipt makes usage coverage `partial`, even+if a later turn succeeds. Recorded numeric zero is distinct from a missing+receipt. These checks describe available local records; they cannot reconstruct+requests whose usage was never persisted locally or prove an exhaustive billing+total.+New drafts use the current finding schema: `codeEvidence`, `rootCause`,`attackPath.dataflow`, and `evidenceRefs`. Source snippets belong in`codeEvidence`; `rootCause.evidenceRefs` links to them. Legacy aliases and@@ -729,6 +736,19 @@ input. Missing cache-write usage makes the uncached/cache-write breakdownunavailable. The CLI cannot recover missing information already recorded as zeroby the runtime.+Completed scan history also saves rollout observations under `usage`, alongside+any `cost` estimate. `byRole` separates parent tokens from combined worker tokens.+`window` bounds the counted events, `observedAt` records collection time, and+`tokensUpdatedAt` records the newest token receipt. Partial coverage means some+work could not be measured, including in-flight turns or missing earlier attempts.+The parent can continue after report completion, so final CLI tokens can exceed+the saved measurement window.++`usage.accountRateLimits` saves the latest observed account-wide readings with+their own timestamps, window durations, and reset times. These are historical+observations, not a live allowance check or scan-only consumption. Empty readings+mean allowance was unavailable. There is no token-to-allowance conversion here.+Cost displays use [standard API prices](https://developers.openai.com/api/docs/pricing)and show a short/long-context range. They estimate model usage, excluding othertiers, fees, surcharges, and account-specific pricing. They do not measure ChatGPTdiff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.tsindex 0f3f9c477..9dba00660 100644--- a/sdk/typescript/tests-ts/api.test.ts+++ b/sdk/typescript/tests-ts/api.test.ts@@ -877,7 +877,8 @@ describe("CodexSecurity orchestration", () => {"workbench usage captured",);expect(measured).toMatchObject({- coverage: "complete",+ coverage: "partial",+ warnings: ["turn_in_progress"],inputTokens: 100,outputTokens: 10,totalTokens: 110,diff --git a/sdk/typescript/tests-ts/cost.test.ts b/sdk/typescript/tests-ts/cost.test.tsindex 947cc610c..1d0740abc 100644--- a/sdk/typescript/tests-ts/cost.test.ts+++ b/sdk/typescript/tests-ts/cost.test.ts@@ -1789,7 +1789,7 @@ describe("live scan cost tracking", () => {threadId: childUuid7Thread,codexHome: home,});- const ownedEvents = [rollout[0]!, ...rollout.slice(-2)];+ const ownedEvents = [rollout[0]!, ...rollout.slice(-3)];expect(forwardedEvents.map(({ event }) => event)).toEqual(ownedEvents);expect(saved.events.map(({ event }) => event)).toEqual(ownedEvents);});diff --git a/sdk/typescript/tests-ts/support/usage-rollout.ts b/sdk/typescript/tests-ts/support/usage-rollout.tsindex 87030c736..201464738 100644--- a/sdk/typescript/tests-ts/support/usage-rollout.ts+++ b/sdk/typescript/tests-ts/support/usage-rollout.ts@@ -84,6 +84,11 @@ export function ownershipRollout(uuid7TokenSnapshot(1_000, 100),uuid7TaskStarted(higherUuid7Turn),uuid7TokenSnapshot(1_100, 110),+ {+ type: "event_msg",+ timestamp: uuid7EventTimestamp,+ payload: { type: "task_complete" },+ },];}@@ -100,12 +105,12 @@ export function readPythonRolloutUsage("sys.path.insert(0, sys.argv[1])","import workbench_scan_usage","session = workbench_scan_usage.RolloutSession(sys.argv[3], sys.argv[4], Path(sys.argv[2]))",- "usage, warnings = workbench_scan_usage._read_rollout_usage(",+ "usage = workbench_scan_usage._read_rollout_usage("," session,"," started_at=datetime(2026, 7, 26, 12, tzinfo=timezone.utc),"," completed_at=None,",")",- "print(json.dumps({'usage': usage, 'warnings': sorted(warnings)}, sort_keys=True))",+ "print(json.dumps({'usage': usage.tokens, 'warnings': sorted(usage.warnings)}, sort_keys=True))",].join("\n");const result = runNodePython(python!, ["-c",