pqcheck 0.15.1 → 0.15.2

package/bin/cipherwake-statusline.js

@@ -64,44 +64,72 @@ let state;
 try {
   state = JSON.parse(readFileSync(STATE_FILE, "utf8"));
 } catch {
-  // No scan yet — render an onboarding hint so first-time users learn the
-  // command. Use the dim color so it doesn't dominate the status line.
+  // No scan yet — anchor on the brand so first-time users see Cipherwake
+  // every turn (and learn what the status line refers to), then nudge to
+  // the command. Dim so it doesn't dominate.
   process.stdout.write(
-    c(C.dim, "◆ cipherwake · no scan yet · ") + c(C.cyan, "npx pqcheck <domain> --ai")
+    c(C.dim, "◆ Cipherwake · no scan yet — ") + c(C.cyan, "npx pqcheck <domain> --ai")
   );
   process.exit(0);
 }
 
-const { domain, score, grade, ship_decision, written_at, max_severity, kind } = state;
+const { domain, score, grade, ship_decision, written_at, max_severity, unreachable } = state;
 const age = ageHours(written_at);
 
 if (age > STALE_THRESHOLD_HOURS) {
-  const stalePart = c(C.dim, `◆ ${domain || "cipherwake"} · stale (${formatAge(written_at)})`);
-  const hintPart = c(C.cyan, `npx pqcheck ${domain || "<domain>"} --ai`);
-  process.stdout.write(`${stalePart} · ${hintPart}`);
+  // Stale = the cached check is too old to anchor a deploy on. Use ◌
+  // (dotted circle) to signal "needs refresh" without alarming. Stays
+  // muted so an old check doesn't pretend to be active state.
+  process.stdout.write(
+    c(C.dim, `◆ Cipherwake · ${domain || "—"} ◌ STALE · last checked ${formatAge(written_at)} — `) +
+      c(C.cyan, `npx pqcheck ${domain || "<domain>"} --ai`)
+  );
   process.exit(0);
 }
 
-const symbolByDecision = { pass: "✓", review: "⚠", block: "✗" };
+// Brand-anchored layout — "Cipherwake" is always the first word after the
+// diamond, so the customer (and their AI agent) can identify the status
+// line's source at a glance. Trailing segments depend on what we have:
+//
+//   pass  (no DBR):  ◆ Cipherwake · pinnedai.dev ✓ PASS · just now
+//   pass  (w/ DBR):  ◆ Cipherwake · pinnedai.dev ✓ PASS · DBR 8.7 A · just now
+//   review:          ◆ Cipherwake · pinnedai.dev ⚠ REVIEW · DBR 4.1 C · HIGH · 1h ago
+//   block:           ◆ Cipherwake · pinnedai.dev ⛔ BLOCK · HIGH · now
+//   unreachable:     ◆ Cipherwake · pinnedai.dev ⊘ UNREACHABLE · now
+//
+// "Unreachable" is a distinct visual + label even though ship_decision=block,
+// because the failure mode is different (we couldn't measure the trust
+// surface at all, vs. we found a critical finding). The AI agent still
+// halts on block-routing — same protocol behavior, clearer customer
+// messaging.
+const isUnreachable = !!unreachable;
+const symbolByDecision = { pass: "✓", review: "⚠", block: "⛔" };
 const colorByDecision = { pass: C.green, review: C.yellow, block: C.red };
-const symbol = symbolByDecision[ship_decision] || "·";
-const cdec = colorByDecision[ship_decision] || C.dim;
+const symbol = isUnreachable ? "⊘" : (symbolByDecision[ship_decision] || "·");
+const cdec = isUnreachable ? C.red : (colorByDecision[ship_decision] || C.dim);
+const labelWord = isUnreachable
+  ? "UNREACHABLE"
+  : (ship_decision || "—").toUpperCase();
 
-const dbrStr = typeof score === "number" ? `DBR ${score.toFixed(1)}` : "";
-const gradeStr = grade ? grade : "";
-const sevStr = max_severity && max_severity !== "none"
-  ? `· ${String(max_severity).toUpperCase()}`
+// When unreachable, suppress DBR/severity trailing segments — they aren't
+// meaningful (no score was computed) and would clutter the line. Just the
+// glyph + UNREACHABLE label + age is enough.
+const dbrSegment = (!isUnreachable && typeof score === "number")
+  ? ` · DBR ${score.toFixed(1)}${grade ? " " + grade : ""}`
+  : "";
+const sevSegment = (!isUnreachable && max_severity && max_severity !== "none")
+  ? ` · ${String(max_severity).toUpperCase()}`
   : "";
-const kindStr = kind && kind !== "scan" ? `· ${kind}` : "";
 
-// Final layout (color-coded; ANSI stripped under --no-color / NO_COLOR=1):
-//   ◆ <domain> ✓|⚠|✗ ship_decision · DBR X.X grade · SEVERITY · kind · age
 process.stdout.write(
   c(cdec, "◆") +
     " " +
-    c(C.bold, domain || "cipherwake") +
+    c(C.bold, "Cipherwake") +
+    " " +
+    c(C.dim, "·") +
     " " +
-    c(cdec, `${symbol} ${(ship_decision || "—").toUpperCase()}`) +
+    c(C.bold, domain || "—") +
     " " +
-    c(C.dim, `· ${dbrStr}${gradeStr ? " " + gradeStr : ""} ${sevStr} ${kindStr} · ${formatAge(written_at)}`)
+    c(cdec, `${symbol} ${labelWord}`) +
+    c(C.dim, `${dbrSegment}${sevSegment} · ${formatAge(written_at)}`)
 );

package/bin/pqcheck.js

@@ -24,7 +24,7 @@
 })();
 
 const API_BASE = process.env.PQCHECK_API_BASE || "https://cipherwake.io";
-const VERSION = "0.15.1";
+const VERSION = "0.15.2";
 
 // API-key support — paid tiers (Starter $29 / Growth $79 / Scale $199) get
 // per-account monthly quotas instead of the per-IP rate limit. Set via:
@@ -296,26 +296,78 @@ async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi,
     console.error(`pqcheck: ⚠ ${domain} — using cached score (live probe failed: ${report._meta.degradedReason || "unknown"}; last verified ${report._meta.lastUpdated || "?"})`);
   }
 
+  // Compute ship-decision once — needed both for AI-mode footer AND for the
+  // per-user/per-repo state files that statusline/chat-hook/prompt-hook read.
+  // State files must update on every successful scan, regardless of --ai, so
+  // downstream agents see the same scan the human just ran.
+  const findings = Array.isArray(report.findings) ? report.findings : [];
+  const maxSev = highestSeverity(findings);
+  let shipDecision = computeShipDecision({ maxSeverity: maxSev });
+  const topFinding = [...findings].sort((a, b) => severityRank(b.severity) - severityRank(a.severity))[0];
+
+  // Unreachable / degraded → force "block". A scan that couldn't actually
+  // reach the domain (no DNS, TLS handshake failed, deploy hadn't propagated
+  // yet, typo in the domain) is categorically different from "trust drift
+  // detected" — we couldn't evaluate the trust surface AT ALL. "review"
+  // would be too soft (the AI agent might shrug and ship); "block" properly
+  // halts announcement per the AI Coder Protocol until the human confirms
+  // the unreachability was expected (e.g., they know DNS is still
+  // propagating) or fixes the deploy. This matches the protocol's "STOP,
+  // wait for explicit override" routing.
+  // Only treat literal "reachable === false" as unreachable. _meta.degraded
+  // is too broad — it also fires for fingerprint disagreement / cache
+  // fallback / mid-scan state changes on reachable domains (e.g. stripe.com
+  // mid-deploy), and those scans returned a real score we shouldn't hide
+  // behind an UNREACHABLE label.
+  const unreachable = report?.reachable === false;
+  if (unreachable) {
+    shipDecision = "block";
+  }
+
+  // Capture reachability AFTER ship_decision override so state files reflect
+  // the truth: ship_decision=block + unreachable=true means "we couldn't
+  // reach it, treat as block." Downstream surfaces (statusline / VS Code
+  // extension / AI banner) display the "UNREACHABLE" label when
+  // unreachable=true instead of the generic "BLOCK" — more informative,
+  // same protocol routing.
+  await writeLastScanFile({
+    domain,
+    kind: "scan",
+    score: typeof report.score === "number" ? report.score : null,
+    grade: report.grade || null,
+    max_severity: maxSev,
+    ship_decision: shipDecision,
+    unreachable: unreachable || false,
+    top_issue: topFinding?.id || topFinding?.title || null,
+  });
+
   // AI Coder Mode — three-layer output for Claude Code / Cursor / Aider.
   // Overrides --format when --ai is set; emits the structured block at the
   // bottom so downstream agents can parse ship_decision deterministically.
   if (aiMode) {
-    const findings = Array.isArray(report.findings) ? report.findings : [];
-    const maxSev = highestSeverity(findings);
-    const shipDecision = computeShipDecision({ maxSeverity: maxSev });
-    const topFinding = [...findings].sort((a, b) => severityRank(b.severity) - severityRank(a.severity))[0];
-
-    const topIssue = topFinding
-      ? `[${String(topFinding.severity || "").toUpperCase()}] ${topFinding.title || topFinding.detail || "finding"}`
-      : "No findings at or above LOW severity.";
-    const whyMatters = topFinding?.detail || "DBR scoring measures harvest-now-decrypt-later risk. Findings reflect public-surface signals only.";
-    const nextActions = shipDecision === "pass"
-      ? [`Domain looks healthy. View full report: ${API_BASE}/r/${domain}`]
-      : [
-          `Review finding above and decide if it was intentional.`,
-          `View full report: ${API_BASE}/r/${domain}`,
-          `Re-scan with --fresh after fix: npx pqcheck ${domain} --fresh --ai`,
-        ];
+    let topIssue, whyMatters, nextActions;
+    if (unreachable) {
+      topIssue = "[REACHABILITY] Domain unreachable — TLS probe failed or DNS unresolved";
+      whyMatters = report?._meta?.degradedReason || "The scanner couldn't reach the domain on port 443. Either DNS hasn't propagated, the deploy hasn't completed, or this domain isn't deployed at the address we expected.";
+      nextActions = [
+        `Check the domain is correct (typo?): ${domain}`,
+        `Verify DNS: dig +short ${domain}`,
+        `Verify deploy completed and TLS is live on https://${domain}`,
+        `Re-run after fix: npx pqcheck deploy-check ${domain} --ai`,
+      ];
+    } else {
+      topIssue = topFinding
+        ? `[${String(topFinding.severity || "").toUpperCase()}] ${topFinding.title || topFinding.detail || "finding"}`
+        : "No findings at or above LOW severity.";
+      whyMatters = topFinding?.detail || "DBR scoring measures harvest-now-decrypt-later risk. Findings reflect public-surface signals only.";
+      nextActions = shipDecision === "pass"
+        ? [`Domain looks healthy. View full report: ${API_BASE}/r/${domain}`]
+        : [
+            `Review finding above and decide if it was intentional.`,
+            `View full report: ${API_BASE}/r/${domain}`,
+            `Re-scan with --fresh after fix: npx pqcheck ${domain} --fresh --ai`,
+          ];
+    }
 
     console.log("");
     console.log(formatAiBanner({
@@ -325,6 +377,7 @@ async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi,
       grade: report.grade,
       maxSeverity: maxSev,
       shipDecision,
+      unreachable,
     }));
     console.log(formatAiBody({ topIssue, whyMatters, nextActions }));
     console.log(formatAiFooterBlock({
@@ -343,16 +396,6 @@ async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi,
     }));
     console.log("");
 
-    await writeLastScanFile({
-      domain,
-      kind: "scan",
-      score: typeof report.score === "number" ? report.score : null,
-      grade: report.grade || null,
-      max_severity: maxSev,
-      ship_decision: shipDecision,
-      top_issue: topFinding?.id || topFinding?.title || null,
-    });
-
     // Threshold check still applies under --ai (script-pipeable). Otherwise
     // exit code reflects ship_decision so the caller can route on it.
     if (threshold !== null && typeof report.score === "number" && report.score >= threshold) {
@@ -585,14 +628,30 @@ function aiStatusEmoji(shipDecision) {
   return "⚠";
 }
 
-function formatAiBanner({ domain, kind, dbr, grade, maxSeverity, shipDecision }) {
-  const emoji = aiStatusEmoji(shipDecision);
-  const statusWord = ({ pass: "PASS", review: "REVIEW", block: "BLOCK" })[shipDecision] || "REVIEW";
-  const c = aiBannerColor(shipDecision);
-  const dbrStr = typeof dbr === "number" ? dbr.toFixed(1) : "—";
-  const gradeStr = grade ? ` ${grade}` : "";
-  const sevStr = maxSeverity && maxSeverity !== "none" ? ` · ${String(maxSeverity).toUpperCase()}` : "";
-  return color(c, `◆ cipherwake · ${kind} · ${emoji} ${statusWord} · ${domain} · DBR ${dbrStr}${gradeStr}${sevStr} · ship_decision=${shipDecision}`);
+function formatAiBanner({ domain, kind, dbr, grade, maxSeverity, shipDecision, unreachable }) {
+  // When the scanner couldn't reach the domain we render "UNREACHABLE"
+  // (with a distinct ⊘ glyph) instead of the generic "BLOCK" — semantically
+  // clearer for the customer: their site isn't deployed / isn't responding,
+  // not that we found a critical security finding.
+  //
+  // Suppress DBR + severity trailing segments when unreachable: even if the
+  // API returned a stale cached score on a degraded scan, surfacing it next
+  // to "UNREACHABLE" reads as contradictory ("how can it score X if you
+  // couldn't reach it?"). The age + banner already convey the situation.
+  const isUnreachable = !!unreachable;
+  const emoji = isUnreachable ? "⊘" : aiStatusEmoji(shipDecision);
+  const statusWord = isUnreachable
+    ? "UNREACHABLE"
+    : (({ pass: "PASS", review: "REVIEW", block: "BLOCK" })[shipDecision] || "REVIEW");
+  const c = aiBannerColor(isUnreachable ? "block" : shipDecision);
+  const dbrSegment = (!isUnreachable && typeof dbr === "number")
+    ? ` · DBR ${dbr.toFixed(1)}${grade ? " " + grade : ""}`
+    : "";
+  const sevSegment = (!isUnreachable && maxSeverity && maxSeverity !== "none")
+    ? ` · ${String(maxSeverity).toUpperCase()}`
+    : "";
+  const kindSegment = (kind && kind !== "scan") ? ` · ${kind}` : "";
+  return color(c, `◆ Cipherwake · ${domain} ${emoji} ${statusWord}${dbrSegment}${sevSegment}${kindSegment}`);
 }
 
 function formatAiBody({ topIssue, whyMatters, nextActions }) {
@@ -2333,19 +2392,49 @@ async function runScanBasedDeployCheck(domain, args) {
   const report = await resp.json();
   const findings = Array.isArray(report.findings) ? report.findings : [];
   const maxSev = highestSeverity(findings);
-  const shipDecision = computeShipDecision({ maxSeverity: maxSev });
+  let shipDecision = computeShipDecision({ maxSeverity: maxSev });
   const topFinding = [...findings].sort((a, b) => severityRank(b.severity) - severityRank(a.severity))[0];
-  const topIssue = topFinding
-    ? `[${String(topFinding.severity || "").toUpperCase()}] ${topFinding.title || topFinding.detail || "finding"}`
-    : "No findings at or above LOW severity.";
-  const whyMatters = topFinding?.detail || "DBR scoring measures harvest-now-decrypt-later risk on the public TLS surface.";
-  const nextActions = shipDecision === "pass"
-    ? [`Domain looks healthy on first scan. View full report: ${API_BASE}/r/${domain}`]
-    : [
-        `Review finding above and decide if it was intentional.`,
-        `View full report: ${API_BASE}/r/${domain}`,
-        `Subsequent deploy-checks will diff against this scan as baseline.`,
-      ];
+
+  // Unreachable / degraded → force "block" with an UNREACHABLE display label
+  // downstream. See main scan path for the rationale: an undeployed-or-broken
+  // domain can't be evaluated, so the AI agent must halt announcement and ask
+  // the human (was this expected? did the deploy fail?). The `unreachable`
+  // field travels in the state file + structured block so statusline /
+  // VS Code ext / chat-hook can render "UNREACHABLE" instead of generic
+  // "BLOCK" — semantically clearer for this specific failure mode.
+  // Only treat literal "reachable === false" as unreachable. _meta.degraded
+  // is too broad — it also fires for fingerprint disagreement / cache
+  // fallback / mid-scan state changes on reachable domains (e.g. stripe.com
+  // mid-deploy), and those scans returned a real score we shouldn't hide
+  // behind an UNREACHABLE label.
+  const unreachable = report?.reachable === false;
+  if (unreachable) {
+    shipDecision = "block";
+  }
+
+  let topIssue, whyMatters, nextActions;
+  if (unreachable) {
+    topIssue = "[REACHABILITY] Domain unreachable — TLS probe failed or DNS unresolved";
+    whyMatters = report?._meta?.degradedReason || "The scanner couldn't reach the domain on port 443. Either DNS hasn't propagated, the deploy hasn't completed, or this domain isn't deployed at the address we expected.";
+    nextActions = [
+      `Check the domain is correct (typo?): ${domain}`,
+      `Verify DNS: dig +short ${domain}`,
+      `Verify deploy completed and TLS is live on https://${domain}`,
+      `Re-run after fix: npx pqcheck deploy-check ${domain} --ai`,
+    ];
+  } else {
+    topIssue = topFinding
+      ? `[${String(topFinding.severity || "").toUpperCase()}] ${topFinding.title || topFinding.detail || "finding"}`
+      : "No findings at or above LOW severity.";
+    whyMatters = topFinding?.detail || "DBR scoring measures harvest-now-decrypt-later risk on the public TLS surface.";
+    nextActions = shipDecision === "pass"
+      ? [`Domain looks healthy on first scan. View full report: ${API_BASE}/r/${domain}`]
+      : [
+          `Review finding above and decide if it was intentional.`,
+          `View full report: ${API_BASE}/r/${domain}`,
+          `Subsequent deploy-checks will diff against this scan as baseline.`,
+        ];
+  }
 
   console.log("");
   console.log(color("dim", `  ℹ first deploy-check for ${domain} — using current scan state (no baseline yet to diff against)`));
@@ -2357,23 +2446,46 @@ async function runScanBasedDeployCheck(domain, args) {
     grade: report.grade,
     maxSeverity: maxSev,
     shipDecision,
+    unreachable,
   }));
   console.log(formatAiBody({ topIssue, whyMatters, nextActions }));
   console.log(formatAiFooterBlock({
-    status: shipDecision === "pass" ? "pass" : "review",
+    status: shipDecision,
     domain,
     kind: "scan",
     dbr: report.score,
     grade: report.grade,
     max_severity: maxSev,
     ship_decision: shipDecision,
-    top_issue: topFinding ? `findings.${topFinding.id || "unknown"}` : "none",
+    unreachable: unreachable ? "true" : "false",
+    top_issue: unreachable
+      ? "findings.reachability.unreachable"
+      : (topFinding ? `findings.${topFinding.id || "unknown"}` : "none"),
     findings_high: findings.filter((f) => severityRank(f.severity) >= severityRank("high")).length,
     findings_critical: findings.filter((f) => severityRank(f.severity) >= severityRank("critical")).length,
     scanned_at: new Date().toISOString(),
     advisory_only: true,
-    note: "first-deploy: no baseline yet, scored on current state",
+    note: unreachable
+      ? "domain unreachable on port 443; deploy may have failed or DNS not propagated"
+      : "first-deploy: no baseline yet, scored on current state",
   }));
+
+  await writeLastScanFile({
+    domain,
+    kind: "scan",
+    score: typeof report.score === "number" ? report.score : null,
+    grade: report.grade || null,
+    max_severity: maxSev,
+    ship_decision: shipDecision,
+    unreachable: unreachable || false,
+    top_issue: unreachable
+      ? "findings.reachability.unreachable"
+      : (topFinding?.id || topFinding?.title || null),
+    note: unreachable
+      ? "domain unreachable on port 443; deploy may have failed or DNS not propagated"
+      : "first-deploy: no baseline yet, scored on current state",
+  });
+
   // Exit code: 0 on pass, non-zero on review/block (matches deploy-check contract)
   process.exit(shipDecision === "pass" ? 0 : 1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pqcheck",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Deploy gate for AI-coded web apps. `pqcheck deploy-check --ai` returns ship_decision=pass|review|block for Claude Code / Cursor / Copilot / Aider to gate deploys before they ship. Anonymous, no signup, free for first use.",
   "keywords": [
     "ai-coder",