@zigrivers/surface-mcp 0.1.1 → 0.2.0

package/dist/index.js

@@ -1,24 +1,286 @@
 // src/index.ts
+import path from "path";
 import { pathToFileURL } from "url";
 import {
   DEFAULT_COMPOSITION_STAGE_IDS,
   DEFAULT_SURFACE_CONFIG,
+  browserQaFlowRunsForGate,
+  browserQaFlowSeverityFromWithFlows,
+  browserQaGateTargetCli,
   createBoundedAlternatives,
   createTrackedFinding,
   createSurfaceComposition,
-  createSurfaceError,
+  createSurfaceError as createSurfaceError2,
   diffTrackedFindings,
-  err,
+  err as err2,
+  evaluateGateWithQaFlows,
   instantiateLensExecutionPlan,
-  isOk,
-  ok,
+  isOk as isOk2,
+  ok as ok2,
   scoreFinding,
   selectLensExecutionPlan,
   synthesizeBacklog,
-  toMcpError,
+  toMcpError as toMcpError2,
   transitionTrackedFinding
 } from "@zigrivers/surface-core";
+import { z as z2 } from "zod";
+
+// src/browser-qa-tools.ts
+import {
+  createSurfaceError,
+  err,
+  isOk,
+  ok,
+  toMcpError
+} from "@zigrivers/surface-core";
 import { z } from "zod";
+var BROWSER_QA_MCP_SERVER_TOOL_NAMES = [
+  "surface_qa",
+  "surface_explore",
+  "surface_flow_run",
+  "surface_flow_list",
+  "surface_flow_promote",
+  "surface_evidence",
+  "surface_replay",
+  "surface_report_qa",
+  "surface_artifact_read"
+];
+var TargetInputSchema = z.object({
+  kind: z.enum(["url", "localhost", "route", "screenshot", "component", "dom"]),
+  ref: z.string().min(1),
+  theme: z.enum(["light", "dark"]).optional(),
+  viewport: z.object({
+    height: z.number().int().positive(),
+    label: z.enum(["mobile", "tablet", "desktop"]),
+    width: z.number().int().positive()
+  }).strict().optional()
+}).strict();
+var SurfaceQaInputSchema = z.object({
+  actionPolicyRef: z.string().min(1).optional(),
+  allowedDomains: z.array(z.string().min(1)).optional(),
+  ci: z.boolean().optional(),
+  evidence: z.enum(["minimal", "failures", "full"]).optional(),
+  explore: z.boolean().optional(),
+  flows: z.array(z.string().min(1)).optional(),
+  maxActions: z.number().int().positive().optional(),
+  maxDepth: z.number().int().positive().optional(),
+  maxStates: z.number().int().positive().optional(),
+  network: z.enum(["summary", "har", "off"]).optional(),
+  scope: z.string().min(1).optional(),
+  sessionMode: z.enum(["isolated", "shared"]).optional(),
+  stateLockTimeoutMs: z.number().int().positive().optional(),
+  target: TargetInputSchema,
+  task: z.string().min(1).optional(),
+  video: z.enum(["off", "failures", "all"]).optional()
+}).strict();
+var SurfaceExploreInputSchema = z.object({
+  actionPolicyRef: z.string().min(1).optional(),
+  allowedDomains: z.array(z.string().min(1)).optional(),
+  evidence: z.enum(["minimal", "failures", "full"]).optional(),
+  maxActions: z.number().int().positive().optional(),
+  maxDepth: z.number().int().positive().optional(),
+  maxStates: z.number().int().positive().optional(),
+  network: z.enum(["summary", "har", "off"]).optional(),
+  scope: z.string().min(1).optional(),
+  sessionMode: z.enum(["isolated", "shared"]).optional(),
+  stateLockTimeoutMs: z.number().int().positive().optional(),
+  target: TargetInputSchema,
+  task: z.string().min(1).optional(),
+  video: z.enum(["off", "failures", "all"]).optional()
+}).strict();
+var SurfaceFlowRunInputSchema = z.object({
+  actionPolicyRef: z.string().min(1).optional(),
+  baseUrl: z.string().min(1).optional(),
+  ci: z.boolean().optional(),
+  flowPath: z.string().min(1),
+  localhost: z.boolean().optional(),
+  target: z.string().min(1).optional(),
+  url: z.string().min(1).optional()
+}).strict().refine(
+  (input) => [input.target, input.url, input.localhost === true ? "localhost" : void 0].filter(
+    (value) => value !== void 0
+  ).length <= 1,
+  "Pass at most one of target, url, or localhost."
+);
+var SurfaceFlowListInputSchema = z.object({ candidates: z.boolean().optional() }).strict();
+var SurfaceFlowPromoteInputSchema = z.object({
+  candidateFlowId: z.string().min(1),
+  outPath: z.string().min(1)
+}).strict();
+var SurfaceEvidenceInputSchema = z.object({ refId: z.string().min(1) }).strict();
+var SurfaceReplayInputSchema = z.object({
+  promoteOnRepro: z.boolean().optional(),
+  refId: z.string().min(1)
+}).strict();
+var SurfaceReportQaInputSchema = z.object({
+  format: z.enum(["md", "json", "manifest"]).optional(),
+  runId: z.string().min(1)
+}).strict();
+var SurfaceArtifactReadInputSchema = z.object({
+  artifactId: z.string().min(1),
+  maxBytes: z.number().int().positive().max(65536).optional(),
+  refId: z.string().min(1)
+}).strict();
+var BROWSER_QA_MCP_SERVER_INPUT_SCHEMAS = {
+  surface_qa: SurfaceQaInputSchema,
+  surface_explore: SurfaceExploreInputSchema,
+  surface_flow_run: SurfaceFlowRunInputSchema,
+  surface_flow_list: SurfaceFlowListInputSchema,
+  surface_flow_promote: SurfaceFlowPromoteInputSchema,
+  surface_evidence: SurfaceEvidenceInputSchema,
+  surface_replay: SurfaceReplayInputSchema,
+  surface_report_qa: SurfaceReportQaInputSchema,
+  surface_artifact_read: SurfaceArtifactReadInputSchema
+};
+var BROWSER_QA_MCP_TOOL_INPUT_SCHEMAS = BROWSER_QA_MCP_SERVER_INPUT_SCHEMAS;
+var BROWSER_QA_MCP_SERVER_TOOL_METADATA = {
+  surface_qa: {
+    description: "Run agent-led browser QA over a target.",
+    title: "Run Browser QA"
+  },
+  surface_explore: {
+    description: "Run bounded browser QA exploration.",
+    title: "Explore Browser QA"
+  },
+  surface_flow_run: {
+    description: "Run a reviewed browser QA flow.",
+    title: "Run Browser QA Flow"
+  },
+  surface_flow_list: {
+    description: "List browser QA flow runs or candidate flows.",
+    title: "List Browser QA Flows"
+  },
+  surface_flow_promote: {
+    description: "Promote a candidate browser QA flow.",
+    title: "Promote Browser QA Flow"
+  },
+  surface_evidence: {
+    description: "Read redacted browser QA evidence metadata.",
+    title: "Read Browser QA Evidence"
+  },
+  surface_replay: {
+    description: "Replay a browser QA candidate or finding.",
+    title: "Replay Browser QA Finding"
+  },
+  surface_report_qa: {
+    description: "Render a browser QA report.",
+    title: "Render Browser QA Report"
+  },
+  surface_artifact_read: {
+    description: "Read a bounded MCP-approved browser QA artifact by registered refs.",
+    title: "Read Browser QA Artifact"
+  }
+};
+var BROWSER_QA_MCP_SERVER_TOOL_NAME_SET = new Set(BROWSER_QA_MCP_SERVER_TOOL_NAMES);
+var REGISTERED_REF_ID_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_-]*$/u;
+function createBrowserQaMcpHandlers(composition) {
+  const browserQa = browserQaFromComposition(composition);
+  const orchestrator = browserQa?.orchestrator;
+  const flowService = browserQa?.flowService;
+  const evidenceStore = browserQa?.evidenceStore;
+  return {
+    artifactRead: (input) => evidenceStore?.readArtifactByRegisteredRef(input) ?? Promise.resolve(qaMcpUnavailable("Browser QA evidence artifact reads are unavailable.")),
+    evidence: (input) => orchestrator?.readEvidence(input) ?? Promise.resolve(qaMcpUnavailable("Browser QA evidence reads are unavailable.")),
+    explore: (input) => orchestrator?.runExplore({
+      ...input,
+      maxActions: input.maxActions ?? 25,
+      maxDepth: input.maxDepth ?? 2,
+      maxStates: input.maxStates ?? 10
+    }) ?? Promise.resolve(qaMcpUnavailable("Browser QA exploration is unavailable.")),
+    flowList: (input) => flowService?.listFlows(input) ?? Promise.resolve(qaMcpUnavailable("Browser QA flow listing is unavailable.")),
+    flowPromote: (input) => flowService?.promoteFlow(input) ?? Promise.resolve(qaMcpUnavailable("Browser QA flow promotion is unavailable.")),
+    flowRun: (input) => flowService?.runFlowFile({
+      ...input.actionPolicyRef === void 0 ? {} : { actionPolicyRef: input.actionPolicyRef },
+      ...input.ci === void 0 ? {} : { ci: input.ci },
+      flowPath: input.flowPath,
+      targetCli: targetCliForFlowRun(input)
+    }) ?? Promise.resolve(qaMcpUnavailable("Browser QA flow running is unavailable.")),
+    qa: (input) => orchestrator?.runQa(input) ?? Promise.resolve(qaMcpUnavailable("Browser QA orchestration is unavailable.")),
+    replay: (input) => orchestrator?.replay(input) ?? Promise.resolve(qaMcpUnavailable("Browser QA replay is unavailable.")),
+    reportQa: (input) => orchestrator?.reportQa(input) ?? Promise.resolve(qaMcpUnavailable("Browser QA reports are unavailable."))
+  };
+}
+function isBrowserQaMcpServerToolName(name) {
+  return BROWSER_QA_MCP_SERVER_TOOL_NAME_SET.has(name);
+}
+async function callBrowserQaMcpTool(input) {
+  const parsed = parseBrowserQaToolInput(input.name, input.input);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  switch (input.name) {
+    case "surface_qa":
+      return await input.handlers.qa(parsed.value);
+    case "surface_explore":
+      return await input.handlers.explore(parsed.value);
+    case "surface_flow_run":
+      return await input.handlers.flowRun(parsed.value);
+    case "surface_flow_list":
+      return await input.handlers.flowList(parsed.value);
+    case "surface_flow_promote":
+      return await input.handlers.flowPromote(parsed.value);
+    case "surface_evidence":
+      return await input.handlers.evidence(parsed.value);
+    case "surface_replay":
+      return await input.handlers.replay(parsed.value);
+    case "surface_report_qa":
+      return await input.handlers.reportQa(parsed.value);
+    case "surface_artifact_read":
+      return await callArtifactReadHandler(
+        input.handlers,
+        parsed.value
+      );
+  }
+}
+function parseBrowserQaToolInput(name, input) {
+  const parsed = BROWSER_QA_MCP_TOOL_INPUT_SCHEMAS[name].safeParse(input);
+  if (!parsed.success) {
+    return err(
+      createSurfaceError("config_invalid", "Browser QA MCP input did not match its schema.", {
+        cause: parsed.error,
+        details: { tool: name }
+      })
+    );
+  }
+  return ok(parsed.data);
+}
+async function callArtifactReadHandler(handlers, input) {
+  const refCheck = validateRegisteredRef(input.refId, "refId");
+  if (!refCheck.ok) {
+    return refCheck;
+  }
+  const artifactCheck = validateRegisteredRef(input.artifactId, "artifactId");
+  if (!artifactCheck.ok) {
+    return artifactCheck;
+  }
+  return await handlers.artifactRead({ ...input, maxBytes: input.maxBytes ?? 8192 });
+}
+function validateRegisteredRef(value, field) {
+  if (!REGISTERED_REF_ID_PATTERN.test(value) || value.includes("..")) {
+    return err(
+      createSurfaceError("config_invalid", "Browser QA artifact reads require registered ids.", {
+        details: { field }
+      })
+    );
+  }
+  return ok(true);
+}
+function browserQaFromComposition(composition) {
+  return composition.browserQa;
+}
+function targetCliForFlowRun(input) {
+  return {
+    ...input.baseUrl === void 0 ? {} : { baseUrl: input.baseUrl },
+    ...input.localhost === true ? { localhost: true } : {},
+    ...input.target === void 0 ? {} : { target: input.target },
+    ...input.url === void 0 ? {} : { url: input.url }
+  };
+}
+function qaMcpUnavailable(message) {
+  return err(createSurfaceError("qa_unavailable", message));
+}
+
+// src/index.ts
 var SURFACE_MCP_SERVER_NAME = "surface";
 var SURFACE_MCP_SERVER_VERSION = "1.0.0";
 var SURFACE_MCP_TOOL_SCHEMA_VERSION = "1.0.0";
@@ -36,62 +298,77 @@ var TOOL_ORDER = [
   "surface_trace",
   "surface_run",
   "surface_next",
-  "surface_status"
+  "surface_status",
+  ...BROWSER_QA_MCP_SERVER_TOOL_NAMES
 ];
-var TargetSchema = z.object({
-  kind: z.enum(["url", "localhost", "route", "screenshot", "component", "dom"]),
-  ref: z.string().min(1),
-  theme: z.enum(["light", "dark"]).optional(),
-  viewport: z.object({
-    height: z.number().int().positive(),
-    label: z.enum(["mobile", "tablet", "desktop"]),
-    width: z.number().int().positive()
+var TargetSchema = z2.object({
+  kind: z2.enum(["url", "localhost", "route", "screenshot", "component", "dom"]),
+  ref: z2.string().min(1),
+  theme: z2.enum(["light", "dark"]).optional(),
+  viewport: z2.object({
+    height: z2.number().int().positive(),
+    label: z2.enum(["mobile", "tablet", "desktop"]),
+    width: z2.number().int().positive()
   }).strict().optional()
 }).strict();
-var AuthStateRefSchema = z.string().min(1);
-var RunRefSchema = z.object({ runId: z.string().min(1) }).strict();
-var GatePolicyInputSchema = z.record(z.string(), z.unknown());
+var AuthStateRefSchema = z2.string().min(1);
+var RunRefSchema = z2.object({ runId: z2.string().min(1) }).strict();
+var GatePolicyInputSchema = z2.record(z2.string(), z2.unknown());
 var TOOL_INPUT_SCHEMAS = {
-  surface_capture: z.object({
+  surface_capture: z2.object({
     authState: AuthStateRefSchema.optional(),
     target: TargetSchema
   }).strict(),
-  surface_audit: z.object({
+  surface_audit: z2.object({
     authState: AuthStateRefSchema.optional(),
-    depth: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4), z.literal(5)]).optional(),
-    persona: z.string().min(1).optional(),
-    preset: z.string().min(1).optional(),
+    depth: z2.union([z2.literal(1), z2.literal(2), z2.literal(3), z2.literal(4), z2.literal(5)]).optional(),
+    persona: z2.string().min(1).optional(),
+    preset: z2.string().min(1).optional(),
     target: TargetSchema,
-    task: z.string().min(1).optional()
+    task: z2.string().min(1).optional()
   }).strict(),
-  surface_explain: z.object({ findingId: z.string().min(1) }).strict(),
-  surface_backlog: z.object({
-    exportTarget: z.string().min(1).optional(),
-    runId: z.string().min(1).optional()
+  surface_explain: z2.object({ findingId: z2.string().min(1) }).strict(),
+  surface_backlog: z2.object({
+    exportTarget: z2.string().min(1).optional(),
+    runId: z2.string().min(1).optional()
   }).strict(),
-  surface_gate: z.object({
+  surface_gate: z2.object({
+    actionPolicyRef: z2.string().min(1).optional(),
+    baseUrl: z2.string().min(1).optional(),
+    ci: z2.boolean().optional(),
+    localhost: z2.boolean().optional(),
     policy: GatePolicyInputSchema.optional(),
-    runId: z.string().min(1).optional()
+    runId: z2.string().min(1).optional(),
+    target: z2.string().min(1).optional(),
+    url: z2.string().min(1).optional(),
+    withFlows: z2.union([z2.boolean(), z2.string().min(1)]).optional()
+  }).strict().refine(
+    (input) => [input.target, input.url, input.localhost === true ? "localhost" : void 0].filter(
+      (value) => value !== void 0
+    ).length <= 1,
+    "Pass at most one of target, url, or localhost."
+  ),
+  surface_validate: z2.object({ runId: z2.string().min(1) }).strict(),
+  surface_baseline: z2.object({ reason: z2.string().min(1).optional() }).strict(),
+  surface_verdict: z2.object({
+    decision: z2.enum(["accept", "reject", "correct", "defer"]),
+    findingId: z2.string().min(1),
+    promote: z2.boolean().optional(),
+    rationale: z2.string().min(1)
   }).strict(),
-  surface_validate: z.object({ runId: z.string().min(1) }).strict(),
-  surface_baseline: z.object({ reason: z.string().min(1).optional() }).strict(),
-  surface_verdict: z.object({
-    decision: z.enum(["accept", "reject", "correct", "defer"]),
-    findingId: z.string().min(1),
-    rationale: z.string().min(1)
-  }).strict(),
-  surface_diff: z.object({ after: RunRefSchema, before: RunRefSchema }).strict(),
-  surface_alternatives: z.object({
+  surface_diff: z2.object({ after: RunRefSchema, before: RunRefSchema }).strict(),
+  surface_alternatives: z2.object({
     authState: AuthStateRefSchema.optional(),
     target: TargetSchema
   }).strict(),
-  surface_trace: z.object({ findingId: z.string().min(1) }).strict(),
-  surface_run: z.object({
-    step: z.string().min(1),
+  surface_trace: z2.object({ findingId: z2.string().min(1) }).strict(),
+  surface_run: z2.object({
+    step: z2.string().min(1),
     target: TargetSchema.optional()
   }).strict(),
-  surface_next: z.object({}).strict(),
-  surface_status: z.object({}).strict()
+  surface_next: z2.object({}).strict(),
+  surface_status: z2.object({}).strict(),
+  ...BROWSER_QA_MCP_SERVER_INPUT_SCHEMAS
 };
 var TOOL_METADATA = {
   surface_capture: {
@@ -149,7 +426,8 @@ var TOOL_METADATA = {
   surface_status: {
     title: "Read Status",
     description: "Read Surface project status."
-  }
+  },
+  ...BROWSER_QA_MCP_SERVER_TOOL_METADATA
 };
 var INTERNAL_TOOLS = TOOL_ORDER.map((name) => {
   const metadata = TOOL_METADATA[name];
@@ -158,7 +436,7 @@ var INTERNAL_TOOLS = TOOL_ORDER.map((name) => {
     name,
     ...metadata,
     inputZodSchema,
-    inputSchema: z.toJSONSchema(inputZodSchema),
+    inputSchema: z2.toJSONSchema(inputZodSchema),
     schemaVersion: SURFACE_MCP_TOOL_SCHEMA_VERSION
   };
 });
@@ -180,8 +458,9 @@ function createSurfaceMcpToolRegistry() {
 }
 function createSurfaceMcpServer(options = {}) {
   const registry = createSurfaceMcpToolRegistry();
+  const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
   const composition = options.composition ?? createSurfaceComposition(options);
-  const session = createSurfaceMcpSessionState();
+  const session = createSurfaceMcpSessionState(projectRoot);
   return {
     composition,
     callTool: async (name, input) => {
@@ -226,14 +505,15 @@ function assertMcpToolSchemaCompatibility(input) {
       );
     }
   }
-  return ok(true);
+  return ok2(true);
 }
-function createSurfaceMcpSessionState() {
+function createSurfaceMcpSessionState(projectRoot) {
   return {
     baselines: /* @__PURE__ */ new Map(),
     baselineOrder: [],
     runs: /* @__PURE__ */ new Map(),
     runOrder: [],
+    projectRoot,
     trackedByIdentity: /* @__PURE__ */ new Map(),
     verdicts: /* @__PURE__ */ new Map(),
     nextBaselineSequence: 1,
@@ -246,7 +526,7 @@ async function hydrateSurfaceMcpSession(composition, session) {
     return state;
   }
   resetSurfaceMcpSessionFromState(session, state.value);
-  return ok(void 0);
+  return ok2(void 0);
 }
 function resetSurfaceMcpSessionFromState(session, state) {
   session.baselines.clear();
@@ -310,14 +590,14 @@ async function persistSurfaceMcpSession(composition, session) {
   const updateState = stateSnapshotForMcpSession(session);
   if (composition.stateStore.updateState !== void 0) {
     const updated = await composition.stateStore.updateState(updateState);
-    return updated.ok ? ok(void 0) : updated;
+    return updated.ok ? ok2(void 0) : updated;
   }
   const current = await composition.stateStore.readState();
   if (!current.ok) {
     return current;
   }
   const written = await composition.stateStore.writeState(updateState(current.value));
-  return written.ok ? ok(void 0) : written;
+  return written.ok ? ok2(void 0) : written;
 }
 function stateSnapshotForMcpSession(session) {
   return (state) => {
@@ -372,6 +652,13 @@ function nextSequenceFromIds(ids, prefix) {
   return maxSequence + 1;
 }
 async function callSurfaceMcpTool(input) {
+  if (isBrowserQaMcpServerToolName(input.name)) {
+    return await callBrowserQaMcpTool({
+      handlers: createBrowserQaMcpHandlers(input.composition),
+      input: input.input,
+      name: input.name
+    });
+  }
   switch (input.name) {
     case "surface_capture":
       return await callSurfaceCapture(input.composition, input.input);
@@ -465,7 +752,7 @@ async function callSurfaceAudit(composition, session, rawInput) {
   if (!persisted.ok) {
     return persisted;
   }
-  return ok({
+  return ok2({
     backlog: record.backlog,
     capture: record.capture,
     findings: record.findings,
@@ -480,20 +767,20 @@ function callSurfaceExplain(session, rawInput) {
   }
   const finding = findStoredFinding(session, parsed.value.findingId);
   if (finding === void 0) {
-    return err(
-      createSurfaceError("finding_not_found", "No stored MCP finding matched the requested id.", {
+    return err2(
+      createSurfaceError2("finding_not_found", "No stored MCP finding matched the requested id.", {
         details: { findingId: parsed.value.findingId }
       })
     );
   }
   if (finding.evidence.length === 0) {
-    return err(
-      createSurfaceError("evidence_missing", "Stored MCP finding has no evidence to explain.", {
+    return err2(
+      createSurfaceError2("evidence_missing", "Stored MCP finding has no evidence to explain.", {
         details: { findingId: finding.id }
       })
     );
   }
-  return ok({
+  return ok2({
     evidence: finding.evidence,
     finding,
     rationale: finding.rationale
@@ -506,21 +793,21 @@ async function callSurfaceBacklog(composition, session, rawInput) {
   }
   const record = runRecordFor(session, parsed.value.runId);
   if (record === void 0) {
-    return err(
-      createSurfaceError("run_not_found", "No stored MCP run matched the requested backlog.", {
+    return err2(
+      createSurfaceError2("run_not_found", "No stored MCP run matched the requested backlog.", {
         details: { runId: parsed.value.runId ?? null }
       })
     );
   }
   if (parsed.value.exportTarget === void 0) {
-    return ok(record.backlog);
+    return ok2(record.backlog);
   }
   const exporter = composition.issueExporters.find(
     (candidate) => candidate.target === parsed.value.exportTarget
   );
   if (exporter === void 0) {
-    return err(
-      createSurfaceError(
+    return err2(
+      createSurfaceError2(
         "unknown_export_target",
         "No issue exporter matched the MCP backlog target.",
         {
@@ -545,13 +832,13 @@ async function callSurfaceBacklog(composition, session, rawInput) {
     return exported;
   }
   if (exported.value.status === "partial") {
-    return err(
-      createSurfaceError("export_partial", "MCP backlog export completed partially.", {
+    return err2(
+      createSurfaceError2("export_partial", "MCP backlog export completed partially.", {
         details: { exportId: exported.value.id, target: exported.value.target }
       })
     );
   }
-  return ok(exported.value);
+  return ok2(exported.value);
 }
 async function callSurfaceGate(composition, session, rawInput) {
   const parsed = parseToolInput("surface_gate", rawInput);
@@ -560,8 +847,8 @@ async function callSurfaceGate(composition, session, rawInput) {
   }
   const record = runRecordFor(session, parsed.value.runId);
   if (record === void 0) {
-    return err(
-      createSurfaceError("run_not_found", "No stored MCP run matched the requested gate.", {
+    return err2(
+      createSurfaceError2("run_not_found", "No stored MCP run matched the requested gate.", {
         details: { runId: parsed.value.runId ?? null }
       })
     );
@@ -573,7 +860,32 @@ async function callSurfaceGate(composition, session, rawInput) {
     return tracked === void 0 || !baselineIdentityKeys.has(tracked.identityKey);
   });
   const policy = parsed.value.policy === void 0 ? DEFAULT_SURFACE_CONFIG.reporting.gatePolicy : parsed.value.policy;
-  return await composition.gateEvaluator.evaluate(findings, policy);
+  if (parsed.value.withFlows === void 0) {
+    return await composition.gateEvaluator.evaluate(findings, policy);
+  }
+  const targetCli = browserQaGateTargetCli(parsed.value);
+  if (!targetCli.ok) {
+    return targetCli;
+  }
+  const flowRuns = await browserQaFlowRunsForGate(composition, {
+    ...parsed.value.actionPolicyRef === void 0 ? {} : { actionPolicyRef: parsed.value.actionPolicyRef },
+    ci: parsed.value.ci === true,
+    projectRoot: session.projectRoot,
+    ...targetCli.value === void 0 ? {} : { targetCli: targetCli.value },
+    withFlows: parsed.value.withFlows
+  });
+  if (!flowRuns.ok) {
+    return flowRuns;
+  }
+  const flowAwareGate = evaluateGateWithQaFlows({
+    findings,
+    policy: {
+      ...policy,
+      failOnFlowSeverityAtOrAbove: browserQaFlowSeverityFromWithFlows(parsed.value.withFlows)
+    },
+    qaFlowRuns: flowRuns.value
+  });
+  return flowAwareGate;
 }
 function callSurfaceValidate(session, rawInput) {
   const parsed = parseToolInput("surface_validate", rawInput);
@@ -582,13 +894,13 @@ function callSurfaceValidate(session, rawInput) {
   }
   const record = runRecordFor(session, parsed.value.runId);
   if (record === void 0) {
-    return err(
-      createSurfaceError("run_not_found", "No stored MCP run matched the requested validation.", {
+    return err2(
+      createSurfaceError2("run_not_found", "No stored MCP run matched the requested validation.", {
         details: { runId: parsed.value.runId }
       })
     );
   }
-  return ok({
+  return ok2({
     checks: record.trackedFindings.map((trackedFinding) => ({
       id: trackedFinding.identityKey,
       passed: trackedFinding.status !== "identity-broken",
@@ -604,8 +916,8 @@ async function callSurfaceBaseline(composition, session, rawInput) {
   }
   const record = runRecordFor(session, void 0);
   if (record === void 0 || record.trackedFindings.length === 0) {
-    return err(
-      createSurfaceError("no_findings_to_baseline", "No MCP findings are available to baseline.")
+    return err2(
+      createSurfaceError2("no_findings_to_baseline", "No MCP findings are available to baseline.")
     );
   }
   const baselineId = nextBaselineId(session);
@@ -622,7 +934,7 @@ async function callSurfaceBaseline(composition, session, rawInput) {
   if (!persisted.ok) {
     return persisted;
   }
-  return ok({
+  return ok2({
     baselineId,
     count: baseline.identityKeys.size,
     ...baseline.reason === void 0 ? {} : { reason: baseline.reason }
@@ -633,10 +945,33 @@ async function callSurfaceVerdict(composition, session, rawInput) {
   if (!parsed.ok) {
     return parsed;
   }
+  if (parsed.value.findingId.startsWith("qfc_")) {
+    if (parsed.value.promote !== true) {
+      return err2(
+        createSurfaceError2("finding_not_found", "Browser QA candidate verdicts require promote.", {
+          details: { findingId: parsed.value.findingId }
+        })
+      );
+    }
+    const promotion = await composition.browserQa.orchestrator.promoteCandidateByVerdict({
+      refId: parsed.value.findingId,
+      reason: parsed.value.rationale,
+      verdictId: `verdict_${Date.now().toString(36)}`
+    });
+    if (!promotion.ok) {
+      return promotion;
+    }
+    return ok2({
+      decision: parsed.value.decision,
+      findingId: parsed.value.findingId,
+      promotion: promotion.value,
+      rationale: parsed.value.rationale
+    });
+  }
   const finding = findStoredFinding(session, parsed.value.findingId);
   if (finding === void 0) {
-    return err(
-      createSurfaceError("finding_not_found", "No stored MCP finding matched the verdict.", {
+    return err2(
+      createSurfaceError2("finding_not_found", "No stored MCP finding matched the verdict.", {
         details: { findingId: parsed.value.findingId }
       })
     );
@@ -651,7 +986,7 @@ async function callSurfaceVerdict(composition, session, rawInput) {
   if (!persisted.ok) {
     return persisted;
   }
-  return ok(verdict);
+  return ok2(verdict);
 }
 function callSurfaceDiff(session, rawInput) {
   const parsed = parseToolInput("surface_diff", rawInput);
@@ -661,13 +996,13 @@ function callSurfaceDiff(session, rawInput) {
   const before = runRecordFor(session, parsed.value.before.runId);
   const after = runRecordFor(session, parsed.value.after.runId);
   if (before === void 0 || after === void 0) {
-    return err(
-      createSurfaceError("run_not_found", "Both MCP diff runs must exist.", {
+    return err2(
+      createSurfaceError2("run_not_found", "Both MCP diff runs must exist.", {
         details: { after: parsed.value.after.runId, before: parsed.value.before.runId }
       })
     );
   }
-  return ok(diffTrackedFindings(before.trackedFindings, after.trackedFindings));
+  return ok2(diffTrackedFindings(before.trackedFindings, after.trackedFindings));
 }
 async function callSurfaceAlternatives(composition, rawInput) {
   const parsed = parseToolInput("surface_alternatives", rawInput);
@@ -682,7 +1017,7 @@ async function callSurfaceAlternatives(composition, rawInput) {
   if (!capture.ok) {
     return capture;
   }
-  return ok({
+  return ok2({
     alternatives: createBoundedAlternatives(target)
   });
 }
@@ -693,13 +1028,13 @@ function callSurfaceTrace(session, rawInput) {
   }
   const trackedFinding = findStoredTrackedFinding(session, parsed.value.findingId);
   if (trackedFinding === void 0) {
-    return err(
-      createSurfaceError("finding_not_found", "No tracked MCP finding matched the requested id.", {
+    return err2(
+      createSurfaceError2("finding_not_found", "No tracked MCP finding matched the requested id.", {
         details: { findingId: parsed.value.findingId }
       })
     );
   }
-  return ok({ trackedFinding });
+  return ok2({ trackedFinding });
 }
 async function callSurfaceRun(composition, rawInput) {
   const parsed = parseToolInput("surface_run", rawInput);
@@ -707,8 +1042,8 @@ async function callSurfaceRun(composition, rawInput) {
     return parsed;
   }
   if (parsed.value.step !== "all" && !isExecutableStageId(parsed.value.step)) {
-    return err(
-      createSurfaceError("unknown_step", `Unknown MCP pipeline step "${parsed.value.step}".`, {
+    return err2(
+      createSurfaceError2("unknown_step", `Unknown MCP pipeline step "${parsed.value.step}".`, {
         details: { step: parsed.value.step }
       })
     );
@@ -719,14 +1054,14 @@ async function callSurfaceRun(composition, rawInput) {
     runId
   });
   if (!run.ok) {
-    return err(
-      createSurfaceError("step_failed", `MCP pipeline run ${runId} failed.`, {
+    return err2(
+      createSurfaceError2("step_failed", `MCP pipeline run ${runId} failed.`, {
         cause: run.error,
         details: { runId, stage: parsed.value.step }
       })
     );
   }
-  return ok({
+  return ok2({
     runId: run.value.runId,
     stage: parsed.value.step,
     status: "completed"
@@ -739,7 +1074,7 @@ async function callSurfaceNext(composition) {
   }
   const lastCompletedStage = state.value.pipeline?.lastCompletedStage;
   const eligible = lastCompletedStage === void 0 ? ["run discovery", "run all"] : eligibleStagesAfter(lastCompletedStage).map((stage) => `run ${stage}`);
-  return ok({ eligible });
+  return ok2({ eligible });
 }
 function callSurfaceStatus(session) {
   const runHistory = session.runOrder.map((runId) => session.runs.get(runId)).filter((record) => record !== void 0).map((record) => ({
@@ -750,7 +1085,7 @@ function callSurfaceStatus(session) {
   }));
   const completedRuns = runHistory.filter((entry) => entry.status === "completed").length;
   const failedRuns = runHistory.filter((entry) => entry.status === "failed").length;
-  return ok({
+  return ok2({
     currentStage: runHistory.at(-1)?.status === "completed" ? "completed" : "pending",
     progress: {
       completedRuns,
@@ -771,7 +1106,7 @@ async function groundingEvidenceFor(composition, capture) {
       evidence.push(...toolResult.evidence);
     }
   }
-  return ok(evidence);
+  return ok2(evidence);
 }
 async function findingsForPlan(composition, config, capture, evidence, plan) {
   const findings = [];
@@ -794,7 +1129,7 @@ async function findingsForPlan(composition, config, capture, evidence, plan) {
       findings.push(scored.value);
     }
   }
-  return ok(findings);
+  return ok2(findings);
 }
 function configForAuditInput(input) {
   return {
@@ -832,14 +1167,14 @@ function targetForCore(input) {
 function parseToolInput(name, input) {
   const parsed = TOOL_INPUT_SCHEMAS[name].safeParse(input);
   if (!parsed.success) {
-    return err(
-      createSurfaceError("config_invalid", "MCP tool input did not match the registered schema.", {
+    return err2(
+      createSurfaceError2("config_invalid", "MCP tool input did not match the registered schema.", {
         cause: parsed.error,
         details: { tool: name }
       })
     );
   }
-  return ok(parsed.data);
+  return ok2(parsed.data);
 }
 function nextRunId(session) {
   const runId = `run_mcp_${session.nextRunSequence.toString().padStart(4, "0")}`;
@@ -957,7 +1292,7 @@ async function runSurfaceMcpStdioServer(options = {}) {
   await server.connect(new StdioServerTransport());
 }
 function mcpToolCallResult(result) {
-  if (isOk(result)) {
+  if (isOk2(result)) {
     return {
       content: [{ text: JSON.stringify(result.value, null, 2), type: "text" }],
       structuredContent: result.value
@@ -966,7 +1301,7 @@ function mcpToolCallResult(result) {
   return {
     content: [{ text: result.error.message, type: "text" }],
     isError: true,
-    structuredContent: toMcpError(result.error)
+    structuredContent: toMcpError2(result.error)
   };
 }
 function publicToolDefinition(tool) {
@@ -997,8 +1332,8 @@ function majorVersion(version) {
   return Number.isInteger(major) ? major : void 0;
 }
 function mcpSchemaIncompatible(message, input, details = {}) {
-  return err(
-    createSurfaceError("mcp_schema_incompatible", message, {
+  return err2(
+    createSurfaceError2("mcp_schema_incompatible", message, {
       details: {
         current: {
           name: input.current.name,