fix: make missing scan artifact failures actionable (#167)

* fix: allow completion when no draft manifest exists yet

Fresh recipe-driven scans fail at completion with:

  Could not save the Codex Security scan: scan-manifest.json:
  expected a regular file inside the scan directory.

`workbench_db.complete_scan` reads `scan-manifest.json` with
`required=True` when `scan.recipe_json is not None`, but on a first
completion of a fresh scan there is no prior draft on disk yet — the
draft is authored later by `_write_prepared_scan_finalization`. The
read therefore always raises before the write can happen, and every
retry still throws before writing anything, so `scan_dir` stays empty
and models are billed with no artifacts produced.

Make the pre-write read optional. When a prior manifest is present
(resumed / re-completed scans), preserve the sealed timestamps as
before; otherwise skip that step and let the downstream finalizer
write the draft.

Verified against `pnpm run lint` (tsc --noEmit) and the full
`bun test` suite on the public SDK: 367 pass, 23 expected skips,
0 fail.

Refs #73

* fix: diagnose missing scan agent draft artifacts

---------

Co-authored-by: Onur Tirpan <otirpan@cscleasing.com>
Co-authored-by: Onur Tirpan <posta@onurtirpan.com>

Author: mldangelo-oai

sdk/typescript/_bundled_plugin/scripts/workbench_db.py

@@ -1414,18 +1414,32 @@ def complete_scan_locked(
     completion_timestamp = now()
     completion_binding = workbench_completion_binding(scan, completion_timestamp)
     if scan["recipe_json"] is not None:
-        # Fresh recipe-driven scans have no prior scan-manifest.json on disk — the
-        # draft is authored later by _write_prepared_scan_finalization. Guard the
-        # read so first-time completion does not fail with "expected a regular
-        # file inside the scan directory" (issue #73). When a prior manifest does
-        # exist (resumed / re-completed scans), preserve the sealed timestamps.
-        manifest_path = artifact_path(scan_dir, ARTIFACTS["manifest"], required=False)
-        if manifest_path is not None:
-            manifest = read_json_object(manifest_path)
-            manifest_scan = manifest.get("scan")
-            if isinstance(manifest_scan, dict) and manifest_scan.get("sealedAt") is not None:
-                completion_binding["startedAt"] = manifest_scan.get("startedAt")
-                completion_binding["completedAt"] = manifest_scan.get("completedAt")
+        draft_artifacts: dict[str, Path] = {}
+        missing_drafts = []
+        for file_name in (
+            ARTIFACTS["manifest"],
+            ARTIFACTS["findings"],
+            ARTIFACTS["coverage"],
+        ):
+            try:
+                (scan_dir / file_name).lstat()
+            except FileNotFoundError:
+                missing_drafts.append(file_name)
+                continue
+            draft_path = artifact_path(scan_dir, file_name, required=True)
+            if draft_path is not None:
+                draft_artifacts[file_name] = draft_path
+        if missing_drafts:
+            raise SystemExit(
+                "Scan agent did not create required draft artifacts: "
+                f"{', '.join(missing_drafts)}. Check that the scan agent can run shell "
+                "commands and write to the scan directory before retrying."
+            )
+        manifest = read_json_object(draft_artifacts[ARTIFACTS["manifest"]])
+        manifest_scan = manifest.get("scan")
+        if isinstance(manifest_scan, dict) and manifest_scan.get("sealedAt") is not None:
+            completion_binding["startedAt"] = manifest_scan.get("startedAt")
+            completion_binding["completedAt"] = manifest_scan.get("completedAt")
     try:
         prepared = _prepare_scan_finalization(
             scan_dir,

sdk/typescript/tests-ts/runtime.test.ts

@@ -7,6 +7,7 @@ import {
   mkdir,
   mkdtemp,
   readFile,
+  readlink,
   realpath,
   readdir,
   rename,
@@ -1858,6 +1859,132 @@ describe("runtime directories and plugin Python boundary", () => {
     expect(result).toEqual({ ok: true });
   });
 
+  test.each([
+    ["all required draft artifacts", []],
+    ["the manifest draft", ["findings.json", "coverage.json"]],
+    ["the findings draft", ["scan-manifest.json", "coverage.json"]],
+    ["the coverage draft", ["scan-manifest.json", "findings.json"]],
+  ] as const)(
+    "rejects recipe scans when the agent did not create %s",
+    async (_description, present) => {
+      const python = Bun.which("python3") ?? Bun.which("python");
+      expect(python).not.toBeNull();
+      const requiredDrafts = [
+        "scan-manifest.json",
+        "findings.json",
+        "coverage.json",
+      ] as const;
+      const root = await temporaryDirectory("codex-security-missing-drafts-");
+      const repository = join(root, "repository");
+      const scanDir = join(root, "scan");
+      await mkdir(repository);
+      await mkdir(scanDir, { mode: 0o700 });
+      const workbenchOptions = {
+        python: python!,
+        pluginRoot: PLUGIN_ROOT,
+        environment: {
+          PATH: process.env["PATH"],
+          CODEX_SECURITY_STATE_DIR: join(root, "state"),
+        },
+      };
+      const registration = await runWorkbench(workbenchOptions, [
+        "register-cli-scan",
+        "--repository",
+        repository,
+        "--scan-dir",
+        scanDir,
+        "--recipe-json",
+        JSON.stringify({
+          config: {},
+          mode: "standard",
+          repository,
+          target: { kind: "repository", paths: [] },
+        }),
+      ]);
+      await Promise.all(
+        present.map((filename) =>
+          copyFile(
+            join(PLUGIN_ROOT, "examples", "completed-scan", filename),
+            join(scanDir, filename),
+          ),
+        ),
+      );
+      const missing = requiredDrafts.filter(
+        (filename) => !present.some((candidate) => candidate === filename),
+      );
+
+      await expect(
+        runWorkbench(workbenchOptions, [
+          "complete-scan",
+          "--scan-id",
+          String(registration["scanId"]),
+        ]),
+      ).rejects.toThrow(
+        `Scan agent did not create required draft artifacts: ${missing.join(
+          ", ",
+        )}. Check that the scan agent can run shell commands and write to the scan directory before retrying.`,
+      );
+      expect((await readdir(scanDir)).sort()).toEqual([...present].sort());
+      const stored = await runWorkbench(workbenchOptions, [
+        "get-scan",
+        "--scan-id",
+        String(registration["scanId"]),
+      ]);
+      expect(stored["scan"]).toMatchObject({
+        progress: { status: "running" },
+      });
+    },
+  );
+
+  testPosix("rejects symlinked recipe scan draft artifacts", async () => {
+    const root = await temporaryDirectory("codex-security-symlinked-draft-");
+    const repository = join(root, "repository");
+    const scanDir = join(root, "scan");
+    await mkdir(repository);
+    await mkdir(scanDir, { mode: 0o700 });
+    const python = Bun.which("python3") ?? Bun.which("python");
+    expect(python).not.toBeNull();
+    const workbenchOptions = {
+      python: python!,
+      pluginRoot: PLUGIN_ROOT,
+      environment: {
+        PATH: process.env["PATH"],
+        CODEX_SECURITY_STATE_DIR: join(root, "state"),
+      },
+    };
+    const registration = await runWorkbench(workbenchOptions, [
+      "register-cli-scan",
+      "--repository",
+      repository,
+      "--scan-dir",
+      scanDir,
+      "--recipe-json",
+      JSON.stringify({
+        config: {},
+        mode: "standard",
+        repository,
+        target: { kind: "repository", paths: [] },
+      }),
+    ]);
+    await symlink(
+      join(root, "missing-manifest.json"),
+      join(scanDir, "scan-manifest.json"),
+    );
+
+    await expect(
+      runWorkbench(workbenchOptions, [
+        "complete-scan",
+        "--scan-id",
+        String(registration["scanId"]),
+      ]),
+    ).rejects.toThrow(
+      "scan-manifest.json: expected a regular file inside the scan directory.",
+    );
+    expect(await readlink(join(scanDir, "scan-manifest.json"))).toBe(
+      join(root, "missing-manifest.json"),
+    );
+  });
+
   test("preserves recorded artifact paths when archiving a completed scan", async () => {
     const root = await temporaryDirectory();
     const scanDir = join(root, "scan");