feat(cli): review and apply saved SECURITY.md drafts

Dockerfile

@@ -2,6 +2,10 @@
 
 FROM node:22-bookworm-slim@sha256:6c74791e557ce11fc957704f6d4fe134a7bc8d6f5ca4403205b2966bd488f6b3 AS package
 
+RUN apt-get update \
+    && apt-get install --no-install-recommends --yes python3 \
+    && rm -rf /var/lib/apt/lists/*
+
 WORKDIR /build/sdk/typescript
 
 COPY sdk/typescript/package.json sdk/typescript/pnpm-lock.yaml ./

README.md

@@ -97,10 +97,20 @@ npx @openai/codex-security policy . --headless --output-dir /path/outside/reposi
 
 The command reads the source, describes the system, builds a detailed threat
 model, and drafts a short `SECURITY.md`. In a terminal, it asks about important
-facts the code cannot establish and shows the proposed diff. It does not change
-repository files. Review the saved policy and check for other policy files that
-link to the target before copying it. Later scans read the root and nested
-`SECURITY.md` files.
+facts the code cannot establish, shows the proposed diff, and asks before
+writing. Later scans read the approved root and nested `SECURITY.md` files.
+
+To review a saved draft, edit its `SECURITY.md`, then run:
+
+```bash
+npx @openai/codex-security policy . --apply /path/outside/repository/policy --write
+```
+
+Use the same repository and `--path` as generation. Applying does not call the
+model. It checks that the original and inherited policies are unchanged, keeps
+the write inside the approved scope, and verifies the result. Updates retain the
+previous file at the reported recovery path. Keep it until other writers have
+closed it and any edits are reconciled.
 
 Drafts are stored outside the repository and any enclosing Git checkout. The
 same private directory contains `project-spec.md`, `THREAT_MODEL.md`, and review

sdk/typescript/README.md

@@ -201,9 +201,9 @@ Trusted Access for Cyber. To apply or check your access, visit
 
 ## Generate a security policy
 
-`policy` drafts a `SECURITY.md` for owner review. It uses the same Codex runtime,
-authentication, model settings, and security guidance as scans, but does not
-look for vulnerabilities or create a scan record. Codex can read files but
+`policy` drafts or updates a `SECURITY.md` for owner review. It uses the same
+Codex runtime, authentication, model settings, and security guidance as scans,
+but does not look for vulnerabilities or create a scan record. Codex can read files but
 cannot write them. Network access, web search, apps, and MCP servers are disabled.
 The SDK saves the responses in a private directory outside the checkout.
 
@@ -227,57 +227,90 @@ that would spread a component policy to a wider scope.
 Generation has three stages: describe the system, build a detailed threat model,
 and draft the policy. In a terminal, the command asks about important facts the
 source cannot establish, then shows the exact diff and decisions that need
-review. If both a ChatGPT sign-in and an API key are available, it asks which to
-use. Set `--auth chatgpt` or `--auth api-key` to choose explicitly.
+review. It asks before writing to the repository. If both a ChatGPT sign-in and
+an API key are available, it asks which to use. Set `--auth chatgpt` or
+`--auth api-key` to choose explicitly.
 
-### Review the draft
+### Review and apply a saved draft
 
-The command never changes repository files. Review the saved `SECURITY.md`
-before copying it to the reported target path. Check whether another policy,
-such as `.github/SECURITY.md` or `docs/SECURITY.md`, links to that target; a
-manual copy can change the linked policy too. Preserve existing reporting
+Review the saved `SECURITY.md` before applying it. Preserve existing reporting
 instructions and obtain owner approval for exclusions, accepted risks, and
 severity decisions. Later scans read the approved policy.
 
 Preview checks that the selected policy and its parent policies have not
 changed. Other source files are not frozen; generate a new draft if relevant
 source or neighboring policy files change.
 
-Use `--headless` or an explicit output format to skip questions. Unanswered
-questions remain in the review notes. Drafts default to the Codex Security state
-directory; `--output-dir` selects an empty directory outside every enclosing
-Git checkout and its Git metadata.
+Use `--headless` or an explicit output format to skip questions and write
+prompts. Unanswered questions remain in the review notes. Drafts default to the
+Codex Security state directory; `--output-dir` selects an empty directory
+outside every enclosing Git checkout and its Git metadata.
 
 ```bash
 npx @openai/codex-security policy . --path services/api \
   --headless --output-dir /path/outside/repository/api-policy --json
+
+# Review or edit the saved SECURITY.md.
+npx @openai/codex-security policy . --path services/api \
+  --apply /path/outside/repository/api-policy --write
 ```
 
+`--apply` loads the saved draft without starting Codex. Omit `--write` to review
+and confirm interactively. `--write` requires `--apply`; it cannot write an
+unseen model response. The repository and component must match the draft.
+Before writing, the command checks that the original policy and inherited
+guidance have not changed. It also rejects links that would change another
+component's guidance or a separate reporting policy in `.github` or `docs`.
+Fix those links before applying. It writes the reviewed bytes, verifies that
+the policy resolver can read them, and does not stage, commit, or publish them.
+If a write succeeded but verification failed, fix the reported problem and
+retry the same saved draft with `--write`. An exact-content retry verifies the
+installed policy without replacing it. Keep any previously reported recovery
+file until concurrent edits have been reconciled.
+
+Updates keep the previous file so a late save through an open editor handle is
+not lost. The command moves it into the private artifact directory when possible;
+otherwise it stays beside the target as `.SECURITY.md.*.previous`. The CLI prints
+the path and returns `recoveryPath` in JSON. Keep that file until other writers
+have closed it and any edits are reconciled. A `recovery_required` result means
+the replacement needs manual reconciliation. A `written_unverified` result means
+the new policy was written but verification failed. Inspect the reported paths
+before retrying. Once a write commits, SDK cancellation does not skip the
+remaining checks. A terminal interrupt or process failure can still leave a
+`written_unverified` result. A later Ctrl-C or SIGTERM forces the CLI to stop.
+
+Save edited drafts as UTF-8. If generation used a custom `--plugin-path`, select
+it again when applying a saved draft. Saved metadata cannot choose executable
+plugin code. Both plugin directories and ZIP files are supported.
+
 The artifact directory contains:
 
 | File                   | Purpose                                                   |
 | ---------------------- | --------------------------------------------------------- |
 | `SECURITY.md`          | Editable policy draft.                                    |
 | `THREAT_MODEL.md`      | Detailed threat model with source references.             |
 | `project-spec.md`      | System description and security boundaries.               |
-| `previous-SECURITY.md` | Original policy used for the diff.                        |
+| `previous-SECURITY.md` | Original policy used for the diff and overwrite checks.   |
 | `policy-draft.json`    | Target, policy hashes, revision, model, and review notes. |
 
+An update may also retain `recovery-SECURITY-*.md` files.
+
 Keep detailed models and intermediate files private until they have been
 reviewed for disclosure. Generation does not imply owner approval or confirm
 that a threat scenario is a vulnerability.
 
 `--format md` writes the draft to stdout. `--json` returns paths, review notes,
 status, and estimated cost. Global filters and token options work with these
 formats. Progress goes to stderr. `--full-output` reports failures with
-`ok: false`. `--max-cost` applies to the whole generation. If a stage cannot
+`ok: false`. Plain `--json` retains recovery status and paths when a write
+needs attention. `--max-cost` applies to the whole generation. If a stage cannot
 inspect required source evidence, generation stops and preserves completed
 documents. Fix the reported problem and use a new output directory to retry.
 
 ### Generate a policy from TypeScript
 
 ```ts
-import { CodexSecurity } from "@openai/codex-security";
+import { CodexSecurity, applySecurityPolicy } from "@openai/codex-security";
 
 const security = new CodexSecurity();
 try {
@@ -289,6 +322,8 @@ try {
 
   console.log(await security.previewPolicy(draft));
   // Open draft.draftPath in an editor to review the saved policy.
+  // Obtain approval for this exact draft before calling:
+  // await applySecurityPolicy(draft, { pythonPath: security.config.pythonPath });
 } finally {
   await security.close();
 }
@@ -298,11 +333,20 @@ try {
 `previewPolicy()` uses the client's Python setting and makes terminal control
 characters visible. The standalone `securityPolicyDiff()` returns a raw diff
 for files or other non-terminal uses; pass an interpreter explicitly if needed.
-`generatePolicy()` accepts `auth`, `path`, `knowledgeBasePaths`, `outputDir`,
-`maxCostUsd`, `signal`, and progress and cost callbacks. An optional
+`generatePolicy()` never edits the repository. It accepts `auth`, `path`,
+`knowledgeBasePaths`, `outputDir`, `maxCostUsd`, `signal`, and progress and cost
+callbacks. An optional
 `answerQuestions` callback receives each group of up to three owner questions
 and a cancellation signal. Without it, the questions remain unresolved.
 
+Use `loadSecurityPolicyDraft(repository, artifactDirectory, { path })` to load
+an edited draft. `applySecurityPolicy()` returns `{ status, targetPath, recoveryPath }`;
+`status` is `written` or `unchanged`.
+`recoveryPath` is `null` when no existing file was replaced. Pass `{ pluginPath }`
+when applying a saved custom-plugin draft. `SecurityPolicyVerificationError` and
+`SecurityPolicyRecoveryError` identify files that need inspection or
+reconciliation.
+
 ## CLI
 
 ```bash