@openai/codex-security 0.1.27 → 0.1.29

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 (214) hide show
  1. package/README.md +328 -59
  2. package/_bundled_plugin/examples/completed-scan/report.md +0 -1
  3. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  4. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  6. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  7. package/_bundled_plugin/references/artifact-storage.md +56 -0
  8. package/_bundled_plugin/references/config-preflight.md +7 -1
  9. package/_bundled_plugin/references/final-report.md +2 -0
  10. package/_bundled_plugin/references/scan-artifacts.md +6 -14
  11. package/_bundled_plugin/references/scan-prologue.md +2 -0
  12. package/_bundled_plugin/references/security-guidance.md +2 -0
  13. package/_bundled_plugin/scripts/deep_scan_config.py +10 -8
  14. package/_bundled_plugin/scripts/deep_scan_defaults.json +8 -0
  15. package/_bundled_plugin/scripts/finalize_scan_contract.py +2 -0
  16. package/_bundled_plugin/scripts/generate_in_scope_files.py +12 -2
  17. package/_bundled_plugin/scripts/generate_rank_input.py +1 -6
  18. package/_bundled_plugin/scripts/rank_preview.py +8 -7
  19. package/_bundled_plugin/scripts/report_projection.py +0 -1
  20. package/_bundled_plugin/scripts/reserved_artifact_paths.json +6 -0
  21. package/_bundled_plugin/scripts/windows_scan_local_files.py +1 -3
  22. package/_bundled_plugin/scripts/workbench/storage.py +18 -0
  23. package/_bundled_plugin/scripts/workbench_cli.py +13 -0
  24. package/_bundled_plugin/scripts/workbench_dashboard.py +24 -3
  25. package/_bundled_plugin/scripts/workbench_db.py +13 -13
  26. package/_bundled_plugin/scripts/workbench_saved_results.py +77 -1
  27. package/_bundled_plugin/scripts/workbench_scan_usage.py +23 -10
  28. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +2 -0
  29. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +2 -0
  30. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +5 -1
  31. package/_bundled_plugin/skills/finding-discovery/SKILL.md +2 -0
  32. package/_bundled_plugin/skills/fix-finding/SKILL.md +3 -1
  33. package/_bundled_plugin/skills/fix-finding/agents/openai.yaml +1 -1
  34. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +2 -0
  35. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +5 -1
  36. package/_bundled_plugin/skills/threat-model/SKILL.md +2 -0
  37. package/_bundled_plugin/skills/validation/SKILL.md +2 -0
  38. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +2 -0
  39. package/dist/api.d.ts +7 -23
  40. package/dist/api.d.ts.map +1 -1
  41. package/dist/api.js +109 -113
  42. package/dist/api.js.map +1 -1
  43. package/dist/auth.d.ts.map +1 -1
  44. package/dist/auth.js.map +1 -1
  45. package/dist/bulk-scan-discovery.d.ts +1 -1
  46. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  47. package/dist/bulk-scan-discovery.js +2 -2
  48. package/dist/bulk-scan-discovery.js.map +1 -1
  49. package/dist/classify-scan-severity.js.map +1 -1
  50. package/dist/classify-severity.d.ts.map +1 -1
  51. package/dist/classify-severity.js.map +1 -1
  52. package/dist/cli-scan-logs-json.d.ts +3 -0
  53. package/dist/cli-scan-logs-json.d.ts.map +1 -0
  54. package/dist/cli-scan-logs-json.js +22 -0
  55. package/dist/cli-scan-logs-json.js.map +1 -0
  56. package/dist/cli.d.ts +6 -2
  57. package/dist/cli.d.ts.map +1 -1
  58. package/dist/cli.js +802 -394
  59. package/dist/cli.js.map +1 -1
  60. package/dist/cloud-publish.js.map +1 -1
  61. package/dist/component-plan.js.map +1 -1
  62. package/dist/component-scan.d.ts +4 -2
  63. package/dist/component-scan.d.ts.map +1 -1
  64. package/dist/component-scan.js +7 -1
  65. package/dist/component-scan.js.map +1 -1
  66. package/dist/config-path.d.ts +6 -0
  67. package/dist/config-path.d.ts.map +1 -0
  68. package/dist/config-path.js +6 -0
  69. package/dist/config-path.js.map +1 -0
  70. package/dist/config.d.ts +2 -0
  71. package/dist/config.d.ts.map +1 -1
  72. package/dist/config.js +13 -3
  73. package/dist/config.js.map +1 -1
  74. package/dist/contract.js.map +1 -1
  75. package/dist/cost-model.d.ts +20 -6
  76. package/dist/cost-model.d.ts.map +1 -1
  77. package/dist/cost-model.js +73 -8
  78. package/dist/cost-model.js.map +1 -1
  79. package/dist/cost.d.ts.map +1 -1
  80. package/dist/custom-publish.js.map +1 -1
  81. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  82. package/dist/deduplication/checkpointed-review.js.map +1 -1
  83. package/dist/deduplication/codex-review.d.ts.map +1 -1
  84. package/dist/deduplication/codex-review.js +26 -4
  85. package/dist/deduplication/codex-review.js.map +1 -1
  86. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  87. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  88. package/dist/deduplication/deduplication.d.ts +12 -1
  89. package/dist/deduplication/deduplication.d.ts.map +1 -1
  90. package/dist/deduplication/deduplication.js +41 -7
  91. package/dist/deduplication/deduplication.js.map +1 -1
  92. package/dist/deduplication/refusal.d.ts +3 -0
  93. package/dist/deduplication/refusal.d.ts.map +1 -0
  94. package/dist/deduplication/refusal.js +16 -0
  95. package/dist/deduplication/refusal.js.map +1 -0
  96. package/dist/deduplication/scan.d.ts.map +1 -1
  97. package/dist/deduplication/scan.js.map +1 -1
  98. package/dist/deep-config.d.ts +17 -0
  99. package/dist/deep-config.d.ts.map +1 -0
  100. package/dist/deep-config.js +145 -0
  101. package/dist/deep-config.js.map +1 -0
  102. package/dist/deep-progress.d.ts.map +1 -1
  103. package/dist/deep-scan-defaults.d.ts +9 -0
  104. package/dist/deep-scan-defaults.d.ts.map +1 -0
  105. package/dist/deep-scan-defaults.js +10 -0
  106. package/dist/deep-scan-defaults.js.map +1 -0
  107. package/dist/errors.d.ts +1 -1
  108. package/dist/errors.d.ts.map +1 -1
  109. package/dist/errors.js +2 -2
  110. package/dist/errors.js.map +1 -1
  111. package/dist/feedback.d.ts.map +1 -1
  112. package/dist/feedback.js +21 -7
  113. package/dist/feedback.js.map +1 -1
  114. package/dist/finding-catalogue.js.map +1 -1
  115. package/dist/finding-workflow.d.ts.map +1 -1
  116. package/dist/finding-workflow.js.map +1 -1
  117. package/dist/findings-client.d.ts.map +1 -1
  118. package/dist/findings-client.js.map +1 -1
  119. package/dist/findings-import.d.ts +6 -6
  120. package/dist/github.d.ts +625 -7
  121. package/dist/github.d.ts.map +1 -1
  122. package/dist/github.js.map +1 -1
  123. package/dist/import-scan.js.map +1 -1
  124. package/dist/index.d.ts +6 -0
  125. package/dist/index.d.ts.map +1 -1
  126. package/dist/index.js +1 -0
  127. package/dist/index.js.map +1 -1
  128. package/dist/knowledge-base.d.ts.map +1 -1
  129. package/dist/knowledge-base.js +17 -6
  130. package/dist/knowledge-base.js.map +1 -1
  131. package/dist/models.d.ts.map +1 -1
  132. package/dist/models.js.map +1 -1
  133. package/dist/multiscan.d.ts +6 -6
  134. package/dist/multiscan.d.ts.map +1 -1
  135. package/dist/multiscan.js +69 -4
  136. package/dist/multiscan.js.map +1 -1
  137. package/dist/patch-tui.d.ts.map +1 -1
  138. package/dist/patch-tui.js.map +1 -1
  139. package/dist/project-config-schema.d.ts +191 -0
  140. package/dist/project-config-schema.d.ts.map +1 -0
  141. package/dist/project-config-schema.js +85 -0
  142. package/dist/project-config-schema.js.map +1 -0
  143. package/dist/project-config.d.ts +50 -0
  144. package/dist/project-config.d.ts.map +1 -0
  145. package/dist/project-config.js +220 -0
  146. package/dist/project-config.js.map +1 -0
  147. package/dist/prompt-files.d.ts +13 -0
  148. package/dist/prompt-files.d.ts.map +1 -0
  149. package/dist/prompt-files.js +74 -0
  150. package/dist/prompt-files.js.map +1 -0
  151. package/dist/publication-events.d.ts.map +1 -1
  152. package/dist/publication-events.js.map +1 -1
  153. package/dist/publish.d.ts.map +1 -1
  154. package/dist/publish.js +1 -1
  155. package/dist/publish.js.map +1 -1
  156. package/dist/result.d.ts +2 -1
  157. package/dist/result.d.ts.map +1 -1
  158. package/dist/result.js +5 -0
  159. package/dist/result.js.map +1 -1
  160. package/dist/runtime.js +4 -4
  161. package/dist/runtime.js.map +1 -1
  162. package/dist/scan-comparison.d.ts.map +1 -1
  163. package/dist/scan-comparison.js.map +1 -1
  164. package/dist/scan-dashboard.d.ts +1 -0
  165. package/dist/scan-dashboard.d.ts.map +1 -1
  166. package/dist/scan-dashboard.js +34 -22
  167. package/dist/scan-dashboard.js.map +1 -1
  168. package/dist/scan-history-renderer.d.ts.map +1 -1
  169. package/dist/scan-history-renderer.js.map +1 -1
  170. package/dist/scan-logs.d.ts +12 -5
  171. package/dist/scan-logs.d.ts.map +1 -1
  172. package/dist/scan-logs.js +76 -19
  173. package/dist/scan-logs.js.map +1 -1
  174. package/dist/scan-modes.d.ts +3 -0
  175. package/dist/scan-modes.d.ts.map +1 -0
  176. package/dist/scan-modes.js +2 -0
  177. package/dist/scan-modes.js.map +1 -0
  178. package/dist/scan-settings.d.ts +81 -0
  179. package/dist/scan-settings.d.ts.map +1 -0
  180. package/dist/scan-settings.js +123 -0
  181. package/dist/scan-settings.js.map +1 -0
  182. package/dist/security-policy-cli.js +2 -2
  183. package/dist/security-policy-cli.js.map +1 -1
  184. package/dist/security-policy.d.ts.map +1 -1
  185. package/dist/security-policy.js.map +1 -1
  186. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +3 -3
  187. package/dist/server/dashboard/app.css +1 -1
  188. package/dist/server/dashboard/app.js +7 -7
  189. package/dist/server/dashboard-types.d.ts +4 -1
  190. package/dist/server/dashboard-types.d.ts.map +1 -1
  191. package/dist/server/dashboard-types.js.map +1 -1
  192. package/dist/server/dashboard.d.ts.map +1 -1
  193. package/dist/server/dashboard.js +18 -4
  194. package/dist/server/dashboard.js.map +1 -1
  195. package/dist/server/embeddings.d.ts.map +1 -1
  196. package/dist/server/embeddings.js.map +1 -1
  197. package/dist/server/errors.d.ts.map +1 -1
  198. package/dist/server/errors.js.map +1 -1
  199. package/dist/server/findings-service.d.ts.map +1 -1
  200. package/dist/server/findings-service.js.map +1 -1
  201. package/dist/server/serve.js.map +1 -1
  202. package/dist/server/sqlite-store.d.ts.map +1 -1
  203. package/dist/server/sqlite-store.js.map +1 -1
  204. package/dist/severity-store.js.map +1 -1
  205. package/dist/targets.d.ts +2 -1
  206. package/dist/targets.d.ts.map +1 -1
  207. package/dist/targets.js +4 -4
  208. package/dist/targets.js.map +1 -1
  209. package/dist/thread-source.d.ts.map +1 -1
  210. package/dist/version.js.map +1 -1
  211. package/dist/worker-progress.d.ts.map +1 -1
  212. package/dist/worker-progress.js.map +1 -1
  213. package/package.json +31 -28
  214. package/schemas/project-config.schema.json +211 -0
package/README.md CHANGED
@@ -139,21 +139,25 @@ Constructor options:
139
139
  Options for `security.run(repository, options)` and
140
140
  `security.preflight(repository, options)`:
141
141
 
142
- | Option | Description |
143
- | ----------------------- | ------------------------------------------------------------------------------ |
144
- | `auth` | Credential source: `"auto"`, `"chatgpt"`, or `"api-key"`. |
145
- | `safetyIdentifier` | Stable hashed end-user ID for model requests; requires API-key authentication. |
146
- | `target` | Repository, repository-relative paths, committed diff, or working-tree diff. |
147
- | `mode` | `"standard"` or `"deep"`; deep mode supports repositories and paths. |
148
- | `knowledgeBasePaths` | Architecture documents, security policies, threat models, or directories. |
149
- | `outputDir` | Artifact directory outside the enclosing Git worktree. |
150
- | `archiveExisting` | Archive existing results in `outputDir` before scanning. |
151
- | `maxCostUsd` | Stop when estimated model cost exceeds this positive USD amount. |
152
- | `maxTimeHours` | Deep-scan discovery limit in hours: greater than zero, up to 96. |
153
- | `failureSeverity` | Finding-severity policy to record in the saved scan recipe. |
154
- | `parentScanId` | Parent scan ID for a rerun. |
155
- | `expectedPluginVersion` | Required original plugin version when replaying a scan. |
156
- | `signal` | `AbortSignal` to cancel a scan. |
142
+ | Option | Description |
143
+ | ------------------------------------------- | ----------------------------------------------------------------------------------- |
144
+ | `auth` | Credential source: `"auto"`, `"chatgpt"`, or `"api-key"`. |
145
+ | `safetyIdentifier` | Stable hashed end-user ID for model requests; requires API-key authentication. |
146
+ | `target` | Repository, repository-relative paths, committed diff, or working-tree diff. |
147
+ | `mode` | `"standard"` or `"deep"`; deep mode supports repositories and paths. |
148
+ | `knowledgeBasePaths` | Architecture documents, security policies, threat models, or directories. |
149
+ | `scanPrompt` / `scanPromptFile` | Additional scan instructions as text or a local file. |
150
+ | `validationPrompt` / `validationPromptFile` | Custom validation instructions as text or a local file; not Deep. |
151
+ | `postScanPrompt` / `postScanPromptFile` | Follow-up instructions as text or a local file. |
152
+ | `outputDir` | Artifact directory outside the enclosing Git worktree. |
153
+ | `archiveExisting` | Archive existing results in `outputDir` before scanning. |
154
+ | `maxCostUsd` | Stop when estimated model cost exceeds this positive USD amount. |
155
+ | `stopAfterConsecutiveErrors` | Stop deep discovery after this many consecutive errors (default: 3). |
156
+ | `maxTimeHours` | Deep-scan discovery limit in hours: greater than zero, up to 96. |
157
+ | `failureSeverity` | Severity threshold recorded in the recipe; the SDK caller decides how to handle it. |
158
+ | `parentScanId` | Parent scan ID for a rerun. |
159
+ | `expectedPluginVersion` | Required original plugin version when replaying a scan. |
160
+ | `signal` | `AbortSignal` to cancel a scan. |
157
161
 
158
162
  Follow scans with `onWorkerStatus` and `onReconnect`. `onSessionEvent` receives
159
163
  saved events with thread IDs and worker numbers. Deep scans can additionally use
@@ -164,6 +168,46 @@ and `maximum`. The maximum is a configured cap, not a percentage denominator.
164
168
  `preflight` and CLI `--dry-run` check local inputs without starting Codex or
165
169
  using the network. They don't authenticate, verify model access, resolve Python,
166
170
  inspect the plugin, or run scan-lifecycle callbacks. Dry runs print effective settings.
171
+ Deep preflight includes all six resolved deep settings and their origins in
172
+ `deepScanSources`. Applicable legacy deep configuration is validated during
173
+ preflight rather than after runtime startup.
174
+
175
+ `ScanSettings` is the shared settings type. `ScanOptions` adds callbacks,
176
+ cancellation, workflow, and runtime controls. Load the same project file used by
177
+ `scan -c` through the SDK:
178
+
179
+ ```ts
180
+ import { CodexSecurity, loadProjectConfig } from "@openai/codex-security";
181
+
182
+ const { config, options } = await loadProjectConfig("codex-security.yaml");
183
+ await using security = new CodexSecurity(config);
184
+ const result = await security.run(repository, options);
185
+ if (
186
+ options.failureSeverity !== undefined &&
187
+ result.hasFindingsAtOrAbove(options.failureSeverity)
188
+ ) {
189
+ process.exitCode = 1;
190
+ }
191
+ ```
192
+
193
+ `resolveProjectConfig(input, directory?)` accepts a typed `ProjectConfigInput`
194
+ object with the same `snake_case` keys as YAML/JSON and returns the same `{ config,
195
+ options }` pair and an immutable `sources` map. Resolved context, prompt, and output
196
+ paths have the `AbsolutePath` type. `loadProjectConfig(file, directory?)` resolves the selected file
197
+ from `directory`, which defaults to the current directory; paths inside the file
198
+ are relative to that file. Object paths are relative to the supplied directory.
199
+ Scope paths remain relative to the selected repository. Neither helper starts a
200
+ scan, reads prompt contents, or discovers another configuration file. `preflight`
201
+ and `run` apply the existing local checks and remaining legacy deep defaults.
202
+ Project-file keys follow Codex's configuration convention; SDK options keep their
203
+ existing `camelCase` names, and CLI flags keep `kebab-case`.
204
+
205
+ Override resolved SDK options with `{ ...options, maxCostUsd: 5 }`, or add
206
+ callbacks there. Direct SDK prompt-file paths use the current directory; inline
207
+ text takes precedence over its matching file. Files use the same regular-file
208
+ protections as the CLI. The SDK records `failureSeverity` without throwing or
209
+ changing process status. `hasFindingsAtOrAbove()` uses the CLI's severity ordering
210
+ and leaves the findings unchanged.
167
211
 
168
212
  ## Authentication
169
213
 
@@ -446,7 +490,73 @@ npx @openai/codex-security scan /path/to/repository --dry-run
446
490
 
447
491
  Use `scan --help` for options, `--version` for the installed version, and
448
492
  `info --json` for package, plugin, runtime, and model details. `--dry-run`
449
- runs local preflight checks.
493
+ runs local preflight checks. `info -c FILE --json` inspects resolved configuration
494
+ and its sources without a repository or runtime.
495
+
496
+ ### Project files
497
+
498
+ Use `scan -c FILE` / `scan --config FILE` to load reusable scan settings:
499
+
500
+ ```bash
501
+ codex-security scan . -c codex-security.yaml --dry-run --json
502
+ codex-security scan . -c codex-security.json --model gpt-5.6-terra
503
+ codex-security init
504
+ codex-security info -c codex-security.yaml --json
505
+ ```
506
+
507
+ Select one `.yaml`, `.yml`, or `.json` file. `scan`, `bulk-scan`, `scan-components`,
508
+ and `info` accept `-c`. They also accept an operator-set
509
+ `CODEX_SECURITY_PROJECT_CONFIG`; an explicit `-c` wins. Without either, no file is
510
+ loaded or discovered. The repository still comes from the command's target
511
+ selection. SDK `run()` and saved reruns do not load project files automatically.
512
+
513
+ The selected file is trusted like CLI options and SDK `codexOverrides`. Native
514
+ settings can start configured MCP server processes and select model-service destinations. Do not
515
+ select configuration controlled by an untrusted repository or pull request; keep
516
+ CI scanner configuration outside the checkout being assessed.
517
+
518
+ `init [file]` writes `codex-security.yaml` by default and never overwrites an
519
+ existing file. YAML starters show defaults as comments; JSON starters contain the
520
+ editor schema hint, relative to the chosen file and the invocation directory's
521
+ local package installation. `info` reports effective model details and native key sources
522
+ without dumping raw native values.
523
+
524
+ ```yaml
525
+ # yaml-language-server: $schema=./node_modules/@openai/codex-security/schemas/project-config.schema.json
526
+ scan:
527
+ mode: standard
528
+ scope:
529
+ paths: [src]
530
+ codex:
531
+ model: gpt-5.6-sol
532
+ model_reasoning_effort: xhigh
533
+ policy:
534
+ fail_on_severity: high
535
+ ```
536
+
537
+ All settings are optional; `{}` uses the existing defaults. JSON files can use a
538
+ root `$schema` string pointing to the same packaged schema. Schema hints are for
539
+ editors; the CLI uses its bundled validator without fetching URLs, coercing values,
540
+ or dropping unknown keys. Native `codex` settings retain their existing checks and
541
+ profile semantics. CLI `scan --schema --json` describes command arguments.
542
+
543
+ Settings use built-in defaults, applicable legacy deep defaults, the file, then
544
+ explicit CLI values. Lists and scope variants are replaced. `--head` can refine
545
+ a file diff and `--base` a file working-tree scope. A selected native profile can
546
+ still override root model/effort values. Existing native alias-conflict checks
547
+ and the behavior of `--provider openai` are unchanged.
548
+
549
+ File context, instruction, validation, and output paths resolve from the file's
550
+ directory. CLI file paths resolve from the invocation directory; scope paths
551
+ resolve from the repository. The file cannot select a different repository or
552
+ enable automatic patching/publication. The loader does not evaluate code,
553
+ interpolate environment values, include remote files, or merge multiple files.
554
+
555
+ Dry-run output adds `projectConfig.path` and `projectConfig.sources`, selected
556
+ prompt paths, and the finding policy without dumping raw native configuration.
557
+ Missing or invalid selected files exit `2`. Help, version, and command schema
558
+ output do not load project files. Existing scan and finding-policy exit codes
559
+ remain unchanged.
450
560
 
451
561
  ### Scan options and output
452
562
 
@@ -454,13 +564,18 @@ runs local preflight checks.
454
564
  and `--working-tree` scans staged and unstaged changes. Deep scans support
455
565
  repository and path targets.
456
566
 
567
+ Bulk scans use clean, shallow checkouts and support repository or path scopes.
568
+ They reject configured diff or working-tree scopes before starting unless each
569
+ affected CSV row supplies its own path scope.
570
+
457
571
  Working-tree snapshots include files from untracked nested Git repositories.
458
572
  Initialized submodules must be clean and checked out at the commit recorded by
459
573
  the parent repository.
460
574
 
461
- Repeat `--knowledge-base PATH` for Markdown, text, PDF, or Word (`.docx`) files.
462
- Directories are searched recursively. Bulk scans share these documents with
463
- every repository.
575
+ Repeat `--knowledge-base PATH` for UTF-8 text files with any extension (including
576
+ JSON and SARIF), PDF, or Word (`.docx`) files. Directories are searched recursively,
577
+ skipping other binary files. Explicitly supplied unsupported binary files are rejected.
578
+ Bulk scans share these documents with every repository.
464
579
 
465
580
  Use an empty output directory outside the scanned directory and enclosing Git
466
581
  worktree. On macOS/Linux, existing directories must be private to you
@@ -472,6 +587,23 @@ Scans are report-only by default. Set `--fail-on-severity high` to exit with
472
587
  `1` if a completed scan finds high or critical issues. Incomplete scans exit
473
588
  with `2`, writing available results to stdout and a coverage warning to stderr.
474
589
 
590
+ For machine-readable scan output (`--format json` or `--format jsonl`), a scan
591
+ execution failure writes one structured object to stdout:
592
+
593
+ ```json
594
+ {
595
+ "status": "failed",
596
+ "code": "SCAN_FAILED",
597
+ "message": "..."
598
+ }
599
+ ```
600
+
601
+ The command still exits with `2` for runtime, export, invalid-input, or
602
+ incomplete-scan failures, and human-readable diagnostics remain on stderr.
603
+ Use `scan --schema --format json` to discover this failure variant alongside
604
+ the successful scan output. Cancellation and termination retain their `130`
605
+ and `143` exit codes.
606
+
475
607
  ### Import findings as a saved scan
476
608
 
477
609
  Import an existing findings CSV or JSON file into local scan history and SQLite:
@@ -567,7 +699,7 @@ runtime or plugin compatibility. Older versions may omit the ID.
567
699
  ### Scan project components
568
700
 
569
701
  `scan --path` runs one scan across selected paths. To scan each local project
570
- component separately in standard mode, use `scan-components`:
702
+ component separately (standard mode by default), use `scan-components`:
571
703
 
572
704
  ```bash
573
705
  npx @openai/codex-security scan-components /path/to/project \
@@ -575,6 +707,12 @@ npx @openai/codex-security scan-components /path/to/project \
575
707
  --workers 4 --output-dir /path/outside/project/results
576
708
  ```
577
709
 
710
+ Use `-c FILE` to share settings, including `scan.mode: deep`, context and prompt
711
+ files, per-scan deep workers, cost limits, and severity policy. Component plans
712
+ override the file's scope. `output.directory` supplies the results directory when
713
+ `--output-dir` is omitted. A configured severity threshold returns exit `1` after
714
+ completed scans; failures or incomplete results return `2`.
715
+
578
716
  Use `--auto` instead of `--component` for a proposed split. Save a plan to
579
717
  review or edit, then run it with a new output directory:
580
718
 
@@ -651,6 +789,7 @@ await security.run("/path/to/repository", {
651
789
  workers: 2,
652
790
  subagents: 0,
653
791
  stopAfterNoNew: 3,
792
+ stopAfterConsecutiveErrors: 2,
654
793
  maxDiscoveryRuns: 10,
655
794
  maxTimeHours: 1.5,
656
795
  });
@@ -668,8 +807,10 @@ max_discovery_runs = 40
668
807
  max_time_hours = 96
669
808
  ```
670
809
 
671
- CLI and SDK options override these defaults. Set `stop_after_consecutive_errors`
672
- in the file; `--codex` cannot configure this section. Worker and run counts must
810
+ CLI and SDK options override these defaults. Project files can use
811
+ `scan.deep.stop_after_consecutive_errors`, and SDK calls can use
812
+ `stopAfterConsecutiveErrors`; there is no new CLI flag for it. `--codex` cannot
813
+ configure this section. Worker and run counts must
673
814
  be positive integers; `subagents` can be zero. Legacy `workers = "auto"` means
674
815
  four workers. Unknown keys are rejected.
675
816
 
@@ -679,6 +820,12 @@ At the deadline, discovery stops; the scan combines and returns completed findin
679
820
  `scan --workers` controls discovery workers within one deep scan;
680
821
  `bulk-scan --workers` controls how many repositories are scanned concurrently.
681
822
 
823
+ The project-file deep block uses `subagents_per_worker` for the existing SDK/CLI
824
+ `subagents` setting. A valid deep block can remain inactive in standard mode;
825
+ explicit deep CLI options require deep mode. All six active values are resolved
826
+ before runtime preparation and saved in new recipes. Complete saved values are
827
+ independent of later changes to the legacy TOML file.
828
+
682
829
  ### Runtime configuration and worker limits
683
830
 
684
831
  Scans use these isolated Codex defaults instead of your user or repository
@@ -761,23 +908,24 @@ restrictions.
761
908
 
762
909
  ### Environment variables
763
910
 
764
- | Variable | Effect |
765
- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
766
- | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |
767
- | `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |
768
- | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |
769
- | `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |
770
- | `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |
771
- | `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
772
- | `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |
773
- | `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |
774
- | `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |
775
- | `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |
776
- | `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |
777
- | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |
778
- | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |
779
- | `CI` | Disables interactive update notices. |
780
- | `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |
911
+ | Variable | Effect |
912
+ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
913
+ | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |
914
+ | `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |
915
+ | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |
916
+ | `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |
917
+ | `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |
918
+ | `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
919
+ | `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |
920
+ | `CODEX_SECURITY_PROJECT_CONFIG` | Trusted project file for `scan`, `bulk-scan`, `scan-components`, and `info`; `-c` wins. Unset by default. |
921
+ | `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |
922
+ | `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |
923
+ | `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |
924
+ | `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |
925
+ | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |
926
+ | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |
927
+ | `CI` | Disables interactive update notices. |
928
+ | `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |
781
929
 
782
930
  Custom Codex executables need thread source attribution for `exec` and
783
931
  `app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
@@ -803,20 +951,32 @@ The final summary preserves missing-data information from a matching session log
803
951
  If the Codex runtime converts an omitted count to zero before recording it, the
804
952
  CLI cannot distinguish that zero from reported usage.
805
953
 
806
- JSON results, scan history, and bulk-scan receipts record the model, tokens,
807
- estimated cost, and `cost.pricing`: the price source, verification date, processing
808
- tier, context category, and rates in USD per million tokens. Estimates use
809
- [standard, short-context API prices](https://developers.openai.com/api/docs/pricing),
810
- including cache reads and writes. They exclude long-context and other processing
811
- tier adjustments, fees, and surcharges. GPT-5.5 and GPT-6 Astra are supported;
812
- models without known prices show an unavailable estimate.
954
+ Cost displays show a range using
955
+ [standard API prices](https://developers.openai.com/api/docs/pricing), because
956
+ runtime usage does not identify which requests received long-context pricing.
957
+ The minimum assumes short-context pricing; the maximum assumes long-context
958
+ pricing. These are token-cost estimates for the observed usage, excluding other
959
+ processing tiers, fees, surcharges, and account-specific pricing.
960
+
961
+ JSON results, scan history, and bulk-scan receipts preserve
962
+ `cost.estimatedUsdRange`: `min`, `max`, and `context: "unknown"`. A `null` maximum
963
+ means an upper estimate is unavailable, including models without verified
964
+ long-context rates. `cost.pricing` records the price source, verification date,
965
+ processing tier, short-context rates, and verified long-context rates when known.
966
+ Models without known short-context prices still have no cost estimate.
813
967
 
814
968
  For compatibility, `cacheWriteInputTokens` remains the reported token subtotal.
815
969
  `cacheWriteInputTokensReported: false` means at least one included usage record
816
970
  did not report cache writes. Raw usage uses `cache_write_input_tokens_reported`.
817
- In that case, the estimate prices unclassified input at the ordinary input rate;
818
- it may undercount cache-write charges. Older saved records lack this distinction
819
- and the saved pricing basis.
971
+ In that case, the range minimum prices unclassified input as ordinary input,
972
+ and the maximum allows it to be cache writes. Token counts remain unchanged.
973
+ Older saved records remain readable and display a labeled legacy estimate;
974
+ they are not repriced using current rates.
975
+
976
+ For compatibility, `cost.estimatedUsd` retains the short-context baseline used
977
+ by existing spending limits. `cost.pricing.context: "short"` describes that
978
+ baseline, not observed request contexts. Use `estimatedUsdRange` for cost
979
+ reporting. This change does not change when spending limits stop scans.
820
980
 
821
981
  `--max-cost USD` stops the scan and its workers when estimated cost exceeds
822
982
  the limit, though in-flight requests can finish above it. If deep-scan
@@ -873,6 +1033,11 @@ npx @openai/codex-security bulk-scan repositories.csv \
873
1033
 
874
1034
  `--scan-prompt-file PATH` adds instructions to a scan or all bulk scans. Each
875
1035
  repository's CSV `prompt` follows the shared instructions.
1036
+ `-c FILE` shares config with single scans: CSV mode/scope override file defaults,
1037
+ and deep settings apply only to deep rows. `output.directory` can supply the
1038
+ results directory. `fail_on_severity` returns exit `1` without retrying completed
1039
+ scans, including when resuming saved results. A changed project configuration
1040
+ requires a new campaign output directory.
876
1041
  `--post-scan-prompt-file PATH` runs a follow-up in the same authenticated session,
877
1042
  even after a failed or incomplete scan, but not after cancellation or a
878
1043
  cost-limit stop.
@@ -927,7 +1092,8 @@ file. Source review still runs; discovery workers do not receive this prompt.
927
1092
  npx @openai/codex-security scan . --validation-prompt-file validation.md
928
1093
  ```
929
1094
 
930
- The SDK accepts the same text as `validationPrompt`:
1095
+ The SDK accepts the same file as `validationPromptFile`, or inline text as
1096
+ `validationPrompt`:
931
1097
 
932
1098
  ```ts
933
1099
  const result = await security.run(repository, {
@@ -1141,7 +1307,7 @@ Omitting `--rubric` inherits each finding's existing severity without a model ca
1141
1307
 
1142
1308
  `--rubric PATH` supplies the classification policy. Repeat `--knowledge-base PATH`
1143
1309
  to provide supporting architecture, deployment, or business context. Both accept
1144
- the same Markdown, text, PDF, DOCX, and directory inputs as scan knowledge bases.
1310
+ the same UTF-8 text, PDF, DOCX, and directory inputs as scan knowledge bases.
1145
1311
  Rubric classification uses the full supplied report and context in a separate
1146
1312
  read-only Codex turn per finding, without source inspection, tools, or new
1147
1313
  validation. `--model` and `--effort` select the classification model and reasoning
@@ -1275,11 +1441,35 @@ and worker activity. These can contain source code, prompts, findings, tool
1275
1441
  output, and other sensitive data. Only include logs you can share with OpenAI.
1276
1442
  The command uses Codex's feedback service and respects `feedback.enabled = false`.
1277
1443
 
1444
+ For scans started through the Desktop plugin, run the command on the machine
1445
+ where the scan ran, using the same Codex home and Codex Security state directory.
1446
+ It searches active and archived sessions in both that Codex home and the CLI's
1447
+ managed home, and attaches available worker logs even if the parent log is missing.
1448
+ Earlier retries that started separate sessions may be missing when their session
1449
+ IDs are no longer recorded.
1450
+
1451
+ Standard scans run inside an existing Codex conversation attach only the owner's
1452
+ saved session; they do not record which subagents belong to the scan. Deep Scans
1453
+ and scans launched by `codex-security` also attach their recorded execution
1454
+ threads and descendants, without following unrelated children of the owner.
1455
+
1278
1456
  ### Scan history and reruns
1279
1457
 
1280
1458
  Commands default to the current repository. Select scans by full ID or a
1281
1459
  unique prefix of at least eight characters.
1282
1460
 
1461
+ New recipes retain resolved settings and the authentication choice, not
1462
+ credentials. Reruns do not reload project files; complete saved deep settings do
1463
+ not use current legacy defaults. Older partial recipes retain their previous
1464
+ fallback behavior. Context paths and the current checkout are not immutable input
1465
+ snapshots.
1466
+
1467
+ Reruns require replacement scan instructions when the original scan used them.
1468
+ New recipes mark this requirement, and `scans rerun` refuses to omit them silently; use
1469
+ `scans rerun [SCAN_ID] --scan-prompt-file FILE` to supply a nonempty replacement.
1470
+ Replacement files resolve from the invocation directory. Custom validation keeps its existing
1471
+ `scans rerun --validation-prompt-file` requirement.
1472
+
1283
1473
  | Command | Purpose |
1284
1474
  | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
1285
1475
  | `scans list [REPOSITORY]` | List scans. Filter by artifact root with `--scan-root DIR`. |
@@ -1308,8 +1498,10 @@ The checkout's identity, revision, and contents must match the saved target.
1308
1498
  Completed, failed, and canceled scans cannot resume; `scans rerun` starts a new scan.
1309
1499
 
1310
1500
  Resume uses the saved configuration and instructions with the installed plugin.
1311
- New scans save the explicit safety identifier and post-scan prompt contents.
1312
- Single-scan resume restores them even if the prompt file changes or disappears.
1501
+ New scans save the selected authentication mode, explicit safety identifier, and
1502
+ post-scan prompt contents. Resume restores the authentication choice without
1503
+ saving credentials. Single-scan resume restores the prompt even if its original
1504
+ file changes or disappears.
1313
1505
  Older records that did not save these values cannot reconstruct them. Bulk
1314
1506
  recovery still requires matching campaign inputs and options; it uses the supplied
1315
1507
  post-scan prompt when the scan has no saved prompt.
@@ -1448,6 +1640,26 @@ Use the SDK loop for a disposition per alert.
1448
1640
  files or literal text and work in the current directory. Pass a saved finding
1449
1641
  or occurrence ID to `patch` to use its original repository.
1450
1642
 
1643
+ Add `--validation-prompt-file PATH` to supply custom dynamic validation
1644
+ instructions, using the same UTF-8 prompt file format as `scan`. The patch task
1645
+ uses these instructions to set up the environment, build or start the application,
1646
+ exercise the fix, check legitimate behavior, and clean up. Include the commands,
1647
+ authorized targets, expected results, and cleanup steps for your environment.
1648
+ The task must report validation evidence or explain which checks failed or could
1649
+ not run before claiming the patch is fixed or verified.
1650
+
1651
+ ```bash
1652
+ npx @openai/codex-security patch OCCURRENCE_ID --validation-prompt-file validation.md
1653
+ npx @openai/codex-security patch issues.md --validation-prompt-file validation.md
1654
+ ```
1655
+
1656
+ The flag works with saved findings, issue text/files, and Linear inputs. Relative
1657
+ prompt paths resolve from the directory where you invoke the CLI, including when
1658
+ the saved finding belongs to another repository. The file is read once before
1659
+ patching; missing, empty, or non-regular files fail before the patch task starts.
1660
+ Without the flag, the usual fix-finding verification applies. The flag does not
1661
+ change sandbox permissions and cannot be combined with `--resume-pr`.
1662
+
1451
1663
  Add `--assess-patch-risk` to a `patch` command to run the bundled patch-risk
1452
1664
  assessment skill once on the completed patch. The assessment is advisory and
1453
1665
  does not change the patch or its merge state. Human-readable commands print the
@@ -1465,16 +1677,38 @@ npx @openai/codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
1465
1677
  npx @openai/codex-security patch --linear-issue SEC-123 --assess-patch-risk --create-pr
1466
1678
  ```
1467
1679
 
1468
- `--scan latest` selects the current repository's latest scan. Saved-finding
1469
- patch commands support `--json`; literal-text and file inputs don't. Change
1680
+ `--scan latest` selects the current repository's latest scan. Patch commands
1681
+ support `--json`, including literal-text and file inputs. Change
1470
1682
  the model with `--codex 'model="gpt-5.6-sol"'` or effort with `--effort high`.
1471
1683
  Each finding gets its own saved Codex desktop task.
1472
1684
 
1685
+ Before patching, the CLI runs a command with the task's sandbox policy. If the
1686
+ sandbox cannot start, the command exits with a nonzero status and reports
1687
+ `SANDBOX_UNAVAILABLE`. JSON errors include `ok: false`. A completed model response
1688
+ with no repository changes fails with `NO_PATCH_APPLIED`. Results report `applied`,
1689
+ `filesChanged`, and `files`; existing local changes do not count as patch changes.
1690
+ These fields report file changes, not proof that the security issue is fixed.
1691
+ Saved findings still require a verified result from the patch task.
1692
+
1693
+ For a controlled container that provides its own isolation, explicitly opt in:
1694
+
1695
+ ```bash
1696
+ npx @openai/codex-security patch "Security issue" --external-sandbox --json
1697
+ ```
1698
+
1699
+ `--external-sandbox` defaults to false. It uses Codex's external-sandbox policy
1700
+ and prints a warning: Codex does not enforce filesystem or network isolation for
1701
+ the patch task. The container must enforce those boundaries. The CLI never
1702
+ falls back to this mode automatically. Optional patch-risk assessment still uses
1703
+ its read-only Codex sandbox.
1704
+
1473
1705
  `scan --patch` patches after a complete scan. `--patch-severity` defaults to
1474
1706
  `low`; `high` selects high and critical findings. Use the interactive browser
1475
1707
  to select findings and add patch instructions. Results include a `patches`
1476
1708
  entry per finding with status `verified`, `no_change`, `blocked`, or `failed`.
1477
1709
  Verified and already-fixed findings no longer fail `--fail-on-severity`.
1710
+ Patching shows each finding's position, elapsed time, and live Codex activity.
1711
+ Progress goes to stderr; completed results stay in the terminal history.
1478
1712
 
1479
1713
  `--create-pr` commits generated patch files and opens a draft GitHub pull request
1480
1714
  with `gh` or a draft GitLab merge request with `glab`. Install and authenticate
@@ -1578,6 +1812,12 @@ cancels, resumes, publishes, edits, or deduplicates anything.
1578
1812
 
1579
1813
  The dashboard opens on Findings, followed by Duplicate groups. Both views
1580
1814
  support search, repository filtering, sorting, pagination, and record details.
1815
+ Click any column header to sort all matching records; click it again to reverse
1816
+ the order. The arrow marks the active column and direction. Changing the sort
1817
+ returns to the first page, and automatic refreshes keep the selected order.
1818
+ By default, findings sort by last update descending, then severity descending,
1819
+ then ID ascending to break ties. Groups sort by last update descending and ID
1820
+ ascending.
1581
1821
  Findings show stored content and links to their duplicate groups. Groups link
1582
1822
  back to their member findings, preserving separate overlapping groups and the
1583
1823
  original finding records.
@@ -1594,7 +1834,10 @@ repository choices, a page of records, and optional selected-record details:
1594
1834
 
1595
1835
  - `view`: `findings` (default) or `groups`.
1596
1836
  - `query`, `repository`: optional search text and exact repository ID.
1597
- - `sort`: `activity` (default; most recently updated first) or `newest`.
1837
+ - `sort`: `activity` (default; last update), `newest` (created), `title`,
1838
+ `repository`, `severity` (findings only), or `members` (groups only).
1839
+ - `direction`: `asc` or `desc` (default). Text sorts alphabetically without
1840
+ case sensitivity, severity by level, and member counts numerically.
1598
1841
  - `limit`, `offset`: existing pagination conventions, defaulting to 50 and 0.
1599
1842
  - `id`: optional exact record ID to include in `detail`; unknown IDs return
1600
1843
  `detail: null` without hiding the list.
@@ -1721,7 +1964,7 @@ console.log(receipt.repositoryId, receipt.findingIds);
1721
1964
  Publish the scan with `--to custom` (or import it through the bulk API with its
1722
1965
  `repositoryId`) before deduplicating. The
1723
1966
  workflow reads a completed saved scan, queries candidates by finding ID, and
1724
- runs Luna and Sol in the calling SDK/CLI process. Once all reviews succeed,
1967
+ runs Luna and Sol in the calling SDK/CLI process. Once all reviews finish,
1725
1968
  it posts accepted groups to the service. It does not re-upload findings or
1726
1969
  change scan artifacts.
1727
1970
 
@@ -1742,7 +1985,14 @@ has finished and none voted `DISTINCT`. It can run while unrelated Luna
1742
1985
  screenings continue. Results are combined in input order so completion timing
1743
1986
  does not change the groups.
1744
1987
 
1745
- If a job fails after its retries, queued jobs stop and already running jobs
1988
+ An explicit model refusal keeps the affected pairs separate and allows unrelated
1989
+ reviews to continue. It is recorded as `NO_DECISION`, not a reviewed `DISTINCT`
1990
+ verdict. A screening refusal applies to every anchor/candidate pair in that
1991
+ screening; a pair-review refusal applies only to its assigned pair. Neither pair
1992
+ can be merged indirectly through other findings. Recognized policy errors and
1993
+ explicit refusal responses are not retried or sent to another model.
1994
+
1995
+ If another kind of job fails after its retries, queued jobs stop and already running jobs
1746
1996
  finish before the command reports the failure. No groups are posted from an
1747
1997
  incomplete review. To retain completed reviews across runs, use a
1748
1998
  `--workflow-id` as described below.
@@ -1806,6 +2056,19 @@ has the highest reported severity; ties use finding ID. Results do not delete,
1806
2056
  merge, or change stored finding documents. Accepted groups are saved as durable
1807
2057
  associations in the service before `deduplicationStatus` becomes `completed`.
1808
2058
 
2059
+ When any review is refused, the result instead has
2060
+ `deduplicationStatus: "completed_with_refusals"` and a `refusals` array. Each
2061
+ entry contains `decision: "NO_DECISION"`, `stage`, `model`, `findingIds`, and
2062
+ `reason`. For screening, the first finding ID is the anchor and the remaining
2063
+ IDs are its candidates. The CLI logs each refusal to stderr and exits
2064
+ successfully after saving the accepted groups. SDK callers can inspect and log
2065
+ the same structured entries. Findings retained because of a refusal are not
2066
+ confirmed unique. Successful runs without refusals keep their existing output
2067
+ shape. No command, flag, or default changes are required.
2068
+
2069
+ This behavior applies to post-scan Luna/Sol deduplication. Deep Scan's internal
2070
+ reducer uses a separate workflow.
2071
+
1809
2072
  ### Stored duplicate groups
1810
2073
 
1811
2074
  `POST /v1/dedupe-groups` accepts a batch of explicitly reviewed member sets:
@@ -1907,10 +2170,16 @@ exponential backoff with jitter; HTTP retries honor `Retry-After`. Waiting to re
1907
2170
  occupies the job's concurrency slot.
1908
2171
 
1909
2172
  Cancellation, authentication or configuration errors, permanent HTTP errors, and
1910
- required-source-access blockers are not retried. Exhausted retries fail deduplication;
2173
+ required-source-access blockers are not retried. Model refusals continue with
2174
+ `NO_DECISION` as described above. Other exhausted retries fail deduplication;
1911
2175
  invalid or unfinished reviews are not cached. Completed checkpoints remain
1912
2176
  available when the workflow resumes.
1913
2177
 
2178
+ Refusals are not saved as validated review checkpoints. A completed workflow
2179
+ retains its final `completed_with_refusals` result, including all refusal entries,
2180
+ and returns it on subsequent calls. To attempt those reviews again after
2181
+ resolving the refusal, run dedupe without that workflow ID or with a new one.
2182
+
1914
2183
  Checkpoints bind to the exact original records and ordering, approved source path,
1915
2184
  Git revision and current file contents (including ignored files), repository scope,
1916
2185
  model and reasoning settings, Codex configuration and version, and prompt/contract version. Changed
@@ -12,7 +12,6 @@ The scan reviewed the canonical include paths and exclusions listed below.
12
12
  - Inventory strategy: repository
13
13
  - Included paths: .
14
14
  - Excluded paths: none
15
- - Runtime or test status: not recorded
16
15
 
17
16
  ### Scan Summary
18
17