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
refactor: clarify Python contracts and simplify scan recovery and reporting (#2340)
Michael D'Angelo5c0be2444b47
diff --git a/.github/scripts/require_native_python_report.py b/.github/scripts/require_native_python_report.pyindex 54e04ff40..69fab17fc 100644--- a/.github/scripts/require_native_python_report.py+++ b/.github/scripts/require_native_python_report.py@@ -1,3 +1,5 @@+"""Require at least one test case and zero skipped cases in reports/python.xml."""+from xml.etree import ElementTreereport = ElementTree.parse("reports/python.xml")diff --git a/.github/scripts/test_require_native_python_report.py b/.github/scripts/test_require_native_python_report.pyindex 2b1e3b0ff..62757ef3a 100644--- a/.github/scripts/test_require_native_python_report.py+++ b/.github/scripts/test_require_native_python_report.py@@ -1,3 +1,5 @@+"""Exercise the native-test CI gate with missing, malformed, skipped, and passing reports."""+from contextlib import nullcontextfrom pathlib import Pathfrom runpy import run_pathdiff --git a/docker/wolfi/payload/stage.py b/docker/wolfi/payload/stage.pyindex c8ed6f8da..3b632eb28 100644--- a/docker/wolfi/payload/stage.py+++ b/docker/wolfi/payload/stage.py@@ -47,6 +47,7 @@ def read_json(path):def matches_target(package):+ """Return whether the npm package permits the target OS, CPU, and libc."""for key, target in TARGET.items():values = package.get(key, [])allowed = [v for v in values if not v.startswith("!")]@@ -56,6 +57,7 @@ def matches_target(package):def source_url(pkg):+ """Return the canonical HTTPS GitHub repository URL, raising ValueError on unfamiliar metadata."""repo = pkg.get("repository")raw = repo.get("url") if isinstance(repo, dict) else repo# npm accepts both GitHub shorthand and conventional git URLs. Do not@@ -67,6 +69,7 @@ def source_url(pkg):def select_scanner_payload(app):+ """Prune voice assets and off-target MCP binaries in place, checking the remaining Codex files."""# Voice belongs to the interactive client, not repository scanning. The# MCP server uses Node's target (Linux x64 glibc), while the Codex executable# itself is the upstream static musl build.@@ -86,6 +89,16 @@ def select_scanner_payload(app):def write_attributions(root, app, wanted):+ """Write upstream notices and the source inventory into the staged license directory.++ Args:+ root (Path): Staged filesystem containing the license directory.+ app (Path): Directory containing the installed npm packages.+ wanted (dict): Target-specific lock records keyed by installed package path.++ Raises:+ ValueError: A notice, declared license, or source falls outside the reviewed set.+ """license_dir = root / LICENSE_DIRnotices = read_json(HERE / "notices/sources.json")for name, item in notices.items():@@ -137,6 +150,15 @@ def write_attributions(root, app, wanted):def stage_root(root):+ """Stage the locked scanner runtime and return its count of target npm packages.++ Args:+ root (Path): Scratch filesystem root with space for a new runtime tree.+ A failed installation or verification can leave partial files here.++ SCANNER_RUNTIME_LOCK selects an alternate lock, and SCANNER_TARBALL supplies+ a local release archive in place of the registry's scanner package.+ """app = root / INSTALLapp.mkdir(parents=True)lock_path = Path(os.environ.get("SCANNER_RUNTIME_LOCK") or HERE / "package-lock.json")@@ -204,6 +226,7 @@ def stage_root(root):def normalize(entry):+ """Set reproducible ownership, timestamp, and mode on a tar member and return it to tarfile."""if not (entry.isdir() or entry.isreg() or entry.issym()):raise ValueError(f"Unexpected file type: {entry.name}")entry.uid = entry.gid = entry.mtime = 0@@ -213,6 +236,7 @@ def normalize(entry):def main():+ """Publish payload.tar.gz and print its package count and the digest of the uncompressed tar."""args = argparse.ArgumentParser(description=__doc__)args.add_argument("stage", type=Path, help="melange --source-dir (only payload.tar.gz will be written)")output = args.parse_args().stage.resolve()diff --git a/docker/wolfi/release-sbom.py b/docker/wolfi/release-sbom.pyindex 3130a7585..548f7652d 100644--- a/docker/wolfi/release-sbom.py+++ b/docker/wolfi/release-sbom.py@@ -9,6 +9,18 @@ from urllib.parse import quotedef enrich(sbom, components):+ """Add installed npm packages, bundled tokenizer libraries, and native files to an SPDX document.++ Args:+ sbom (dict): apko's single-image SPDX document, updated in place.+ components (dict): public-components.json inventory produced for the same image.++ Returns:+ dict: The input document with containment relationships and a new document namespace.++ Raises:+ ValueError: The image manifest in the inventory differs from the one in the SBOM.+ """packages = sbom["packages"]image, = (p for p in packages if p["SPDXID"] in sbom["documentDescribes"])if image["name"] != components["image_manifest"]:diff --git a/docker/wolfi/snapshot-builder.py b/docker/wolfi/snapshot-builder.pyindex 601c77a61..4481c3c98 100644--- a/docker/wolfi/snapshot-builder.py+++ b/docker/wolfi/snapshot-builder.py@@ -14,11 +14,23 @@ REPO = "https://packages.wolfi.dev/os/" + ARCHclass NoRedirect(HTTPRedirectHandler):+ """Keep the APK downloader on the exact URLs recorded in the builder lock."""+def redirect_request(self, *args):return None # Only fetch the exact URLs in the lock.def stage_package(pkg, directory, fetch):+ """Write one APK into the staging directory, checking each locked byte range.++ Args:+ pkg (dict): Package record from the apko lock, including component checksums.+ directory (Path): Existing staging directory for x86_64 APKs.+ fetch (callable): Open the package URL with a timeout and return a binary stream.++ Raises:+ ValueError: The source, architecture, byte ranges, or digests differ from the lock.+ """name, version = pkg["name"], pkg["version"]filename = f"{name}-{version}.apk"if not all(re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9.+_~-]*", s) for s in (name, version)):@@ -47,6 +59,16 @@ def stage_package(pkg, directory, fetch):def snapshot(lock, output, fetch):+ """Publish the locked APKs under output/x86_64 after every package verifies.++ Args:+ lock (dict): Nonempty apko v1 builder lock.+ output (Path): New or empty repository directory.+ fetch (callable): URL opener passed to stage_package for each locked package.++ Raises:+ ValueError: The lock or destination is invalid, or a package fails verification.+ """if lock["version"] != "v1" or not lock["contents"]["packages"]:raise ValueError("Expected a nonempty apko v1 builder lock")output.mkdir(parents=True, exist_ok=True)diff --git a/docker/wolfi/tests/test_snapshot_builder.py b/docker/wolfi/tests/test_snapshot_builder.pyindex 84bb3acf7..79a6260eb 100644--- a/docker/wolfi/tests/test_snapshot_builder.py+++ b/docker/wolfi/tests/test_snapshot_builder.py@@ -1,3 +1,5 @@+"""Exercise snapshot publication against signed, unsigned, and corrupted APK byte streams."""+import base64import gzipimport hashlib@@ -11,6 +13,7 @@ snapshot = runpy.run_path(str(Path(__file__).resolve().parents[1] / "snapshot-budef fixture(name, signed):+ """Return an apko lock record and the matching gzip members for one synthetic APK."""# APK v2 stores consecutive, independently compressed gzip members.url = f"https://packages.wolfi.dev/os/x86_64/{name}-1-r0.apk"pkg = {"name": name, "version": "1-r0", "url": url, "architecture": "x86_64"}@@ -28,6 +31,8 @@ def fixture(name, signed):class SnapshotTest(unittest.TestCase):+ """Stage packages in a temporary directory using an in-memory URL opener."""+def setUp(self):self.first, self.a = fixture("first", signed=False)self.second, self.b = fixture("second", signed=True)diff --git a/docker/wolfi/tests/test_tokenizer_inventory.py b/docker/wolfi/tests/test_tokenizer_inventory.pyindex ff769926b..81c91802c 100644--- a/docker/wolfi/tests/test_tokenizer_inventory.py+++ b/docker/wolfi/tests/test_tokenizer_inventory.py@@ -1,3 +1,5 @@+"""Check bundled tokenizer component identities and the legacy npm dependency fallback."""+import jsonimport runpyimport unittestdiff --git a/docker/wolfi/to-oci.py b/docker/wolfi/to-oci.pyindex 1d7ad00ba..7fa08cabb 100644--- a/docker/wolfi/to-oci.py+++ b/docker/wolfi/to-oci.py@@ -15,6 +15,19 @@ from pathlib import Pathdef convert(archive, verification, destination):+ """Verify each image blob before publishing a new OCI layout.++ Args:+ archive (Path): Uncompressed, single-platform apko image tar.+ verification (Path): Matching verification.json from the verified release.+ destination (Path): New layout directory under an existing parent.++ Returns:+ str: OCI manifest digest, including the sha256 prefix.++ Raises:+ ValueError: The destination exists or an archive verification check fails.+ """if destination.exists() or destination.is_symlink():raise ValueError(f"Destination already exists: {destination}")expected = json.loads(verification.read_bytes())@@ -34,6 +47,7 @@ def convert(archive, verification, destination):return mdef copy_blob(name, desc):+ """Write a blob into the layout, verify its size and SHA-256, and return its staged path."""digest = desc["digest"]if not re.fullmatch(r"sha256:[0-9a-f]{64}", digest):raise ValueError(f"Invalid blob digest: {digest}")diff --git a/docker/wolfi/verify-public.py b/docker/wolfi/verify-public.pyindex bd50cb2aa..74802e224 100644--- a/docker/wolfi/verify-public.py+++ b/docker/wolfi/verify-public.py@@ -25,10 +25,12 @@ GPL-2.0-only GPL-2.0-or-later GPL-3.0-or-later LGPL-2.0-or-later LGPL-2.1 LGPL-2LGPL-2.1-or-later LGPL-3.0-or-later GCC-exception-3.1 libselinux-1.0 blessing CC-PDDC AND OR WITH""".split())def check(ok, message):+ """Exit with the supplied verification message when a release invariant fails."""if not ok:raise SystemExit(message)def check_license(name, expression):+ """Exit if the declared expression is empty or contains an unreviewed license term."""terms = set(re.findall(r"[\w.+-]+", expression or ""))check(terms and not (terms - LICENSES), f"Unreviewed license for {name}: {expression}")@@ -46,10 +48,12 @@ class HashingReader:@propertydef digest(self):+ """Return the OCI-style SHA-256 digest of the bytes read so far."""return "sha256:" + self.hash.hexdigest()def read_blob(tar, descriptor):+ """Return a parsed OCI JSON blob after checking its byte length and SHA-256."""data = tar.extractfile(descriptor["digest"]).read()check(len(data) == descriptor["size"] and "sha256:" + hashlib.sha256(data).hexdigest() == descriptor["digest"],f"OCI blob does not match descriptor: {descriptor['digest']}")@@ -57,6 +61,19 @@ def read_blob(tar, descriptor):def inspect_layer(fs):+ """Collect release evidence in one pass through the root filesystem.++ Args:+ fs (tarfile.TarFile): Open layer tar positioned for streaming reads.++ Returns:+ tuple: Raw package metadata by image path, npm manifests by install path,+ public APK keys by filename, and native file SHA-256 hashes by image path.++ Raises:+ SystemExit: The layer contains a melange.rsa file name or a non-file APK key,+ or lacks a regular entrypoint executable by the configured runtime user.+ """raw, manifests, keys, native = {}, {}, {}, {}executable = Falsefor ent in fs:@@ -84,6 +101,7 @@ def inspect_layer(fs):def inventory_apks(database, packages):+ """Return installed APK records sorted by name after checking them against the lock."""apks = []lock = {p["name"]:p for p in packages}for record in database.decode().strip().split("\n\n"):@@ -102,6 +120,7 @@ def inventory_apks(database, packages):def inventory_npm(manifests, packages, sources):+ """Match manifests to lockfile and attribution entries by install path and return the npm inventory."""paths = {p["path"] for p in sources}check(len(paths) == len(sources) and paths == manifests.keys(),"Installed npm package paths differ from SOURCES.json")@@ -125,6 +144,12 @@ def inventory_npm(manifests, packages, sources):def inventory_tokenizer(manifests, bom):+ """Return the bundled tokenizer's verified CycloneDX components.++ When a legacy image has no tokenizer BOM, verify that the installed+ js-tiktoken package matches the SDK dependency pin. Return an empty list+ because the npm inventory already includes that installation.+ """scanner = manifests[SCANNER]if bom is None:# Older releases installed the pinned tokenizer as an ordinary npm dependency.@@ -151,6 +176,18 @@ def inventory_tokenizer(manifests, bom):def verify(archive, lock):+ """Verify a local Linux/amd64 image and assemble its two release reports.++ Args:+ archive (Path): The apko image tar containing Docker and OCI manifests.+ lock (dict): The apko lock contents with the expected packages and keyring.++ Returns:+ dict: Report payloads keyed by verification.json and public-components.json.++ Raises:+ SystemExit: An explicit image, package, or source verification check fails.+ """with tarfile.open(archive) as tar:manifest, = json.load(tar.extractfile("manifest.json"))index, = json.load(tar.extractfile("index.json"))["manifests"]diff --git a/plugins/codex-security/mcp-app/tests/clock_workbench.py b/plugins/codex-security/mcp-app/tests/clock_workbench.pyindex 5225c226d..b306e0d42 100644--- a/plugins/codex-security/mcp-app/tests/clock_workbench.py+++ b/plugins/codex-security/mcp-app/tests/clock_workbench.py@@ -1,4 +1,8 @@-"""Control the workbench clock while retaining its real commands and database writes."""+"""Run a workbench command at TEST_WORKBENCH_NOW against its real database.++The first argument selects the workbench script. When TEST_WORKBENCH_RECEIPT_IO_FAILURE+is set, replacing an acceptance receipt raises ENOSPC so tests can observe recovery.+"""import errnoimport osdiff --git a/plugins/codex-security/scripts/deep_scan_config.py b/plugins/codex-security/scripts/deep_scan_config.pyindex a0e200ac5..3ee192f54 100644--- a/plugins/codex-security/scripts/deep_scan_config.py+++ b/plugins/codex-security/scripts/deep_scan_config.py@@ -34,12 +34,14 @@ CONFIG_KEYS = set(CONFIG_FIELDS.values())def codex_home() -> Path:+ """Expand CODEX_HOME, falling back to ~/.codex when the setting is empty or whitespace."""return Path(os.environ["CODEX_HOME"] if os.environ.get("CODEX_HOME", "").strip() else "~/.codex").expanduser()def config_path() -> Path:+ """Return the configured TOML path or the per-user config.toml under the Codex home."""configured = os.environ.get("CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH", "").strip()if configured:return Path(configured).expanduser()@@ -47,12 +49,28 @@ def config_path() -> Path:def resolve_deep_scan_config(available_parallelism: int) -> dict[str, int | float]:+ """Return the numeric deep scan settings for a launch with no project overrides."""return resolve_deep_scan_setup(available_parallelism)["settings"]def resolve_deep_scan_setup(available_parallelism: int, project_json: str | None = None) -> dict[str, Any]:+ """Resolve project overrides, per-user TOML settings, and bundled defaults in that order.++ Args:+ available_parallelism (int): Positive parallelism reported by the caller.+ The configured worker count is independent of this value.+ project_json (str | None): Serialized project configuration with path and settings keys.++ Returns:+ dict: Numeric settings and a source label for each, plus the paths of the+ supplied project configuration and any existing per-user configuration.++ Raises:+ SystemExit: A selected setting is invalid or a required TOML file cannot be read.+ json.JSONDecodeError: The supplied project JSON cannot be parsed.+ """project = json.loads(project_json) if project_json is not None else Noneoverrides = project["settings"] if project is not None else {}unknown = sorted(set(overrides) - set(CONFIG_FIELDS))@@ -106,6 +124,7 @@ def resolve_deep_scan_setup(def require_integer(value: object, label: str, *, minimum: int) -> int:+ """Return an integer at least minimum, accepting integral floats and raising SystemExit for invalid counts."""if isinstance(value, float) and value.is_integer():value = int(value)if isinstance(value, bool) or not isinstance(value, int) or value < minimum:@@ -121,6 +140,7 @@ def require_integer(value: object, label: str, *, minimum: int) -> int:def require_positive_number(value: object, label: str) -> int | float:+ """Return a duration in hours, raising SystemExit unless it falls in (0, 96]."""if isinstance(value, bool) or not isinstance(value, (int, float)):raise SystemExit(f"{label} must be a positive finite number no greater than 96.")if not 0 < value <= MAX_TIME_HOURS:diff --git a/plugins/codex-security/scripts/deep_scan_workbench.py b/plugins/codex-security/scripts/deep_scan_workbench.pyindex e2fb2e18d..635963ca3 100644--- a/plugins/codex-security/scripts/deep_scan_workbench.py+++ b/plugins/codex-security/scripts/deep_scan_workbench.py@@ -42,6 +42,7 @@ def dependencies() -> Any:def deep_scan_error(run: sqlite3.Row) -> str | None:+ """Return recorded error messages, publication error first, or None if both are absent."""original = run["error_message"]publication = run["publication_error_message"]if not isinstance(publication, str):@@ -68,6 +69,7 @@ def require_deep_scan_run(connection: sqlite3.Connection, scan_id: str) -> sqlitdef deep_scan_deadline_reached(run: sqlite3.Row) -> bool:+ """Return whether the time since run creation has reached its configured limit in hours."""elapsed = _parse_timestamp(dependencies().now()) - _parse_timestamp(str(run["created_at"]))return elapsed.total_seconds() / 3600 >= run["max_time_hours"]@@ -75,6 +77,11 @@ def deep_scan_deadline_reached(run: sqlite3.Row) -> bool:def require_deep_scan_ready_for_parent_completion(connection: sqlite3.Connection, scan: sqlite3.Row) -> None:+ """Require a succeeded discovery run with a saved manifest before a Deep Scan completes.++ For a capped run, also verify its workers have finished. Raise SystemExit+ when a completion requirement fails. Other scan modes can complete directly.+ """if scan["mode"] != "deep":returnrun = connection.execute(@@ -169,6 +176,7 @@ def require_deep_scan_workers_finished(def require_owned_scan(connection: sqlite3.Connection, scan_id: str, thread_id: str) -> tuple[sqlite3.Row, sqlite3.Row]:+ """Return the scan and workspace rows or raise SystemExit unless thread_id matches the recorded owner."""scan = dependencies().require_scan(connection, scan_id)workspace = dependencies().require_workspace(connection, scan["workspace_id"])owner = optional_text(thread_id, maximum=512)@@ -187,6 +195,7 @@ def deep_scan_path(*,kind: str,) -> str:+ """Return the canonical absolute path to an existing scan-local file or directory of the requested kind."""supplied = Path(value).expanduser()if not supplied.is_absolute():raise SystemExit(f"{label} must be an absolute path inside the scan directory.")@@ -206,6 +215,7 @@ def deep_scan_path(def deep_scan_output_path(scan: sqlite3.Row, value: str, label: str) -> str:+ """Validate an absolute output path under the scan directory, allowing a new file under an existing parent."""supplied = Path(value).expanduser()if not supplied.is_absolute():raise SystemExit(f"{label} must be an absolute path inside the scan directory.")@@ -219,6 +229,7 @@ def deep_scan_output_path(scan: sqlite3.Row, value: str, label: str) -> str:def promote_staged_file(staged_path: str, output_path: str) -> tuple[Path, Path, Path | None]:+ """Publish the staged file and return the paths needed to finalize or undo the move."""staged = Path(staged_path)output = Path(output_path)if staged == output:@@ -236,6 +247,7 @@ def promote_staged_file(staged_path: str, output_path: str) -> tuple[Path, Path,def rollback_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:+ """Move the published file back to staging and restore the previous output if present."""staged, output, backup = promotionif output.exists():os.replace(output, staged)@@ -244,12 +256,14 @@ def rollback_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:def finish_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:+ """Remove the previous output saved during promotion."""backup = promotion[2]if backup is not None:backup.unlink(missing_ok=True)def publication_matches_snapshot(publication: Path, snapshot: Path) -> bool:+ """Return whether the publication and snapshot identify the same file or contain identical bytes."""try:if publication.samefile(snapshot):return True@@ -279,6 +293,11 @@ def canonical_discovery_artifacts(scan: sqlite3.Row) -> dict[str, str]:def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, Any]:+ """Return persisted orchestration state including settings, workers, artifacts, and deduplication inputs.++ Order workers by creation time and ID. Retain the recorded order of each+ deduplication worker’s discovery inputs.+ """run = require_deep_scan_run(connection, scan_id)scan = dependencies().require_scan(connection, run["scan_id"])worker_rows = saved_deep_workers(connection, scan)@@ -372,6 +391,7 @@ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, Adef independent_review_progress(connection: sqlite3.Connection, scan_id: str) -> dict[str, int | str] | None:+ """Return completed and allowed review counts and the consolidation state, or None for a missing run."""run = connection.execute("""SELECT completion_sequence, phase, updated_at, max_discovery_runs@@ -435,6 +455,7 @@ def deep_scan_result(def effective_deep_scan_config(args: argparse.Namespace, workspace: sqlite3.Row | None = None) -> dict[str, Any]:+ """Use persisted workspace settings when available, otherwise resolve the current launch configuration."""if workspace is not None and workspace["deep_scan_config_json"] is not None:return json.loads(workspace["deep_scan_config_json"])available_parallelism = args.available_parallelism or os.cpu_count() or 1@@ -451,6 +472,7 @@ def ensure_deep_scan_run(service_tier: str | None,pending_target_project_path: str | None = None,) -> sqlite3.Row:+ """Return the existing orchestration row or initialize one for a running Deep Scan with the supplied settings."""existing = connection.execute("SELECT * FROM deep_scan_runs WHERE scan_id = ?", (scan["id"],)).fetchone()@@ -819,6 +841,7 @@ def begin_deep_scan_for_target(def begin_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:+ """Begin orchestration for a registered scan or a target, returning the scan state and its start disposition."""thread_id = optional_text(args.thread_id, maximum=512)if thread_id is None:raise SystemExit("thread-id is required.")@@ -832,6 +855,7 @@ def begin_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) ->def get_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:+ """Return the persisted orchestration result to the thread that owns the scan."""scan, _ = require_owned_scan(connection, args.scan_id, args.thread_id)return deep_scan_result(connection, scan["id"])@@ -860,6 +884,7 @@ def coordinator_lease_is_live(scan: sqlite3.Row,timestamp: str,) -> bool:+ """Check coordinator freshness using the lease generation and its applicable activity timestamps."""if run["coordinator_generation"] == 1:active_worker = connection.execute("""@@ -923,7 +948,8 @@ def claim_deep_scan_coordinator_locked(args.claim_token,error_message="Deep Scan orchestration is owned by another continuation.",)- run, _ = require_running_deep_scan(connection, scan_id)+ run = require_deep_scan_run(connection, scan_id)+ require_running_deep_scan(run, scan)timestamp = dependencies().now()if args.coordinator_generation is not None:require_current_coordinator(run, args)@@ -957,6 +983,7 @@ def claim_deep_scan_coordinator_locked(def recover_expired_coordinator(connection: sqlite3.Connection, run: sqlite3.Row, timestamp: str) -> None:+ """Recover interrupted publications and reset active work so a replacement coordinator can resume."""scan_id = run["scan_id"]recover_candidate_ledger_publication(connection, scan_id)legacy_generation = int(run["coordinator_generation"] == 1)@@ -1032,6 +1059,7 @@ def recover_expired_coordinator(def recover_candidate_ledger_publication(connection: sqlite3.Connection, scan_id: str) -> None:+ """Reconcile ledger backups with reducer snapshots after an interrupted publication."""scan = dependencies().require_scan(connection, scan_id)ledger = Path(scan["scan_dir"]) / "artifacts" / "02_discovery" / "candidate_ledger.jsonl"backups = sorted(@@ -1069,26 +1097,11 @@ def recover_candidate_ledger_publication(connection: sqlite3.Connection, scan_idreturn-def require_deep_scan_worker(connection: sqlite3.Connection, worker_id: str) -> sqlite3.Row:- worker_id = require_uuid(worker_id, "worker-id")- row = connection.execute(- "SELECT * FROM deep_scan_workers WHERE id = ?", (worker_id,)- ).fetchone()- if row is None:- raise SystemExit("Codex Security Deep Scan worker not found.")- return row---def require_running_deep_scan(- connection: sqlite3.Connection, scan_id: str-) -> tuple[sqlite3.Row, sqlite3.Row]:- run = require_deep_scan_run(connection, scan_id)- scan = dependencies().require_scan(connection, run["scan_id"])+def require_running_deep_scan(run: sqlite3.Row, scan: sqlite3.Row) -> None:if run["status"] != "running" or run["cancel_requested"]:raise SystemExit("Only a running Deep Scan can update orchestration state.")if scan["status"] != "running" or scan["canceled_at"] is not None:raise SystemExit("Only a running scan can update Deep Scan orchestration state.")- return run, scandef require_worker_transition(current: str, requested: str) -> None:@@ -1146,7 +1159,7 @@ def upsert_deep_scan_worker(and args.status in {"succeeded", "failed", "canceled"})if not cleanup_update and not terminal_repeat:- require_running_deep_scan(connection, scan_id)+ require_running_deep_scan(run, scan)prompt_path = deep_scan_path(scan, args.prompt_path, "Worker prompt path", kind="file")artifact_dir = deep_scan_path(scan, args.artifact_dir, "Worker artifact directory", kind="directory"@@ -1351,13 +1364,19 @@ def upsert_deep_scan_worker(def record_deep_scan_iteration(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:- """Commit the host-computed union and its Standard scans in one transaction."""+ """Commit the checkpoint and its input workers in one transaction, then return deep scan state.++ Repeating the same iteration and inputs replays the saved result. Conflicting+ checkpoint or input-worker IDs raise SystemExit.+ """scan_id = require_uuid(args.scan_id, "scan-id")checkpoint_id = require_uuid(args.worker_id, "worker-id")input_ids = [require_uuid(value, "input-worker-id") for value in args.input_worker_id]connection.execute("BEGIN IMMEDIATE")with connection:- run, scan = require_running_deep_scan(connection, scan_id)+ run = require_deep_scan_run(connection, scan_id)+ scan = dependencies().require_scan(connection, scan_id)+ require_running_deep_scan(run, scan)require_current_coordinator(run, args)result = deep_scan_path(scan, args.result_manifest_path, "Iteration result", kind="file")existing = connection.execute(@@ -1419,10 +1438,10 @@ def finish_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -def finish_deep_scan_locked(connection: sqlite3.Connection, args: argparse.Namespace, scan_id: str) -> dict[str, Any]:- omitted_worker_ids = [+ omitted_worker_ids = {require_uuid(value, "omitted-worker-id") for value in args.omitted_worker_id- ]- if len(set(omitted_worker_ids)) != len(omitted_worker_ids):+ }+ if len(omitted_worker_ids) != len(args.omitted_worker_id):raise SystemExit("Omitted Deep Scan worker IDs must be unique.")promotion: tuple[Path, Path, Path | None] | None = Nonedeadline_publication: (@@ -1442,24 +1461,19 @@ def finish_deep_scan_locked()standard_scan_manifest = manifest_path == str(Path(scan["scan_dir"]) / "scan-manifest.json")- buffered_worker_ids = [+ buffered_worker_ids = {row["id"]for row in connection.execute("""SELECT idFROM deep_scan_workersWHERE scan_id = ? AND kind = 'discovery' AND merge_state = 'buffered'- ORDER BY completion_sequence, id""",(scan_id,),)- ]+ }# Historical succeeded runs retain their exact omitted-worker replay contract.- omissions_match = (- set(omitted_worker_ids) == set(buffered_worker_ids)- if args.terminal_reason == "saturated" or run["status"] == "succeeded"- else not omitted_worker_ids and not buffered_worker_ids- )+ omissions_match = omitted_worker_ids == buffered_worker_idsif run["status"] == "succeeded":if (run["terminal_reason"] != args.terminal_reason@@ -1478,7 +1492,7 @@ def finish_deep_scan_locked()connection.commit()return deep_scan_result(connection, scan_id)- require_running_deep_scan(connection, scan_id)+ require_running_deep_scan(run, scan)if run["error_message"] is not None:raise SystemExit(run["error_message"])if (@@ -1795,6 +1809,7 @@ def cancel_active_workers(connection: sqlite3.Connection, scan_id: str, timestamdef other_running_deep_scans(connection: sqlite3.Connection, current_scan_id: str) -> list[dict[str, str]]:+ """List other running Deep Scans ordered by most recent update, with target paths and phases."""rows = connection.execute("""SELECT id, target_path, phase, started_at, updated_atdiff --git a/plugins/codex-security/scripts/filesystem_identity.py b/plugins/codex-security/scripts/filesystem_identity.pyindex 91d6c5346..541c84a72 100644--- a/plugins/codex-security/scripts/filesystem_identity.py+++ b/plugins/codex-security/scripts/filesystem_identity.py@@ -19,6 +19,7 @@ def serialize_filesystem_identity(value: int) -> int | str:def stored_filesystem_identity_matches(stored: object, current: int) -> bool:+ """Compare a stored SQLite value with the platform file ID in its database representation."""return stored == serialize_filesystem_identity(current)diff --git a/plugins/codex-security/scripts/finalize_scan_contract.py b/plugins/codex-security/scripts/finalize_scan_contract.pyindex 705238561..a10e49efb 100644--- a/plugins/codex-security/scripts/finalize_scan_contract.py+++ b/plugins/codex-security/scripts/finalize_scan_contract.py@@ -862,6 +862,11 @@ def stage_scan_local_bytes(owner_read_write: bool = False,replace_existing: bool = False,) -> Iterator[Callable[..., tuple[os.stat_result, int]]]:+ """Stage payload under the scan directory and yield a callback that publishes it.++ Call the callback inside the context to get file metadata and a platform-specific+ change-time token. Leaving without publishing discards the staged write.+ """scan_dir, relative_path = _scan_local_write_path(scan_dir, relative_path, external_name)if not _descriptor_relative_writes_available():if not _is_windows():@@ -2780,6 +2785,7 @@ def _read_sealed_scan(def build_sarif_projection(scan_dir: Path, source_root: Path | None = None, schema_dir: Path | None = None) -> dict[str, Any]:+ """Build SARIF for a sealed scan, using the optional source directory to resolve locations."""if source_root is not None:try:source_root = source_root.resolve(strict=True)@@ -2892,6 +2898,7 @@ def finding_csv_columns(deep_scan: bool) -> tuple[str, ...]:def build_csv_projection(findings: dict[str, Any], coverage: dict[str, Any]) -> bytes:+ """Encode findings in input order as UTF-8 CSV using the columns selected by coverage and findings."""output = io.StringIO(newline="")writer = csv.writer(output)deep_scan = report_projection.uses_deep_presentation(coverage, findings["findings"])@@ -2935,6 +2942,11 @@ def build_findings_export(schema_dir: Path | None = None,avit_template: Path | None = None,) -> bytes:+ """Return bytes for the requested export of a sealed scan.++ JSON preserves the sealed findings bytes. SARIF can use source_root to resolve+ locations. ServiceNow AVIT requires an application template.+ """if export_format not in EXPORT_PATHS:raise ContractError(f"unsupported export format: {export_format}")if export_format == "sarif":@@ -3058,6 +3070,8 @@ def _write_sarif_projection_if_possible(class PreparedScanFinalization(NamedTuple):+ """Validated in-memory scan documents, rendered report bytes, and warnings awaiting publication."""+scan_dir: Pathschema_dir: Pathmanifest: dict[str, Any]@@ -3069,6 +3083,7 @@ class PreparedScanFinalization(NamedTuple):def manifest_is_sealed(scan: dict[str, Any]) -> bool:+ """Return whether the manifest records a seal time or sealed artifacts."""return scan.get("sealedAt") is not None or scan.get("artifacts") not in (None, [])diff --git a/plugins/codex-security/scripts/finding_preview.py b/plugins/codex-security/scripts/finding_preview.pyindex d943a9cbe..7754d155e 100644--- a/plugins/codex-security/scripts/finding_preview.py+++ b/plugins/codex-security/scripts/finding_preview.py@@ -27,6 +27,11 @@ from workbench_constants import (def bounded_finding_details(value: Any) -> dict[str, Any]:+ """Build the workbench preview of a stored finding, returning an empty dict for non-object input.++ Budget for writeup text, diagnostics, and guidance alongside code evidence so a+ large snippet cannot consume the whole preview.+ """if not isinstance(value, dict):return {}prepared: dict[str, Any] = {}@@ -251,6 +256,7 @@ def bounded_finding_section(priority_keys: tuple[str, ...],reserved_fields: tuple[tuple[tuple[str, ...], int], ...],) -> Any:+ """Apply each field group’s size cap before selecting fields in priority order under the section cap."""if not isinstance(value, dict):return bounded_json_value(value, [maximum_bytes])ordered: dict[str, Any] = {}@@ -270,6 +276,12 @@ def bounded_finding_section(def merged_bounded_code_evidence(value: dict[str, Any]) -> tuple[str | None, Any]:+ """Return the preferred evidence key and the preview data to store under it.++ Merge camelCase and snake_case catalogs by evidence ID, keeping the first+ eligible snippet per ID. Return (None, None) if both keys are absent.+ If neither value is a list, preserve the first supplied value.+ """evidence_keys = [key for key in ("codeEvidence", "code_evidence") if key in value]if not evidence_keys:return None, None@@ -315,6 +327,7 @@ def merged_bounded_code_evidence(value: dict[str, Any]) -> tuple[str | None, Anydef json_size(value: Any) -> int:+ """Return the byte count of the compact, ASCII-escaped JSON representation."""# ASCII output gives byte length; strings can use the cached default encoder.return len(json.dumps(value, separators=None if isinstance(value, str) else (",", ":")))@@ -326,6 +339,7 @@ def bounded_json_value(depth: int = 0,max_depth: int = 4,) -> Any:+ """Build a depth-limited preview while charging its JSON representation to the shared byte budget."""if budget[0] <= 0:return Noneif depth >= max_depth:@@ -415,6 +429,7 @@ def bounded_json_value(def consume_json_budget(budget: list[int], size: int) -> bool:+ """Deduct the requested size and return whether it fit, exhausting the budget on failure."""if budget[0] < size:budget[0] = 0return False@@ -423,6 +438,11 @@ def consume_json_budget(budget: list[int], size: int) -> bool:def bounded_json_text(value: str, maximum_bytes: int) -> tuple[str, int]:+ """Return a string prefix and its ASCII-escaped JSON size in bytes.++ Count the surrounding quotes and escape sequences toward maximum_bytes.+ If even the empty string exceeds the budget, return the empty string and 2.+ """length = bisect_right(range(min(len(value), maximum_bytes) + 1), maximum_bytes, key=lambda n: json_size(value[:n]))diff --git a/plugins/codex-security/scripts/posix_scan_local_files.py b/plugins/codex-security/scripts/posix_scan_local_files.pyindex 021eaa2a4..5df348ab1 100644--- a/plugins/codex-security/scripts/posix_scan_local_files.py+++ b/plugins/codex-security/scripts/posix_scan_local_files.py@@ -14,6 +14,7 @@ from pathlib import Path, PurePosixPathdef descriptor_relative_writes_available() -> bool:+ """Return whether the platform supports the descriptor-relative operations used for writes."""# os.replace accepts src_dir_fd/dst_dir_fd wherever descriptor-relative# os.rename is supported, but Python lists only os.rename in supports_dir_fd.required_operations = (os.mkdir, os.open, os.rename, os.stat, os.unlink)@@ -24,6 +25,7 @@ def descriptor_relative_writes_available() -> bool:@contextmanagerdef managed_fd(descriptor: int) -> Iterator[int]:+ """Yield the descriptor and close it when the context exits, including on error."""try:yield descriptorfinally:@@ -34,6 +36,7 @@ def managed_fd(descriptor: int) -> Iterator[int]:def stage_file(parent_fd: int, filename: str, payload: bytes, owner_read_write: bool) -> Iterator[int]:+ """Yield a synced file descriptor for a new staging entry, removing the entry on exit if it still matches."""descriptor = os.open(filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=parent_fd)try:with os.fdopen(descriptor, "wb", closefd=False) as handle:@@ -56,6 +59,7 @@ def stage_file(def _rename_exclusive(parent_fd: int, source: str, destination: str) -> None:+ """Rename a directory entry atomically while requiring the destination to be absent."""import ctypeslibc = ctypes.CDLL(None, use_errno=True)@@ -87,6 +91,7 @@ def _rename_exclusive(parent_fd: int, source: str, destination: str) -> None:def publish_new_file(parent_fd: int, source: str, destination: str) -> None:+ """Publish the staged name without overwriting the destination, using an exclusive rename if linking is unavailable."""try:os.link(source, destination, src_dir_fd=parent_fd, dst_dir_fd=parent_fd, follow_symlinks=False@@ -118,6 +123,12 @@ def stage_write(check_parent: Callable[[Path], None],contract_error: type[ValueError],) -> Iterator[Callable[..., tuple[os.stat_result, int]]]:+ """Stage payload under the open parent directory and yield a callable that publishes it.++ Call the publisher inside the context. It returns file metadata and the+ change time in nanoseconds. With compare_existing, matching bytes can+ reuse an existing file when replacements are allowed.+ """name = PurePosixPath(relative_path).name# Stage through the held parent so a replacement path cannot redirect the write.try:diff --git a/plugins/codex-security/scripts/report_projection.py b/plugins/codex-security/scripts/report_projection.pyindex 56cb6e809..b6a0a329b 100644--- a/plugins/codex-security/scripts/report_projection.py+++ b/plugins/codex-security/scripts/report_projection.py@@ -14,6 +14,13 @@ from typing import AnySEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "informational": 4}CONFIDENCE_ORDER = {"high": 0, "medium": 1, "low": 2}REPORTABLE_SEVERITIES = {"critical", "high", "medium", "low"}+THREAT_MODEL_SECTIONS = (+ ("Assets", "assets"),+ ("Trust Boundaries", "trustBoundaries"),+ ("Attacker Capabilities", "attackerCapabilities"),+ ("Security Objectives", "securityObjectives"),+ ("Assumptions", "assumptions"),+)DISPOSITION_LABELS = {"reported": "Reported","no_issue_found": "No issue found",@@ -31,6 +38,14 @@ class ReportProjectionError(ValueError):"""Raised when a canonical scan cannot be projected into a valid report."""+def markdown_threat_model_content(model: dict[str, Any]) -> str | None:+ """Return nonblank authored content for a Markdown model, otherwise None."""+ content = model.get("content")+ if model.get("format") == "markdown" and isinstance(content, str) and content.strip():+ return content+ return None++def _escape_markdown(value: str) -> str:# Locate whole URLs before matching code spans: a URL can contain backticks.urls = [match.span() for match in re.finditer(WWW_LINK_RE, value)]@@ -135,6 +150,7 @@ def _has_deep_child_metadata(finding: dict[str, Any]) -> bool:def uses_deep_presentation(coverage: dict[str, Any], findings: list[dict[str, Any]]) -> bool:+ """Select deep-report formatting for repository scans in deep mode and scoped scans with deep-child metadata."""if coverage.get("mode") == "deep_repository":return Trueif coverage.get("mode") != "scoped_path":@@ -167,15 +183,6 @@ def _deep_title_parts(finding: dict[str, Any], report_id: str) -> tuple[str, strreturn normalized, None-def _deep_finding_groups(- findings: list[dict[str, Any]], writeup_paths: list[str | None]-) -> list[list[tuple[int, dict[str, Any], str | None]]]:- groups: dict[str, list[tuple[int, dict[str, Any], str | None]]] = {}- for number, (finding, report_path) in enumerate(zip(findings, writeup_paths, strict=True), 1):- groups.setdefault(_deep_candidate_id(finding), []).append((number, finding, report_path))- return list(groups.values())--def _deep_group_levels(group: list[tuple[int, dict[str, Any], str | None]],field: str,@@ -242,6 +249,7 @@ def _bullet_section(heading: str, items: list[str]) -> list[str]:def code_evidence_rows(*catalogs: Any) -> Iterator[dict[str, Any]]:+ """Yield evidence objects with nonblank code in their original order."""for items in catalogs:if isinstance(items, list):yield from (@@ -254,6 +262,7 @@ def code_evidence_rows(*catalogs: Any) -> Iterator[dict[str, Any]]:def embedded_code_evidence(section: dict[str, Any]) -> Iterator[dict[str, Any]]:+ """Collect code evidence from both supported field spellings."""return code_evidence_rows(section.get("codeEvidence"), section.get("code_evidence"))@@ -282,6 +291,7 @@ def _section_code_evidence(def merged_root_cause(value: dict[str, Any]) -> tuple[str | None, Any]:+ """Return the first recorded root-cause field name and its merged detail, or (None, None) if absent."""keys = [key for key in ("rootCause", "root_cause") if key in value]if not keys:return None, None@@ -743,6 +753,16 @@ def _linked_finding_section(number: int, finding: dict[str, Any], report_path: sdef build_report_markdown(manifest: dict[str, Any], findings_document: dict[str, Any], coverage: dict[str, Any]) -> str:+ """Render findings and review coverage as a Markdown report ending in a newline.++ Args:+ manifest: Scan metadata, target, and scope.+ findings_document: Canonical findings for the scan.+ coverage: Review coverage for older manifests. Newer scans supply review state inline.++ Raises:+ ReportProjectionError: Reportable findings share a writeup path.+ """scan = manifest["scan"]if "review" in scan and "coverageRef" not in scan:from review_state import review_state@@ -759,19 +779,23 @@ def build_report_markdown(),key=_finding_sort_key,)- writeup_paths = [_writeup_report_path(finding) for finding in findings]- duplicate_writeup_paths = sorted(- path- for path, count in Counter(path for path in writeup_paths if path is not None).items()- if count > 1- )+ numbered_findings = [+ (number, finding, _writeup_report_path(finding))+ for number, finding in enumerate(findings, 1)+ ]+ writeup_counts = Counter(path for _, _, path in numbered_findings if path is not None)+ duplicate_writeup_paths = sorted(path for path, count in writeup_counts.items() if count > 1)if duplicate_writeup_paths:raise ReportProjectionError("reportable findings have duplicate writeup reportPath values: "+ ", ".join(duplicate_writeup_paths))deep_presentation = uses_deep_presentation(coverage, findings)- deep_finding_groups = _deep_finding_groups(findings, writeup_paths) if deep_presentation else []+ deep_finding_groups: dict[str, list[tuple[int, dict[str, Any], str | None]]] = {}+ if deep_presentation:+ for entry in numbered_findings:+ _, finding, _ = entry+ deep_finding_groups.setdefault(_deep_candidate_id(finding), []).append(entry)hardening_portfolio_path = _hardening_portfolio_path(scan)include_paths = [_path_text(path) for path in coverage.get("includePaths", scope.get("includePaths", []))@@ -840,8 +864,8 @@ def build_report_markdown("",])- content = threat_model.get("content")- if threat_model.get("format") == "markdown" and isinstance(content, str) and content.strip():+ content = markdown_threat_model_content(threat_model)+ if content is not None:lines.append(content)else:lines.append(@@ -850,13 +874,7 @@ def build_report_markdown("No explicit canonical threat-model summary was recorded.",))- for heading, key in (- ("Assets", "assets"),- ("Trust Boundaries", "trustBoundaries"),- ("Attacker Capabilities", "attackerCapabilities"),- ("Security Objectives", "securityObjectives"),- ("Assumptions", "assumptions"),- ):+ for heading, key in THREAT_MODEL_SECTIONS:values = _strings(threat_model.get(key))if values:lines.extend(["", f"### {heading}", "", *(f"- {value}" for value in values)])@@ -881,7 +899,7 @@ def build_report_markdown("| --- | --- | --- | --- | --- |",])- lines.extend(_deep_group_row(group) for group in deep_finding_groups)+ lines.extend(_deep_group_row(group) for group in deep_finding_groups.values())else:lines.extend([@@ -889,9 +907,7 @@ def build_report_markdown("| --- | --- | --- | --- |",])- for number, (finding, report_path) in enumerate(- zip(findings, writeup_paths, strict=True), 1- ):+ for number, finding, report_path in numbered_findings:title = _cell(finding["title"])finding_link = f"[{title}](#finding-{number})"writeup_link = f"[Open report]({report_path})" if report_path else "inline below"@@ -911,9 +927,7 @@ def build_report_markdown("| low | Evidence is incomplete and the item is retained only for explicit follow-up. |",])- for number, (finding, report_path) in enumerate(- zip(findings, writeup_paths, strict=True), 1- ):+ for number, finding, report_path in numbered_findings:if report_path is not None:lines.extend(["", *_linked_finding_section(number, finding, report_path)])else:@@ -1018,6 +1032,7 @@ def generate_report_markdown(findings: dict[str, Any],coverage: dict[str, Any],) -> bytes:+ """Return the Markdown report for the scan as UTF-8 bytes ready to write."""return build_report_markdown(manifest, findings, coverage).encode("utf-8")diff --git a/plugins/codex-security/scripts/review_state.py b/plugins/codex-security/scripts/review_state.pyindex 17554e6c9..cdfd6bcbd 100644--- a/plugins/codex-security/scripts/review_state.py+++ b/plugins/codex-security/scripts/review_state.py@@ -8,17 +8,23 @@ from typing import Anydef uses_legacy_review(scan: dict[str, Any]) -> bool:+ """Return whether the manifest points to separate coverage or predates inline review metadata."""return "coverageRef" in scan or ("reviewState" not in scan and "review" not in scan)def review_summary(state: dict[str, Any]) -> dict[str, Any]:+ """Return the excluded path patterns in the compact form stored on the scan manifest."""return {"excludedPaths": [item["pattern"] for item in state.get("explicitExclusions", [])],}def review_state(scan: dict[str, Any]) -> dict[str, Any]:- """Read new manifest metadata using the recovery code's existing representation."""+ """Build the recovery coverage record from inline manifest metadata.++ Copy the saved review state, deriving exclusions from the summary when needed,+ and attach the inventory strategy and scope for this scan.+ """summary = scan.get("review", {})state = copy.deepcopy(scan.get("reviewState", {}))mode = scan.get("mode", "repository")@@ -48,7 +54,7 @@ def review_state(scan: dict[str, Any]) -> dict[str, Any]:def checkpoint_review_state(state: dict[str, Any]) -> dict[str, Any]:- """Retain unfinished work and candidate outcomes, without a coverage report."""+ """Copy the review data needed for recovery, omitting per-surface risk areas and report metadata."""return {"surfaces": [{key: copy.deepcopy(value) for key, value in item.items() if key != "riskArea"}diff --git a/plugins/codex-security/scripts/servicenow_avit.py b/plugins/codex-security/scripts/servicenow_avit.pyindex 3e9710926..04a33c5db 100644--- a/plugins/codex-security/scripts/servicenow_avit.py+++ b/plugins/codex-security/scripts/servicenow_avit.py@@ -32,6 +32,16 @@ AVIT_FINDING_FIELDS = (def read_template(path: Path) -> tuple[list[str], dict[str, str]]:+ """Read the application defaults for a ServiceNow AVIT export from a UTF-8 CSV.++ Returns:+ tuple: The original column headings and a mapping of stripped, case-folded+ headings to values from the single application row.++ Raises:+ ValueError: The file is unreadable, required columns are missing or+ duplicated, or application values are empty or too long.+ """try:with path.open(encoding="utf-8-sig", newline="") as source:rows = (row for row in csv.reader(source, strict=True) if row)@@ -62,6 +72,11 @@ def _narrative(text: str) -> str:def finding_fields(finding: dict[str, Any], location: dict[str, Any], steps: str) -> dict[str, str]:+ """Return AVIT columns for a finding at the selected location with the recorded steps.++ Use the first recognized CWE as the category, or the finding ID as the+ vulnerability ID when no CWE qualifies. Both narrative fields fit in 1,000 characters.+ """details = (f"{finding['findingId']} | {location['path']}:{location['startLine']}\n"f"{finding['title']}\n{finding['summary']}\n{finding['remediation']}"@@ -85,6 +100,11 @@ def finding_fields(finding: dict[str, Any], location: dict[str, Any], steps: strdef render(template: Path, rows: Iterable[dict[str, str]]) -> bytes:+ """Return UTF-8 CSV bytes with the template's header and one row per finding.++ The template supplies application fields and column order. For nonempty input,+ write the count of findings missing reproduction steps to stderr.+ """headers, row = read_template(template)output = io.StringIO(newline="")writer = csv.writer(output)diff --git a/plugins/codex-security/scripts/snapshot_sqlite.py b/plugins/codex-security/scripts/snapshot_sqlite.pyindex e91d81a75..4d8f7a3dc 100644--- a/plugins/codex-security/scripts/snapshot_sqlite.py+++ b/plugins/codex-security/scripts/snapshot_sqlite.py@@ -10,6 +10,7 @@ from urllib.parse import quotedef main() -> None:+ """Back up the read-only source database into a separate destination using SQLite’s backup API."""parser = argparse.ArgumentParser(description=__doc__)parser.add_argument("source", type=Path)parser.add_argument("destination", type=Path)diff --git a/plugins/codex-security/scripts/threat_model_projection.py b/plugins/codex-security/scripts/threat_model_projection.pyindex ff17b7334..30e06043b 100644--- a/plugins/codex-security/scripts/threat_model_projection.py+++ b/plugins/codex-security/scripts/threat_model_projection.py@@ -6,7 +6,6 @@ from __future__ import annotationsimport argparseimport jsonimport sys-from collections.abc import Callablefrom pathlib import Pathfrom typing import Any@@ -14,14 +13,6 @@ from typing import Anysys.path.insert(0, str(Path(__file__).resolve().parent))import report_projection as report-_STRUCTURED_SECTIONS = (- ("Assets", "assets"),- ("Trust Boundaries", "trustBoundaries"),- ("Attacker Capabilities", "attackerCapabilities"),- ("Security Objectives", "securityObjectives"),- ("Assumptions", "assumptions"),-)-def _is_structured_model(model: dict[str, Any]) -> bool:summary = model.get("summary")@@ -31,21 +22,18 @@ def _is_structured_model(model: dict[str, Any]) -> bool:and all(isinstance(values := model.get(key, []), list)and all(isinstance(value, str) and value for value in values)- for _, key in _STRUCTURED_SECTIONS+ for _, key in report.THREAT_MODEL_SECTIONS))-def _markdown_content(model: dict[str, Any]) -> str | None:- content = model.get("content")- if model.get("format") == "markdown" and isinstance(content, str) and content.strip():- return content- return None--def threat_model_body(model: dict[str, Any]) -> str:- """Keep authored Markdown intact, including summaries from older scans."""- content = _markdown_content(model)+ """Return the authored Markdown body verbatim or render a legacy summary and its sections.++ Raises:+ ValueError: Required content is absent or the saved model has invalid metadata or sections.+ """+ content = report.markdown_threat_model_content(model)if content is not None:# The structured schema permits legacy metadata as extension fields.if _is_structured_model(model):@@ -82,7 +70,7 @@ def threat_model_body(model: dict[str, Any]) -> str:sections = [summary if summary.strip() else "No explicit canonical threat-model summary was recorded."]- for heading, key in _STRUCTURED_SECTIONS:+ for heading, key in report.THREAT_MODEL_SECTIONS:values = model.get(key, [])if not isinstance(values, list):raise ValueError(f"threatModel.{key}: expected an array")@@ -96,7 +84,7 @@ def threat_model_body(model: dict[str, Any]) -> str:return "\n\n".join(sections)-def _scope_lines(scope: Any, label: str, text: Callable[[Any, str], str]) -> list[str]:+def _scope_lines(scope: Any, label: str) -> list[str]:# Older structured models may use these extension names for unrelated data.included = scope.get("includePaths") if isinstance(scope, dict) else Noneif not isinstance(included, list) or not all(isinstance(path, str) for path in included):@@ -109,14 +97,19 @@ def _scope_lines(scope: Any, label: str, text: Callable[[Any, str], str]) -> lislines.append(f"- {label} exclusions: {excluded_text or 'none'}")summary = scope.get("summary")if isinstance(summary, str) and summary:- lines.append(f"- {label} description: {text(summary, 'not recorded')}")+ lines.append(f"- {label} description: {report._text(summary, 'not recorded')}")return linesdef render_threat_model(model: dict[str, Any], provenance: dict[str, Any] | None = None) -> bytes:- """Render a portable document with authored content and recorded provenance."""+ """Return the saved threat model as UTF-8 Markdown, including its provenance footer.++ Args:+ model (dict): Authored Markdown or a legacy structured model from a scan.+ provenance (dict | None): Optional saved scan identifiers, scope, and provisional status.+ """body = threat_model_body(model)- if _markdown_content(model) is None:+ if report.markdown_threat_model_content(model) is None:body = "# Threat Model\n\n" + bodytext = report._textprovenance = provenance or {}@@ -132,10 +125,10 @@ def render_threat_model(model: dict[str, Any], provenance: dict[str, Any] | Noneif provenance.get(key):footer.append(f"- {label}: {text(str(provenance[key]), 'not recorded')}")footer.append(f"- Model origin: {text(model.get('origin'), 'not recorded')}")- footer.extend(_scope_lines(model.get("scope"), "Model scope", text))+ footer.extend(_scope_lines(model.get("scope"), "Model scope"))scan_scope = provenance.get("scanScope")if isinstance(scan_scope, dict):- footer.extend(_scope_lines(scan_scope, "Scan scope", text))+ footer.extend(_scope_lines(scan_scope, "Scan scope"))if provenance.get("provisional"):footer.extend(["", "This is a provisional model saved before successful completion."])return (body + ("\n" if body.endswith("\n") else "\n\n") + "\n".join(footer) + "\n").encode(@@ -144,6 +137,7 @@ def render_threat_model(model: dict[str, Any], provenance: dict[str, Any] | Nonedef main() -> int:+ """Render a JSON payload from stdin to UTF-8 Markdown on stdout and return zero on success."""parser = argparse.ArgumentParser(description=__doc__)parser.add_argument("--input-json-stdin", action="store_true", required=True)parser.parse_args()diff --git a/plugins/codex-security/scripts/validate_scan_contract.py b/plugins/codex-security/scripts/validate_scan_contract.pyindex 3e1849386..b8e9d0a6f 100644--- a/plugins/codex-security/scripts/validate_scan_contract.py+++ b/plugins/codex-security/scripts/validate_scan_contract.py@@ -15,7 +15,11 @@ import finalize_scan_contract as FINALIZERdef validate_contract(scan_dir: Path) -> dict[str, Any]:- """Return validated canonical documents for one sealed scan."""+ """Validate the sealed artifacts and return the manifest, original findings, and review summary.++ Legacy finding records are adapted for validation only. ContractError propagates+ when a required artifact, digest, schema, or evidence check fails.+ """scan_dir = FINALIZER._require_scan_directory(scan_dir.expanduser().resolve(strict=True))schema_dir = Path(__file__).resolve().parents[1] / "schemas"@@ -46,6 +50,7 @@ def validate_contract(scan_dir: Path) -> dict[str, Any]:def receipt(validated: dict[str, Any]) -> dict[str, Any]:+ """Return the CLI success payload with paths to the validated manifest, findings, and report."""scan_dir = Path(validated["scanDir"])scan = validated["manifest"]["scan"]return {@@ -58,6 +63,7 @@ def receipt(validated: dict[str, Any]) -> dict[str, Any]:def main(argv: list[str] | None = None) -> int:+ """Print the validation receipt on success or report a validation error to stderr and return 2."""parser = argparse.ArgumentParser(description=__doc__)parser.add_argument("--scan-dir", required=True, type=Path)args = parser.parse_args(argv)diff --git a/plugins/codex-security/scripts/windows_scan_local_files.py b/plugins/codex-security/scripts/windows_scan_local_files.pyindex 800c45442..a23cf8db0 100644--- a/plugins/codex-security/scripts/windows_scan_local_files.py+++ b/plugins/codex-security/scripts/windows_scan_local_files.py@@ -587,7 +587,11 @@ def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:def open_read_fd_with_path(scan_dir: Path, relative_path: str, context: str) -> tuple[int, str]:- """Return the descriptor and its filename while the verified parents are held."""+ """Return an owned read descriptor and the scan-relative path with the file's actual leaf name.++ Verify the regular file while holding its parent directories. The caller must+ close the returned descriptor.+ """try:with _locked_parent(scan_dir, relative_path, create=False, missing_is_path_error=False) as (@@ -636,6 +640,7 @@ def file_change_time(descriptor: int) -> int:def stream_matches_payload(stream: BinaryIO, payload: bytes) -> bool:+ """Compare bytes from the current stream position to payload, requiring EOF after the final byte."""offset = 0while offset < len(payload):chunk = stream.read(min(_MAX_COMPARE_CHUNK, len(payload) - offset))diff --git a/plugins/codex-security/scripts/workbench/__init__.py b/plugins/codex-security/scripts/workbench/__init__.pyindex 660a264fe..450800ad1 100644--- a/plugins/codex-security/scripts/workbench/__init__.py+++ b/plugins/codex-security/scripts/workbench/__init__.py@@ -1 +1 @@-"""Focused Codex Security workbench operation modules."""+"""Persist workbench state, transfer scan ownership, and recover results from saved artifacts."""diff --git a/plugins/codex-security/scripts/workbench/handoff.py b/plugins/codex-security/scripts/workbench/handoff.pyindex fa21ec8d5..1d64d8854 100644--- a/plugins/codex-security/scripts/workbench/handoff.py+++ b/plugins/codex-security/scripts/workbench/handoff.py@@ -12,6 +12,7 @@ RECOVERY_HANDOFF_TOKEN_PREFIX = "recovery_"def require_handoff_claim_token(value: str) -> str:+ """Normalize the claim UUID, retaining the prefix that marks a recovery handoff."""recovery_token = value.startswith(RECOVERY_HANDOFF_TOKEN_PREFIX)token = value.removeprefix(RECOVERY_HANDOFF_TOKEN_PREFIX) if recovery_token else valuenormalized = require_uuid(token, "claim-token")@@ -24,6 +25,7 @@ def require_current_continuation(*,error_message: str,) -> None:+ """Require the current claim token, allowing a tokenless continuation for legacy delivered scans."""if (scan["handoff_status"] == "delivered"and scan["handoff_claim_token"] is None@@ -41,6 +43,7 @@ def validate_handoff_delivery_thread(requesting_thread_id: str,claim_token: str,) -> None:+ """Require the owning thread for delivery unless the caller presents a recovery claim token."""if owning_thread_id != requesting_thread_id and not claim_token.startswith(RECOVERY_HANDOFF_TOKEN_PREFIX):@@ -54,6 +57,12 @@ def claim_handoff_delivery(connection: sqlite3.Connection,args: argparse.Namespace,) -> dict[str, Any]:+ """Claim a pending handoff and return the current workspace state.++ The first claim wins. When take_over_stale is requested, replacing an expired+ claim also clears the continuation and deep scan owner. Retrying the same claim+ or losing a competing claim returns the workspace state without changing ownership.+ """scan_id = require_uuid(args.scan_id, "scan-id")claim_token = require_handoff_claim_token(args.claim_token)timestamp = wb.now()@@ -102,6 +111,7 @@ def release_handoff_delivery(connection: sqlite3.Connection,args: argparse.Namespace,) -> dict[str, Any]:+ """Release a matching pending claim, detach its continuation, and return the workspace state."""scan_id = require_uuid(args.scan_id, "scan-id")claim_token = require_handoff_claim_token(args.claim_token)timestamp = wb.now()@@ -126,6 +136,11 @@ def attach_scan_continuation_thread(connection: sqlite3.Connection,args: argparse.Namespace,) -> dict[str, Any]:+ """Bind the claimed scan to a continuation and return its workspace state.++ An immediate transaction serializes ownership changes. Reattaching the same+ thread is idempotent. A different thread or mismatched claim token raises SystemExit.+ """scan_id = require_uuid(args.scan_id, "scan-id")claim_token = require_handoff_claim_token(args.claim_token)thread_id = optional_text(args.thread_id, maximum=512)@@ -165,6 +180,11 @@ def mark_handoff_delivered(connection: sqlite3.Connection,args: argparse.Namespace,) -> dict[str, Any]:+ """Record delivery for the pending claim and return the workspace state.++ For standard scans this resets preflight progress. The same claim can confirm+ delivery again. A conflicting claim or invalid requesting thread raises SystemExit.+ """scan_id = require_uuid(args.scan_id, "scan-id")claim_token = require_handoff_claim_token(args.claim_token)thread_id = optional_text(args.thread_id, maximum=512)diff --git a/plugins/codex-security/scripts/workbench/retained_coverage.py b/plugins/codex-security/scripts/workbench/retained_coverage.pyindex b4e394d3b..7329c0e0d 100644--- a/plugins/codex-security/scripts/workbench/retained_coverage.py+++ b/plugins/codex-security/scripts/workbench/retained_coverage.py@@ -116,7 +116,13 @@ def merge_saved_results(current_contract: bool = False,recovery_snapshot_error: _CheckpointSnapshotError | None = None,) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]] | None:- """Read only bound parent/worker files; return an unsealed loss-preserving union."""+ """Reconcile the bound parent and worker checkpoints into an unsealed scan draft.++ Return the manifest, findings document, and coverage document, or None when there+ is no saved input or the sealed parent already reflects the selected checkpoints.+ Frozen digests and heads identify the inputs selected when the scan stopped.+ Recovery appends diagnostics to the caller's warnings list.+ """initial_warnings = set(warnings)if frozen_source_digests is None:checkpoint_heads = {}@@ -621,18 +627,16 @@ def merge_saved_results(if previous is not None and isinstance(previous.get("id"), str):result["id"] = previous["id"]else:- surfaces = coverage.get("surfaces", [])if any(isinstance(row, dict) and row.get("id") == result["id"]- for row in (surfaces if isinstance(surfaces, list) else [])+ for row in _coverage_rows(coverage, "surfaces")):result["id"] = f"{result['id']}-{_digest(result)[:16]}"elif field == "deferred":result["id"] = f"{prefix}-deferred-{index}"if isinstance(item.get("surfaceIds"), list):surface_ids: dict[str, str] = {}- surfaces = projected_coverage.get("surfaces", [])- for surface in surfaces if isinstance(surfaces, list) else []:+ for surface in _coverage_rows(projected_coverage, "surfaces"):if not isinstance(surface, dict) or not isinstance(surface.get("id"), str):continueprovenance = surface.get("provenance", {})@@ -643,9 +647,8 @@ def merge_saved_results(and isinstance(provenance.get("sourceId"), str)):surface_ids.setdefault(provenance["sourceId"], surface["id"])- surfaces = source.get("surfaces", [])source_surface_ids: dict[str, tuple[int, dict[str, Any]]] = {}- for offset, surface in enumerate(surfaces if isinstance(surfaces, list) else [], 1):+ for offset, surface in enumerate(_coverage_rows(source, "surfaces"), 1):if isinstance(surface, dict) and isinstance(surface.get("id"), str):source_surface_ids.setdefault(surface["id"], (offset, surface))for (owner, source_id), accepted in accepted_surfaces.items():@@ -771,8 +774,7 @@ def merge_saved_results(for relative, draft, worker_id in sources:if relative not in accepted_sources:continue- surfaces = draft["reviewState"].get("surfaces", [])- for index, surface in enumerate(surfaces if isinstance(surfaces, list) else [], 1):+ for index, surface in enumerate(_coverage_rows(draft["reviewState"], "surfaces"), 1):if isinstance(surface, dict) and isinstance(surface.get("id"), str):accepted_surfaces.setdefault((worker_id, surface["id"]), []).append((index, surface)@@ -893,11 +895,7 @@ def merge_saved_results(surface_ids_by_source: dict[tuple[str, str], list[str]] = {(relative, row["id"]): []for relative, draft, _ in all_sources- for row in (- draft["reviewState"].get("surfaces", [])- if isinstance(draft["reviewState"].get("surfaces"), list)- else []- )+ for row in _coverage_rows(draft["reviewState"], "surfaces")if isinstance(row, dict) and isinstance(row.get("id"), str)}discarded_coverage_sources: set[str] = set()@@ -1155,8 +1153,7 @@ def merge_saved_results(retained_surface_rows: set[int] = set()for relative, draft, _ in all_sources:for field in ("surfaces", "deferred"):- rows = draft["reviewState"].get(field)- for row in rows if isinstance(rows, list) else []:+ for row in _coverage_rows(draft["reviewState"], field):if isinstance(row, dict):paths_for_row = coverage_sources.setdefault(id(row), (row, []))[1]if relative not in paths_for_row:@@ -1316,8 +1313,7 @@ def merge_saved_results(if isinstance(finding, dict) and valid_finding(finding)}for field in ("surfaces", "deferred", "explicitExclusions"):- rows = draft["reviewState"].get(field, [])- for index, row in enumerate(rows if isinstance(rows, list) else [], 1):+ for index, row in enumerate(_coverage_rows(draft["reviewState"], field), 1):if not isinstance(row, dict):continueif (@@ -1439,8 +1435,7 @@ def merge_saved_results(pending_surface_orders: dict[tuple[str | None, str], tuple[int, int]] = {}for relative, draft, owner in all_sources:- surfaces = draft["reviewState"].get("surfaces", [])- for surface in surfaces if isinstance(surfaces, list) else []:+ for surface in _coverage_rows(draft["reviewState"], "surfaces"):if (isinstance(surface, dict)and surface.get("disposition") == "needs_follow_up"@@ -3174,8 +3169,7 @@ def merge_saved_results(item = {"id": "scan-stopped", "reason": reason}if item not in coverage["deferred"]:coverage["deferred"].append(item)- surfaces = coverage.get("surfaces", [])- for surface in surfaces if isinstance(surfaces, list) else []:+ for surface in _coverage_rows(coverage, "surfaces"):if isinstance(surface, dict) and isinstance(surface.get("provenance"), dict):surface["provenance"].pop("scanReceiptRefs", None)if (diff --git a/plugins/codex-security/scripts/workbench/retained_records.py b/plugins/codex-security/scripts/workbench/retained_records.pyindex 4e84a755b..5b808dcf1 100644--- a/plugins/codex-security/scripts/workbench/retained_records.py+++ b/plugins/codex-security/scripts/workbench/retained_records.py@@ -20,6 +20,7 @@ from finalize_scan_contract import (_validate_schema_node,finding_candidate_id,)+from finalize_scan_contract import _schema_values_equal as same_raw_valuefrom workbench.saved_coverage import _coverage_rows, _saved_coverage_idfrom workbench.saved_sources import _digest, _encodedfrom workbench_coverage_receipts import resolve_coverage_receipts@@ -242,6 +243,7 @@ def _append_previous_finding(def _recover_preserved_worker_source(scan_dir, relative, scan_id, binding, worker_id, worker, draft, warnings):+ """Normalize findings and receipt references in the draft and return diagnostics for discarded findings."""discarded_findings = []# Recover imported records without relaxing canonical parent validation.if "complete" in draft and not isinstance(draft["complete"], bool):@@ -320,10 +322,10 @@ def _recover_preserved_worker_source(def _recover_preserved_worker_coverage(scan_dir, relative, worker_id, draft, discarded_findings, warnings):+ """Repair coverage in the draft, append source warnings, and return whether coverage was discarded."""discarded_coverage = Falsefor field in ("surfaces", "explicitExclusions", "deferred"):- rows = draft["reviewState"].get(field)- for row in rows if isinstance(rows, list) else []:+ for row in _coverage_rows(draft["reviewState"], field):if isinstance(row, dict):row.setdefault("id", _saved_coverage_id(row))if field == "surfaces":@@ -352,6 +354,7 @@ def _recover_preserved_worker_coverage(def identifiers(value: dict[str, Any]) -> tuple[Any, Any]:+ """Return the report ID and ledger row ID from extensions, using None for missing or blank IDs."""extensions = value.get("extensions")return tuple(identifier if _has_identity_text(identifier) else None@@ -363,6 +366,7 @@ def identifiers(value: dict[str, Any]) -> tuple[Any, Any]:def distinct_reports(left: dict[str, Any] | None, right: dict[str, Any] | None) -> bool:+ """Check the latest observations for conflicting report IDs or ledger row IDs."""return (left is not Noneand right is not None@@ -374,6 +378,7 @@ def distinct_reports(left: dict[str, Any] | None, right: dict[str, Any] | None)def raw_owner(value: dict[str, Any], source_owner: str | None) -> str | None:+ """Return the source owner, falling back to the worker ID recorded in finding provenance."""if source_owner is not None:return source_ownerprovenance = value.get("provenance", {})@@ -382,6 +387,7 @@ def raw_owner(value: dict[str, Any], source_owner: str | None) -> str | None:def raw_scope(value: dict[str, Any]) -> tuple[Any, ...]:+ """Return the rule, path, and line range of the first location used to match anonymous reports."""# Match scanFindingIdentity's primary location for anonymous reports.location = value["locations"][0]return (@@ -393,6 +399,7 @@ def raw_scope(value: dict[str, Any]) -> tuple[Any, ...]:def same_raw_finding(left: dict[str, Any], right: dict[str, Any]) -> bool:+ """Check whether semantic identities match or, in their absence, whether candidate and report IDs are compatible."""if isinstance(left.get("identity"), dict) and isinstance(right.get("identity"), dict):return _semantic_identity_key(left, _finding_identity(left)) == _semantic_identity_key(right, _finding_identity(right)@@ -409,24 +416,9 @@ def same_raw_finding(left: dict[str, Any], right: dict[str, Any]) -> bool:return True-def same_raw_value(left: Any, right: Any) -> bool:- if isinstance(left, dict):- return (- isinstance(right, dict)- and left.keys() == right.keys()- and all(same_raw_value(value, right[key]) for key, value in left.items())- )- if isinstance(left, list):- return (- isinstance(right, list)- and len(left) == len(right)- and all(same_raw_value(a, b) for a, b in zip(left, right, strict=True))- )- # JSON numbers compare by value, but booleans are a distinct scalar type.- return isinstance(left, bool) == isinstance(right, bool) and left == right--def same_raw_content(left: dict[str, Any], right: dict[str, Any]) -> bool:+ """Compare substantive finding fields while ignoring identity, provenance, and report-tracking IDs."""+def content(value: dict[str, Any]) -> dict[str, Any]:result = _finding_content(value)if isinstance(result.get("extensions"), dict):@@ -443,6 +435,10 @@ def same_raw_content(left: dict[str, Any], right: dict[str, Any]) -> bool:def contains_raw_value(current: Any, previous: Any) -> bool:+ """Check whether the current JSON value retains every part of the previous value.++ Match dictionary values by key and list elements by content, regardless of order.+ """if isinstance(previous, dict):return isinstance(current, dict) and all(key in current and contains_raw_value(current[key], value)@@ -521,6 +517,7 @@ def _saved_candidate_outcomes(workers_by_id,coverage_schema,):+ """Return saved candidate outcomes with their evidence and the ordering of pending candidates by owner."""pending_candidate_orders: dict[tuple[str | None, str], tuple[int, int]] = {}outcomes = []for relative, draft, owner in current_drafts:@@ -531,8 +528,7 @@ def _saved_candidate_outcomes(}pending_candidates = set()for field in ("deferred", "surfaces"):- items = draft["reviewState"].get(field, [])- for item in items if isinstance(items, list) else []:+ for item in _coverage_rows(draft["reviewState"], field):if isinstance(item, dict) and (field == "deferred" or item.get("disposition") == "needs_follow_up"):diff --git a/plugins/codex-security/scripts/workbench/runtime_toml.py b/plugins/codex-security/scripts/workbench/runtime_toml.pyindex 8c8af28b9..beae50248 100644--- a/plugins/codex-security/scripts/workbench/runtime_toml.py+++ b/plugins/codex-security/scripts/workbench/runtime_toml.py@@ -1,4 +1,7 @@-"""Load TOML using the supported Python runtime."""+"""Expose tomllib to workbench callers, using tomli on Python 3.10.++Import exits with setup guidance when the runtime is too old or the backport is missing.+"""import sysdiff --git a/plugins/codex-security/scripts/workbench/saved_coverage.py b/plugins/codex-security/scripts/workbench/saved_coverage.pyindex 7b37c19a2..d57e8e59e 100644--- a/plugins/codex-security/scripts/workbench/saved_coverage.py+++ b/plugins/codex-security/scripts/workbench/saved_coverage.py@@ -250,7 +250,7 @@ def prepare_saved_coverage_projection(class SavedCoverageProjection:- """Keep worker source links stable while legacy and accepted rows converge."""+ """Track which worker supplied a coverage row so reconstructed links can resolve to the retained surface."""def __init__(self, project_worker_coverage, legacy_surface_links, projection_origins):self.project_worker_coverage = project_worker_coverage@@ -293,8 +293,7 @@ class SavedCoverageProjection:if field == "surfaces":# Canonical IDs can change while source content and ownership stay the same.item = {key: value for key, value in item.items() if key != "id"}- records = coverage.get(field, [])- for record in records if isinstance(records, list) else []:+ for record in _coverage_rows(coverage, field):if not isinstance(record, dict):continueoriginal = dict(canonical_record(field, record))@@ -329,12 +328,11 @@ class SavedCoverageProjection:or worker["merge_state"] != "merged"):return False- reviews = canonical.get("reviews", [])return any(isinstance(review, dict)and review.get("workerId") == worker["id"]and review.get("attempt") == worker["attempt"]- for review in (reviews if isinstance(reviews, list) else [])+ for review in _coverage_rows(canonical, "reviews"))def repair_reviewed_surface(self, coverage, canonical, worker, source, surface):@@ -446,11 +444,8 @@ class SavedCoverageProjection:retained_legacy_surface_links: dict[int, tuple[dict[str, Any], dict[str, dict[str, Any]]]] = {}- output_tasks = coverage.get("deferred", [])- task_candidates = [- (self.worker_row_owners.get(id(row)), row)- for row in (output_tasks if isinstance(output_tasks, list) else [])- ]+ output_tasks = _coverage_rows(coverage, "deferred")+ task_candidates = [(self.worker_row_owners.get(id(row)), row) for row in output_tasks]for task, published_id, surface, _ in self.task_surface_links(task_candidates):retained_surface = self.linked_surface(surface,@@ -481,8 +476,7 @@ class SavedCoverageProjection:named_surface_outputs = {identity for outputs in self.worker_surface_outputs.values() for identity in outputs}- surfaces = coverage.get("surfaces", [])- for surface in surfaces if isinstance(surfaces, list) else []:+ for surface in _coverage_rows(coverage, "surfaces"):if not isinstance(surface, dict):continueowner, identity = self.worker_row_owners.get(id(surface)), surface.get("id")@@ -496,7 +490,7 @@ class SavedCoverageProjection:and id(existing) not in named_surface_outputs):worker_surfaces[key] = surface- for task in output_tasks if isinstance(output_tasks, list) else []:+ for task in output_tasks:if (not isinstance(task, dict)or (owner := self.worker_row_owners.get(id(task))) is None@@ -610,8 +604,7 @@ class SavedCoverageProjection:# tasks. Preserve their original links, even when the outcome changes ID# or a distinct retained surface shares the old source-local ID.for relative, draft, owner in all_sources:- originals = draft["reviewState"].get("surfaces", [])- for original in originals if isinstance(originals, list) else []:+ for original in _coverage_rows(draft["reviewState"], "surfaces"):if (not isinstance(original, dict)or id(original) in retained_surface_rows@@ -652,8 +645,7 @@ class SavedCoverageProjection:prospective_surfaces = {}prospective_named = {}for relative, draft, owner in all_sources:- rows = draft["reviewState"].get("surfaces", [])- for row in rows if isinstance(rows, list) else []:+ for row in _coverage_rows(draft["reviewState"], "surfaces"):if owner is None or not isinstance(row, dict):continueemitted = surface_is_retained(relative, owner, row)diff --git a/plugins/codex-security/scripts/workbench/saved_outputs.py b/plugins/codex-security/scripts/workbench/saved_outputs.pyindex bb9910a9a..b438ac23d 100644--- a/plugins/codex-security/scripts/workbench/saved_outputs.py+++ b/plugins/codex-security/scripts/workbench/saved_outputs.py@@ -26,6 +26,11 @@ _PUBLISHED_OUTPUTS = (def _snapshot_published_outputs(scan_dir: Path, relative_paths: tuple[str, ...] = _PUBLISHED_OUTPUTS) -> dict[str, tuple[bytes, os.stat_result] | None]:+ """Capture each artifact's bytes and stat metadata before publication.++ A None entry records an absent artifact. An unsafe optional threatmodel.md is+ omitted so rollback leaves it alone. Other unreadable existing outputs raise ContractError.+ """snapshots: dict[str, tuple[bytes, os.stat_result] | None] = {}for relative in relative_paths:descriptor = -1@@ -56,6 +61,10 @@ def _restore_published_outputs(snapshots: dict[str, tuple[bytes, os.stat_result] | None],created_paths: set[str] | None = None,) -> None:+ """Restore the captured bytes and timestamps after a publication failure.++ Remove outputs that were originally absent and paths journaled as newly created by the caller.+ """for relative, snapshot in snapshots.items():if snapshot is None:path = scan_dir / relativediff --git a/plugins/codex-security/scripts/workbench/saved_sources.py b/plugins/codex-security/scripts/workbench/saved_sources.pyindex 55caff0a6..d8c018a1e 100644--- a/plugins/codex-security/scripts/workbench/saved_sources.py+++ b/plugins/codex-security/scripts/workbench/saved_sources.py@@ -57,6 +57,11 @@ def _source_digests(value: Any, error: str) -> dict[str, str]:def _retained_source_state(value: Any) -> tuple[dict[str, str], str | None]:+ """Return the saved source digests and the optional path supplying the threat model.++ Accept both a legacy path-to-digest map and an envelope containing sources.+ Raise ContractError if the model points outside that envelope's source set.+ """if isinstance(value, dict) and isinstance(value.get("sources"), dict):sources = _source_digests(value["sources"], "Saved stopped-scan source digests are malformed."@@ -73,6 +78,11 @@ def _retained_source_state(value: Any) -> tuple[dict[str, str], str | None]:def _retained_checkpoint_state(scan: Any,) -> tuple[dict[str, str | None] | None, dict[str, Any] | None]:+ """Return selected checkpoint heads and any pending recovery record.++ Older scans can store the head map directly. Recovery records also bind+ the selection to a sealed manifest digest. A conflicting digest raises ContractError.+ """raw = scan["retained_checkpoint_heads_json"]if raw is None:return None, None@@ -125,6 +135,7 @@ def _checkpoint_paths(scan_dir: Path, directory: str) -> list[str]:def _checkpoint_head_directory(relative: str) -> Path | None:+ """Return the owner directory of a current or archived checkpoint head path, or None for another file."""path = Path(relative)if path.name == "checkpoint-head.json":return path.parent@@ -162,6 +173,7 @@ def _capture_saved_source(checkpoint_heads: dict[str, str | None] | None = None,expected_digest: str | None = None,) -> dict[str, tuple[str, int]]:+ """Capture digests and observation times for a saved source and its selected checkpoint or receipt inputs."""if not snapshot_head or Path(relative).name != "checkpoint-head.json":_, digest, observed = _read_saved_result(scan_dir, relative, scan_id, kind=kind)return capture_receipt_checkpoints(@@ -392,6 +404,7 @@ def _restore_checkpoint_head(sources: dict[str, str],relative: str,) -> None:+ """Restore the prior selection for a checkpoint directory, allowing legacy evidence with no selected head."""path = Path(relative)if path.name != "checkpoint-head.json":returndiff --git a/plugins/codex-security/scripts/workbench/storage.py b/plugins/codex-security/scripts/workbench/storage.pyindex 2a303cfa4..90abe5cd3 100644--- a/plugins/codex-security/scripts/workbench/storage.py+++ b/plugins/codex-security/scripts/workbench/storage.py@@ -9,6 +9,7 @@ from typing import Anydef state_dir(*, canonical: bool = True) -> Path:+ """Return the workbench state path, resolving symlinks unless canonical is false."""configured = os.environ.get("CODEX_SECURITY_STATE_DIR")if configured:path = Path(configured).expanduser()@@ -21,6 +22,7 @@ def state_dir(*, canonical: bool = True) -> Path:def resolve_scan_root(scan_root: str | None) -> Path:+ """Resolve an explicit scan output root, defaulting to the scans directory under workbench state."""return Path(scan_root).expanduser().resolve() if scan_root else state_dir() / "scans"diff --git a/plugins/codex-security/scripts/workbench_cli.py b/plugins/codex-security/scripts/workbench_cli.pyindex e2d2cf10c..acd772c35 100644--- a/plugins/codex-security/scripts/workbench_cli.py+++ b/plugins/codex-security/scripts/workbench_cli.py@@ -37,6 +37,11 @@ def add_user_context(parser: argparse.ArgumentParser, *, required: bool = False)def parse_args(description: str, *, inspection_only: bool = False) -> argparse.Namespace:+ """Parse the workbench command line into the namespace consumed by its dispatcher.++ For a full command, read UTF-8 user context from stdin when requested. In+ inspection mode, recognized inspection arguments return before that read.+ """parser = argparse.ArgumentParser(description=description)subparsers = parser.add_subparsers(dest="command", required=True)diff --git a/plugins/codex-security/scripts/workbench_constants.py b/plugins/codex-security/scripts/workbench_constants.pyindex a5441e42c..cc1452c6e 100644--- a/plugins/codex-security/scripts/workbench_constants.py+++ b/plugins/codex-security/scripts/workbench_constants.py@@ -63,6 +63,7 @@ EMPTY_GIT_TREES = {def optional_text(value: str | None, *, maximum: int | None = None) -> str | None:+ """Strip surrounding whitespace, return None for blank text, and enforce the character limit."""if value is None:return Nonenormalized = value.strip()@@ -72,6 +73,7 @@ def optional_text(value: str | None, *, maximum: int | None = None) -> str | Nondef positive_int(value: str) -> int:+ """Parse a CLI count and reject values below one with an argparse validation error."""parsed = int(value)if parsed < 1:raise argparse.ArgumentTypeError("expected a positive integer")diff --git a/plugins/codex-security/scripts/workbench_coverage_receipts.py b/plugins/codex-security/scripts/workbench_coverage_receipts.pyindex 8bdde383e..4b27b3997 100644--- a/plugins/codex-security/scripts/workbench_coverage_receipts.py+++ b/plugins/codex-security/scripts/workbench_coverage_receipts.py@@ -108,6 +108,7 @@ def retain_recorded_receipt_ownership(def resolve_coverage_receipts(scan_dir: Path, item: dict[str, Any], worker: Any, relative: str) -> Any:+ """Qualify worker receipt references relative to their source checkpoint for use in parent coverage."""refs = item.get("receiptRefs", [])if not isinstance(refs, list):return refsdiff --git a/plugins/codex-security/scripts/workbench_db.py b/plugins/codex-security/scripts/workbench_db.pyindex aec50dbb6..e1661a406 100644--- a/plugins/codex-security/scripts/workbench_db.py+++ b/plugins/codex-security/scripts/workbench_db.py@@ -175,6 +175,7 @@ def database_path() -> Path:@contextmanagerdef scan_completion_lock(scan_id: str) -> Any:+ """Hold the cross-process lock for a scan ID until the context exits."""lock_dir = state_dir() / "completion-locks"create_private_directory(lock_dir)lock_path = lock_dir / f"{require_uuid(scan_id, 'scan-id')}.lock"@@ -238,6 +239,20 @@ def release_completion_file_lock(descriptor: int) -> None:def connect(*, deferred: bool = False) -> sqlite3.Connection:+ """Open the workbench SQLite database and bring its schema up to date.++ Args:+ deferred (bool): Let the first migration attempt defer its write lock.+ Retries after lock contention use an immediate transaction.++ Returns:+ sqlite3.Connection: A caller-owned connection with named rows, foreign+ keys enabled, and write-ahead logging.++ Raises:+ sqlite3.OperationalError: Opening or configuring the database fails, or+ lock contention persists after retries.+ """path = database_path()guidance = (f"Workbench database: {path}. Ensure the state directory and SQLite journal files "@@ -289,11 +304,13 @@ def requested_scan_file_paths(scan: sqlite3.Row) -> list[str]:def requested_finding_scope(scan: sqlite3.Row) -> list[tuple[str, bool]]:+ """Return requested paths paired with whether the stored recipe identified each one as a file."""files = {PurePosixPath(path) for path in requested_scan_file_paths(scan)}return [(path, PurePosixPath(path) in files) for path in requested_scan_paths(scan)]def scan_contract(scan: sqlite3.Row) -> dict[str, Any]:+ """Return the target identity, scope requirements, and diff target recorded for this scan."""target = Path(scan["target_path"])target_contract = {"allowedKinds": expected_target_kinds(scan),@@ -326,6 +343,7 @@ def scan_contract(scan: sqlite3.Row) -> dict[str, Any]:def expected_coverage_mode(scan: sqlite3.Row) -> str:+ """Return the coverage mode implied by the recorded scope, scan mode, and diff target kind."""if scan["mode"] == "diff":mode = {"commit": "commit",@@ -347,6 +365,7 @@ def expected_coverage_mode(scan: sqlite3.Row) -> str:def workbench_completion_binding(scan: sqlite3.Row, completed_at: str, manifest: dict[str, Any] | None = None) -> dict[str, Any]:+ """Build the scan ID, timestamps, producer, target, and scope used to bind output artifacts at completion."""contract = scan_contract(scan)target_contract = contract["target"]plugin_version = loaded_plugin_version()@@ -384,6 +403,7 @@ def workbench_completion_binding(def verify_manifest_binding(scan: sqlite3.Row, manifest: dict[str, Any]) -> None:+ """Raise SystemExit if the supplied manifest does not match the registered scan, target, or scope."""manifest_scan = manifest.get("scan")if not isinstance(manifest_scan, dict):raise SystemExit("scan-manifest.json scan must be an object.")@@ -471,6 +491,10 @@ def require_scan(connection: sqlite3.Connection, scan_id: str) -> sqlite3.Row:def resolve_scan_id(connection: sqlite3.Connection, scan_id: str) -> str:+ """Return a canonical UUID or resolve a unique scan ID prefix of at least eight characters.++ Raise SystemExit for a prefix that is too short, ambiguous, or absent from the database.+ """try:return str(uuid.UUID(scan_id))except ValueError:@@ -942,6 +966,7 @@ def _start_prompt_driven_scan(def scan_local_file_digest(scan_dir: Path, relative_path: str) -> str:+ """Return the SHA-256 of the scan-local file contents, prefixed with sha256:."""digest = hashlib.sha256()with open_scan_local_file(scan_dir, relative_path) as source:for chunk in iter(lambda: source.read(1024 * 1024), b""):@@ -950,6 +975,7 @@ def scan_local_file_digest(scan_dir: Path, relative_path: str) -> str:def published_manifest_digest(scan_dir: Path, manifest: dict[str, Any]) -> str:+ """Return the canonical manifest digest or raise SystemExit if the published bytes differ."""canonical = (json.dumps(manifest, allow_nan=False, indent=2, sort_keys=True) + "\n").encode()expected = f"sha256:{hashlib.sha256(canonical).hexdigest()}"actual = scan_local_file_digest(scan_dir, ARTIFACTS["manifest"])@@ -959,6 +985,7 @@ def published_manifest_digest(scan_dir: Path, manifest: dict[str, Any]) -> str:def require_recorded_manifest_digest(scan: sqlite3.Row, scan_dir: Path) -> None:+ """Raise SystemExit if the saved manifest differs from the digest recorded when the scan was sealed."""expected = scan["seal_manifest_digest"]if expected is None:return@@ -969,6 +996,7 @@ def require_recorded_manifest_digest(scan: sqlite3.Row, scan_dir: Path) -> None:def pin_legacy_manifest_digest(connection: sqlite3.Connection, scan_id: str, manifest_digest: str) -> None:+ """Record a previously missing digest in a write transaction, rejecting a conflict with an existing digest."""connection.execute("BEGIN IMMEDIATE")with connection:scan = require_scan(connection, scan_id)@@ -1044,6 +1072,7 @@ def finalize_scan_usage(connection: sqlite3.Connection, args: argparse.Namespacedef complete_budget_exhausted_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:+ """Complete a running CLI Deep Scan using the measured cost and saved results after its budget is exhausted."""scan_id = require_uuid(args.scan_id, "scan-id")cost_json = parse_scan_cost(args.cost_json)if cost_json is None:@@ -1440,6 +1469,12 @@ def register_cli_scan(*,before_archive: Callable[[], None] | None = None,) -> dict[str, Any]:+ """Register a CLI scan and its selected target before execution begins.++ Record the launch recipe and target identity with the new scan. When reusing+ an output directory, coordinate archiving with registration so previous results+ can still be located. Return the scan ID, contract, and target metadata.+ """repository = require_target(args.repository)require_scannable_target(repository)scan_dir = None@@ -2583,6 +2618,11 @@ def scan_result(*,occurrence_id: str | None = None,) -> dict[str, Any]:+ """Assemble the workbench view of a saved scan, backfilling older finding details as needed.++ An occurrence ID selects one finding from that scan. An occurrence belonging+ to a different scan raises SystemExit.+ """backfill_legacy_finding_details(connection, scan)scan = scan_history.scan_with_progress(connection, scan["id"])artifact_rows = connection.execute(@@ -2612,9 +2652,6 @@ def scan_result(raise SystemExit("This finding does not belong to the selected scan.")if all(row["id"] != occurrence["id"] for row in occurrence_rows):occurrence_rows.append(occurrence)- finding_count = connection.execute(- "SELECT COUNT(*) FROM finding_occurrences WHERE scan_id = ?", (scan["id"],)- ).fetchone()[0]severity_counts = {row["severity"]: row["count"]for row in connection.execute(@@ -2627,6 +2664,7 @@ def scan_result((scan["id"],),)}+ finding_count = sum(severity_counts.values())remediation_available, remediation_unavailable_reason = remediation_availability(scan)progress_result, review_updated_at = scan_progress_result(connection, scan)relations = scan_history.finding_relations(diff --git a/plugins/codex-security/scripts/workbench_feedback.py b/plugins/codex-security/scripts/workbench_feedback.pyindex 3f9201a25..605a8a792 100644--- a/plugins/codex-security/scripts/workbench_feedback.py+++ b/plugins/codex-security/scripts/workbench_feedback.py@@ -20,6 +20,11 @@ from workbench_validation import bounded_output_textdef get_scan_feedback(connection: sqlite3.Connection, scan: sqlite3.Row) -> dict[str, Any]:+ """Return reviewed false-positive decisions from other completed scans of the same target.++ For each finding, include the latest decision only if it closes the finding as a+ false positive with a nonblank reason. Prefer the root-control location in its preview.+ """rows = connection.execute("""WITH ranked_decisions AS (diff --git a/plugins/codex-security/scripts/workbench_finding_index.py b/plugins/codex-security/scripts/workbench_finding_index.pyindex 0fecd9320..1e7969fa0 100644--- a/plugins/codex-security/scripts/workbench_finding_index.py+++ b/plugins/codex-security/scripts/workbench_finding_index.py@@ -70,6 +70,7 @@ def index_findings(document: dict[str, Any],timestamp: str,) -> None:+ """Index findings for this scan and write occurrence and ordered location rows in the caller’s transaction."""repository_id = connection.execute("SELECT target_id FROM scans WHERE id = ?", (scan_id,)).fetchone()["target_id"]diff --git a/plugins/codex-security/scripts/workbench_finding_workflows.py b/plugins/codex-security/scripts/workbench_finding_workflows.pyindex ffa541b7d..18f9c0752 100644--- a/plugins/codex-security/scripts/workbench_finding_workflows.py+++ b/plugins/codex-security/scripts/workbench_finding_workflows.py@@ -95,6 +95,7 @@ def _recorded_cost(value: str | None) -> dict[str, Any] | None:def read_workflow(connection: sqlite3.Connection, workflow_id: str) -> dict[str, Any] | None:+ """Return the stored stages, scope, and available scan cost, or None if the workflow ID is unknown."""row = connection.execute("""SELECT w.*, s.cost_json FROM finding_workflows AS wLEFT JOIN scans AS s ON s.id = w.scan_id AND s.scan_dir = w.scan_dir@@ -128,6 +129,7 @@ def read_workflow(connection: sqlite3.Connection, workflow_id: str) -> dict[str,def save_workflow(connection: sqlite3.Connection, state: dict[str, Any], timestamp: str) -> None:+ """Insert or update the workflow bindings, scope, stage statuses, and saved results in the caller’s connection."""values = {"id": state["id"]}values.update({column: state.get(field) for field, column in WORKFLOW_BINDINGS.items()})scope = state.get("scope", {})@@ -160,6 +162,7 @@ def save_workflow(connection: sqlite3.Connection, state: dict[str, Any], timestadef bind_workflow(state: dict[str, Any], binding: dict[str, Any]) -> None:+ """Add bindings to the supplied state in place, raising SystemExit for unknown or conflicting fields."""for field, value in binding.items():if field not in WORKFLOW_BINDINGS and field != "scope":raise SystemExit("Unknown workflow binding.")@@ -206,6 +209,7 @@ def register_workflow_scan(def finding_workflow(connection: sqlite3.Connection, payload: dict[str, Any], timestamp: str) -> dict[str, Any]:+ """Dispatch a workflow request by ID and return its state, source snapshot, or review as the action specifies."""workflow_id = payload["id"]if not isinstance(workflow_id, str) or not workflow_id.strip():raise SystemExit("workflowId must be a nonempty string.")diff --git a/plugins/codex-security/scripts/workbench_native_indexes.py b/plugins/codex-security/scripts/workbench_native_indexes.pyindex 1f64c5030..20b1e60d2 100644--- a/plugins/codex-security/scripts/workbench_native_indexes.py+++ b/plugins/codex-security/scripts/workbench_native_indexes.py@@ -20,6 +20,7 @@ def list_global_findings(connection: sqlite3.Connection,args: argparse.Namespace,) -> dict[str, Any]:+ """Return a page of indexed findings after applying the requested filters, with nextOffset for continuation."""limit = min(args.limit, FINDINGS_PAGE_MAX)query = args.query.strip().casefold() if args.query else ""findings = (@@ -203,6 +204,7 @@ def list_repositories(connection: sqlite3.Connection,args: argparse.Namespace | None = None,) -> dict[str, Any]:+ """Return tracked targets with scan summaries, finding counts, and current checkout availability."""by_target: dict[str, dict[str, Any]] = {}for row in connection.execute(f"""diff --git a/plugins/codex-security/scripts/workbench_progress.py b/plugins/codex-security/scripts/workbench_progress.pyindex 50a3b1d3d..7727bb8d3 100644--- a/plugins/codex-security/scripts/workbench_progress.py+++ b/plugins/codex-security/scripts/workbench_progress.py@@ -16,6 +16,7 @@ from workbench_validation import optional_text, require_uuid, user_context_argumdef reportable_count(current_phase: str, requested_phase: str | None, count: int | None) -> int | None:+ """Default a missing count to zero on entering validation or a later phase from an earlier phase."""if count is None and requested_phase in PHASES[3:] and current_phase in PHASES[:3]:return 0return count@@ -26,6 +27,7 @@ def update_context(connection: sqlite3.Connection,args: argparse.Namespace,) -> dict[str, Any]:+ """Update user context on a running scan and return the refreshed scan context in the same workbench."""scan_id = require_uuid(args.scan_id, "scan-id")context = user_context_argument(args)connection.execute("BEGIN IMMEDIATE")@@ -72,6 +74,12 @@ def update_progress(connection: sqlite3.Connection,args: argparse.Namespace,) -> dict[str, Any]:+ """Record phase and review counters for a running scan and return its updated context.++ Check continuation and coordinator ownership where applicable. A new phase+ starts with fresh phase counters. A new Deep Scan review pass must start+ with zero completed items. Invalid progress raises SystemExit.+ """scan_id = require_uuid(args.scan_id, "scan-id")model = optional_text(args.model, maximum=200)reasoning_effort = optional_text(args.reasoning_effort, maximum=32)diff --git a/plugins/codex-security/scripts/workbench_publication.py b/plugins/codex-security/scripts/workbench_publication.pyindex d649fa693..b87630493 100644--- a/plugins/codex-security/scripts/workbench_publication.py+++ b/plugins/codex-security/scripts/workbench_publication.py@@ -31,6 +31,7 @@ from validate_scan_contract import validate_contractdef destination_key(destination: Any) -> str:+ """Encode exact provider-specific destination IDs into a stable key for matching issue receipts."""if not isinstance(destination, dict):raise SystemExit("Finding issues require an exact tracker destination.")kind = destination.get("type")@@ -59,6 +60,12 @@ def verify_publication_history(scan_directory: str,findings: list[dict[str, Any]],) -> None:+ """Require publication input to match the completed scan in local history.++ Check the exact scan ID, directory, pinned manifest digest when present,+ and the complete set of occurrence-to-finding associations. Raise+ SystemExit if any of these disagree.+ """try:scan = db.require_scan(connection, scan_id)except SystemExit as exc:@@ -109,6 +116,7 @@ def inspect_issue_receipts(key: str,finding_ids: list[str],) -> list[dict[str, Any]]:+ """Return receipts for the selected findings and destination, including receipts from older Linear tables."""tables = {row[0] for row in connection.execute("SELECT name FROM sqlite_master WHERE type = 'table'")}@@ -132,6 +140,7 @@ def inspect_issue_receipts(def validate_issue_receipts(receipts: Any, selected: dict[str, str]) -> list[dict[str, Any]]:+ """Return receipts bound to the selected finding occurrences or raise SystemExit on invalid receipt data."""if not isinstance(receipts, list):raise SystemExit("Finding issue receipts must be an array.")for receipt in receipts:@@ -367,6 +376,7 @@ def write_csv_export(scan: sqlite3.Row,findings_document: dict[str, Any],) -> Path:+ """Write indexed findings to exports/findings.csv, adding candidate IDs for Deep Scans, and return its path."""scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))output = io.StringIO(newline="")writer = csv.writer(output)diff --git a/plugins/codex-security/scripts/workbench_remediation.py b/plugins/codex-security/scripts/workbench_remediation.pyindex 6792bfa79..a0848f8e2 100644--- a/plugins/codex-security/scripts/workbench_remediation.py+++ b/plugins/codex-security/scripts/workbench_remediation.py@@ -47,6 +47,7 @@ SCAN_STATUS_ERROR = "Remediation is available only for successfully completed scdef require_available(connection: sqlite3.Connection, args: Any, require_scan: Any) -> None:+ """Require a successfully completed scan for commands that act on a remediation request."""if args.command not in COMMANDS:returnoccurrence = require_occurrence(connection, args.occurrence_id)@@ -57,6 +58,7 @@ def require_available(connection: sqlite3.Connection, args: Any, require_scan: Adef require_request(connection: sqlite3.Connection, request_id: str, occurrence: sqlite3.Row) -> sqlite3.Row:+ """Return the request row or raise SystemExit if the request is missing or belongs to a different occurrence."""current = connection.execute("SELECT * FROM finding_remediation_attempts WHERE request_id = ?",(request_id,),@@ -67,6 +69,7 @@ def require_request(def latest_attempt(connection: sqlite3.Connection, occurrence_id: str) -> sqlite3.Row | None:+ """Return the newest remediation attempt for the occurrence, breaking timestamp ties by insertion order."""return connection.execute("""SELECT * FROM finding_remediation_attempts@@ -344,6 +347,12 @@ def patch_metadata(patch: bytes | None,resolve_path: Callable[[str], str],) -> tuple[str | None, str | None]:+ """Resolve a remediation attempt’s patch path and SHA-256 digest.++ For newly generated bytes, compute the digest and use the existing or+ request-specific path. For a referenced patch, validate the supplied path+ and digest. Raise SystemExit if either conflicts with a previously reviewed value.+ """path = args.patch_pathdigest = args.patch_digestif patch is not None:@@ -371,6 +380,7 @@ def patch_metadata(def same_file_version(original: tuple[os.stat_result, int], current: tuple[os.stat_result, int]) -> bool:+ """Compare file identity, size, modification time, and the platform-specific change-time token."""before, before_change = originalafter, after_change = currentreturn (@@ -382,6 +392,7 @@ def same_file_version(def file_digest_and_version(source: BinaryIO, label: str) -> tuple[str, tuple[os.stat_result, int]]:+ """Hash the remaining stream bytes and return their digest and file version, raising SystemExit if the file changes."""before = scan_local_file_version(source.fileno())digest = hashlib.sha256()for chunk in iter(lambda: source.read(1024 * 1024), b""):@@ -393,6 +404,7 @@ def file_digest_and_version(source: BinaryIO, label: str) -> tuple[str, tuple[osdef matching_patch_metadata(source: BinaryIO, expected_digest: str) -> tuple[os.stat_result, int]:+ """Return the stable patch version or raise SystemExit if its bytes differ from expected_digest."""digest, version = file_digest_and_version(source, "scan-local patch")if digest != expected_digest:raise SystemExit("Patch digest does not match the scan-local patch file.")@@ -402,6 +414,7 @@ def matching_patch_metadata(source: BinaryIO, expected_digest: str) -> tuple[os.def patch_manifest_version(db: Any, scan: sqlite3.Row, scan_dir: Path) -> tuple[str, tuple[os.stat_result, int]]:+ """Verify the sealed scan manifest and return its byte digest and file version, including for legacy scans."""manifest_path = db.ARTIFACTS["manifest"]expected = scan["seal_manifest_digest"]if expected is None:diff --git a/plugins/codex-security/scripts/workbench_saved_results.py b/plugins/codex-security/scripts/workbench_saved_results.pyindex f9ac96ee2..466d9f680 100644--- a/plugins/codex-security/scripts/workbench_saved_results.py+++ b/plugins/codex-security/scripts/workbench_saved_results.py@@ -85,6 +85,7 @@ _RESERVED_ARTIFACT_PATHS = json.loads(def threat_model_fields(db: Any, scan: sqlite3.Row) -> dict[str, Any]:+ """Return availability and provenance for a saved threat model, reporting it as unavailable when verification fails."""scan_dir = Path(scan["scan_dir"])fields: dict[str, Any] = {"threatModelAvailable": False}try:@@ -352,6 +353,7 @@ def _recovery_source_digests(def scan_results_recovery_needed(db: Any, connection: Any, scan: Any) -> bool:+ """Return whether a failed, uncanceled scan has a publication error or saved evidence to recover."""if scan["status"] != "failed" or scan["canceled_at"] is not None:return Falsewarnings = json.loads(scan["completion_warnings_json"])@@ -409,6 +411,7 @@ def preserve_parent_head_on_error(scan_dir: Path) -> Iterator[None]:def coverage_for_comparison(db: Any, scan: Any) -> dict[str, Any]:+ """Return coverage from the verified, sealed scan or raise SystemExit if the stored scan cannot be matched."""if scan["seal_manifest_digest"] is None:raise SystemExit("Only sealed scans can be compared.")scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))@@ -894,6 +897,7 @@ def preserve_scan_results_locked(def recover_scan_results(db: Any, connection: Any, args: Any) -> dict[str, Any]:+ """Recover terminal results from saved checkpoints under the completion lock for a failed, uncanceled scan."""scan_id = db.require_uuid(args.scan_id, "scan-id")with db.scan_completion_lock(scan_id):scan = db.require_scan(connection, scan_id)@@ -926,6 +930,7 @@ def recover_scan_results(db: Any, connection: Any, args: Any) -> dict[str, Any]:def preserve_scan_results(db: Any, connection: Any, args: Any) -> dict[str, Any]:+ """Publish results for a stopped scan under its completion lock and return the updated scan context."""scan_id = db.require_uuid(args.scan_id, "scan-id")with db.scan_completion_lock(scan_id):scan = db.require_scan(connection, scan_id)@@ -1003,6 +1008,12 @@ def save_scan_artifact(db: Any, connection: Any, args: Any) -> dict[str, Any]:def write_scan_draft(db: Any, connection: Any, args: Any) -> dict[str, Any]:+ """Publish a staged draft for the current continuation of a running, unsealed scan.++ Read the draft from its registered scan directory and bind it to the scan+ before publishing it under the completion lock. Return the scan ID, the+ draft_written status, and any warning about the optional threat model.+ """scan_id = db.require_uuid(args.scan_id, "scan-id")with db.scan_completion_lock(scan_id):scan = db.require_scan(connection, scan_id)@@ -1320,6 +1331,7 @@ def cancel_scan_locked(db: Any, connection: Any, args: Any) -> dict[str, Any]:def preserve_stopped_results_after_transition(db: Any, connection: Any, scan_id: str) -> None:+ """Try to publish saved evidence after stopping a scan and record a warning if publication fails."""try:published = preserve_scan_results_locked(db, connection, scan_id)except (ContractError, OSError, SystemExit, ValueError) as exc:diff --git a/plugins/codex-security/scripts/workbench_scan_history.py b/plugins/codex-security/scripts/workbench_scan_history.pyindex f6719df2e..76f8e3d09 100644--- a/plugins/codex-security/scripts/workbench_scan_history.py+++ b/plugins/codex-security/scripts/workbench_scan_history.py@@ -43,6 +43,7 @@ def rename_scan(connection: sqlite3.Connection, scan: sqlite3.Row, name: str) ->def scan_recipe(scan: sqlite3.Row) -> dict[str, Any]:+ """Return the public launch recipe with its scan and parent IDs, raising SystemExit if the recipe was never saved."""if scan["recipe_json"] is None:raise SystemExit("This scan does not have a saved launch recipe.")return {@@ -55,6 +56,7 @@ def scan_recipe(scan: sqlite3.Row) -> dict[str, Any]:def preserve_sealed_completion(binding: dict[str, Any], manifest: dict[str, Any] | None) -> dict[str, Any]:+ """Copy the original timestamps and producer version from a sealed manifest into binding, then return it."""manifest_scan = manifest.get("scan") if manifest is not None else Noneif isinstance(manifest_scan, dict) and manifest_scan.get("sealedAt") is not None:# Keep the original producer; finalization still validates schema, seal and owner.@@ -147,6 +149,7 @@ def cli_scan_resume(def coverage_summary_for_history(wb: Any, scan: sqlite3.Row, canonical_scan_directory: Callable[[Path], Path]) -> dict[str, Any]:+ """Return the coverage mode and path filters for history after verifying the sealed scan data."""scan_dir = canonical_scan_directory(Path(scan["scan_dir"]))coverage_ref = "coverage.json"try:@@ -655,6 +658,7 @@ def compare_scans(include_matching_inputs: bool = False,require_matches: bool = False,) -> dict[str, Any]:+ """Compare completed scans of the same repository, returning finding groups and any inputs needed for matching."""before = require_scan(connection, args.before_scan_id)after = require_scan(connection, args.after_scan_id)if before["id"] == after["id"]:@@ -688,9 +692,7 @@ def compare_scans(after_findings = _scan_findings(connection, after["id"])matches = json.loads(cached["result_json"]) if cached is not None else Nonesaved_matches = matches["matches"] if matches is not None else []- occurrences = {- row["id"]: row for row in chain(before_findings.values(), after_findings.values())- }+ occurrences = before_findings | after_findingsaliases = _confirmed_finding_aliases(connection, occurrences)groups = _finding_groups(before_findings, after_findings, saved_matches, aliases)uncertain = (@@ -709,17 +711,8 @@ def compare_scans(}for previous_rows, current_rows, match_reason in groups:- previous = (- min(previous_rows, key=lambda row: SEVERITY_ORDER[row["severity"]])- if previous_rows- else None- )- current = (- min(current_rows, key=lambda row: SEVERITY_ORDER[row["severity"]])- if current_rows- else None- )- selected = current if current is not None else previous+ selected_rows = current_rows or previous_rows+ selected = min(selected_rows, key=lambda row: SEVERITY_ORDER[row["severity"]])item = {"findingId": selected["finding_id"],"path": selected["relative_path"],@@ -730,18 +723,12 @@ def compare_scans(uncertain_reason = next((uncertain[(side, row["id"])]- for row in current_rows or previous_rows+ for row in selected_rowsif (side, row["id"]) in uncertain),None,)- if previous is None:- if uncertain_reason is None:- status = "new"- else:- status = "unknown"- item["reason"] = uncertain_reason- elif current is not None:+ if previous_rows and current_rows:status = ("reopened"if any(@@ -756,6 +743,8 @@ def compare_scans(elif uncertain_reason is not None:status = "unknown"item["reason"] = uncertain_reason+ elif current_rows:+ status = "new"elif not all(scan_covers_path(after,@@ -776,17 +765,17 @@ def compare_scans(status = "not_observed"item["reason"] = "Not observed in the later scan; remediation has not been verified."if len(previous_rows) == 1:- item["beforeOccurrenceId"] = previous["id"]+ item["beforeOccurrenceId"] = previous_rows[0]["id"]elif previous_rows:item["beforeOccurrenceIds"] = [row["id"] for row in previous_rows]if len(current_rows) == 1:- item["afterOccurrenceId"] = current["id"]+ item["afterOccurrenceId"] = current_rows[0]["id"]elif current_rows:item["afterOccurrenceIds"] = [row["id"] for row in current_rows]- if current is not None:+ if current_rows:item["triage"] = {- "closeReason": current["close_reason"],- "status": current["triage_status"],+ "closeReason": selected["close_reason"],+ "status": selected["triage_status"],}item["status"] = statusfindings.append(item)@@ -860,8 +849,10 @@ def save_scan_comparison(if not _same_repository(before, after):raise SystemExit("Semantic scan comparisons require the same repository target.")read_coverage(after)- before_findings = _scan_findings(connection, before["id"])- after_findings = _scan_findings(connection, after["id"])+ allowed = {+ "before": set(_scan_findings(connection, before["id"])),+ "after": set(_scan_findings(connection, after["id"])),+ }matches_json = (sys.stdin.read() if getattr(args, "matches_json_stdin", False) else args.matches_json)@@ -879,10 +870,6 @@ def save_scan_comparison(not isinstance(payload.get(key, []), list) for key in ("matches", "uncertain", "related")):raise SystemExit("Scan comparison matches must contain matches and uncertain arrays.")- allowed = {- "before": {row["id"] for row in before_findings.values()},- "after": {row["id"] for row in after_findings.values()},- }consumed: dict[str, dict[str, int]] = {"before": {}, "after": {}}for group, match in enumerate(payload["matches"]):if (@@ -1177,10 +1164,7 @@ def _finding_groups(matches: list[dict[str, Any]],aliases: dict[str, str],) -> list[tuple[list[sqlite3.Row], list[sqlite3.Row], str | None]]:- rows = {- side: {row["id"]: row for row in findings.values()}- for side, findings in (("before", before_findings), ("after", after_findings))- }+ rows = {"before": before_findings, "after": after_findings}groups: dict[str, tuple[list[sqlite3.Row], list[sqlite3.Row], list[str]]] = {}def group(row: sqlite3.Row) -> tuple[list[sqlite3.Row], list[sqlite3.Row], list[str]]:@@ -1308,6 +1292,7 @@ def finding_occurrence_conditions(def _scan_findings(connection: sqlite3.Connection, scan_id: str) -> dict[str, sqlite3.Row]:+ """Index one scan's finding rows by the occurrence IDs used in comparisons."""rows = connection.execute("""SELECT occurrences.*,@@ -1326,7 +1311,7 @@ def _scan_findings(connection: sqlite3.Connection, scan_id: str) -> dict[str, sq""",(scan_id,),)- return {row["finding_id"]: row for row in rows}+ return {row["id"]: row for row in rows}def scan_covers_path(@@ -1336,6 +1321,7 @@ def scan_covers_path(path: str | None,coverage: dict[str, Any],) -> bool:+ """Check whether a completed scan of this target included the path after applying all recorded exclusions."""if scan["status"] != "complete" or scan["target_id"] != target_id:return Falseif not isinstance(path, str) or not path:diff --git a/plugins/codex-security/scripts/workbench_scan_start.py b/plugins/codex-security/scripts/workbench_scan_start.pyindex 03b09a41d..8a93b69cf 100644--- a/plugins/codex-security/scripts/workbench_scan_start.py+++ b/plugins/codex-security/scripts/workbench_scan_start.py@@ -30,6 +30,7 @@ from workbench_validation import optional_text, read_json_objectdef safe_segment(value: str) -> str:+ """Normalize a filename segment, falling back to ``scan`` for an empty result."""segment = re.sub(r"[^\w.-]", "-", value)if segment != value:segment = segment.strip("-")@@ -37,10 +38,12 @@ def safe_segment(value: str) -> str:def compact_timestamp() -> str:+ """Return the current UTC time in YYYYMMDDTHHMMSSZ format."""return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")def loaded_plugin_version() -> str:+ """Read the required version string from the loaded plugin's manifest."""manifest = read_json_object(Path(__file__).resolve().parents[1] / ".codex-plugin" / "plugin.json")@@ -56,6 +59,11 @@ def scan_target_identity(*,metadata: os.stat_result | None = None,) -> tuple[str, str | None, int | str, int | str]:+ """Return revision, content digest, device ID, and inode for scan registration.++ An explicit diff uses its head revision and a None digest. Other targets use+ the worktree or directory digest. Device and inode use the SQLite-safe representation.+ """if metadata is None:metadata = target.stat()revision = diff_target["headRevision"] if diff_target else git_revision(target)@@ -77,6 +85,7 @@ def scan_target_identity(def scan_diff_identity(diff_target: dict[str, str] | None,) -> tuple[str | None, str | None, str | None, str | None]:+ """Return kind, base, head, and optional digest in database order, or four nulls."""if diff_target is None:return (None, None, None, None)return (@@ -88,6 +97,7 @@ def scan_diff_identity(def stored_diff_target(row: sqlite3.Row) -> dict[str, str] | None:+ """Rebuild the diff target from a scan row, or return None for a full scan."""if not row["diff_target_kind"]:return Nonetarget = {@@ -110,6 +120,7 @@ def archive_scan(*,before_archive: Callable[[], None] | None = None,) -> Iterator[Path | None]:+ """Yield the archive directory while preparing the original scan path for reuse."""archived_scan_dir = (canonical_directory(Path(args.archived_scan_dir).expanduser())if args.archived_scan_dir is not Nonediff --git a/plugins/codex-security/scripts/workbench_scan_usage.py b/plugins/codex-security/scripts/workbench_scan_usage.pyindex a0cb5b902..01b4d6e64 100644--- a/plugins/codex-security/scripts/workbench_scan_usage.py+++ b/plugins/codex-security/scripts/workbench_scan_usage.py@@ -30,6 +30,8 @@ STATE_DATABASE_TIMEOUT_SECONDS = 1.0@dataclass(frozen=True)class RolloutSession:+ """Associate a thread and its optional parent with the path of the rollout used for usage accounting."""+thread_id: strparent_thread_id: str | Nonepath: Path@@ -37,6 +39,8 @@ class RolloutSession:@dataclassclass RolloutUsage:+ """Collect token counts, their update time, warnings, and account rate-limit observations for a rollout."""+tokens: dict[str, int]warnings: set[str]tokens_updated_at: datetime | None@@ -89,7 +93,12 @@ def collect_scan_usage(completed_at: str | None = None,completed_turn_id: str | None = None,) -> dict[str, Any]:- """Count attributable receipts and flag observable gaps inside the scan window."""+ """Count attributable session receipts during the scan window and report missing coverage.++ The optional thread and completion arguments identify the finishing turn when+ the scan record alone is insufficient. Return an unavailable usage record when+ the window, Codex state, or relevant threads cannot be established.+ """roots = _scan_root_thread_ids(connection, scan, thread_id)parent_ids = set(_scan_root_thread_ids(connection, scan, thread_id, include_workers=False))diff --git a/plugins/codex-security/scripts/workbench_schema.py b/plugins/codex-security/scripts/workbench_schema.pyindex 526fb38f5..990829735 100644--- a/plugins/codex-security/scripts/workbench_schema.py+++ b/plugins/codex-security/scripts/workbench_schema.py@@ -52,6 +52,12 @@ def apply_migrations(*,immediate: bool = False,) -> None:+ """Apply missing schema versions and repair supported historical migrations.++ Commit pending work on the connection before starting the migration transaction.+ Set immediate to acquire the SQLite write lock up front. The backfill callback+ links older scans and workspaces to stable targets when required.+ """connection.commit()connection.execute("BEGIN IMMEDIATE" if immediate else "BEGIN")with connection:@@ -178,6 +184,11 @@ def repair_thread_scoped_workspaces_migration(connection: sqlite3.Connection) ->def repair_stable_targets_migration(connection: sqlite3.Connection) -> bool:+ """Repair a partial target-ID migration and return whether the schema required repair.++ Create missing target tables, columns, and indexes. Clear scan references+ to missing target records so they can be backfilled.+ """workspace_columns = {row["name"] for row in connection.execute("PRAGMA table_info(workspaces)")}scan_columns = {row["name"] for row in connection.execute("PRAGMA table_info(scans)")}existing_objects = {@@ -215,6 +226,7 @@ def repair_stable_targets_migration(connection: sqlite3.Connection) -> bool:def repair_additive_migration(connection: sqlite3.Connection, version: int) -> None:+ """Replay the column additions from one historical migration, skipping columns already present."""sql = next(sql for migration_version, _, sql in MIGRATIONS if migration_version == version)for statement in sql_statements(sql):add_migration_column(connection, statement)diff --git a/plugins/codex-security/scripts/workbench_setup.py b/plugins/codex-security/scripts/workbench_setup.pyindex 6fa406952..fcfeafede 100644--- a/plugins/codex-security/scripts/workbench_setup.py+++ b/plugins/codex-security/scripts/workbench_setup.py@@ -22,6 +22,7 @@ from workbench_target import (def require_target(value: str) -> Path:+ """Return the resolved local directory or raise SystemExit if the supplied path is relative or missing."""expanded = Path(value).expanduser()if not expanded.is_absolute():raise SystemExit("Scan target must be an absolute local directory path.")@@ -32,6 +33,7 @@ def require_target(value: str) -> Path:def inspect_target(target: Path) -> dict[str, Any]:+ """Return the target path, display name, and local Git metadata used by setup."""return {"displayName": target.name,"targetMetadata": git_target_metadata(target),@@ -40,6 +42,7 @@ def inspect_target(target: Path) -> dict[str, Any]:def resolve_git_commit(target: Path, revision: str, label: str) -> str:+ """Resolve a revision to a local commit ID or raise SystemExit with the caller’s label."""value = optional_text(revision, maximum=512)if not value:raise SystemExit(f"{label} is required.")@@ -62,6 +65,11 @@ def require_diff_target(head_revision: str | None,content_digest: str | None,) -> dict[str, str]:+ """Resolve the selected Git change to its base and head commits.++ For a working-tree selection, also return the current content digest and reject+ changes since selection. Invalid or stale selections raise SystemExit.+ """current_head = require_review_changes_target(target)if kind not in DIFF_TARGET_KINDS:raise SystemExit("Choose which Git changes to review before starting a diff scan.")@@ -131,6 +139,7 @@ def inspect_setup_values(diff_head_revision: str | None,diff_content_digest: str | None,) -> dict[str, Any]:+ """Validate the target, scope, and scan mode and return their normalized values and resolved diff target."""target = require_target(target_path)inspected = require_scannable_target(target)normalized_scope = require_scope(scope, mode, target)@@ -165,6 +174,7 @@ def inspect_setup_values(def require_review_changes_target(target: Path) -> str:+ """Return the checked-out revision or raise SystemExit if target is not the worktree root."""revision = require_git_worktree_head(target)repository_root = git_output(target, "rev-parse", "--show-toplevel")if repository_root is None or not Path(repository_root).samefile(target):@@ -175,6 +185,7 @@ def require_review_changes_target(target: Path) -> str:def require_scannable_target(target: Path) -> dict[str, Any]:+ """Return the inspected target metadata, rejecting a Git repository that has no checked-out worktree."""inspected = inspect_target(target)metadata = inspected["targetMetadata"]if metadata["isGit"] and not metadata["isWorktree"]:@@ -185,6 +196,7 @@ def require_scannable_target(target: Path) -> dict[str, Any]:def require_scope(scope: str, mode: str, target: Path) -> str:+ """Return the existing scan directory relative to the target, requiring the whole repository for deep mode."""value = scope if scope.strip() else "."requested_scope = Path(value)if "\\" in value and (os.name != "nt" or not requested_scope.is_absolute()):diff --git a/plugins/codex-security/scripts/workbench_source_excerpt.py b/plugins/codex-security/scripts/workbench_source_excerpt.pyindex 6faaccf28..5efcb3430 100644--- a/plugins/codex-security/scripts/workbench_source_excerpt.py+++ b/plugins/codex-security/scripts/workbench_source_excerpt.py@@ -30,6 +30,18 @@ def finding_source_excerpt(locations: list[dict[str, Any]],scopes: list[str],) -> str | None:+ """Return numbered context from a finding location at the scanned Git revision.++ Args:+ scan: Saved scan row with its revision, snapshot digest, and scope metadata.+ target: Local target directory in which to resolve the recorded Git objects.+ locations: Displayed finding locations, using one-based line numbers.+ scopes: Selected paths used to interpret saved source scopes.++ Returns:+ A bounded excerpt, or None when a location, scope, or local blob cannot+ supply it. Root-control locations have priority.+ """if target is None or not locations or scan["target_revision"] == "unversioned":return Nonesnapshot = scan["target_snapshot_digest"]@@ -116,6 +128,7 @@ def finding_source_excerpt(def scanned_source_text(repository: Path, object_id: str) -> str | None:+ """Decode the locally available Git blob as UTF-8 with replacement, or return None on lookup failure."""try:content = offline_git_bytes(repository, "cat-file", "blob", object_id)except (OSError, RuntimeError, SystemExit):diff --git a/plugins/codex-security/scripts/workbench_source_scopes.py b/plugins/codex-security/scripts/workbench_source_scopes.pyindex 88198e0c4..bb0060b32 100644--- a/plugins/codex-security/scripts/workbench_source_scopes.py+++ b/plugins/codex-security/scripts/workbench_source_scopes.py@@ -26,6 +26,7 @@ OBJECT_ID = re.compile(r"(?:[0-9a-f]{40}|[0-9a-f]{64})\Z")def expected_target_kinds(scan: sqlite3.Row) -> list[str]:+ """Return the manifest target kinds compatible with the stored scan mode, revision, and snapshot digest."""if scan["mode"] == "diff":return ["git_diff"]if scan["target_revision"] == "unversioned":@@ -38,6 +39,7 @@ def expected_target_kinds(scan: sqlite3.Row) -> list[str]:def requested_scan_paths(scan: sqlite3.Row) -> list[str]:+ """Return the explicit paths in the saved launch recipe, falling back to the scan’s original scope."""if "recipe_json" in scan.keys() and scan["recipe_json"] is not None:recipe = json.loads(scan["recipe_json"], parse_constant=reject_non_finite_json)target = recipe["target"]@@ -47,6 +49,7 @@ def requested_scan_paths(scan: sqlite3.Row) -> list[str]:def public_scan_recipe(scan: sqlite3.Row) -> dict[str, Any]:+ """Return the decoded launch recipe with the internal file-scope metadata removed."""recipe = json.loads(scan["recipe_json"], parse_constant=reject_non_finite_json)recipe.pop("_codexSecurityFileScopes", None)return recipe@@ -62,6 +65,7 @@ def relative_path(value: str) -> PurePosixPath | None:def safe_source_path(target: Path, value: str) -> Path | None:+ """Resolve a repository-relative POSIX path and return None if it is invalid or resolves outside the target."""parsed = relative_path(value)if parsed is None:return None@@ -74,6 +78,7 @@ def safe_source_path(target: Path, value: str) -> Path | None:def offline_git_bytes(repository: Path, *arguments: str) -> bytes | None:+ """Return raw stdout for a successful offline Git command with replacement objects disabled, otherwise None."""result = git_command(repository,*arguments,@@ -86,6 +91,7 @@ def offline_git_bytes(repository: Path, *arguments: str) -> bytes | None:@cachedef tree_entries(repository: Path, tree: str) -> dict[str, tuple[tuple[str, str, str], ...]] | None:+ """Index a Git tree by normalized name, retaining every original name, entry kind, and object ID in each group."""content = offline_git_bytes(repository, "ls-tree", "-z", tree)if content is None:return None@@ -217,6 +223,12 @@ def capture_source_scopes(*,diff_target_kind: str | None = None,) -> dict[str, Any]:+ """Bind requested paths to the local Git objects that may supply excerpts later.++ Return the revision and the file or tree IDs that can be verified locally.+ A working-tree diff, dirty snapshot, or replacement ref leaves the scope list+ empty. A path that cannot be bound adds no authority to read other paths.+ """revision, snapshot = target_identity[:2]result: dict[str, Any] = {"version": 1, "revision": revision, "scopes": []}# HEAD cannot represent the uncommitted bytes reviewed by a working-tree scan.@@ -267,6 +279,11 @@ def capture_source_scopes(def load_source_scopes(scan: sqlite3.Row, target: Path, requested: list[str]) -> tuple[Path, str, list[dict[str, str]]] | None:+ """Return the repository, tree ID, and valid source scopes, or None when none can be established.++ Use saved object IDs for current records. For a legacy scan, reconstruct only+ unambiguous entries from its original revision and respect any recorded file kinds.+ """kind = scan["diff_target_kind"] if "diff_target_kind" in scan.keys() else Noneif kind == "working_tree" or ("mode" in scan.keys() and scan["mode"] == "diff" and kind not in ("commit", "range")@@ -343,6 +360,7 @@ def load_source_scopes(def source_object_for_path(repository: Path, tree: str, target: Path, value: str, scope: dict[str, str]) -> str | None:+ """Return the Git blob ID for a file covered by the recorded scope, or None if the path cannot be verified."""path = relative_path(value)if path is None or safe_source_path(target, value) is None:return Nonediff --git a/plugins/codex-security/scripts/workbench_target.py b/plugins/codex-security/scripts/workbench_target.pyindex 74b98e9fe..55ce17a60 100644--- a/plugins/codex-security/scripts/workbench_target.py+++ b/plugins/codex-security/scripts/workbench_target.py@@ -44,6 +44,11 @@ def committed_diff_snapshot_digest(kind: str, base_revision: str, head_revision:def diff_snapshot_digest(scan: sqlite3.Row, manifest: dict[str, Any] | None) -> str | None:+ """Return the content identity used for a stored diff, or None when unavailable.++ Working-tree scans use their recorded content digest. Commit and range scans+ reuse the sealed manifest value during recovery or derive a digest from both revisions.+ """if scan["diff_target_kind"] == "working_tree":return scan["diff_content_digest"]if scan["diff_target_kind"] in {"commit", "range"}:@@ -67,6 +72,7 @@ def git_output(work_tree: Path | None = None,offline: bool = False,) -> str | None:+ """Return decoded Git stdout with one trailing newline removed, or None on failure or empty output."""completed = git_command(target, *args, text=False, git_dir=git_dir, work_tree=work_tree, offline=offline)@@ -275,6 +281,12 @@ def git_command(environment_overrides: dict[str, str] | None = None,offline: bool = False,) -> subprocess.CompletedProcess[str] | subprocess.CompletedProcess[bytes]:+ """Run Git against target and return the completed process with its exit status.++ Pass git_dir and work_tree together to select an explicit checkout. Set+ offline to disable transports and lazy fetches. The text flag selects+ decoded or binary output, and stdout_file can redirect it to a file.+ """if (git_dir is None) != (work_tree is None):raise ValueError("git_dir and work_tree must be provided together")environment = os.environ.copy()@@ -527,6 +539,19 @@ def update_digest_field(digest: Any, label: bytes, value: bytes) -> None:digest.update(value)+def _update_regular_file_digest(digest: Any, path: Path, prefix: bytes = b"") -> None:+ """Record the file kind, byte count, and SHA-256 in the snapshot digest."""+ content = hashlib.sha256()+ size = 0+ with path.open("rb") as handle:+ for chunk in iter(lambda: handle.read(1024 * 1024), b""):+ content.update(chunk)+ size += len(chunk)+ update_digest_field(digest, prefix + b"kind", b"file")+ update_digest_field(digest, prefix + b"size", str(size).encode())+ update_digest_field(digest, prefix + b"content-sha256", content.digest())++def _visible_git_character(char: str) -> str:if char in "\n\t" or unicodedata.category(char) not in {"Cc", "Cf"}:return char@@ -569,6 +594,7 @@ def _update_digest_field_from_git(def worktree_content_digest(target: Path) -> str:+ """Return the worktree digest for the selected path after checking the state of its submodules."""require_clean_submodule_worktrees(target)repository, pathspec = git_worktree_context(target)return worktree_content_digest_for_context(repository, pathspec)@@ -582,6 +608,7 @@ def remediation_checkout_snapshot("Repository HEAD changed. Regenerate the remediation patch against the current checkout."),) -> tuple[str, str | None]:+ """Return the current revision and content digest after verifying the recorded checkout identity and required revision."""target = require_scan_target_identity(scan)revision = git_revision(target)required_revision = expected_revision or scan["target_revision"]@@ -706,26 +733,10 @@ def worktree_content_digest_for_context(directory_content_digest(path.resolve()).encode(),)elif stat.S_ISREG(metadata.st_mode):- content_digest = hashlib.sha256()- content_size = 0try:- with path.open("rb") as handle:- for chunk in iter(lambda: handle.read(1024 * 1024), b""):- content_digest.update(chunk)- content_size += len(chunk)+ _update_regular_file_digest(digest, path, prefix=b"untracked-")except OSError as exc:raise SystemExit(f"Could not read untracked file: {relative_path}") from exc- update_digest_field(digest, b"untracked-kind", b"file")- update_digest_field(- digest,- b"untracked-size",- str(content_size).encode(),- )- update_digest_field(- digest,- b"untracked-content-sha256",- content_digest.digest(),- )else:raise SystemExit(f"Unsupported untracked file type: {relative_path}")return f"codex-security-snapshot/v1:sha256:{digest.hexdigest()}"@@ -1084,18 +1095,10 @@ def directory_content_digest(elif stat.S_ISDIR(mode):update_digest_field(digest, b"kind", b"directory")elif stat.S_ISREG(mode):- content_digest = hashlib.sha256()- content_size = 0try:- with path.open("rb") as handle:- for chunk in iter(lambda: handle.read(1024 * 1024), b""):- content_digest.update(chunk)- content_size += len(chunk)+ _update_regular_file_digest(digest, path)except OSError as exc:raise UnreadableLocalFile(f"Could not read local file: {relative_path}") from exc- update_digest_field(digest, b"kind", b"file")- update_digest_field(digest, b"size", str(content_size).encode())- update_digest_field(digest, b"content-sha256", content_digest.digest())else:raise UnsupportedLocalFileType(f"Unsupported local file type: {relative_path}")return f"codex-security-snapshot/v1:sha256:{digest.hexdigest()}"@@ -1311,6 +1314,7 @@ def require_remediation_target(value: str) -> Path:def require_scan_target_identity(scan: sqlite3.Row) -> Path:+ """Return the recorded checkout path or raise SystemExit if it no longer identifies the original directory."""target = require_remediation_target(scan["target_path"])expected_inode = scan["target_inode"]if expected_inode is None:diff --git a/plugins/codex-security/scripts/workbench_target_state.py b/plugins/codex-security/scripts/workbench_target_state.pyindex 7d24a5f20..23daebb95 100644--- a/plugins/codex-security/scripts/workbench_target_state.py+++ b/plugins/codex-security/scripts/workbench_target_state.py@@ -10,11 +10,13 @@ from pathlib import Pathdef stable_target_id(target: Path) -> str:+ """Hash the supplied path spelling into the workbench ID for a local workspace."""digest = hashlib.sha256(f"local-workspace\0{target}".encode()).hexdigest()return f"target_sha256_{digest}"def backfill_security_targets(connection: sqlite3.Connection) -> None:+ """Fill missing target IDs on scans and workspaces in the caller’s transaction."""rows = connection.execute("""SELECT target_path FROM workspaces WHERE target_path IS NOT NULL@@ -36,6 +38,7 @@ def backfill_security_targets(connection: sqlite3.Connection) -> None:def ensure_security_target(connection: sqlite3.Connection, target_path: str) -> str:+ """Return the ID already associated with the path or insert a deterministic ID for it."""existing = connection.execute("SELECT id FROM security_targets WHERE current_path = ?",(target_path,),diff --git a/plugins/codex-security/scripts/workbench_validation.py b/plugins/codex-security/scripts/workbench_validation.pyindex cc9f51cf5..df5b1e6db 100644--- a/plugins/codex-security/scripts/workbench_validation.py+++ b/plugins/codex-security/scripts/workbench_validation.py@@ -27,6 +27,7 @@ reject_non_finite_json = finalizer._reject_non_finite_jsondef read_json_object(path: Path) -> dict[str, Any]:+ """Read a UTF-8 JSON object from path, raising SystemExit on read errors, malformed JSON, or another top-level type."""try:payload = json.loads(path.read_text(encoding="utf-8"),@@ -53,6 +54,7 @@ def timestamp_key(value: str) -> datetime:def require_uuid(value: str, label: str) -> str:+ """Return the standard hyphenated UUID text or raise SystemExit using label to identify the invalid argument."""try:return str(uuid.UUID(value))except ValueError as exc:@@ -67,6 +69,7 @@ path_within_scope = finalizer.path_within_scopedef require_close_note(close_reason: str | None, note: str | None) -> None:+ """Require a note when closing a finding as a false positive or when declining a fix."""if note is None and close_reason == "false_positive":raise SystemExit("Explain why this finding is a false positive.")if note is None and close_reason == "wont_fix":@@ -201,6 +204,11 @@ def _valid_measured_scan_usage(usage: object) -> bool:def parse_scan_cost(value: str | None) -> str | None:+ """Return compact JSON for valid measured usage or a legacy cost estimate.++ None means cost data was omitted. Invalid JSON, nonfinite numbers, or an+ unsupported cost record raise SystemExit.+ """if value is None:return Nonetry:@@ -223,11 +231,13 @@ def parse_scan_cost(value: str | None) -> str | None:def bounded_output_text(value: Any, maximum_bytes: int) -> str:+ """Return the prefix of the stringified value that fits in maximum_bytes of UTF-8 without splitting a character."""encoded = str(value).encode("utf-8")[:maximum_bytes]return encoded.decode("utf-8", errors="ignore")def require_occurrence(connection: sqlite3.Connection, occurrence_id: str) -> sqlite3.Row:+ """Return the finding occurrence row or raise SystemExit if its ID is missing or unknown."""occurrence_id = optional_text(occurrence_id, maximum=256)if occurrence_id is None:raise SystemExit("occurrence-id is required.")diff --git a/plugins/codex-security/skills/threat-model-visualize/scripts/build_explorer.py b/plugins/codex-security/skills/threat-model-visualize/scripts/build_explorer.pyindex 666474c7c..94aaeeb42 100644--- a/plugins/codex-security/skills/threat-model-visualize/scripts/build_explorer.py+++ b/plugins/codex-security/skills/threat-model-visualize/scripts/build_explorer.py@@ -16,7 +16,20 @@ def require(condition, message):def validate(model, assessment_bytes: bytes):+ """Check the explorer graph and its citations against the assessment before rendering.++ Args:+ model (dict): Parsed explorer JSON containing the graph, scenarios, and evidence.+ assessment_bytes (bytes): Original UTF-8 bytes used to match quotations, line ranges,+ and the optional assessment digest. Preserve the original line endings.++ Raises:+ ValueError: A graph relationship, layout value, or evidence check fails.+ KeyError: A required field is missing when accessed by name.+ """+def indexed(key, default=None):+ """Index a model collection by its unique, nonempty string IDs."""items = model.get(key, default)require(isinstance(items, list), f"{key} must be a list")ids = [item.get("id") for item in items]@@ -148,6 +161,7 @@ def validate(model, assessment_bytes: bytes):source_roles(model.get("participants", []), "participants", participant=True)def chain(item, scenario_id, route_id):+ """Return the edge IDs of a connected route after checking its assessment references."""ids = item.get("edges", [])require(isinstance(ids, list) and ids and all(i in edges for i in ids),@@ -163,6 +177,7 @@ def validate(model, assessment_bytes: bytes):return idsdef applicable_routes(control, routes, sources):+ """Return the routes selected by both the control and any sources it targets."""return [routefor route in routes@@ -482,6 +497,7 @@ def validate(model, assessment_bytes: bytes):def embedded(value):+ """Encode a value as JSON for an HTML script element, escaping HTML delimiters."""return (json.dumps(value, ensure_ascii=False, allow_nan=False).replace("<", "\\u003c")@@ -491,7 +507,10 @@ def embedded(value):def enters_node(start, end, node):- """Intersect the segment's parameter interval with the open box on each axis."""+ """Return whether the segment between two (x, y) points enters the open node rectangle.++ Contact with an edge or corner alone is allowed when routing a connector.+ """enter, leave = 0, 1for a, b, low, size in zip(start, end, (node["x"], node["y"]), (node["w"], node["h"])):high = low + size@@ -505,6 +524,7 @@ def enters_node(start, end, node):def connector_warnings(model):+ """Yield layout warnings for diagonal end bends and connectors that enter node interiors."""for edge in model["edges"]:segments = [(a, b) for a, b in pairwise(edge["points"]) if a != b]diagonal = [a[0] != b[0] and a[1] != b[1] for a, b in segments]@@ -518,6 +538,7 @@ def connector_warnings(model):def main():+ """Validate the assessment and model, write a self-contained HTML file, and print layout warnings."""parser = argparse.ArgumentParser(description=__doc__)parser.add_argument("model", type=Path)parser.add_argument("--assessment", required=True, type=Path)diff --git a/plugins/codex-security/tests/conftest.py b/plugins/codex-security/tests/conftest.pyindex c7b038c7d..1b9736de1 100644--- a/plugins/codex-security/tests/conftest.py+++ b/plugins/codex-security/tests/conftest.py@@ -1,3 +1,5 @@+"""Provide an isolated in-memory workbench database for each test using a shared migrated schema."""+from __future__ import annotationsimport runpy@@ -18,6 +20,7 @@ from publication_fixtures import ( # noqa: F401 -- pytest discovers these share@pytest.fixture(scope="session")def workbench_api():+ """Return the script globals used to exercise the workbench directly without starting its CLI."""script = Path(__file__).resolve().parents[1] / "scripts" / "workbench_db.py"return runpy.run_path(str(script), run_name="codex_security_test_workbench")@@ -34,6 +37,7 @@ def workbench_schema(workbench_api):@pytest.fixturedef workbench_db(workbench_schema):+ """Yield a fresh in-memory copy of the migrated schema with foreign keys enabled and named rows."""with closing(sqlite3.connect(":memory:")) as connection:connection.row_factory = sqlite3.Rowconnection.execute("PRAGMA foreign_keys = ON")diff --git a/plugins/codex-security/tests/deep_deadline_crash.py b/plugins/codex-security/tests/deep_deadline_crash.pyindex c5dda0a3b..e2a6fbdf7 100644--- a/plugins/codex-security/tests/deep_deadline_crash.py+++ b/plugins/codex-security/tests/deep_deadline_crash.py@@ -12,11 +12,14 @@ COMMIT_EXIT = 23class CrashBeforeCommit(sqlite3.Connection):+ """Terminate the child at its commit call so the parent can test recovery with unpublished database state."""+def commit(self):os._exit(COMMIT_EXIT)def interrupt_finish_before_commit(database, scan, hash_seed):+ """Run deadline completion in a child with the requested hash seed and require the simulated crash exit code."""result = subprocess.run([sys.executable,diff --git a/plugins/codex-security/tests/finalize_sarif_cases.py b/plugins/codex-security/tests/finalize_sarif_cases.pyindex 0cc1e31e6..e33b9a637 100644--- a/plugins/codex-security/tests/finalize_sarif_cases.py+++ b/plugins/codex-security/tests/finalize_sarif_cases.py@@ -1,3 +1,5 @@+"""Exercise SARIF source locations, URI encoding, and fingerprints against the scan's captured source."""+from __future__ import annotationsimport iodiff --git a/plugins/codex-security/tests/publication_fixtures.py b/plugins/codex-security/tests/publication_fixtures.pyindex 9a768e71b..ae7fff403 100644--- a/plugins/codex-security/tests/publication_fixtures.py+++ b/plugins/codex-security/tests/publication_fixtures.py@@ -1,3 +1,5 @@+"""Build recorded workbench scans and worker artifacts for publication and crash-recovery tests."""+from __future__ import annotationsimport copy@@ -14,7 +16,19 @@ from workbench_test_support import read_review_state, write_completed_contractclass PublicationScan(SimpleNamespace):+ """Drive publication and recovery against one test scan and its persisted worker records."""++ def worker_draft(self, findings=(), **coverage_updates):+ """Build a completed worker result using this scan's coverage as the starting point."""+ return {+ "scanId": self.scan_id,+ "complete": True,+ "findings": list(findings),+ "coverage": {**self.coverage, **coverage_updates},+ }+def add_worker(self, connection=None, *, status="succeeded") -> Path:+ """Register a discovery worker and return the path where the test can write its result manifest."""worker_id = str(uuid.uuid4())output = self.scan_dir / "workers" / worker_idoutput.mkdir(parents=True)@@ -221,16 +235,7 @@ def publication_scan(workbench_api, workbench_db, tmp_path, monkeypatch):def saturated_scan(publication_scan):scan = publication_scan()completed_result = scan.add_worker()- completed_result.write_text(- json.dumps(- {- "scanId": scan.scan_id,- "complete": True,- "findings": scan.findings,- "coverage": scan.coverage,- }- )- )+ completed_result.write_text(json.dumps(scan.worker_draft(scan.findings)))reducer_result = scan.add_worker()reducer_result.write_bytes(completed_result.read_bytes())with scan.connection:diff --git a/plugins/codex-security/tests/source_cases.py b/plugins/codex-security/tests/source_cases.pyindex fbbfc0219..caaf6ad7d 100644--- a/plugins/codex-security/tests/source_cases.py+++ b/plugins/codex-security/tests/source_cases.py@@ -11,6 +11,8 @@ from typing import NamedTupleclass SourceCase(NamedTuple):+ """Pair the original and modified contents of one repository-relative file for inventory and ranking tests."""+path: strbefore: strafter: strdiff --git a/plugins/codex-security/tests/test_checkpoint_publication_authority.py b/plugins/codex-security/tests/test_checkpoint_publication_authority.pyindex 63ea81688..9237bd49a 100644--- a/plugins/codex-security/tests/test_checkpoint_publication_authority.py+++ b/plugins/codex-security/tests/test_checkpoint_publication_authority.py@@ -1,3 +1,5 @@+"""Test which saved parent and worker checkpoints may supply findings after publication or a stop."""+from __future__ import annotationsimport copy@@ -47,16 +49,7 @@ def test_flat_retained_source_name_replays(workbench_db, publication_scan, sourc(scan.scan_dir / "findings.json").write_text(json.dumps({"findings": []}))scan.add_worker(status="canceled")source = scan.scan_dir / source_name- source.write_text(- json.dumps(- {- "scanId": scan.scan_id,- "complete": True,- "findings": scan.findings,- "coverage": scan.coverage,- }- )- )+ source.write_text(json.dumps(scan.worker_draft(scan.findings)))with workbench_db:workbench_db.execute("UPDATE deep_scan_workers SET result_manifest_path = ? WHERE scan_id = ?",@@ -206,12 +199,7 @@ def test_recovery_honors_rejection_committed_before_result_replacement(if archived:result_path = result_path.parent / "attempts" / "attempt-1" / "result.json"result_path.parent.mkdir(parents=True)- previous = {- "scanId": scan.scan_id,- "complete": True,- "findings": [provisional, retained],- "coverage": scan.coverage,- }+ previous = scan.worker_draft([provisional, retained])result_path.write_text(json.dumps(previous))old_checkpoint = write_checkpoint(result_path.parent / "checkpoints", previous)rejected = {@@ -258,22 +246,17 @@ def save_disposition(scan, directory, disposition):directory.mkdir(parents=True, exist_ok=True)finding = copy.deepcopy(scan.findings[0])finding["extensions"] = {"candidateId": "candidate-disposition"}- draft = {- "scanId": scan.scan_id,- "complete": True,- "findings": [finding] if disposition == "reported" else [],- "coverage": {- **scan.coverage,- "surfaces": [- {- "candidateId": "candidate-disposition",- "label": "Validated candidate disposition",- "disposition": disposition,- "receiptRefs": [],- }- ],- },- }+ draft = scan.worker_draft(+ [finding] if disposition == "reported" else [],+ surfaces=[+ {+ "candidateId": "candidate-disposition",+ "label": "Validated candidate disposition",+ "disposition": disposition,+ "receiptRefs": [],+ }+ ],+ )checkpoint = write_checkpoint(directory / "checkpoints", draft)head = select_checkpoint(directory, checkpoint)result = directory / "result.json"diff --git a/plugins/codex-security/tests/test_checkpoint_recovery_fallbacks.py b/plugins/codex-security/tests/test_checkpoint_recovery_fallbacks.pyindex b6dcb5aba..a0dd1e709 100644--- a/plugins/codex-security/tests/test_checkpoint_recovery_fallbacks.py+++ b/plugins/codex-security/tests/test_checkpoint_recovery_fallbacks.py@@ -1,3 +1,5 @@+"""Recover selected checkpoint records when sibling captures fail or a previous recovery was interrupted."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_checkpoint_schema.py b/plugins/codex-security/tests/test_checkpoint_schema.pyindex bd2e1e97a..5d9121c61 100644--- a/plugins/codex-security/tests/test_checkpoint_schema.py+++ b/plugins/codex-security/tests/test_checkpoint_schema.py@@ -1,3 +1,5 @@+"""Check that upgrading the checkpoint-head schema preserves scans and lets current readers proceed during a write."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_cli_dry_runs.py b/plugins/codex-security/tests/test_cli_dry_runs.pyindex 624902f16..d6400ccd7 100644--- a/plugins/codex-security/tests/test_cli_dry_runs.py+++ b/plugins/codex-security/tests/test_cli_dry_runs.py@@ -1,3 +1,5 @@+"""Exercise isolated script imports, CLI help, and finalization of the checked-in example bundle."""+from __future__ import annotationsimport shutildiff --git a/plugins/codex-security/tests/test_collect_checkmarx.py b/plugins/codex-security/tests/test_collect_checkmarx.pyindex d848342e8..b2943dc03 100644--- a/plugins/codex-security/tests/test_collect_checkmarx.py+++ b/plugins/codex-security/tests/test_collect_checkmarx.py@@ -1,3 +1,5 @@+"""Exercise selected Checkmarx One and CxSAST report collection with isolated vendor tools."""+import ioimport jsonimport osdiff --git a/plugins/codex-security/tests/test_deep_coverage_recovery.py b/plugins/codex-security/tests/test_deep_coverage_recovery.pyindex 016eb0761..cec9ce4d7 100644--- a/plugins/codex-security/tests/test_deep_coverage_recovery.py+++ b/plugins/codex-security/tests/test_deep_coverage_recovery.py@@ -1,3 +1,5 @@+"""Reconcile worker coverage with parent findings, deferred tasks, and their supporting receipts on replay."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_deep_deadline_recovery_edges.py b/plugins/codex-security/tests/test_deep_deadline_recovery_edges.pyindex 80df432dd..8f032273a 100644--- a/plugins/codex-security/tests/test_deep_deadline_recovery_edges.py+++ b/plugins/codex-security/tests/test_deep_deadline_recovery_edges.py@@ -1,3 +1,5 @@+"""Preserve usable worker checkpoints and earlier recovery files when deadline publication fails."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_deep_deadline_rollback.py b/plugins/codex-security/tests/test_deep_deadline_rollback.pyindex 3d1caf1a4..d9c8bc9d4 100644--- a/plugins/codex-security/tests/test_deep_deadline_rollback.py+++ b/plugins/codex-security/tests/test_deep_deadline_rollback.py@@ -1,3 +1,5 @@+"""Check which parent observations and worker evidence survive rollback of a deadline publication."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_deep_scan_deadline_contracts.py b/plugins/codex-security/tests/test_deep_scan_deadline_contracts.pyindex 3e8da2ed8..a1b653c86 100644--- a/plugins/codex-security/tests/test_deep_scan_deadline_contracts.py+++ b/plugins/codex-security/tests/test_deep_scan_deadline_contracts.py@@ -1,3 +1,5 @@+"""Require recovered deadline findings and worker closeouts to satisfy the completed scan contract."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_deep_scan_deadline_recovery.py b/plugins/codex-security/tests/test_deep_scan_deadline_recovery.pyindex 8d268684c..9c4bf68c6 100644--- a/plugins/codex-security/tests/test_deep_scan_deadline_recovery.py+++ b/plugins/codex-security/tests/test_deep_scan_deadline_recovery.py@@ -1,3 +1,5 @@+"""Replay deadline completion across crashes while preserving pending work and prior rejection decisions."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_deep_scan_deadline_surface_links.py b/plugins/codex-security/tests/test_deep_scan_deadline_surface_links.pyindex ae439b21d..81e419dc5 100644--- a/plugins/codex-security/tests/test_deep_scan_deadline_surface_links.py+++ b/plugins/codex-security/tests/test_deep_scan_deadline_surface_links.py@@ -1,3 +1,5 @@+"""Track source-to-surface links through deadline recovery, reused IDs, and repeated crashes."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_deep_scan_project_config.py b/plugins/codex-security/tests/test_deep_scan_project_config.pyindex 74e610cb5..e6cff3af1 100644--- a/plugins/codex-security/tests/test_deep_scan_project_config.py+++ b/plugins/codex-security/tests/test_deep_scan_project_config.py@@ -1,3 +1,5 @@+"""Check when project limits are captured and how simultaneous deep scans keep their settings separate."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_deep_scan_publication.py b/plugins/codex-security/tests/test_deep_scan_publication.pyindex d57a306be..0bb692e73 100644--- a/plugins/codex-security/tests/test_deep_scan_publication.py+++ b/plugins/codex-security/tests/test_deep_scan_publication.py@@ -1,3 +1,5 @@+"""Compare an archived deep scan publication with the snapshot used to produce it."""+from __future__ import annotationsimport importlibdiff --git a/plugins/codex-security/tests/test_deep_scan_publication_authority.py b/plugins/codex-security/tests/test_deep_scan_publication_authority.pyindex d5aab2a1b..a2404ea73 100644--- a/plugins/codex-security/tests/test_deep_scan_publication_authority.py+++ b/plugins/codex-security/tests/test_deep_scan_publication_authority.py@@ -1,3 +1,5 @@+"""Check coordinator ownership and receipt validation when publishing or replaying a deep scan."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_deep_scan_publication_replay.py b/plugins/codex-security/tests/test_deep_scan_publication_replay.pyindex 34871113b..a59c048b5 100644--- a/plugins/codex-security/tests/test_deep_scan_publication_replay.py+++ b/plugins/codex-security/tests/test_deep_scan_publication_replay.py@@ -1,3 +1,5 @@+"""Replay the inputs selected before a publication crash while protecting newer canonical output."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_deep_scan_request_identity.py b/plugins/codex-security/tests/test_deep_scan_request_identity.pyindex edda16ae6..a17e768fe 100644--- a/plugins/codex-security/tests/test_deep_scan_request_identity.py+++ b/plugins/codex-security/tests/test_deep_scan_request_identity.py@@ -1,3 +1,5 @@+"""Match resumable deep scans to their original target and discovery context, including older records."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_deep_scan_stop_conditions.py b/plugins/codex-security/tests/test_deep_scan_stop_conditions.pyindex 0d9a54024..c35644499 100644--- a/plugins/codex-security/tests/test_deep_scan_stop_conditions.py+++ b/plugins/codex-security/tests/test_deep_scan_stop_conditions.py@@ -1,3 +1,5 @@+"""Recover findings and checkpoint evidence when deep scans hit a stop condition."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_deep_scan_successful_publication.py b/plugins/codex-security/tests/test_deep_scan_successful_publication.pyindex 19d2ad175..3a899ce76 100644--- a/plugins/codex-security/tests/test_deep_scan_successful_publication.py+++ b/plugins/codex-security/tests/test_deep_scan_successful_publication.py@@ -1,3 +1,5 @@+"""Check how final deep scan reports preserve remediation, selected paths, and worker evidence."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_deep_security_scan_concurrency_guard.py b/plugins/codex-security/tests/test_deep_security_scan_concurrency_guard.pyindex 84093455e..89beb9f4a 100644--- a/plugins/codex-security/tests/test_deep_security_scan_concurrency_guard.py+++ b/plugins/codex-security/tests/test_deep_security_scan_concurrency_guard.py@@ -1,3 +1,5 @@+"""Check that scan context counts concurrent deep scans while excluding the current run."""+from __future__ import annotationsimport uuiddiff --git a/plugins/codex-security/tests/test_finalize_scan_contract.py b/plugins/codex-security/tests/test_finalize_scan_contract.pyindex 799910775..1e1fb6083 100644--- a/plugins/codex-security/tests/test_finalize_scan_contract.py+++ b/plugins/codex-security/tests/test_finalize_scan_contract.py@@ -1,3 +1,5 @@+"""Exercise sealing and recovery of scan bundles, including inputs that change during finalization."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_finalize_scan_timestamps.py b/plugins/codex-security/tests/test_finalize_scan_timestamps.pyindex dcc50a2a3..91967c98e 100644--- a/plugins/codex-security/tests/test_finalize_scan_timestamps.py+++ b/plugins/codex-security/tests/test_finalize_scan_timestamps.py@@ -1,3 +1,5 @@+"""Distinguish workbench timestamps from model-supplied times when sealing and exporting a scan."""+from __future__ import annotationsimport osdiff --git a/plugins/codex-security/tests/test_finalize_schema_validation.py b/plugins/codex-security/tests/test_finalize_schema_validation.pyindex f1fe9c2a9..6bd98de96 100644--- a/plugins/codex-security/tests/test_finalize_schema_validation.py+++ b/plugins/codex-security/tests/test_finalize_schema_validation.py@@ -1,3 +1,5 @@+"""Exercise numeric types and constraints on referenced nodes in the finalizer's schema checker."""+from __future__ import annotationsimport pytestdiff --git a/plugins/codex-security/tests/test_finalize_writeup_recovery.py b/plugins/codex-security/tests/test_finalize_writeup_recovery.pyindex e2f23a8a8..0640623c7 100644--- a/plugins/codex-security/tests/test_finalize_writeup_recovery.py+++ b/plugins/codex-security/tests/test_finalize_writeup_recovery.py@@ -1,3 +1,5 @@+"""Distinguish a missing optional writeup from other read failures during scan recovery."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_finding_issue_receipts.py b/plugins/codex-security/tests/test_finding_issue_receipts.pyindex 1b690ded0..81244f719 100644--- a/plugins/codex-security/tests/test_finding_issue_receipts.py+++ b/plugins/codex-security/tests/test_finding_issue_receipts.py@@ -1,3 +1,5 @@+"""Verify that issue receipts stay bound to their finding and that inspection preserves local state."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_finding_preview.py b/plugins/codex-security/tests/test_finding_preview.pyindex 1bfcf4c5c..0d1226cf7 100644--- a/plugins/codex-security/tests/test_finding_preview.py+++ b/plugins/codex-security/tests/test_finding_preview.py@@ -1,3 +1,5 @@+"""Check how finding previews fit a size budget while retaining report text and diagnostics."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_git_inventory_regressions.py b/plugins/codex-security/tests/test_git_inventory_regressions.pyindex 20e7c9fb6..86f84e877 100644--- a/plugins/codex-security/tests/test_git_inventory_regressions.py+++ b/plugins/codex-security/tests/test_git_inventory_regressions.py@@ -1,3 +1,5 @@+"""Exercise local Git inventories for root commits, worktree changes, submodules, and optional snapshots."""+from __future__ import annotationsimport hashlibdiff --git a/plugins/codex-security/tests/test_partial_coverage_projection.py b/plugins/codex-security/tests/test_partial_coverage_projection.pyindex a0d2020cc..745e8b521 100644--- a/plugins/codex-security/tests/test_partial_coverage_projection.py+++ b/plugins/codex-security/tests/test_partial_coverage_projection.py@@ -1,3 +1,5 @@+"""Preserve source-specific receipts, surface links, and pending work when projecting partial coverage."""+from __future__ import annotationsimport copy@@ -62,17 +64,7 @@ def test_parent_candidate_outcome_compares_headless_worker_chronology("receiptRefs": [],}task = {"id": "worker-task", "candidateId": candidate, "reason": "Validate worker evidence."}- draft = {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {- **scan.coverage,- "completeness": "partial",- "surfaces": [surface],- "deferred": [task],- },- }+ draft = scan.worker_draft(completeness="partial", surfaces=[surface], deferred=[task])write_result_draft(result, draft, mtime_ns=300)originals = {result: result.read_bytes()}if has_head:@@ -154,17 +146,7 @@ def test_missing_deferred_projection_links_first_duplicate_surface(}result.write_text(json.dumps(- {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {- **scan.coverage,- "completeness": "partial",- "surfaces": surfaces,- "deferred": [deferred],- },- }+ scan.worker_draft(completeness="partial", surfaces=surfaces, deferred=[deferred])))original = result.read_bytes()@@ -503,17 +485,9 @@ def test_missing_projection_keeps_surface_links_and_independent_reviews()result.write_text(json.dumps(- {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {- **scan.coverage,- "completeness": "partial",- "surfaces": worker_surfaces,- "deferred": [deferred],- },- }+ scan.worker_draft(+ completeness="partial", surfaces=worker_surfaces, deferred=[deferred]+ )))originals[result] = result.read_bytes()@@ -567,16 +541,7 @@ def test_previous_attempt_resolution_does_not_clear_current_gap(result = scan.add_worker()worker_id = result.parent.namedeferred = {"candidateId": "candidate-1", "reason": "Validate the current attempt."}- result.write_text(- json.dumps(- {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {**scan.coverage, "completeness": "partial", "deferred": [deferred]},- }- )- )+ result.write_text(json.dumps(scan.worker_draft(completeness="partial", deferred=[deferred])))original = result.read_bytes()with workbench_db:workbench_db.execute(@@ -630,16 +595,7 @@ def test_recovery_compares_open_questions_using_canonical_normalization(" Which deployment controls apply? ",{"question": " Which runtime settings apply? ", "followUpPrompt": " \t"},]- result.write_text(- json.dumps(- {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {**scan.coverage, "openQuestions": questions},- }- )- )+ result.write_text(json.dumps(scan.worker_draft(openQuestions=questions)))original = result.read_bytes()if selected_checkpoint:checkpoint = write_checkpoint(result.parent / "checkpoints", json.loads(result.read_text()))@@ -697,16 +653,7 @@ def test_rejected_retry_preserves_original_finding_history("disposition": "rejected","receiptRefs": [],}- result.write_text(- json.dumps(- {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {**scan.coverage, "surfaces": [surface]},- }- )- )+ result.write_text(json.dumps(scan.worker_draft(surfaces=[surface])))with workbench_db:workbench_db.execute("UPDATE deep_scan_workers SET attempt = 2 WHERE id = ?", (worker_id,))other_result = scan.add_worker()@@ -781,16 +728,7 @@ def test_stopped_recovery_keeps_current_parent_projection(result = scan.add_worker()worker_id = result.parent.namedeferred = {"candidateId": "candidate-1", "reason": "The current review remains unresolved."}- result.write_text(- json.dumps(- {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {**scan.coverage, "completeness": "partial", "deferred": [deferred]},- }- )- )+ result.write_text(json.dumps(scan.worker_draft(completeness="partial", deferred=[deferred])))reducer = scan.add_worker()reducer.write_text(json.dumps({"scanId": scan.scan_id, "findings": []}))reducer_checkpoint = write_checkpoint(@@ -934,24 +872,18 @@ def test_matching_accepted_checkpoint_preserves_receipt_path(receipt = result.parent / "artifacts" / "evidence.txt"receipt.parent.mkdir(parents=True, exist_ok=True)receipt.write_text("Synthetic source-review evidence.")- draft = {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {- **scan.coverage,- "completeness": "complete",- "deferred": [],- "surfaces": [- {- "id": "source-review",- "label": "Accepted source review",- "disposition": "no_issue_found",- "receiptRefs": ["artifacts/evidence.txt"],- }- ],- },- }+ draft = scan.worker_draft(+ completeness="complete",+ deferred=[],+ surfaces=[+ {+ "id": "source-review",+ "label": "Accepted source review",+ "disposition": "no_issue_found",+ "receiptRefs": ["artifacts/evidence.txt"],+ }+ ],+ )result.write_text(json.dumps(draft))checkpoint = write_checkpoint(result.parent / "checkpoints", draft)os.utime(result, ns=(100, 100))@@ -1018,12 +950,7 @@ def test_idless_accepted_surface_matches_projection_after_checkpoint_id_inferenc"disposition": "no_issue_found","receiptRefs": [],}- draft = {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {**scan.coverage, "surfaces": [surface]},- }+ draft = scan.worker_draft(surfaces=[surface])result.write_text(json.dumps(draft))checkpoint = write_checkpoint(result.parent / "checkpoints",@@ -1077,16 +1004,7 @@ def test_parent_candidate_provenance_cannot_override_accepted_worker_evidence(finding = copy.deepcopy(scan.findings[0])finding["provenance"]["candidateId"] = "source-candidate"finding["summary"] = "Accepted independent source evidence."- result.write_text(- json.dumps(- {- "scanId": scan.scan_id,- "complete": True,- "findings": [finding],- "coverage": scan.coverage,- }- )- )+ result.write_text(json.dumps(scan.worker_draft([finding])))originals = {result: result.read_bytes()}if selected_checkpoint:checkpoint = write_checkpoint(result.parent / "checkpoints", json.loads(result.read_text()))@@ -1158,17 +1076,7 @@ def test_projected_generic_closure_updates_parent_copy_in_its_worker_namespace("reason": "Complete source follow-up.","surfaceIds": [surface["id"]],}- draft = {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {- **scan.coverage,- "completeness": "partial",- "surfaces": [surface],- "deferred": [task],- },- }+ draft = scan.worker_draft(completeness="partial", surfaces=[surface], deferred=[task])result.write_text(json.dumps(draft))projected_surface = {**surface,@@ -1259,17 +1167,7 @@ def test_selected_candidate_outcome_removes_its_projected_parent_pending_rows("candidateId": candidate,"reason": "Complete candidate follow-up.",}- draft = {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {- **scan.coverage,- "completeness": "partial",- "surfaces": [surface],- "deferred": [task],- },- }+ draft = scan.worker_draft(completeness="partial", surfaces=[surface], deferred=[task])result.write_text(json.dumps(draft))projected_candidate = (f"{worker_id}-attempt-1-candidate-{hashlib.sha256(candidate.encode()).hexdigest()}"@@ -1410,17 +1308,7 @@ def test_selected_worker_projection_keeps_links_and_pending_authority(receipt = result.parent / "artifacts" / f"{name}.txt"receipt.parent.mkdir(exist_ok=True)receipt.write_text(f"Synthetic {name} receipt.\n")- draft = {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {- **scan.coverage,- "completeness": "partial",- "surfaces": surfaces,- "deferred": deferred,- },- }+ draft = scan.worker_draft(completeness="partial", surfaces=surfaces, deferred=deferred)if change == "reopened mixed receipts":draft["coverage"]["resolvedDeferred"] = [{"id": task["id"], "reason": "Earlier source follow-up completed."}@@ -1644,17 +1532,7 @@ def test_linked_archived_receipts_preserve_accepted_surface_links("disposition": "needs_follow_up","receiptRefs": ["artifacts/review.txt"],}- draft = {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {- **scan.coverage,- "completeness": "partial",- "surfaces": [surface],- "deferred": [],- },- }+ draft = scan.worker_draft(completeness="partial", surfaces=[surface], deferred=[])result.write_text(json.dumps(draft))projected = {**surface,@@ -1822,17 +1700,7 @@ def test_deferred_projection_preserves_each_referenced_source_surface({"id": f"task-{index}", "reason": f"Verify source {index}.", "surfaceIds": [surface["id"]]}for index, surface in enumerate(surfaces)]- draft = {- "scanId": scan.scan_id,- "complete": True,- "findings": [],- "coverage": {- **scan.coverage,- "completeness": "partial",- "surfaces": surfaces,- "deferred": deferred,- },- }+ draft = scan.worker_draft(completeness="partial", surfaces=surfaces, deferred=deferred)result.write_text(json.dumps(draft))original = result.read_bytes()for name in ("scan-manifest.json", "findings.json", "coverage.json"):diff --git a/plugins/codex-security/tests/test_plugin_contract.py b/plugins/codex-security/tests/test_plugin_contract.pyindex 63c2c2730..e1e0469c5 100644--- a/plugins/codex-security/tests/test_plugin_contract.py+++ b/plugins/codex-security/tests/test_plugin_contract.py@@ -1,3 +1,5 @@+"""Check the plugin manifest, skill interfaces, declared app connections, and referenced assets."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_portable_artifact_paths.py b/plugins/codex-security/tests/test_portable_artifact_paths.pyindex 85278b9f8..16ed6fbee 100644--- a/plugins/codex-security/tests/test_portable_artifact_paths.py+++ b/plugins/codex-security/tests/test_portable_artifact_paths.py@@ -1,3 +1,5 @@+"""Distinguish portable sealed-artifact names from the source paths a finding may cite."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_recovered_worker_closeouts.py b/plugins/codex-security/tests/test_recovered_worker_closeouts.pyindex 29f7f5938..8ac615a24 100644--- a/plugins/codex-security/tests/test_recovered_worker_closeouts.py+++ b/plugins/codex-security/tests/test_recovered_worker_closeouts.py@@ -1,3 +1,5 @@+"""Track worker closeouts through parent copies, reopened work, and archived attempts."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_report_projection.py b/plugins/codex-security/tests/test_report_projection.pyindex 0b7ded5e4..09c12b9bf 100644--- a/plugins/codex-security/tests/test_report_projection.py+++ b/plugins/codex-security/tests/test_report_projection.py@@ -1,3 +1,5 @@+"""Check how structured scan records and legacy evidence become readable Markdown reports."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_resolved_deferred_finalization.py b/plugins/codex-security/tests/test_resolved_deferred_finalization.pyindex 26d850775..f9c96073d 100644--- a/plugins/codex-security/tests/test_resolved_deferred_finalization.py+++ b/plugins/codex-security/tests/test_resolved_deferred_finalization.py@@ -1,3 +1,5 @@+"""Check how finalization reconciles completed deferred work with the remaining coverage record."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_review_state.py b/plugins/codex-security/tests/test_review_state.pyindex b03a02bad..7aa0804fa 100644--- a/plugins/codex-security/tests/test_review_state.py+++ b/plugins/codex-security/tests/test_review_state.py@@ -1,3 +1,5 @@+"""Reconstruct coverage from results that contain review state but have no separate coverage file."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_root_candidate_authority.py b/plugins/codex-security/tests/test_root_candidate_authority.pyindex b9ed0e7b0..5d0741df3 100644--- a/plugins/codex-security/tests/test_root_candidate_authority.py+++ b/plugins/codex-security/tests/test_root_candidate_authority.py@@ -1,3 +1,5 @@+"""Resolve competing root candidate outcomes from canonical, pending, and legacy checkpoint evidence."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_runtime_settings.py b/plugins/codex-security/tests/test_runtime_settings.pyindex bf078ec05..bd8ccd928 100644--- a/plugins/codex-security/tests/test_runtime_settings.py+++ b/plugins/codex-security/tests/test_runtime_settings.py@@ -1,3 +1,5 @@+"""Check Python settings against SDK conventions for home paths, TOML numbers, and parser availability."""+from __future__ import annotationsimport runpydiff --git a/plugins/codex-security/tests/test_sarif_projection.py b/plugins/codex-security/tests/test_sarif_projection.pyindex 02dc7fa02..2a36a40ac 100644--- a/plugins/codex-security/tests/test_sarif_projection.py+++ b/plugins/codex-security/tests/test_sarif_projection.py@@ -1,3 +1,5 @@+"""Project sealed findings into SARIF while preserving alert identity, rule metadata, and run warnings."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_saved_deferred_identity.py b/plugins/codex-security/tests/test_saved_deferred_identity.pyindex 4d538a8d2..d3aadd92e 100644--- a/plugins/codex-security/tests/test_saved_deferred_identity.py+++ b/plugins/codex-security/tests/test_saved_deferred_identity.py@@ -1,3 +1,5 @@+"""Track deferred observations through ID collisions, worker revisions, and frozen source order."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_saved_deferred_unicode.py b/plugins/codex-security/tests/test_saved_deferred_unicode.pyindex 41062d488..5ecec879a 100644--- a/plugins/codex-security/tests/test_saved_deferred_unicode.py+++ b/plugins/codex-security/tests/test_saved_deferred_unicode.py@@ -1,3 +1,5 @@+"""Recover and publish scans whose earlier writers stored Unicode review identifiers."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_saved_threat_model_recovery.py b/plugins/codex-security/tests/test_saved_threat_model_recovery.pyindex 477c1e8b2..ebd8c611a 100644--- a/plugins/codex-security/tests/test_saved_threat_model_recovery.py+++ b/plugins/codex-security/tests/test_saved_threat_model_recovery.py@@ -1,3 +1,5 @@+"""Recover findings and replay the frozen result when optional threat-model context is invalid."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_scan_contract_examples.py b/plugins/codex-security/tests/test_scan_contract_examples.pyindex 0871e54ae..5cb65d02d 100644--- a/plugins/codex-security/tests/test_scan_contract_examples.py+++ b/plugins/codex-security/tests/test_scan_contract_examples.py@@ -1,3 +1,5 @@+"""Validate the checked-in scan examples and exercise schema boundaries for evidence and coverage."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_scan_local_write_cleanup.py b/plugins/codex-security/tests/test_scan_local_write_cleanup.pyindex 35ebb5434..efc54e40f 100644--- a/plugins/codex-security/tests/test_scan_local_write_cleanup.py+++ b/plugins/codex-security/tests/test_scan_local_write_cleanup.py@@ -1,3 +1,5 @@+"""Exercise cleanup and file-identity checks when scan-local writes race or fail partway."""+from __future__ import annotationsimport ctypesdiff --git a/plugins/codex-security/tests/test_threat_model_projection.py b/plugins/codex-security/tests/test_threat_model_projection.pyindex 6a13d17ac..a86845698 100644--- a/plugins/codex-security/tests/test_threat_model_projection.py+++ b/plugins/codex-security/tests/test_threat_model_projection.py@@ -1,3 +1,5 @@+"""Check how authored Markdown and older threat models are sealed, recovered, and exported."""+from __future__ import annotationsimport iodiff --git a/plugins/codex-security/tests/test_threat_model_visualize.py b/plugins/codex-security/tests/test_threat_model_visualize.pyindex 8fd49d248..69b270e29 100644--- a/plugins/codex-security/tests/test_threat_model_visualize.py+++ b/plugins/codex-security/tests/test_threat_model_visualize.py@@ -1,4 +1,4 @@-"""Semantic guard checks for control effects. Python 3.12+."""+"""Test explorer validation against assessment bytes and inspect the resulting self-contained HTML."""import copyimport hashlib@@ -19,6 +19,7 @@ spec.loader.exec_module(builder)def run_builder(model_file, source, output):+ """Run the explorer CLI on the supplied paths and return its exit status, stdout, and stderr."""return subprocess.run([sys.executable,@@ -59,6 +60,8 @@ class EmbeddedHtml(HTMLParser):class ControlValidation(unittest.TestCase):+ """Vary a three-node scenario to test route, control, evidence, and rendering contracts."""+def setUp(self):self.model = {"brand": "Synthetic assessment",@@ -135,6 +138,17 @@ class ControlValidation(unittest.TestCase):def build_html(self, assessment_bytes, *, error=None, existing_html=None, model_encoding="utf-8"):+ """Run the builder with temporary inputs and check the outcome.++ Args:+ assessment_bytes (bytes): Exact assessment content used to validate the model.+ error (str | None): Expected stderr substring for a build that exits with status 2.+ existing_html (str | None): Prior output to seed and check after a failed build.+ model_encoding (str): Encoding used to write the model fixture.++ Returns:+ str | None: The generated HTML on success, or None after the expected failure.+ """with tempfile.TemporaryDirectory() as folder:folder = Path(folder)model_file, source, output = (@@ -162,6 +176,7 @@ class ControlValidation(unittest.TestCase):return output.read_text(encoding="utf-8")def embedded_data(self, html, element_id):+ """Decode the single application/json script with element_id from the generated HTML."""values = [codefor tag, attrs, code in EmbeddedHtml(html).elementsdiff --git a/plugins/codex-security/tests/test_track_findings_skill.py b/plugins/codex-security/tests/test_track_findings_skill.pyindex 36918bc93..9eb9b9c75 100644--- a/plugins/codex-security/tests/test_track_findings_skill.py+++ b/plugins/codex-security/tests/test_track_findings_skill.py@@ -1,3 +1,5 @@+"""Check provider app declarations and the instructions for reading back a published finding."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_validate_scan_contract.py b/plugins/codex-security/tests/test_validate_scan_contract.pyindex ce96d3d04..fb41ec7fb 100644--- a/plugins/codex-security/tests/test_validate_scan_contract.py+++ b/plugins/codex-security/tests/test_validate_scan_contract.py@@ -1,3 +1,5 @@+"""Exercise read-only validation of sealed bundles, including legacy evidence and unsealed inputs."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_windows_report_e2e.py b/plugins/codex-security/tests/test_windows_report_e2e.pyindex 6bdb8a6a3..61d934ba2 100644--- a/plugins/codex-security/tests/test_windows_report_e2e.py+++ b/plugins/codex-security/tests/test_windows_report_e2e.py@@ -1,3 +1,5 @@+"""Complete and export a scan through the native Windows filesystem backend."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_windows_scan_local_files.py b/plugins/codex-security/tests/test_windows_scan_local_files.pyindex 9dc5f1889..1b55b9a60 100644--- a/plugins/codex-security/tests/test_windows_scan_local_files.py+++ b/plugins/codex-security/tests/test_windows_scan_local_files.py@@ -1,3 +1,5 @@+"""Exercise Windows scan-local path handling across aliases, junctions, and replacement races."""+from __future__ import annotationsimport argparsediff --git a/plugins/codex-security/tests/test_workbench_archive.py b/plugins/codex-security/tests/test_workbench_archive.pyindex 43614e831..e094dd883 100644--- a/plugins/codex-security/tests/test_workbench_archive.py+++ b/plugins/codex-security/tests/test_workbench_archive.py@@ -1,3 +1,5 @@+"""Exercise output archiving when registrations race, fail, or encounter aliases to active state."""+from __future__ import annotationsimport argparsediff --git a/plugins/codex-security/tests/test_workbench_cancellation.py b/plugins/codex-security/tests/test_workbench_cancellation.pyindex cae122b3e..2d40c6db5 100644--- a/plugins/codex-security/tests/test_workbench_cancellation.py+++ b/plugins/codex-security/tests/test_workbench_cancellation.py@@ -1,3 +1,5 @@+"""Test scan ownership and coherent workbench responses when cancellation or replacement races a request."""+from __future__ import annotationsimport argparsediff --git a/plugins/codex-security/tests/test_workbench_checkpoint_heads.py b/plugins/codex-security/tests/test_workbench_checkpoint_heads.pyindex e2ccfb6da..a4d8c6780 100644--- a/plugins/codex-security/tests/test_workbench_checkpoint_heads.py+++ b/plugins/codex-security/tests/test_workbench_checkpoint_heads.py@@ -1,3 +1,5 @@+"""Replay frozen checkpoint selections across late changes, tied timestamps, and explicit recovery."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_workbench_cli.py b/plugins/codex-security/tests/test_workbench_cli.pyindex c43958a69..a332ad6d7 100644--- a/plugins/codex-security/tests/test_workbench_cli.py+++ b/plugins/codex-security/tests/test_workbench_cli.py@@ -1,3 +1,5 @@+"""Check how workbench commands read context from stdin and handle conflicting inputs."""+from __future__ import annotationsimport osdiff --git a/plugins/codex-security/tests/test_workbench_completion_binding.py b/plugins/codex-security/tests/test_workbench_completion_binding.pyindex 7646cfd9a..331cdd7be 100644--- a/plugins/codex-security/tests/test_workbench_completion_binding.py+++ b/plugins/codex-security/tests/test_workbench_completion_binding.py@@ -1,3 +1,5 @@+"""Bind CLI scan counts, final artifacts, and recovered coverage to the registered target."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_workbench_db.py b/plugins/codex-security/tests/test_workbench_db.pyindex a07d015be..b24b0b68e 100644--- a/plugins/codex-security/tests/test_workbench_db.py+++ b/plugins/codex-security/tests/test_workbench_db.py@@ -1,3 +1,5 @@+"""Exercise persisted workbench operations, including scan budgets, finding state, and patch identity."""+from __future__ import annotationsimport hashlibdiff --git a/plugins/codex-security/tests/test_workbench_db_exports.py b/plugins/codex-security/tests/test_workbench_db_exports.pyindex f98b9cc66..293f33702 100644--- a/plugins/codex-security/tests/test_workbench_db_exports.py+++ b/plugins/codex-security/tests/test_workbench_db_exports.py@@ -1,3 +1,5 @@+"""Export saved findings from stopped scans while retaining newer drafts across recovery."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_workbench_deep_scan.py b/plugins/codex-security/tests/test_workbench_deep_scan.pyindex 9d87ab61c..7b44c6bd3 100644--- a/plugins/codex-security/tests/test_workbench_deep_scan.py+++ b/plugins/codex-security/tests/test_workbench_deep_scan.py@@ -1,3 +1,5 @@+"""Exercise deep scan registration, coordinator claims, iteration ordering, and terminal state transitions."""+from __future__ import annotationsimport hashlib@@ -191,6 +193,8 @@ def write_canonical_artifacts(scan_dir: Path) -> dict[str, Path]:@dataclass(frozen=True)class DeepScan:+ """Keep a test scan ID, state directory, and Codex home together when issuing worker and coordinator commands."""+state_dir: Pathcodex_home: Pathid: strdiff --git a/plugins/codex-security/tests/test_workbench_diagnostics.py b/plugins/codex-security/tests/test_workbench_diagnostics.pyindex 33339db0a..dc3eb321c 100644--- a/plugins/codex-security/tests/test_workbench_diagnostics.py+++ b/plugins/codex-security/tests/test_workbench_diagnostics.py@@ -1,3 +1,5 @@+"""Check that workbench failures retain their full diagnostics through terminal updates and replay."""+from __future__ import annotationsimport sqlite3diff --git a/plugins/codex-security/tests/test_workbench_draft_publication.py b/plugins/codex-security/tests/test_workbench_draft_publication.pyindex 0c3da7d10..3b70729a3 100644--- a/plugins/codex-security/tests/test_workbench_draft_publication.py+++ b/plugins/codex-security/tests/test_workbench_draft_publication.py@@ -1,3 +1,5 @@+"""Exercise deep scan drafts before orchestration and after the run has reached a terminal state."""+from __future__ import annotationsimport hashlibdiff --git a/plugins/codex-security/tests/test_workbench_feedback.py b/plugins/codex-security/tests/test_workbench_feedback.pyindex d4098a3aa..1f468187b 100644--- a/plugins/codex-security/tests/test_workbench_feedback.py+++ b/plugins/codex-security/tests/test_workbench_feedback.py@@ -1,3 +1,5 @@+"""Project false-positive decisions into later scans and preserve the reasons behind triage changes."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_workbench_finding_workflows.py b/plugins/codex-security/tests/test_workbench_finding_workflows.pyindex 3f274a7b3..407c2e298 100644--- a/plugins/codex-security/tests/test_workbench_finding_workflows.py+++ b/plugins/codex-security/tests/test_workbench_finding_workflows.py@@ -1,3 +1,5 @@+"""Exercise competing finding workflow registrations and the scope of their optional evidence snapshots."""+from __future__ import annotationsimport hashlibdiff --git a/plugins/codex-security/tests/test_workbench_handoff.py b/plugins/codex-security/tests/test_workbench_handoff.pyindex cc45ac7fb..7c1c8526b 100644--- a/plugins/codex-security/tests/test_workbench_handoff.py+++ b/plugins/codex-security/tests/test_workbench_handoff.py@@ -1,3 +1,5 @@+"""Check handoff claims, releases, and continuation ownership across concurrent workbench requests."""+from __future__ import annotationsimport sqlite3diff --git a/plugins/codex-security/tests/test_workbench_local_dedupe.py b/plugins/codex-security/tests/test_workbench_local_dedupe.pyindex b09236365..d850158f7 100644--- a/plugins/codex-security/tests/test_workbench_local_dedupe.py+++ b/plugins/codex-security/tests/test_workbench_local_dedupe.py@@ -1,3 +1,5 @@+"""Check that embedding cache migrations preserve vectors and distinguish local and service records."""+from __future__ import annotationsimport sqlite3diff --git a/plugins/codex-security/tests/test_workbench_native_index_queries.py b/plugins/codex-security/tests/test_workbench_native_index_queries.pyindex 01a780079..27e1933b6 100644--- a/plugins/codex-security/tests/test_workbench_native_index_queries.py+++ b/plugins/codex-security/tests/test_workbench_native_index_queries.py@@ -1,3 +1,5 @@+"""Exercise filtering, pagination, and latest-scan selection in finding and repository indexes."""+from __future__ import annotationsimport ntpathdiff --git a/plugins/codex-security/tests/test_workbench_native_indexes.py b/plugins/codex-security/tests/test_workbench_native_indexes.pyindex 6e8d34f74..80b3649fe 100644--- a/plugins/codex-security/tests/test_workbench_native_indexes.py+++ b/plugins/codex-security/tests/test_workbench_native_indexes.py@@ -1,3 +1,5 @@+"""Check cross-scan finding identity, repository counts, and Unicode search in the workbench indexes."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_workbench_output_permissions.py b/plugins/codex-security/tests/test_workbench_output_permissions.pyindex 8613231cc..add821b1e 100644--- a/plugins/codex-security/tests/test_workbench_output_permissions.py+++ b/plugins/codex-security/tests/test_workbench_output_permissions.py@@ -1,3 +1,5 @@+"""Check private output creation under permissive umasks and reuse of existing directories."""+from __future__ import annotationsimport osdiff --git a/plugins/codex-security/tests/test_workbench_progress.py b/plugins/codex-security/tests/test_workbench_progress.pyindex aa44a2898..86871e003 100644--- a/plugins/codex-security/tests/test_workbench_progress.py+++ b/plugins/codex-security/tests/test_workbench_progress.py@@ -1,3 +1,5 @@+"""Carry phase receipts and historical preflight diagnostics through workbench progress updates."""+import jsonimport sqlite3from pathlib import Pathdiff --git a/plugins/codex-security/tests/test_workbench_prompt_only_scan.py b/plugins/codex-security/tests/test_workbench_prompt_only_scan.pyindex 2f2eca21a..25c24b3bd 100644--- a/plugins/codex-security/tests/test_workbench_prompt_only_scan.py+++ b/plugins/codex-security/tests/test_workbench_prompt_only_scan.py@@ -1,3 +1,5 @@+"""Check ownership, target identity, and backwards compatibility when starting scans without setup."""+from __future__ import annotationsimport argparsediff --git a/plugins/codex-security/tests/test_workbench_recovery_outcome_validation.py b/plugins/codex-security/tests/test_workbench_recovery_outcome_validation.pyindex 833492b52..071baa6be 100644--- a/plugins/codex-security/tests/test_workbench_recovery_outcome_validation.py+++ b/plugins/codex-security/tests/test_workbench_recovery_outcome_validation.py@@ -1,3 +1,5 @@+"""Require evidence for rejection and closure decisions before recovered scans can be sealed."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_workbench_remediation_cancellation.py b/plugins/codex-security/tests/test_workbench_remediation_cancellation.pyindex 4ef1c6d64..921bc4196 100644--- a/plugins/codex-security/tests/test_workbench_remediation_cancellation.py+++ b/plugins/codex-security/tests/test_workbench_remediation_cancellation.py@@ -1,3 +1,5 @@+"""Check that canceling a remediation request restores the finding's prior state."""+from __future__ import annotationsimport subprocessdiff --git a/plugins/codex-security/tests/test_workbench_remediation_retry.py b/plugins/codex-security/tests/test_workbench_remediation_retry.pyindex 4bb0e9b14..915867479 100644--- a/plugins/codex-security/tests/test_workbench_remediation_retry.py+++ b/plugins/codex-security/tests/test_workbench_remediation_retry.py@@ -1,3 +1,5 @@+"""Exercise patch verification and retries after failed remediation steps, including offline Git reads."""+from __future__ import annotationsimport argparsediff --git a/plugins/codex-security/tests/test_workbench_saved_source_order.py b/plugins/codex-security/tests/test_workbench_saved_source_order.pyindex f8867b4f1..e0294e18d 100644--- a/plugins/codex-security/tests/test_workbench_saved_source_order.py+++ b/plugins/codex-security/tests/test_workbench_saved_source_order.py@@ -1,3 +1,5 @@+"""Check which saved sources a stopped scan selects when timestamps tie or publication is retried."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_workbench_scan_archive.py b/plugins/codex-security/tests/test_workbench_scan_archive.pyindex 41a78042c..bc6cd3fd7 100644--- a/plugins/codex-security/tests/test_workbench_scan_archive.py+++ b/plugins/codex-security/tests/test_workbench_scan_archive.py@@ -1,3 +1,5 @@+"""Exercise scan directory reuse and protect the active database while archiving or rolling back."""+from __future__ import annotationsimport argparsediff --git a/plugins/codex-security/tests/test_workbench_scan_history.py b/plugins/codex-security/tests/test_workbench_scan_history.pyindex d05b02615..3ecf51637 100644--- a/plugins/codex-security/tests/test_workbench_scan_history.py+++ b/plugins/codex-security/tests/test_workbench_scan_history.py@@ -1,3 +1,5 @@+"""Exercise history updates and reruns against the original checkout, scope, and revisions."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_workbench_scan_history_queries.py b/plugins/codex-security/tests/test_workbench_scan_history_queries.pyindex f0d0925c5..b6f421b75 100644--- a/plugins/codex-security/tests/test_workbench_scan_history_queries.py+++ b/plugins/codex-security/tests/test_workbench_scan_history_queries.py@@ -1,3 +1,5 @@+"""Check repository matching and finding relationships across legacy, linked, and unlinked scan records."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_workbench_scan_usage.py b/plugins/codex-security/tests/test_workbench_scan_usage.pyindex 87cc68523..22343b250 100644--- a/plugins/codex-security/tests/test_workbench_scan_usage.py+++ b/plugins/codex-security/tests/test_workbench_scan_usage.py@@ -1,3 +1,5 @@+"""Compute scan usage from session events and receipts, accounting for legacy duplicates and partial turns."""+from __future__ import annotationsimport json@@ -33,6 +35,8 @@ def scan_usage(workbench_api):@dataclass(frozen=True)class ScanFixture:+ """Hold the CLI environment, scan identity, and launch time for replaying rollout events in usage tests."""+state_dir: Pathtarget: Pathscan_id: str@@ -45,6 +49,7 @@ class ScanFixture:def write_parent_rollout(self, events: list[dict[str, Any]], *, originator: str | None = None) -> Path:+ """Write a parent rollout, register it in the fixture state graph, and return its path."""rollout = _rollout(self.target.parent, "scan-parent", events, originator=originator)_state_graph(self.environment, {"scan-parent": rollout}, [])return rolloutdiff --git a/plugins/codex-security/tests/test_workbench_scan_validation.py b/plugins/codex-security/tests/test_workbench_scan_validation.pyindex aadf0152e..877a9f0f8 100644--- a/plugins/codex-security/tests/test_workbench_scan_validation.py+++ b/plugins/codex-security/tests/test_workbench_scan_validation.py@@ -1,3 +1,5 @@+"""Check saved target snapshots against current contents and earlier revision-only scan records."""+from __future__ import annotationsimport osdiff --git a/plugins/codex-security/tests/test_workbench_setup_and_migrations.py b/plugins/codex-security/tests/test_workbench_setup_and_migrations.pyindex 162258b23..69566b80a 100644--- a/plugins/codex-security/tests/test_workbench_setup_and_migrations.py+++ b/plugins/codex-security/tests/test_workbench_setup_and_migrations.py@@ -1,3 +1,5 @@+"""Exercise workbench state setup and migration across historical schemas and conflicting histories."""+from __future__ import annotationsimport argparsediff --git a/plugins/codex-security/tests/test_workbench_standard_deep_results.py b/plugins/codex-security/tests/test_workbench_standard_deep_results.pyindex 2c6e759bf..d96cba887 100644--- a/plugins/codex-security/tests/test_workbench_standard_deep_results.py+++ b/plugins/codex-security/tests/test_workbench_standard_deep_results.py@@ -1,3 +1,5 @@+"""Reconcile saved parent and worker results across stops, reopened findings, and publication retries."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/test_workbench_stopped_worker_coverage.py b/plugins/codex-security/tests/test_workbench_stopped_worker_coverage.pyindex 35fe9205e..99fc2c057 100644--- a/plugins/codex-security/tests/test_workbench_stopped_worker_coverage.py+++ b/plugins/codex-security/tests/test_workbench_stopped_worker_coverage.py@@ -1,3 +1,5 @@+"""Rebuild stopped scan coverage from worker surfaces, deferred links, and matching artifact receipts."""+from __future__ import annotationsimport jsondiff --git a/plugins/codex-security/tests/test_workbench_target.py b/plugins/codex-security/tests/test_workbench_target.pyindex d2f83096d..e766e4af1 100644--- a/plugins/codex-security/tests/test_workbench_target.py+++ b/plugins/codex-security/tests/test_workbench_target.py@@ -1,3 +1,5 @@+"""Exercise Git discovery, snapshot identity, scoped inventory, and patch handling across filesystem aliases."""+from __future__ import annotationsimport difflibdiff --git a/plugins/codex-security/tests/test_workbench_timestamps.py b/plugins/codex-security/tests/test_workbench_timestamps.pyindex 5bd9097b6..4c58aa341 100644--- a/plugins/codex-security/tests/test_workbench_timestamps.py+++ b/plugins/codex-security/tests/test_workbench_timestamps.py@@ -1,3 +1,5 @@+"""Exercise UTC timestamps for workbench leases and deadlines with Python 3.10 semantics."""+from __future__ import annotationsimport importlib@@ -13,6 +15,8 @@ pytestmark = pytest.mark.cross_platformclass Python310DateTime(datetime):+ """Freeze the clock and reproduce Python 3.10's handling of Z-suffixed timestamps for lease tests."""+@classmethoddef fromisoformat(cls, value: str) -> datetime:if isinstance(value, str) and value.endswith(("Z", "z")):diff --git a/plugins/codex-security/tests/test_worker_receipt_admission.py b/plugins/codex-security/tests/test_worker_receipt_admission.pyindex b90bdaa24..f6917a7ca 100644--- a/plugins/codex-security/tests/test_worker_receipt_admission.py+++ b/plugins/codex-security/tests/test_worker_receipt_admission.py@@ -1,3 +1,5 @@+"""Check which worker receipts and surface links a stopped scan may retain from saved checkpoints."""+from __future__ import annotationsimport copydiff --git a/plugins/codex-security/tests/workbench_test_support.py b/plugins/codex-security/tests/workbench_test_support.pyindex 273ead7a0..c576e7f97 100644--- a/plugins/codex-security/tests/workbench_test_support.py+++ b/plugins/codex-security/tests/workbench_test_support.py@@ -1,3 +1,5 @@+"""Build temporary workbench targets, scan artifacts, and database state for integration tests."""+from __future__ import annotationsimport hashlib@@ -34,6 +36,7 @@ PLUGIN_MANIFEST = Path(__file__).resolve().parents[1] / ".codex-plugin" / "plugidef load_script(name: str, *, module_name: str | None = None) -> ModuleType:+ """Load a fresh module from the plugin scripts directory, optionally overriding its import name."""script = SCRIPT.parent / f"{name}.py"spec = importlib.util.spec_from_file_location(module_name or name, script)if spec is None or spec.loader is None:@@ -120,6 +123,7 @@ def source_plugin_version() -> str:def write_checkpoint(checkpoint_dir: Path, payload: Any, *, mtime_ns: int | None = None) -> Path:+ """Write the serialized payload as a SHA-256-named checkpoint and optionally set its timestamp for ordering tests."""encoded = json.dumps(payload).encode()checkpoint_dir.mkdir(parents=True, exist_ok=True)checkpoint_path = checkpoint_dir / f"{hashlib.sha256(encoded).hexdigest()}.json"@@ -130,6 +134,7 @@ def write_checkpoint(checkpoint_dir: Path, payload: Any, *, mtime_ns: int | Nonedef select_checkpoint(output: Path, checkpoint: Path, *, mtime_ns: int | None = None) -> Path:+ """Write a head pointing to the checkpoint filename and return the head path for further fixture changes."""head = output / "checkpoint-head.json"head.write_text(json.dumps({"checkpoint": checkpoint.name}))if mtime_ns is not None:@@ -143,6 +148,7 @@ def write_result_draft(path: Path, draft: dict, *, mtime_ns: int) -> None:def sort_checkpoint_entries(monkeypatch, *, key=None, reverse=False):+ """Control checkpoint enumeration order so a test can distinguish filesystem order from source precedence."""from workbench import saved_sourceschildren = saved_sources._children@@ -210,6 +216,7 @@ def saved_discovery_worker(output: Path, worker_id: str = "worker", attempt: intdef replay_saved_results(module, documents, scan_dir, scan_id, binding, workers=(), *, stopped=True):+ """Rebuild the interrupted result using the source digests frozen in the supplied manifest."""return module.merge_saved_results(scan_dir,scan_id,@@ -235,6 +242,7 @@ def update_digest_field(digest: Any, label: bytes, value: bytes) -> None:def directory_snapshot_digest(target: Path, *, excluded: tuple[Path, ...] = ()) -> str:+ """Compute the expected snapshot digest from fixture paths, entry modes, link targets, and file contents."""excluded_relative = []for path in excluded:try:@@ -278,6 +286,12 @@ def run_workbench(input_text: str | None = None,umask: int = -1,) -> dict[str, object]:+ """Run the workbench CLI with a fixture state directory and capture its output.++ By default, decode JSON from stdout and raise CalledProcessError on failure.+ With check=False, return the exit code and stderr for diagnostic assertions.+ Entries in environment override the inherited environment and state setting.+ """completed = subprocess.run([sys.executable, str(SCRIPT), *args],check=check,@@ -535,6 +549,8 @@ def write_remediation_patch(patch_path: Path, **text_options: Any) -> None:@dataclass(frozen=True)class RemediationRequest:+ """Run remediation commands for one occurrence using the same request ID across retries and state changes."""+state_dir: Pathoccurrence_id: strid: str = field(default_factory=lambda: str(uuid.uuid4()))@@ -997,6 +1013,8 @@ def windows_file_backend() -> mock.Mock:class ScanFixtureTestCase(TestCase):+ """Copy the example scan into a fresh temporary directory and rebuild its report for each test."""+def setUp(self) -> None:self.temp_dir = tempfile.TemporaryDirectory()self.scan_dir = Path(self.temp_dir.name) / "scan"@@ -1019,6 +1037,7 @@ class ScanFixtureTestCase(TestCase):path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")def rewrite_sealed_artifact(self, relative_path: str, payload: object) -> None:+ """Rewrite the JSON artifact and update its hash in the fixture manifest so the seal matches the new bytes."""self.write_json(relative_path, payload)manifest = self.read_json("scan-manifest.json")for artifact in manifest["scan"]["artifacts"]:diff --git a/sdk/typescript/tests-ts/fixtures/source_scopes.py b/sdk/typescript/tests-ts/fixtures/source_scopes.pyindex ddf66cebc..d70952144 100644--- a/sdk/typescript/tests-ts/fixtures/source_scopes.py+++ b/sdk/typescript/tests-ts/fixtures/source_scopes.py@@ -1,4 +1,8 @@-"""Synthetic Git fixtures for finding-source authorization tests."""+"""Run one source-scope scenario in a temporary Git repository and print its JSON result.++The SDK test passes the workbench scripts directory and scenario name on the command line.+Scenarios exercise saved scan permissions against Git objects and the host filesystem.+"""from __future__ import annotations@@ -28,6 +32,7 @@ from workbench_target import clean_worktree_content_digestdef git(repository: Path, *arguments: str, input_data: bytes | None = None) -> str:+ """Run Git with fixture-local author details and return stripped stdout on success."""environment = dict(os.environ, GIT_CONFIG_GLOBAL=os.devnull, GIT_CONFIG_NOSYSTEM="1")@@ -60,12 +65,14 @@ def write(repository: Path, name: str, content: str) -> None:def commit(repository: Path) -> str:+ """Stage all fixture changes, commit them, and return the resulting revision."""git(repository, "add", "--all")git(repository, "commit", "--quiet", "-m", "Synthetic fixture")return git(repository, "rev-parse", "HEAD")def scan(repository: Path, revision: str, paths: list[str]) -> dict:+ """Build a saved scan record for a clean revision using the requested relative paths."""identity = (revision, clean_worktree_content_digest(), 0, 0)return {"target_revision": revision,@@ -80,6 +87,7 @@ def scan(repository: Path, revision: str, paths: list[str]) -> dict:def excerpt(record: dict, repository: Path, path: str, selected: list[str]) -> str | None:+ """Return the numbered excerpt for the first line at path, or None when it is unavailable."""return excerpts.finding_source_excerpt(record, repository, [{"path": path, "startLine": 1}], selected)@@ -88,6 +96,16 @@ def excerpt(def register_recipe(repository: Path, recipe: dict, environment: dict[str, str] | None = None) -> tuple[dict, dict]:+ """Register a real CLI scan in fixture state and read it back from SQLite.++ Args:+ repository (Path): Synthetic target with a writable parent for state and scan files.+ recipe (dict): Launch recipe serialized for the register-cli-scan command.+ environment (dict | None): Extra environment variables for the workbench subprocess.++ Returns:+ tuple: The JSON reply used by CLI callers and the complete persisted scan row.+ """state = repository.parent / "state"scan_dir = Path(tempfile.mkdtemp(prefix="cli-scan-", dir=repository.parent))result = subprocess.run(@@ -125,6 +143,7 @@ def register_recipe(def directory_link(target: Path, link: Path) -> None:+ """Create a directory junction on Windows or a directory symlink on POSIX."""if os.name == "nt":subprocess.run([@@ -142,6 +161,7 @@ def directory_link(target: Path, link: Path) -> None:def replacements(repository: Path) -> None:+ """Check that saved excerpts use original Git objects and active replacements block new scopes."""write(repository, "selected.py", "selected source\n")write(repository, "private.py", "private source\n")write(repository, "selected/public.py", "selected directory\n")@@ -170,6 +190,7 @@ def replacements(repository: Path) -> None:def replacement_filters(repository: Path) -> None:+ """Check that registering a revision with replacement refs never invokes the worktree clean filter."""write(repository, "tracked.py", "synthetic source\n")write(repository, ".gitattributes", "tracked.py filter=scope_probe\n")revision = commit(repository)@@ -217,6 +238,7 @@ def replacement_filters(repository: Path) -> None:def replacement_snapshot(repository: Path) -> None:+ """Exercise saved and legacy scopes when replacements make a different tree appear clean."""from workbench_scan_start import scan_target_identitywrite(repository, "src/public.py", "historical source\n")@@ -259,6 +281,7 @@ def replacement_snapshot(repository: Path) -> None:def indexed_scopes(repository: Path) -> int:+ """Return the number of selected files after checking that path normalization scales linearly."""selected = [f"source-{index}.py" for index in range(256)]for name in selected:write(repository, name, "synthetic source\n")@@ -280,6 +303,7 @@ def indexed_scopes(repository: Path) -> int:def display_locations(repository: Path) -> int:+ """Return the displayed location count after checking the excerpt uses a visible location."""import workbench_db as dbfrom filesystem_identity import serialize_filesystem_identity@@ -341,6 +365,7 @@ def display_locations(repository: Path) -> int:def selected_redirects(repository: Path) -> None:+ """Verify requested paths stay in the recipe even when directory links prevent excerpt access."""write(repository, ".gitignore", "/selected/link\n")write(repository, "selected/public.py", "selected source\n")write(repository, "private/secret.py", "private source\n")@@ -374,6 +399,7 @@ def selected_redirects(repository: Path) -> None:def working_tree_excerpt(repository: Path) -> dict:+ """Report excerpt availability for dirty working-tree scans and explicit commit-range scans."""write(repository, "source.py", "old committed source\n")revision = commit(repository)write(repository, "source.py", "new working-tree source\n")@@ -415,6 +441,7 @@ def working_tree_excerpt(repository: Path) -> dict:def unsafe_locations(repository: Path) -> None:+ """Check that malformed line numbers and paths outside the repository are rejected before Git lookup."""write(repository, "source.py", "selected source\n")record = scan(repository, commit(repository), ["."])outside = repository.parent / "outside"@@ -442,6 +469,7 @@ def unsafe_locations(repository: Path) -> None:def boundaries(repository: Path) -> dict:+ """Return excerpt results for saved and legacy scopes, including removed paths and offline reads."""for name, content in {"src/public.py": "public source\n","src/support.py": "support source\n",@@ -583,6 +611,7 @@ def boundaries(repository: Path) -> dict:def aliases(repository: Path) -> dict:+ """Return the case and Unicode aliases supported by the fixture filesystem after checking excerpt lookup."""composed = unicodedata.normalize("NFC", "café")decomposed = unicodedata.normalize("NFD", composed)write(repository, "src/nested/public.py", "historical source\n")@@ -666,6 +695,7 @@ def aliases(repository: Path) -> dict:def descendant_aliases(repository: Path) -> None:+ """Exercise case collisions below a saved directory before and after deleting its worktree copy."""pairs = [("foo.py", "FOO.py"), ("nested/public.py", "NESTED/public.py")]for lower, _ in pairs:write(repository, f"selected/{lower}", "lower source\n")@@ -703,6 +733,7 @@ def descendant_aliases(repository: Path) -> None:def alias_evidence(_: Path) -> dict:+ """Return alias decisions for simulated regular files, hard links, symlinks, and reparse points."""selected, candidate = Path("/synthetic/SECRET.py"), Path("/synthetic/secret.py")result = {}for kind in ("ordinary", "hardlink", "symlink", "reparse"):@@ -732,6 +763,7 @@ def alias_evidence(_: Path) -> dict:def worktrees(repository: Path) -> None:+ """Check that scopes in a nested scan target retain that boundary in a linked worktree."""write(repository, "nested/src/public.py", "nested target source\n")write(repository, "private.py", "outside target source\n")revision = commit(repository)@@ -757,6 +789,7 @@ def worktrees(repository: Path) -> None:def writer(repository: Path, kind: str) -> str:+ """Exercise the named scan entry point, check persisted scope metadata, and return the entry point name."""write(repository, "src/public.py", "public source\n")write(repository, "selected.py", "selected file\n")revision = commit(repository)@@ -897,6 +930,7 @@ def writer(repository: Path, kind: str) -> str:def migration(_: Path) -> None:+ """Check how source-scope migrations handle preexisting scans and conflicting migration records."""from workbench_schema import MIGRATIONS, apply_migrationstimestamp = "2026-08-01T00:00:00Z"diff --git a/sdk/typescript/tests-ts/fixtures/verify_fix_stderr_harness.py b/sdk/typescript/tests-ts/fixtures/verify_fix_stderr_harness.pyindex ab8e6a1c8..b44b92323 100644--- a/sdk/typescript/tests-ts/fixtures/verify_fix_stderr_harness.py+++ b/sdk/typescript/tests-ts/fixtures/verify_fix_stderr_harness.py@@ -1,3 +1,9 @@+"""Run verify-fix fixture processes with broken or congested stderr and emit JSON results.++A separate pipe carries synchronization events so tests can observe worker completion,+cancellation, and cleanup even when the simulated terminal stops accepting output.+"""+from __future__ import annotationsfrom contextlib import contextmanager@@ -21,6 +27,8 @@ NODE, FIXTURE, CWD, STATE_ROOT, SCENARIO_TIMEOUT = sys.argv[1:]class HarnessTermination(Exception):+ """Unwind a scenario on SIGTERM so the harness can clean up its process group."""+pass@@ -33,6 +41,7 @@ signal.signal(signal.SIGTERM, terminate_harness)def wait(process: subprocess.Popen, timeout: float = 10):+ """Return True if the child is still running after the timeout, in seconds."""try:process.wait(timeout=timeout)return False@@ -41,6 +50,14 @@ def wait(process: subprocess.Popen, timeout: float = 10):class RunningProcess:+ """Own a fixture subprocess, its process group, and the read end of its synchronization pipe.++ The process attribute is the Node child. The state path is where its worker+ publishes a PID. Use event_until to synchronize with that worker and finish+ to collect the exit status and output. The running context manager releases+ the process group and descriptors on exit.+ """+def __init__(self, scenario: str, stderr, label: str):self.label = labelsync_read, sync_write = os.pipe()@@ -75,12 +92,14 @@ class RunningProcess:self.sync_buffer = b""def send(self, command: str = "continue"):+ """Write one newline-terminated command to the child and flush it immediately."""if self.process.stdin is None or self.process.stdin.closed:raise AssertionError("fixture stdin is closed")self.process.stdin.write(f"{command}\n".encode())self.process.stdin.flush()def _next_event(self, timeout: float = 10):+ """Decode one newline-delimited JSON event, retaining later events in the read buffer."""deadline = time.monotonic() + timeoutwhile b"\n" not in self.sync_buffer:remaining = deadline - time.monotonic()@@ -97,6 +116,18 @@ class RunningProcess:return json.loads(line)def event_until(self, name: str, worker: int | None = None):+ """Read synchronization events through the first matching milestone.++ Args:+ name (str): Event name emitted by the child.+ worker (int | None): Require a matching worker ID when supplied.++ Returns:+ list: All events read by this call, including the matching event.++ Raises:+ AssertionError: The synchronization pipe closes or times out before the milestone.+ """events = []while True:try:@@ -127,6 +158,7 @@ class RunningProcess:passdef stop(self):+ """Stop the fixture, escalating to SIGKILL and cleaning up any descendants still in its group."""if self.process.poll() is None:self.signal_group(signal.SIGTERM)if wait(self.process, 1):@@ -154,6 +186,7 @@ class RunningProcess:return stream.read().decode(errors="replace")def collect(self, events, blocked: bool = False):+ """Drain events into the supplied list and return exit status, captured output, and the blocked flag."""if self.process.poll() is None:self.process.wait()events.extend(self._remaining_events())@@ -171,6 +204,15 @@ class RunningProcess:}def finish(self, events, timeout: float = 10):+ """Close stdin, then wait for the child before collecting its final state.++ Args:+ events (list): Previously observed synchronization events, extended in place.+ timeout (float): Seconds to wait for normal exit before stopping the group.++ Returns:+ dict: Exit code, timeout flag (blocked), stdout, stderr, and all observed events.+ """self.close_stdin()blocked = wait(self.process, timeout)if blocked:@@ -192,6 +234,8 @@ class RunningProcess:@contextmanagerdef running(scenario: str, stderr=subprocess.PIPE, *, label: str | None = None):+ """Yield an isolated fixture process and clean it up on completion, interruption, or timeout."""+def timeout(_signal_number, _frame):raise TimeoutError(f"Verification fixture timed out: {scenario}")@@ -206,6 +250,7 @@ def running(scenario: str, stderr=subprocess.PIPE, *, label: str | None = None):def read_pty(master: int):+ """Read the master end through EOF or terminal hangup and decode the captured output."""chunks = []while True:try:@@ -235,12 +280,14 @@ def drain_pty(master: int, stopped: threading.Event):def open_pty():+ """Return master and slave descriptors for a terminal with 24 rows and 100 columns."""master, slave = pty.openpty()fcntl.ioctl(slave, termios.TIOCSWINSZ, struct.pack("HHHH", 24, 100, 0, 0))return master, slavedef wait_for_worker(state: Path):+ """Return the PID written by a worker, raising AssertionError if its state file fails to appear."""deadline = time.monotonic() + 10while not state.exists():if time.monotonic() >= deadline:@@ -274,6 +321,7 @@ def connected_output(scenario: str, name: str, stderr=subprocess.PIPE):def fill_output(fd: int):+ """Fill the descriptor until a single byte would block, then restore blocking mode."""os.set_blocking(fd, False)try:chunk = b"x" * 4096@@ -324,6 +372,7 @@ def disconnected_pty(scenario: str):def release_with_full_terminal(fixture: RunningProcess, slave: int):+ """Fill terminal output before releasing the second worker and return its startup events."""events = fixture.event_until("worker-started", 2)# Use a separate file description so the fixture's stderr stays blocking.with open(os.ttyname(slave), "wb", buffering=0) as filler:@@ -333,6 +382,7 @@ def release_with_full_terminal(fixture: RunningProcess, slave: int):def paused_pty(scenario: str, sent_signal: signal.Signals | None):+ """Return completion and worker-liveness observations while leaving terminal output undrained."""master, slave = open_pty()try:with running(scenario, slave) as fixture:@@ -395,6 +445,7 @@ def full_terminal(scenario: str):def mixed_signals(first: signal.Signals, second: signal.Signals):+ """Send the second signal after the worker observes the first and collect the final worker state."""scenario = f"pty-backpressure-mixed-{first.name.lower()}-{second.name.lower()}"master, slave = open_pty()try:@@ -431,6 +482,7 @@ def mixed_signals(first: signal.Signals, second: signal.Signals):def cleanup_sigwinch():+ """Deliver a resize signal after terminal cleanup and capture the fixture's response."""master, slave = open_pty()stop_reader = threading.Event()reader = threading.Thread(target=drain_pty, args=(master, stop_reader))