pqcheck 0.16.4 → 0.16.10

package/README.md

@@ -177,7 +177,16 @@ Sample output:
   Tier: free · policy: report
 ```
 
-Flags: `--preview <URL>` · `--production <URL>` · `--compare-transport` · `--fail-on <severity>` (default `high`; `none` for report-only) · `--format pretty|json`. CSP weakening detection diffs `script-src` / `default-src` / `object-src` / `frame-ancestors` / `base-uri` / `style-src` for newly-permissive tokens (`*`, `'unsafe-inline'`, `'unsafe-eval'`, `data:`, `blob:`).
+Flags: `--preview <URL>` · `--production <URL>` · `--compare-transport` · `--fail-on <severity>` (default `high`; `none` for report-only) · `--format pretty|json` · `--protected-path <PATH>` (repeatable) · `--first-party-host <HOSTNAME>` (repeatable). CSP weakening detection diffs `script-src` / `default-src` / `object-src` / `frame-ancestors` / `base-uri` / `style-src` for newly-permissive tokens (`*`, `'unsafe-inline'`, `'unsafe-eval'`, `data:`, `blob:`).
+
+**First-party hosts.** Subdomains of the scanned hostname are auto-promoted to first-party (PSL-backed: scanning `acme.com` makes `api.acme.com` first-party, but `acme.co.uk` does NOT auto-promote `evil.co.uk`). If your owned hosts span different registrable domains (`acme.com` + `acmecdn.net`), add them via `--first-party-host` or persist in `.cipherwake/config.json`:
+
+```json
+{
+  "firstPartyHosts": ["acmecdn.net", "static.acme.io"],
+  "protectedPaths": ["/api/admin/export", "/internal/billing"]
+}
+```
 
 **Diffing a local dev build against prod?** Cipherwake runs the comparison server-side, so `--preview http://localhost:3000` is rejected (we'd be reaching for *our* loopback, not yours). Expose your dev build via a public tunnel:
 

package/bin/cipherwake-statusline.js

@@ -18,13 +18,45 @@
 // Code calls it on every turn. Reads a single file, formats one line, exits.
 // =============================================================================
 
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 
-const STATE_FILE = join(homedir(), ".config", "cipherwake", "last-scan.json");
+const GLOBAL_STATE_FILE = join(homedir(), ".config", "cipherwake", "last-scan.json");
 const STALE_THRESHOLD_HOURS = 24;
 
+// v0.16.6 — project-aware state lookup. Walk up from CWD looking for a
+// repo-local `.cipherwake/last-scan.json`. This way each project shows
+// its own last scan, and switching projects doesn't bleed the previous
+// project's state into the new one. Falls back to the global file when
+// no project-local state exists (or when running outside a project).
+//
+// The walk stops at the first ancestor containing EITHER a `.git/` dir
+// or a `package.json` — that's our project-root heuristic. We do not
+// require both because non-Node projects (Python, Go) still have `.git/`
+// but no package.json.
+// pqcheck writes repo-local state to `.cipherwake/last-status.json` (writer
+// uses that filename per writeLastScanFile in pqcheck.js — kept compatible).
+function findProjectStateFile(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 20; i++) {
+    const candidate = join(dir, ".cipherwake", "last-status.json");
+    if (existsSync(candidate)) return candidate;
+    // Stop at the project root even if no .cipherwake/ — don't bleed across
+    // project boundaries by continuing up.
+    const isProjectRoot = existsSync(join(dir, ".git")) || existsSync(join(dir, "package.json"));
+    if (isProjectRoot) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+const cwd = process.env.PWD || process.cwd();
+const projectStateFile = findProjectStateFile(cwd);
+const STATE_FILE = projectStateFile || GLOBAL_STATE_FILE;
+
 const C = {
   reset: "\x1b[0m",
   bold: "\x1b[1m",
@@ -91,85 +123,32 @@ if (age > STALE_THRESHOLD_HOURS) {
   process.exit(0);
 }
 
-// v0.16.4 — preview-diff 4-line state.
-// User direction: when the last scan was `preview-diff` (two URLs compared),
-// render the high-yield block in the statusline. Other scan kinds keep the
-// 1-line compact format below — the bigger block would be too noisy when
-// it's just a routine domain scan with no diff context.
-if (kind === "preview-diff" && !unreachable) {
-  // Line 1: brand header (hostname only).
-  const head = c(C.bold, "◆ Cipherwake") + c(C.dim, " — ") + c(C.bold, domain || "—");
-  // Line 3: decision pulse, diff-flavored copy.
-  let pulse;
-  if (ship_decision === "pass") {
-    pulse = c(C.green, "✓ PASS") + c(C.dim, " · no risky deploy-surface drift detected");
-  } else if (ship_decision === "review") {
-    pulse = c(C.yellow, "⚠ REVIEW") + c(C.dim, ` · ${delta_count || 0} public-surface change${delta_count === 1 ? "" : "s"}`);
-  } else if (ship_decision === "block") {
-    pulse = c(C.red, "⛔ BLOCK") + c(C.dim, ` · ${delta_count || 0} critical change${delta_count === 1 ? "" : "s"}`);
-  } else {
-    pulse = c(C.dim, "· no decision");
-  }
-  // Line 4: trust posture (DBR + percentile copy + stability).
-  function formatPercentile(percentile, sector) {
-    if (typeof percentile !== "number") return null;
-    const s = sector || "industry";
-    if (percentile <= 10) return `top 10% in ${s}`;
-    if (percentile <= 25) return `top 25% in ${s}`;
-    if (percentile <= 50) return `above median in ${s}`;
-    if (percentile <= 75) return `below median in ${s}`;
-    if (percentile <= 90) return `bottom 25% in ${s}`;
-    return `bottom 10% in ${s}`;
-  }
-  function formatStability(iso) {
-    if (!iso) return null;
-    const days = Math.floor((Date.now() - new Date(iso).getTime()) / 86400000);
-    if (days <= 0) return "drifted today";
-    if (days < 7) return `drifted ${days}d ago`;
-    return `stable ${days}d`;
-  }
-  const trustParts = [];
-  if (typeof score === "number") {
-    trustParts.push(`DBR ${score.toFixed(1)}${grade ? " " + grade : ""}`);
-  }
-  const pct = formatPercentile(sector_ranking?.percentile, sector_ranking?.sectorLabel || sector_ranking?.sectorName || sector_ranking?.sector);
-  if (pct) trustParts.push(pct);
-  const stab = formatStability(last_changed);
-  if (stab) trustParts.push(stab);
-  const trustLine = trustParts.length > 0
-    ? c(C.green, "✓ ") + c(C.bold, "Trust posture: ") + trustParts.join(c(C.dim, " · "))
-    : null;
-  // Line 5: verified signals (or finding line when there IS drift).
-  let verifiedLine = null;
-  if (Array.isArray(verified_signal_categories) && verified_signal_categories.length > 0) {
-    const head = diff_no_change === true
-      ? "Security-relevant surface unchanged"
-      : `Verified ${verified_signal_categories.length} signal${verified_signal_categories.length === 1 ? "" : "s"}`;
-    verifiedLine = c(C.green, "✓ ") + c(C.bold, head) + c(C.dim, " · " + verified_signal_categories.join(", "));
-  }
-  // Compose
-  const lines = [head, "", pulse];
-  if (trustLine) lines.push(trustLine);
-  if (verifiedLine) lines.push(verifiedLine);
-  process.stdout.write(lines.join("\n"));
-  process.exit(0);
+// v0.16.6 — Single-line canonical format for ALL scan kinds. Prior versions
+// rendered a 4-line "high-yield block" for preview-diff state, but it's
+// overkill: the persistent statusline is read at-a-glance, not as a report.
+// One line that answers 4 questions:
+//   1. Is Cipherwake on?           → "◆ Cipherwake" anchor
+//   2. Which domain is it watching? → cleaned hostname
+//   3. Is the latest state good?    → ✓ PASS / ⚠ REVIEW / ⛔ BLOCK
+//   4. How fresh is the signal?     → "12m ago"
+//
+// Example: ◆ Cipherwake · quantasyte.com ✓ PASS · DBR 4.7 C · stable 14d · 12m ago
+
+// Vercel preview URLs aren't useful in the statusline — extract the project
+// name when the domain field is one. Otherwise return the domain unchanged.
+function cleanDomain(d) {
+  if (!d) return "—";
+  // Strip protocol if any leaked through.
+  let s = d.replace(/^https?:\/\//, "").replace(/\/$/, "");
+  // Vercel preview hostnames: <project>-<hash>-<org>.vercel.app
+  // Reduce to just <project> so the customer sees "back-in-play" not
+  // "back-in-play-30aoyitmn-michaels-projects-0b2351fa.vercel.app".
+  const vercel = s.match(/^([a-z0-9][a-z0-9-]*?)(?:-[a-z0-9]{6,})+-[a-z0-9-]+\.vercel\.app$/i);
+  if (vercel) return vercel[1] + " (preview)";
+  return s;
 }
+const displayDomain = cleanDomain(domain);
 
-// 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 };
@@ -180,21 +159,20 @@ const labelWord = isUnreachable
   : (ship_decision || "—").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.
+// meaningful (no score was computed) and would clutter the line.
 const dbrSegment = (!isUnreachable && typeof score === "number")
   ? ` · DBR ${score.toFixed(1)}${grade ? " " + grade : ""}`
   : "";
-const sevSegment = (!isUnreachable && max_severity && max_severity !== "none")
-  ? ` · ${String(max_severity).toUpperCase()}`
-  : "";
+// Severity is redundant with the PASS/REVIEW/BLOCK glyph (v0.16.6 dropped it
+// from the default render). Keep variable for future use but omit from line.
+const sevSegment = "";
 
-// v0.16.2 — drift narrative suffix. "stable 14d" / "drifted 2d ago" / "now".
-// Sourced from state.lastChanged (smartCache populates) so the customer
-// sees time-series anchor at a glance, not just a single-point snapshot.
+// Drift narrative suffix. Sourced from lastChanged (preview-diff state uses
+// last_changed; scan state uses state.lastChanged). "stable 14d" / "drifted Xd".
+const stabilitySource = last_changed || state.lastChanged;
 let stabilitySegment = "";
-if (!isUnreachable && state.lastChanged) {
-  const dms = Date.now() - new Date(state.lastChanged).getTime();
+if (!isUnreachable && stabilitySource) {
+  const dms = Date.now() - new Date(stabilitySource).getTime();
   const days = Math.floor(dms / 86400000);
   if (days <= 0) stabilitySegment = " · drifted today";
   else if (days < 7) stabilitySegment = ` · drifted ${days}d ago`;
@@ -208,8 +186,8 @@ process.stdout.write(
     " " +
     c(C.dim, "·") +
     " " +
-    c(C.bold, domain || "—") +
+    c(C.bold, displayDomain) +
     " " +
     c(cdec, `${symbol} ${labelWord}`) +
-    c(C.dim, `${dbrSegment}${sevSegment} · ${formatAge(written_at)}`)
+    c(C.dim, `${dbrSegment}${stabilitySegment} · ${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.16.4";
+const VERSION = "0.16.10";
 
 // 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:
@@ -117,6 +117,11 @@ async function main() {
     // changes (new third-party scripts, header regressions, score drops).
     return runPreviewDiffCommand(args.slice(1));
   }
+  if (args[0] === "guards") {
+    // CLI v0.16.9 (2026-05-23, R80, EXPERIMENTAL): Site Guards beta.
+    // Subcommands manage `.cipherwake/guards.json` and run guards against a URL.
+    return runGuardsCommand(args.slice(1));
+  }
   if (args[0] === "history") {
     return runHistoryCommand(args.slice(1));
   }
@@ -950,8 +955,13 @@ function formatHighYieldVerbose(report) {
 function formatPreviewDiffPerSignal(prev, prod, options = {}) {
   if (!prev || !prod) return null;
   const verbose = options.verbose === true;
+  // v0.16.5 — caller may pass the application_surface.scripts diff so the
+  // Scripts row can name the specific hosts that were added/removed
+  // (preview-diff was rendering "Scripts | 2 → 3" with no indication of
+  // WHICH vendor changed; the answer was buried in summary_lines above).
+  const scriptDeltas = Array.isArray(options.scriptDeltas) ? options.scriptDeltas : [];
   const rows = [];
-  const push = (name, l, r) => rows.push({ name, prev: l, prod: r, same: l === r });
+  const push = (name, l, r, extra) => rows.push({ name, prev: l, prod: r, same: l === r, extra: extra || null });
 
   if (typeof prev?.score === "number" || typeof prod?.score === "number") {
     const dbrL = typeof prev?.score === "number" ? `${prev.score.toFixed(1)}${prev.grade ? " " + prev.grade : ""}` : "—";
@@ -962,7 +972,18 @@ function formatPreviewDiffPerSignal(prev, prod, options = {}) {
   const prevScripts = prev?.publicDeps?.thirdPartyCount;
   const prodScripts = prod?.publicDeps?.thirdPartyCount;
   if (prevScripts !== undefined || prodScripts !== undefined) {
-    push("Scripts", String(prevScripts ?? "—"), String(prodScripts ?? "—"));
+    // Sub-lines naming the specific hosts that changed (added/removed),
+    // when application_surface.scripts is available. A substitution
+    // (a.com → c.com, count unchanged) still surfaces because the diff
+    // is computed by host-set, not by count.
+    const scriptSubLines = scriptDeltas.length > 0
+      ? scriptDeltas.map((s) => {
+          const sigil = s.kind === "added" ? "+" : s.kind === "removed" ? "-" : "~";
+          const tone = s.kind === "added" ? "yellow" : s.kind === "removed" ? "red" : "dim";
+          return color(tone, `${sigil} ${s.host}`);
+        })
+      : null;
+    push("Scripts", String(prevScripts ?? "—"), String(prodScripts ?? "—"), scriptSubLines);
   }
 
   const hdrSummary = (h) => {
@@ -1043,7 +1064,18 @@ function formatPreviewDiffPerSignal(prev, prod, options = {}) {
     const sameCount = rows.filter((r) => r.same).length;
     const allMatch = sameCount === rows.length;
     const symbol = allMatch ? color("green", "✓ ") : color("yellow", "~ ");
-    return symbol + color("bold", `${sameCount}/${rows.length} signals match`) + color("dim", " (preview ↔ production)");
+    const head = symbol + color("bold", `${sameCount}/${rows.length} signals match`) + color("dim", " (preview ↔ production)");
+    // v0.16.5 — if the Scripts row changed AND we have the host-level
+    // diff, append a sub-line naming each added/removed host even in
+    // compact mode. Keeps the customer from having to scroll up to
+    // summary_lines to find out WHICH vendor changed.
+    const scriptsRow = rows.find((r) => r.name === "Scripts");
+    if (scriptsRow && scriptsRow.extra && scriptsRow.extra.length > 0) {
+      const shown = scriptsRow.extra.slice(0, 5);
+      const more = scriptsRow.extra.length > 5 ? color("dim", `  +${scriptsRow.extra.length - 5} more`) : "";
+      return [head, ...shown.map((l) => "  " + l)].join("\n") + (more ? "\n" + more : "");
+    }
+    return head;
   }
 
   // Verbose: per-row table
@@ -1062,6 +1094,13 @@ function formatPreviewDiffPerSignal(prev, prod, options = {}) {
       arrow + "  " +
       color(valueColor, r.prod)
     );
+    // v0.16.5 — sub-lines under Scripts row naming added/removed hosts.
+    // Indent past the name+value columns so the per-host info reads as
+    // a nested detail of the parent row, not a peer signal.
+    if (r.extra && r.extra.length > 0) {
+      const indent = "  " + " ".repeat(nameWidth) + "  " + " ".repeat(prevWidth) + "     ";
+      for (const sub of r.extra) lines.push(indent + sub);
+    }
   }
   return lines.join("\n");
 }
@@ -1454,6 +1493,7 @@ ${color("bold", "Commands:")}
   npx pqcheck deploy-check <domain>             Pre-deploy trust gate (Trust Diff vs last scan; deploy-friendly framing) — see also: AI Coder Protocol at https://cipherwake.io/methodology/ai-coder-protocol
   npx pqcheck guard --domain <D> -- <cmd>       NEW: wrap any deploy command. Runs deploy-check first; conditionally runs <cmd> based on ship_decision. The strongest single artifact for AI-coder workflows.
   npx pqcheck protocol install                  NEW: install the AI Coder Protocol into your CLAUDE.md / .cursorrules (Rule 17 consent flow)
+  npx pqcheck guards <init|list|run>            EXPERIMENTAL (BETA): manage Site Guards (.cipherwake/guards.json) — runtime policies for source-maps / mixed-content / approved-hosts / protected-paths / cookie-flags / link-integrity. See: https://cipherwake.io/methodology/site-guards
   npx pqcheck release-checklist [domain]        Print a pre-release trust checklist (markdown, offline)
   npx pqcheck vendors export <domain>           Write cipherwake.vendors.json from observed third-party scripts
   npx pqcheck vendors check <domain>            Compare current scan to lockfile; exit 4 on new origins (Free CI gate)
@@ -3199,12 +3239,238 @@ async function runTrustDiffCommand(args) {
  * been removed; server applyRepoQuota handles all 3 auth paths, including
  * anonymous per-IP rate limit for frictionless first use.
  */
+// v0.16.6 R76 — collect custom protected paths from flags + config file.
+// Returns a sanitized array (max 20 entries, each ≤200 chars, starts with "/").
+// Server applies the same sanitizer, so anything that gets past this still
+// gets filtered server-side — defense in depth.
+async function loadCustomProtectedPaths(args) {
+  const out = [];
+  // Source 1: --protected-path flag, repeatable
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--protected-path" && i + 1 < args.length) {
+      out.push(args[i + 1]);
+    }
+  }
+  // Source 2: .cipherwake/config.json `protectedPaths`
+  try {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const cfgPath = path.join(process.cwd(), ".cipherwake", "config.json");
+    const raw = await fs.readFile(cfgPath, "utf8");
+    const cfg = JSON.parse(raw);
+    if (Array.isArray(cfg.protectedPaths)) {
+      for (const p of cfg.protectedPaths) {
+        if (typeof p === "string") out.push(p);
+      }
+    }
+  } catch {
+    // No config file or invalid JSON — that's fine, fall back to flag-only.
+  }
+  // Sanitize + dedupe + cap
+  const seen = new Set();
+  const sanitized = [];
+  for (const p of out) {
+    const trimmed = String(p).trim();
+    if (trimmed.length === 0 || trimmed.length > 200) continue;
+    if (!trimmed.startsWith("/")) continue;
+    if (seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    sanitized.push(trimmed);
+    if (sanitized.length >= 20) break;
+  }
+  return sanitized;
+}
+
+// v0.16.9 R80 — EXPERIMENTAL Site Guards. Load .cipherwake/guards.json
+// (when --guards flag is present). Returns a {version, guards[]} object or
+// null when --guards is absent / file missing / invalid. Sanitization runs
+// AGAIN server-side via sanitizeGuardsConfig — both layers run so the API
+// never trusts arbitrary structure that landed in the request body.
+async function loadSiteGuards(args) {
+  if (!args.includes("--guards")) return null;
+  try {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const cfgPath = path.join(process.cwd(), ".cipherwake", "guards.json");
+    const raw = await fs.readFile(cfgPath, "utf8");
+    const cfg = JSON.parse(raw);
+    if (!cfg || typeof cfg !== "object" || !Array.isArray(cfg.guards)) return null;
+    // Pass through more-or-less verbatim; server sanitizes. We don't try to
+    // duplicate the full sanitizer here — just sanity-check the shape so we
+    // don't ship obviously bad payloads.
+    return {
+      version: typeof cfg.version === "number" ? cfg.version : 1,
+      guards: cfg.guards.slice(0, 50),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// v0.16.8 — collect first-party host overrides from flags + config file.
+// PSL-backed subdomain auto-promote happens server-side regardless (scanning
+// quantasyte.com always treats *.quantasyte.com as first-party). This list
+// is the escape hatch for multi-domain shops whose owned hosts live under
+// DIFFERENT registrable domains (acme.com + acmecdn.net). Up to 50 entries,
+// each must pass a strict hostname regex (lowercase alphanumeric + hyphen
+// labels separated by dots, no leading/trailing/double dots, ≤253 chars).
+// Server applies the same sanitizer — defense in depth.
+//
+// Source priority:
+//   1. --first-party-host flag, repeatable (e.g. --first-party-host api.acme.com)
+//   2. .cipherwake/config.json `firstPartyHosts: string[]` in CWD
+const FIRST_PARTY_HOST_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/;
+async function loadFirstPartyHosts(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--first-party-host" && i + 1 < args.length) {
+      out.push(args[i + 1]);
+    }
+  }
+  try {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const cfgPath = path.join(process.cwd(), ".cipherwake", "config.json");
+    const raw = await fs.readFile(cfgPath, "utf8");
+    const cfg = JSON.parse(raw);
+    if (Array.isArray(cfg.firstPartyHosts)) {
+      for (const h of cfg.firstPartyHosts) {
+        if (typeof h === "string") out.push(h);
+      }
+    }
+  } catch {
+    // No config file or invalid JSON — fall back to flag-only.
+  }
+  const seen = new Set();
+  const sanitized = [];
+  for (const h of out) {
+    const norm = String(h).trim().toLowerCase();
+    if (norm.length === 0 || norm.length > 253) continue;
+    if (!FIRST_PARTY_HOST_RE.test(norm)) continue;
+    if (seen.has(norm)) continue;
+    seen.add(norm);
+    sanitized.push(norm);
+    if (sanitized.length >= 50) break;
+  }
+  return sanitized;
+}
+
+// v0.16.9 R80 — EXPERIMENTAL Site Guards subcommand surface.
+// Subcommands:
+//   pqcheck guards init [--domain D]   — create .cipherwake/guards.json with default guard set
+//   pqcheck guards list                 — show configured guards + mode/severity
+//   pqcheck guards run --preview URL    — run guards against a URL via preview-diff
+//                       --production URL  (required because guards run as part of the same scan path)
+//
+// The full activate/observe/disable/approve-host/add-protected-path surface from
+// the original spec is intentionally deferred — those are JSON edits the user
+// can do by hand against `.cipherwake/guards.json`. We can add the editor sugar
+// once the core flow has soaked in real use.
+async function runGuardsCommand(args) {
+  const sub = args[0];
+  if (!sub || sub === "--help" || sub === "-h") {
+    console.log(`${color("bold", "pqcheck guards")} — Site Guards beta (EXPERIMENTAL)`);
+    console.log("");
+    console.log("Subcommands:");
+    console.log(`  ${color("cyan", "init")} [--domain D]              Create .cipherwake/guards.json with default guards`);
+    console.log(`  ${color("cyan", "list")}                            Show configured guards from .cipherwake/guards.json`);
+    console.log(`  ${color("cyan", "run")} --preview URL --production URL`);
+    console.log(`                                  Run guards against a URL (uses preview-diff path)`);
+    console.log("");
+    console.log("Or pass " + color("bold", "--guards") + " to " + color("bold", "pqcheck preview-diff") + " to run guards alongside the diff.");
+    console.log("");
+    console.log(color("yellow", "BETA: Site Guards are experimental. New guards default to observe mode."));
+    console.log(color("dim", "Docs: https://cipherwake.io/methodology/site-guards"));
+    return;
+  }
+  if (sub === "init") return runGuardsInitCommand(args.slice(1));
+  if (sub === "list") return runGuardsListCommand(args.slice(1));
+  if (sub === "run") return runGuardsRunCommand(args.slice(1));
+  console.error(color("red", `error: unknown guards subcommand: ${sub}`));
+  console.error(color("dim", "Run `pqcheck guards --help` for usage."));
+  process.exit(1);
+}
+
+async function runGuardsInitCommand(args) {
+  const fs = await import("node:fs/promises");
+  const path = await import("node:path");
+  const domain = parseFlag(args, "--domain") || "your-domain.com";
+  const force = args.includes("--force");
+  const cfgDir = path.join(process.cwd(), ".cipherwake");
+  const cfgPath = path.join(cfgDir, "guards.json");
+  try {
+    await fs.access(cfgPath);
+    if (!force) {
+      console.error(color("yellow", `warn: ${cfgPath} already exists. Pass --force to overwrite.`));
+      process.exit(1);
+    }
+  } catch { /* file doesn't exist, fine */ }
+  // Default set mirrors lib/siteGuards.ts defaultGuardsConfig — duplicated here
+  // to avoid an import dependency from the CLI bundle on the TS lib at runtime.
+  const defaults = {
+    version: 1,
+    domain,
+    firstPartyHosts: [],
+    guards: [
+      { id: "no-source-maps", type: "source_map_exposure", mode: "observe", severity: "review" },
+      { id: "no-mixed-content", type: "mixed_content", mode: "observe", severity: "review" },
+      { id: "approved-hosts", type: "approved_hosts", mode: "observe", severity: "review", approvedHosts: [] },
+      { id: "protected-admin", type: "protected_path", path: "/admin", expect: "401_or_302", mode: "observe", severity: "block" },
+      { id: "session-cookie-flags", type: "cookie_flags", cookieNamePattern: "(?:session|sess|auth|token|sid|csrf|jwt)", require: ["Secure", "HttpOnly"], sameSiteMinimum: "Lax", mode: "observe", severity: "block" },
+      { id: "primary-links-resolve", type: "link_integrity", mode: "observe", severity: "review" },
+    ],
+  };
+  await fs.mkdir(cfgDir, { recursive: true });
+  await fs.writeFile(cfgPath, JSON.stringify(defaults, null, 2) + "\n");
+  console.log(color("green", `✓ wrote ${cfgPath}`));
+  console.log(color("dim", "  6 guards configured · all in observe mode (default)"));
+  console.log(color("dim", "  Edit guards.json to flip to active mode or seed approvedHosts."));
+  console.log(color("dim", "  Then: npx pqcheck preview-diff --preview <URL> --production <URL> --guards"));
+}
+
+async function runGuardsListCommand(_args) {
+  const fs = await import("node:fs/promises");
+  const path = await import("node:path");
+  const cfgPath = path.join(process.cwd(), ".cipherwake", "guards.json");
+  let cfg;
+  try {
+    cfg = JSON.parse(await fs.readFile(cfgPath, "utf8"));
+  } catch (err) {
+    console.error(color("red", `error: could not read ${cfgPath}: ${err.message}`));
+    console.error(color("dim", "Run `pqcheck guards init` to create one."));
+    process.exit(1);
+  }
+  const guards = Array.isArray(cfg.guards) ? cfg.guards : [];
+  if (guards.length === 0) {
+    console.log(color("dim", "(no guards configured)"));
+    return;
+  }
+  console.log(`${color("bold", `${guards.length} guard${guards.length === 1 ? "" : "s"}`)}${cfg.domain ? color("dim", ` · ${cfg.domain}`) : ""}`);
+  for (const g of guards) {
+    const mode = g.mode ?? "observe";
+    const modeChip = mode === "active" ? color("cyan", `[${mode}]`)
+      : mode === "disabled" ? color("dim", `[${mode}]`)
+      : color("yellow", `[${mode}]`);
+    const sev = color("dim", `· ${g.severity ?? "review"}`);
+    console.log(`  ${modeChip} ${color("bold", g.id)} (${g.type}) ${sev}`);
+  }
+  console.log("");
+  console.log(color("yellow", "BETA — Site Guards are experimental. Observe-mode guards never affect CI."));
+}
+
+async function runGuardsRunCommand(args) {
+  // Convenience wrapper — re-runs preview-diff with --guards forced on.
+  // Useful for "just run my guards, don't think about preview-diff" UX.
+  if (!args.includes("--guards")) args = ["--guards", ...args];
+  return runPreviewDiffCommand(args);
+}
+
 async function runPreviewDiffCommand(args) {
   const previewUrl = parseFlag(args, "--preview");
   const productionUrl = parseFlag(args, "--production");
   if (!previewUrl || !productionUrl) {
     console.error(color("red", "error: pqcheck preview-diff requires --preview and --production URLs"));
-    console.error(color("dim", "Usage: npx pqcheck preview-diff --preview https://preview-xyz.vercel.app --production https://example.com [--compare-transport] [--fail-on high] [--format pretty|json]"));
+    console.error(color("dim", "Usage: npx pqcheck preview-diff --preview https://preview-xyz.vercel.app --production https://example.com [--compare-transport] [--fail-on high] [--format pretty|json] [--protected-path /api/admin/export]... [--first-party-host api.acme.com]..."));
     process.exit(3);
   }
 
@@ -3220,6 +3486,23 @@ async function runPreviewDiffCommand(args) {
     ? "report"
     : "fail";
 
+  // v0.16.6 R76 — custom protected paths. Source priority:
+  //   1. --protected-path flag (repeatable, e.g. --protected-path /api/admin/export)
+  //   2. .cipherwake/config.json `protectedPaths: string[]` in CWD
+  // Sanitized + capped server-side. Lets each customer probe their own auth-
+  // gated routes alongside the universal default list.
+  const customProtectedPaths = await loadCustomProtectedPaths(args);
+
+  // v0.16.8 — first-party host overrides. Server unconditionally treats
+  // subdomains of the scanned hostname as first-party (PSL-backed); this
+  // list adds owned hosts whose registrable domains differ.
+  const customFirstPartyHosts = await loadFirstPartyHosts(args);
+
+  // v0.16.9 R80 — EXPERIMENTAL Site Guards. Only loaded when --guards flag
+  // is present; otherwise the request includes no site_guards block and the
+  // response's site_guards array stays empty.
+  const siteGuardsPayload = await loadSiteGuards(args);
+
   const headers = {
     "Content-Type": "application/json",
     "User-Agent": `pqcheck-cli/${VERSION}`,
@@ -3239,6 +3522,9 @@ async function runPreviewDiffCommand(args) {
         compare_transport: compareTransport,
         fail_on: failOn,
         policy_mode: policyMode,
+        ...(customProtectedPaths.length > 0 ? { protected_paths: customProtectedPaths } : {}),
+        ...(customFirstPartyHosts.length > 0 ? { first_party_hosts: customFirstPartyHosts } : {}),
+        ...(siteGuardsPayload ? { site_guards: siteGuardsPayload } : {}),
       }),
     });
   } catch (err) {
@@ -3270,6 +3556,10 @@ async function runPreviewDiffCommand(args) {
   const result = await resp.json();
   const verdict = result?.result?.verdict || "pass";
   const summaryLines = result?.result?.summary_lines || [];
+  // v0.16.6 R78 — plain-English "what this means" sentence per finding,
+  // parallel to summaryLines. Renders as a dim sub-line under each tech
+  // line so non-security readers see the consequence at a glance.
+  const summaryLinesHuman = result?.result?.summary_lines_human || [];
 
   // AI Coder Mode — three-layer output (banner / body / structured block).
   if (parseAiMode(args)) {
@@ -3344,9 +3634,16 @@ async function runPreviewDiffCommand(args) {
     console.log(formatDecisionPulse({ shipDecision, alertCount: deltaLines.length, unreachable: false, diffContext: true }));
 
     if (deltaLines.length > 0) {
+      // v0.16.6 R78 — find the matching human-readable line for each tech
+      // line. summaryLinesHuman is parallel-indexed to summaryLines, so we
+      // re-derive the index from the original (unfiltered) summaryLines
+      // array.
       for (const dl of deltaLines.slice(0, 3)) {
         const sym = dl.startsWith("⛔") || dl.startsWith("-") ? "red" : dl.startsWith("⚠") || dl.startsWith("~") ? "yellow" : "dim";
         console.log(color(sym, dl));
+        const idx = summaryLines.indexOf(dl);
+        const human = idx >= 0 ? summaryLinesHuman[idx] : null;
+        if (human) console.log(color("dim", `   → ${human}`));
       }
       if (deltaLines.length > 3) console.log(color("dim", `  +${deltaLines.length - 3} more (run with --verbose)`));
     }
@@ -3359,7 +3656,10 @@ async function runPreviewDiffCommand(args) {
     //   - default: 1-line "9/9 signals match (preview ↔ production)" so the
     //     customer sees the checks fired without scrolling
     //   - --verbose: per-row table with both sides spelled out
-    const psl = formatPreviewDiffPerSignal(prevSig, prodSig, { verbose });
+    const scriptDeltas = Array.isArray(result?.result?.application_surface?.scripts)
+      ? result.result.application_surface.scripts
+      : [];
+    const psl = formatPreviewDiffPerSignal(prevSig, prodSig, { verbose, scriptDeltas });
     if (psl) console.log(psl);
     if (!verbose) {
       console.log(color("dim", "  Run with --verbose to see per-signal breakdown."));
@@ -3436,12 +3736,56 @@ async function runPreviewDiffCommand(args) {
     if (summaryLines.length === 0 || (summaryLines.length === 1 && /no meaningful/i.test(summaryLines[0]))) {
       console.log(`    ${color("green", "✓ No meaningful application-surface changes detected.")}`);
     } else {
-      for (const line of summaryLines) {
+      // v0.16.6 R78 — pretty mode renders the tech line + dim layman sub-line.
+      for (let i = 0; i < summaryLines.length; i++) {
+        const line = summaryLines[i];
+        const human = summaryLinesHuman[i];
         const c = line.startsWith("+") ? "yellow" : line.startsWith("-") ? "red" : "dim";
         console.log(`    ${color(c, line)}`);
+        if (human) console.log(`      ${color("dim", "→ " + human)}`);
       }
     }
     console.log("");
+    // v0.16.9 R80 — EXPERIMENTAL Site Guards rendering. Only shown when the
+    // server returned a non-empty site_guards array. Renders status tally
+    // (passed / failed / not_checked / probe_failed / not_applicable) then
+    // per-guard one-liners. Observe-mode failures are labeled "observation"
+    // so the customer reads them as informational. Active-mode failures use
+    // the same prefix as preview-diff findings.
+    const siteGuards = Array.isArray(result?.site_guards) ? result.site_guards : [];
+    if (siteGuards.length > 0) {
+      console.log(`  ${color("bold", "Site Guards")} ${color("yellow", "(BETA)")}`);
+      const tally = { pass: 0, fail: 0, not_checked: 0, probe_failed: 0, not_applicable: 0 };
+      for (const g of siteGuards) {
+        tally[g.status] = (tally[g.status] ?? 0) + 1;
+      }
+      const tallyParts = [];
+      if (tally.pass > 0) tallyParts.push(color("green", `${tally.pass} passed`));
+      if (tally.fail > 0) tallyParts.push(color("red", `${tally.fail} failed`));
+      if (tally.not_checked > 0) tallyParts.push(color("dim", `${tally.not_checked} disabled`));
+      if (tally.probe_failed > 0) tallyParts.push(color("yellow", `${tally.probe_failed} probe-failed`));
+      if (tally.not_applicable > 0) tallyParts.push(color("dim", `${tally.not_applicable} n/a`));
+      console.log(`    ${siteGuards.length} guards checked: ${tallyParts.join(color("dim", " · "))}`);
+      for (const g of siteGuards) {
+        const isFail = g.status === "fail";
+        const isPass = g.status === "pass";
+        const isObserve = g.mode === "observe";
+        const mark = isFail
+          ? (isObserve ? color("yellow", "◌") : color("red", "⛔"))
+          : isPass ? color("green", "✓")
+          : g.status === "probe_failed" ? color("yellow", "?")
+          : color("dim", "·");
+        const label = isFail && isObserve
+          ? color("dim", "observation:")
+          : isFail ? color("red", "fail:")
+          : color("dim", `${g.status}:`);
+        console.log(`    ${mark} ${color("bold", g.id)} ${label} ${g.message}`);
+        if (g.human) {
+          console.log(`      ${color("dim", "→ " + g.human)}`);
+        }
+      }
+      console.log("");
+    }
     const transport = result?.result?.transport || {};
     if (transport.preview_is_edge_hosted) {
       console.log(`  ${color("dim", `Transport: preview is edge-hosted (${transport.preview_cert_issuer ?? "unknown"}) — informational only.`)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pqcheck",
-  "version": "0.16.4",
+  "version": "0.16.10",
   "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",