@bugmole/cli 0.4.0

package/src/runtime/journey-editor.ts

@@ -0,0 +1,452 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { projectPrefix } from "../storage/keys.js";
+import {
+  emptyJourneyGraph,
+  repairJourneyGraph,
+  validateJourneyGraph,
+  type JourneyEdge,
+  type JourneyGraph,
+  type JourneyNode,
+  type UserJourney,
+} from "./journey-graph.js";
+import { blockerFingerprint, readBlockerResolution } from "./blocker-resolution.js";
+
+type JourneyConfig = {
+  runtime?: { spec_dir?: string; artifacts_dir?: string };
+  storage?: any;
+  project?: { id?: string; app_id?: string; environment_id?: string };
+};
+
+export type JourneyNextTask = {
+  status: "actionable" | "exhausted" | "blocked";
+  journeyId: string;
+  reason: string;
+  nodeId?: string;
+  route?: string;
+  action?: string;
+  edgeId?: string;
+  controlId?: string;
+  nextSteps: string[];
+  clarification?: {
+    status: "needed" | "remembered";
+    fingerprint: string;
+    question: string;
+    reason: string;
+    resolutionId?: string;
+  };
+};
+
+function graphPath(cfg: JourneyConfig): string {
+  return path.join(cfg.runtime?.spec_dir || "./spec", "journeys.graph.json");
+}
+
+function projectId(cfg: JourneyConfig): string {
+  return cfg.project?.id || "default";
+}
+
+function storeFor(cfg: JourneyConfig) {
+  return createProjectObjectStore(cfg);
+}
+
+export function readJourneyGraph(cfg: JourneyConfig): JourneyGraph {
+  const file = graphPath(cfg);
+  if (!fs.existsSync(file)) return emptyJourneyGraph(projectId(cfg));
+  const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as JourneyGraph;
+  const graph = {
+    ...emptyJourneyGraph(projectId(cfg)),
+    ...parsed,
+    journeys: Array.isArray(parsed.journeys) ? parsed.journeys : [],
+    nodes: Array.isArray(parsed.nodes) ? parsed.nodes : [],
+    edges: Array.isArray(parsed.edges) ? parsed.edges : [],
+  };
+  return repairJourneyGraph(graph, projectId(cfg));
+}
+
+export async function writeJourneyGraph(cfg: JourneyConfig, graph: JourneyGraph): Promise<JourneyGraph> {
+  const validation = validateJourneyGraph(graph);
+  if (!validation.valid) throw new Error(`Invalid journey graph: ${validation.errors.join("; ")}`);
+  const content = JSON.stringify(graph, null, 2) + "\n";
+  fs.mkdirSync(path.dirname(graphPath(cfg)), { recursive: true });
+  fs.writeFileSync(graphPath(cfg), content, "utf8");
+  await storeFor(cfg).put(
+    `${projectPrefix(projectId(cfg))}/journeys/graph.json`,
+    content,
+    "application/json",
+  );
+  return graph;
+}
+
+function idPart(value: string): string {
+  return value.trim().replace(/[^a-zA-Z0-9._:-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+function requireJourney(graph: JourneyGraph, journeyId: string): UserJourney {
+  const journey = graph.journeys.find((item) => item.id === journeyId);
+  if (!journey) throw new Error(`Journey not found: ${journeyId}`);
+  return journey;
+}
+
+function nextRevision(journey: UserJourney): UserJourney {
+  return {
+    ...journey,
+    revision: (journey.revision || 0) + 1,
+    status: "draft",
+    stability: "stabilizing",
+    linkedToGraph: false,
+  };
+}
+
+export async function stabilizeJourney(
+  cfg: JourneyConfig,
+  input: { journeyId: string; verificationRunId: string; verifiedAt?: string },
+) {
+  if (!input.verificationRunId.trim()) throw new Error("verificationRunId is required");
+  const graph = readJourneyGraph(cfg);
+  const current = requireJourney(graph, input.journeyId);
+  const journey: UserJourney = {
+    ...current,
+    status: "published",
+    stability: "stable",
+    linkedToGraph: true,
+    verificationRunId: input.verificationRunId.trim(),
+    verifiedAt: input.verifiedAt || new Date().toISOString(),
+  };
+  graph.journeys = graph.journeys.map((item) => item.id === current.id ? journey : item);
+  return { graph: await writeJourneyGraph(cfg, graph), journey };
+}
+
+export async function createJourney(
+  cfg: JourneyConfig,
+  input: { id?: string; name: string; description?: string; actor: string; startNodeId?: string },
+) {
+  const graph = readJourneyGraph(cfg);
+  const id = idPart(input.id || input.name.toLowerCase().replace(/\s+/g, "-"));
+  if (!id || !input.name.trim() || !input.actor.trim()) throw new Error("id/name and actor are required");
+  if (graph.journeys.some((journey) => journey.id === id)) throw new Error(`Journey already exists: ${id}`);
+  if (input.startNodeId && !graph.nodes.some((node) => node.id === input.startNodeId)) {
+    throw new Error(`Start node not found: ${input.startNodeId}`);
+  }
+  const journey: UserJourney = {
+    id,
+    name: input.name.trim(),
+    description: input.description?.trim(),
+    actor: input.actor.trim(),
+    startNodeId: input.startNodeId,
+    nodeIds: input.startNodeId ? [input.startNodeId] : [],
+    edgeIds: [],
+    revision: 1,
+    status: "draft",
+    sourceOfTruth: "canonical_flow",
+    stability: "discovered",
+    linkedToGraph: false,
+  };
+  graph.journeys.push(journey);
+  return { graph: await writeJourneyGraph(cfg, graph), journey };
+}
+
+export async function addJourneyStep(
+  cfg: JourneyConfig,
+  input: { journeyId: string; node: Omit<JourneyNode, "id"> & { id?: string }; afterNodeId?: string },
+) {
+  const graph = readJourneyGraph(cfg);
+  const journey = requireJourney(graph, input.journeyId);
+  const nodeId = idPart(input.node.id || `step-${Date.now()}`);
+  if (!nodeId || graph.nodes.some((node) => node.id === nodeId)) throw new Error(`Node already exists: ${nodeId}`);
+  const node = { ...input.node, id: nodeId } as JourneyNode;
+  graph.nodes.push(node);
+  if (input.afterNodeId) {
+    if (!journey.nodeIds.includes(input.afterNodeId)) throw new Error(`Journey node not found: ${input.afterNodeId}`);
+    journey.nodeIds = [...journey.nodeIds, nodeId];
+  } else {
+    journey.nodeIds = [...journey.nodeIds, nodeId];
+  }
+  if (!journey.startNodeId) journey.startNodeId = nodeId;
+  const updated = nextRevision(journey);
+  graph.journeys = graph.journeys.map((item) => item.id === journey.id ? updated : item);
+  return { graph: await writeJourneyGraph(cfg, graph), journey: updated, node };
+}
+
+export async function reuseJourneyStep(
+  cfg: JourneyConfig,
+  input: { journeyId: string; sourceJourneyId: string; stepId: string; alias?: string },
+) {
+  const graph = readJourneyGraph(cfg);
+  const target = requireJourney(graph, input.journeyId);
+  const source = requireJourney(graph, input.sourceJourneyId);
+  if (!source.nodeIds.includes(input.stepId)) {
+    throw new Error(`Step ${input.stepId} is not part of source journey ${input.sourceJourneyId}`);
+  }
+  if (!graph.nodes.some((node) => node.id === input.stepId)) {
+    throw new Error(`Step node not found: ${input.stepId}`);
+  }
+  const updated = nextRevision({
+    ...target,
+    nodeIds: [...new Set([...target.nodeIds, input.stepId])],
+    reuses: [
+      ...(target.reuses ?? []),
+      { flowId: source.id, stepId: input.stepId, alias: input.alias?.trim() || undefined },
+    ],
+  });
+  graph.journeys = graph.journeys.map((item) => item.id === target.id ? updated : item);
+  return { graph: await writeJourneyGraph(cfg, graph), journey: updated };
+}
+
+export async function addJourneyTransition(
+  cfg: JourneyConfig,
+  input: { journeyId: string; from: string; to: string; edge?: Partial<JourneyEdge> },
+) {
+  const graph = readJourneyGraph(cfg);
+  const journey = requireJourney(graph, input.journeyId);
+  if (!graph.nodes.some((node) => node.id === input.from) || !graph.nodes.some((node) => node.id === input.to)) {
+    throw new Error("Transition endpoints must reference existing nodes");
+  }
+  const edgeId = idPart(input.edge?.id || `${input.from}->${input.to}:${Date.now()}`);
+  if (graph.edges.some((edge) => edge.id === edgeId)) throw new Error(`Edge already exists: ${edgeId}`);
+  const edge: JourneyEdge = { ...input.edge, id: edgeId, from: input.from, to: input.to };
+  graph.edges.push(edge);
+  journey.nodeIds = [...new Set([...journey.nodeIds, input.from, input.to])];
+  journey.edgeIds = [...journey.edgeIds, edgeId];
+  const updated = nextRevision(journey);
+  graph.journeys = graph.journeys.map((item) => item.id === journey.id ? updated : item);
+  return { graph: await writeJourneyGraph(cfg, graph), journey: updated, edge };
+}
+
+export async function updateJourney(
+  cfg: JourneyConfig,
+  input: { journeyId: string; journey?: Partial<UserJourney>; node?: Partial<JourneyNode> & { id: string }; edge?: Partial<JourneyEdge> & { id: string } },
+) {
+  const graph = readJourneyGraph(cfg);
+  const current = requireJourney(graph, input.journeyId);
+  let updated = { ...current, ...(input.journey || {}) };
+  if (input.node) {
+    const index = graph.nodes.findIndex((node) => node.id === input.node!.id);
+    if (index < 0) throw new Error(`Node not found: ${input.node.id}`);
+    graph.nodes[index] = { ...graph.nodes[index], ...input.node };
+  }
+  if (input.edge) {
+    const index = graph.edges.findIndex((edge) => edge.id === input.edge!.id);
+    if (index < 0) throw new Error(`Edge not found: ${input.edge.id}`);
+    graph.edges[index] = { ...graph.edges[index], ...input.edge };
+  }
+  updated = nextRevision(updated);
+  graph.journeys = graph.journeys.map((journey) => journey.id === current.id ? updated : journey);
+  return { graph: await writeJourneyGraph(cfg, graph), journey: updated };
+}
+
+export async function removeJourneyItem(
+  cfg: JourneyConfig,
+  input: { journeyId: string; nodeId?: string; edgeId?: string },
+) {
+  const graph = readJourneyGraph(cfg);
+  const current = requireJourney(graph, input.journeyId);
+  if (!input.nodeId && !input.edgeId) throw new Error("nodeId or edgeId is required");
+  if (input.nodeId) {
+    if (!graph.nodes.some((node) => node.id === input.nodeId)) throw new Error(`Node not found: ${input.nodeId}`);
+    graph.nodes = graph.nodes.filter((node) => node.id !== input.nodeId);
+    graph.edges = graph.edges.filter((edge) => edge.from !== input.nodeId && edge.to !== input.nodeId);
+    current.nodeIds = current.nodeIds.filter((id) => id !== input.nodeId);
+    current.edgeIds = current.edgeIds.filter((id) => graph.edges.some((edge) => edge.id === id));
+    if (current.startNodeId === input.nodeId) current.startNodeId = current.nodeIds[0];
+  } else if (input.edgeId) {
+    if (!graph.edges.some((edge) => edge.id === input.edgeId)) throw new Error(`Edge not found: ${input.edgeId}`);
+    graph.edges = graph.edges.filter((edge) => edge.id !== input.edgeId);
+    current.edgeIds = current.edgeIds.filter((id) => id !== input.edgeId);
+  }
+  const updated = nextRevision(current);
+  graph.journeys = graph.journeys.map((journey) => journey.id === current.id ? updated : journey);
+  return { graph: await writeJourneyGraph(cfg, graph), journey: updated };
+}
+
+export function nextJourneyTask(cfg: JourneyConfig, journeyId: string): JourneyNextTask {
+  const graph = readJourneyGraph(cfg);
+  const journey = requireJourney(graph, journeyId);
+  const included = new Set(journey.nodeIds);
+  const includedEdges = new Set(journey.edgeIds);
+  const coveredTransitions = new Set(
+    graph.edges
+      .filter((edge) => includedEdges.has(edge.id))
+      .map((edge) => `${edge.from}->${edge.to}`),
+  );
+  const blocked = graph.nodes.find((node) => {
+    if (!included.has(node.id)) return false;
+    const probe = (node as any).runtimeProbe;
+    return probe?.status === "blocked" || probe?.status === "unreachable";
+  });
+  if (blocked) {
+    const probe = (blocked as any).runtimeProbe;
+    return {
+      status: "blocked",
+      journeyId,
+      reason: probe?.reason
+        ? `Runtime access is unavailable for ${blocked.route || blocked.id}: ${probe.reason}`
+        : `Runtime access is blocked for ${blocked.route || blocked.id}.`,
+      nodeId: blocked.id,
+      route: blocked.route,
+      nextSteps: [
+        `Resolve runtime access for ${blocked.route || blocked.id}`,
+        "Ask the user for clarification if the required access or startup action is unknown",
+        "Retry bugmole_journey_next after recording the resolution",
+      ],
+    };
+  }
+  const pathScoped = (journey as any).metadata?.flowScope === "path";
+  if (pathScoped) {
+    const metadata = (journey as any).metadata ?? {};
+    const verifiedEdgeIds = new Set(
+      Array.isArray(metadata.verifiedEdgeIds) ? metadata.verifiedEdgeIds : [],
+    );
+    const unverifiedEdgeId = journey.edgeIds.find((edgeId) => !verifiedEdgeIds.has(edgeId));
+    if (unverifiedEdgeId) {
+      const edge = graph.edges.find((item) => item.id === unverifiedEdgeId);
+      const target = edge ? graph.nodes.find((node) => node.id === edge.to) : undefined;
+      return {
+        status: "actionable",
+        journeyId,
+        reason: "This source-discovered transition still needs runtime verification.",
+        nodeId: target?.id,
+        route: target?.route,
+        action: edge?.label || edge?.condition || edge?.id || unverifiedEdgeId,
+        edgeId: unverifiedEdgeId,
+        nextSteps: [
+          `Perform "${edge?.label || edge?.condition || unverifiedEdgeId}" from ${edge?.from || journey.startNodeId}`,
+          "Record the observed screen and transition with bugmole_record_discovery",
+          "Call bugmole_journey_next again after recording the evidence",
+        ],
+      };
+    }
+    const goalNodeId = typeof metadata.goalNodeId === "string"
+      ? metadata.goalNodeId
+      : typeof metadata.goal?.nodeId === "string" ? metadata.goal.nodeId : undefined;
+    const completedGoalIds = new Set(
+      Array.isArray(metadata.completedGoalIds) ? metadata.completedGoalIds : [],
+    );
+    const goal = goalNodeId ? graph.nodes.find((node) => node.id === goalNodeId) : undefined;
+    const controls = graph.nodes
+      .filter((node) => included.has(node.id))
+      .flatMap((node) => Array.isArray((node as any).metadata?.interactiveControls)
+        ? (node as any).metadata.interactiveControls.map((control: any) => ({ ...control, nodeId: node.id }))
+        : []);
+    const verifiedControlIds = new Set(
+      Array.isArray(metadata.verifiedControlIds) ? metadata.verifiedControlIds : [],
+    );
+    const unverifiedControl = controls.find(
+      (control: any) => typeof control?.id === "string" && !verifiedControlIds.has(control.id),
+    );
+    if (unverifiedControl) {
+      return {
+        status: "actionable",
+        journeyId,
+        reason: "The flow still has an unchecked button, link, or action.",
+        nodeId: unverifiedControl.nodeId,
+        route: graph.nodes.find((node) => node.id === unverifiedControl.nodeId)?.route,
+        action: `${unverifiedControl.label || unverifiedControl.id}${unverifiedControl.destinationRoute
+          ? ` → ${unverifiedControl.destinationRoute}`
+          : ""}`,
+        controlId: unverifiedControl.id,
+        nextSteps: [
+          `Inspect and perform "${unverifiedControl.label || unverifiedControl.id}" on ${unverifiedControl.nodeId}`,
+          "Confirm its destination or terminal behavior, then record it with verifiedControlIds",
+          "Call bugmole_journey_next again before claiming the journey is complete",
+        ],
+      };
+    }
+    if (goalNodeId && !completedGoalIds.has(goalNodeId)) {
+      return {
+        status: "actionable",
+        journeyId,
+        reason: "The journey reached its goal screen but the terminal action is not verified.",
+        nodeId: goal?.id,
+        route: goal?.route,
+        action: `Complete and verify ${goal?.title || goalNodeId}`,
+        nextSteps: [
+          `Complete the terminal action on ${goal?.route || goalNodeId}`,
+          "Record the result and proof with bugmole_record_discovery using completedNodeIds",
+          "Call bugmole_journey_next again after recording the completion",
+        ],
+      };
+    }
+    return {
+      status: "exhausted",
+      journeyId,
+      reason: "Every transition was runtime-verified and the terminal goal was completed.",
+      nextSteps: ["Read the final journey graph", `Call bugmole_plan for ${journeyId} if planning is required`],
+    };
+  }
+  const candidate = graph.edges.find((edge) => {
+    if (!included.has(edge.from)) return false;
+    if (coveredTransitions.has(`${edge.from}->${edge.to}`)) return false;
+    return !included.has(edge.to) || !includedEdges.has(edge.id);
+  });
+  if (candidate) {
+    const target = graph.nodes.find((node) => node.id === candidate.to);
+    return {
+      status: "actionable",
+      journeyId,
+      reason: "The flow has an unrecorded outgoing transition.",
+      nodeId: target?.id,
+      route: target?.route,
+      action: candidate.label || candidate.condition || candidate.id,
+      edgeId: candidate.id,
+      nextSteps: [
+        `Perform or inspect "${candidate.label || candidate.condition || candidate.id}" from ${candidate.from}`,
+        `Record the resulting node and transition with bugmole_record_discovery or bugmole_journey_add_step`,
+        "Call bugmole_journey_next again after recording the result",
+      ],
+    };
+  }
+  return {
+    status: "exhausted",
+    journeyId,
+    reason: "Every node and transition in this selected flow is represented.",
+    nextSteps: ["Read the final journey graph", `Call bugmole_plan for ${journeyId} if planning is required`],
+  };
+}
+
+export async function nextJourneyTaskWithClarification(
+  cfg: JourneyConfig,
+  journeyId: string,
+): Promise<JourneyNextTask> {
+  const task = nextJourneyTask(cfg, journeyId);
+  if (task.status !== "blocked") return task;
+  const input = {
+    category: "journey-access",
+    reason: task.reason,
+    route: task.route,
+    nodeId: task.nodeId,
+    environmentId: cfg.project?.environment_id,
+  };
+  const fingerprint = blockerFingerprint(input);
+  const resolution = await readBlockerResolution(cfg, input);
+  if (resolution) {
+    return {
+      ...task,
+      clarification: {
+        status: "remembered",
+        fingerprint,
+        question: resolution.question,
+        reason: resolution.reason,
+        resolutionId: resolution.resolutionId,
+      },
+      nextSteps: [
+        "Verify the remembered resolution still applies to the current blocker evidence",
+        "Call bugmole_resolve_blocker with a corrected resolution if it does not",
+        "Retry the journey task after verification",
+      ],
+    };
+  }
+  return {
+    ...task,
+    clarification: {
+      status: "needed",
+      fingerprint,
+      question: `How should the agent resolve this blocker at ${task.route || task.nodeId || "the current step"}?`,
+      reason: task.reason,
+    },
+    nextSteps: [
+      "Ask the user the clarification question before guessing",
+      "Call bugmole_resolve_blocker with the user's answer",
+    ],
+  };
+}

package/src/runtime/journey-evidence.test.ts

@@ -0,0 +1,161 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { LocalObjectStore } from "../storage/object-store.js";
+import { captureJourneyScreenshots } from "./journey-evidence.js";
+import { emptyJourneyGraph } from "./journey-graph.js";
+
+test("captures an active related reference for every journey node", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-journey-evidence-"));
+  const reference = path.join(root, "reference.png");
+  await fs.writeFile(reference, Buffer.from("png-bytes"));
+  const graph = emptyJourneyGraph("demo");
+  graph.nodes = [
+    { id: "start", title: "Open app", kind: "screen" },
+    { id: "end", title: "Finish", kind: "screen" },
+  ];
+  graph.journeys = [{
+    id: "demo-flow",
+    name: "Demo flow",
+    actor: "user",
+    nodeIds: ["start", "end"],
+    edgeIds: [],
+    revision: 1,
+    status: "draft",
+  }];
+
+  const updated = await captureJourneyScreenshots(graph, {
+    projectId: "demo",
+    journeyId: "demo-flow",
+    store: new LocalObjectStore(root),
+    sources: [{ kind: "reference", location: reference, related: true }],
+  });
+
+  assert.equal(updated.nodes.every((node) => node.screenshot?.status === "captured"), true);
+  assert.equal(await new LocalObjectStore(root).has("projects/demo/journeys/evidence/demo-flow/start.png"), true);
+});
+
+test("falls back to runtime capture when the reference is archived", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-journey-evidence-"));
+  const graph = emptyJourneyGraph("demo");
+  graph.nodes = [{ id: "start", title: "Open app", kind: "screen" }];
+  graph.journeys = [{
+    id: "demo-flow",
+    name: "Demo flow",
+    actor: "user",
+    nodeIds: ["start"],
+    edgeIds: [],
+    revision: 1,
+    status: "draft",
+  }];
+
+  const updated = await captureJourneyScreenshots(graph, {
+    projectId: "demo",
+    journeyId: "demo-flow",
+    store: new LocalObjectStore(root),
+    sources: [{ kind: "reference", location: "/archived/mockup.png", active: false }],
+    captureRuntime: async () => new Uint8Array([1, 2, 3]),
+  });
+
+  assert.equal(updated.nodes[0].screenshot?.source, "runtime");
+  assert.equal(updated.nodes[0].screenshot?.status, "captured");
+});
+
+test("uses a browser provider for an active mockup URL", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-journey-evidence-"));
+  const graph = emptyJourneyGraph("demo");
+  graph.nodes = [{ id: "start", title: "Open app", kind: "screen" }];
+  graph.journeys = [{
+    id: "demo-flow",
+    name: "Demo flow",
+    actor: "user",
+    nodeIds: ["start"],
+    edgeIds: [],
+    revision: 1,
+    status: "draft",
+  }];
+  let capturedUrl = "";
+
+  const updated = await captureJourneyScreenshots(graph, {
+    projectId: "demo",
+    journeyId: "demo-flow",
+    store: new LocalObjectStore(root),
+    sources: [{ kind: "reference", location: "https://mockup.example.com/flow", related: true }],
+    captureReferenceUrl: async (url) => {
+      capturedUrl = url;
+      return new Uint8Array([4, 5, 6]);
+    },
+  });
+
+  assert.equal(capturedUrl, "https://mockup.example.com/flow");
+  assert.equal(updated.nodes[0].screenshot?.source, "reference");
+  assert.equal(updated.nodes[0].screenshot?.status, "captured");
+});
+
+test("bounds concurrent captures instead of launching every node's browser at once", async () => {
+  const originalLimit = process.env.BUGMOLE_CAPTURE_CONCURRENCY;
+  process.env.BUGMOLE_CAPTURE_CONCURRENCY = "2";
+  try {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-journey-evidence-"));
+    const graph = emptyJourneyGraph("demo");
+    graph.nodes = Array.from({ length: 6 }, (_, index) => ({ id: `node-${index}`, title: `Screen ${index}`, kind: "screen" as const }));
+    graph.journeys = [{
+      id: "demo-flow",
+      name: "Demo flow",
+      actor: "user",
+      nodeIds: graph.nodes.map((node) => node.id),
+      edgeIds: [],
+      revision: 1,
+      status: "draft",
+    }];
+
+    let inFlight = 0;
+    let peakInFlight = 0;
+
+    await captureJourneyScreenshots(graph, {
+      projectId: "demo",
+      journeyId: "demo-flow",
+      store: new LocalObjectStore(root),
+      captureRuntime: async () => {
+        inFlight += 1;
+        peakInFlight = Math.max(peakInFlight, inFlight);
+        // Yield so overlapping calls actually get a chance to race, the way
+        // real concurrent headless-browser launches would.
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        inFlight -= 1;
+        return new Uint8Array([1]);
+      },
+    });
+
+    assert.equal(peakInFlight <= 2, true, `expected at most 2 concurrent captures, saw ${peakInFlight}`);
+  } finally {
+    if (originalLimit === undefined) delete process.env.BUGMOLE_CAPTURE_CONCURRENCY;
+    else process.env.BUGMOLE_CAPTURE_CONCURRENCY = originalLimit;
+  }
+});
+
+test("preserves nodes with explicit blocked screenshot evidence", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-journey-evidence-"));
+  const graph = emptyJourneyGraph("demo");
+  graph.nodes = [{ id: "start", title: "Open app", kind: "screen" }];
+  graph.journeys = [{
+    id: "demo-flow",
+    name: "Demo flow",
+    actor: "user",
+    nodeIds: ["start"],
+    edgeIds: [],
+    revision: 1,
+    status: "draft",
+  }];
+
+  const updated = await captureJourneyScreenshots(graph, {
+    projectId: "demo",
+    journeyId: "demo-flow",
+    store: new LocalObjectStore(root),
+  });
+
+  assert.equal(updated.nodes[0].screenshot?.status, "blocked");
+  assert.match(updated.nodes[0].screenshot?.reason ?? "", /No active related reference/);
+});