@openai/codex-security 0.1.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 (178) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +306 -0
  3. package/_bundled_plugin/.app.json +20 -0
  4. package/_bundled_plugin/.codex-plugin/plugin.json +41 -0
  5. package/_bundled_plugin/.mcp.json +20 -0
  6. package/_bundled_plugin/assets/logo.png +0 -0
  7. package/_bundled_plugin/examples/completed-scan/coverage.json +22 -0
  8. package/_bundled_plugin/examples/completed-scan/findings.json +51 -0
  9. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +43 -0
  10. package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
  11. package/_bundled_plugin/mcp/server.mjs +24 -0
  12. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  14. package/_bundled_plugin/preflight/capability-profiles.toml +179 -0
  15. package/_bundled_plugin/references/config-preflight.md +115 -0
  16. package/_bundled_plugin/references/final-report.md +205 -0
  17. package/_bundled_plugin/references/finding-detail-fields.md +162 -0
  18. package/_bundled_plugin/references/sarif-adapter.md +26 -0
  19. package/_bundled_plugin/references/scan-artifacts.md +116 -0
  20. package/_bundled_plugin/references/scan-contract.md +164 -0
  21. package/_bundled_plugin/references/security-guidance.md +15 -0
  22. package/_bundled_plugin/references/shared-hard-rules.md +15 -0
  23. package/_bundled_plugin/references/static-finding-assessment.md +75 -0
  24. package/_bundled_plugin/schemas/coverage.schema.json +228 -0
  25. package/_bundled_plugin/schemas/findings.schema.json +359 -0
  26. package/_bundled_plugin/schemas/scan-manifest.schema.json +332 -0
  27. package/_bundled_plugin/scripts/config_preflight.py +901 -0
  28. package/_bundled_plugin/scripts/deep_scan_config.py +108 -0
  29. package/_bundled_plugin/scripts/deep_scan_workbench.py +1547 -0
  30. package/_bundled_plugin/scripts/filesystem_identity.py +30 -0
  31. package/_bundled_plugin/scripts/finalize_scan_contract.py +2208 -0
  32. package/_bundled_plugin/scripts/finding_preview.py +270 -0
  33. package/_bundled_plugin/scripts/generate_rank_input.py +1013 -0
  34. package/_bundled_plugin/scripts/normalize_candidates.py +320 -0
  35. package/_bundled_plugin/scripts/rank_preview.py +968 -0
  36. package/_bundled_plugin/scripts/report_projection.py +844 -0
  37. package/_bundled_plugin/scripts/resolve_security_md.py +158 -0
  38. package/_bundled_plugin/scripts/snapshot_sqlite.py +26 -0
  39. package/_bundled_plugin/scripts/validate_report_format.py +138 -0
  40. package/_bundled_plugin/scripts/validate_scan_contract.py +108 -0
  41. package/_bundled_plugin/scripts/validate_tracking_source.py +92 -0
  42. package/_bundled_plugin/scripts/windows_scan_local_files.py +612 -0
  43. package/_bundled_plugin/scripts/workbench/__init__.py +1 -0
  44. package/_bundled_plugin/scripts/workbench/handoff.py +238 -0
  45. package/_bundled_plugin/scripts/workbench_cli.py +325 -0
  46. package/_bundled_plugin/scripts/workbench_constants.py +81 -0
  47. package/_bundled_plugin/scripts/workbench_db.py +3728 -0
  48. package/_bundled_plugin/scripts/workbench_native_indexes.py +242 -0
  49. package/_bundled_plugin/scripts/workbench_progress.py +226 -0
  50. package/_bundled_plugin/scripts/workbench_remediation.py +125 -0
  51. package/_bundled_plugin/scripts/workbench_scan_history.py +829 -0
  52. package/_bundled_plugin/scripts/workbench_scan_start.py +149 -0
  53. package/_bundled_plugin/scripts/workbench_schema.py +714 -0
  54. package/_bundled_plugin/scripts/workbench_source_excerpt.py +99 -0
  55. package/_bundled_plugin/scripts/workbench_target.py +469 -0
  56. package/_bundled_plugin/scripts/workbench_target_state.py +63 -0
  57. package/_bundled_plugin/scripts/workbench_validation.py +294 -0
  58. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +117 -0
  59. package/_bundled_plugin/skills/attack-path-analysis/agents/openai.yaml +4 -0
  60. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +76 -0
  61. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +153 -0
  62. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +166 -0
  63. package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +4 -0
  64. package/_bundled_plugin/skills/define-security-policy/SKILL.md +93 -0
  65. package/_bundled_plugin/skills/define-security-policy/agents/openai.yaml +4 -0
  66. package/_bundled_plugin/skills/finding-discovery/SKILL.md +155 -0
  67. package/_bundled_plugin/skills/finding-discovery/agents/openai.yaml +4 -0
  68. package/_bundled_plugin/skills/fix-finding/SKILL.md +112 -0
  69. package/_bundled_plugin/skills/fix-finding/agents/openai.yaml +4 -0
  70. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +240 -0
  71. package/_bundled_plugin/skills/propose-security-hardening/agents/openai.yaml +4 -0
  72. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +424 -0
  73. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +167 -0
  74. package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +4 -0
  75. package/_bundled_plugin/skills/security-scan/SKILL.md +42 -0
  76. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +4 -0
  77. package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +48 -0
  78. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +85 -0
  79. package/_bundled_plugin/skills/threat-model/SKILL.md +59 -0
  80. package/_bundled_plugin/skills/threat-model/agents/openai.yaml +4 -0
  81. package/_bundled_plugin/skills/threat-model/references/threat-model-guidance.md +48 -0
  82. package/_bundled_plugin/skills/track-findings/SKILL.md +222 -0
  83. package/_bundled_plugin/skills/track-findings/agents/openai.yaml +6 -0
  84. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +54 -0
  85. package/_bundled_plugin/skills/track-findings/references/jira.md +77 -0
  86. package/_bundled_plugin/skills/triage-finding/SKILL.md +342 -0
  87. package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +4 -0
  88. package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +168 -0
  89. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +62 -0
  90. package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +108 -0
  91. package/_bundled_plugin/skills/validation/SKILL.md +110 -0
  92. package/_bundled_plugin/skills/validation/agents/openai.yaml +4 -0
  93. package/_bundled_plugin/skills/validation/references/validation-guidance.md +122 -0
  94. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +263 -0
  95. package/_bundled_plugin/skills/vulnerability-writeup/agents/openai.yaml +4 -0
  96. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +104 -0
  97. package/bin/codex-security.mjs +26 -0
  98. package/dist/api.d.ts +112 -0
  99. package/dist/api.d.ts.map +1 -0
  100. package/dist/api.js +1051 -0
  101. package/dist/api.js.map +1 -0
  102. package/dist/auth.d.ts +29 -0
  103. package/dist/auth.d.ts.map +1 -0
  104. package/dist/auth.js +246 -0
  105. package/dist/auth.js.map +1 -0
  106. package/dist/bulk-scan-discovery.d.ts +35 -0
  107. package/dist/bulk-scan-discovery.d.ts.map +1 -0
  108. package/dist/bulk-scan-discovery.js +217 -0
  109. package/dist/bulk-scan-discovery.js.map +1 -0
  110. package/dist/cli.d.ts +67 -0
  111. package/dist/cli.d.ts.map +1 -0
  112. package/dist/cli.js +2128 -0
  113. package/dist/cli.js.map +1 -0
  114. package/dist/config.d.ts +19 -0
  115. package/dist/config.d.ts.map +1 -0
  116. package/dist/config.js +199 -0
  117. package/dist/config.js.map +1 -0
  118. package/dist/contract.d.ts +21 -0
  119. package/dist/contract.d.ts.map +1 -0
  120. package/dist/contract.js +848 -0
  121. package/dist/contract.js.map +1 -0
  122. package/dist/cost.d.ts +30 -0
  123. package/dist/cost.d.ts.map +1 -0
  124. package/dist/cost.js +280 -0
  125. package/dist/cost.js.map +1 -0
  126. package/dist/errors.d.ts +38 -0
  127. package/dist/errors.d.ts.map +1 -0
  128. package/dist/errors.js +52 -0
  129. package/dist/errors.js.map +1 -0
  130. package/dist/index.d.ts +22 -0
  131. package/dist/index.d.ts.map +1 -0
  132. package/dist/index.js +11 -0
  133. package/dist/index.js.map +1 -0
  134. package/dist/knowledge-base.d.ts +7 -0
  135. package/dist/knowledge-base.d.ts.map +1 -0
  136. package/dist/knowledge-base.js +181 -0
  137. package/dist/knowledge-base.js.map +1 -0
  138. package/dist/models.d.ts +231 -0
  139. package/dist/models.d.ts.map +1 -0
  140. package/dist/models.js +3 -0
  141. package/dist/models.js.map +1 -0
  142. package/dist/multiscan.d.ts +30 -0
  143. package/dist/multiscan.d.ts.map +1 -0
  144. package/dist/multiscan.js +397 -0
  145. package/dist/multiscan.js.map +1 -0
  146. package/dist/result.d.ts +39 -0
  147. package/dist/result.d.ts.map +1 -0
  148. package/dist/result.js +71 -0
  149. package/dist/result.js.map +1 -0
  150. package/dist/runtime.d.ts +69 -0
  151. package/dist/runtime.d.ts.map +1 -0
  152. package/dist/runtime.js +997 -0
  153. package/dist/runtime.js.map +1 -0
  154. package/dist/scan-comparison.d.ts +42 -0
  155. package/dist/scan-comparison.d.ts.map +1 -0
  156. package/dist/scan-comparison.js +153 -0
  157. package/dist/scan-comparison.js.map +1 -0
  158. package/dist/scan-history-renderer.d.ts +13 -0
  159. package/dist/scan-history-renderer.d.ts.map +1 -0
  160. package/dist/scan-history-renderer.js +297 -0
  161. package/dist/scan-history-renderer.js.map +1 -0
  162. package/dist/targets.d.ts +39 -0
  163. package/dist/targets.d.ts.map +1 -0
  164. package/dist/targets.js +295 -0
  165. package/dist/targets.js.map +1 -0
  166. package/dist/trusted-executable.d.ts +6 -0
  167. package/dist/trusted-executable.d.ts.map +1 -0
  168. package/dist/trusted-executable.js +77 -0
  169. package/dist/trusted-executable.js.map +1 -0
  170. package/dist/version.d.ts +6 -0
  171. package/dist/version.d.ts.map +1 -0
  172. package/dist/version.js +42 -0
  173. package/dist/version.js.map +1 -0
  174. package/dist/worker-progress.d.ts +13 -0
  175. package/dist/worker-progress.d.ts.map +1 -0
  176. package/dist/worker-progress.js +113 -0
  177. package/dist/worker-progress.js.map +1 -0
  178. package/package.json +74 -0
@@ -0,0 +1,1547 @@
1
+ """Persist deterministic Codex Security Deep Scan orchestration state."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import os
7
+ import sqlite3
8
+ import sys
9
+ import tempfile
10
+ import uuid
11
+ from dataclasses import dataclass
12
+ from pathlib import Path
13
+ from typing import Any, Callable
14
+
15
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
16
+ from deep_scan_config import resolve_deep_scan_config
17
+ from filesystem_identity import serialize_filesystem_identity
18
+ from workbench.handoff import require_current_continuation
19
+ from workbench_target import (
20
+ directory_content_digest,
21
+ directory_snapshot_regular_file_count,
22
+ git_revision,
23
+ worktree_content_digest,
24
+ )
25
+ from workbench_validation import optional_text, require_uuid
26
+
27
+ DEEP_SCAN_WORKER_KINDS = ("setup", "discovery", "dedup")
28
+ DEEP_SCAN_WORKER_STATUSES = ("queued", "running", "succeeded", "failed", "canceled")
29
+ DEEP_SCAN_TERMINAL_REASONS = ("saturated", "capped")
30
+ DEEP_SCAN_WORKFLOW_VERSION = "deep-security-scan/v1"
31
+
32
+
33
+ def register_subcommands(subparsers: Any, positive_int: Callable[[str], int]) -> None:
34
+ begin_deep_scan = subparsers.add_parser("begin-deep-scan")
35
+ begin_deep_scan.add_argument("--thread-id", required=True)
36
+ begin_target = begin_deep_scan.add_mutually_exclusive_group(required=True)
37
+ begin_target.add_argument("--scan-id")
38
+ begin_target.add_argument("--target-path")
39
+ begin_deep_scan.add_argument("--scope", default=".")
40
+ begin_deep_scan.add_argument("--user-context")
41
+ begin_deep_scan.add_argument("--scan-root")
42
+ begin_deep_scan.add_argument("--claim-token")
43
+ begin_deep_scan.add_argument("--available-parallelism", type=positive_int)
44
+ begin_deep_scan.add_argument("--workflow-version", default=DEEP_SCAN_WORKFLOW_VERSION)
45
+
46
+ get_deep_scan = subparsers.add_parser("get-deep-scan")
47
+ get_deep_scan.add_argument("--scan-id", required=True)
48
+ get_deep_scan.add_argument("--thread-id", required=True)
49
+
50
+ upsert_deep_worker = subparsers.add_parser("upsert-deep-scan-worker")
51
+ upsert_deep_worker.add_argument("--scan-id", required=True)
52
+ upsert_deep_worker.add_argument("--worker-id", required=True)
53
+ upsert_deep_worker.add_argument("--kind", choices=DEEP_SCAN_WORKER_KINDS, required=True)
54
+ upsert_deep_worker.add_argument("--status", choices=DEEP_SCAN_WORKER_STATUSES, required=True)
55
+ upsert_deep_worker.add_argument("--prompt-path", required=True)
56
+ upsert_deep_worker.add_argument("--artifact-dir", required=True)
57
+ upsert_deep_worker.add_argument("--result-manifest-path")
58
+ upsert_deep_worker.add_argument("--attempt", type=non_negative_int)
59
+ upsert_deep_worker.add_argument("--sdk-thread-id")
60
+ upsert_deep_worker.add_argument("--error-message")
61
+
62
+ claim_deep_dedup = subparsers.add_parser("claim-deep-scan-dedup")
63
+ claim_deep_dedup.add_argument("--scan-id", required=True)
64
+ claim_deep_dedup.add_argument("--worker-id", required=True)
65
+ claim_deep_dedup.add_argument("--prompt-path", required=True)
66
+ claim_deep_dedup.add_argument("--artifact-dir", required=True)
67
+ claim_deep_dedup.add_argument("--input-worker-id", action="append", required=True)
68
+
69
+ commit_deep_dedup = subparsers.add_parser("commit-deep-scan-dedup")
70
+ commit_deep_dedup.add_argument("--scan-id", required=True)
71
+ commit_deep_dedup.add_argument("--worker-id", required=True)
72
+ commit_deep_dedup.add_argument("--canonical-inventory-path", required=True)
73
+ commit_deep_dedup.add_argument("--canonical-finding-report-path", required=True)
74
+ commit_deep_dedup.add_argument("--canonical-candidates-path", required=True)
75
+ commit_deep_dedup.add_argument("--dedupe-report-path", required=True)
76
+ commit_deep_dedup.add_argument("--seed-research-path", required=True)
77
+ commit_deep_dedup.add_argument("--work-ledger-path", required=True)
78
+ commit_deep_dedup.add_argument("--raw-candidates-path", required=True)
79
+ commit_deep_dedup.add_argument("--coverage-ledger-path", required=True)
80
+ commit_deep_dedup.add_argument("--findings-dir", required=True)
81
+ commit_deep_dedup.add_argument("--result-manifest-path", required=True)
82
+ commit_deep_dedup.add_argument("--new-findings-count", type=non_negative_int, required=True)
83
+
84
+ finish_deep_scan = subparsers.add_parser("finish-deep-scan")
85
+ finish_deep_scan.add_argument("--scan-id", required=True)
86
+ finish_deep_scan.add_argument(
87
+ "--terminal-reason", choices=DEEP_SCAN_TERMINAL_REASONS, required=True
88
+ )
89
+ finish_deep_scan.add_argument("--manifest-path", required=True)
90
+ finish_deep_scan.add_argument("--omitted-worker-id", action="append", default=[])
91
+
92
+ fail_deep_scan = subparsers.add_parser("fail-deep-scan")
93
+ fail_deep_scan.add_argument("--scan-id", required=True)
94
+ fail_deep_scan.add_argument("--message", required=True)
95
+ fail_deep_scan.add_argument("--manifest-path")
96
+ fail_deep_scan.add_argument(
97
+ "--deep-status", choices=("failed", "interrupted"), default="failed"
98
+ )
99
+
100
+
101
+ def non_negative_int(value: str) -> int:
102
+ parsed = int(value)
103
+ if parsed < 0:
104
+ raise argparse.ArgumentTypeError("expected a non-negative integer")
105
+ return parsed
106
+
107
+
108
+ @dataclass(frozen=True)
109
+ class DeepScanDependencies:
110
+ now: Callable[[], str]
111
+ state_dir: Callable[[], Path]
112
+ require_scan: Callable[[sqlite3.Connection, str], sqlite3.Row]
113
+ require_workspace: Callable[[sqlite3.Connection, str], sqlite3.Row]
114
+ require_target: Callable[[str], Path]
115
+ require_remediation_target: Callable[[str], Path]
116
+ require_scannable_target: Callable[[Path], None]
117
+ require_scope: Callable[[str, str, Path], str]
118
+ ensure_security_target: Callable[[sqlite3.Connection, str], str]
119
+ require_canonical_scan_directory: Callable[[Path], Path]
120
+ safe_segment: Callable[[str], str]
121
+ compact_timestamp: Callable[[], str]
122
+
123
+
124
+ _dependencies: DeepScanDependencies | None = None
125
+
126
+
127
+ def configure(dependencies: DeepScanDependencies) -> None:
128
+ global _dependencies
129
+ _dependencies = dependencies
130
+
131
+
132
+ def dependencies() -> DeepScanDependencies:
133
+ if _dependencies is None:
134
+ raise RuntimeError("Deep Scan workbench dependencies are not configured.")
135
+ return _dependencies
136
+
137
+
138
+ def now() -> str:
139
+ return dependencies().now()
140
+
141
+
142
+ def state_dir() -> Path:
143
+ return dependencies().state_dir()
144
+
145
+
146
+ def require_scan(connection: sqlite3.Connection, scan_id: str) -> sqlite3.Row:
147
+ return dependencies().require_scan(connection, scan_id)
148
+
149
+
150
+ def require_workspace(connection: sqlite3.Connection, workspace_id: str) -> sqlite3.Row:
151
+ return dependencies().require_workspace(connection, workspace_id)
152
+
153
+
154
+ def require_target(value: str) -> Path:
155
+ return dependencies().require_target(value)
156
+
157
+
158
+ def require_remediation_target(value: str) -> Path:
159
+ return dependencies().require_remediation_target(value)
160
+
161
+
162
+ def require_scannable_target(target: Path) -> None:
163
+ dependencies().require_scannable_target(target)
164
+
165
+
166
+ def require_scope(scope: str, mode: str, target: Path) -> str:
167
+ return dependencies().require_scope(scope, mode, target)
168
+
169
+
170
+ def ensure_security_target(connection: sqlite3.Connection, target_path: str) -> str:
171
+ return dependencies().ensure_security_target(connection, target_path)
172
+
173
+
174
+ def require_canonical_scan_directory(scan_dir: Path) -> Path:
175
+ return dependencies().require_canonical_scan_directory(scan_dir)
176
+
177
+
178
+ def safe_segment(value: str) -> str:
179
+ return dependencies().safe_segment(value)
180
+
181
+
182
+ def compact_timestamp() -> str:
183
+ return dependencies().compact_timestamp()
184
+
185
+
186
+ def require_deep_scan_run(connection: sqlite3.Connection, scan_id: str) -> sqlite3.Row:
187
+ scan_id = require_uuid(scan_id, "scan-id")
188
+ row = connection.execute(
189
+ "SELECT * FROM deep_scan_runs WHERE scan_id = ?", (scan_id,)
190
+ ).fetchone()
191
+ if row is None:
192
+ raise SystemExit("Codex Security Deep Scan orchestration state not found.")
193
+ return row
194
+
195
+
196
+ def require_deep_scan_ready_for_parent_completion(
197
+ connection: sqlite3.Connection, scan: sqlite3.Row
198
+ ) -> None:
199
+ if scan["mode"] != "deep":
200
+ return
201
+ run = connection.execute(
202
+ "SELECT status, manifest_path FROM deep_scan_runs WHERE scan_id = ?",
203
+ (scan["id"],),
204
+ ).fetchone()
205
+ if run is None or run["status"] != "succeeded" or run["manifest_path"] is None:
206
+ raise SystemExit(
207
+ "Deep Scan discovery orchestration must finish and persist its manifest before "
208
+ "the parent scan can be completed."
209
+ )
210
+
211
+
212
+ def require_owned_scan(
213
+ connection: sqlite3.Connection, scan_id: str, thread_id: str
214
+ ) -> tuple[sqlite3.Row, sqlite3.Row]:
215
+ scan = require_scan(connection, scan_id)
216
+ workspace = require_workspace(connection, scan["workspace_id"])
217
+ owner = optional_text(thread_id, maximum=512)
218
+ if owner is None:
219
+ raise SystemExit("thread-id is required.")
220
+ persisted_owner = scan["deep_scan_owner_thread_id"] or workspace["thread_id"]
221
+ if persisted_owner != owner:
222
+ raise SystemExit("A scan can only be orchestrated from its owning Codex thread.")
223
+ return scan, workspace
224
+
225
+
226
+ def deep_scan_path(
227
+ scan: sqlite3.Row,
228
+ value: str,
229
+ label: str,
230
+ *,
231
+ kind: str,
232
+ ) -> str:
233
+ supplied = Path(value).expanduser()
234
+ if not supplied.is_absolute():
235
+ raise SystemExit(f"{label} must be an absolute path inside the scan directory.")
236
+ try:
237
+ resolved = supplied.resolve(strict=True)
238
+ scan_dir = require_canonical_scan_directory(Path(scan["scan_dir"]))
239
+ resolved.relative_to(scan_dir)
240
+ except (OSError, RuntimeError, ValueError) as exc:
241
+ raise SystemExit(f"{label} must be an existing path inside the scan directory.") from exc
242
+ if resolved != supplied.absolute():
243
+ raise SystemExit(f"{label} must be a canonical non-symlink path.")
244
+ if kind == "file" and not resolved.is_file():
245
+ raise SystemExit(f"{label} must be a regular file.")
246
+ if kind == "directory" and not resolved.is_dir():
247
+ raise SystemExit(f"{label} must be a directory.")
248
+ return str(resolved)
249
+
250
+
251
+ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, Any]:
252
+ run = require_deep_scan_run(connection, scan_id)
253
+ scan = require_scan(connection, run["scan_id"])
254
+ worker_rows = connection.execute(
255
+ """
256
+ SELECT *
257
+ FROM deep_scan_workers
258
+ WHERE scan_id = ?
259
+ ORDER BY created_at, id
260
+ """,
261
+ (run["scan_id"],),
262
+ )
263
+ input_rows = connection.execute(
264
+ """
265
+ SELECT dedup_worker_id, discovery_worker_id, input_order
266
+ FROM deep_scan_dedup_inputs
267
+ WHERE scan_id = ?
268
+ ORDER BY dedup_worker_id, input_order
269
+ """,
270
+ (run["scan_id"],),
271
+ )
272
+ return {
273
+ "scanId": run["scan_id"],
274
+ "targetPath": scan["target_path"],
275
+ "scope": scan["scope"],
276
+ "userContext": scan["user_context"],
277
+ "scanDir": scan["scan_dir"],
278
+ "schemaVersion": run["schema_version"],
279
+ "workflowVersion": run["workflow_version"],
280
+ "coordinatorGeneration": run["coordinator_generation"],
281
+ "status": run["status"],
282
+ "phase": run["phase"],
283
+ "config": {
284
+ "workers": run["workers"],
285
+ "subagents": run["subagents"],
286
+ "stopAfterNoNew": run["stop_after_no_new"],
287
+ "maxDiscoveryRuns": run["max_discovery_runs"],
288
+ },
289
+ "dispatchedCount": run["discovery_runs_dispatched"],
290
+ "completionSequence": run["completion_sequence"],
291
+ "noNewStreak": run["consecutive_no_new"],
292
+ "cancelRequested": bool(run["cancel_requested"]),
293
+ "canonicalInventoryPath": run["canonical_inventory_path"],
294
+ "canonicalArtifacts": {
295
+ "inventoryPath": run["canonical_inventory_path"],
296
+ "findingReportPath": run["canonical_finding_report_path"],
297
+ "candidatesPath": run["canonical_candidates_path"],
298
+ "dedupeReportPath": run["dedupe_report_path"],
299
+ "seedResearchPath": run["seed_research_path"],
300
+ "workLedgerPath": run["work_ledger_path"],
301
+ "rawCandidatesPath": run["raw_candidates_path"],
302
+ "coverageLedgerPath": run["coverage_ledger_path"],
303
+ "findingsDir": run["findings_dir"],
304
+ },
305
+ "manifestPath": run["manifest_path"],
306
+ "terminalReason": run["terminal_reason"],
307
+ "error": run["error_message"],
308
+ "createdAt": run["created_at"],
309
+ "updatedAt": run["updated_at"],
310
+ "completedAt": run["completed_at"],
311
+ "workers": [deep_scan_worker_state(row) for row in worker_rows],
312
+ "dedupInputs": [
313
+ {
314
+ "dedupWorkerId": row["dedup_worker_id"],
315
+ "discoveryWorkerId": row["discovery_worker_id"],
316
+ "inputOrder": row["input_order"],
317
+ }
318
+ for row in input_rows
319
+ ],
320
+ }
321
+
322
+
323
+ def independent_review_progress(
324
+ connection: sqlite3.Connection, scan_id: str
325
+ ) -> dict[str, int | str] | None:
326
+ run = connection.execute(
327
+ "SELECT completion_sequence, updated_at FROM deep_scan_runs WHERE scan_id = ?",
328
+ (scan_id,),
329
+ ).fetchone()
330
+ if run is None:
331
+ return None
332
+ active = connection.execute(
333
+ """
334
+ SELECT COUNT(*)
335
+ FROM deep_scan_workers
336
+ WHERE scan_id = ?
337
+ AND kind = 'discovery'
338
+ AND status IN ('queued', 'running')
339
+ """,
340
+ (scan_id,),
341
+ ).fetchone()[0]
342
+ return {
343
+ "active": int(active),
344
+ "completed": int(run["completion_sequence"]),
345
+ "updatedAt": str(run["updated_at"]),
346
+ }
347
+
348
+
349
+ def deep_scan_worker_state(row: sqlite3.Row) -> dict[str, Any]:
350
+ return {
351
+ "id": row["id"],
352
+ "kind": row["kind"],
353
+ "status": row["status"],
354
+ "mergeState": row["merge_state"],
355
+ "promptPath": row["prompt_path"],
356
+ "artifactDir": row["artifact_dir"],
357
+ "resultManifestPath": row["result_manifest_path"],
358
+ "attempt": row["attempt"],
359
+ "sdkThreadId": row["sdk_thread_id"],
360
+ "completionSequence": row["completion_sequence"],
361
+ "error": row["error_message"],
362
+ "createdAt": row["created_at"],
363
+ "startedAt": row["started_at"],
364
+ "completedAt": row["completed_at"],
365
+ "updatedAt": row["updated_at"],
366
+ }
367
+
368
+
369
+ def deep_scan_result(
370
+ connection: sqlite3.Connection,
371
+ scan_id: str,
372
+ *,
373
+ start_disposition: str | None = None,
374
+ ) -> dict[str, Any]:
375
+ result: dict[str, Any] = {"deepScan": deep_scan_state(connection, scan_id)}
376
+ if start_disposition is not None:
377
+ result["startDisposition"] = start_disposition
378
+ return result
379
+
380
+
381
+ def effective_deep_scan_config(args: argparse.Namespace) -> dict[str, int]:
382
+ available_parallelism = args.available_parallelism or os.cpu_count() or 1
383
+ return resolve_deep_scan_config(available_parallelism)
384
+
385
+
386
+ def ensure_deep_scan_run(
387
+ connection: sqlite3.Connection,
388
+ scan: sqlite3.Row,
389
+ config: dict[str, int],
390
+ workflow_version: str,
391
+ timestamp: str,
392
+ ) -> sqlite3.Row:
393
+ existing = connection.execute(
394
+ "SELECT * FROM deep_scan_runs WHERE scan_id = ?", (scan["id"],)
395
+ ).fetchone()
396
+ if existing is not None:
397
+ return existing
398
+ if scan["mode"] != "deep":
399
+ raise SystemExit("Deep Scan orchestration requires a scan in deep mode.")
400
+ if scan["status"] != "running":
401
+ raise SystemExit("Only a running Deep Scan can start orchestration.")
402
+ connection.execute(
403
+ """
404
+ INSERT INTO deep_scan_runs (
405
+ scan_id, schema_version, workflow_version, status, phase,
406
+ workers, subagents, stop_after_no_new, max_discovery_runs,
407
+ created_at, updated_at
408
+ ) VALUES (?, 1, ?, 'running', 'setup', ?, ?, ?, ?, ?, ?)
409
+ """,
410
+ (
411
+ scan["id"],
412
+ workflow_version,
413
+ config["workers"],
414
+ config["subagents"],
415
+ config["stopAfterNoNew"],
416
+ config["maxDiscoveryRuns"],
417
+ timestamp,
418
+ timestamp,
419
+ ),
420
+ )
421
+ return require_deep_scan_run(connection, scan["id"])
422
+
423
+
424
+ def existing_deep_scan_for_target(
425
+ connection: sqlite3.Connection, thread_id: str, target_path: str, scope: str
426
+ ) -> sqlite3.Row | None:
427
+ return connection.execute(
428
+ """
429
+ SELECT scans.*
430
+ FROM scans
431
+ JOIN workspaces ON workspaces.id = scans.workspace_id
432
+ WHERE workspaces.thread_id = ?
433
+ AND COALESCE(scans.deep_scan_owner_thread_id, workspaces.thread_id) = ?
434
+ AND scans.target_path = ?
435
+ AND scans.scope = ?
436
+ AND scans.mode = 'deep'
437
+ AND scans.status = 'running'
438
+ ORDER BY scans.updated_at DESC, scans.started_at DESC, scans.id
439
+ LIMIT 1
440
+ """,
441
+ (thread_id, thread_id, target_path, scope),
442
+ ).fetchone()
443
+
444
+
445
+ def terminal_deep_scan_for_target_snapshot(
446
+ connection: sqlite3.Connection,
447
+ thread_id: str,
448
+ target_path: str,
449
+ scope: str,
450
+ revision: str,
451
+ snapshot_digest: str,
452
+ target_device: int | str,
453
+ target_inode: int | str,
454
+ ) -> sqlite3.Row | None:
455
+ """Find discovery completed before a headless continuation changed thread IDs.
456
+
457
+ A continuation may safely consume a finished coordinator manifest while the
458
+ parent scan is still open. It must not adopt live orchestration owned by a
459
+ different thread, or reuse results after the repository snapshot changed.
460
+ """
461
+ return connection.execute(
462
+ """
463
+ SELECT scans.*
464
+ FROM scans
465
+ JOIN deep_scan_runs ON deep_scan_runs.scan_id = scans.id
466
+ JOIN workspaces ON workspaces.id = scans.workspace_id
467
+ WHERE scans.target_path = ?
468
+ AND scans.scope = ?
469
+ AND scans.mode = 'deep'
470
+ AND scans.status = 'running'
471
+ AND scans.canceled_at IS NULL
472
+ AND scans.target_revision = ?
473
+ AND scans.target_snapshot_digest = ?
474
+ AND scans.target_device = ?
475
+ AND scans.target_inode = ?
476
+ AND scans.handoff_status = 'delivered'
477
+ AND scans.handoff_claim_token IS NULL
478
+ AND COALESCE(scans.deep_scan_owner_thread_id, workspaces.thread_id) <> ?
479
+ AND workspaces.active_scan_id = scans.id
480
+ AND deep_scan_runs.status = 'succeeded'
481
+ AND deep_scan_runs.phase = 'terminal'
482
+ AND deep_scan_runs.cancel_requested = 0
483
+ AND deep_scan_runs.terminal_reason IN ('saturated', 'capped')
484
+ AND deep_scan_runs.manifest_path IS NOT NULL
485
+ AND deep_scan_runs.completed_at IS NOT NULL
486
+ ORDER BY deep_scan_runs.completed_at DESC, scans.updated_at DESC, scans.id
487
+ LIMIT 1
488
+ """,
489
+ (
490
+ target_path,
491
+ scope,
492
+ revision,
493
+ snapshot_digest,
494
+ target_device,
495
+ target_inode,
496
+ thread_id,
497
+ ),
498
+ ).fetchone()
499
+
500
+
501
+ def pending_deep_workspace_for_target(
502
+ connection: sqlite3.Connection, thread_id: str, target_path: str, scope: str
503
+ ) -> sqlite3.Row | None:
504
+ return connection.execute(
505
+ """
506
+ SELECT *
507
+ FROM workspaces
508
+ WHERE thread_id = ?
509
+ AND target_path = ?
510
+ AND default_scope = ?
511
+ AND default_mode = 'deep'
512
+ AND active_scan_id IS NULL
513
+ ORDER BY updated_at DESC, created_at DESC, id
514
+ LIMIT 1
515
+ """,
516
+ (thread_id, target_path, scope),
517
+ ).fetchone()
518
+
519
+
520
+ def setup_ui_opt_out_enabled(connection: sqlite3.Connection) -> bool:
521
+ row = connection.execute(
522
+ "SELECT skip_setup_ui FROM setup_preferences WHERE singleton = 1"
523
+ ).fetchone()
524
+ return row is not None and bool(row["skip_setup_ui"])
525
+
526
+
527
+ def begin_deep_scan_for_scan(
528
+ connection: sqlite3.Connection,
529
+ scan_id: str,
530
+ thread_id: str,
531
+ args: argparse.Namespace,
532
+ ) -> dict[str, Any]:
533
+ scan_id = require_uuid(scan_id, "scan-id")
534
+ scan, _ = require_owned_scan(connection, scan_id, thread_id)
535
+ require_current_continuation(
536
+ scan,
537
+ args.claim_token,
538
+ error_message="Deep Scan orchestration is owned by another continuation.",
539
+ )
540
+ if scan["mode"] != "deep":
541
+ raise SystemExit("Deep Scan orchestration requires a scan in deep mode.")
542
+ existing = connection.execute(
543
+ "SELECT scan_id FROM deep_scan_runs WHERE scan_id = ?", (scan_id,)
544
+ ).fetchone()
545
+ if existing is not None:
546
+ return deep_scan_result(connection, scan_id, start_disposition="joined")
547
+ config = effective_deep_scan_config(args)
548
+ workflow_version = optional_text(args.workflow_version, maximum=256)
549
+ if workflow_version is None:
550
+ raise SystemExit("workflow-version is required.")
551
+ connection.execute("BEGIN IMMEDIATE")
552
+ try:
553
+ scan, _ = require_owned_scan(connection, scan_id, thread_id)
554
+ require_current_continuation(
555
+ scan,
556
+ args.claim_token,
557
+ error_message="Deep Scan orchestration is owned by another continuation.",
558
+ )
559
+ ensure_deep_scan_run(connection, scan, config, workflow_version, now())
560
+ connection.commit()
561
+ except BaseException:
562
+ connection.rollback()
563
+ raise
564
+ return deep_scan_result(connection, scan_id, start_disposition="created")
565
+
566
+
567
+ def begin_deep_scan_for_target(
568
+ connection: sqlite3.Connection, args: argparse.Namespace, thread_id: str
569
+ ) -> dict[str, Any]:
570
+ target = require_target(args.target_path)
571
+ require_scannable_target(target)
572
+ scope = require_scope(args.scope, "deep", target)
573
+ target_path = str(target)
574
+ existing = existing_deep_scan_for_target(connection, thread_id, target_path, scope)
575
+ if existing is not None:
576
+ return begin_deep_scan_for_scan(connection, existing["id"], thread_id, args)
577
+ target_metadata = target.stat()
578
+ revision = git_revision(target)
579
+ target_snapshot_digest = (
580
+ directory_content_digest(target)
581
+ if revision == "unversioned"
582
+ else worktree_content_digest(target)
583
+ )
584
+ target_device = serialize_filesystem_identity(target_metadata.st_dev)
585
+ target_inode = serialize_filesystem_identity(target_metadata.st_ino)
586
+ scope_file_count = directory_snapshot_regular_file_count(
587
+ target if scope == "." else target / scope
588
+ )
589
+ connection.execute("BEGIN IMMEDIATE")
590
+ try:
591
+ existing = existing_deep_scan_for_target(connection, thread_id, target_path, scope)
592
+ if existing is not None:
593
+ existing_run = connection.execute(
594
+ "SELECT 1 FROM deep_scan_runs WHERE scan_id = ?", (existing["id"],)
595
+ ).fetchone()
596
+ if existing_run is None:
597
+ config = effective_deep_scan_config(args)
598
+ workflow_version = optional_text(args.workflow_version, maximum=256)
599
+ if workflow_version is None:
600
+ raise SystemExit("workflow-version is required.")
601
+ ensure_deep_scan_run(connection, existing, config, workflow_version, now())
602
+ connection.commit()
603
+ return deep_scan_result(
604
+ connection,
605
+ existing["id"],
606
+ start_disposition="joined" if existing_run is not None else "created",
607
+ )
608
+ pending_workspace = pending_deep_workspace_for_target(
609
+ connection, thread_id, target_path, scope
610
+ )
611
+ if pending_workspace is not None and not setup_ui_opt_out_enabled(connection):
612
+ raise SystemExit(
613
+ "A matching Codex Security setup workspace is waiting for Start scan. "
614
+ "Finish that setup and retry with its scanId."
615
+ )
616
+ current_target = require_remediation_target(target_path)
617
+ current_metadata = current_target.stat()
618
+ if (current_metadata.st_dev, current_metadata.st_ino) != (
619
+ target_metadata.st_dev,
620
+ target_metadata.st_ino,
621
+ ):
622
+ raise SystemExit(
623
+ "The selected scan target changed while the scan was starting. Try again."
624
+ )
625
+ terminal = terminal_deep_scan_for_target_snapshot(
626
+ connection,
627
+ thread_id,
628
+ target_path,
629
+ scope,
630
+ revision,
631
+ target_snapshot_digest,
632
+ target_device,
633
+ target_inode,
634
+ )
635
+ if terminal is not None:
636
+ connection.commit()
637
+ return deep_scan_result(
638
+ connection,
639
+ terminal["id"],
640
+ start_disposition="joined",
641
+ )
642
+ config = effective_deep_scan_config(args)
643
+ workflow_version = optional_text(args.workflow_version, maximum=256)
644
+ if workflow_version is None:
645
+ raise SystemExit("workflow-version is required.")
646
+ root = (
647
+ Path(args.scan_root).expanduser().resolve() if args.scan_root else state_dir() / "scans"
648
+ )
649
+ target_root = (root / safe_segment(target.name)).resolve()
650
+ if target_root == target or target in target_root.parents:
651
+ raise SystemExit("The scan artifact directory must be outside the selected target.")
652
+ target_root.mkdir(parents=True, exist_ok=True)
653
+ user_context = optional_text(args.user_context)
654
+ workspace_id = str(uuid.uuid4())
655
+ scan_id = str(uuid.uuid4())
656
+ timestamp = now()
657
+ target_id = ensure_security_target(connection, target_path)
658
+ scan_dir = Path(
659
+ tempfile.mkdtemp(
660
+ prefix=f"{safe_segment(revision)}_{compact_timestamp()}_",
661
+ dir=target_root,
662
+ )
663
+ ).resolve()
664
+ connection.execute(
665
+ """
666
+ INSERT INTO workspaces (
667
+ id, thread_id, target_id, target_path, target_title, default_scope, default_mode,
668
+ user_context, submitted, created_at, updated_at
669
+ ) VALUES (?, ?, ?, ?, ?, ?, 'deep', ?, 1, ?, ?)
670
+ """,
671
+ (
672
+ workspace_id,
673
+ thread_id,
674
+ target_id,
675
+ target_path,
676
+ target.name,
677
+ scope,
678
+ user_context,
679
+ timestamp,
680
+ timestamp,
681
+ ),
682
+ )
683
+ connection.execute(
684
+ """
685
+ INSERT INTO scans (
686
+ id, workspace_id, target_id, target_path, target_revision, target_snapshot_digest,
687
+ target_device, target_inode, scope, mode, user_context,
688
+ deep_scan_owner_thread_id, scan_dir, status, phase, handoff_status,
689
+ started_at, created_at, updated_at
690
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'deep', ?, ?, ?, 'running', 'preflight',
691
+ 'delivered', ?, ?, ?)
692
+ """,
693
+ (
694
+ scan_id,
695
+ workspace_id,
696
+ target_id,
697
+ target_path,
698
+ revision,
699
+ target_snapshot_digest,
700
+ target_device,
701
+ target_inode,
702
+ scope,
703
+ user_context,
704
+ thread_id,
705
+ str(scan_dir),
706
+ timestamp,
707
+ timestamp,
708
+ timestamp,
709
+ ),
710
+ )
711
+ connection.execute(
712
+ """
713
+ INSERT INTO scan_progress (
714
+ scan_id, scope_file_count, review_items_total, review_items_completed,
715
+ reportable_findings_count, updated_at
716
+ ) VALUES (?, ?, 0, 0, 0, ?)
717
+ """,
718
+ (scan_id, scope_file_count, timestamp),
719
+ )
720
+ connection.execute(
721
+ "UPDATE workspaces SET active_scan_id = ?, updated_at = ? WHERE id = ?",
722
+ (scan_id, timestamp, workspace_id),
723
+ )
724
+ scan = require_scan(connection, scan_id)
725
+ ensure_deep_scan_run(connection, scan, config, workflow_version, timestamp)
726
+ connection.commit()
727
+ except BaseException:
728
+ connection.rollback()
729
+ raise
730
+ return deep_scan_result(connection, scan_id, start_disposition="created")
731
+
732
+
733
+ def begin_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
734
+ thread_id = optional_text(args.thread_id, maximum=512)
735
+ if thread_id is None:
736
+ raise SystemExit("thread-id is required.")
737
+ if args.scan_id:
738
+ if args.user_context is not None or args.scope != ".":
739
+ raise SystemExit("scan-id cannot be combined with target setup fields.")
740
+ return begin_deep_scan_for_scan(connection, args.scan_id, thread_id, args)
741
+ if args.claim_token is not None:
742
+ raise SystemExit("claim-token is only valid with scan-id.")
743
+ return begin_deep_scan_for_target(connection, args, thread_id)
744
+
745
+
746
+ def get_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
747
+ scan, _ = require_owned_scan(connection, args.scan_id, args.thread_id)
748
+ return deep_scan_result(connection, scan["id"])
749
+
750
+
751
+ def require_deep_scan_worker(connection: sqlite3.Connection, worker_id: str) -> sqlite3.Row:
752
+ worker_id = require_uuid(worker_id, "worker-id")
753
+ row = connection.execute(
754
+ "SELECT * FROM deep_scan_workers WHERE id = ?", (worker_id,)
755
+ ).fetchone()
756
+ if row is None:
757
+ raise SystemExit("Codex Security Deep Scan worker not found.")
758
+ return row
759
+
760
+
761
+ def require_running_deep_scan(
762
+ connection: sqlite3.Connection, scan_id: str
763
+ ) -> tuple[sqlite3.Row, sqlite3.Row]:
764
+ run = require_deep_scan_run(connection, scan_id)
765
+ scan = require_scan(connection, run["scan_id"])
766
+ if run["status"] != "running" or run["cancel_requested"]:
767
+ raise SystemExit("Only a running Deep Scan can update orchestration state.")
768
+ if scan["status"] != "running" or scan["canceled_at"] is not None:
769
+ raise SystemExit("Only a running scan can update Deep Scan orchestration state.")
770
+ return run, scan
771
+
772
+
773
+ def require_worker_transition(current: str, requested: str) -> None:
774
+ allowed = {
775
+ "queued": {"queued", "running", "failed", "canceled"},
776
+ "running": {"running", "succeeded", "failed", "canceled"},
777
+ "succeeded": {"succeeded"},
778
+ "failed": {"failed"},
779
+ "canceled": {"canceled"},
780
+ }
781
+ if requested not in allowed[current]:
782
+ raise SystemExit(f"Deep Scan worker cannot transition from {current} to {requested}.")
783
+
784
+
785
+ def upsert_deep_scan_worker(
786
+ connection: sqlite3.Connection, args: argparse.Namespace
787
+ ) -> dict[str, Any]:
788
+ scan_id = require_uuid(args.scan_id, "scan-id")
789
+ worker_id = require_uuid(args.worker_id, "worker-id")
790
+ connection.execute("BEGIN IMMEDIATE")
791
+ try:
792
+ run = require_deep_scan_run(connection, scan_id)
793
+ scan = require_scan(connection, scan_id)
794
+ existing = connection.execute(
795
+ "SELECT * FROM deep_scan_workers WHERE id = ?", (worker_id,)
796
+ ).fetchone()
797
+ cleanup_update = (
798
+ existing is not None
799
+ and args.status == "canceled"
800
+ and existing["status"] in {"queued", "running", "canceled"}
801
+ and run["status"] in {"succeeded", "failed", "canceled", "interrupted"}
802
+ )
803
+ terminal_repeat = (
804
+ existing is not None
805
+ and existing["status"] == args.status
806
+ and args.status in {"succeeded", "failed", "canceled"}
807
+ )
808
+ if not cleanup_update and not terminal_repeat:
809
+ require_running_deep_scan(connection, scan_id)
810
+ prompt_path = deep_scan_path(scan, args.prompt_path, "Worker prompt path", kind="file")
811
+ artifact_dir = deep_scan_path(
812
+ scan, args.artifact_dir, "Worker artifact directory", kind="directory"
813
+ )
814
+ result_manifest_path = (
815
+ deep_scan_path(
816
+ scan,
817
+ args.result_manifest_path,
818
+ "Worker result manifest path",
819
+ kind="file",
820
+ )
821
+ if args.result_manifest_path
822
+ else None
823
+ )
824
+ timestamp = now()
825
+ if existing is None:
826
+ if args.kind == "dedup":
827
+ raise SystemExit("Create dedup workers with claim-deep-scan-dedup.")
828
+ if args.status not in {"queued", "running"}:
829
+ raise SystemExit("A new Deep Scan worker must be queued or running.")
830
+ if (
831
+ args.kind == "setup"
832
+ and connection.execute(
833
+ "SELECT 1 FROM deep_scan_workers WHERE scan_id = ? AND kind = 'setup'",
834
+ (scan_id,),
835
+ ).fetchone()
836
+ is not None
837
+ ):
838
+ raise SystemExit("A Deep Scan can have only one setup worker.")
839
+ attempt = (
840
+ args.attempt if args.attempt is not None else (1 if args.status == "running" else 0)
841
+ )
842
+ if args.status == "running" and attempt < 1:
843
+ raise SystemExit("A running Deep Scan worker attempt must be at least one.")
844
+ if args.kind == "discovery":
845
+ if run["discovery_runs_dispatched"] >= run["max_discovery_runs"]:
846
+ raise SystemExit("Deep Scan maximum discovery runs has been reached.")
847
+ connection.execute(
848
+ """
849
+ UPDATE deep_scan_runs
850
+ SET discovery_runs_dispatched = discovery_runs_dispatched + 1,
851
+ phase = 'discovery', updated_at = ?
852
+ WHERE scan_id = ?
853
+ """,
854
+ (timestamp, scan_id),
855
+ )
856
+ connection.execute(
857
+ """
858
+ INSERT INTO deep_scan_workers (
859
+ id, scan_id, kind, status, prompt_path, artifact_dir, attempt,
860
+ sdk_thread_id, error_message, created_at, started_at, updated_at
861
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
862
+ """,
863
+ (
864
+ worker_id,
865
+ scan_id,
866
+ args.kind,
867
+ args.status,
868
+ prompt_path,
869
+ artifact_dir,
870
+ attempt,
871
+ optional_text(args.sdk_thread_id, maximum=512),
872
+ optional_text(args.error_message, maximum=2400),
873
+ timestamp,
874
+ timestamp if args.status == "running" else None,
875
+ timestamp,
876
+ ),
877
+ )
878
+ connection.commit()
879
+ return deep_scan_result(connection, scan_id)
880
+
881
+ if existing["scan_id"] != scan_id or existing["kind"] != args.kind:
882
+ raise SystemExit("Deep Scan worker identity does not match its persisted run and kind.")
883
+ if existing["prompt_path"] != prompt_path or existing["artifact_dir"] != artifact_dir:
884
+ raise SystemExit("Deep Scan worker prompt and artifact paths are immutable.")
885
+ require_worker_transition(existing["status"], args.status)
886
+ if terminal_repeat:
887
+ repeated_attempt = args.attempt if args.attempt is not None else existing["attempt"]
888
+ repeated_thread_id = optional_text(args.sdk_thread_id, maximum=512)
889
+ repeated_error = optional_text(args.error_message, maximum=2400)
890
+ repeated_result_path = result_manifest_path or existing["result_manifest_path"]
891
+ if (
892
+ repeated_attempt != existing["attempt"]
893
+ or repeated_result_path != existing["result_manifest_path"]
894
+ or (
895
+ repeated_thread_id is not None
896
+ and repeated_thread_id != existing["sdk_thread_id"]
897
+ )
898
+ or repeated_error is not None
899
+ and repeated_error != existing["error_message"]
900
+ ):
901
+ raise SystemExit("Deep Scan worker terminal state is immutable.")
902
+ connection.commit()
903
+ return deep_scan_result(connection, scan_id)
904
+ attempt = args.attempt if args.attempt is not None else existing["attempt"]
905
+ if attempt < existing["attempt"]:
906
+ raise SystemExit("Deep Scan worker attempt cannot decrease.")
907
+ if args.status == "running" and attempt < 1:
908
+ raise SystemExit("A running Deep Scan worker attempt must be at least one.")
909
+ if args.kind == "dedup" and args.status == "succeeded":
910
+ raise SystemExit("Commit a successful dedup worker with commit-deep-scan-dedup.")
911
+ if args.kind == "discovery" and args.status == "succeeded" and result_manifest_path is None:
912
+ result_manifest_path = existing["result_manifest_path"]
913
+ if result_manifest_path is None:
914
+ raise SystemExit("A successful Deep Scan worker requires a result manifest.")
915
+
916
+ completion_sequence = existing["completion_sequence"]
917
+ merge_state = existing["merge_state"]
918
+ if args.kind == "discovery" and args.status == "succeeded" and completion_sequence is None:
919
+ completion_sequence = run["completion_sequence"] + 1
920
+ merge_state = "buffered"
921
+ connection.execute(
922
+ """
923
+ UPDATE deep_scan_runs
924
+ SET completion_sequence = ?, phase = 'discovery', updated_at = ?
925
+ WHERE scan_id = ?
926
+ """,
927
+ (completion_sequence, timestamp, scan_id),
928
+ )
929
+ completed_at = (
930
+ timestamp
931
+ if args.status in {"succeeded", "failed", "canceled"}
932
+ else existing["completed_at"]
933
+ )
934
+ error_message = optional_text(args.error_message, maximum=2400)
935
+ if error_message is None and args.status != "succeeded":
936
+ error_message = existing["error_message"]
937
+ started_at = existing["started_at"] or (timestamp if args.status == "running" else None)
938
+ connection.execute(
939
+ """
940
+ UPDATE deep_scan_workers
941
+ SET status = ?, result_manifest_path = ?, attempt = ?,
942
+ sdk_thread_id = COALESCE(?, sdk_thread_id),
943
+ completion_sequence = ?, merge_state = ?,
944
+ error_message = ?,
945
+ started_at = ?, completed_at = ?, updated_at = ?
946
+ WHERE id = ?
947
+ """,
948
+ (
949
+ args.status,
950
+ result_manifest_path or existing["result_manifest_path"],
951
+ attempt,
952
+ optional_text(args.sdk_thread_id, maximum=512),
953
+ completion_sequence,
954
+ merge_state,
955
+ error_message,
956
+ started_at,
957
+ completed_at,
958
+ timestamp,
959
+ worker_id,
960
+ ),
961
+ )
962
+ connection.commit()
963
+ except BaseException:
964
+ connection.rollback()
965
+ raise
966
+ return deep_scan_result(connection, scan_id)
967
+
968
+
969
+ def claim_deep_scan_dedup(
970
+ connection: sqlite3.Connection, args: argparse.Namespace
971
+ ) -> dict[str, Any]:
972
+ scan_id = require_uuid(args.scan_id, "scan-id")
973
+ worker_id = require_uuid(args.worker_id, "worker-id")
974
+ input_ids = [require_uuid(value, "input-worker-id") for value in args.input_worker_id]
975
+ if len(set(input_ids)) != len(input_ids):
976
+ raise SystemExit("Dedup input worker IDs must be unique.")
977
+ connection.execute("BEGIN IMMEDIATE")
978
+ try:
979
+ run, scan = require_running_deep_scan(connection, scan_id)
980
+ prompt_path = deep_scan_path(scan, args.prompt_path, "Dedup prompt path", kind="file")
981
+ artifact_dir = deep_scan_path(
982
+ scan, args.artifact_dir, "Dedup artifact directory", kind="directory"
983
+ )
984
+ existing = connection.execute(
985
+ "SELECT * FROM deep_scan_workers WHERE id = ?", (worker_id,)
986
+ ).fetchone()
987
+ if existing is not None:
988
+ persisted_inputs = [
989
+ row["discovery_worker_id"]
990
+ for row in connection.execute(
991
+ """
992
+ SELECT discovery_worker_id
993
+ FROM deep_scan_dedup_inputs
994
+ WHERE dedup_worker_id = ?
995
+ ORDER BY input_order
996
+ """,
997
+ (worker_id,),
998
+ )
999
+ ]
1000
+ if (
1001
+ existing["scan_id"] == scan_id
1002
+ and existing["kind"] == "dedup"
1003
+ and existing["prompt_path"] == prompt_path
1004
+ and existing["artifact_dir"] == artifact_dir
1005
+ and persisted_inputs == input_ids
1006
+ ):
1007
+ connection.commit()
1008
+ return deep_scan_result(connection, scan_id)
1009
+ raise SystemExit("Dedup worker ID is already used by a different reducer claim.")
1010
+ active_reducer = connection.execute(
1011
+ """
1012
+ SELECT 1 FROM deep_scan_workers
1013
+ WHERE scan_id = ? AND kind = 'dedup' AND status IN ('queued', 'running')
1014
+ """,
1015
+ (scan_id,),
1016
+ ).fetchone()
1017
+ if active_reducer is not None:
1018
+ raise SystemExit("Only one Deep Scan dedup worker can run at a time.")
1019
+ buffered_ids = [
1020
+ row["id"]
1021
+ for row in connection.execute(
1022
+ """
1023
+ SELECT id FROM deep_scan_workers
1024
+ WHERE scan_id = ? AND kind = 'discovery'
1025
+ AND status = 'succeeded' AND merge_state = 'buffered'
1026
+ ORDER BY completion_sequence
1027
+ """,
1028
+ (scan_id,),
1029
+ )
1030
+ ]
1031
+ if input_ids != buffered_ids[: len(input_ids)]:
1032
+ raise SystemExit(
1033
+ "A Deep Scan dedup worker must claim an ordered prefix of buffered discovery "
1034
+ "results in completion order."
1035
+ )
1036
+ hard_cap_singleton = (
1037
+ len(input_ids) == 1
1038
+ and run["discovery_runs_dispatched"] >= run["max_discovery_runs"]
1039
+ and connection.execute(
1040
+ """
1041
+ SELECT 1 FROM deep_scan_workers
1042
+ WHERE scan_id = ? AND kind = 'discovery' AND status IN ('queued', 'running')
1043
+ LIMIT 1
1044
+ """,
1045
+ (scan_id,),
1046
+ ).fetchone()
1047
+ is None
1048
+ )
1049
+ minimum_inputs = 1 if run["canonical_inventory_path"] or hard_cap_singleton else 2
1050
+ if len(input_ids) < minimum_inputs:
1051
+ raise SystemExit(
1052
+ "The first Deep Scan dedup requires two buffered discovery results."
1053
+ if minimum_inputs == 2
1054
+ else "A Deep Scan dedup requires at least one buffered discovery result."
1055
+ )
1056
+ timestamp = now()
1057
+ connection.execute(
1058
+ """
1059
+ INSERT INTO deep_scan_workers (
1060
+ id, scan_id, kind, status, prompt_path, artifact_dir,
1061
+ created_at, updated_at
1062
+ ) VALUES (?, ?, 'dedup', 'queued', ?, ?, ?, ?)
1063
+ """,
1064
+ (worker_id, scan_id, prompt_path, artifact_dir, timestamp, timestamp),
1065
+ )
1066
+ for input_order, input_id in enumerate(input_ids):
1067
+ connection.execute(
1068
+ """
1069
+ INSERT INTO deep_scan_dedup_inputs (
1070
+ scan_id, dedup_worker_id, discovery_worker_id, input_order
1071
+ ) VALUES (?, ?, ?, ?)
1072
+ """,
1073
+ (scan_id, worker_id, input_id, input_order),
1074
+ )
1075
+ connection.execute(
1076
+ f"""
1077
+ UPDATE deep_scan_workers
1078
+ SET merge_state = 'merging', updated_at = ?
1079
+ WHERE scan_id = ? AND id IN ({",".join("?" for _ in input_ids)})
1080
+ """,
1081
+ (timestamp, scan_id, *input_ids),
1082
+ )
1083
+ connection.execute(
1084
+ "UPDATE deep_scan_runs SET phase = 'reducing', updated_at = ? WHERE scan_id = ?",
1085
+ (timestamp, scan_id),
1086
+ )
1087
+ connection.commit()
1088
+ except BaseException:
1089
+ connection.rollback()
1090
+ raise
1091
+ return deep_scan_result(connection, scan_id)
1092
+
1093
+
1094
+ def commit_deep_scan_dedup(
1095
+ connection: sqlite3.Connection, args: argparse.Namespace
1096
+ ) -> dict[str, Any]:
1097
+ scan_id = require_uuid(args.scan_id, "scan-id")
1098
+ worker_id = require_uuid(args.worker_id, "worker-id")
1099
+ connection.execute("BEGIN IMMEDIATE")
1100
+ try:
1101
+ run = require_deep_scan_run(connection, scan_id)
1102
+ scan = require_scan(connection, scan_id)
1103
+ worker = require_deep_scan_worker(connection, worker_id)
1104
+ if worker["scan_id"] != scan_id or worker["kind"] != "dedup":
1105
+ raise SystemExit("Dedup worker does not belong to this Deep Scan.")
1106
+ if worker["status"] == "succeeded":
1107
+ connection.commit()
1108
+ return deep_scan_result(connection, scan_id)
1109
+ require_running_deep_scan(connection, scan_id)
1110
+ if worker["status"] not in {"queued", "running"}:
1111
+ raise SystemExit("Only an active dedup worker can commit a result.")
1112
+ canonical_inventory_path = deep_scan_path(
1113
+ scan,
1114
+ args.canonical_inventory_path,
1115
+ "Canonical inventory path",
1116
+ kind="file",
1117
+ )
1118
+ canonical_finding_report_path = deep_scan_path(
1119
+ scan,
1120
+ args.canonical_finding_report_path,
1121
+ "Canonical finding report path",
1122
+ kind="file",
1123
+ )
1124
+ canonical_candidates_path = deep_scan_path(
1125
+ scan,
1126
+ args.canonical_candidates_path,
1127
+ "Canonical candidates path",
1128
+ kind="file",
1129
+ )
1130
+ dedupe_report_path = deep_scan_path(
1131
+ scan, args.dedupe_report_path, "Canonical dedupe report path", kind="file"
1132
+ )
1133
+ seed_research_path = deep_scan_path(
1134
+ scan, args.seed_research_path, "Canonical seed research path", kind="file"
1135
+ )
1136
+ work_ledger_path = deep_scan_path(
1137
+ scan, args.work_ledger_path, "Canonical work ledger path", kind="file"
1138
+ )
1139
+ raw_candidates_path = deep_scan_path(
1140
+ scan, args.raw_candidates_path, "Canonical raw candidates path", kind="file"
1141
+ )
1142
+ coverage_ledger_path = deep_scan_path(
1143
+ scan, args.coverage_ledger_path, "Canonical coverage ledger path", kind="file"
1144
+ )
1145
+ findings_dir = deep_scan_path(
1146
+ scan, args.findings_dir, "Canonical findings directory", kind="directory"
1147
+ )
1148
+ persisted_canonical_paths = {
1149
+ "canonical inventory": run["canonical_inventory_path"],
1150
+ "canonical finding report": run["canonical_finding_report_path"],
1151
+ "canonical candidates": run["canonical_candidates_path"],
1152
+ "dedupe report": run["dedupe_report_path"],
1153
+ "seed research": run["seed_research_path"],
1154
+ "work ledger": run["work_ledger_path"],
1155
+ "raw candidates": run["raw_candidates_path"],
1156
+ "coverage ledger": run["coverage_ledger_path"],
1157
+ "findings directory": run["findings_dir"],
1158
+ }
1159
+ submitted_canonical_paths = {
1160
+ "canonical inventory": canonical_inventory_path,
1161
+ "canonical finding report": canonical_finding_report_path,
1162
+ "canonical candidates": canonical_candidates_path,
1163
+ "dedupe report": dedupe_report_path,
1164
+ "seed research": seed_research_path,
1165
+ "work ledger": work_ledger_path,
1166
+ "raw candidates": raw_candidates_path,
1167
+ "coverage ledger": coverage_ledger_path,
1168
+ "findings directory": findings_dir,
1169
+ }
1170
+ if run["canonical_inventory_path"] is not None:
1171
+ changed = [
1172
+ label
1173
+ for label, persisted in persisted_canonical_paths.items()
1174
+ if submitted_canonical_paths[label] != persisted
1175
+ ]
1176
+ if changed:
1177
+ raise SystemExit(
1178
+ "Deep Scan canonical artifact paths are immutable after the first dedup: "
1179
+ f"{', '.join(changed)}."
1180
+ )
1181
+ result_manifest_path = deep_scan_path(
1182
+ scan,
1183
+ args.result_manifest_path,
1184
+ "Dedup result manifest path",
1185
+ kind="file",
1186
+ )
1187
+ inputs = list(
1188
+ connection.execute(
1189
+ """
1190
+ SELECT workers.*
1191
+ FROM deep_scan_dedup_inputs AS inputs
1192
+ JOIN deep_scan_workers AS workers ON workers.id = inputs.discovery_worker_id
1193
+ WHERE inputs.dedup_worker_id = ?
1194
+ ORDER BY inputs.input_order
1195
+ """,
1196
+ (worker_id,),
1197
+ )
1198
+ )
1199
+ if not inputs or any(row["merge_state"] != "merging" for row in inputs):
1200
+ raise SystemExit("Dedup inputs are not in the claimed merging state.")
1201
+ timestamp = now()
1202
+ connection.execute(
1203
+ """
1204
+ UPDATE deep_scan_workers
1205
+ SET merge_state = 'merged', updated_at = ?
1206
+ WHERE id IN (
1207
+ SELECT discovery_worker_id FROM deep_scan_dedup_inputs
1208
+ WHERE dedup_worker_id = ?
1209
+ )
1210
+ """,
1211
+ (timestamp, worker_id),
1212
+ )
1213
+ connection.execute(
1214
+ """
1215
+ UPDATE deep_scan_workers
1216
+ SET status = 'succeeded', result_manifest_path = ?,
1217
+ error_message = NULL, started_at = COALESCE(started_at, ?),
1218
+ completed_at = ?, updated_at = ?
1219
+ WHERE id = ?
1220
+ """,
1221
+ (result_manifest_path, timestamp, timestamp, timestamp, worker_id),
1222
+ )
1223
+ no_new_streak = (
1224
+ 0 if args.new_findings_count > 0 else run["consecutive_no_new"] + len(inputs)
1225
+ )
1226
+ connection.execute(
1227
+ """
1228
+ UPDATE deep_scan_runs
1229
+ SET phase = 'discovery', consecutive_no_new = ?,
1230
+ canonical_inventory_path = ?, canonical_finding_report_path = ?,
1231
+ canonical_candidates_path = ?, dedupe_report_path = ?,
1232
+ seed_research_path = ?, work_ledger_path = ?, raw_candidates_path = ?,
1233
+ coverage_ledger_path = ?, findings_dir = ?, updated_at = ?
1234
+ WHERE scan_id = ?
1235
+ """,
1236
+ (
1237
+ no_new_streak,
1238
+ canonical_inventory_path,
1239
+ canonical_finding_report_path,
1240
+ canonical_candidates_path,
1241
+ dedupe_report_path,
1242
+ seed_research_path,
1243
+ work_ledger_path,
1244
+ raw_candidates_path,
1245
+ coverage_ledger_path,
1246
+ findings_dir,
1247
+ timestamp,
1248
+ scan_id,
1249
+ ),
1250
+ )
1251
+ connection.commit()
1252
+ except BaseException:
1253
+ connection.rollback()
1254
+ raise
1255
+ return deep_scan_result(connection, scan_id)
1256
+
1257
+
1258
+ def finish_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
1259
+ scan_id = require_uuid(args.scan_id, "scan-id")
1260
+ omitted_worker_ids = [
1261
+ require_uuid(value, "omitted-worker-id") for value in args.omitted_worker_id
1262
+ ]
1263
+ if len(set(omitted_worker_ids)) != len(omitted_worker_ids):
1264
+ raise SystemExit("Omitted Deep Scan worker IDs must be unique.")
1265
+ connection.execute("BEGIN IMMEDIATE")
1266
+ try:
1267
+ run = require_deep_scan_run(connection, scan_id)
1268
+ scan = require_scan(connection, scan_id)
1269
+ manifest_path = deep_scan_path(
1270
+ scan, args.manifest_path, "Deep Scan coordinator manifest path", kind="file"
1271
+ )
1272
+ buffered_worker_ids = [
1273
+ row["id"]
1274
+ for row in connection.execute(
1275
+ """
1276
+ SELECT id
1277
+ FROM deep_scan_workers
1278
+ WHERE scan_id = ? AND kind = 'discovery' AND merge_state = 'buffered'
1279
+ ORDER BY completion_sequence, id
1280
+ """,
1281
+ (scan_id,),
1282
+ )
1283
+ ]
1284
+ omissions_match = (
1285
+ set(omitted_worker_ids) == set(buffered_worker_ids)
1286
+ if args.terminal_reason == "saturated"
1287
+ else not omitted_worker_ids and not buffered_worker_ids
1288
+ )
1289
+ if run["status"] == "succeeded":
1290
+ if (
1291
+ run["terminal_reason"] != args.terminal_reason
1292
+ or run["manifest_path"] not in {None, manifest_path}
1293
+ or not omissions_match
1294
+ ):
1295
+ raise SystemExit(
1296
+ "Deep Scan terminal state is immutable; finish must exactly replay its "
1297
+ "terminal reason, manifest path, and omitted worker IDs."
1298
+ )
1299
+ if run["manifest_path"] is None:
1300
+ connection.execute(
1301
+ "UPDATE deep_scan_runs SET manifest_path = ?, updated_at = ? WHERE scan_id = ?",
1302
+ (manifest_path, now(), scan_id),
1303
+ )
1304
+ connection.commit()
1305
+ return deep_scan_result(connection, scan_id)
1306
+ require_running_deep_scan(connection, scan_id)
1307
+ if (
1308
+ args.terminal_reason == "saturated"
1309
+ and run["consecutive_no_new"] < run["stop_after_no_new"]
1310
+ ):
1311
+ raise SystemExit(
1312
+ "Deep Scan cannot finish saturated before reaching its no-new-findings threshold."
1313
+ )
1314
+ if (
1315
+ args.terminal_reason == "capped"
1316
+ and run["discovery_runs_dispatched"] < run["max_discovery_runs"]
1317
+ ):
1318
+ raise SystemExit(
1319
+ "Deep Scan cannot finish capped before reaching its configured maximum."
1320
+ )
1321
+ canonical_columns = (
1322
+ "canonical_inventory_path",
1323
+ "canonical_finding_report_path",
1324
+ "canonical_candidates_path",
1325
+ "dedupe_report_path",
1326
+ "seed_research_path",
1327
+ "work_ledger_path",
1328
+ "raw_candidates_path",
1329
+ "coverage_ledger_path",
1330
+ "findings_dir",
1331
+ )
1332
+ if any(run[column] is None for column in canonical_columns):
1333
+ raise SystemExit("Deep Scan cannot finish without canonical discovery artifacts.")
1334
+ successful_reducer = connection.execute(
1335
+ """
1336
+ SELECT 1 FROM deep_scan_workers
1337
+ WHERE scan_id = ? AND kind = 'dedup' AND status = 'succeeded'
1338
+ LIMIT 1
1339
+ """,
1340
+ (scan_id,),
1341
+ ).fetchone()
1342
+ if successful_reducer is None:
1343
+ raise SystemExit("Deep Scan cannot finish without a successful dedup worker.")
1344
+ failed_worker = connection.execute(
1345
+ """
1346
+ SELECT 1 FROM deep_scan_workers
1347
+ WHERE scan_id = ? AND status = 'failed'
1348
+ LIMIT 1
1349
+ """,
1350
+ (scan_id,),
1351
+ ).fetchone()
1352
+ if failed_worker is not None:
1353
+ raise SystemExit("Deep Scan cannot finish after a worker has failed.")
1354
+ active_worker = connection.execute(
1355
+ """
1356
+ SELECT 1 FROM deep_scan_workers
1357
+ WHERE scan_id = ? AND status IN ('queued', 'running')
1358
+ LIMIT 1
1359
+ """,
1360
+ (scan_id,),
1361
+ ).fetchone()
1362
+ if active_worker is not None:
1363
+ raise SystemExit("Deep Scan cannot finish while workers are active.")
1364
+ merging_worker = connection.execute(
1365
+ """
1366
+ SELECT 1 FROM deep_scan_workers
1367
+ WHERE scan_id = ? AND merge_state = 'merging'
1368
+ LIMIT 1
1369
+ """,
1370
+ (scan_id,),
1371
+ ).fetchone()
1372
+ if merging_worker is not None:
1373
+ raise SystemExit("Deep Scan cannot finish while discovery output is merging.")
1374
+ if args.terminal_reason == "capped" and omitted_worker_ids:
1375
+ raise SystemExit("Deep Scan capped completion cannot declare omitted buffered workers.")
1376
+ if args.terminal_reason == "capped" and buffered_worker_ids:
1377
+ raise SystemExit(
1378
+ "Deep Scan cannot finish capped while discovery output remains buffered."
1379
+ )
1380
+ if args.terminal_reason == "saturated" and not omissions_match:
1381
+ raise SystemExit(
1382
+ "Deep Scan saturated completion must exactly identify all buffered discovery "
1383
+ "workers with --omitted-worker-id."
1384
+ )
1385
+ timestamp = now()
1386
+ connection.execute(
1387
+ """
1388
+ UPDATE deep_scan_runs
1389
+ SET status = 'succeeded', phase = 'terminal', terminal_reason = ?,
1390
+ manifest_path = ?, completed_at = ?, updated_at = ?
1391
+ WHERE scan_id = ?
1392
+ """,
1393
+ (args.terminal_reason, manifest_path, timestamp, timestamp, scan_id),
1394
+ )
1395
+ cancel_active_workers(connection, scan_id, timestamp)
1396
+ connection.commit()
1397
+ except BaseException:
1398
+ connection.rollback()
1399
+ raise
1400
+ return deep_scan_result(connection, scan_id)
1401
+
1402
+
1403
+ def fail_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
1404
+ scan_id = require_uuid(args.scan_id, "scan-id")
1405
+ message = optional_text(args.message, maximum=2400)
1406
+ if message is None:
1407
+ raise SystemExit("message is required.")
1408
+ connection.execute("BEGIN IMMEDIATE")
1409
+ try:
1410
+ run = require_deep_scan_run(connection, scan_id)
1411
+ scan = require_scan(connection, scan_id)
1412
+ manifest_path = (
1413
+ deep_scan_path(
1414
+ scan,
1415
+ args.manifest_path,
1416
+ "Deep Scan failure manifest path",
1417
+ kind="file",
1418
+ )
1419
+ if args.manifest_path
1420
+ else None
1421
+ )
1422
+ if run["status"] in {"failed", "interrupted"} or scan["status"] == "failed":
1423
+ if (
1424
+ run["status"] == args.deep_status
1425
+ and scan["status"] == "failed"
1426
+ and run["error_message"] == message
1427
+ and run["manifest_path"] == manifest_path
1428
+ and scan["failure_message"] == message
1429
+ ):
1430
+ connection.commit()
1431
+ return deep_scan_result(connection, scan_id)
1432
+ raise SystemExit(
1433
+ "Deep Scan terminal failure state is immutable; failure status, message, "
1434
+ "manifest path, and parent failure must exactly match."
1435
+ )
1436
+ terminal_before_manifest = (
1437
+ args.deep_status in {"failed", "interrupted"}
1438
+ and run["status"] == "succeeded"
1439
+ and run["terminal_reason"] in {"saturated", "capped"}
1440
+ and run["manifest_path"] is None
1441
+ )
1442
+ if (run["status"] != "running" and not terminal_before_manifest) or scan[
1443
+ "status"
1444
+ ] != "running":
1445
+ raise SystemExit("Only a running Deep Scan can be failed or interrupted.")
1446
+ if run["manifest_path"] not in {None, manifest_path}:
1447
+ raise SystemExit("Deep Scan coordinator manifest path is immutable.")
1448
+ timestamp = now()
1449
+ connection.execute(
1450
+ """
1451
+ UPDATE deep_scan_runs
1452
+ SET status = ?, phase = 'terminal', cancel_requested = 1,
1453
+ error_message = ?, manifest_path = ?, completed_at = ?, updated_at = ?
1454
+ WHERE scan_id = ?
1455
+ """,
1456
+ (args.deep_status, message, manifest_path, timestamp, timestamp, scan_id),
1457
+ )
1458
+ cancel_active_workers(connection, scan_id, timestamp)
1459
+ parent_update = connection.execute(
1460
+ """
1461
+ UPDATE scans
1462
+ SET status = 'failed', failure_message = ?, completed_at = ?, updated_at = ?
1463
+ WHERE id = ? AND status = 'running'
1464
+ """,
1465
+ (message, timestamp, timestamp, scan_id),
1466
+ )
1467
+ if parent_update.rowcount != 1:
1468
+ raise SystemExit("Deep Scan failure could not be persisted to its parent scan.")
1469
+ connection.execute(
1470
+ "UPDATE scan_progress SET updated_at = ? WHERE scan_id = ?",
1471
+ (timestamp, scan_id),
1472
+ )
1473
+ connection.commit()
1474
+ except BaseException:
1475
+ connection.rollback()
1476
+ raise
1477
+ return deep_scan_result(connection, scan_id)
1478
+
1479
+
1480
+ def fail_from_parent_scan(
1481
+ connection: sqlite3.Connection,
1482
+ scan_id: str,
1483
+ message: str | None,
1484
+ timestamp: str,
1485
+ ) -> None:
1486
+ connection.execute(
1487
+ """
1488
+ UPDATE deep_scan_runs
1489
+ SET status = 'failed', phase = 'terminal', cancel_requested = 1,
1490
+ error_message = ?, completed_at = ?, updated_at = ?
1491
+ WHERE scan_id = ? AND status = 'running'
1492
+ """,
1493
+ (message, timestamp, timestamp, scan_id),
1494
+ )
1495
+ cancel_active_workers(connection, scan_id, timestamp)
1496
+
1497
+
1498
+ def cancel_from_parent_scan(connection: sqlite3.Connection, scan_id: str, timestamp: str) -> None:
1499
+ connection.execute(
1500
+ """
1501
+ UPDATE deep_scan_runs
1502
+ SET status = 'canceled', phase = 'terminal', cancel_requested = 1,
1503
+ completed_at = ?, updated_at = ?
1504
+ WHERE scan_id = ? AND status IN ('running', 'succeeded')
1505
+ """,
1506
+ (timestamp, timestamp, scan_id),
1507
+ )
1508
+ cancel_active_workers(connection, scan_id, timestamp)
1509
+
1510
+
1511
+ def cancel_active_workers(connection: sqlite3.Connection, scan_id: str, timestamp: str) -> None:
1512
+ connection.execute(
1513
+ """
1514
+ UPDATE deep_scan_workers
1515
+ SET status = 'canceled', completed_at = ?, updated_at = ?
1516
+ WHERE scan_id = ? AND status IN ('queued', 'running')
1517
+ """,
1518
+ (timestamp, timestamp, scan_id),
1519
+ )
1520
+
1521
+
1522
+ def other_running_deep_scans(
1523
+ connection: sqlite3.Connection, current_scan_id: str
1524
+ ) -> list[dict[str, str]]:
1525
+ rows = connection.execute(
1526
+ """
1527
+ SELECT id, target_path, phase, started_at, updated_at
1528
+ FROM scans
1529
+ WHERE mode = 'deep' AND status = 'running' AND id != ?
1530
+ ORDER BY updated_at DESC, started_at DESC, id
1531
+ """,
1532
+ (current_scan_id,),
1533
+ )
1534
+ return [
1535
+ {
1536
+ "phase": row["phase"],
1537
+ "scanId": row["id"],
1538
+ "startedAt": row["started_at"],
1539
+ "targetPath": row["target_path"],
1540
+ "updatedAt": row["updated_at"],
1541
+ }
1542
+ for row in rows
1543
+ ]
1544
+
1545
+
1546
+ if __name__ == "__main__":
1547
+ argparse.ArgumentParser(description=__doc__).parse_args()