feat(deep): share execution and persist recoverable scan results

plugins/codex-security/mcp-app/helpers-main.ts

@@ -1,34 +1,48 @@
+import { existsSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+export { parseCanonicalScanDraft } from "./src/artifact-scan-draft.js";
+export { resumeSelectedDeepScan } from "./src/deep-scan/finalization.js";
 import { resolveSecurityMdCommand } from "./src/helpers/resolve-security-md";
 import { decodePosixBytes } from "./src/helpers/posix-path";
 import { windowsBinding } from "./src/native";
 
-let commandLine = process.argv.slice(2);
-if (process.platform === "win32") {
-  const original = windowsBinding().windowsArguments();
-  commandLine = original
-    .slice(original.length - commandLine.length)
-    .map((argument) => argument.toString("utf16le"));
-}
-let posixHome = process.env.HOME;
-if (commandLine[0] === "--helper") {
+// Importing the bundled helper from the SDK does not invoke its CLI adapter.
+const entryPath = import.meta.url.startsWith("file:") ? fileURLToPath(import.meta.url) : import.meta.url;
+const invokedPath = process.argv[1];
+if (
+  invokedPath && existsSync(invokedPath)
+  && realpathSync(invokedPath) === realpathSync(entryPath)
+) runHelper();
+
+function runHelper(): void {
+  let commandLine = process.argv.slice(2);
   if (process.platform === "win32") {
-    commandLine = commandLine.slice(1);
+    const original = windowsBinding().windowsArguments();
+    commandLine = original
+      .slice(original.length - commandLine.length)
+      .map((argument) => argument.toString("utf16le"));
+  }
+  let posixHome = process.env.HOME;
+  if (commandLine[0] === "--helper") {
+    if (process.platform === "win32") {
+      commandLine = commandLine.slice(1);
+    } else {
+      const [homeSet, home, ...args] = decodePosixBytes(
+        Buffer.from(commandLine[1] ?? "", "hex"),
+      )
+        .split("\0")
+        .slice(0, -1);
+      posixHome = homeSet ? home : undefined;
+      commandLine = args;
+    }
+  }
+  const [command, ...args] = commandLine;
+  if (command === "resolve-security-md") {
+    process.exitCode = resolveSecurityMdCommand(args, posixHome);
   } else {
-    const [homeSet, home, ...args] = decodePosixBytes(
-      Buffer.from(commandLine[1] ?? "", "hex"),
-    )
-      .split("\0")
-      .slice(0, -1);
-    posixHome = homeSet ? home : undefined;
-    commandLine = args;
+    console.error(
+      "Usage: launch_codex_security_mcp[.cmd] --helper resolve-security-md [options]",
+    );
+    process.exitCode = 2;
   }
 }
-const [command, ...args] = commandLine;
-if (command === "resolve-security-md") {
-  process.exitCode = resolveSecurityMdCommand(args, posixHome);
-} else {
-  console.error(
-    "Usage: launch_codex_security_mcp[.cmd] --helper resolve-security-md [options]",
-  );
-  process.exitCode = 2;
-}

plugins/codex-security/mcp-app/scripts/build_mcp_app.mjs

@@ -41,6 +41,7 @@ export async function buildMcpApp({ output }) {
         loader: { ".md": "text" },
         logLevel: "info",
         logOverride: { "empty-import-meta": "silent" },
+        nodePaths: [join(root, "node_modules")],
         outfile: bundle,
         platform: "node",
         target: "node20"
@@ -108,5 +109,6 @@ const runtimeModule = new Module(loaderPath);
 runtimeModule.filename = loaderPath;
 runtimeModule.paths = Module._nodeModulePaths(dirname(loaderPath));
 runtimeModule._compile(runtimeSource, loaderPath);
+export default runtimeModule.exports;
 `;
 }

plugins/codex-security/mcp-app/src/artifact-deep-reducer.ts

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { dirname, join, relative, sep } from "node:path";
 import type { ZodType } from "zod/v4";
 import commonSchema from "../../schemas/definitions/artifact-common.schema.json";
 import reducerSchema from "../../schemas/tools/deep-reducer.schema.json";
@@ -20,7 +20,9 @@ import {
   type DeepScanArtifacts
 } from "./deep-scan/artifacts.js";
 import {
+  deepReductionForPersistence,
   parseDeepReduction,
+  projectDiscoveryCoverage,
   reconcileDeepReduction,
   type DeepReductionInput,
   type DeepReductionSources,
@@ -54,6 +56,18 @@ interface BoundReducer {
 /** Read the findings and scan context assigned to this reducer. */
 export async function getCodexSecurityDeepReducerInputs(
   context: ArtifactContext
+): Promise<DeepReductionSources> {
+  const inputs = await readDeepReductionSources(context);
+  const { sourceCoverage: _coverage, ...previous } = inputs.previous ?? {};
+  return {
+    discoveries: inputs.discoveries.map(({ workerId, result }) => ({ workerId, result })),
+    previous: inputs.previous === null ? null : previous as DeepReductionInput,
+  };
+}
+
+/** Capture host coverage alongside the reducer's immutable finding inputs. */
+export async function readDeepReductionSources(
+  context: ArtifactContext
 ): Promise<DeepReductionSources> {
   return withLogicalReducerErrors(context, async () => {
     const bound = bindDeepReducer(context);
@@ -73,8 +87,13 @@ export async function getCodexSecurityDeepReducerInputs(
           sourceFindingIds: [`${worker.id}:${index}`],
         },
       }));
-      const { coverage: _coverage, ...reduction } = result;
-      return { workerId: worker.id, result: reduction };
+      const { coverage, ...reduction } = result;
+      return {
+        workerId: worker.id,
+        ...(worker.attempt === undefined ? {} : { attempt: worker.attempt }),
+        coverage: projectDiscoveryCoverage(coverage, worker, relative(bound.artifacts.scanDir, worker.artifactDir ?? dirname(worker.resultPath)).split(sep).join("/")),
+        result: reduction,
+      };
     }));
     const previous = await readPreviousReduction(bound);
     const scanId = bound.scanId ?? previous?.scanId ?? discoveries[0]?.result.scanId;
@@ -107,7 +126,7 @@ export async function recordCodexSecurityDeepReduction(
     const submitted = deepReductionInputSchema.parse(input);
     let reduction = parseDeepReduction(submitted);
     if (reduction.complete === false) throw new Error("Deep reduction is only a checkpoint, not a complete result.");
-    const inputs = await getCodexSecurityDeepReducerInputs(context);
+    const inputs = await readDeepReductionSources(context);
     const expectedScanId = bound.scanId
       ?? inputs.previous?.scanId
       ?? inputs.discoveries[0]?.result.scanId;
@@ -116,8 +135,9 @@ export async function recordCodexSecurityDeepReduction(
     }
     reduction = reconcileDeepReduction(reduction, inputs.discoveries, inputs.previous);
 
-    await saveScanDraftCheckpoint(context, reduction);
-    await writeJsonAtomic(bound.resultPath, reduction);
+    const persisted = deepReductionForPersistence(reduction, bound.state.persistSourceCoverage);
+    await saveScanDraftCheckpoint(context, persisted);
+    await writeJsonAtomic(bound.resultPath, persisted);
     return {
       findingCount: reduction.findings.length,
       consumedWorkerIds: bound.state.claimedWorkers.map((worker) => worker.id)

plugins/codex-security/mcp-app/src/artifact-io.ts

@@ -5,12 +5,16 @@ import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 export interface DeepReducerWorkerContext {
   id: string;
   resultPath: string;
+  /** Original output owner for relative evidence, including accepted checkpoints. */
+  artifactDir?: string;
+  attempt?: number;
 }
 
 export interface DeepReducerContext {
   scanRoot: string;
   claimedWorkers: DeepReducerWorkerContext[];
   previousReducerResultPath?: string;
+  persistSourceCoverage?: boolean;
 }
 
 /**

plugins/codex-security/mcp-app/src/artifact-scan-draft.ts

@@ -4,6 +4,7 @@ import { dirname, join, sep } from "node:path";
 import type * as z from "zod/v4";
 import commonSchema from "../../schemas/definitions/artifact-common.schema.json";
 import scanDraftDocument from "../../schemas/tools/scan-draft.schema.json";
+import scanManifestDocument from "../../schemas/scan-manifest.schema.json";
 import type { ArtifactContext } from "./artifact-context.js";
 import type { RunArtifactWorkbench } from "./artifact-context.js";
 import {
@@ -17,17 +18,10 @@ import {
   type SchemaDocument,
 } from "./artifact-schema-loader.js";
 
-type JsonObject = Record<string, unknown>;
+import type { ScanDraftInput } from "../../../../sdk/typescript/src/accepted-audit.js";
+export type { ScanDraftInput } from "../../../../sdk/typescript/src/accepted-audit.js";
 
-export interface ScanDraftInput {
-  scanId: string;
-  complete?: boolean;
-  handoffClaimToken?: string;
-  scope?: JsonObject;
-  threatModel?: JsonObject;
-  findings: JsonObject[];
-  coverage: JsonObject;
-}
+type JsonObject = Record<string, unknown>;
 
 export interface CompletedScanInput {
   scanId: string;
@@ -55,6 +49,12 @@ interface PreparedScanDraft {
   coverage: JsonObject;
 }
 
+/** Host-selected Deep aggregate, separate from model-authored draft fields. */
+export interface DeepScanPublication {
+  coordinatorGeneration?: number;
+  resultPath: string | null;
+}
+
 type PublishScanDraft = (
   draft: PreparedScanDraft,
   expectedDigest: string | undefined,
@@ -69,6 +69,19 @@ export const scanDraftInputSchema = loadArtifactZodSchema(
   "scanDraftInput",
 ) as z.ZodType<ScanDraftInput>;
 
+// Sealed documents retain the existing public ID contract; live drafts require UUIDs.
+const canonicalScanDraftInputSchema = loadArtifactZodSchema(
+  [commonSchema, {
+    ...scanDraftDocument,
+    $defs: {
+      ...scanDraftDocument.$defs,
+      scanId: scanManifestDocument.properties.scan.properties.id,
+    },
+  }] as SchemaDocument[],
+  scanDraftDocument.$id,
+  "scanDraftInput",
+) as z.ZodType<ScanDraftInput>;
+
 export const completedScanInputSchema = loadArtifactZodSchema(
   schemaDocuments,
   scanDraftDocument.$id,
@@ -165,6 +178,7 @@ export async function recordCodexSecurityScanDraftViaWorkbench(
   input: ScanDraftInput,
   runWorkbench: RunArtifactWorkbench,
   signal?: AbortSignal,
+  publication?: DeepScanPublication,
 ): Promise<ScanDraftResult> {
   return recordCodexSecurityScanDraft(
     context,
@@ -184,7 +198,10 @@ export async function recordCodexSecurityScanDraftViaWorkbench(
         const { handoffClaimToken: _claim, ...snapshot } = checkpoint;
         await Promise.all([
           replaceArtifactJson(checkpointPath, snapshot),
-          replaceArtifactJson(draftPath, draft),
+          replaceArtifactJson(draftPath, {
+            ...draft,
+            ...(publication === undefined ? {} : { deepScanPublication: publication }),
+          }),
         ]);
         const arguments_ = [
           "write-scan-draft",
@@ -548,32 +565,9 @@ async function readPreviousScanDraft(
   const manifest = parseJsonObject(contents[0]!, "previous scan draft manifest");
   const findings = parseJsonObject(contents[1]!, "previous scan draft findings");
   const coverage = parseJsonObject(contents[2]!, "previous scan draft coverage");
-  const scan = requireObject(manifest.scan, "previous scan draft.scan");
-  const semanticScope = isObject(scan.scope) ? { ...scan.scope } : undefined;
-  if (semanticScope) {
-    delete semanticScope.includePaths;
-    delete semanticScope.excludePaths;
-  }
-  const semanticCoverage = { ...coverage };
-  for (const field of ["documentType", "schemaVersion", "scanId", "mode", "includePaths", "excludePaths", "receiptRefs", "inventoryStrategy"]) delete semanticCoverage[field];
   return {
     digest,
-    input: parsePersistedScanDraft({
-      scanId: context.scanId,
-      ...(scan.complete === false ? { complete: false } : {}),
-      ...(semanticScope && Object.keys(semanticScope).length > 0
-        ? { scope: semanticScope }
-        : {}),
-      ...(isObject(scan.threatModel)
-        ? { threatModel: structuredClone(scan.threatModel) }
-        : {}),
-      findings: (findings.findings as JsonObject[]).map((finding) => {
-        const semantic = { ...finding };
-        for (const field of ["findingId", "occurrenceId", "fingerprints"]) delete semantic[field];
-        return semantic;
-      }),
-      coverage: semanticCoverage,
-    }),
+    input: parseCanonicalScanDraft({ scanId: context.scanId, manifest, findings, coverage }),
   };
 }
 
@@ -973,8 +967,35 @@ export async function getCodexSecurityCompletedScan(
   return { scanId: parsed.scanId, manifest, findings, coverage };
 }
 
+/** Project canonical documents through the same semantic parser as worker drafts. */
+export function parseCanonicalScanDraft(input: {
+  scanId?: string;
+  manifest: JsonObject;
+  findings: JsonObject;
+  coverage: JsonObject;
+}): ScanDraftInput {
+  const scan = requireObject(input.manifest.scan, "scan draft manifest.scan");
+  for (const scanId of [scan.id, input.findings.scanId, input.coverage.scanId]) {
+    if (scanId !== undefined && scanId !== input.scanId) {
+      throw new Error("scan draft: canonical documents belong to a different scan.");
+    }
+  }
+  return parsePersistedCheckpoint({
+    scanId: input.scanId,
+    ...(scan.complete === undefined ? {} : { complete: scan.complete }),
+    ...(scan.scope === undefined ? {} : { scope: scan.scope }),
+    ...(scan.threatModel === undefined ? {} : { threatModel: scan.threatModel }),
+    findings: input.findings.findings,
+    coverage: input.coverage,
+  }, canonicalScanDraftInputSchema);
+}
+
 export function parseScanDraft(input: ScanDraftInput): ScanDraftInput {
-  const parsed = scanDraftInputSchema.parse(input);
+  return parseSemanticScanDraft(input, scanDraftInputSchema);
+}
+
+function parseSemanticScanDraft(input: unknown, schema: z.ZodType<ScanDraftInput>): ScanDraftInput {
+  const parsed = schema.parse(input);
   validateFindingSemantics(parsed.findings);
   validateCoverageSemantics(parsed.coverage);
   return parsed;
@@ -984,18 +1005,23 @@ export function parseScanDraft(input: ScanDraftInput): ScanDraftInput {
 export function parsePersistedScanDraft(
   input: Record<string, unknown>
 ): ScanDraftInput {
+  return parsePersistedDraft(input, scanDraftInputSchema);
+}
+
+function parsePersistedDraft(input: Record<string, unknown>, schema: z.ZodType<ScanDraftInput>): ScanDraftInput {
   const compatible = structuredClone(input);
-  if (!Array.isArray(compatible.findings)) {
-    return parseScanDraft(compatible as unknown as ScanDraftInput);
-  }
-  for (const finding of compatible.findings) {
-    if (!isObject(finding)) continue;
-    normalizePersistedFindingDetails(finding);
+  if (Array.isArray(compatible.findings)) {
+    for (const finding of compatible.findings) {
+      if (isObject(finding)) normalizePersistedFindingDetails(finding);
+    }
   }
-  return parseScanDraft(compatible as unknown as ScanDraftInput);
+  return parseSemanticScanDraft(compatible, schema);
 }
 
-function parsePersistedCheckpoint(input: Record<string, unknown>): ScanDraftInput {
+function parsePersistedCheckpoint(
+  input: Record<string, unknown>,
+  schema = scanDraftInputSchema,
+): ScanDraftInput {
   const compatible = structuredClone(input);
   if (isObject(compatible.scope)) {
     delete compatible.scope.includePaths;
@@ -1022,7 +1048,7 @@ function parsePersistedCheckpoint(input: Record<string, unknown>): ScanDraftInpu
       delete finding.fingerprints;
     }
   }
-  return parsePersistedScanDraft(compatible);
+  return parsePersistedDraft(compatible, schema);
 }
 
 function normalizePersistedFindingDetails(finding: JsonObject): void {