@openai/codex-security 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (243) hide show
  1. package/README.md +68 -37
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  5. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +1 -1
  6. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  7. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  8. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  9. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  10. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  11. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  12. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  14. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  15. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  16. package/_bundled_plugin/references/access-advisory.md +11 -0
  17. package/_bundled_plugin/references/core-scan.md +30 -77
  18. package/_bundled_plugin/references/final-report.md +45 -189
  19. package/_bundled_plugin/references/scan-contract.md +2 -0
  20. package/_bundled_plugin/references/scan-prologue.md +1 -1
  21. package/_bundled_plugin/references/scan-runtime.md +1 -5
  22. package/_bundled_plugin/references/threat-model.md +33 -41
  23. package/_bundled_plugin/schemas/coverage.schema.json +12 -1
  24. package/_bundled_plugin/schemas/scan-manifest.schema.json +1 -0
  25. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +38 -1
  26. package/_bundled_plugin/scripts/deep_scan_config.py +39 -39
  27. package/_bundled_plugin/scripts/deep_scan_workbench.py +145 -85
  28. package/_bundled_plugin/scripts/finalize_scan_contract.py +189 -57
  29. package/_bundled_plugin/scripts/report_projection.py +44 -15
  30. package/_bundled_plugin/scripts/threat_model_projection.py +4 -2
  31. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -14
  32. package/_bundled_plugin/scripts/workbench/retained_coverage.py +3218 -0
  33. package/_bundled_plugin/scripts/workbench/retained_records.py +627 -0
  34. package/_bundled_plugin/scripts/workbench/saved_coverage.py +644 -1
  35. package/_bundled_plugin/scripts/workbench/saved_outputs.py +72 -0
  36. package/_bundled_plugin/scripts/workbench/saved_sources.py +712 -0
  37. package/_bundled_plugin/scripts/workbench_cli.py +3 -0
  38. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +479 -0
  39. package/_bundled_plugin/scripts/workbench_db.py +51 -22
  40. package/_bundled_plugin/scripts/workbench_feedback.py +0 -1
  41. package/_bundled_plugin/scripts/workbench_finding_workflows.py +51 -9
  42. package/_bundled_plugin/scripts/workbench_native_indexes.py +56 -44
  43. package/_bundled_plugin/scripts/workbench_saved_results.py +641 -2387
  44. package/_bundled_plugin/scripts/workbench_scan_history.py +72 -7
  45. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  46. package/_bundled_plugin/scripts/workbench_source_scopes.py +4 -1
  47. package/_bundled_plugin/scripts/workbench_target.py +142 -17
  48. package/_bundled_plugin/scripts/workbench_validation.py +9 -2
  49. package/_bundled_plugin/shared/workbench-history-repairs.json +21 -0
  50. package/_bundled_plugin/shared/workbench-migrations.json +28 -0
  51. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +3 -14
  52. package/_bundled_plugin/skills/assess-patch-risk/references/windows-validation.md +14 -0
  53. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +38 -103
  54. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +11 -73
  55. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +57 -116
  56. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +28 -51
  57. package/_bundled_plugin/skills/define-security-policy/SKILL.md +9 -9
  58. package/_bundled_plugin/skills/finding-discovery/SKILL.md +26 -140
  59. package/_bundled_plugin/skills/fix-finding/SKILL.md +9 -28
  60. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +28 -218
  61. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +29 -424
  62. package/_bundled_plugin/skills/publish-findings/SKILL.md +28 -24
  63. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +64 -0
  64. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +12 -12
  65. package/_bundled_plugin/skills/security-scan/SKILL.md +28 -16
  66. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +11 -17
  67. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +52 -69
  68. package/_bundled_plugin/skills/threat-model/SKILL.md +16 -9
  69. package/_bundled_plugin/skills/triage-finding/SKILL.md +5 -15
  70. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -6
  71. package/_bundled_plugin/skills/validation/SKILL.md +42 -104
  72. package/_bundled_plugin/skills/validation/references/validation-guidance.md +21 -106
  73. package/_bundled_plugin/skills/verify-fix/SKILL.md +4 -2
  74. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +21 -159
  75. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +18 -60
  76. package/dist/api.d.ts +5 -3
  77. package/dist/api.d.ts.map +1 -1
  78. package/dist/api.js +341 -37
  79. package/dist/api.js.map +1 -1
  80. package/dist/auth.d.ts.map +1 -1
  81. package/dist/auth.js +4 -1
  82. package/dist/auth.js.map +1 -1
  83. package/dist/cli.d.ts +2 -2
  84. package/dist/cli.d.ts.map +1 -1
  85. package/dist/cli.js +674 -419
  86. package/dist/cli.js.map +1 -1
  87. package/dist/component-scan.d.ts +8 -2
  88. package/dist/component-scan.d.ts.map +1 -1
  89. package/dist/component-scan.js +2 -0
  90. package/dist/component-scan.js.map +1 -1
  91. package/dist/contract.d.ts +2 -0
  92. package/dist/contract.d.ts.map +1 -1
  93. package/dist/contract.js +67 -33
  94. package/dist/contract.js.map +1 -1
  95. package/dist/cost.d.ts +18 -0
  96. package/dist/cost.d.ts.map +1 -1
  97. package/dist/cost.js +107 -12
  98. package/dist/cost.js.map +1 -1
  99. package/dist/coverage-presentation.d.ts +6 -0
  100. package/dist/coverage-presentation.d.ts.map +1 -0
  101. package/dist/coverage-presentation.js +34 -0
  102. package/dist/coverage-presentation.js.map +1 -0
  103. package/dist/custom-validation-prompt.js +3 -3
  104. package/dist/custom-validation-prompt.js.map +1 -1
  105. package/dist/custom-validation.d.ts.map +1 -1
  106. package/dist/custom-validation.js +30 -4
  107. package/dist/custom-validation.js.map +1 -1
  108. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  109. package/dist/deduplication/checkpointed-review.js +3 -1
  110. package/dist/deduplication/checkpointed-review.js.map +1 -1
  111. package/dist/deduplication/scan.d.ts.map +1 -1
  112. package/dist/deduplication/scan.js +7 -5
  113. package/dist/deduplication/scan.js.map +1 -1
  114. package/dist/endor-findings.d.ts +4 -3
  115. package/dist/endor-findings.d.ts.map +1 -1
  116. package/dist/endor-findings.js +16 -11
  117. package/dist/endor-findings.js.map +1 -1
  118. package/dist/external-findings-import.d.ts.map +1 -1
  119. package/dist/external-findings-import.js +13 -5
  120. package/dist/external-findings-import.js.map +1 -1
  121. package/dist/external-findings-local.d.ts.map +1 -1
  122. package/dist/external-findings-local.js +8 -1
  123. package/dist/external-findings-local.js.map +1 -1
  124. package/dist/external-findings-publish.d.ts +1 -1
  125. package/dist/external-findings-publish.d.ts.map +1 -1
  126. package/dist/external-findings-publish.js +11 -3
  127. package/dist/external-findings-publish.js.map +1 -1
  128. package/dist/external-findings-read.d.ts +11 -1
  129. package/dist/external-findings-read.d.ts.map +1 -1
  130. package/dist/external-findings-read.js +15 -6
  131. package/dist/external-findings-read.js.map +1 -1
  132. package/dist/external-import-contract.d.ts +3 -1
  133. package/dist/external-import-contract.d.ts.map +1 -1
  134. package/dist/external-import-contract.js +33 -25
  135. package/dist/external-import-contract.js.map +1 -1
  136. package/dist/external-imports-feature.d.ts +6 -0
  137. package/dist/external-imports-feature.d.ts.map +1 -0
  138. package/dist/external-imports-feature.js +51 -0
  139. package/dist/external-imports-feature.js.map +1 -0
  140. package/dist/finding-workflow.d.ts +22 -5
  141. package/dist/finding-workflow.d.ts.map +1 -1
  142. package/dist/finding-workflow.js +21 -9
  143. package/dist/finding-workflow.js.map +1 -1
  144. package/dist/github-advisories.d.ts.map +1 -1
  145. package/dist/github-advisories.js +3 -1
  146. package/dist/github-advisories.js.map +1 -1
  147. package/dist/github-findings.d.ts +4 -3
  148. package/dist/github-findings.d.ts.map +1 -1
  149. package/dist/github-findings.js +16 -14
  150. package/dist/github-findings.js.map +1 -1
  151. package/dist/hosted-remediation.d.ts.map +1 -1
  152. package/dist/hosted-remediation.js +19 -2
  153. package/dist/hosted-remediation.js.map +1 -1
  154. package/dist/hosted-scan.d.ts +1 -1
  155. package/dist/hosted-scan.d.ts.map +1 -1
  156. package/dist/hosted-scan.js +0 -5
  157. package/dist/hosted-scan.js.map +1 -1
  158. package/dist/import-scan.js +1 -1
  159. package/dist/import-scan.js.map +1 -1
  160. package/dist/index.d.ts +3 -3
  161. package/dist/index.d.ts.map +1 -1
  162. package/dist/index.js +1 -1
  163. package/dist/index.js.map +1 -1
  164. package/dist/knowledge-base.d.ts +1 -0
  165. package/dist/knowledge-base.d.ts.map +1 -1
  166. package/dist/knowledge-base.js +17 -8
  167. package/dist/knowledge-base.js.map +1 -1
  168. package/dist/models.d.ts +1 -0
  169. package/dist/models.d.ts.map +1 -1
  170. package/dist/models.js.map +1 -1
  171. package/dist/owner-evidence.d.ts +2 -0
  172. package/dist/owner-evidence.d.ts.map +1 -1
  173. package/dist/owner-evidence.js +2 -1
  174. package/dist/owner-evidence.js.map +1 -1
  175. package/dist/publish.d.ts +2 -0
  176. package/dist/publish.d.ts.map +1 -1
  177. package/dist/publish.js +1 -1
  178. package/dist/publish.js.map +1 -1
  179. package/dist/remediation.d.ts +1 -25
  180. package/dist/remediation.d.ts.map +1 -1
  181. package/dist/remediation.js +3 -24
  182. package/dist/remediation.js.map +1 -1
  183. package/dist/runtime.d.ts.map +1 -1
  184. package/dist/runtime.js +7 -7
  185. package/dist/runtime.js.map +1 -1
  186. package/dist/scan-dashboard.d.ts +5 -3
  187. package/dist/scan-dashboard.d.ts.map +1 -1
  188. package/dist/scan-dashboard.js +79 -26
  189. package/dist/scan-dashboard.js.map +1 -1
  190. package/dist/scan-history-renderer.d.ts.map +1 -1
  191. package/dist/scan-history-renderer.js +8 -2
  192. package/dist/scan-history-renderer.js.map +1 -1
  193. package/dist/scan-owner-suggestions.d.ts +1 -1
  194. package/dist/scan-owner-suggestions.d.ts.map +1 -1
  195. package/dist/scan-owner-suggestions.js +4 -4
  196. package/dist/scan-owner-suggestions.js.map +1 -1
  197. package/dist/scan-usage-display.d.ts +8 -0
  198. package/dist/scan-usage-display.d.ts.map +1 -0
  199. package/dist/scan-usage-display.js +46 -0
  200. package/dist/scan-usage-display.js.map +1 -0
  201. package/dist/scanner-import.d.ts +1 -1
  202. package/dist/scanner-import.d.ts.map +1 -1
  203. package/dist/scanner-import.js +7 -3
  204. package/dist/scanner-import.js.map +1 -1
  205. package/dist/security-policy.d.ts.map +1 -1
  206. package/dist/security-policy.js +1 -20
  207. package/dist/security-policy.js.map +1 -1
  208. package/dist/semgrep-findings.d.ts +4 -3
  209. package/dist/semgrep-findings.d.ts.map +1 -1
  210. package/dist/semgrep-findings.js +9 -9
  211. package/dist/semgrep-findings.js.map +1 -1
  212. package/dist/skill-authentication.d.ts +18 -0
  213. package/dist/skill-authentication.d.ts.map +1 -0
  214. package/dist/skill-authentication.js +82 -0
  215. package/dist/skill-authentication.js.map +1 -0
  216. package/dist/snyk-findings.d.ts +5 -4
  217. package/dist/snyk-findings.d.ts.map +1 -1
  218. package/dist/snyk-findings.js +18 -17
  219. package/dist/snyk-findings.js.map +1 -1
  220. package/dist/suggest-owners.d.ts +4 -1
  221. package/dist/suggest-owners.d.ts.map +1 -1
  222. package/dist/suggest-owners.js +53 -21
  223. package/dist/suggest-owners.js.map +1 -1
  224. package/dist/targets.d.ts.map +1 -1
  225. package/dist/targets.js +4 -1
  226. package/dist/targets.js.map +1 -1
  227. package/dist/wiz-csv.d.ts +2 -1
  228. package/dist/wiz-csv.d.ts.map +1 -1
  229. package/dist/wiz-csv.js +3 -3
  230. package/dist/wiz-csv.js.map +1 -1
  231. package/dist/wiz-findings.d.ts +2 -1
  232. package/dist/wiz-findings.d.ts.map +1 -1
  233. package/dist/wiz-findings.js +27 -23
  234. package/dist/wiz-findings.js.map +1 -1
  235. package/docs/classify-severity-records.md +3 -4
  236. package/docs/cli.md +155 -38
  237. package/docs/findings-service.md +119 -118
  238. package/docs/hosted-remediation.md +19 -17
  239. package/docs/hosted-scans.md +37 -11
  240. package/package.json +8 -8
  241. package/_bundled_plugin/scripts/generate_in_scope_files.py +0 -277
  242. package/_bundled_plugin/scripts/generate_rank_input.py +0 -350
  243. package/_bundled_plugin/scripts/rank_preview.py +0 -129
@@ -2,7 +2,7 @@
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
3
  "$id": "codex-security://schemas/tools/deep-reducer.schema.json",
4
4
  "title": "Codex Security Deep Scan semantic reducer operations",
5
- "$ref": "#/$defs/reductionInput",
5
+ "$ref": "#/$defs/reductionSubmission",
6
6
  "$defs": {
7
7
  "reducerInputs": {
8
8
  "type": "object",
@@ -54,6 +54,43 @@
54
54
  },
55
55
  "required": ["scanId", "findings"],
56
56
  "additionalProperties": false
57
+ },
58
+ "reductionSubmission": {
59
+ "type": "object",
60
+ "properties": {
61
+ "complete": {
62
+ "type": "boolean",
63
+ "description": "Omit or set true when submitting the finished aggregate."
64
+ },
65
+ "scanId": {
66
+ "$ref": "codex-security://schemas/definitions/artifact-common.schema.json#/$defs/scanId"
67
+ },
68
+ "handoffClaimToken": {
69
+ "$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/handoffClaimToken"
70
+ },
71
+ "scope": {
72
+ "$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/scope"
73
+ },
74
+ "threatModel": {
75
+ "$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/threatModel"
76
+ },
77
+ "findings": {
78
+ "type": "array",
79
+ "items": {
80
+ "$ref": "codex-security://schemas/tools/scan-draft.schema.json#/$defs/finding"
81
+ }
82
+ },
83
+ "retainedFindingRefs": {
84
+ "type": "array",
85
+ "items": {
86
+ "type": "string",
87
+ "pattern": "^previous:(0|[1-9][0-9]*)$"
88
+ },
89
+ "description": "Copy unchanged previous aggregate findings by previous:<zero-based index>. The host preserves their complete bodies, identities, and source references; do not also submit them in findings."
90
+ }
91
+ },
92
+ "required": ["scanId", "findings"],
93
+ "additionalProperties": false
57
94
  }
58
95
  }
59
96
  }
@@ -22,14 +22,15 @@ DEFAULT_STOP_AFTER_CONSECUTIVE_ERRORS = DEFAULTS["stopAfterConsecutiveErrors"]
22
22
  DEFAULT_MAX_DISCOVERY_RUNS = DEFAULTS["maxDiscoveryRuns"]
23
23
  DEFAULT_MAX_TIME_HOURS = DEFAULTS["maxTimeHours"]
24
24
  MAX_TIME_HOURS = 96
25
- CONFIG_KEYS = {
26
- "workers",
27
- "subagents",
28
- "stop_after_no_new",
29
- "stop_after_consecutive_errors",
30
- "max_discovery_runs",
31
- "max_time_hours",
25
+ CONFIG_FIELDS = {
26
+ "workers": "workers",
27
+ "subagents": "subagents",
28
+ "stopAfterNoNew": "stop_after_no_new",
29
+ "stopAfterConsecutiveErrors": "stop_after_consecutive_errors",
30
+ "maxDiscoveryRuns": "max_discovery_runs",
31
+ "maxTimeHours": "max_time_hours",
32
32
  }
33
+ CONFIG_KEYS = set(CONFIG_FIELDS.values())
33
34
 
34
35
 
35
36
  def codex_home() -> Path:
@@ -46,11 +47,23 @@ def config_path() -> Path:
46
47
 
47
48
 
48
49
  def resolve_deep_scan_config(available_parallelism: int) -> dict[str, int | float]:
50
+ return resolve_deep_scan_setup(available_parallelism)["settings"]
51
+
52
+
53
+ def resolve_deep_scan_setup(
54
+ available_parallelism: int, project_json: str | None = None
55
+ ) -> dict[str, Any]:
56
+ project = json.loads(project_json) if project_json is not None else None
57
+ overrides = project["settings"] if project is not None else {}
58
+ unknown = sorted(set(overrides) - set(CONFIG_FIELDS))
59
+ if unknown:
60
+ raise SystemExit(f"Unknown Deep Scan project settings: {', '.join(unknown)}.")
49
61
  if isinstance(available_parallelism, bool) or available_parallelism < 1:
50
62
  raise SystemExit("Available parallelism must be a positive integer.")
51
63
  path = config_path()
52
64
  configured: dict[str, Any] = {}
53
- if path.exists():
65
+ exists = path.exists()
66
+ if exists and not all(name in overrides for name in CONFIG_FIELDS):
54
67
  try:
55
68
  with path.open("rb") as source:
56
69
  document: object = tomllib.load(source)
@@ -70,38 +83,25 @@ def resolve_deep_scan_config(available_parallelism: int) -> dict[str, int | floa
70
83
  )
71
84
  configured = deep_scan
72
85
 
73
- workers: object = configured.get("workers", DEFAULT_WORKERS)
74
- if workers == "auto":
75
- resolved_workers = DEFAULT_WORKERS
76
- else:
77
- resolved_workers = require_integer(workers, "deep_scan.workers", minimum=1)
78
- stop_after_no_new = require_integer(
79
- configured.get("stop_after_no_new", DEFAULT_STOP_AFTER_NO_NEW),
80
- "deep_scan.stop_after_no_new",
81
- minimum=1,
82
- )
86
+ settings: dict[str, int | float] = {}
87
+ sources: dict[str, str] = {}
88
+ for name, key in CONFIG_FIELDS.items():
89
+ value = overrides.get(name, configured.get(key, DEFAULTS[name]))
90
+ sources[name] = (
91
+ "project" if name in overrides else "legacy" if key in configured else "default"
92
+ )
93
+ if name == "workers" and value == "auto":
94
+ value = DEFAULT_WORKERS
95
+ settings[name] = (
96
+ require_positive_number(value, "deep_scan.max_time_hours")
97
+ if name == "maxTimeHours"
98
+ else require_integer(value, f"deep_scan.{key}", minimum=0 if name == "subagents" else 1)
99
+ )
83
100
  return {
84
- "workers": resolved_workers,
85
- "subagents": require_integer(
86
- configured.get("subagents", DEFAULT_SUBAGENTS),
87
- "deep_scan.subagents",
88
- minimum=0,
89
- ),
90
- "stopAfterNoNew": stop_after_no_new,
91
- "stopAfterConsecutiveErrors": require_integer(
92
- configured.get("stop_after_consecutive_errors", DEFAULT_STOP_AFTER_CONSECUTIVE_ERRORS),
93
- "deep_scan.stop_after_consecutive_errors",
94
- minimum=1,
95
- ),
96
- "maxDiscoveryRuns": require_integer(
97
- configured.get("max_discovery_runs", DEFAULT_MAX_DISCOVERY_RUNS),
98
- "deep_scan.max_discovery_runs",
99
- minimum=1,
100
- ),
101
- "maxTimeHours": require_positive_number(
102
- configured.get("max_time_hours", DEFAULT_MAX_TIME_HOURS),
103
- "deep_scan.max_time_hours",
104
- ),
101
+ "settings": settings,
102
+ "sources": sources,
103
+ **({"legacyConfigPath": str(path)} if exists else {}),
104
+ **({"projectConfigPath": project["path"]} if project is not None else {}),
105
105
  }
106
106
 
107
107
 
@@ -3,21 +3,19 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import argparse
6
- import hashlib
7
6
  import json
8
7
  import os
9
8
  import shutil
10
9
  import sqlite3
11
10
  import sys
12
11
  import uuid
13
- from contextlib import nullcontext
14
12
  from datetime import datetime, timedelta
15
13
  from pathlib import Path
16
14
  from typing import Any, Callable
17
15
 
18
16
  sys.path.insert(0, str(Path(__file__).resolve().parent))
19
17
  import workbench_saved_results as saved_results
20
- from deep_scan_config import resolve_deep_scan_config
18
+ from deep_scan_config import resolve_deep_scan_setup
21
19
  from workbench.handoff import require_current_continuation
22
20
  from workbench.storage import create_private_directory
23
21
  from workbench_source_scopes import capture_source_scopes
@@ -35,7 +33,6 @@ DEEP_SCAN_TERMINAL_REASONS = ("saturated", "capped")
35
33
  DEEP_SCAN_WORKFLOW_VERSION = "deep-security-scan/v1"
36
34
  DEEP_SCAN_COORDINATOR_LEASE_SECONDS = 30
37
35
  DEEP_SCAN_LEGACY_COORDINATOR_GRACE_SECONDS = 120
38
- DEEP_SCAN_MAX_ERROR_LENGTH = 2400
39
36
  DEEP_SCAN_PUBLICATION_ERROR_SEPARATOR = "\nOriginal Deep Scan failure:\n"
40
37
 
41
38
 
@@ -54,12 +51,18 @@ def register_subcommands(subparsers: Any, positive_int: Callable[[str], int]) ->
54
51
  begin_deep_scan.add_argument("--model")
55
52
  begin_deep_scan.add_argument("--reasoning-effort")
56
53
  begin_deep_scan.add_argument("--available-parallelism", type=positive_int)
54
+ begin_deep_scan.add_argument("--deep-scan-project-json")
55
+ begin_deep_scan.add_argument("--project-config-path")
56
+ begin_deep_scan.add_argument("--join-only", action="store_true")
57
57
  begin_deep_scan.add_argument("--workflow-version", default=DEEP_SCAN_WORKFLOW_VERSION)
58
58
 
59
59
  get_deep_scan = subparsers.add_parser("get-deep-scan")
60
60
  get_deep_scan.add_argument("--scan-id", required=True)
61
61
  get_deep_scan.add_argument("--thread-id", required=True)
62
62
 
63
+ acknowledge_result = subparsers.add_parser("acknowledge-deep-scan-result")
64
+ acknowledge_result.add_argument("--scan-id", required=True)
65
+
63
66
  claim_coordinator = subparsers.add_parser("claim-deep-scan-coordinator")
64
67
  claim_coordinator.add_argument("--scan-id", required=True)
65
68
  claim_coordinator.add_argument("--thread-id", required=True)
@@ -145,16 +148,6 @@ def dependencies() -> Any:
145
148
  return _dependencies
146
149
 
147
150
 
148
- def _bounded_error_text(message: str, maximum: int) -> str:
149
- if len(message) <= maximum:
150
- return message
151
- digest = hashlib.sha256(message.encode()).hexdigest()
152
- suffix = f"\n...[truncated; sha256:{digest}]"
153
- if len(suffix) >= maximum:
154
- return message[:maximum]
155
- return f"{message[: maximum - len(suffix)]}{suffix}"
156
-
157
-
158
151
  def deep_scan_error(run: sqlite3.Row) -> str | None:
159
152
  original = run["error_message"]
160
153
  publication = run["publication_error_message"]
@@ -162,15 +155,7 @@ def deep_scan_error(run: sqlite3.Row) -> str | None:
162
155
  return original if isinstance(original, str) else None
163
156
  if not isinstance(original, str):
164
157
  return publication
165
- available = DEEP_SCAN_MAX_ERROR_LENGTH - len(DEEP_SCAN_PUBLICATION_ERROR_SEPARATOR)
166
- publication_budget = min(len(publication), available // 2)
167
- original_budget = min(len(original), available - publication_budget)
168
- publication_budget = min(len(publication), available - original_budget)
169
- return (
170
- _bounded_error_text(publication, publication_budget)
171
- + DEEP_SCAN_PUBLICATION_ERROR_SEPARATOR
172
- + _bounded_error_text(original, original_budget)
173
- )
158
+ return publication + DEEP_SCAN_PUBLICATION_ERROR_SEPARATOR + original
174
159
 
175
160
 
176
161
  def _parse_timestamp(value: str) -> datetime:
@@ -449,6 +434,7 @@ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, A
449
434
  )
450
435
  return {
451
436
  "scanId": run["scan_id"],
437
+ "sdkOwnsCompletion": scan["recipe_json"] is not None,
452
438
  "targetPath": scan["target_path"],
453
439
  "scope": scan["scope"],
454
440
  "includePaths": dependencies().requested_scan_paths(scan),
@@ -560,9 +546,13 @@ def deep_scan_result(
560
546
  return result
561
547
 
562
548
 
563
- def effective_deep_scan_config(args: argparse.Namespace) -> dict[str, int | float]:
549
+ def effective_deep_scan_config(
550
+ args: argparse.Namespace, workspace: sqlite3.Row | None = None
551
+ ) -> dict[str, Any]:
552
+ if workspace is not None and workspace["deep_scan_config_json"] is not None:
553
+ return json.loads(workspace["deep_scan_config_json"])
564
554
  available_parallelism = args.available_parallelism or os.cpu_count() or 1
565
- return resolve_deep_scan_config(available_parallelism)
555
+ return resolve_deep_scan_setup(available_parallelism, args.deep_scan_project_json)
566
556
 
567
557
 
568
558
  def ensure_deep_scan_run(
@@ -571,6 +561,8 @@ def ensure_deep_scan_run(
571
561
  config: dict[str, int | float],
572
562
  workflow_version: str,
573
563
  timestamp: str,
564
+ *,
565
+ pending_target_project_path: str | None = None,
574
566
  ) -> sqlite3.Row:
575
567
  existing = connection.execute(
576
568
  "SELECT * FROM deep_scan_runs WHERE scan_id = ?", (scan["id"],)
@@ -587,8 +579,8 @@ def ensure_deep_scan_run(
587
579
  scan_id, schema_version, workflow_version, status, phase,
588
580
  workers, subagents, stop_after_no_new, stop_after_consecutive_errors,
589
581
  max_discovery_runs, max_time_hours, discovery_user_context_json,
590
- created_at, updated_at
591
- ) VALUES (?, 1, ?, 'running', 'setup', ?, ?, ?, ?, ?, ?, ?, ?, ?)
582
+ created_at, updated_at, pending_target_project_path
583
+ ) VALUES (?, 1, ?, 'running', 'setup', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
592
584
  """,
593
585
  (
594
586
  scan["id"],
@@ -602,6 +594,7 @@ def ensure_deep_scan_run(
602
594
  json.dumps(scan["user_context"]),
603
595
  timestamp,
604
596
  timestamp,
597
+ pending_target_project_path,
605
598
  ),
606
599
  )
607
600
  return require_deep_scan_run(connection, scan["id"])
@@ -634,18 +627,13 @@ def terminal_deep_scan_for_target_snapshot(
634
627
  target_path: str,
635
628
  scope: str,
636
629
  user_context: str | None,
630
+ project_path: str,
637
631
  revision: str,
638
632
  snapshot_digest: str,
639
633
  target_device: int | str,
640
634
  target_inode: int | str,
641
635
  ) -> sqlite3.Row | None:
642
- """Find discovery completed before a headless continuation changed thread IDs.
643
-
644
- A continuation may safely consume a finished coordinator manifest while the
645
- parent scan is still open. It must not adopt live orchestration owned by a
646
- different thread, or reuse results for a different repository snapshot or
647
- original discovery context.
648
- """
636
+ """Recover a matching terminal headless result, including after the parent was sealed."""
649
637
  return connection.execute(
650
638
  """
651
639
  SELECT scans.*
@@ -656,15 +644,22 @@ def terminal_deep_scan_for_target_snapshot(
656
644
  AND scans.scope = ?
657
645
  AND deep_scan_runs.discovery_user_context_json = ?
658
646
  AND scans.mode = 'deep'
659
- AND scans.status = 'running'
647
+ AND (
648
+ (scans.status = 'running'
649
+ AND COALESCE(scans.deep_scan_owner_thread_id, workspaces.thread_id) <> ?)
650
+ OR (scans.status = 'complete'
651
+ AND deep_scan_runs.pending_target_project_path IS NOT NULL)
652
+ )
653
+ AND (deep_scan_runs.pending_target_project_path IS NULL
654
+ OR deep_scan_runs.pending_target_project_path = ?)
660
655
  AND scans.canceled_at IS NULL
656
+ AND scans.recipe_json IS NULL
661
657
  AND scans.target_revision = ?
662
658
  AND scans.target_snapshot_digest = ?
663
659
  AND scans.target_device = ?
664
660
  AND scans.target_inode = ?
665
661
  AND scans.handoff_status = 'delivered'
666
662
  AND scans.handoff_claim_token IS NULL
667
- AND COALESCE(scans.deep_scan_owner_thread_id, workspaces.thread_id) <> ?
668
663
  AND workspaces.active_scan_id = scans.id
669
664
  AND deep_scan_runs.status = 'succeeded'
670
665
  AND deep_scan_runs.phase = 'terminal'
@@ -672,13 +667,16 @@ def terminal_deep_scan_for_target_snapshot(
672
667
  AND deep_scan_runs.terminal_reason IN ('saturated', 'capped')
673
668
  AND deep_scan_runs.manifest_path IS NOT NULL
674
669
  AND deep_scan_runs.completed_at IS NOT NULL
675
- ORDER BY deep_scan_runs.completed_at DESC, scans.updated_at DESC, scans.id
670
+ ORDER BY (COALESCE(scans.deep_scan_owner_thread_id, workspaces.thread_id) = ?) DESC,
671
+ deep_scan_runs.completed_at DESC, scans.updated_at DESC, scans.id
676
672
  LIMIT 1
677
673
  """,
678
674
  (
679
675
  target_path,
680
676
  scope,
681
677
  json.dumps(user_context),
678
+ thread_id,
679
+ project_path,
682
680
  revision,
683
681
  snapshot_digest,
684
682
  target_device,
@@ -733,6 +731,11 @@ def begin_deep_scan_for_scan(
733
731
  )
734
732
  if scan["mode"] != "deep":
735
733
  raise SystemExit("Deep Scan orchestration requires a scan in deep mode.")
734
+ existing = connection.execute(
735
+ "SELECT scan_id FROM deep_scan_runs WHERE scan_id = ?", (scan_id,)
736
+ ).fetchone()
737
+ if args.join_only and existing is None and workspace["deep_scan_config_json"] is None:
738
+ return {"newScanTarget": scan["target_path"]}
736
739
  model = optional_text(args.model, maximum=200)
737
740
  reasoning_effort = optional_text(args.reasoning_effort, maximum=32)
738
741
  if model is not None or reasoning_effort is not None:
@@ -745,12 +748,11 @@ def begin_deep_scan_for_scan(
745
748
  (model, reasoning_effort, scan_id),
746
749
  )
747
750
  connection.commit()
748
- existing = connection.execute(
749
- "SELECT scan_id FROM deep_scan_runs WHERE scan_id = ?", (scan_id,)
750
- ).fetchone()
751
751
  if existing is not None:
752
752
  return deep_scan_result(connection, scan_id, start_disposition="joined")
753
- config = effective_deep_scan_config(args)
753
+ workspace = dependencies().require_workspace(connection, scan["workspace_id"])
754
+ configuration = effective_deep_scan_config(args, workspace)
755
+ config = configuration["settings"]
754
756
  workflow_version = optional_text(args.workflow_version, maximum=256)
755
757
  if workflow_version is None:
756
758
  raise SystemExit("workflow-version is required.")
@@ -762,6 +764,10 @@ def begin_deep_scan_for_scan(
762
764
  args.claim_token,
763
765
  error_message="Deep Scan orchestration is owned by another continuation.",
764
766
  )
767
+ connection.execute(
768
+ "UPDATE workspaces SET deep_scan_config_json = ? WHERE id = ? AND deep_scan_config_json IS NULL",
769
+ (json.dumps(configuration), workspace["id"]),
770
+ )
765
771
  ensure_deep_scan_run(connection, scan, config, workflow_version, dependencies().now())
766
772
  return deep_scan_result(connection, scan_id, start_disposition="created")
767
773
 
@@ -777,6 +783,30 @@ def begin_deep_scan_for_target(
777
783
  if existing is not None:
778
784
  return begin_deep_scan_for_scan(connection, existing["id"], thread_id, args)
779
785
  user_context = user_context_argument(args)
786
+ # Keep the requested spelling so a continuation can match a removed file or symlink.
787
+ # NULL means no result is pending. The empty string denotes a launch with no project file.
788
+ project_path = args.project_config_path or ""
789
+ # Avoid hashing the checkout during this probe when a fresh scan needs its configuration.
790
+ if (
791
+ args.join_only
792
+ and not connection.execute(
793
+ """
794
+ SELECT 1 FROM scans JOIN deep_scan_runs ON deep_scan_runs.scan_id = scans.id
795
+ WHERE scans.target_path = ? AND scans.scope = ?
796
+ AND (scans.status = 'running'
797
+ OR (scans.status = 'complete'
798
+ AND deep_scan_runs.pending_target_project_path IS NOT NULL))
799
+ AND (deep_scan_runs.pending_target_project_path IS NULL
800
+ OR deep_scan_runs.pending_target_project_path = ?)
801
+ AND scans.recipe_json IS NULL
802
+ AND scans.handoff_claim_token IS NULL AND deep_scan_runs.status = 'succeeded'
803
+ AND deep_scan_runs.discovery_user_context_json = ?
804
+ LIMIT 1
805
+ """,
806
+ (target_path, scope, project_path, json.dumps(user_context)),
807
+ ).fetchone()
808
+ ):
809
+ return {"newScanTarget": target_path}
780
810
  target_metadata = target.stat()
781
811
  target_identity = dependencies().scan_target_identity(target, None, metadata=target_metadata)
782
812
  revision, target_snapshot_digest, target_device, target_inode = target_identity
@@ -787,23 +817,8 @@ def begin_deep_scan_for_target(
787
817
  with connection:
788
818
  existing = existing_deep_scan_for_target(connection, thread_id, target_path, scope)
789
819
  if existing is not None:
790
- existing_run = connection.execute(
791
- "SELECT 1 FROM deep_scan_runs WHERE scan_id = ?", (existing["id"],)
792
- ).fetchone()
793
- if existing_run is None:
794
- config = effective_deep_scan_config(args)
795
- workflow_version = optional_text(args.workflow_version, maximum=256)
796
- if workflow_version is None:
797
- raise SystemExit("workflow-version is required.")
798
- ensure_deep_scan_run(
799
- connection, existing, config, workflow_version, dependencies().now()
800
- )
801
820
  connection.commit()
802
- return deep_scan_result(
803
- connection,
804
- existing["id"],
805
- start_disposition="joined" if existing_run is not None else "created",
806
- )
821
+ return begin_deep_scan_for_scan(connection, existing["id"], thread_id, args)
807
822
  current_target = dependencies().require_remediation_target(target_path)
808
823
  current_metadata = current_target.stat()
809
824
  if (current_metadata.st_dev, current_metadata.st_ino) != (
@@ -819,6 +834,7 @@ def begin_deep_scan_for_target(
819
834
  target_path,
820
835
  scope,
821
836
  user_context,
837
+ project_path,
822
838
  revision,
823
839
  target_snapshot_digest,
824
840
  target_device,
@@ -831,12 +847,15 @@ def begin_deep_scan_for_target(
831
847
  terminal["id"],
832
848
  start_disposition="joined",
833
849
  )
850
+ if args.join_only:
851
+ return {"newScanTarget": target_path}
834
852
  source_scopes = capture_source_scopes(
835
853
  target,
836
854
  (revision, target_snapshot_digest, target_device, target_inode),
837
855
  [scope],
838
856
  )
839
- config = effective_deep_scan_config(args)
857
+ configuration = effective_deep_scan_config(args)
858
+ config = configuration["settings"]
840
859
  workflow_version = optional_text(args.workflow_version, maximum=256)
841
860
  if workflow_version is None:
842
861
  raise SystemExit("workflow-version is required.")
@@ -855,8 +874,8 @@ def begin_deep_scan_for_target(
855
874
  """
856
875
  INSERT INTO workspaces (
857
876
  id, thread_id, target_id, target_path, target_title, default_scope, default_mode,
858
- user_context, submitted, created_at, updated_at
859
- ) VALUES (?, ?, ?, ?, ?, ?, 'deep', ?, 1, ?, ?)
877
+ user_context, submitted, created_at, updated_at, deep_scan_config_json
878
+ ) VALUES (?, ?, ?, ?, ?, ?, 'deep', ?, 1, ?, ?, ?)
860
879
  """,
861
880
  (
862
881
  workspace_id,
@@ -868,6 +887,7 @@ def begin_deep_scan_for_target(
868
887
  user_context,
869
888
  timestamp,
870
889
  timestamp,
890
+ json.dumps(configuration),
871
891
  ),
872
892
  )
873
893
  workspace = connection.execute(
@@ -891,7 +911,14 @@ def begin_deep_scan_for_target(
891
911
  reasoning_effort=reasoning_effort,
892
912
  )
893
913
  scan = dependencies().require_scan(connection, scan_id)
894
- ensure_deep_scan_run(connection, scan, config, workflow_version, timestamp)
914
+ ensure_deep_scan_run(
915
+ connection,
916
+ scan,
917
+ config,
918
+ workflow_version,
919
+ timestamp,
920
+ pending_target_project_path=project_path,
921
+ )
895
922
  return deep_scan_result(connection, scan_id, start_disposition="created")
896
923
 
897
924
 
@@ -913,6 +940,24 @@ def get_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> d
913
940
  return deep_scan_result(connection, scan["id"])
914
941
 
915
942
 
943
+ def acknowledge_deep_scan_result(
944
+ connection: sqlite3.Connection, args: argparse.Namespace
945
+ ) -> dict[str, Any]:
946
+ with connection:
947
+ connection.execute(
948
+ """
949
+ UPDATE deep_scan_runs SET pending_target_project_path = NULL
950
+ WHERE scan_id = ? AND pending_target_project_path IS NOT NULL
951
+ AND status = 'succeeded'
952
+ AND EXISTS (
953
+ SELECT 1 FROM scans WHERE id = deep_scan_runs.scan_id AND status = 'complete'
954
+ )
955
+ """,
956
+ (require_uuid(args.scan_id, "scan-id"),),
957
+ )
958
+ return {}
959
+
960
+
916
961
  def coordinator_lease_is_live(
917
962
  connection: sqlite3.Connection,
918
963
  run: sqlite3.Row,
@@ -1181,7 +1226,7 @@ def upsert_deep_scan_worker(
1181
1226
  or args.status != "canceled"
1182
1227
  or existing is None
1183
1228
  or existing["status"] not in {"running", "canceled"}
1184
- or optional_text(args.error_message, maximum=2400) is None
1229
+ or optional_text(args.error_message) is None
1185
1230
  ):
1186
1231
  raise SystemExit(
1187
1232
  "A replaceable Deep Scan failure requires a running discovery worker, "
@@ -1262,7 +1307,7 @@ def upsert_deep_scan_worker(
1262
1307
  artifact_dir,
1263
1308
  attempt,
1264
1309
  optional_text(args.sdk_thread_id, maximum=512),
1265
- optional_text(args.error_message, maximum=2400),
1310
+ optional_text(args.error_message),
1266
1311
  timestamp,
1267
1312
  timestamp if args.status == "running" else None,
1268
1313
  timestamp,
@@ -1279,7 +1324,7 @@ def upsert_deep_scan_worker(
1279
1324
  if terminal_repeat:
1280
1325
  repeated_attempt = args.attempt if args.attempt is not None else existing["attempt"]
1281
1326
  repeated_thread_id = optional_text(args.sdk_thread_id, maximum=512)
1282
- repeated_error = optional_text(args.error_message, maximum=2400)
1327
+ repeated_error = optional_text(args.error_message)
1283
1328
  repeated_result_path = result_manifest_path or existing["result_manifest_path"]
1284
1329
  if (
1285
1330
  repeated_attempt != existing["attempt"]
@@ -1361,7 +1406,7 @@ def upsert_deep_scan_worker(
1361
1406
  if args.status in {"succeeded", "failed", "canceled"}
1362
1407
  else existing["completed_at"]
1363
1408
  )
1364
- error_message = optional_text(args.error_message, maximum=2400)
1409
+ error_message = optional_text(args.error_message)
1365
1410
  if error_message is None and args.status != "succeeded":
1366
1411
  error_message = existing["error_message"]
1367
1412
  started_at = existing["started_at"] or (timestamp if args.status == "running" else None)
@@ -1676,6 +1721,9 @@ def finish_deep_scan_locked(
1676
1721
  if len(set(omitted_worker_ids)) != len(omitted_worker_ids):
1677
1722
  raise SystemExit("Omitted Deep Scan worker IDs must be unique.")
1678
1723
  promotion: tuple[Path, Path, Path | None] | None = None
1724
+ deadline_publication: (
1725
+ tuple[Path, dict[str, tuple[bytes, os.stat_result] | None], set[str]] | None
1726
+ ) = None
1679
1727
  connection.execute("BEGIN IMMEDIATE")
1680
1728
  try:
1681
1729
  run = require_deep_scan_run(connection, scan_id)
@@ -1765,9 +1813,9 @@ def finish_deep_scan_locked(
1765
1813
  """,
1766
1814
  (scan_id,),
1767
1815
  ).fetchone()
1816
+ discovery_deadline = args.terminal_reason == "capped" and deep_scan_deadline_reached(run)
1768
1817
  zero_discovery_deadline = (
1769
- args.terminal_reason == "capped"
1770
- and deep_scan_deadline_reached(run)
1818
+ discovery_deadline
1771
1819
  and run["completion_sequence"] == 0
1772
1820
  and (
1773
1821
  standard_scan_manifest
@@ -1799,25 +1847,37 @@ def finish_deep_scan_locked(
1799
1847
  kind="file",
1800
1848
  )
1801
1849
  promotion = promote_staged_file(staged_manifest_path, manifest_path)
1802
- with (
1803
- saved_results.preserve_deep_deadline_draft(dependencies(), connection, scan)
1804
- if zero_discovery_deadline and standard_scan_manifest
1805
- else nullcontext()
1806
- ):
1807
- timestamp = dependencies().now()
1808
- connection.execute(
1809
- """
1810
- UPDATE deep_scan_runs
1811
- SET status = 'succeeded', phase = 'terminal', terminal_reason = ?,
1812
- manifest_path = ?, completed_at = ?, updated_at = ?
1813
- WHERE scan_id = ?
1814
- """,
1815
- (args.terminal_reason, manifest_path, timestamp, timestamp, scan_id),
1850
+ if zero_discovery_deadline or (discovery_deadline and standard_scan_manifest):
1851
+ deadline_publication = saved_results.preserve_deep_deadline_draft(
1852
+ dependencies(),
1853
+ connection,
1854
+ scan,
1855
+ preserve_reduction=not zero_discovery_deadline,
1856
+ allow_empty=not standard_scan_manifest,
1816
1857
  )
1817
- cancel_active_workers(connection, scan_id, timestamp)
1818
- connection.commit()
1858
+ timestamp = dependencies().now()
1859
+ connection.execute(
1860
+ """
1861
+ UPDATE deep_scan_runs
1862
+ SET status = 'succeeded', phase = 'terminal', terminal_reason = ?,
1863
+ manifest_path = ?, completed_at = ?, updated_at = ?
1864
+ WHERE scan_id = ?
1865
+ """,
1866
+ (args.terminal_reason, manifest_path, timestamp, timestamp, scan_id),
1867
+ )
1868
+ cancel_active_workers(connection, scan_id, timestamp)
1869
+ connection.commit()
1819
1870
  except BaseException:
1820
1871
  connection.rollback()
1872
+ if deadline_publication is not None or promotion is not None:
1873
+ # A signal can arrive after SQLite commits but before commit returns.
1874
+ # The completion lock makes persisted success authoritative here.
1875
+ if require_deep_scan_run(connection, scan_id)["status"] == "succeeded":
1876
+ if promotion is not None:
1877
+ finish_staged_file(promotion)
1878
+ raise
1879
+ if deadline_publication is not None:
1880
+ saved_results._restore_published_outputs(*deadline_publication)
1821
1881
  if promotion is not None:
1822
1882
  rollback_staged_file(promotion)
1823
1883
  raise
@@ -1835,7 +1895,7 @@ def fail_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) ->
1835
1895
  def fail_deep_scan_locked(
1836
1896
  connection: sqlite3.Connection, args: argparse.Namespace, scan_id: str
1837
1897
  ) -> dict[str, Any]:
1838
- message = optional_text(args.message, maximum=2400)
1898
+ message = optional_text(args.message)
1839
1899
  if message is None:
1840
1900
  raise SystemExit("message is required.")
1841
1901
  promotion: tuple[Path, Path, Path | None] | None = None
@@ -1933,7 +1993,7 @@ def record_deep_scan_publication_failure(
1933
1993
  connection: sqlite3.Connection, args: argparse.Namespace
1934
1994
  ) -> dict[str, Any]:
1935
1995
  scan_id = require_uuid(args.scan_id, "scan-id")
1936
- message = optional_text(args.message, maximum=2400)
1996
+ message = optional_text(args.message)
1937
1997
  if message is None:
1938
1998
  raise SystemExit("message is required.")
1939
1999
  with dependencies().scan_completion_lock(scan_id):