fix: harden research workspace resolution and evidence gates

Prevent nested .omv workspaces under checkouts, ignore surface sidecars
during campaign listing, accept file:line ranges, allow verification
nuance notes with agrees:true, route needs-repro only for missing
observed_result, and add an ssrf-filter attack-surface pack from dogfood
audits.

Author: bx33661

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+- Fixed research workspace resolution so commands run from under `.omv/` (for example `.omv/checkouts/<pkg>`) reuse the owning project instead of creating a nested empty `.omv`. Supports `OMV_PROJECT_ROOT` / `OMV_ROOT` and global `--root <path>`.
+- Fixed `omv dashboard` / `omv campaign list` treating AttackSurfaceList sidecars (`*.surfaces.yaml`) as Campaign.v1 files, which produced hard validation errors after `surfaces propose`.
+- Confirmed evidence `file:line` checks now accept inclusive ranges (`path/file.go:12-18`) as well as column forms.
+- Verification `decision.status: pass` no longer fails when a review sets `agrees: true` but still lists nuance notes under `disagreements`.
+- `omv review` routes to `/omv-repro` only for missing `observed_result`, not merely for `plausible` exploitability.
+- Added `ssrf-filter` attack-surface pack for HTTP client SSRF filters and private-IP agents.
+- Documented allowed `--mode`, `--goal`, and `--budget` enums in `omv help start`, plus project-root resolution in top-level help.
+
 ## v1.0.0 - 2026-07-11
 
 - Added Windows as a validated platform with Python 3 runtime discovery, shell-independent Node test execution, cross-platform Skill packaging and LOC estimation, and an Ubuntu/Windows CI matrix. Claude Code remains the default platform when `--platform` is omitted.

scripts/run_node_tests.mjs

@@ -18,7 +18,13 @@ if (tests.length === 0) {
   console.error("No compiled Node tests found. Run npm run build first.");
   process.exit(1);
 }
-const result = spawnSync(process.execPath, ["--test", ...tests], { stdio: "inherit", windowsHide: true });
+const testEnv = { ...process.env, NO_COLOR: "1" };
+delete testEnv.FORCE_COLOR;
+const result = spawnSync(process.execPath, ["--test", ...tests], {
+  stdio: "inherit",
+  windowsHide: true,
+  env: testEnv,
+});
 if (result.error) {
   console.error(result.error.message);
   process.exit(1);

shared/surface-catalog/packs.v1.json

@@ -62,6 +62,35 @@
       "guards": ["scheme/host allowlist", "private-IP block", "redirect policy", "signature validation"],
       "false_positive_checks": ["admin-only callback URLs in single-tenant tools"]
     },
+    {
+      "id": "ssrf-filter",
+      "title": "HTTP client SSRF filter or private-IP block",
+      "vulnerability_classes": ["ssrf", "redirect"],
+      "discovery_hints": [
+        "ssrf",
+        "private ip",
+        "request filter",
+        "filtering agent",
+        "ipaddr",
+        "allowlist",
+        "denylist",
+        "metadata",
+        "169.254"
+      ],
+      "sources": ["caller-supplied URL or request options", "DNS lookup results", "redirect targets"],
+      "sinks": ["http.Agent createConnection", "fetch/axios agent", "socket connect", "unix socket path"],
+      "guards": [
+        "block non-unicast IP ranges after DNS",
+        "reject metadata and link-local",
+        "redirect policy",
+        "unix socket / socketPath policy",
+        "scheme allowlist"
+      ],
+      "false_positive_checks": [
+        "libraries that only document SSRF without implementing network connect filtering",
+        "pure DNS utilities with no outbound HTTP"
+      ]
+    },
     {
       "id": "upload-handler",
       "title": "Multipart upload and storage placement",

skills/omv-find/references/pattern-packs.md

@@ -14,6 +14,7 @@ Each pack is a discovery filter plus a source -> sink -> guard checklist. Use it
 | `config-loader` | `yaml`, `proto`, `deser`, `auth`, `crypto` | config, yaml, json, dotenv, rc, schema, plugin config | config files, environment maps, CLI overrides, JSON/YAML objects | unsafe loader, deep merge, object hook, secret/key parsing | schema validation, safe loader, key denylist, null-prototype objects, secret handling |
 | `media-tool` | `ssrf`, `upload`, `overflow`, `infoleak`, `xxe` | image, svg, pdf, video, thumbnail, metadata, exif | uploaded files, remote media URLs, embedded metadata, SVG/XML | remote fetch, parser decode, thumbnailer shell, XML parser, native bindings | URL allowlist, file magic, parser sandbox, DTD disabled, bounded decode |
 | `webhook-client` | `ssrf`, `redirect`, `auth`, `crypto` | webhook, callback, integration, notifier, bot, oauth | user-provided webhook URLs, callback targets, token config | HTTP client, redirect follow, signature verifier, callback redirect | scheme/host allowlist, private-IP block, redirect policy, signature validation |
+| `ssrf-filter` | `ssrf`, `redirect` | ssrf, private ip, request filter, filtering agent, ipaddr, metadata | caller URL/options, DNS results, redirects | agent createConnection, fetch agent, socket connect, unix socket | non-unicast block after DNS, metadata/link-local reject, redirect and socketPath policy |
 | `upload-handler` | `upload`, `traversal`, `race`, `infoleak` | upload, multipart, avatar, import, attachment, file manager | multipart filenames, content types, temp files, user-supplied paths | extension checks, move/write, public storage, post-process parser | extension allowlist, content sniffing, hash rename, quarantine, atomic move |
 
 ## Discovery Rules

src/cli/__tests__/campaign.test.ts

@@ -33,6 +33,7 @@ import {
   workspaceActivityLogPath,
   workspaceIndexPath,
 } from "../paths.js";
+import { proposeSurfaces } from "../surfaces.js";
 import { initWorkspace, readWorkspaceActivity } from "../workspace.js";
 
 const FIXED_ISO = "2026-07-10T00:00:00.000Z";
@@ -1107,6 +1108,29 @@ test("Campaign list and show leave workspace index bytes unchanged", async () =>
   }
 });
 
+test("Campaign list ignores attack-surface sidecars next to Campaign.v1 files", async () => {
+  const projectRoot = await mkdtemp(join(tmpdir(), "omv-campaign-"));
+
+  try {
+    const campaign = await initCampaign(
+      { id: "demo", target: "Acme", ecosystem: "npm", vulnerabilities: ["ssrf"] },
+      { projectRoot, now: fixedNow },
+    );
+    await proposeSurfaces(campaign.campaign.id, projectRoot);
+    const surfacesPath = join(campaignsDir(projectRoot), `${campaign.campaign.id}.surfaces.yaml`);
+    assert.equal(existsSync(surfacesPath), true);
+
+    const listed = await listCampaigns(projectRoot);
+    assert.deepEqual(
+      listed.map((item) => item.id),
+      [campaign.campaign.id],
+    );
+    assert.equal(listed[0]?.target, "Acme");
+  } finally {
+    await rm(projectRoot, { recursive: true, force: true });
+  }
+});
+
 test("Campaign ecosystem-aware next actions gate unknown targets before seed", async () => {
   const projectRoot = await mkdtemp(join(tmpdir(), "omv-campaign-"));
 

src/cli/__tests__/findings.test.ts

@@ -997,3 +997,71 @@ test("end-to-end finding flow validates, promotes, checks artifacts, and archive
     await rm(projectRoot, { recursive: true, force: true });
   }
 });
+
+
+test("confirmed findings accept file:line ranges in evidence traces", async () => {
+  const projectRoot = await mkdtemp(join(tmpdir(), "omv-fileline-"));
+  try {
+    const dir = await ensureFindingsDir(projectRoot);
+    const body = BASE_FINDING
+      .replace("status: candidate", "status: confirmed")
+      .replace(
+        "source: lib/index.js:12 options.filename",
+        "source: lib/index.js:12-18 options.filename enters sanitize",
+      )
+      .replace(
+        "sink: lib/index.js:44 fs.readFileSync",
+        "sink: lib/index.js:44-50 fs.readFileSync",
+      )
+      .replace(
+        "guard: missing path normalization",
+        "guard: lib/index.js:30-36 incomplete prefix check after normalize",
+      );
+    await writeFile(join(dir, "ranged.yaml"), body, "utf-8");
+    const result = await validateFinding("ranged", projectRoot);
+    assert.equal(result.ok, true, result.errors.join("\n"));
+    assert.equal(result.status, "confirmed");
+  } finally {
+    await rm(projectRoot, { recursive: true, force: true });
+  }
+});
+
+test("Verification.v1 pass allows nuance notes when agrees is true", async () => {
+  const projectRoot = await mkdtemp(join(tmpdir(), "omv-verif-nuance-"));
+  try {
+    const dir = await ensureFindingsDir(projectRoot);
+    await writeFile(join(dir, "confirmed.yaml"), BASE_FINDING.replace("status: candidate", "status: confirmed"), "utf-8");
+    const init = await initVerification("confirmed", projectRoot);
+    await writeFile(
+      verificationPath("confirmed", projectRoot),
+      `schema_version: "1"
+finding_id: "confirmed"
+finding_sha256: "${init.findingSha256}"
+reviews:
+  - reviewer: verifier
+    target: evidence.guard
+    agrees: true
+    disagreements:
+      - "impact requires sibling path pre-positioning"
+    required_changes: []
+    confidence: high
+    reviewed_at: "2026-04-29"
+decision:
+  status: pass
+  reason: agrees with nuance notes only
+  required_for_confirmed: true
+provenance:
+  generated_at: "2026-04-29"
+  tool: omv
+  tool_version: test
+`,
+      "utf-8",
+    );
+    const validation = await validateVerification("confirmed", projectRoot);
+    assert.equal(validation.ok, true, validation.errors.join("\n"));
+    assert.equal(validation.status, "pass");
+    assert.equal(validation.disagreements, 0);
+  } finally {
+    await rm(projectRoot, { recursive: true, force: true });
+  }
+});

src/cli/__tests__/project-root.test.ts

@@ -0,0 +1,101 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { projectRootIfInsideOmvState, resolveProjectRoot } from "../paths.js";
+import { extractProjectRootOption } from "../commands/index.js";
+
+test("projectRootIfInsideOmvState maps checkouts back to the owner project", () => {
+  const root = "/tmp/research-root";
+  assert.equal(
+    projectRootIfInsideOmvState(join(root, ".omv", "checkouts", "pkg")),
+    root,
+  );
+  assert.equal(
+    projectRootIfInsideOmvState(join(root, ".omv", "findings")),
+    root,
+  );
+  assert.equal(projectRootIfInsideOmvState(root), undefined);
+  assert.equal(projectRootIfInsideOmvState(join(root, "src")), undefined);
+});
+
+test("resolveProjectRoot prefers OMV_PROJECT_ROOT over walk-up", async () => {
+  const outer = await mkdtemp(join(tmpdir(), "omv-root-outer-"));
+  const inner = await mkdtemp(join(tmpdir(), "omv-root-inner-"));
+  try {
+    await mkdir(join(outer, ".omv"), { recursive: true });
+    await mkdir(join(inner, ".omv"), { recursive: true });
+    const previous = process.env.OMV_PROJECT_ROOT;
+    process.env.OMV_PROJECT_ROOT = inner;
+    try {
+      assert.equal(resolveProjectRoot(outer), inner);
+    } finally {
+      if (previous === undefined) {
+        delete process.env.OMV_PROJECT_ROOT;
+      } else {
+        process.env.OMV_PROJECT_ROOT = previous;
+      }
+    }
+  } finally {
+    await rm(outer, { recursive: true, force: true });
+    await rm(inner, { recursive: true, force: true });
+  }
+});
+
+test("resolveProjectRoot walks up to nearest .omv owner from a subdirectory", async () => {
+  const project = await mkdtemp(join(tmpdir(), "omv-root-walk-"));
+  try {
+    await mkdir(join(project, ".omv", "findings"), { recursive: true });
+    await writeFile(join(project, ".omv", "index.json"), "{\"version\":1,\"findings\":[]}\n", "utf-8");
+    const nested = join(project, "src", "cli");
+    await mkdir(nested, { recursive: true });
+    const previous = process.env.OMV_PROJECT_ROOT;
+    delete process.env.OMV_PROJECT_ROOT;
+    delete process.env.OMV_ROOT;
+    try {
+      assert.equal(resolveProjectRoot(nested), project);
+    } finally {
+      if (previous !== undefined) {
+        process.env.OMV_PROJECT_ROOT = previous;
+      }
+    }
+  } finally {
+    await rm(project, { recursive: true, force: true });
+  }
+});
+
+test("resolveProjectRoot does not create nested workspaces under .omv/checkouts", async () => {
+  const project = await mkdtemp(join(tmpdir(), "omv-root-checkout-"));
+  try {
+    const checkout = join(project, ".omv", "checkouts", "sanitize-url");
+    await mkdir(checkout, { recursive: true });
+    await mkdir(join(project, ".omv", "findings"), { recursive: true });
+    // Accidental nested workspace under the checkout must not win.
+    await mkdir(join(checkout, ".omv", "findings"), { recursive: true });
+    const previous = process.env.OMV_PROJECT_ROOT;
+    delete process.env.OMV_PROJECT_ROOT;
+    delete process.env.OMV_ROOT;
+    try {
+      assert.equal(resolveProjectRoot(checkout), project);
+    } finally {
+      if (previous !== undefined) {
+        process.env.OMV_PROJECT_ROOT = previous;
+      }
+    }
+  } finally {
+    await rm(project, { recursive: true, force: true });
+  }
+});
+
+test("extractProjectRootOption strips --root forms", () => {
+  assert.deepEqual(extractProjectRootOption(["--root", "/tmp/ws", "dashboard", "--json"]), {
+    args: ["dashboard", "--json"],
+    root: "/tmp/ws",
+  });
+  assert.deepEqual(extractProjectRootOption(["findings", "list", "--root=/tmp/ws"]), {
+    args: ["findings", "list"],
+    root: "/tmp/ws",
+  });
+  assert.equal(extractProjectRootOption(["--root"]).error, "--root requires a directory path");
+});

src/cli/__tests__/surfaces.test.ts

@@ -26,11 +26,31 @@ test("surface catalog proposes cards that intersect campaign vulnerability class
   const list = proposeCardsForCampaign(campaign, catalog);
   const ids = list.cards.map((card) => card.id).sort();
   assert.ok(ids.includes("renderer-pipeline"));
+  assert.ok(ids.includes("ssrf-filter"), `expected ssrf-filter in ${ids.join(",")}`);
   assert.ok(ids.includes("webhook-client") || ids.includes("media-tool"));
   assert.ok(list.cards.every((card) => card.status === "proposed"));
   assert.ok(list.cards.every((card) => card.finding_id.startsWith(`${campaign.id}-`)));
 });
 
+test("ssrf-only campaigns propose the ssrf-filter pack", async () => {
+  const catalog = await loadSurfaceCatalog();
+  const campaign = (
+    await initCampaign(
+      {
+        target: "FilterLib",
+        version: "1",
+        ecosystem: "npm",
+        vulnerabilities: ["ssrf"],
+      },
+      { projectRoot: await emptyProject() },
+    )
+  ).campaign;
+  const list = proposeCardsForCampaign(campaign, catalog);
+  const ids = list.cards.map((card) => card.id);
+  assert.ok(ids.includes("ssrf-filter"));
+  assert.ok(ids.includes("webhook-client") || ids.includes("media-tool"));
+});
+
 test("surfaces propose/select drive campaign seed finding ids", async () => {
   const projectRoot = await emptyProject();
   try {

src/cli/campaign-seed.ts

@@ -10,7 +10,7 @@ import {
   type EvidenceResearcherGoal,
   type FindingTemplateResult,
 } from "./findings.js";
-import { campaignSurfacesPath, findingsDir } from "./paths.js";
+import { campaignSurfacesPath, findingsDir, resolveProjectRoot } from "./paths.js";
 import { readSurfaceList, selectedSeedTargets, type AttackSurfaceCard } from "./surfaces.js";
 
 export interface CampaignSeedSkipped {
@@ -51,7 +51,7 @@ export interface SeedCampaignDependencies {
 
 export async function seedCampaign(
   id: string,
-  projectRoot = process.cwd(),
+  projectRoot = resolveProjectRoot(),
   dependencies: SeedCampaignDependencies = {},
 ): Promise<CampaignSeedResult> {
   const detail = await showCampaign(id, projectRoot);

src/cli/campaign.ts

@@ -2,7 +2,7 @@ import { existsSync } from "fs";
 import { link, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, rmdir, unlink, writeFile } from "fs/promises";
 import { basename, join } from "path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
-import { campaignPath, campaignRunbookPath, campaignsDir, workspaceActivityLogPath } from "./paths.js";
+import { campaignPath, campaignRunbookPath, campaignsDir, workspaceActivityLogPath, resolveProjectRoot } from "./paths.js";
 import { appendWorkspaceActivity } from "./workspace.js";
 
 export const CAMPAIGN_MODES = ["whitebox", "graybox", "local-lab", "passive", "mixed"] as const;
@@ -374,7 +374,7 @@ export async function initCampaign(
   options: InitCampaignOptions = {},
 ): Promise<InitCampaignResult> {
   const campaign = buildCampaign(input, options.now);
-  const projectRoot = options.projectRoot ?? process.cwd();
+  const projectRoot = options.projectRoot ?? resolveProjectRoot();
   const force = options.force ?? false;
   await ensureRealCampaignDirectory(projectRoot);
   const result = await withCampaignLock(
@@ -395,17 +395,19 @@ export async function initCampaign(
   }
 }
 
-export async function listCampaigns(projectRoot = process.cwd()): Promise<CampaignSummary[]> {
+export async function listCampaigns(projectRoot = resolveProjectRoot()): Promise<CampaignSummary[]> {
   const dir = campaignsDir(projectRoot);
   if (!existsSync(dir)) {
     return [];
   }
 
+  // Only Campaign.v1 sources: <id>.yaml / <id>.yml.
+  // Sidecars such as <id>.surfaces.yaml share the campaigns directory and must not be listed.
   const files = (await readdir(dir, { withFileTypes: true }))
-    .filter((dirent) => dirent.isFile() && /\.ya?ml$/.test(dirent.name))
+    .filter((dirent) => dirent.isFile() && isCampaignSourceFileName(dirent.name))
     .map((dirent) => dirent.name);
   const summaries: CampaignSummary[] = [];
-  const ids = [...new Set(files.map((file) => file.replace(/\.ya?ml$/, "")))];
+  const ids = [...new Set(files.map((file) => file.replace(/\.ya?ml$/i, "")))];
   for (const id of ids) {
     const path = resolveCampaignSource(id, projectRoot);
     if (!path) {
@@ -425,9 +427,17 @@ export async function listCampaigns(projectRoot = process.cwd()): Promise<Campai
   return summaries.sort((left, right) => left.id.localeCompare(right.id));
 }
 
+/** True for Campaign.v1 filenames; false for sidecars (e.g. *.surfaces.yaml) and other artifacts. */
+export function isCampaignSourceFileName(name: string): boolean {
+  if (/\.surfaces\.ya?ml$/i.test(name)) {
+    return false;
+  }
+  return /\.ya?ml$/i.test(name);
+}
+
 export async function showCampaign(
   id: string,
-  projectRoot = process.cwd(),
+  projectRoot = resolveProjectRoot(),
 ): Promise<ShowCampaignResult> {
   const normalizedId = normalizeCampaignId(id);
   const yamlPath = resolveCampaignSource(normalizedId, projectRoot);