feat(deep): prepare compatible readers for durable scan recovery

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

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
+import { existsSync, realpathSync } from "node:fs";
 import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 import { brotliCompressSync, constants as zlibConstants } from "node:zlib";
 import { execFileSync } from "node:child_process";
 import { build } from "esbuild";
@@ -41,6 +42,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"
@@ -68,8 +70,8 @@ export async function buildMcpApp({ output }) {
 
 const invokedPath = process.argv[1];
 if (
-  invokedPath !== undefined
-  && pathToFileURL(resolve(invokedPath)).href === import.meta.url
+  invokedPath !== undefined && existsSync(invokedPath)
+  && realpathSync(invokedPath) === realpathSync(fileURLToPath(import.meta.url))
 ) {
   const args = process.argv.slice(2);
   if (args.length !== 2 || args[0] !== "--output") {
@@ -108,5 +110,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/server.ts

@@ -22,6 +22,7 @@ import {
   DeepScanStartLock,
   startOrJoinDeepScanCoordinator
 } from "./src/deep-scan/registry.js";
+import { captureDeepScanExecutionSettings, loadDeepScanExecutionSettings, restoredDeepScanWorkerSettings, type DeepScanLegacySettingsContext } from "./src/deep-scan/recovery-settings.js";
 import { CodexSdkWorkerExecutor } from "./src/deep-scan/executor.js";
 import {
   CODEX_SANDBOX_STATE_META_CAPABILITY,
@@ -750,6 +751,27 @@ export function createCodexSecurityServer(): McpServer {
         registry: deepScanCoordinators,
         options: {
           store: deepScanStore,
+          prepareExecutor: async (run) => new CodexSdkWorkerExecutor({
+            ...restoredDeepScanWorkerSettings(
+              begun.shouldStart
+                ? await captureDeepScanExecutionSettings(run, parentSandbox, process.env,
+                  { threadId, startedAt: run.createdAt })
+                : await loadDeepScanExecutionSettings(run.scanDir, run, async () => {
+                  const context = await runWorkbench(["get-scan", "--scan-id", run.scanId]);
+                  const recipe = context.recipe as Pick<DeepScanLegacySettingsContext, "config"> | undefined;
+                  const scan = context.scan as { executionAttribution?: { owner: DeepScanRunState["usageOwner"] } };
+                  return { config: recipe?.config, usageOwner: scan.executionAttribution?.owner };
+                }),
+              parentSandbox
+            ),
+            artifactContext: {
+              pluginRoot: PLUGIN_ROOT,
+              scanRoot: run.scanDir,
+              repoRoot: run.targetPath,
+              scanId: run.scanId,
+              scope: run.scope
+            }
+          }),
           executor: new CodexSdkWorkerExecutor({
             ...modelSettings,
             parentSandbox,
@@ -765,7 +787,7 @@ export function createCodexSecurityServer(): McpServer {
           log: logDeepScanEvent,
           handoffClaimToken,
           threadId,
-          onComplete: async (draft, signal) => {
+          onComplete: async (draft, signal, publication) => {
             const context = await createScanArtifactContext(
               begun.run.scanId,
               runWorkbench,
@@ -779,7 +801,7 @@ export function createCodexSecurityServer(): McpServer {
             await recordCodexSecurityScanDraftViaWorkbench(context, {
               ...draft,
               ...(handoffClaimToken === undefined ? {} : { handoffClaimToken })
-            }, runWorkbench, signal);
+            }, runWorkbench, signal, publication);
           },
           onStopped: async (run) => {
             await runWorkbench([
@@ -796,12 +818,26 @@ export function createCodexSecurityServer(): McpServer {
       invocationFailure: toolErrorResult(deepScanInvocationFailureMessage(error))
     }));
     if ("invocationFailure" in preparation) return preparation.invocationFailure;
-    if (preparation.immediate) return preparation.immediate;
+    const completeSelectedParent = async (run: DeepScanRunState) => {
+      if (run.finalizationInput && run.status === "succeeded") {
+        await runWorkbench([
+          "complete-scan", "--scan-id", run.scanId, "--thread-id", threadId,
+          ...optionalArg("--claim-token", handoffClaimToken),
+        ]);
+      }
+    };
+    if (preparation.immediate) {
+      try { await completeSelectedParent(preparation.begun.run); }
+      catch (error) { return toolErrorResult(deepScanInvocationFailureMessage(error)); }
+      return preparation.immediate;
+    }
     const { begun, coordinator, joined } = preparation;
     if (joined) {
       logDeepScanEvent({ event: "coordinator_joined", scanId: begun.run.scanId });
     }
     const terminal = await coordinator.wait(abortSignalFromExtra(extra));
+    try { await completeSelectedParent(terminal); }
+    catch (error) { return toolErrorResult(deepScanInvocationFailureMessage(error)); }
     const result = deepScanTerminalResult(terminal);
     if (!result) {
       return toolErrorResult(deepScanInvocationFailureMessage(
@@ -1632,12 +1668,14 @@ function logDeepScanEvent(event: {
 
 async function runWorkbench(
   args: string[],
-  input?: string | Buffer
+  input?: string | Buffer,
+  selectFinalization = false,
+  withExecutionSettings = false,
 ): Promise<JsonObject> {
   let pythonCommand: string | undefined;
   try {
     pythonCommand = await resolvePythonCommand();
-    return await executeWorkbenchWithStateSelection(pythonCommand, args, input);
+    return await executeWorkbenchWithStateSelection(pythonCommand, args, input, selectFinalization, withExecutionSettings);
   } catch (error) {
     const launchError = pythonCommand
       ? missingPythonHelperMessage(error, pythonCommand)
@@ -1655,36 +1693,38 @@ async function runWorkbench(
 async function executeWorkbenchWithStateSelection(
   pythonCommand: string,
   args: string[],
-  input?: string | Buffer
+  input?: string | Buffer,
+  selectFinalization = false,
+  withExecutionSettings = false,
 ): Promise<JsonObject> {
   if (WORKBENCH_COMMANDS_WITHOUT_DATABASE.has(args[0] ?? "")) {
-    return await executeWorkbench(pythonCommand, args, undefined, input);
+    return await executeWorkbench(pythonCommand, args, undefined, input, selectFinalization, withExecutionSettings);
   }
   if (CONFIGURED_WORKBENCH_STATE_DIR) {
-    return await executeWorkbench(pythonCommand, args, undefined, input);
+    return await executeWorkbench(pythonCommand, args, undefined, input, selectFinalization, withExecutionSettings);
   }
   if (fallbackWorkbenchStateDir) {
-    return await executeWorkbench(pythonCommand, args, await fallbackWorkbenchStateDir, input);
+    return await executeWorkbench(pythonCommand, args, await fallbackWorkbenchStateDir, input, selectFinalization, withExecutionSettings);
   }
   if (persistentWorkbenchStateSucceeded) {
-    return await executeWorkbench(pythonCommand, args, undefined, input);
+    return await executeWorkbench(pythonCommand, args, undefined, input, selectFinalization, withExecutionSettings);
   }
   return await withWorkbenchStateSelectionLock(async () => {
     if (fallbackWorkbenchStateDir) {
-      return await executeWorkbench(pythonCommand, args, await fallbackWorkbenchStateDir, input);
+      return await executeWorkbench(pythonCommand, args, await fallbackWorkbenchStateDir, input, selectFinalization, withExecutionSettings);
     }
     if (persistentWorkbenchStateSucceeded) {
-      return await executeWorkbench(pythonCommand, args, undefined, input);
+      return await executeWorkbench(pythonCommand, args, undefined, input, selectFinalization, withExecutionSettings);
     }
     try {
-      const result = await executeWorkbench(pythonCommand, args, undefined, input);
+      const result = await executeWorkbench(pythonCommand, args, undefined, input, selectFinalization, withExecutionSettings);
       persistentWorkbenchStateSucceeded = true;
       return result;
     } catch (error) {
       if (!isUnwritableSqliteOpenError(error)) throw error;
       const fallbackStateDir = await pinFallbackWorkbenchStateDir();
       logWorkbenchStateFallback();
-      return await executeWorkbench(pythonCommand, args, fallbackStateDir, input);
+      return await executeWorkbench(pythonCommand, args, fallbackStateDir, input, selectFinalization, withExecutionSettings);
     }
   });
 }
@@ -1707,7 +1747,9 @@ async function executeWorkbench(
   pythonCommand: string,
   args: string[],
   stateDir?: string,
-  input?: string | Buffer
+  input?: string | Buffer,
+  selectFinalization = false,
+  withExecutionSettings = false,
 ): Promise<JsonObject> {
   const userContextIndex = args.indexOf("--user-context");
   const userContext = userContextIndex === -1 ? undefined : args[userContextIndex + 1];
@@ -1716,7 +1758,12 @@ async function executeWorkbench(
     workbenchArgs.splice(userContextIndex, 2, "--user-context-stdin");
   }
   const workbenchInput = input ?? userContext;
-  const execution = execFileAsync(pythonCommand, [workbenchScriptPath(), ...workbenchArgs], {
+  const internalInvocation = selectFinalization ? "select_finalization=True"
+    : withExecutionSettings ? "with_execution_settings=True" : undefined;
+  const pythonArgs = internalInvocation
+    ? ["-c", `import runpy, sys; script = sys.argv.pop(1); runpy.run_path(script)['main'](${internalInvocation})`, workbenchScriptPath(), ...workbenchArgs]
+    : [workbenchScriptPath(), ...workbenchArgs];
+  const execution = execFileAsync(pythonCommand, pythonArgs, {
     cwd: PLUGIN_ROOT,
     env: stateDir
       ? { ...process.env, CODEX_SECURITY_STATE_DIR: stateDir }

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;
 }
 
 /**