pqcheck 0.15.1 → 0.15.3

package/README.md

@@ -1,27 +1,54 @@
 # pqcheck
 
-> **Decryption Blast Radius scanner** — find out how much of your data unlocks when quantum decryption arrives.
+> **A deploy gate for AI coding agents.** Tell Claude Code / Cursor / Copilot whether the site you just deployed is safe to announce — or whether your AI coworker should pause and ask you first.
 
 [![npm version](https://img.shields.io/npm/v/pqcheck.svg?style=flat-square&color=06b6d4)](https://www.npmjs.com/package/pqcheck)
 [![npm downloads](https://img.shields.io/npm/dm/pqcheck.svg?style=flat-square&color=06b6d4)](https://www.npmjs.com/package/pqcheck)
 [![license](https://img.shields.io/npm/l/pqcheck.svg?style=flat-square&color=06b6d4)](./LICENSE)
 
 ```bash
-npx pqcheck stripe.com
+npx pqcheck deploy-check yourdomain.com --ai
+```
+
 ```
+◆ Cipherwake · yourdomain.com ⚠ REVIEW · DBR 4.1 C · HIGH
+
+Top finding:
+  [HIGH] ECDHE-only — quantum-vulnerable key exchange
+
+CIPHERWAKE_AI_GUARD_RESULT
+ship_decision=review
+top_issue=tls.ecdhe_only_quantum_vulnerable
+END_CIPHERWAKE_AI_GUARD_RESULT
+```
+
+The last block — `CIPHERWAKE_AI_GUARD_RESULT` — is what your AI coding agent parses. It contains a single field, `ship_decision=pass|review|block`, that tells the agent whether to:
+
+- **pass** — go ahead and announce the deploy is shipped
+- **review** — stop and ask you what to do (your HTTPS posture drifted vs. last scan)
+- **block** — refuse to announce until you investigate (something critical changed)
+
+Zero install. Works in any terminal with Node 18+. Free, no signup, no API key required for first deploys.
+
+## What pqcheck actually checks
+
+Each `pqcheck <domain>` scans your site's public HTTPS surface and produces:
 
-Zero install. Works in any terminal with Node 18+. Free, no signup, no API key.
+- a **DBR score** (Decryption Blast Radius, 0–10) — how much of today's traffic would be readable to an attacker who's storing it now and waiting for quantum computers to break today's encryption (the "harvest-now, decrypt-later" risk, typically 5–10 years out per NIST timelines)
+- a **letter grade** (A–F)
+- a **findings list** ranked by severity — TLS cipher suites, certificate quality, security headers (CSP / HSTS / etc.), third-party scripts loaded by the page, key reuse across subdomains, and more
 
-The same scanner that powers [cipherwake.io](https://cipherwake.io), the browser extension, and the GitHub Action.
+You get the same scanner that powers [cipherwake.io](https://cipherwake.io), the browser extension, and the GitHub Action.
 
 ---
 
-## What it does
+## Commands at a glance
 
 | Command | What it gives you |
 |---|---|
-| `npx pqcheck <domain>` | One-shot DBR scan + grade. The original surface. |
-| `npx pqcheck trust-diff <domain>` | Compare today's public trust posture vs a baseline (last-week, last-month, or a saved CI baseline). For CI gates + release checklists. |
+| `npx pqcheck <domain>` | The basic scan. Returns DBR score (0–10), letter grade (A–F), and a list of findings ranked by severity. The fastest way to ask "is my site's HTTPS posture healthy today?" |
+| `npx pqcheck deploy-check <domain> --ai` | The flagship command. Wraps the scan with `ship_decision=pass\|review\|block` for your AI coding agent to gate the deploy announcement. Works anonymously on first use; subsequent runs compare against the previous scan. |
+| `npx pqcheck trust-diff <domain>` | Compare today's HTTPS surface against a saved baseline (last week / last month / a saved CI baseline). For CI gates and release checklists. |
 | `npx pqcheck preview-diff --preview <URL> --production <URL>` | Compare a Vercel/Netlify preview deployment URL to production. Surfaces new third-party scripts, header regressions, and DBR score drops *inside the PR*, before merge. |
 | `npx pqcheck vendors export/check/sync <domain>` | Vendor lockfile (`cipherwake.vendors.json`) + CI gate that exits non-zero when a new third-party origin appears. Like `package-lock.json` for vendor scripts. |
 | `npx pqcheck onboard <domain>` | One command: scan → scaffold the GitHub Action → capture a vendor lockfile → set a baseline → commit + push. Zero copy-paste from docs. |
@@ -45,7 +72,7 @@ npx pqcheck cipherwake.io --ai
 Output:
 
 ```
-◆ cipherwake · scan · ⚠ REVIEW · cipherwake.io · DBR 4.1 C · HIGH · ship_decision=review
+◆ Cipherwake · cipherwake.io ⚠ REVIEW · DBR 4.1 C · HIGH
 
 Top finding:
   [HIGH] ECDHE-only — quantum-vulnerable key exchange

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.3";
 
 // 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:
@@ -263,13 +263,34 @@ async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi,
     if (!quiet && format === "text") process.stderr.write("\r\x1b[K");
     if (!resp.ok) {
       const errBody = await safeJSON(resp);
-      console.error(color("red", `error scanning ${domain}: ${resp.status} ${errBody?.error || resp.statusText}`));
-      if (errBody?.detail) console.error(color("dim", errBody.detail));
-      // Surface the 429 upsell hint if present — tells users how to ask for
-      // higher limits via the feedback form. Same demand signal we capture
-      // on the homepage.
-      if (resp.status === 429 && errBody?.need_more?.feedback_url) {
-        console.error(color("dim", `${errBody.need_more.message} → ${errBody.need_more.feedback_url}`));
+      // Friendly per-status messages so customers see actionable guidance
+      // instead of "error scanning X: 429 rate_limit_exceeded" raw HTTP
+      // verbiage. Batch users scripting many scans in a row hit this hardest
+      // — surface what they should do (wait + retry, or upgrade) rather than
+      // leaving them to guess.
+      if (resp.status === 429) {
+        const retryAfter = resp.headers.get("retry-after");
+        const waitMsg = retryAfter ? `Wait ${retryAfter}s then retry.` : "Wait ~60s then retry.";
+        console.error(color("yellow", `⚠ Rate limit hit on ${domain} — too many scans from this IP in the current window.`));
+        console.error(color("dim", `  ${waitMsg} For higher limits, get an account: ${API_BASE}/account`));
+        if (errBody?.need_more?.feedback_url) {
+          console.error(color("dim", `  Need much higher throughput? ${errBody.need_more.feedback_url}`));
+        }
+      } else if (resp.status >= 500) {
+        console.error(color("red", `error scanning ${domain}: Cipherwake's scanner hit a transient issue (HTTP ${resp.status}).`));
+        console.error(color("dim", `  Retry in ~1 minute. If it keeps happening, report at ${API_BASE}/feedback (include the domain + timestamp).`));
+        if (errBody?.detail) console.error(color("dim", `  Detail: ${errBody.detail}`));
+      } else if (resp.status === 400) {
+        // Most 400s on /api/scan are "invalid domain" — typically the
+        // customer typed a URL with a path or used localhost. The
+        // server already returns a clear message; just present it
+        // without raw HTTP noise.
+        console.error(color("red", `error scanning ${domain}: ${errBody?.error || resp.statusText}`));
+        if (errBody?.detail) console.error(color("dim", `  ${errBody.detail}`));
+        console.error(color("dim", `  Cipherwake only scans public domains. URLs with paths, IPs, and \`localhost\` aren't supported.`));
+      } else {
+        console.error(color("red", `error scanning ${domain}: ${resp.status} ${errBody?.error || resp.statusText}`));
+        if (errBody?.detail) console.error(color("dim", errBody.detail));
       }
       return 1;
     }
@@ -296,26 +317,93 @@ 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.
+  // Treat as "cannot evaluate" — and route through the UNREACHABLE label —
+  // when either:
+  //   • reachable === false  (no TCP/TLS handshake at all)
+  //   • scanAvailable === false  (TCP/TLS up, but scan couldn't produce a
+  //     coherent fingerprint — e.g. medium.com churning vendor scripts
+  //     faster than our dual-fingerprint check)
+  //
+  // _meta.degraded alone is too broad (fires on cache fallback + mid-scan
+  // state changes on otherwise-scoreable domains like stripe.com), so we
+  // narrow to the structured failure signals the server emits.
+  const unreachable = report?.reachable === false || report?.scanAvailable === 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) {
+      const isUnstable = report?.reason === "scan_unstable";
+      topIssue = isUnstable
+        ? "[REACHABILITY] Scan unstable — site changing faster than we can scan it"
+        : "[REACHABILITY] Domain unreachable — TLS probe failed or DNS unresolved";
+      whyMatters = report?.userMessage || report?._meta?.degradedReason || (isUnstable
+        ? "The scanner reached the site but couldn't produce a coherent fingerprint — rolling deploy, rapid A/B variation, or fast vendor-script rotation. Retry usually succeeds once the site settles."
+        : "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 = isUnstable
+        ? [
+            `Wait ~1 minute then retry: npx pqcheck deploy-check ${domain} --ai`,
+            `View full report (last successful scan): ${API_BASE}/r/${domain}`,
+          ]
+        : [
+            `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 +413,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 +432,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 +664,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 +2428,64 @@ 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.
+  // Treat as "cannot evaluate" — and route through the UNREACHABLE label —
+  // when either:
+  //   • reachable === false  (no TCP/TLS handshake at all)
+  //   • scanAvailable === false  (TCP/TLS up, but scan couldn't produce a
+  //     coherent fingerprint — e.g. medium.com churning vendor scripts
+  //     faster than our dual-fingerprint check)
+  //
+  // _meta.degraded alone is too broad (fires on cache fallback + mid-scan
+  // state changes on otherwise-scoreable domains like stripe.com), so we
+  // narrow to the structured failure signals the server emits.
+  const unreachable = report?.reachable === false || report?.scanAvailable === false;
+  if (unreachable) {
+    shipDecision = "block";
+  }
+
+  let topIssue, whyMatters, nextActions;
+  if (unreachable) {
+    const isUnstable = report?.reason === "scan_unstable";
+    topIssue = isUnstable
+      ? "[REACHABILITY] Scan unstable — site changing faster than we can scan it"
+      : "[REACHABILITY] Domain unreachable — TLS probe failed or DNS unresolved";
+    whyMatters = report?.userMessage || report?._meta?.degradedReason || (isUnstable
+      ? "The scanner reached the site but couldn't produce a coherent fingerprint — rolling deploy, rapid A/B variation, or fast vendor-script rotation. Retry usually succeeds once the site settles."
+      : "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 = isUnstable
+      ? [
+          `Wait ~1 minute then retry: npx pqcheck deploy-check ${domain} --ai`,
+          `View full report (last successful scan): ${API_BASE}/r/${domain}`,
+        ]
+      : [
+          `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 +2497,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.3",
   "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",