pqcheck 0.15.0 → 0.15.2

package/README.md

@@ -27,7 +27,9 @@ The same scanner that powers [cipherwake.io](https://cipherwake.io), the browser
 | `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. |
 | **`npx pqcheck guard --domain <D> -- <cmd>`** 🆕 | **Deploy guard wrapper.** Wraps any deploy command. Runs `deploy-check` first; conditionally runs `<cmd>` based on `ship_decision`. Modes: `--gate-mode balanced` (default) / `advisory` / `strict`. ONE command instead of two — the strongest single artifact for AI-coder workflows because the AI never has to remember to chain check + deploy. |
 | **`npx pqcheck protocol install`** 🆕 | **Opt-in installer** for the AI Coder Protocol — appends the pre-deploy verification rule to your `CLAUDE.md` / `.cursorrules` / `.aider.conf.yml` with explicit consent (Rule 17). One upfront question (auto / manual / no). Never silent writes. |
-| **`npx pqcheck setup --auto --domain <D>`** 🆕 | **One-command full setup for every AI coder.** Installs (idempotently): GitHub Action workflow, AI Coder Protocol across all detected rules files (Claude / Cursor / Copilot / Aider / Windsurf / Continue / Cline / AGENTS.md) using fenced markers (`<!-- CIPHERWAKE_AI_CODER_PROTOCOL_START/END -->`), git pre-push hook, Claude Code statusLine + chat-hook (PostToolUse Bash). Skip flags available. Backups taken before any `~/.claude/settings.json` write. Audit trail at `~/.config/cipherwake/install-prefs.json`; install manifest at `~/.config/cipherwake/install-manifest.json`. |
+| **`npx pqcheck setup --auto --domain <D>`** 🆕 | **One-command full setup for every AI coder.** Installs (idempotently): GitHub Action workflow, AI Coder Protocol across all detected rules files (Claude / Cursor / Copilot / Aider / Windsurf / Continue / Cline / AGENTS.md) using fenced markers (`<!-- CIPHERWAKE_AI_CODER_PROTOCOL_START/END -->`), git pre-push hook, Claude Code statusLine + 2 hooks (PostToolUse Bash + **UserPromptSubmit** ⓝ), per-repo `.cipherwake/last-status.json` for Cursor / Copilot / Continue to read as context. Skip flags available. Backups taken before any `~/.claude/settings.json` write. Audit trail at `~/.config/cipherwake/install-prefs.json`; install manifest at `~/.config/cipherwake/install-manifest.json`. |
+| **`UserPromptSubmit` hook** (v0.15.1 ⓝ) | **Claude sees `ship_decision` before responding to every prompt.** When `pqcheck setup --auto` runs, it wires `cipherwake-prompt-hook` as a Claude Code UserPromptSubmit hook. On every user prompt, the hook injects `additionalContext` with the current scan's `ship_decision` IF it's `review`/`block` and the state is <24h old. Silent when state is missing, stale, or `pass`. Different timing from the PostToolUse chat-hook: this fires *before* Claude thinks (proactive), the chat-hook fires *after* a Bash command (reactive). |
+| **Per-repo state file** `.cipherwake/last-status.json` (v0.15.1 ⓝ) | **Cursor / Copilot / Continue read this for workspace context.** Every `pqcheck` scan writes the same payload as the per-user file. Created by `setup --auto`; auto-added to `.gitignore` (per-developer state, not committable). Gives AI agents inside VS Code-family editors a repo-local artifact they pick up automatically when reading workspace files. |
 | **`npx pqcheck setup --plan --domain <D>`** 🆕 | **Dry-run mode.** Prints every file change `--auto` would make (target paths + operation type: create / append-markered / deep-merge / backup-first) without writing anything. Run this first when you're not sure what `--auto` will touch. |
 | **`npx pqcheck debug-network`** 🆕 | **Connectivity diagnostic.** Probes cipherwake.io API, homepage, crt.sh upstream, and the direct Vercel URL (bypassing Cloudflare). Reports HTTP status + timing per hop. Use when "scan hung" / "command not found" / corporate proxy issues come up — surfaces the actual broken hop with an actionable cause list. |
 | **`--ai` flag** (any of the above) | **AI Coder Mode** (0.15.0). Three-layer output (banner / body / structured `CIPHERWAKE_AI_GUARD_RESULT` block) tuned for Claude Code / Cursor / Aider / Zed. Includes a `ship_decision=pass\|review\|block` field your AI coworker parses to decide whether to announce the deploy, ask you, or revert. See [/methodology/ai-coder-mode](https://cipherwake.io/methodology/ai-coder-mode). |

package/bin/cipherwake-prompt-hook.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// =============================================================================
+// cipherwake-prompt-hook — Claude Code UserPromptSubmit hook (v0.15.1 parity)
+// =============================================================================
+// Fires BEFORE Claude responds to every user prompt. Injects the latest scan
+// state from ~/.config/cipherwake/last-scan.json into Claude's context, so
+// the AI sees ship_decision proactively (e.g., when the user says "ok deploy
+// this", Claude already knows the trust posture).
+//
+// Different timing from cipherwake-chat-hook (PostToolUse Bash) — that one
+// fires AFTER a tool runs and pushes a chat message reactively. This one
+// fires BEFORE the model thinks, by injecting additionalContext via the
+// hookSpecificOutput shape.
+//
+// Silent (no injection) when:
+//   • state file missing
+//   • state file > 24h old (don't anchor on stale data)
+//   • ship_decision === "pass" (no need to spam the model with good news)
+//
+// Wire-up via `pqcheck setup --auto` writes the entry to
+// ~/.claude/settings.json under `hooks.UserPromptSubmit`.
+// =============================================================================
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const STATE_FILE = process.env.CIPHERWAKE_STATE_FILE
+  || join(homedir(), ".config", "cipherwake", "last-scan.json");
+
+const MAX_STATE_AGE_MS = 24 * 60 * 60 * 1000; // 24h — older than this, don't inject
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => (data += chunk));
+    process.stdin.on("end", () => resolve(data));
+    // If no stdin (manual invocation), resolve empty immediately
+    if (process.stdin.isTTY) resolve("");
+  });
+}
+
+function silent() {
+  // Output nothing — Claude Code treats empty output as "no injection".
+  process.exit(0);
+}
+
+async function main() {
+  // Drain stdin (Claude Code sends a JSON event payload). We don't actually
+  // need the event content here — we just decide based on cached state.
+  try { await readStdin(); } catch { /* ignore */ }
+
+  let state;
+  try {
+    state = JSON.parse(readFileSync(STATE_FILE, "utf8"));
+  } catch {
+    silent();
+    return;
+  }
+
+  // Freshness: only inject if the last scan is recent. Anchoring Claude on
+  // a week-old REVIEW state would be misleading after the user has likely
+  // already fixed the issue.
+  const writtenAt = state.written_at ? new Date(state.written_at).getTime() : 0;
+  if (!writtenAt || Date.now() - writtenAt > MAX_STATE_AGE_MS) {
+    silent();
+    return;
+  }
+
+  // Only inject for non-pass states. Don't spam the model with good news on
+  // every prompt — Claude already trusts that no news is good news.
+  const shipDecision = String(state.ship_decision || "").toLowerCase();
+  if (shipDecision !== "review" && shipDecision !== "block") {
+    silent();
+    return;
+  }
+
+  const emoji = shipDecision === "block" ? "⛔" : "⚠";
+  const sevLabel = shipDecision === "block" ? "BLOCK" : "REVIEW";
+  const dbr = typeof state.score === "number" ? state.score.toFixed(1) : "?";
+  const grade = state.grade || "?";
+  const maxSev = String(state.max_severity || "").toUpperCase();
+  const top = state.top_issue || "—";
+  const ago = Math.floor((Date.now() - writtenAt) / 60000);
+  const ageStr = ago < 1 ? "just now" : ago < 60 ? `${ago}m ago` : `${Math.floor(ago / 60)}h ago`;
+
+  // Build the context-injection block. Brevity matters — this lands in every
+  // user prompt's context, so it should be a one-paragraph reminder, not a
+  // multi-screen status report.
+  const additionalContext =
+    `${emoji} Cipherwake — latest scan of ${state.domain || "configured domain"}: ship_decision=${shipDecision} ` +
+    `(${sevLabel}, DBR ${dbr} ${grade}, max ${maxSev}, last scanned ${ageStr}). ` +
+    `Top issue: ${top}. ` +
+    `Before announcing a deploy, run \`npx pqcheck deploy-check ${state.domain || "<domain>"} --ai\` to refresh. ` +
+    `If ship_decision is still ${shipDecision}, surface the change to the user per the AI Coder Protocol ` +
+    `(https://cipherwake.io/methodology/ai-coder-protocol) — don't auto-announce.`;
+
+  // Claude Code's UserPromptSubmit hook accepts hookSpecificOutput.additionalContext
+  // which is injected into the model's input on this turn. The hook returns
+  // synchronously; suppressOutput hides anything on stdout from the UI.
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext,
+    },
+    suppressOutput: true,
+  }));
+}
+
+main().catch(() => silent());

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.0";
+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 }) {
@@ -633,18 +692,39 @@ function formatAiFooterBlock(fields) {
 }
 
 // Persist last-scan state to ~/.config/cipherwake/last-scan.json.
-// Feeds the optional cipherwake-statusline script (v0.16.0) so users get
-// persistent ambient state in their AI coder's status line. Best-effort —
-// never throws (a write failure here doesn't break the scan).
+// Feeds the cipherwake-statusline + cipherwake-prompt-hook + cipherwake-chat-hook
+// scripts so users get persistent ambient state in their AI coder's surfaces.
+//
+// v0.15.1 (2026-05-22): ALSO writes a per-repo state file at
+// .cipherwake/last-status.json IF that directory exists in cwd (created by
+// `pqcheck setup --auto`). This gives Cursor / Copilot / Continue / Cline
+// agents a read-on-demand surface inside the repo — they see the latest
+// trust posture for the customer's primary domain when scanning repo state.
+//
+// Best-effort — never throws (a write failure doesn't break the scan).
 async function writeLastScanFile(payload) {
   try {
     const os = await import("node:os");
     const path = await import("node:path");
     const fs = await import("node:fs/promises");
-    const dir = path.join(os.homedir(), ".config", "cipherwake");
-    await fs.mkdir(dir, { recursive: true });
-    const file = path.join(dir, "last-scan.json");
-    await fs.writeFile(file, JSON.stringify({ ...payload, written_at: new Date().toISOString() }, null, 2));
+    const enriched = { ...payload, written_at: new Date().toISOString() };
+
+    // Per-user state file (primary, always written)
+    const userDir = path.join(os.homedir(), ".config", "cipherwake");
+    await fs.mkdir(userDir, { recursive: true });
+    await fs.writeFile(path.join(userDir, "last-scan.json"), JSON.stringify(enriched, null, 2));
+
+    // Per-repo state file (secondary, only if .cipherwake/ exists in cwd
+    // — i.e., this repo went through `pqcheck setup --auto`). Gives Cursor/
+    // Copilot/Continue/Cline agents a repo-local artifact they pick up
+    // automatically when reading workspace state.
+    const repoDir = path.join(process.cwd(), ".cipherwake");
+    try {
+      await fs.access(repoDir);
+      await fs.writeFile(path.join(repoDir, "last-status.json"), JSON.stringify(enriched, null, 2));
+    } catch {
+      // .cipherwake/ doesn't exist here — that's fine, user didn't run setup --auto in this repo
+    }
   } catch {
     // best-effort
   }
@@ -2312,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)`));
@@ -2336,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);
 }
@@ -4991,6 +5124,96 @@ async function runSetupCommand(args) {
     }
   }
 
+  // -------------------------------------------------------------------------
+  // Component 4c: Claude Code prompt-hook (UserPromptSubmit → cipherwake-prompt-hook)
+  // v0.15.1 — pinnedai-parity item. Injects ship_decision into Claude's
+  // context BEFORE Claude responds to every user prompt. Different timing
+  // from 4b: chat-hook fires AFTER a tool ran (reactive), prompt-hook fires
+  // BEFORE Claude responds (proactive). Silent when state is missing / stale
+  // / ship_decision=pass (no spam).
+  // -------------------------------------------------------------------------
+  if (!skipStatusline) {
+    const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+    try {
+      let settings = {};
+      let existed = false;
+      try {
+        const raw = await fs.readFile(settingsPath, "utf8");
+        settings = JSON.parse(raw);
+        existed = true;
+      } catch { /* will create */ }
+      settings.hooks = settings.hooks || {};
+      settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit || [];
+
+      const cipherwakeHookCmd = "npx cipherwake-prompt-hook";
+      const alreadyInstalled = settings.hooks.UserPromptSubmit.some(
+        (entry) => Array.isArray(entry?.hooks) && entry.hooks.some(
+          (h) => h?.type === "command" && typeof h?.command === "string" && h.command.includes("cipherwake-prompt-hook"),
+        ),
+      );
+
+      if (alreadyInstalled) {
+        console.log(color("dim", `  ⊝ prompt-hook already configured in ~/.claude/settings.json UserPromptSubmit — skipping`));
+        installSummary.push({ component: "Claude Code prompt-hook", path: settingsPath, status: "skipped-already-present" });
+      } else {
+        const backupPath = existed ? await backupSettingsJson(settingsPath) : null;
+        if (backupPath) console.log(color("dim", `    backup: ${backupPath}`));
+        settings.hooks.UserPromptSubmit.push({ hooks: [{ type: "command", command: cipherwakeHookCmd }] });
+        await fs.mkdir(path.dirname(settingsPath), { recursive: true });
+        await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+        console.log(color("green", `  ✓ added prompt-hook (UserPromptSubmit) → ~/.claude/settings.json`));
+        console.log(color("dim", `    Claude will see latest ship_decision in context on every prompt (when REVIEW/BLOCK)`));
+        installSummary.push({ component: "Claude Code prompt-hook", path: settingsPath, status: existed ? "installed-updated" : "installed-created", backup: backupPath });
+      }
+    } catch (err) {
+      console.log(color("red", `  ✗ prompt-hook install failed: ${err.message}`));
+      installSummary.push({ component: "Claude Code prompt-hook", status: "failed", error: String(err?.message || err) });
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Component 4d: Per-repo state directory (.cipherwake/) for Cursor / Copilot
+  // v0.15.1 — pinnedai-parity item. Cursor/Copilot/Continue/Cline read repo
+  // state for context. Creating .cipherwake/ in the repo gives them a
+  // read-on-demand surface that subsequent `pqcheck` runs (via the
+  // writeLastScanFile path) populate with the latest scan state. Also adds
+  // .cipherwake/ to .gitignore if not already there — per-developer state,
+  // not committable.
+  // -------------------------------------------------------------------------
+  if (!skipStatusline) {
+    try {
+      const repoStateDir = path.join(process.cwd(), ".cipherwake");
+      await fs.mkdir(repoStateDir, { recursive: true });
+      // Write an initial placeholder so the file exists immediately. Subsequent
+      // scans via writeLastScanFile will overwrite with real data.
+      const placeholderPath = path.join(repoStateDir, "last-status.json");
+      try {
+        await fs.access(placeholderPath);
+        // Already exists — preserve it.
+      } catch {
+        await fs.writeFile(placeholderPath, JSON.stringify({
+          domain,
+          ship_decision: "unknown",
+          note: "Initial placeholder — run `npx pqcheck deploy-check " + domain + " --ai` to populate",
+          written_at: new Date().toISOString(),
+        }, null, 2));
+      }
+      // Add .cipherwake/ to .gitignore if missing (don't commit per-developer state).
+      const gitignorePath = path.join(process.cwd(), ".gitignore");
+      let gitignore = "";
+      try { gitignore = await fs.readFile(gitignorePath, "utf8"); } catch { /* may not exist */ }
+      if (!/^\.cipherwake\/?\s*$/m.test(gitignore)) {
+        const appended = gitignore + (gitignore.endsWith("\n") || gitignore.length === 0 ? "" : "\n") + "\n# Cipherwake per-developer scan state (read-on-demand by AI coders)\n.cipherwake/\n";
+        await fs.writeFile(gitignorePath, appended);
+      }
+      console.log(color("green", `  ✓ created .cipherwake/last-status.json (Cursor/Copilot/Continue read this for context)`));
+      installSummary.push({ component: "Per-repo state file", path: placeholderPath, status: "installed" });
+    } catch (err) {
+      console.log(color("red", `  ✗ per-repo state install failed: ${err.message}`));
+      installSummary.push({ component: "Per-repo state file", status: "failed", error: String(err?.message || err) });
+    }
+  }
+
   // -------------------------------------------------------------------------
   // Component 5: VS Code / Cursor extension (via `code` CLI if available)
   // -------------------------------------------------------------------------

package/package.json

@@ -1,21 +1,29 @@
 {
   "name": "pqcheck",
-  "version": "0.15.0",
-  "description": "HTTPS posture scanner with Preview Deploy Trust Diff for PRs, Trust Diff for CI, vendor lockfile + drift alerts, cross-tenant key map, and HNDL/quantum-decryption risk scoring. Free, no signup.",
+  "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": [
-    "post-quantum",
-    "cryptography",
+    "ai-coder",
+    "claude-code",
+    "cursor",
+    "copilot",
+    "aider",
+    "deploy-gate",
+    "deploy-check",
+    "ai-coder-mode",
+    "ship-decision",
+    "deploy-guard",
+    "ci",
     "security",
     "tls",
     "ssl",
     "scanner",
+    "post-quantum",
     "harvest-now-decrypt-later",
     "hndl",
     "blast-radius",
     "pqc",
-    "quantum",
-    "crypto-audit",
-    "crypto-inventory"
+    "quantum"
   ],
   "homepage": "https://cipherwake.io",
   "bugs": "https://cipherwake.io",
@@ -33,7 +41,8 @@
   "bin": {
     "pqcheck": "./bin/pqcheck.js",
     "cipherwake-statusline": "./bin/cipherwake-statusline.js",
-    "cipherwake-chat-hook": "./bin/cipherwake-chat-hook.js"
+    "cipherwake-chat-hook": "./bin/cipherwake-chat-hook.js",
+    "cipherwake-prompt-hook": "./bin/cipherwake-prompt-hook.js"
   },
   "files": [
     "bin/",