fix: add structured edge frp diagnosis

scripts/src/dev-edge-health-smoke-lib.mjs

@@ -103,6 +103,7 @@ async function createDevGateReport(edgeHealth) {
   const commitId = await gitCommitId();
   const status = edgeHealth.status === "pass" ? "pass" : edgeHealth.status === "not_run" ? "not_run" : "blocked";
   const blockerType = status === "blocked" ? blockerTypeFor(edgeHealth.classification) : null;
+  const blockerScope = edgeHealth.diagnosis?.likelyLayer ?? edgeHealth.classification;
 
   return {
     $schema: "https://hwlab.pikastech.local/schemas/dev-gate-report.schema.json",
@@ -170,7 +171,7 @@ async function createDevGateReport(edgeHealth) {
       ? [
           {
             type: blockerType,
-            scope: edgeHealth.classification,
+            scope: blockerScope,
             status: "open",
             summary: edgeHealth.blocker
           }
@@ -338,7 +339,7 @@ function classify(report) {
     return classifyReachableHealth(publicHealth.json);
   }
   if (port6667?.status === "error" && port6667.code === "ECONNREFUSED") {
-    return classifyRefusedPort(frpsControl, tunnelHealth);
+    return classifyRefusedPort(port6667, frpsControl, tunnelHealth);
   }
   if (port6667?.status === "timeout") {
     return blocker("dns_port_firewall_blocker", "public 6667 timed out before any HTTP response");
@@ -363,21 +364,80 @@ function classifyReachableHealth(json) {
   return { status: "pass", classification: "none", blocker: null };
 }
 
-function classifyRefusedPort(frpsControl, tunnelHealth) {
+function classifyRefusedPort(port6667, frpsControl, tunnelHealth) {
   if (frpsControl?.status === "error" && frpsControl.code === "ECONNREFUSED") {
-    return blocker("frp_blocker", "public 6667 and frps control 7000 both refuse TCP connections; frps is not reachable on the master edge");
+    const allPortsRefused = tunnelHealth?.status === "error" && tunnelHealth.code === "ECONNREFUSED";
+    const diagnosis = {
+      likelyLayer: "master-edge/frps",
+      confidence: "high",
+      likelyCause: allPortsRefused
+        ? "public 6667, frps control 7000, and tunnel health 7402 all refuse TCP connections; the master-edge frps listener or its ports are most likely down or closed"
+        : "public 6667 and frps control 7000 both refuse TCP connections; the master-edge frps listener or its ports are most likely down or closed",
+      evidence: [
+        summarizeTcpProbe(port6667),
+        summarizeTcpProbe(frpsControl),
+        summarizeTcpProbe(tunnelHealth)
+      ],
+      notProven: [
+        "k3s service readiness",
+        "frpc connectivity",
+        "edge proxy deployment"
+      ],
+      nextTask: "Restore or reopen frps on 74.48.78.17, then rerun the read-only edge smoke."
+    };
+    return blocker("frp_blocker", diagnosis.likelyCause, diagnosis);
   }
   if (tunnelHealth?.status === "error" && tunnelHealth.code === "ECONNREFUSED") {
-    return blocker("frp_blocker", "public 6667 refuses TCP and tunnel health 7402 is not reachable");
+    return blocker("frp_blocker", "public 6667 refuses TCP and tunnel health 7402 is not reachable", {
+      likelyLayer: "d601/frpc",
+      confidence: "medium",
+      likelyCause: "public 6667 and tunnel health 7402 both refuse TCP connections; the D601 frp client or its remote port is the likely break",
+      evidence: [
+        summarizeTcpProbe(port6667),
+        summarizeTcpProbe(tunnelHealth)
+      ],
+      notProven: [
+        "master-edge frps reachability",
+        "k3s service readiness"
+      ],
+      nextTask: "Restore the D601 tunnel client or its remote port, then rerun the read-only edge smoke."
+    });
   }
-  return blocker("edge_proxy_blocker", "public 6667 refuses TCP connections");
+  return blocker("edge_proxy_blocker", "public 6667 refuses TCP connections", {
+    likelyLayer: "master-edge/edge-proxy",
+    confidence: "medium",
+    likelyCause: "public 6667 refuses TCP while frps control 7000 stays reachable, so the public edge proxy or its listener is the likely break",
+    evidence: [
+      summarizeTcpProbe(port6667),
+      summarizeTcpProbe(frpsControl)
+    ],
+    notProven: [
+      "k3s service readiness"
+    ],
+    nextTask: "Repair the edge proxy or its public listener, then rerun the read-only edge smoke."
+  });
 }
 
-function blocker(classification, message) {
+function blocker(classification, message, diagnosis = null) {
   return {
     status: "blocker",
     classification,
-    blocker: message
+    blocker: message,
+    ...(diagnosis ? { diagnosis } : {})
+  };
+}
+
+function summarizeTcpProbe(probe) {
+  if (!probe) {
+    return null;
+  }
+
+  return {
+    host: probe.host,
+    port: probe.port,
+    status: probe.status,
+    code: probe.code ?? null,
+    message: probe.message ?? null
   };
 }
 

scripts/src/dev-gate-preflight.mjs

@@ -431,9 +431,9 @@ function validateEdgeHealthReport(reporter, edgeReport) {
   reporter.check("dev-edge-health-report", "edge", "blocked", `Committed DEV edge health report is ${edgeReport.status} with classification ${classification}.`, evidence);
   reporter.block({
     type: "network_blocker",
-    scope: "dev-edge-health",
+    scope: edgeHealth?.diagnosis?.likelyLayer ?? "dev-edge-health",
     summary,
-    nextTask: "Repair the master frps/public DEV edge route and rerun the read-only DEV edge health smoke before real deployment."
+    nextTask: edgeHealth?.diagnosis?.nextTask ?? "Repair the master frps/public DEV edge route and rerun the read-only DEV edge health smoke before real deployment."
   });
 }