@openai/codex-security 0.8.3 → 0.10.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 (658) hide show
  1. package/README.md +36 -746
  2. package/_bundled_plugin/.codex-plugin/plugin.json +2 -0
  3. package/_bundled_plugin/.mcp.json +7 -1
  4. package/_bundled_plugin/examples/completed-scan/findings.json +16 -4
  5. package/_bundled_plugin/examples/completed-scan/report.md +11 -8
  6. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +4 -2
  7. package/_bundled_plugin/mcp/fzstd-LICENSE.txt +21 -0
  8. package/_bundled_plugin/mcp/helpers.mjs +2 -11
  9. package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
  10. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +3 -210
  11. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  13. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/package.json +1 -0
  20. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +5 -2
  21. package/_bundled_plugin/mcp/server.mjs +2 -11
  22. package/_bundled_plugin/mcp/server.mjs.br +0 -0
  23. package/_bundled_plugin/mcp/session-decompression.mjs +712 -0
  24. package/_bundled_plugin/references/artifact-storage.md +1 -1
  25. package/_bundled_plugin/references/baseline-auditor.md +18 -0
  26. package/_bundled_plugin/references/core-scan.md +5 -42
  27. package/_bundled_plugin/references/default-severity-rubric.md +9 -4
  28. package/_bundled_plugin/references/final-report.md +5 -3
  29. package/_bundled_plugin/references/finding-detail-fields.md +18 -18
  30. package/_bundled_plugin/references/focused-investigator.md +13 -0
  31. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  32. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  33. package/_bundled_plugin/references/scan-contract.md +27 -33
  34. package/_bundled_plugin/references/scan-prologue.md +2 -2
  35. package/_bundled_plugin/references/scan-runtime.md +4 -2
  36. package/_bundled_plugin/references/security-guidance.md +14 -1
  37. package/_bundled_plugin/references/validate-scan-findings.md +3 -0
  38. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  39. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  40. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  41. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  42. package/_bundled_plugin/scripts/deep_scan_workbench.py +192 -352
  43. package/_bundled_plugin/scripts/dispatch_inventory_tool +7 -0
  44. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  45. package/_bundled_plugin/scripts/finalize_scan_contract.py +182 -230
  46. package/_bundled_plugin/scripts/finding_preview.py +20 -0
  47. package/_bundled_plugin/scripts/launch_codex_security_mcp +55 -16
  48. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  49. package/_bundled_plugin/scripts/posix_scan_local_files.py +37 -1
  50. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  51. package/_bundled_plugin/scripts/report_projection.py +81 -43
  52. package/_bundled_plugin/scripts/review_state.py +8 -2
  53. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  54. package/_bundled_plugin/scripts/snapshot_sqlite.py +9 -2
  55. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  56. package/_bundled_plugin/scripts/validate_scan_contract.py +7 -1
  57. package/_bundled_plugin/scripts/windows_scan_local_files.py +582 -20
  58. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  59. package/_bundled_plugin/scripts/workbench/handoff.py +100 -23
  60. package/_bundled_plugin/scripts/workbench/retained_coverage.py +30 -51
  61. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  62. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  63. package/_bundled_plugin/scripts/workbench/saved_coverage.py +9 -17
  64. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  65. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  66. package/_bundled_plugin/scripts/workbench/storage.py +91 -7
  67. package/_bundled_plugin/scripts/workbench_cli.py +54 -14
  68. package/_bundled_plugin/scripts/workbench_constants.py +12 -0
  69. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  70. package/_bundled_plugin/scripts/workbench_db.py +562 -303
  71. package/_bundled_plugin/scripts/workbench_feedback.py +57 -11
  72. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  73. package/_bundled_plugin/scripts/workbench_finding_workflows.py +4 -0
  74. package/_bundled_plugin/scripts/workbench_native_indexes.py +238 -41
  75. package/_bundled_plugin/scripts/workbench_progress.py +169 -4
  76. package/_bundled_plugin/scripts/workbench_publication.py +16 -13
  77. package/_bundled_plugin/scripts/workbench_remediation.py +155 -2
  78. package/_bundled_plugin/scripts/workbench_saved_results.py +176 -81
  79. package/_bundled_plugin/scripts/workbench_scan_history.py +398 -174
  80. package/_bundled_plugin/scripts/workbench_scan_start.py +224 -31
  81. package/_bundled_plugin/scripts/workbench_scan_usage.py +675 -73
  82. package/_bundled_plugin/scripts/workbench_schema.py +258 -63
  83. package/_bundled_plugin/scripts/workbench_setup.py +14 -2
  84. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  85. package/_bundled_plugin/scripts/workbench_source_scopes.py +18 -0
  86. package/_bundled_plugin/scripts/workbench_target.py +594 -136
  87. package/_bundled_plugin/scripts/workbench_target_state.py +1110 -21
  88. package/_bundled_plugin/scripts/workbench_validation.py +43 -3
  89. package/_bundled_plugin/shared/workbench-history-repairs.json +77 -35
  90. package/_bundled_plugin/shared/workbench-migrations.json +100 -0
  91. package/_bundled_plugin/skills/cloud-findings/SKILL.md +5 -5
  92. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  93. package/_bundled_plugin/skills/fix-finding/SKILL.md +2 -1
  94. package/_bundled_plugin/skills/publish-findings/SKILL.md +24 -153
  95. package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +2 -2
  96. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  97. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +3 -3
  98. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +409 -0
  99. package/_bundled_plugin/skills/publish-findings/scripts/collect_continuum.py +224 -0
  100. package/_bundled_plugin/skills/publish-findings/scripts/collector_paths.py +63 -0
  101. package/_bundled_plugin/skills/security-scan/SKILL.md +9 -46
  102. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +2 -2
  103. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -21
  104. package/_bundled_plugin/skills/security-scan/references/managed-scan.md +11 -0
  105. package/_bundled_plugin/skills/security-scan/references/scan-results.md +15 -0
  106. package/_bundled_plugin/skills/security-scan/references/scoped-paths.md +23 -0
  107. package/_bundled_plugin/skills/security-scan/references/sdk-files.md +24 -0
  108. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +22 -1
  109. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -2
  110. package/bin/codex-security.mjs +2 -2
  111. package/dist/api.d.ts +45 -5
  112. package/dist/api.d.ts.map +1 -1
  113. package/dist/api.js +1192 -427
  114. package/dist/api.js.map +1 -1
  115. package/dist/armorcode-findings.d.ts +9 -0
  116. package/dist/armorcode-findings.d.ts.map +1 -0
  117. package/dist/armorcode-findings.js +145 -0
  118. package/dist/armorcode-findings.js.map +1 -0
  119. package/dist/artifact-export.d.ts +2 -0
  120. package/dist/artifact-export.d.ts.map +1 -1
  121. package/dist/artifact-export.js +29 -13
  122. package/dist/artifact-export.js.map +1 -1
  123. package/dist/auth.d.ts +6 -2
  124. package/dist/auth.d.ts.map +1 -1
  125. package/dist/auth.js +37 -18
  126. package/dist/auth.js.map +1 -1
  127. package/dist/batch-cost.d.ts +18 -0
  128. package/dist/batch-cost.d.ts.map +1 -0
  129. package/dist/batch-cost.js +41 -0
  130. package/dist/batch-cost.js.map +1 -0
  131. package/dist/bedrock-oss-pricing.d.ts +6 -0
  132. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  133. package/dist/bedrock-oss-pricing.js +58 -0
  134. package/dist/bedrock-oss-pricing.js.map +1 -0
  135. package/dist/bedrock-pricing.d.ts +15 -0
  136. package/dist/bedrock-pricing.d.ts.map +1 -0
  137. package/dist/bedrock-pricing.js +117 -0
  138. package/dist/bedrock-pricing.js.map +1 -0
  139. package/dist/blackduck-findings.d.ts +1 -1
  140. package/dist/blackduck-findings.d.ts.map +1 -1
  141. package/dist/blackduck-findings.js +24 -22
  142. package/dist/blackduck-findings.js.map +1 -1
  143. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  144. package/dist/bulk-scan-discovery.js +4 -4
  145. package/dist/bulk-scan-discovery.js.map +1 -1
  146. package/dist/bundled-plugin.d.ts +4 -0
  147. package/dist/bundled-plugin.d.ts.map +1 -0
  148. package/dist/bundled-plugin.js +23 -0
  149. package/dist/bundled-plugin.js.map +1 -0
  150. package/dist/checkmarx-evidence.d.ts +19 -0
  151. package/dist/checkmarx-evidence.d.ts.map +1 -0
  152. package/dist/checkmarx-evidence.js +36 -0
  153. package/dist/checkmarx-evidence.js.map +1 -0
  154. package/dist/checkmarx-findings.d.ts +4 -0
  155. package/dist/checkmarx-findings.d.ts.map +1 -0
  156. package/dist/checkmarx-findings.js +27 -0
  157. package/dist/checkmarx-findings.js.map +1 -0
  158. package/dist/checkmarx-one.d.ts +4 -0
  159. package/dist/checkmarx-one.d.ts.map +1 -0
  160. package/dist/checkmarx-one.js +53 -0
  161. package/dist/checkmarx-one.js.map +1 -0
  162. package/dist/checkmarx-repository.d.ts +12 -0
  163. package/dist/checkmarx-repository.d.ts.map +1 -0
  164. package/dist/checkmarx-repository.js +181 -0
  165. package/dist/checkmarx-repository.js.map +1 -0
  166. package/dist/checkmarx-xml.d.ts +12 -0
  167. package/dist/checkmarx-xml.d.ts.map +1 -0
  168. package/dist/checkmarx-xml.js +196 -0
  169. package/dist/checkmarx-xml.js.map +1 -0
  170. package/dist/classify-scan-severity.d.ts +1 -1
  171. package/dist/classify-scan-severity.d.ts.map +1 -1
  172. package/dist/classify-scan-severity.js +11 -3
  173. package/dist/classify-scan-severity.js.map +1 -1
  174. package/dist/classify-severity-records.d.ts +1 -9
  175. package/dist/classify-severity-records.d.ts.map +1 -1
  176. package/dist/classify-severity-records.js +3 -13
  177. package/dist/classify-severity-records.js.map +1 -1
  178. package/dist/classify-severity.d.ts.map +1 -1
  179. package/dist/classify-severity.js +11 -10
  180. package/dist/classify-severity.js.map +1 -1
  181. package/dist/cli-argument.d.ts +4 -0
  182. package/dist/cli-argument.d.ts.map +1 -0
  183. package/dist/cli-argument.js +17 -0
  184. package/dist/cli-argument.js.map +1 -0
  185. package/dist/cli-help.d.ts +1 -1
  186. package/dist/cli-help.d.ts.map +1 -1
  187. package/dist/cli-help.js +71 -29
  188. package/dist/cli-help.js.map +1 -1
  189. package/dist/cli-hook.d.ts +3 -0
  190. package/dist/cli-hook.d.ts.map +1 -0
  191. package/dist/cli-hook.js +87 -0
  192. package/dist/cli-hook.js.map +1 -0
  193. package/dist/cli-integrations.d.ts +13 -0
  194. package/dist/cli-integrations.d.ts.map +1 -0
  195. package/dist/cli-integrations.js +333 -0
  196. package/dist/cli-integrations.js.map +1 -0
  197. package/dist/cli-mcp.d.ts +15 -0
  198. package/dist/cli-mcp.d.ts.map +1 -0
  199. package/dist/cli-mcp.js +178 -0
  200. package/dist/cli-mcp.js.map +1 -0
  201. package/dist/cli-token-view.d.ts +10 -0
  202. package/dist/cli-token-view.d.ts.map +1 -0
  203. package/dist/cli-token-view.js +41 -0
  204. package/dist/cli-token-view.js.map +1 -0
  205. package/dist/cli.d.ts +16 -8
  206. package/dist/cli.d.ts.map +1 -1
  207. package/dist/cli.js +3382 -2017
  208. package/dist/cli.js.map +1 -1
  209. package/dist/cloud-publish.d.ts.map +1 -1
  210. package/dist/cloud-publish.js +35 -33
  211. package/dist/cloud-publish.js.map +1 -1
  212. package/dist/codex-sdk-environment.d.ts +6 -0
  213. package/dist/codex-sdk-environment.d.ts.map +1 -1
  214. package/dist/codex-sdk-environment.js +19 -0
  215. package/dist/codex-sdk-environment.js.map +1 -1
  216. package/dist/command-words.d.ts +3 -0
  217. package/dist/command-words.d.ts.map +1 -0
  218. package/dist/command-words.js +46 -0
  219. package/dist/command-words.js.map +1 -0
  220. package/dist/component-scan.d.ts +19 -4
  221. package/dist/component-scan.d.ts.map +1 -1
  222. package/dist/component-scan.js +67 -9
  223. package/dist/component-scan.js.map +1 -1
  224. package/dist/config.d.ts +1 -1
  225. package/dist/config.d.ts.map +1 -1
  226. package/dist/config.js +130 -67
  227. package/dist/config.js.map +1 -1
  228. package/dist/continuum-findings.d.ts +1 -1
  229. package/dist/continuum-findings.d.ts.map +1 -1
  230. package/dist/continuum-findings.js +149 -19
  231. package/dist/continuum-findings.js.map +1 -1
  232. package/dist/contract-values.d.ts +2 -0
  233. package/dist/contract-values.d.ts.map +1 -1
  234. package/dist/contract-values.js +12 -9
  235. package/dist/contract-values.js.map +1 -1
  236. package/dist/cost-model.d.ts +13 -1
  237. package/dist/cost-model.d.ts.map +1 -1
  238. package/dist/cost-model.js +66 -112
  239. package/dist/cost-model.js.map +1 -1
  240. package/dist/cost.d.ts +42 -3
  241. package/dist/cost.d.ts.map +1 -1
  242. package/dist/cost.js +484 -149
  243. package/dist/cost.js.map +1 -1
  244. package/dist/custom-publish.d.ts +4 -0
  245. package/dist/custom-publish.d.ts.map +1 -1
  246. package/dist/custom-publish.js +40 -3
  247. package/dist/custom-publish.js.map +1 -1
  248. package/dist/custom-validation-prompt.d.ts +1 -1
  249. package/dist/custom-validation-prompt.d.ts.map +1 -1
  250. package/dist/custom-validation-prompt.js +29 -19
  251. package/dist/custom-validation-prompt.js.map +1 -1
  252. package/dist/deduplication/local.d.ts +4 -2
  253. package/dist/deduplication/local.d.ts.map +1 -1
  254. package/dist/deduplication/local.js +9 -2
  255. package/dist/deduplication/local.js.map +1 -1
  256. package/dist/deduplication/refusal.d.ts.map +1 -1
  257. package/dist/deduplication/refusal.js +26 -5
  258. package/dist/deduplication/refusal.js.map +1 -1
  259. package/dist/deduplication/scan.d.ts +5 -0
  260. package/dist/deduplication/scan.d.ts.map +1 -1
  261. package/dist/deduplication/scan.js +24 -7
  262. package/dist/deduplication/scan.js.map +1 -1
  263. package/dist/deep-config.d.ts +0 -1
  264. package/dist/deep-config.d.ts.map +1 -1
  265. package/dist/deep-config.js +22 -33
  266. package/dist/deep-config.js.map +1 -1
  267. package/dist/deep-scan-defaults.d.ts +2 -0
  268. package/dist/deep-scan-defaults.d.ts.map +1 -1
  269. package/dist/deep-scan-defaults.js +28 -1
  270. package/dist/deep-scan-defaults.js.map +1 -1
  271. package/dist/deep-scan.d.ts +2 -0
  272. package/dist/deep-scan.d.ts.map +1 -1
  273. package/dist/deep-scan.js +44 -19
  274. package/dist/deep-scan.js.map +1 -1
  275. package/dist/default-severity-rubric.d.ts +1 -1
  276. package/dist/default-severity-rubric.d.ts.map +1 -1
  277. package/dist/default-severity-rubric.js +1 -1
  278. package/dist/default-severity-rubric.js.map +1 -1
  279. package/dist/endor-findings.d.ts +3 -1
  280. package/dist/endor-findings.d.ts.map +1 -1
  281. package/dist/endor-findings.js +86 -45
  282. package/dist/endor-findings.js.map +1 -1
  283. package/dist/errors.d.ts +4 -2
  284. package/dist/errors.d.ts.map +1 -1
  285. package/dist/errors.js +15 -4
  286. package/dist/errors.js.map +1 -1
  287. package/dist/executable-path.d.ts +3 -0
  288. package/dist/executable-path.d.ts.map +1 -1
  289. package/dist/executable-path.js +26 -0
  290. package/dist/executable-path.js.map +1 -1
  291. package/dist/external-findings-import.d.ts +5 -3
  292. package/dist/external-findings-import.d.ts.map +1 -1
  293. package/dist/external-findings-import.js +19 -7
  294. package/dist/external-findings-import.js.map +1 -1
  295. package/dist/external-findings-local.d.ts +69 -5
  296. package/dist/external-findings-local.d.ts.map +1 -1
  297. package/dist/external-findings-local.js +537 -108
  298. package/dist/external-findings-local.js.map +1 -1
  299. package/dist/external-findings-publish.d.ts +13 -6
  300. package/dist/external-findings-publish.d.ts.map +1 -1
  301. package/dist/external-findings-publish.js +895 -1142
  302. package/dist/external-findings-publish.js.map +1 -1
  303. package/dist/external-findings-read.d.ts +21 -2
  304. package/dist/external-findings-read.d.ts.map +1 -1
  305. package/dist/external-findings-read.js +130 -68
  306. package/dist/external-findings-read.js.map +1 -1
  307. package/dist/external-findings.d.ts +15 -3
  308. package/dist/external-findings.d.ts.map +1 -1
  309. package/dist/external-findings.js +54 -2
  310. package/dist/external-findings.js.map +1 -1
  311. package/dist/external-import-contract.d.ts +8 -12
  312. package/dist/external-import-contract.d.ts.map +1 -1
  313. package/dist/external-import-contract.js +51 -184
  314. package/dist/external-import-contract.js.map +1 -1
  315. package/dist/external-import-models.d.ts +1 -1
  316. package/dist/external-import-models.d.ts.map +1 -1
  317. package/dist/external-import-models.js.map +1 -1
  318. package/dist/feedback.d.ts.map +1 -1
  319. package/dist/feedback.js +5 -4
  320. package/dist/feedback.js.map +1 -1
  321. package/dist/finding-prompt.d.ts +5 -0
  322. package/dist/finding-prompt.d.ts.map +1 -0
  323. package/dist/finding-prompt.js +32 -0
  324. package/dist/finding-prompt.js.map +1 -0
  325. package/dist/findings-client.d.ts +1 -0
  326. package/dist/findings-client.d.ts.map +1 -1
  327. package/dist/findings-client.js +27 -3
  328. package/dist/findings-client.js.map +1 -1
  329. package/dist/github-advisories.d.ts.map +1 -1
  330. package/dist/github-advisories.js +0 -2
  331. package/dist/github-advisories.js.map +1 -1
  332. package/dist/github-dependabot-findings.d.ts.map +1 -1
  333. package/dist/github-dependabot-findings.js +18 -8
  334. package/dist/github-dependabot-findings.js.map +1 -1
  335. package/dist/github-findings.d.ts +4 -1
  336. package/dist/github-findings.d.ts.map +1 -1
  337. package/dist/github-findings.js +73 -316
  338. package/dist/github-findings.js.map +1 -1
  339. package/dist/hosted-git-remotes.d.ts +5 -0
  340. package/dist/hosted-git-remotes.d.ts.map +1 -0
  341. package/dist/hosted-git-remotes.js +285 -0
  342. package/dist/hosted-git-remotes.js.map +1 -0
  343. package/dist/hosted-git-repository.d.ts +28 -0
  344. package/dist/hosted-git-repository.d.ts.map +1 -0
  345. package/dist/hosted-git-repository.js +222 -0
  346. package/dist/hosted-git-repository.js.map +1 -0
  347. package/dist/hosted-remediation.d.ts +1 -0
  348. package/dist/hosted-remediation.d.ts.map +1 -1
  349. package/dist/hosted-remediation.js +23 -3
  350. package/dist/hosted-remediation.js.map +1 -1
  351. package/dist/hosted-scan-protocol.js +2 -2
  352. package/dist/hosted-scan-protocol.js.map +1 -1
  353. package/dist/hosted-scan.d.ts.map +1 -1
  354. package/dist/hosted-scan.js +16 -11
  355. package/dist/hosted-scan.js.map +1 -1
  356. package/dist/hosted-scanner-http.d.ts +21 -0
  357. package/dist/hosted-scanner-http.d.ts.map +1 -0
  358. package/dist/hosted-scanner-http.js +204 -0
  359. package/dist/hosted-scanner-http.js.map +1 -0
  360. package/dist/import-scan.d.ts.map +1 -1
  361. package/dist/import-scan.js +3 -0
  362. package/dist/import-scan.js.map +1 -1
  363. package/dist/index.d.ts +21 -9
  364. package/dist/index.d.ts.map +1 -1
  365. package/dist/index.js +12 -3
  366. package/dist/index.js.map +1 -1
  367. package/dist/inspector-findings.d.ts.map +1 -1
  368. package/dist/inspector-findings.js +52 -86
  369. package/dist/inspector-findings.js.map +1 -1
  370. package/dist/knowledge-base.d.ts +1 -1
  371. package/dist/knowledge-base.d.ts.map +1 -1
  372. package/dist/knowledge-base.js +102 -32
  373. package/dist/knowledge-base.js.map +1 -1
  374. package/dist/linear.d.ts +11 -0
  375. package/dist/linear.d.ts.map +1 -1
  376. package/dist/linear.js.map +1 -1
  377. package/dist/local-git-metadata.d.ts +5 -2
  378. package/dist/local-git-metadata.d.ts.map +1 -1
  379. package/dist/local-git-metadata.js +8 -5
  380. package/dist/local-git-metadata.js.map +1 -1
  381. package/dist/multiscan.d.ts +10 -4
  382. package/dist/multiscan.d.ts.map +1 -1
  383. package/dist/multiscan.js +217 -102
  384. package/dist/multiscan.js.map +1 -1
  385. package/dist/native-json-findings.d.ts +2 -1
  386. package/dist/native-json-findings.d.ts.map +1 -1
  387. package/dist/native-json-findings.js +12 -2
  388. package/dist/native-json-findings.js.map +1 -1
  389. package/dist/opengrep-findings.d.ts +5 -2
  390. package/dist/opengrep-findings.d.ts.map +1 -1
  391. package/dist/opengrep-findings.js +54 -33
  392. package/dist/opengrep-findings.js.map +1 -1
  393. package/dist/operation-telemetry.d.ts +104 -0
  394. package/dist/operation-telemetry.d.ts.map +1 -0
  395. package/dist/operation-telemetry.js +293 -0
  396. package/dist/operation-telemetry.js.map +1 -0
  397. package/dist/plugin-python-probe.d.ts +4 -0
  398. package/dist/plugin-python-probe.d.ts.map +1 -0
  399. package/dist/plugin-python-probe.js +10 -0
  400. package/dist/plugin-python-probe.js.map +1 -0
  401. package/dist/private-finding-import.d.ts +99 -9
  402. package/dist/private-finding-import.d.ts.map +1 -1
  403. package/dist/private-finding-import.js +116 -152
  404. package/dist/private-finding-import.js.map +1 -1
  405. package/dist/project-config.d.ts.map +1 -1
  406. package/dist/project-config.js +53 -13
  407. package/dist/project-config.js.map +1 -1
  408. package/dist/prompt-files.d.ts +7 -2
  409. package/dist/prompt-files.d.ts.map +1 -1
  410. package/dist/prompt-files.js +42 -20
  411. package/dist/prompt-files.js.map +1 -1
  412. package/dist/provider-profile.d.ts +1 -1
  413. package/dist/provider-profile.d.ts.map +1 -1
  414. package/dist/provider-profile.js +12 -10
  415. package/dist/provider-profile.js.map +1 -1
  416. package/dist/publication-telemetry.d.ts +45 -0
  417. package/dist/publication-telemetry.d.ts.map +1 -0
  418. package/dist/publication-telemetry.js +50 -0
  419. package/dist/publication-telemetry.js.map +1 -0
  420. package/dist/publication.d.ts +1 -1
  421. package/dist/publication.d.ts.map +1 -1
  422. package/dist/publication.js.map +1 -1
  423. package/dist/publish.d.ts +4 -0
  424. package/dist/publish.d.ts.map +1 -1
  425. package/dist/publish.js +42 -2
  426. package/dist/publish.js.map +1 -1
  427. package/dist/record.d.ts +1 -5
  428. package/dist/record.d.ts.map +1 -1
  429. package/dist/record.js +3 -51
  430. package/dist/record.js.map +1 -1
  431. package/dist/remediation.d.ts +1 -4
  432. package/dist/remediation.d.ts.map +1 -1
  433. package/dist/remediation.js +6 -8
  434. package/dist/remediation.js.map +1 -1
  435. package/dist/request-metadata.d.ts +3 -0
  436. package/dist/request-metadata.d.ts.map +1 -1
  437. package/dist/request-metadata.js +9 -0
  438. package/dist/request-metadata.js.map +1 -1
  439. package/dist/result.d.ts +4 -0
  440. package/dist/result.d.ts.map +1 -1
  441. package/dist/result.js +1 -1
  442. package/dist/result.js.map +1 -1
  443. package/dist/retry-windows-rename.d.ts +8 -0
  444. package/dist/retry-windows-rename.d.ts.map +1 -0
  445. package/dist/retry-windows-rename.js +24 -0
  446. package/dist/retry-windows-rename.js.map +1 -0
  447. package/dist/runtime.d.ts +54 -6
  448. package/dist/runtime.d.ts.map +1 -1
  449. package/dist/runtime.js +1084 -256
  450. package/dist/runtime.js.map +1 -1
  451. package/dist/saved-scan-bootstrap.d.ts +7 -1
  452. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  453. package/dist/saved-scan-bootstrap.js +269 -114
  454. package/dist/saved-scan-bootstrap.js.map +1 -1
  455. package/dist/scan-activity.d.ts.map +1 -1
  456. package/dist/scan-activity.js +141 -56
  457. package/dist/scan-activity.js.map +1 -1
  458. package/dist/scan-archive-path.d.ts +2 -0
  459. package/dist/scan-archive-path.d.ts.map +1 -0
  460. package/dist/scan-archive-path.js +5 -0
  461. package/dist/scan-archive-path.js.map +1 -0
  462. package/dist/scan-comparison.d.ts +10 -5
  463. package/dist/scan-comparison.d.ts.map +1 -1
  464. package/dist/scan-comparison.js +66 -17
  465. package/dist/scan-comparison.js.map +1 -1
  466. package/dist/scan-dashboard.d.ts +7 -6
  467. package/dist/scan-dashboard.d.ts.map +1 -1
  468. package/dist/scan-dashboard.js +92 -43
  469. package/dist/scan-dashboard.js.map +1 -1
  470. package/dist/scan-executor.d.ts +10 -1
  471. package/dist/scan-executor.d.ts.map +1 -1
  472. package/dist/scan-executor.js +24 -2
  473. package/dist/scan-executor.js.map +1 -1
  474. package/dist/scan-history-renderer.d.ts +1 -0
  475. package/dist/scan-history-renderer.d.ts.map +1 -1
  476. package/dist/scan-history-renderer.js +34 -28
  477. package/dist/scan-history-renderer.js.map +1 -1
  478. package/dist/scan-logs.d.ts +12 -0
  479. package/dist/scan-logs.d.ts.map +1 -1
  480. package/dist/scan-logs.js +131 -78
  481. package/dist/scan-logs.js.map +1 -1
  482. package/dist/scan-measurement.d.ts +26 -0
  483. package/dist/scan-measurement.d.ts.map +1 -0
  484. package/dist/scan-measurement.js +77 -0
  485. package/dist/scan-measurement.js.map +1 -0
  486. package/dist/scan-progress.d.ts +1 -0
  487. package/dist/scan-progress.d.ts.map +1 -1
  488. package/dist/scan-progress.js +3 -0
  489. package/dist/scan-progress.js.map +1 -1
  490. package/dist/scan-sessions.d.ts.map +1 -1
  491. package/dist/scan-sessions.js +4 -1
  492. package/dist/scan-sessions.js.map +1 -1
  493. package/dist/scan-settings.d.ts +1 -1
  494. package/dist/scan-settings.d.ts.map +1 -1
  495. package/dist/scan-settings.js +1 -24
  496. package/dist/scan-settings.js.map +1 -1
  497. package/dist/scanner-import.d.ts +25 -13
  498. package/dist/scanner-import.d.ts.map +1 -1
  499. package/dist/scanner-import.js +216 -97
  500. package/dist/scanner-import.js.map +1 -1
  501. package/dist/scanner-repository-url.d.ts +4 -1
  502. package/dist/scanner-repository-url.d.ts.map +1 -1
  503. package/dist/scanner-repository-url.js +10 -6
  504. package/dist/scanner-repository-url.js.map +1 -1
  505. package/dist/security-policy.d.ts +1 -1
  506. package/dist/security-policy.d.ts.map +1 -1
  507. package/dist/security-policy.js +26 -6
  508. package/dist/security-policy.js.map +1 -1
  509. package/dist/semgrep-findings.d.ts +6 -3
  510. package/dist/semgrep-findings.d.ts.map +1 -1
  511. package/dist/semgrep-findings.js +72 -42
  512. package/dist/semgrep-findings.js.map +1 -1
  513. package/dist/semgrep-guardian-findings.d.ts +38 -0
  514. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  515. package/dist/semgrep-guardian-findings.js +165 -0
  516. package/dist/semgrep-guardian-findings.js.map +1 -0
  517. package/dist/semgrep-platform-collector.d.ts +26 -0
  518. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  519. package/dist/semgrep-platform-collector.js +108 -0
  520. package/dist/semgrep-platform-collector.js.map +1 -0
  521. package/dist/semgrep-platform-findings.d.ts +157 -6
  522. package/dist/semgrep-platform-findings.d.ts.map +1 -1
  523. package/dist/semgrep-platform-findings.js +766 -103
  524. package/dist/semgrep-platform-findings.js.map +1 -1
  525. package/dist/server/api.d.ts +1 -1
  526. package/dist/server/api.d.ts.map +1 -1
  527. package/dist/server/api.js.map +1 -1
  528. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  529. package/dist/server/embedding-tokenizer.d.ts +2 -0
  530. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  531. package/dist/server/embedding-tokenizer.js +322 -0
  532. package/dist/server/embedding-tokenizer.js.map +6 -0
  533. package/dist/server/embeddings.d.ts +16 -2
  534. package/dist/server/embeddings.d.ts.map +1 -1
  535. package/dist/server/embeddings.js +35 -5
  536. package/dist/server/embeddings.js.map +1 -1
  537. package/dist/session-lines.d.ts +5 -0
  538. package/dist/session-lines.d.ts.map +1 -0
  539. package/dist/session-lines.js +60 -0
  540. package/dist/session-lines.js.map +1 -0
  541. package/dist/severity-review.d.ts +3 -1
  542. package/dist/severity-review.d.ts.map +1 -1
  543. package/dist/severity-review.js +3 -2
  544. package/dist/severity-review.js.map +1 -1
  545. package/dist/skill-authentication.d.ts +1 -0
  546. package/dist/skill-authentication.d.ts.map +1 -1
  547. package/dist/skill-authentication.js +1 -0
  548. package/dist/skill-authentication.js.map +1 -1
  549. package/dist/snyk-findings.d.ts +9 -2
  550. package/dist/snyk-findings.d.ts.map +1 -1
  551. package/dist/snyk-findings.js +90 -70
  552. package/dist/snyk-findings.js.map +1 -1
  553. package/dist/snyk-rest-findings.d.ts +59 -0
  554. package/dist/snyk-rest-findings.d.ts.map +1 -0
  555. package/dist/snyk-rest-findings.js +879 -0
  556. package/dist/snyk-rest-findings.js.map +1 -0
  557. package/dist/snyk-token-origin.d.ts +4 -0
  558. package/dist/snyk-token-origin.d.ts.map +1 -0
  559. package/dist/snyk-token-origin.js +82 -0
  560. package/dist/snyk-token-origin.js.map +1 -0
  561. package/dist/sonar-collector.d.ts.map +1 -1
  562. package/dist/sonar-collector.js +0 -3
  563. package/dist/sonar-collector.js.map +1 -1
  564. package/dist/sonar-findings.d.ts +1 -1
  565. package/dist/sonar-findings.d.ts.map +1 -1
  566. package/dist/sonar-findings.js +2 -4
  567. package/dist/sonar-findings.js.map +1 -1
  568. package/dist/sonar-import.d.ts +3 -0
  569. package/dist/sonar-import.d.ts.map +1 -1
  570. package/dist/sonar-import.js +30 -34
  571. package/dist/sonar-import.js.map +1 -1
  572. package/dist/stored-finding-projection.d.ts +6 -0
  573. package/dist/stored-finding-projection.d.ts.map +1 -0
  574. package/dist/stored-finding-projection.js +104 -0
  575. package/dist/stored-finding-projection.js.map +1 -0
  576. package/dist/stored-findings-publication.d.ts +23 -0
  577. package/dist/stored-findings-publication.d.ts.map +1 -0
  578. package/dist/stored-findings-publication.js +169 -0
  579. package/dist/stored-findings-publication.js.map +1 -0
  580. package/dist/target-drift.d.ts +9 -0
  581. package/dist/target-drift.d.ts.map +1 -0
  582. package/dist/target-drift.js +27 -0
  583. package/dist/target-drift.js.map +1 -0
  584. package/dist/targets.d.ts +8 -1
  585. package/dist/targets.d.ts.map +1 -1
  586. package/dist/targets.js +131 -42
  587. package/dist/targets.js.map +1 -1
  588. package/dist/tenable-findings.d.ts +6 -0
  589. package/dist/tenable-findings.d.ts.map +1 -0
  590. package/dist/tenable-findings.js +122 -0
  591. package/dist/tenable-findings.js.map +1 -0
  592. package/dist/terminal-stream.d.ts +13 -0
  593. package/dist/terminal-stream.d.ts.map +1 -0
  594. package/dist/terminal-stream.js +35 -0
  595. package/dist/terminal-stream.js.map +1 -0
  596. package/dist/trivy-findings.d.ts +19 -0
  597. package/dist/trivy-findings.d.ts.map +1 -0
  598. package/dist/trivy-findings.js +424 -0
  599. package/dist/trivy-findings.js.map +1 -0
  600. package/dist/trivy-import.d.ts +19 -0
  601. package/dist/trivy-import.d.ts.map +1 -0
  602. package/dist/trivy-import.js +151 -0
  603. package/dist/trivy-import.js.map +1 -0
  604. package/dist/trusted-executable.d.ts +6 -0
  605. package/dist/trusted-executable.d.ts.map +1 -1
  606. package/dist/trusted-executable.js +140 -37
  607. package/dist/trusted-executable.js.map +1 -1
  608. package/dist/validation-records.js +1 -1
  609. package/dist/validation-records.js.map +1 -1
  610. package/dist/veracode-findings.d.ts +1 -1
  611. package/dist/veracode-findings.d.ts.map +1 -1
  612. package/dist/veracode-findings.js +19 -6
  613. package/dist/veracode-findings.js.map +1 -1
  614. package/dist/version.d.ts +3 -1
  615. package/dist/version.d.ts.map +1 -1
  616. package/dist/version.js +184 -32
  617. package/dist/version.js.map +1 -1
  618. package/dist/vertex-pricing.d.ts +8 -0
  619. package/dist/vertex-pricing.d.ts.map +1 -0
  620. package/dist/vertex-pricing.js +20 -0
  621. package/dist/vertex-pricing.js.map +1 -0
  622. package/dist/windows-path.d.ts +1 -0
  623. package/dist/windows-path.d.ts.map +1 -1
  624. package/dist/windows-path.js +26 -1
  625. package/dist/windows-path.js.map +1 -1
  626. package/dist/wiz-findings.d.ts +6 -2
  627. package/dist/wiz-findings.d.ts.map +1 -1
  628. package/dist/wiz-findings.js +65 -89
  629. package/dist/wiz-findings.js.map +1 -1
  630. package/docs/classify-severity-records.md +27 -12
  631. package/docs/cli.md +853 -639
  632. package/docs/dedupe-records.md +44 -24
  633. package/docs/findings-service.md +84 -44
  634. package/docs/hosted-remediation.md +27 -11
  635. package/docs/hosted-scans.md +50 -42
  636. package/docs/sdk.md +903 -0
  637. package/docs/telemetry.md +236 -0
  638. package/docs/validate-records.md +78 -44
  639. package/package.json +23 -16
  640. package/schemas/external-findings.schema.json +4 -1
  641. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  642. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  643. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  644. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  645. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  646. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  647. package/dist/external-imports-feature.d.ts +0 -6
  648. package/dist/external-imports-feature.d.ts.map +0 -1
  649. package/dist/external-imports-feature.js +0 -51
  650. package/dist/external-imports-feature.js.map +0 -1
  651. package/dist/finding-normalization.d.ts +0 -5
  652. package/dist/finding-normalization.d.ts.map +0 -1
  653. package/dist/finding-normalization.js +0 -155
  654. package/dist/finding-normalization.js.map +0 -1
  655. package/dist/reader-selection.d.ts +0 -13
  656. package/dist/reader-selection.d.ts.map +0 -1
  657. package/dist/reader-selection.js +0 -81
  658. package/dist/reader-selection.js.map +0 -1
@@ -5,7 +5,6 @@ from __future__ import annotations
5
5
  import argparse
6
6
  import json
7
7
  import os
8
- import shutil
9
8
  import sqlite3
10
9
  import sys
11
10
  import uuid
@@ -16,10 +15,17 @@ from typing import Any
16
15
  sys.path.insert(0, str(Path(__file__).resolve().parent))
17
16
  import workbench_saved_results as saved_results
18
17
  from deep_scan_config import resolve_deep_scan_setup
19
- from workbench.handoff import require_current_continuation
20
- from workbench.storage import create_private_directory
18
+ from workbench.handoff import require_current_continuation, require_tokenless_scan_owner
19
+ from workbench.storage import (
20
+ archived_deep_path,
21
+ create_private_directory,
22
+ saved_deep_workers,
23
+ worker_usage_directory,
24
+ )
25
+ from workbench_constants import PHASES
21
26
  from workbench_source_scopes import capture_source_scopes
22
27
  from workbench_target import directory_snapshot_regular_file_count
28
+ from workbench_target_state import require_scan_checkout_owner
23
29
  from workbench_validation import optional_text, require_uuid, user_context_argument
24
30
 
25
31
  DEEP_SCAN_COORDINATOR_LEASE_SECONDS = 30
@@ -42,6 +48,7 @@ def dependencies() -> Any:
42
48
 
43
49
 
44
50
  def deep_scan_error(run: sqlite3.Row) -> str | None:
51
+ """Return recorded error messages, publication error first, or None if both are absent."""
45
52
  original = run["error_message"]
46
53
  publication = run["publication_error_message"]
47
54
  if not isinstance(publication, str):
@@ -68,6 +75,7 @@ def require_deep_scan_run(connection: sqlite3.Connection, scan_id: str) -> sqlit
68
75
 
69
76
 
70
77
  def deep_scan_deadline_reached(run: sqlite3.Row) -> bool:
78
+ """Return whether the time since run creation has reached its configured limit in hours."""
71
79
  elapsed = _parse_timestamp(dependencies().now()) - _parse_timestamp(str(run["created_at"]))
72
80
  return elapsed.total_seconds() / 3600 >= run["max_time_hours"]
73
81
 
@@ -75,6 +83,11 @@ def deep_scan_deadline_reached(run: sqlite3.Row) -> bool:
75
83
  def require_deep_scan_ready_for_parent_completion(
76
84
  connection: sqlite3.Connection, scan: sqlite3.Row
77
85
  ) -> None:
86
+ """Require a succeeded discovery run with a saved manifest before a Deep Scan completes.
87
+
88
+ For a capped run, also verify its workers have finished. Raise SystemExit
89
+ when a completion requirement fails. Other scan modes can complete directly.
90
+ """
78
91
  if scan["mode"] != "deep":
79
92
  return
80
93
  run = connection.execute(
@@ -169,6 +182,7 @@ def require_deep_scan_workers_finished(
169
182
  def require_owned_scan(
170
183
  connection: sqlite3.Connection, scan_id: str, thread_id: str
171
184
  ) -> tuple[sqlite3.Row, sqlite3.Row]:
185
+ """Return the scan and workspace rows or raise SystemExit unless thread_id matches the recorded owner."""
172
186
  scan = dependencies().require_scan(connection, scan_id)
173
187
  workspace = dependencies().require_workspace(connection, scan["workspace_id"])
174
188
  owner = optional_text(thread_id, maximum=512)
@@ -187,6 +201,7 @@ def deep_scan_path(
187
201
  *,
188
202
  kind: str,
189
203
  ) -> str:
204
+ """Return the canonical absolute path to an existing scan-local file or directory of the requested kind."""
190
205
  supplied = Path(value).expanduser()
191
206
  if not supplied.is_absolute():
192
207
  raise SystemExit(f"{label} must be an absolute path inside the scan directory.")
@@ -206,6 +221,7 @@ def deep_scan_path(
206
221
 
207
222
 
208
223
  def deep_scan_output_path(scan: sqlite3.Row, value: str, label: str) -> str:
224
+ """Validate an absolute output path under the scan directory, allowing a new file under an existing parent."""
209
225
  supplied = Path(value).expanduser()
210
226
  if not supplied.is_absolute():
211
227
  raise SystemExit(f"{label} must be an absolute path inside the scan directory.")
@@ -219,6 +235,7 @@ def deep_scan_output_path(scan: sqlite3.Row, value: str, label: str) -> str:
219
235
 
220
236
 
221
237
  def promote_staged_file(staged_path: str, output_path: str) -> tuple[Path, Path, Path | None]:
238
+ """Publish the staged file and return the paths needed to finalize or undo the move."""
222
239
  staged = Path(staged_path)
223
240
  output = Path(output_path)
224
241
  if staged == output:
@@ -236,6 +253,7 @@ def promote_staged_file(staged_path: str, output_path: str) -> tuple[Path, Path,
236
253
 
237
254
 
238
255
  def rollback_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:
256
+ """Move the published file back to staging and restore the previous output if present."""
239
257
  staged, output, backup = promotion
240
258
  if output.exists():
241
259
  os.replace(output, staged)
@@ -244,19 +262,14 @@ def rollback_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:
244
262
 
245
263
 
246
264
  def finish_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:
265
+ """Remove the previous output saved during promotion."""
247
266
  backup = promotion[2]
248
267
  if backup is not None:
249
268
  backup.unlink(missing_ok=True)
250
269
 
251
270
 
252
- def create_publication_copy(source: str | Path, destination: str | Path) -> None:
253
- try:
254
- os.link(source, destination)
255
- except OSError:
256
- shutil.copy2(source, destination)
257
-
258
-
259
271
  def publication_matches_snapshot(publication: Path, snapshot: Path) -> bool:
272
+ """Return whether the publication and snapshot identify the same file or contain identical bytes."""
260
273
  try:
261
274
  if publication.samefile(snapshot):
262
275
  return True
@@ -286,17 +299,14 @@ def canonical_discovery_artifacts(scan: sqlite3.Row) -> dict[str, str]:
286
299
 
287
300
 
288
301
  def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, Any]:
302
+ """Return persisted orchestration state including settings, workers, artifacts, and deduplication inputs.
303
+
304
+ Order workers by creation time and ID. Retain the recorded order of each
305
+ deduplication worker’s discovery inputs.
306
+ """
289
307
  run = require_deep_scan_run(connection, scan_id)
290
308
  scan = dependencies().require_scan(connection, run["scan_id"])
291
- worker_rows = connection.execute(
292
- """
293
- SELECT *
294
- FROM deep_scan_workers
295
- WHERE scan_id = ?
296
- ORDER BY created_at, id
297
- """,
298
- (run["scan_id"],),
299
- )
309
+ worker_rows = saved_deep_workers(connection, scan)
300
310
  input_rows = connection.execute(
301
311
  """
302
312
  SELECT dedup_worker_id, discovery_worker_id, input_order
@@ -306,12 +316,13 @@ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, A
306
316
  """,
307
317
  (run["scan_id"],),
308
318
  )
319
+ manifest_path = archived_deep_path(Path(scan["scan_dir"]), run["manifest_path"])
309
320
  canonical_artifacts = None
310
321
  if (
311
322
  run["canonical_inventory_path"] is None
312
323
  and run["status"] == "succeeded"
313
- and run["manifest_path"] is not None
314
- and run["manifest_path"] != str(Path(scan["scan_dir"]) / "scan-manifest.json")
324
+ and manifest_path is not None
325
+ and manifest_path != str(Path(scan["scan_dir"]) / "scan-manifest.json")
315
326
  and (Path(scan["scan_dir"]) / "artifacts" / "02_discovery" / "in_scope_files.txt").exists()
316
327
  ):
317
328
  canonical_artifacts = canonical_discovery_artifacts(scan)
@@ -341,11 +352,17 @@ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, A
341
352
  else scan["user_context"]
342
353
  ),
343
354
  "scanDir": scan["scan_dir"],
355
+ "workerUsageDirectory": str(worker_usage_directory(run["scan_id"])),
344
356
  "schemaVersion": run["schema_version"],
345
357
  "workflowVersion": run["workflow_version"],
346
358
  "coordinatorGeneration": run["coordinator_generation"],
347
359
  "status": run["status"],
348
360
  "phase": run["phase"],
361
+ # Older coordinators could persist discovery on the parent before dispatching.
362
+ "discoveryStarted": (
363
+ PHASES.index(scan["phase"]) >= PHASES.index("discovery")
364
+ or run["phase"] in {"discovery", "reducing"}
365
+ ),
349
366
  "config": {
350
367
  "workers": run["workers"],
351
368
  "subagents": run["subagents"],
@@ -360,7 +377,7 @@ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, A
360
377
  "consecutiveErrors": run["consecutive_errors"],
361
378
  "cancelRequested": bool(run["cancel_requested"]),
362
379
  "canonicalArtifacts": canonical_artifacts,
363
- "manifestPath": run["manifest_path"],
380
+ "manifestPath": manifest_path,
364
381
  "terminalReason": run["terminal_reason"],
365
382
  "error": deep_scan_error(run),
366
383
  "createdAt": run["created_at"],
@@ -379,8 +396,9 @@ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, A
379
396
 
380
397
 
381
398
  def independent_review_progress(
382
- connection: sqlite3.Connection, scan_id: str
399
+ connection: sqlite3.Connection, scan_id: str, *, parent_running: bool
383
400
  ) -> dict[str, int | str] | None:
401
+ """Return completed and allowed review counts and the consolidation state, or None for a missing run."""
384
402
  run = connection.execute(
385
403
  """
386
404
  SELECT completion_sequence, phase, updated_at, max_discovery_runs
@@ -391,21 +409,21 @@ def independent_review_progress(
391
409
  ).fetchone()
392
410
  if run is None:
393
411
  return None
394
- active = connection.execute(
412
+ active, buffered = connection.execute(
395
413
  """
396
- SELECT COUNT(*)
414
+ SELECT COUNT(*) FILTER (WHERE status IN ('queued', 'running')),
415
+ COUNT(*) FILTER (WHERE status = 'succeeded' AND merge_state = 'buffered')
397
416
  FROM deep_scan_workers
398
- WHERE scan_id = ?
399
- AND kind = 'discovery'
400
- AND status IN ('queued', 'running')
417
+ WHERE scan_id = ? AND kind = 'discovery'
401
418
  """,
402
419
  (scan_id,),
403
- ).fetchone()[0]
420
+ ).fetchone()
421
+ consolidating = run["phase"] in {"reducing", "terminal"} or (active == 0 and buffered > 0)
404
422
  return {
405
423
  "active": int(active),
406
424
  "completed": int(run["completion_sequence"]),
407
425
  "maximum": int(run["max_discovery_runs"]),
408
- "consolidating": run["phase"] in {"reducing", "terminal"},
426
+ "consolidating": parent_running and consolidating,
409
427
  "updatedAt": str(run["updated_at"]),
410
428
  }
411
429
 
@@ -445,10 +463,10 @@ def deep_scan_result(
445
463
  def effective_deep_scan_config(
446
464
  args: argparse.Namespace, workspace: sqlite3.Row | None = None
447
465
  ) -> dict[str, Any]:
466
+ """Use persisted workspace settings when available, otherwise resolve the current launch configuration."""
448
467
  if workspace is not None and workspace["deep_scan_config_json"] is not None:
449
468
  return json.loads(workspace["deep_scan_config_json"])
450
- available_parallelism = args.available_parallelism or os.cpu_count() or 1
451
- return resolve_deep_scan_setup(available_parallelism, args.deep_scan_project_json)
469
+ return resolve_deep_scan_setup(project_json=args.deep_scan_project_json)
452
470
 
453
471
 
454
472
  def ensure_deep_scan_run(
@@ -461,6 +479,7 @@ def ensure_deep_scan_run(
461
479
  service_tier: str | None,
462
480
  pending_target_project_path: str | None = None,
463
481
  ) -> sqlite3.Row:
482
+ """Return the existing orchestration row or initialize one for a running Deep Scan with the supplied settings."""
464
483
  existing = connection.execute(
465
484
  "SELECT * FROM deep_scan_runs WHERE scan_id = ?", (scan["id"],)
466
485
  ).fetchone()
@@ -506,7 +525,7 @@ def existing_deep_scan_for_target(
506
525
  SELECT scans.*
507
526
  FROM scans
508
527
  JOIN workspaces ON workspaces.id = scans.workspace_id
509
- WHERE workspaces.thread_id = ?
528
+ WHERE (workspaces.thread_id = ? OR workspaces.thread_id IS NULL)
510
529
  AND COALESCE(scans.deep_scan_owner_thread_id, workspaces.thread_id) = ?
511
530
  AND scans.target_path = ?
512
531
  AND scans.scope = ?
@@ -558,6 +577,7 @@ def terminal_deep_scan_for_target_snapshot(
558
577
  AND scans.target_inode = ?
559
578
  AND scans.handoff_status = 'delivered'
560
579
  AND scans.handoff_claim_token IS NULL
580
+ AND scans.continuation_thread_id IS NULL
561
581
  AND workspaces.active_scan_id = scans.id
562
582
  AND deep_scan_runs.status = 'succeeded'
563
583
  AND deep_scan_runs.phase = 'terminal'
@@ -592,11 +612,16 @@ def begin_deep_scan_for_scan(
592
612
  ) -> dict[str, Any]:
593
613
  scan_id = require_uuid(scan_id, "scan-id")
594
614
  candidate = dependencies().require_scan(connection, scan_id)
615
+ require_scan_checkout_owner(connection, candidate)
616
+ model_thread_id = getattr(args, "model_thread_id", None)
617
+ require_tokenless_scan_owner(connection, candidate, model_thread_id)
595
618
  workspace = dependencies().require_workspace(connection, candidate["workspace_id"])
596
619
  if (
597
620
  candidate["mode"] == "deep"
598
621
  and candidate["status"] == "running"
599
- and candidate["recipe_json"] is not None
622
+ and (
623
+ candidate["recipe_json"] is not None or candidate["continuation_thread_id"] == thread_id
624
+ )
600
625
  and candidate["handoff_status"] == "delivered"
601
626
  and candidate["deep_scan_owner_thread_id"] is None
602
627
  and workspace["thread_id"] is None
@@ -608,18 +633,33 @@ def begin_deep_scan_for_scan(
608
633
  )
609
634
  timestamp = dependencies().now()
610
635
  with connection:
611
- claimed_workspace = connection.execute(
612
- "UPDATE workspaces SET thread_id = ?, updated_at = ? "
613
- "WHERE id = ? AND thread_id IS NULL",
614
- (thread_id, timestamp, workspace["id"]),
615
- )
636
+ # Legacy scans can share a workspace. Only registered scans claim the workspace.
637
+ if candidate["recipe_json"] is not None:
638
+ claimed_workspace = connection.execute(
639
+ "UPDATE workspaces SET thread_id = ?, updated_at = ? "
640
+ "WHERE id = ? AND thread_id IS NULL",
641
+ (thread_id, timestamp, workspace["id"]),
642
+ )
643
+ if claimed_workspace.rowcount != 1:
644
+ raise SystemExit(
645
+ "A scan can only be orchestrated from its owning Codex thread."
646
+ )
616
647
  claimed_scan = connection.execute(
617
648
  "UPDATE scans SET deep_scan_owner_thread_id = ?, updated_at = ? "
618
649
  "WHERE id = ? AND deep_scan_owner_thread_id IS NULL "
619
- "AND handoff_status = 'delivered' AND handoff_claim_token IS ?",
620
- (thread_id, timestamp, scan_id, candidate["handoff_claim_token"]),
650
+ "AND handoff_status = 'delivered' AND handoff_claim_token IS ? "
651
+ "AND (continuation_thread_id = ? OR (recipe_json IS NOT NULL AND "
652
+ "(handoff_claim_token IS NOT NULL OR (? IS NULL AND continuation_thread_id IS NULL))))",
653
+ (
654
+ thread_id,
655
+ timestamp,
656
+ scan_id,
657
+ candidate["handoff_claim_token"],
658
+ thread_id,
659
+ model_thread_id,
660
+ ),
621
661
  )
622
- if claimed_workspace.rowcount != 1 or claimed_scan.rowcount != 1:
662
+ if claimed_scan.rowcount != 1:
623
663
  raise SystemExit("A scan can only be orchestrated from its owning Codex thread.")
624
664
  scan, _ = require_owned_scan(connection, scan_id, thread_id)
625
665
  require_current_continuation(
@@ -657,6 +697,7 @@ def begin_deep_scan_for_scan(
657
697
  connection.execute("BEGIN IMMEDIATE")
658
698
  with connection:
659
699
  scan, _ = require_owned_scan(connection, scan_id, thread_id)
700
+ require_scan_checkout_owner(connection, scan)
660
701
  require_current_continuation(
661
702
  scan,
662
703
  args.claim_token,
@@ -704,7 +745,8 @@ def begin_deep_scan_for_target(
704
745
  AND (deep_scan_runs.pending_target_project_path IS NULL
705
746
  OR deep_scan_runs.pending_target_project_path = ?)
706
747
  AND scans.recipe_json IS NULL
707
- AND scans.handoff_claim_token IS NULL AND deep_scan_runs.status = 'succeeded'
748
+ AND scans.handoff_claim_token IS NULL AND scans.continuation_thread_id IS NULL
749
+ AND deep_scan_runs.status = 'succeeded'
708
750
  AND deep_scan_runs.discovery_user_context_json = ?
709
751
  LIMIT 1
710
752
  """,
@@ -722,6 +764,7 @@ def begin_deep_scan_for_target(
722
764
  with connection:
723
765
  existing = existing_deep_scan_for_target(connection, thread_id, target_path, scope)
724
766
  if existing is not None:
767
+ require_scan_checkout_owner(connection, existing)
725
768
  connection.commit()
726
769
  return begin_deep_scan_for_scan(connection, existing["id"], thread_id, args)
727
770
  current_target = dependencies().require_remediation_target(target_path)
@@ -746,6 +789,7 @@ def begin_deep_scan_for_target(
746
789
  target_inode,
747
790
  )
748
791
  if terminal is not None:
792
+ require_scan_checkout_owner(connection, terminal)
749
793
  connection.commit()
750
794
  return deep_scan_result(
751
795
  connection,
@@ -764,17 +808,15 @@ def begin_deep_scan_for_target(
764
808
  workflow_version = optional_text(args.workflow_version, maximum=256)
765
809
  if workflow_version is None:
766
810
  raise SystemExit("workflow-version is required.")
767
- root = dependencies().resolve_scan_root(args.scan_root)
768
- target_root = (root / dependencies().safe_segment(target.name)).resolve()
769
- if target_root == target or target in target_root.parents:
770
- raise SystemExit("The scan artifact directory must be outside the selected target.")
771
- create_private_directory(target_root)
811
+ target_root = dependencies().scan_target_root(args.scan_root, target)
812
+ create_private_directory(target_root, scan_output=True)
772
813
  model = optional_text(args.model, maximum=200)
773
814
  reasoning_effort = optional_text(args.reasoning_effort, maximum=32)
774
815
  workspace_id = str(uuid.uuid4())
775
816
  scan_id = str(uuid.uuid4())
776
817
  timestamp = dependencies().now()
777
- target_id = dependencies().ensure_security_target(connection, target_path)
818
+ registration = dependencies().register_security_target(connection, target_path)
819
+ target_id = registration.target_id
778
820
  connection.execute(
779
821
  """
780
822
  INSERT INTO workspaces (
@@ -806,6 +848,7 @@ def begin_deep_scan_for_target(
806
848
  scope=scope,
807
849
  diff_target=None,
808
850
  target_identity=target_identity,
851
+ repository_generation=registration.repository_generation,
809
852
  source_scopes=source_scopes,
810
853
  target_root=target_root,
811
854
  target_summary=None,
@@ -829,6 +872,7 @@ def begin_deep_scan_for_target(
829
872
 
830
873
 
831
874
  def begin_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
875
+ """Begin orchestration for a registered scan or a target, returning the scan state and its start disposition."""
832
876
  thread_id = optional_text(args.thread_id, maximum=512)
833
877
  if thread_id is None:
834
878
  raise SystemExit("thread-id is required.")
@@ -842,6 +886,7 @@ def begin_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) ->
842
886
 
843
887
 
844
888
  def get_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
889
+ """Return the persisted orchestration result to the thread that owns the scan."""
845
890
  scan, _ = require_owned_scan(connection, args.scan_id, args.thread_id)
846
891
  return deep_scan_result(connection, scan["id"])
847
892
 
@@ -870,6 +915,7 @@ def coordinator_lease_is_live(
870
915
  scan: sqlite3.Row,
871
916
  timestamp: str,
872
917
  ) -> bool:
918
+ """Check coordinator freshness using the lease generation and its applicable activity timestamps."""
873
919
  if run["coordinator_generation"] == 1:
874
920
  active_worker = connection.execute(
875
921
  """
@@ -933,7 +979,8 @@ def claim_deep_scan_coordinator_locked(
933
979
  args.claim_token,
934
980
  error_message="Deep Scan orchestration is owned by another continuation.",
935
981
  )
936
- run, _ = require_running_deep_scan(connection, scan_id)
982
+ run = require_deep_scan_run(connection, scan_id)
983
+ require_running_deep_scan(run, scan)
937
984
  timestamp = dependencies().now()
938
985
  if args.coordinator_generation is not None:
939
986
  require_current_coordinator(run, args)
@@ -967,6 +1014,7 @@ def claim_deep_scan_coordinator_locked(
967
1014
  def recover_expired_coordinator(
968
1015
  connection: sqlite3.Connection, run: sqlite3.Row, timestamp: str
969
1016
  ) -> None:
1017
+ """Recover interrupted publications and reset active work so a replacement coordinator can resume."""
970
1018
  scan_id = run["scan_id"]
971
1019
  recover_candidate_ledger_publication(connection, scan_id)
972
1020
  legacy_generation = int(run["coordinator_generation"] == 1)
@@ -1042,6 +1090,7 @@ def recover_expired_coordinator(
1042
1090
 
1043
1091
 
1044
1092
  def recover_candidate_ledger_publication(connection: sqlite3.Connection, scan_id: str) -> None:
1093
+ """Reconcile ledger backups with reducer snapshots after an interrupted publication."""
1045
1094
  scan = dependencies().require_scan(connection, scan_id)
1046
1095
  ledger = Path(scan["scan_dir"]) / "artifacts" / "02_discovery" / "candidate_ledger.jsonl"
1047
1096
  backups = sorted(
@@ -1079,26 +1128,11 @@ def recover_candidate_ledger_publication(connection: sqlite3.Connection, scan_id
1079
1128
  return
1080
1129
 
1081
1130
 
1082
- def require_deep_scan_worker(connection: sqlite3.Connection, worker_id: str) -> sqlite3.Row:
1083
- worker_id = require_uuid(worker_id, "worker-id")
1084
- row = connection.execute(
1085
- "SELECT * FROM deep_scan_workers WHERE id = ?", (worker_id,)
1086
- ).fetchone()
1087
- if row is None:
1088
- raise SystemExit("Codex Security Deep Scan worker not found.")
1089
- return row
1090
-
1091
-
1092
- def require_running_deep_scan(
1093
- connection: sqlite3.Connection, scan_id: str
1094
- ) -> tuple[sqlite3.Row, sqlite3.Row]:
1095
- run = require_deep_scan_run(connection, scan_id)
1096
- scan = dependencies().require_scan(connection, run["scan_id"])
1131
+ def require_running_deep_scan(run: sqlite3.Row, scan: sqlite3.Row) -> None:
1097
1132
  if run["status"] != "running" or run["cancel_requested"]:
1098
1133
  raise SystemExit("Only a running Deep Scan can update orchestration state.")
1099
1134
  if scan["status"] != "running" or scan["canceled_at"] is not None:
1100
1135
  raise SystemExit("Only a running scan can update Deep Scan orchestration state.")
1101
- return run, scan
1102
1136
 
1103
1137
 
1104
1138
  def require_worker_transition(current: str, requested: str) -> None:
@@ -1126,6 +1160,12 @@ def upsert_deep_scan_worker(
1126
1160
  existing = connection.execute(
1127
1161
  "SELECT * FROM deep_scan_workers WHERE id = ?", (worker_id,)
1128
1162
  ).fetchone()
1163
+ if args.terminal_failure and (
1164
+ args.status != "failed" or not optional_text(args.error_message)
1165
+ ):
1166
+ raise SystemExit(
1167
+ "A terminal worker failure requires failed status and an error message."
1168
+ )
1129
1169
  replaceable_failure_kind = args.replaceable_failure_kind
1130
1170
  if replaceable_failure_kind is not None and (
1131
1171
  args.kind != "discovery"
@@ -1150,7 +1190,7 @@ def upsert_deep_scan_worker(
1150
1190
  and args.status in {"succeeded", "failed", "canceled"}
1151
1191
  )
1152
1192
  if not cleanup_update and not terminal_repeat:
1153
- require_running_deep_scan(connection, scan_id)
1193
+ require_running_deep_scan(run, scan)
1154
1194
  prompt_path = deep_scan_path(scan, args.prompt_path, "Worker prompt path", kind="file")
1155
1195
  artifact_dir = deep_scan_path(
1156
1196
  scan, args.artifact_dir, "Worker artifact directory", kind="directory"
@@ -1168,7 +1208,9 @@ def upsert_deep_scan_worker(
1168
1208
  timestamp = dependencies().now()
1169
1209
  if existing is None:
1170
1210
  if args.kind == "dedup":
1171
- raise SystemExit("Create dedup workers with claim-deep-scan-dedup.")
1211
+ raise SystemExit(
1212
+ "Deep Scan checkpoints are recorded with record-deep-scan-iteration."
1213
+ )
1172
1214
  if args.status not in {"queued", "running"}:
1173
1215
  raise SystemExit("A new Deep Scan worker must be queued or running.")
1174
1216
  if (
@@ -1251,7 +1293,7 @@ def upsert_deep_scan_worker(
1251
1293
  if args.status == "running" and attempt < 1:
1252
1294
  raise SystemExit("A running Deep Scan worker attempt must be at least one.")
1253
1295
  if args.kind == "dedup" and args.status == "succeeded":
1254
- raise SystemExit("Commit a successful dedup worker with commit-deep-scan-dedup.")
1296
+ raise SystemExit("Deep Scan checkpoints are recorded with record-deep-scan-iteration.")
1255
1297
  if args.kind == "discovery" and args.status == "succeeded" and result_manifest_path is None:
1256
1298
  result_manifest_path = existing["result_manifest_path"]
1257
1299
  if result_manifest_path is None:
@@ -1316,11 +1358,14 @@ def upsert_deep_scan_worker(
1316
1358
  if error_message is None and args.status != "succeeded":
1317
1359
  error_message = existing["error_message"]
1318
1360
  started_at = existing["started_at"] or (timestamp if args.status == "running" else None)
1361
+ thread_id = optional_text(args.sdk_thread_id, maximum=512)
1362
+ if thread_id is None and attempt == existing["attempt"]:
1363
+ thread_id = existing["sdk_thread_id"]
1319
1364
  connection.execute(
1320
1365
  """
1321
1366
  UPDATE deep_scan_workers
1322
1367
  SET status = ?, result_manifest_path = ?, attempt = ?,
1323
- sdk_thread_id = COALESCE(?, sdk_thread_id),
1368
+ sdk_thread_id = ?,
1324
1369
  completion_sequence = ?, merge_state = ?,
1325
1370
  error_message = ?,
1326
1371
  started_at = ?, completed_at = ?, updated_at = ?
@@ -1330,7 +1375,7 @@ def upsert_deep_scan_worker(
1330
1375
  args.status,
1331
1376
  result_manifest_path or existing["result_manifest_path"],
1332
1377
  attempt,
1333
- optional_text(args.sdk_thread_id, maximum=512),
1378
+ thread_id,
1334
1379
  completion_sequence,
1335
1380
  merge_state,
1336
1381
  error_message,
@@ -1340,275 +1385,81 @@ def upsert_deep_scan_worker(
1340
1385
  worker_id,
1341
1386
  ),
1342
1387
  )
1388
+ if args.terminal_failure:
1389
+ # Persist the first terminal cause with its worker. An adopting coordinator
1390
+ # completes the normal failure path after active workers have settled.
1391
+ connection.execute(
1392
+ "UPDATE deep_scan_runs SET error_message = ? WHERE scan_id = ? AND error_message IS NULL",
1393
+ (error_message, scan_id),
1394
+ )
1343
1395
  return deep_scan_result(connection, scan_id)
1344
1396
 
1345
1397
 
1346
- def claim_deep_scan_dedup(
1398
+ def record_deep_scan_iteration(
1347
1399
  connection: sqlite3.Connection, args: argparse.Namespace
1348
1400
  ) -> dict[str, Any]:
1401
+ """Commit the checkpoint and its input workers in one transaction, then return deep scan state.
1402
+
1403
+ Repeating the same iteration and inputs replays the saved result. Conflicting
1404
+ checkpoint or input-worker IDs raise SystemExit.
1405
+ """
1349
1406
  scan_id = require_uuid(args.scan_id, "scan-id")
1350
- worker_id = require_uuid(args.worker_id, "worker-id")
1407
+ checkpoint_id = require_uuid(args.worker_id, "worker-id")
1351
1408
  input_ids = [require_uuid(value, "input-worker-id") for value in args.input_worker_id]
1352
- if len(set(input_ids)) != len(input_ids):
1353
- raise SystemExit("Dedup input worker IDs must be unique.")
1354
1409
  connection.execute("BEGIN IMMEDIATE")
1355
1410
  with connection:
1356
- run, scan = require_running_deep_scan(connection, scan_id)
1411
+ run = require_deep_scan_run(connection, scan_id)
1412
+ scan = dependencies().require_scan(connection, scan_id)
1413
+ require_running_deep_scan(run, scan)
1357
1414
  require_current_coordinator(run, args)
1358
- prompt_path = deep_scan_path(scan, args.prompt_path, "Dedup prompt path", kind="file")
1359
- artifact_dir = deep_scan_path(
1360
- scan, args.artifact_dir, "Dedup artifact directory", kind="directory"
1361
- )
1415
+ result = deep_scan_path(scan, args.result_manifest_path, "Iteration result", kind="file")
1362
1416
  existing = connection.execute(
1363
- "SELECT * FROM deep_scan_workers WHERE id = ?", (worker_id,)
1417
+ "SELECT scan_id, result_manifest_path FROM deep_scan_workers WHERE id = ?",
1418
+ (checkpoint_id,),
1364
1419
  ).fetchone()
1365
1420
  if existing is not None:
1366
- persisted_inputs = [
1367
- row["discovery_worker_id"]
1421
+ if existing["scan_id"] != scan_id or existing["result_manifest_path"] != result:
1422
+ raise SystemExit("Iteration already belongs to another result.")
1423
+ recorded_ids = [
1424
+ row[0]
1368
1425
  for row in connection.execute(
1369
- """
1370
- SELECT discovery_worker_id
1371
- FROM deep_scan_dedup_inputs
1372
- WHERE dedup_worker_id = ?
1373
- ORDER BY input_order
1374
- """,
1375
- (worker_id,),
1426
+ "SELECT discovery_worker_id FROM deep_scan_dedup_inputs WHERE dedup_worker_id = ? ORDER BY input_order",
1427
+ (checkpoint_id,),
1376
1428
  )
1377
1429
  ]
1378
- if (
1379
- existing["scan_id"] == scan_id
1380
- and existing["kind"] == "dedup"
1381
- and existing["prompt_path"] == prompt_path
1382
- and existing["artifact_dir"] == artifact_dir
1383
- and persisted_inputs == input_ids
1384
- ):
1385
- connection.commit()
1386
- return deep_scan_result(connection, scan_id)
1387
- raise SystemExit("Dedup worker ID is already used by a different reducer claim.")
1388
- active_reducer = connection.execute(
1389
- """
1390
- SELECT 1 FROM deep_scan_workers
1391
- WHERE scan_id = ? AND kind = 'dedup' AND status IN ('queued', 'running')
1392
- """,
1393
- (scan_id,),
1394
- ).fetchone()
1395
- if active_reducer is not None:
1396
- raise SystemExit("Only one Deep Scan dedup worker can run at a time.")
1397
- buffered_ids = [
1398
- row["id"]
1399
- for row in connection.execute(
1400
- """
1401
- SELECT id FROM deep_scan_workers
1402
- WHERE scan_id = ? AND kind = 'discovery'
1403
- AND status = 'succeeded' AND merge_state = 'buffered'
1404
- ORDER BY completion_sequence
1405
- """,
1406
- (scan_id,),
1407
- )
1408
- ]
1409
- if input_ids != buffered_ids[: len(input_ids)]:
1410
- raise SystemExit(
1411
- "A Deep Scan dedup worker must claim an ordered prefix of buffered discovery "
1412
- "results in completion order."
1413
- )
1414
- capped_singleton = (
1415
- len(input_ids) == 1
1416
- and (
1417
- run["discovery_runs_dispatched"] >= run["max_discovery_runs"]
1418
- or deep_scan_deadline_reached(run)
1419
- )
1420
- and connection.execute(
1421
- """
1422
- SELECT 1 FROM deep_scan_workers
1423
- WHERE scan_id = ? AND kind = 'discovery' AND status IN ('queued', 'running')
1424
- LIMIT 1
1425
- """,
1426
- (scan_id,),
1427
- ).fetchone()
1428
- is None
1429
- )
1430
- successful_reducer = connection.execute(
1431
- """
1432
- SELECT 1 FROM deep_scan_workers
1433
- WHERE scan_id = ? AND kind = 'dedup' AND status = 'succeeded'
1434
- LIMIT 1
1435
- """,
1436
- (scan_id,),
1437
- ).fetchone()
1438
- minimum_inputs = 1 if successful_reducer is not None or capped_singleton else 2
1439
- if len(input_ids) < minimum_inputs:
1440
- raise SystemExit(
1441
- "The first Deep Scan dedup requires two buffered discovery results."
1442
- if minimum_inputs == 2
1443
- else "A Deep Scan dedup requires at least one buffered discovery result."
1444
- )
1445
- timestamp = dependencies().now()
1446
- connection.execute(
1447
- """
1448
- INSERT INTO deep_scan_workers (
1449
- id, scan_id, kind, status, prompt_path, artifact_dir,
1450
- created_at, updated_at
1451
- ) VALUES (?, ?, 'dedup', 'queued', ?, ?, ?, ?)
1452
- """,
1453
- (worker_id, scan_id, prompt_path, artifact_dir, timestamp, timestamp),
1454
- )
1455
- for input_order, input_id in enumerate(input_ids):
1456
- connection.execute(
1457
- """
1458
- INSERT INTO deep_scan_dedup_inputs (
1459
- scan_id, dedup_worker_id, discovery_worker_id, input_order
1460
- ) VALUES (?, ?, ?, ?)
1461
- """,
1462
- (scan_id, worker_id, input_id, input_order),
1463
- )
1464
- connection.execute(
1465
- f"""
1466
- UPDATE deep_scan_workers
1467
- SET merge_state = 'merging', updated_at = ?
1468
- WHERE scan_id = ? AND id IN ({",".join("?" for _ in input_ids)})
1469
- """,
1470
- (timestamp, scan_id, *input_ids),
1471
- )
1472
- connection.execute(
1473
- "UPDATE deep_scan_runs SET phase = 'reducing', updated_at = ? WHERE scan_id = ?",
1474
- (timestamp, scan_id),
1475
- )
1430
+ if recorded_ids != input_ids:
1431
+ raise SystemExit("Iteration already belongs to other completed scans.")
1432
+ return deep_scan_result(connection, scan_id)
1433
+ now = dependencies().now()
1434
+ # Historical scans use the same rows to bind the selected aggregate at publication.
1476
1435
  connection.execute(
1477
- """
1478
- UPDATE scan_progress
1479
- SET deep_review_pass = COALESCE(deep_review_pass, 0) + 1, updated_at = ?
1480
- WHERE scan_id = ?
1481
- """,
1482
- (timestamp, scan_id),
1436
+ """INSERT INTO deep_scan_workers
1437
+ (id, scan_id, kind, status, prompt_path, artifact_dir, result_manifest_path,
1438
+ created_at, completed_at, updated_at)
1439
+ VALUES (?, ?, 'dedup', 'succeeded', ?, ?, ?, ?, ?, ?)""",
1440
+ (checkpoint_id, scan_id, result, str(Path(result).parent), result, now, now, now),
1483
1441
  )
1484
- return deep_scan_result(connection, scan_id)
1485
-
1486
-
1487
- def commit_deep_scan_dedup(
1488
- connection: sqlite3.Connection, args: argparse.Namespace
1489
- ) -> dict[str, Any]:
1490
- scan_id = require_uuid(args.scan_id, "scan-id")
1491
- with dependencies().scan_completion_lock(scan_id):
1492
- return commit_deep_scan_dedup_locked(connection, args, scan_id)
1493
-
1494
-
1495
- def commit_deep_scan_dedup_locked(
1496
- connection: sqlite3.Connection, args: argparse.Namespace, scan_id: str
1497
- ) -> dict[str, Any]:
1498
- worker_id = require_uuid(args.worker_id, "worker-id")
1499
- promotion: tuple[Path, Path, Path | None] | None = None
1500
- publication_copy: Path | None = None
1501
- connection.execute("BEGIN IMMEDIATE")
1502
- try:
1503
- run = require_deep_scan_run(connection, scan_id)
1504
- require_current_coordinator(run, args)
1505
- scan = dependencies().require_scan(connection, scan_id)
1506
- worker = require_deep_scan_worker(connection, worker_id)
1507
- if worker["scan_id"] != scan_id or worker["kind"] != "dedup":
1508
- raise SystemExit("Dedup worker does not belong to this Deep Scan.")
1509
- if worker["status"] == "succeeded":
1510
- connection.commit()
1511
- return deep_scan_result(connection, scan_id)
1512
- require_running_deep_scan(connection, scan_id)
1513
- if worker["status"] not in {"queued", "running"}:
1514
- raise SystemExit("Only an active dedup worker can commit a result.")
1515
- if args.candidate_ledger_path:
1516
- candidate_ledger_path = deep_scan_path(
1517
- scan,
1518
- args.candidate_ledger_path,
1519
- "Staged candidate ledger path",
1520
- kind="file",
1521
- )
1522
- discovery_dir = Path(scan["scan_dir"]) / "artifacts" / "02_discovery"
1523
- deep_scan_path(
1524
- scan,
1525
- str(discovery_dir / "in_scope_files.txt"),
1526
- "Canonical in-scope inventory path",
1527
- kind="file",
1442
+ for index, worker_id in enumerate(input_ids):
1443
+ updated = connection.execute(
1444
+ """UPDATE deep_scan_workers SET merge_state = 'merged', updated_at = ?
1445
+ WHERE scan_id = ? AND id = ? AND kind = 'discovery'
1446
+ AND status = 'succeeded' AND merge_state = 'buffered'""",
1447
+ (now, scan_id, worker_id),
1528
1448
  )
1529
- canonical_candidate_ledger_path = deep_scan_output_path(
1530
- scan,
1531
- str(discovery_dir / "candidate_ledger.jsonl"),
1532
- "Canonical candidate ledger path",
1533
- )
1534
- else:
1535
- candidate_ledger_path = None
1536
- canonical_candidate_ledger_path = None
1537
- result_manifest_path = deep_scan_path(
1538
- scan,
1539
- args.result_manifest_path,
1540
- "Dedup result manifest path",
1541
- kind="file",
1542
- )
1543
- inputs = list(
1449
+ if updated.rowcount != 1:
1450
+ raise SystemExit("Iteration input is not an unmerged completed scan.")
1544
1451
  connection.execute(
1545
- """
1546
- SELECT workers.*
1547
- FROM deep_scan_dedup_inputs AS inputs
1548
- JOIN deep_scan_workers AS workers ON workers.id = inputs.discovery_worker_id
1549
- WHERE inputs.dedup_worker_id = ?
1550
- ORDER BY inputs.input_order
1551
- """,
1552
- (worker_id,),
1452
+ "INSERT INTO deep_scan_dedup_inputs VALUES (?, ?, ?, ?)",
1453
+ (scan_id, checkpoint_id, worker_id, index),
1553
1454
  )
1554
- )
1555
- if not inputs or any(row["merge_state"] != "merging" for row in inputs):
1556
- raise SystemExit("Dedup inputs are not in the claimed merging state.")
1557
- if candidate_ledger_path and canonical_candidate_ledger_path:
1558
- canonical_path = Path(canonical_candidate_ledger_path)
1559
- publication_copy = canonical_path.with_name(
1560
- f".{canonical_path.name}.{uuid.uuid4()}.publish"
1561
- )
1562
- create_publication_copy(candidate_ledger_path, publication_copy)
1563
- promotion = promote_staged_file(
1564
- str(publication_copy),
1565
- canonical_candidate_ledger_path,
1566
- )
1567
- timestamp = dependencies().now()
1568
1455
  connection.execute(
1569
- """
1570
- UPDATE deep_scan_workers
1571
- SET merge_state = 'merged', updated_at = ?
1572
- WHERE id IN (
1573
- SELECT discovery_worker_id FROM deep_scan_dedup_inputs
1574
- WHERE dedup_worker_id = ?
1575
- )
1576
- """,
1577
- (timestamp, worker_id),
1456
+ "UPDATE deep_scan_runs SET phase = 'discovery', consecutive_no_new = ?, consecutive_errors = ?, updated_at = ? WHERE scan_id = ?",
1457
+ (args.no_new_streak, args.consecutive_errors, now, scan_id),
1578
1458
  )
1579
1459
  connection.execute(
1580
- """
1581
- UPDATE deep_scan_workers
1582
- SET status = 'succeeded', result_manifest_path = ?,
1583
- error_message = NULL, started_at = COALESCE(started_at, ?),
1584
- completed_at = ?, updated_at = ?
1585
- WHERE id = ?
1586
- """,
1587
- (result_manifest_path, timestamp, timestamp, timestamp, worker_id),
1460
+ "UPDATE scan_progress SET deep_review_pass = COALESCE(deep_review_pass, 0) + 1, updated_at = ? WHERE scan_id = ?",
1461
+ (now, scan_id),
1588
1462
  )
1589
- no_new_streak = (
1590
- 0 if args.new_findings_count > 0 else run["consecutive_no_new"] + len(inputs)
1591
- )
1592
- connection.execute(
1593
- """
1594
- UPDATE deep_scan_runs
1595
- SET phase = 'discovery', consecutive_no_new = ?, updated_at = ?
1596
- WHERE scan_id = ?
1597
- """,
1598
- (no_new_streak, timestamp, scan_id),
1599
- )
1600
- connection.commit()
1601
- except BaseException:
1602
- connection.rollback()
1603
- if promotion is not None:
1604
- rollback_staged_file(promotion)
1605
- if publication_copy is not None:
1606
- publication_copy.unlink(missing_ok=True)
1607
- raise
1608
- if promotion is not None:
1609
- finish_staged_file(promotion)
1610
- if publication_copy is not None:
1611
- publication_copy.unlink(missing_ok=True)
1612
1463
  return deep_scan_result(connection, scan_id)
1613
1464
 
1614
1465
 
@@ -1621,10 +1472,10 @@ def finish_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -
1621
1472
  def finish_deep_scan_locked(
1622
1473
  connection: sqlite3.Connection, args: argparse.Namespace, scan_id: str
1623
1474
  ) -> dict[str, Any]:
1624
- omitted_worker_ids = [
1475
+ omitted_worker_ids = {
1625
1476
  require_uuid(value, "omitted-worker-id") for value in args.omitted_worker_id
1626
- ]
1627
- if len(set(omitted_worker_ids)) != len(omitted_worker_ids):
1477
+ }
1478
+ if len(omitted_worker_ids) != len(args.omitted_worker_id):
1628
1479
  raise SystemExit("Omitted Deep Scan worker IDs must be unique.")
1629
1480
  promotion: tuple[Path, Path, Path | None] | None = None
1630
1481
  deadline_publication: (
@@ -1644,29 +1495,23 @@ def finish_deep_scan_locked(
1644
1495
  )
1645
1496
  standard_scan_manifest = manifest_path == str(Path(scan["scan_dir"]) / "scan-manifest.json")
1646
1497
 
1647
- buffered_worker_ids = [
1498
+ buffered_worker_ids = {
1648
1499
  row["id"]
1649
1500
  for row in connection.execute(
1650
1501
  """
1651
1502
  SELECT id
1652
1503
  FROM deep_scan_workers
1653
1504
  WHERE scan_id = ? AND kind = 'discovery' AND merge_state = 'buffered'
1654
- ORDER BY completion_sequence, id
1655
1505
  """,
1656
1506
  (scan_id,),
1657
1507
  )
1658
- ]
1659
- # Historical succeeded runs retain their exact omitted-worker replay contract.
1660
- omissions_match = (
1661
- set(omitted_worker_ids) == set(buffered_worker_ids)
1662
- if args.terminal_reason == "saturated" or run["status"] == "succeeded"
1663
- else not omitted_worker_ids and not buffered_worker_ids
1664
- )
1508
+ }
1665
1509
  if run["status"] == "succeeded":
1666
1510
  if (
1667
1511
  run["terminal_reason"] != args.terminal_reason
1668
- or run["manifest_path"] not in {None, manifest_path}
1669
- or not omissions_match
1512
+ or archived_deep_path(Path(scan["scan_dir"]), run["manifest_path"])
1513
+ not in {None, manifest_path}
1514
+ or omitted_worker_ids != buffered_worker_ids
1670
1515
  ):
1671
1516
  raise SystemExit(
1672
1517
  "Deep Scan terminal state is immutable; finish must exactly replay its "
@@ -1679,7 +1524,9 @@ def finish_deep_scan_locked(
1679
1524
  )
1680
1525
  connection.commit()
1681
1526
  return deep_scan_result(connection, scan_id)
1682
- require_running_deep_scan(connection, scan_id)
1527
+ require_running_deep_scan(run, scan)
1528
+ if run["error_message"] is not None:
1529
+ raise SystemExit(run["error_message"])
1683
1530
  if (
1684
1531
  args.terminal_reason == "saturated"
1685
1532
  and run["consecutive_no_new"] < run["stop_after_no_new"]
@@ -1711,7 +1558,7 @@ def finish_deep_scan_locked(
1711
1558
  raise SystemExit(
1712
1559
  f"Deep Scan cannot finish without canonical discovery artifacts: {exc}"
1713
1560
  ) from exc
1714
- successful_reducer = connection.execute(
1561
+ saved_iteration = connection.execute(
1715
1562
  """
1716
1563
  SELECT 1 FROM deep_scan_workers
1717
1564
  WHERE scan_id = ? AND kind = 'dedup' AND status = 'succeeded'
@@ -1729,8 +1576,8 @@ def finish_deep_scan_locked(
1729
1576
  and Path(canonical_artifacts["candidateLedgerPath"]).stat().st_size == 0
1730
1577
  )
1731
1578
  )
1732
- if successful_reducer is None and not zero_discovery_deadline:
1733
- raise SystemExit("Deep Scan cannot finish without a successful dedup worker.")
1579
+ if saved_iteration is None and not zero_discovery_deadline:
1580
+ raise SystemExit("Deep Scan cannot finish without a saved iteration.")
1734
1581
  if args.terminal_reason == "saturated":
1735
1582
  # Saturation cancels surplus workers, including failed cancellation writes.
1736
1583
  cancel_active_workers(connection, scan_id, dependencies().now())
@@ -1740,7 +1587,7 @@ def finish_deep_scan_locked(
1740
1587
  args.terminal_reason,
1741
1588
  has_omitted_workers=bool(omitted_worker_ids),
1742
1589
  )
1743
- if args.terminal_reason == "saturated" and not omissions_match:
1590
+ if args.terminal_reason == "saturated" and omitted_worker_ids != buffered_worker_ids:
1744
1591
  raise SystemExit(
1745
1592
  f"Deep Scan {args.terminal_reason} completion must exactly identify all buffered discovery "
1746
1593
  "workers with --omitted-worker-id."
@@ -1771,7 +1618,6 @@ def finish_deep_scan_locked(
1771
1618
  """,
1772
1619
  (args.terminal_reason, manifest_path, timestamp, timestamp, scan_id),
1773
1620
  )
1774
- cancel_active_workers(connection, scan_id, timestamp)
1775
1621
  connection.commit()
1776
1622
  except BaseException:
1777
1623
  connection.rollback()
@@ -1810,6 +1656,7 @@ def fail_deep_scan_locked(
1810
1656
  run = require_deep_scan_run(connection, scan_id)
1811
1657
  require_current_coordinator(run, args)
1812
1658
  scan = dependencies().require_scan(connection, scan_id)
1659
+ recorded_manifest = archived_deep_path(Path(scan["scan_dir"]), run["manifest_path"])
1813
1660
  manifest_path = None
1814
1661
  if args.manifest_path:
1815
1662
  manifest_path = (
@@ -1822,14 +1669,14 @@ def fail_deep_scan_locked(
1822
1669
  kind="file",
1823
1670
  )
1824
1671
  )
1825
- elif run["manifest_path"] == str(Path(scan["scan_dir"]) / "scan-manifest.json"):
1826
- manifest_path = run["manifest_path"]
1672
+ elif recorded_manifest == str(Path(scan["scan_dir"]) / "scan-manifest.json"):
1673
+ manifest_path = recorded_manifest
1827
1674
  if run["status"] in {"failed", "interrupted"} or scan["status"] == "failed":
1828
1675
  if (
1829
1676
  run["status"] == args.deep_status
1830
1677
  and scan["status"] == "failed"
1831
1678
  and run["error_message"] == message
1832
- and run["manifest_path"] == manifest_path
1679
+ and recorded_manifest == manifest_path
1833
1680
  and scan["failure_message"] == message
1834
1681
  ):
1835
1682
  connection.commit()
@@ -1848,6 +1695,9 @@ def fail_deep_scan_locked(
1848
1695
  "status"
1849
1696
  ] != "running":
1850
1697
  raise SystemExit("Only a running Deep Scan can be failed or interrupted.")
1698
+ # Cleanup can report a later error after a worker committed the terminal cause.
1699
+ if run["status"] == "running" and run["error_message"] is not None:
1700
+ message = run["error_message"]
1851
1701
  if run["manifest_path"] not in {None, manifest_path}:
1852
1702
  raise SystemExit("Deep Scan coordinator manifest path is immutable.")
1853
1703
  if args.staged_manifest_path and manifest_path:
@@ -1869,20 +1719,9 @@ def fail_deep_scan_locked(
1869
1719
  (args.deep_status, message, manifest_path, timestamp, timestamp, scan_id),
1870
1720
  )
1871
1721
  cancel_active_workers(connection, scan_id, timestamp)
1872
- parent_update = connection.execute(
1873
- """
1874
- UPDATE scans
1875
- SET status = 'failed', failure_message = ?, completed_at = ?, updated_at = ?
1876
- WHERE id = ? AND status = 'running'
1877
- """,
1878
- (message, timestamp, timestamp, scan_id),
1879
- )
1880
- if parent_update.rowcount != 1:
1722
+ if not saved_results.mark_running_scan_failed(connection, scan_id, message, timestamp):
1881
1723
  raise SystemExit("Deep Scan failure could not be persisted to its parent scan.")
1882
- connection.execute(
1883
- "UPDATE scan_progress SET updated_at = ? WHERE scan_id = ?",
1884
- (timestamp, scan_id),
1885
- )
1724
+ saved_results.touch_scan_progress(connection, scan_id, timestamp)
1886
1725
  connection.commit()
1887
1726
  except BaseException:
1888
1727
  connection.rollback()
@@ -1967,7 +1806,7 @@ def cancel_from_parent_scan(connection: sqlite3.Connection, scan_id: str, timest
1967
1806
  connection.execute(
1968
1807
  """
1969
1808
  UPDATE deep_scan_runs
1970
- SET status = 'canceled', phase = 'terminal', cancel_requested = 1,
1809
+ SET status = 'canceled', phase = 'terminal', cancel_requested = 1, error_message = NULL,
1971
1810
  terminal_reviewed_surface_count = NULL, completed_at = ?, updated_at = ?
1972
1811
  WHERE scan_id = ? AND status IN ('running', 'succeeded')
1973
1812
  """,
@@ -1990,6 +1829,7 @@ def cancel_active_workers(connection: sqlite3.Connection, scan_id: str, timestam
1990
1829
  def other_running_deep_scans(
1991
1830
  connection: sqlite3.Connection, current_scan_id: str
1992
1831
  ) -> list[dict[str, str]]:
1832
+ """List other running Deep Scans ordered by most recent update, with target paths and phases."""
1993
1833
  rows = connection.execute(
1994
1834
  """
1995
1835
  SELECT id, target_path, phase, started_at, updated_at