From b707ae085923b27a63c8c655ccab63d3dc624042 Mon Sep 17 00:00:00 2001
From: Mario Tarosso <mariojgt2@gmail.com>
Date: Mon, 26 Oct 2026 11:18:27 +0000
Subject: [PATCH 1/2] Add a doctor command that checks everything and says how
 to fix it

`npx @patchstack/connect doctor` runs every check Patchstack depends on
in one go and prints each problem with its fix: the install, the site,
the account, the guard's wiring, its rules file, the read-only rules
credential (and whether Patchstack still accepts it), the map link and
the build steps. With --url it also checks the live app: that it
carries the widget, and that its guard blocks a test attack.

Problems only the app's owner can fix (connecting the account,
publishing) are marked as theirs, so an assistant fixes the rest and
passes those on instead of waiting on them. It writes nothing and exits
1 when it finds a problem.

AGENT-INSTALL.md tells the agent to run it after setup and fix each
problem until none is left, and discloses what it sends.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 AGENT-INSTALL.md     |   5 +-
 README.md            |   2 +
 src/cli.ts           |  29 ++++-
 src/doctor.ts        | 274 +++++++++++++++++++++++++++++++++++++++++++
 tests/doctor.test.ts | 163 +++++++++++++++++++++++++
 5 files changed, 470 insertions(+), 3 deletions(-)
 create mode 100644 src/doctor.ts
 create mode 100644 tests/doctor.test.ts

diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md
index 8d07487..990371c 100644
--- a/AGENT-INSTALL.md
+++ b/AGENT-INSTALL.md
@@ -62,7 +62,8 @@ The pages get a build step, even though nothing is compiled. The build is what r
 2. Install `@patchstack/connect` as a runtime dependency with the project's package manager. If it is missing, `setup` adds it itself.
 3. Run `npx @patchstack/connect setup`. In a hosted builder, scope `PATCHSTACK_ENVIRONMENT=sandbox` to that command — see "Automated setup".
 4. Finish any `✘` line under `To do` in the report at the end of `setup`. "Automated setup" names each one. Do not start, restart or stop the person's app, and do not touch its data, to check the install: `setup` never runs the app, and the protection check needs an app the person already has running.
-5. End by passing on the `──── Summary ────` that `setup` prints: what Patchstack found, the link, what is left to do and the next step, with a reminder to deploy when they are ready. See "The message you end on".
+5. Run `npx @patchstack/connect doctor`. Fix every `✗` it reports, as its `Fix:` line says, and run it again until none is left. A `✗` marked "for the app owner" (connecting their Patchstack account, publishing the app) is not yours to fix: the summary already hands it to the person.
+6. End by passing on the `──── Summary ────` that `setup` prints: what Patchstack found, the link, what is left to do and the next step, with a reminder to deploy when they are ready. See "The message you end on".
 
 **In a workspace repo** — a root `package.json` that declares `workspaces`, with the app in a package such as `apps/web` (Hostinger Horizons generates this shape) — run every command from the repo root. The site is recorded in the root's `.patchstackrc.json`, and `setup` wires the guard and the widget into the app package from there. Do not run `setup` inside the app package, and do not create a `.patchstackrc.json` there. When `setup`, `scan`, `widget` or `protect` is run inside a package of a repo whose root records the site, it runs at the root instead and prints `Running at the project root (…)`.
 
@@ -85,6 +86,7 @@ Every command at a glance — what it does, whether it reads your source, what i
 | `guide` | Print this project's setup status: what is left to do and the four steps, with tailored commands. `--full` adds this reference. | Reads local protection wiring for verification | Nothing | Nothing |
 | `status` | Re-print the site UUID + dashboard URL and check whether the site still exists (active / removed / could not verify) and whether it is connected to an account. | No | The connected note in `.patchstackrc.json`, when it changed | Site-existence and connection checks |
 | `next` | Say where the project stands and the one thing to do now: connect the account (with the link), or go live (with the same steps `go-live` prints, or asking where the app is hosted when the project does not say). Answers the "done" the summary ends on. | Reads the project files `guide` and `go-live` read | The connected note in `.patchstackrc.json`, when it changed | The site UUID, to the public claim page that says whether it is connected (skipped once `.patchstackrc.json` records that it is) |
+| `doctor [--url <live app>]` | Check that everything Patchstack needs works, and print each problem with its fix: the install, the site, the account, the guard's wiring, its rules file, the read-only rules credential, the map link and the build steps. A problem only the app's owner can fix (connecting the account, publishing) is marked as theirs. Exits 1 when it finds a problem. | Reads the project files `guide` and `protect --check` read | Nothing | The site UUID, to the public claim page that says whether it is connected (skipped once `.patchstackrc.json` records that it is); the read-only rules credential from the guard's rules file, once, to `monitor/pulse/token`, to check Patchstack still accepts it (the token it returns is not kept or used); with `--url`, two GET requests to that address: its page, and the same page with a test attack in a `file` parameter |
 | `vulns` | Show what Patchstack found in this project's packages: vulnerabilities by severity and outdated packages, as counts, with the link that shows the details. Package names are shown in the dashboard once the site is connected. | No | Nothing | The site UUID, to the public claim page that returns the counts |
 | `go-live [--host <name>]` | Show how to add the project's API key to its host and deploy, in three steps. The host is read from project files (`vercel.json`, `netlify.toml`, `wrangler.toml`, `fly.toml`, `render.yaml`, `railway.json`, `amplify.yml`, `Procfile`, `.replit`, a Lovable project's packages) or named with `--host`. The commands it prints read the key from `.patchstackrc.local.json` as they run; it never prints the key. | Reads those project files only | Nothing | Nothing |
 | `widget [--remove]` | Add the Patchstack Connector widget tag to the root page (in a workspace repo, the app package's root page), or take the tag Connect added out with `--remove` (a tag added by hand is left alone). Saves the choice as `"widget"` in `.patchstackrc.json`, which `scan` and `mark-build` follow; `setup --widget` saves the same choice. | Reads the root page to find where the tag goes | `.patchstackrc.json`; the widget `<script>` tag in the root HTML shell or framework root | Nothing |
@@ -956,6 +958,7 @@ Three more endpoints the package can call, for completeness:
 ## Verifying the install
 
 - `npx @patchstack/connect status` re-prints the site UUID and dashboard URL, and checks whether the site still exists on Patchstack (`Site status: active / removed / could not be verified`).
+- `npx @patchstack/connect doctor` runs every check at once and prints each problem with its fix; `--url <live app>` adds the live app's widget and a test attack.
 - `npx @patchstack/connect protect --check` verifies from the source that the runtime guard is connected to the request path. It does not run the app. When the project records a site, it also fails if a guard Connect wrote does not carry it (`the guard carries this project's Patchstack site`): such a guard blocks with the rules it shipped with but fetches no rule updates and reports nothing. Run `npx @patchstack/connect protect` from the project root to fill the site in, then deploy.
 - `npx @patchstack/connect protect --check --runtime` additionally **starts the app** on a loopback port and sends it one request, to establish that a request reaches the guard seam. Opt-in, and the only command that runs the application; exit `0`/`1`/`2` as described in step 4.
 - Load the site in a browser — the widget should appear, as the "Connect this website" panel while the site is unclaimed. Refresh a page that was already open before the tag was added: the widget only loads with the page.
diff --git a/README.md b/README.md
index 5ef4579..8b0c402 100644
--- a/README.md
+++ b/README.md
@@ -189,6 +189,8 @@ patchstack-connect setup  [--widget] [options]     Run scan, add the widget with
 patchstack-connect init   <site-uuid>              Optional: pre-seed .patchstackrc.json with
                                                    an existing site UUID
 patchstack-connect status [options]                Show current configuration
+patchstack-connect doctor [--url <live app>]       Check that everything Patchstack needs works and
+                                                   say how to fix each problem
 patchstack-connect vulns                           Show vulnerabilities by severity and outdated
                                                    packages, with the link to the details
 patchstack-connect go-live [--host <name>]         Show how to add your API key to your host
diff --git a/src/cli.ts b/src/cli.ts
index b3aa51d..e93c083 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -114,6 +114,7 @@ import { formatRuntimeCheck, runRuntimeCheck, runtimeExitCode } from './protect/
 import { runMap } from './map-command.js';
 import { bundleRulesAllowed } from './bundled-rules.js';
 import { getStringFlag } from './flags.js';
+import { renderDoctor, runDoctorChecks } from './doctor.js';
 import { isCanonicalUuid } from './endpoint-policy.js';
 import { setupProtection, wireBuildScripts, wireDevelopmentScript } from './setup.js';
 import { runDevelopment } from './dev-command.js';
@@ -137,6 +138,7 @@ function startScreen(color: boolean): string[] {
     '',
     'Then:',
     command('next', 'what to do next'),
+    command('doctor', 'check that everything works'),
     command('vulns', 'see what was found'),
     command('widget', 'show Patchstack inside your app (optional)'),
     command('go-live', 'how to go live on your host'),
@@ -192,6 +194,15 @@ Usage:
   patchstack-connect summary                         Print the summary the last setup wrote, from
                                                      .patchstack/summary.md. Sends nothing; writes
                                                      nothing
+  patchstack-connect doctor [--url <live app>]       Check that everything Patchstack needs works in this
+                                                     project, and say how to fix each problem: install,
+                                                     site, account, protection wiring, the guard's rules
+                                                     file and its read-only credential, the map link and
+                                                     the build steps. Sends the site UUID to the public
+                                                     claim page and asks Patchstack whether it accepts the
+                                                     read-only credential; with --url, also requests the
+                                                     live app's page and one test attack. Writes nothing.
+                                                     Exits 1 when it finds a problem
   patchstack-connect vulns                           Show what Patchstack found in this project's
                                                      packages: vulnerabilities by severity and
                                                      outdated packages, with the link to the
@@ -1693,6 +1704,18 @@ function runSummary(): number {
  * The one thing to do now, for the word the summary ends on. Connection lives on the server, so it is
  * looked up unless `.patchstackrc.json` already records it; everything else is read from the project.
  */
+/** Check everything Patchstack needs in this project and print each problem with its fix. */
+async function runDoctor(args: ParsedArgs): Promise<number> {
+  const cwd = process.cwd();
+  const config = await resolveCliConfig(args);
+  const state = await collectGuideState(cwd);
+  const url = getStringFlag(args.flags, 'url') ?? null;
+  const findings = await runDoctorChecks(cwd, state, config, { url, claimPreview: fetchClaimPreview });
+  for (const line of renderDoctor(findings, { url })) console.log(line);
+
+  return findings.some((finding) => finding.status === 'problem') ? 1 : 0;
+}
+
 async function runNext(args: ParsedArgs): Promise<number> {
   const config = await resolveCliConfig(args);
   if (config.siteUuid === null) {
@@ -2274,12 +2297,12 @@ async function main(): Promise<number> {
 
 /** Commands `runCommand` dispatches; anything else is an unknown command and sends no notice. */
 const KNOWN_COMMANDS = new Set([
-  'init', 'scan', 'vulns', 'next', 'summary', 'go-live', 'widget', 'status', 'uninstall', 'mark-build', 'protect',
+  'init', 'scan', 'vulns', 'next', 'doctor', 'summary', 'go-live', 'widget', 'status', 'uninstall', 'mark-build', 'protect',
   'demo', 'demo-guide', 'guide', 'setup', 'map', 'claim', 'login',
 ]);
 
 /** Commands that act on the whole project, so in a workspace package they run at the root that holds the site. */
-const ROOT_COMMANDS = new Set(['setup', 'scan', 'widget', 'protect']);
+const ROOT_COMMANDS = new Set(['setup', 'scan', 'widget', 'protect', 'doctor']);
 
 /**
  * A run that sent nothing the site's activity log records still tells Patchstack it ran, by the site's
@@ -2306,6 +2329,8 @@ async function runCommand(args: ParsedArgs): Promise<number> {
       return runSummary();
     case 'next':
       return runNext(args);
+    case 'doctor':
+      return runDoctor(args);
     case 'go-live':
       return runGoLive(args);
     case 'widget':
diff --git a/src/doctor.ts b/src/doctor.ts
new file mode 100644
index 0000000..91b2757
--- /dev/null
+++ b/src/doctor.ts
@@ -0,0 +1,274 @@
+// `doctor`: one check of everything Patchstack needs to work in this project, each problem with its fix.
+//
+// It reads the project the way `guide` and `protect --check` do, and adds the checks behind the failures
+// that are otherwise silent: a guard rules file setup cannot find, a missing or retired read-only rules
+// credential, and a map that is not linked to the guard. With --url it also looks at the live app. It
+// writes nothing.
+
+import { readFileSync } from 'node:fs';
+
+import { readBuildStamp } from './build-id.js';
+import { findRulesFile, ruleBundleOf } from './build-stamp.js';
+import { buildClaimUrl, type ClaimPreview } from './client.js';
+import { assertConnectableEndpoint } from './endpoint-policy.js';
+import { DEV_ONLY_INSTALL, guideMissing, needsSourceProductionMarker, type GuideState } from './guide.js';
+import { buildTokenUrl, parsePulseAuth } from './pulse-token.js';
+import { connectHeaders } from './report-context.js';
+import type { Config } from './types.js';
+
+export type DoctorStatus = 'ok' | 'problem' | 'unknown';
+
+export interface DoctorFinding {
+  status: DoctorStatus;
+  /** What was found, in one short sentence. */
+  text: string;
+  /** What to do about it, one line each. */
+  fix?: string[];
+  /** A step only the app's owner can take (connecting their account, publishing), not a change to the project. */
+  owner?: boolean;
+}
+
+export interface DoctorOptions {
+  /** The live app's address, for the checks that need it. */
+  url?: string | null;
+  fetchImpl?: typeof fetch;
+  /** Whether the site has an owner, from the public claim page. */
+  claimPreview: (config: Config) => Promise<ClaimPreview>;
+}
+
+const READER = /^rr_[0-9a-f]{48}-\d+$/;
+const PROBE = '../../../../etc/passwd';
+const LIVE_TIMEOUT_MS = 10_000;
+
+/** Ask Patchstack whether it accepts a credential, without keeping the token it hands back. */
+async function credentialAccepted(config: Config, credential: string, fetchImpl: typeof fetch): Promise<'accepted' | 'refused' | 'unreachable'> {
+  const parsed = parsePulseAuth(credential);
+  if (parsed === null) return 'refused';
+  try {
+    const url = buildTokenUrl(config.endpoint);
+    assertConnectableEndpoint(config, url);
+    const response = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', ...connectHeaders() },
+      body: JSON.stringify({ grant_type: 'client_credentials', client_id: parsed.clientId, client_secret: parsed.clientSecret }),
+      signal: AbortSignal.timeout(config.timeoutMs),
+    });
+
+    return response.ok ? 'accepted' : response.status === 401 || response.status === 403 ? 'refused' : 'unreachable';
+  } catch {
+    return 'unreachable';
+  }
+}
+
+/** The guard's rules file: where it is, the read-only credential in it, and whether the map is linked. */
+async function rulesFileFindings(cwd: string, config: Config, fetchImpl: typeof fetch): Promise<DoctorFinding[]> {
+  const location = findRulesFile(cwd);
+  if (location.kind === 'none') {
+    return [{
+      status: 'problem',
+      text: "Patchstack cannot find the guard's rules file, so setup cannot keep its rules current",
+      fix: ['Run: npx @patchstack/connect protect', 'Then: npx @patchstack/connect setup'],
+    }];
+  }
+  if (location.kind === 'unreadable') {
+    return [{
+      status: 'problem',
+      text: `The guard's rules file is not valid JSON (${location.paths.join(', ')})`,
+      fix: ['Restore it from version control, or delete it and run: npx @patchstack/connect protect', 'Then: npx @patchstack/connect setup'],
+    }];
+  }
+  if (location.kind === 'ambiguous') {
+    return [{
+      status: 'problem',
+      text: `Two Patchstack guards are installed, each with its own rules file (${location.paths.join(', ')})`,
+      fix: [
+        'Keep the guard npx @patchstack/connect protect --check reports as wired.',
+        'Remove the other guard and its rules file, after checking nothing in the app imports that guard.',
+        'Then: npx @patchstack/connect setup',
+      ],
+    }];
+  }
+
+  let bundle: Record<string, unknown> | null = null;
+  try {
+    bundle = ruleBundleOf(JSON.parse(readFileSync(location.path, 'utf8')));
+  } catch {
+    // Read as missing below.
+  }
+  const findings: DoctorFinding[] = [];
+  const reader = (bundle?._patchstack as { rules_reader?: unknown } | undefined)?.rules_reader;
+  if (typeof reader !== 'string' || !READER.test(reader)) {
+    findings.push({
+      status: 'problem',
+      text: "The guard's rules file has no read-only rules credential, so the published app cannot fetch rule updates or report attacks without the site key",
+      fix: ['Run: npx @patchstack/connect setup (it writes the credential; it needs the site key on this machine)', 'Then publish the app again.'],
+    });
+  } else {
+    const verdict = await credentialAccepted(config, reader, fetchImpl);
+    findings.push(
+      verdict === 'accepted'
+        ? { status: 'ok', text: 'The read-only rules credential works: the published app can fetch rule updates and report attacks' }
+        : verdict === 'refused'
+          ? {
+              status: 'problem',
+              text: 'Patchstack refused the read-only rules credential (the site key was replaced, or the site was removed)',
+              fix: ['Run: npx @patchstack/connect setup (it writes a current one)', 'Then publish the app again.'],
+            }
+          : { status: 'unknown', text: 'Could not reach Patchstack to check the read-only rules credential' },
+    );
+  }
+  if (bundle === null || readBuildStamp(bundle) === null) {
+    findings.push({
+      status: 'problem',
+      text: "The app's map is not linked to the guard, so rules written for this app's own inputs can only report, not block",
+      fix: ['Run: npx @patchstack/connect setup --verbose and fix the reason on its "could not bind this map" line', 'Then run setup again.'],
+    });
+  } else {
+    findings.push({ status: 'ok', text: "The app's map is linked to the guard" });
+  }
+
+  return findings;
+}
+
+/** The live app: whether it carries the widget and whether its guard stops a test attack. */
+async function liveFindings(url: string, state: GuideState, fetchImpl: typeof fetch): Promise<DoctorFinding[]> {
+  let page: URL;
+  try {
+    page = new URL(url);
+    if (page.protocol !== 'https:' && page.protocol !== 'http:') throw new Error('not http');
+  } catch {
+    return [{ status: 'unknown', text: `${url} is not a web address; pass the live app's address, e.g. --url https://your-app.example` }];
+  }
+
+  const findings: DoctorFinding[] = [];
+  try {
+    const response = await fetchImpl(page, { signal: AbortSignal.timeout(LIVE_TIMEOUT_MS) });
+    const html = await response.text();
+    // A page that does not load says nothing about the guard either, so the test attack is not sent.
+    if (!response.ok) {
+      return [{ status: 'unknown', text: `The live app answered ${response.status}, so it could not be checked (is it published? a private publish shows a sign-in page)` }];
+    }
+    if (!state.widgetOptOut && state.siteUuid !== null) {
+      findings.push(
+        html.includes('patchstack-widget.js') && html.includes(state.siteUuid)
+          ? { status: 'ok', text: 'The live app carries the Patchstack widget for this site' }
+          : { status: 'problem', text: 'The live app does not carry the Patchstack widget for this site yet', fix: ['Publish the app again: the live app still runs a build from before setup.'], owner: true },
+      );
+    }
+  } catch {
+    return [{ status: 'unknown', text: `Could not reach ${page.origin}` }];
+  }
+
+  const probe = new URL(page);
+  probe.searchParams.set('file', PROBE);
+  try {
+    const response = await fetchImpl(probe, { signal: AbortSignal.timeout(LIVE_TIMEOUT_MS) });
+    const body = await response.text();
+    findings.push(
+      response.status === 403 && /blocked by Patchstack/i.test(body)
+        ? { status: 'ok', text: "The live app's guard blocked a test attack" }
+        : {
+            status: 'problem',
+            text: `The live app let a test attack through (it answered ${response.status} to ?file=${PROBE})`,
+            fix: [
+              'If the app has not been published since setup, publish it again.',
+              'If the site is not connected to a Patchstack account that includes protection, Patchstack only reports attacks: connect it.',
+            ],
+            owner: true,
+          },
+    );
+  } catch {
+    findings.push({ status: 'unknown', text: `Could not reach ${page.origin} for the test attack` });
+  }
+
+  return findings;
+}
+
+/**
+ * Every check, in the order a fix is worth making. `state` is `collectGuideState` for the project.
+ */
+export async function runDoctorChecks(cwd: string, state: GuideState, config: Config, options: DoctorOptions): Promise<DoctorFinding[]> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const findings: DoctorFinding[] = [];
+
+  if (state.installed === null) {
+    return [{ status: 'problem', text: 'Patchstack is not installed in this project', fix: ['Run: npx @patchstack/connect setup'] }];
+  }
+  if (state.siteUuid === null) {
+    return [{ status: 'problem', text: 'This project is not on Patchstack yet', fix: ['Run: npx @patchstack/connect setup'] }];
+  }
+
+  // Whether the site has an owner. The note in .patchstackrc.json answers it once it is recorded.
+  let connected: boolean | null = state.claimed ? true : null;
+  if (connected === null) {
+    const preview = await options.claimPreview(config);
+    connected = preview.state === 'claimed' ? true : preview.state === 'unclaimed' ? false : null;
+  }
+  if (connected === null) findings.push({ status: 'unknown', text: 'Could not reach Patchstack to check whether this site is connected to an account' });
+
+  // Each thing setup leaves to do, as setup and guide word it. The connection is reported above, with its link.
+  const missing = guideMissing(state, { connected: true });
+  if (connected === false) {
+    const link = config.endpointTrusted !== false ? buildClaimUrl(config.endpoint, state.siteUuid) : null;
+    findings.push({
+      status: 'problem',
+      text: 'Not connected to a Patchstack account, so Patchstack only reports attacks and does not block them',
+      fix: [link ? `Open ${link} and sign in.` : 'Run: npx @patchstack/connect claim'],
+      owner: true,
+    });
+  } else if (connected) {
+    findings.push({ status: 'ok', text: 'Connected to a Patchstack account' });
+  }
+  for (const item of missing) {
+    findings.push({ status: 'problem', text: item.plain?.text ?? item.text, fix: [...(item.hint ?? []), ...(item.detail ?? [])] });
+  }
+  const keys = new Set(missing.map((item) => item.key));
+
+  if (!keys.has(DEV_ONLY_INSTALL)) findings.push({ status: 'ok', text: `Patchstack ${state.installed.version} is installed` });
+  if (!state.protectionApplicable) {
+    findings.push({ status: 'ok', text: 'This app has no server to protect, so runtime protection does not apply' });
+  } else if (state.protectionWired) {
+    findings.push({ status: 'ok', text: `Protection is wired into your server (${state.protectionStack})` });
+  }
+  if (state.installScanWired && (!state.hasBuildScript || (state.prebuildWired && state.postbuildWired))) {
+    findings.push({ status: 'ok', text: 'Your installs and builds run the Patchstack check' });
+  }
+  if (needsSourceProductionMarker(state) && state.productionMarkerWired) {
+    findings.push({ status: 'ok', text: 'Your pages carry the marker that tells Patchstack when the app is live' });
+  }
+
+  if (state.protectionApplicable && state.protectionWired) findings.push(...await rulesFileFindings(cwd, config, fetchImpl));
+  if (options.url) findings.push(...await liveFindings(options.url, state, fetchImpl));
+
+  // Problems first, in the order found, then what could not be checked, then what passed.
+  const rank: Record<DoctorStatus, number> = { problem: 0, unknown: 1, ok: 2 };
+
+  return findings.map((finding, index) => ({ finding, index }))
+    .sort((a, b) => rank[a.finding.status] - rank[b.finding.status] || a.index - b.index)
+    .map(({ finding }) => finding);
+}
+
+/** The report, ending with what to do next for whoever runs it, person or assistant. */
+export function renderDoctor(findings: DoctorFinding[], { url }: { url?: string | null } = {}): string[] {
+  const mark: Record<DoctorStatus, string> = { ok: '✓', problem: '✗', unknown: '?' };
+  const lines = ['Patchstack doctor: is Patchstack set up and working in this project?', ''];
+  for (const finding of findings) {
+    lines.push(`  ${mark[finding.status]} ${finding.text}${finding.owner ? ' (for the app owner)' : ''}`);
+    for (const [index, fix] of (finding.fix ?? []).entries()) lines.push(`      ${index === 0 ? 'Fix: ' : '     '}${fix}`);
+  }
+  lines.push('');
+  const problems = findings.filter((finding) => finding.status === 'problem');
+  const toFix = problems.filter((finding) => !finding.owner).length;
+  const forOwner = problems.length - toFix;
+  if (problems.length === 0) lines.push('No problems found.');
+  if (toFix > 0) {
+    lines.push(`${toFix} problem${toFix === 1 ? '' : 's'} to fix in the project. Fix each ✗ above as its Fix line says, then run npx @patchstack/connect doctor again until none is left.`);
+  }
+  if (forOwner > 0) {
+    lines.push(`${forOwner} step${forOwner === 1 ? '' : 's'} for the app owner (marked "for the app owner"): connecting their Patchstack account or publishing the app. Pass ${forOwner === 1 ? 'it' : 'them'} on; nothing in the project fixes ${forOwner === 1 ? 'it' : 'them'}.`);
+  }
+  if (findings.some((finding) => finding.status === 'unknown')) lines.push('A ? could not be checked from here; it is not a problem on its own.');
+  if (!url) lines.push("To also check the live app, run: npx @patchstack/connect doctor --url <your live app's address>");
+
+  return lines;
+}
diff --git a/tests/doctor.test.ts b/tests/doctor.test.ts
new file mode 100644
index 0000000..985fcd6
--- /dev/null
+++ b/tests/doctor.test.ts
@@ -0,0 +1,163 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { renderDoctor, runDoctorChecks, type DoctorFinding } from '../src/doctor.js';
+import { collectGuideState } from '../src/guide.js';
+import { runProtect } from '../src/protect/install/index.js';
+import type { ClaimPreview } from '../src/client.js';
+import type { Config } from '../src/types.js';
+
+const UUID = '556d8930-ae4d-4bf2-bee8-3bc53c096876';
+const READER = `rr_${'a'.repeat(48)}-4242`;
+const dirs: string[] = [];
+afterEach(() => {
+  dirs.splice(0).forEach((dir) => rmSync(dir, { recursive: true, force: true }));
+  vi.restoreAllMocks();
+});
+
+function config(overrides: Partial<Config> = {}): Config {
+  return {
+    siteUuid: UUID,
+    apiKey: null,
+    pulseAuth: null,
+    endpoint: 'https://api.patchstack.com/monitor/pulse/manifest',
+    timeoutMs: 5_000,
+    environment: 'production',
+    widget: false,
+    ...overrides,
+  } as Config;
+}
+
+/** A plain Node server with the generic guard wired the way the guide says, rules file stamped as setup leaves it. */
+function project(patchstack: Record<string, unknown> | null = { rules_reader: READER, build_id: 'b'.repeat(64) }): string {
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+  const cwd = mkdtempSync(join(tmpdir(), 'ps-doctor-'));
+  dirs.push(cwd);
+  writeFileSync(join(cwd, 'package.json'), JSON.stringify({
+    name: 'doctor-fixture', type: 'module',
+    scripts: { start: 'node server.js', postinstall: 'patchstack-connect scan' },
+    dependencies: { '@patchstack/connect': '^0.5.68' },
+  }));
+  writeFileSync(join(cwd, '.patchstackrc.json'), JSON.stringify({ siteUuid: UUID, widget: false, claimed: true }));
+  writeFileSync(join(cwd, 'server.js'), "import http from 'node:http';\nimport { patchstackMiddleware } from './patchstack/guard.js';\nconst handler = (req, res) => res.end('ok');\nhttp.createServer((req, res) => patchstackMiddleware(req, res, () => handler(req, res))).listen(3000);\n");
+  runProtect(cwd);
+  if (patchstack !== null) {
+    const rules = JSON.parse(readFileSync(join(cwd, 'patchstack/rules.json'), 'utf8'));
+    writeFileSync(join(cwd, 'patchstack/rules.json'), JSON.stringify({ ...rules, _patchstack: patchstack }));
+  }
+  return cwd;
+}
+
+/** Patchstack's token endpoint answering `status`, and a live app answering the page and the test attack. */
+function network({ token = 200, page = 200, attack = 403 }: { token?: number | 'down'; page?: number; attack?: number } = {}) {
+  const calls: string[] = [];
+  const fetchImpl = vi.fn(async (input: string | URL) => {
+    const url = String(input);
+    calls.push(url);
+    if (url.endsWith('/token')) {
+      if (token === 'down') throw new Error('offline');
+      return new Response('{}', { status: token });
+    }
+    if (url.includes('file=')) return new Response(attack === 403 ? '{"error":"This request has been blocked by Patchstack."}' : '<html></html>', { status: attack });
+    return new Response(`<html><script src="https://cdn.patchstack.com/patchstack-widget.js" data-site-uuid="${UUID}"></script></html>`, { status: page });
+  }) as unknown as typeof fetch;
+  return { fetchImpl, calls };
+}
+
+const claimed = async (): Promise<ClaimPreview> => ({ state: 'claimed', summary: null });
+async function doctor(cwd: string, options: { url?: string; claimPreview?: () => Promise<ClaimPreview>; net?: ReturnType<typeof network>; config?: Partial<Config> } = {}) {
+  const net = options.net ?? network();
+  const state = await collectGuideState(cwd);
+  return runDoctorChecks(cwd, state, config(options.config), { url: options.url ?? null, fetchImpl: net.fetchImpl, claimPreview: options.claimPreview ?? claimed });
+}
+const problems = (findings: DoctorFinding[]) => findings.filter((f) => f.status === 'problem').map((f) => f.text);
+
+describe('doctor', () => {
+  it('finds no problem in a project set up the way setup leaves it', async () => {
+    const findings = await doctor(project());
+    expect(problems(findings)).toEqual([]);
+    expect(findings.map((f) => f.text)).toContain('The read-only rules credential works: the published app can fetch rule updates and report attacks');
+    expect(renderDoctor(findings).join('\n')).toContain('No problems found.');
+  });
+
+  it('says what to run when the project is not on Patchstack', async () => {
+    const cwd = project();
+    rmSync(join(cwd, '.patchstackrc.json'));
+    expect(await doctor(cwd, { config: { siteUuid: null } as never })).toEqual([
+      { status: 'problem', text: 'This project is not on Patchstack yet', fix: ['Run: npx @patchstack/connect setup'] },
+    ]);
+  });
+
+  it('flags a site with no owner as report-only, with the link to connect it', async () => {
+    const cwd = project();
+    writeFileSync(join(cwd, '.patchstackrc.json'), JSON.stringify({ siteUuid: UUID, widget: false }));
+    const findings = await doctor(cwd, { claimPreview: async () => ({ state: 'unclaimed', summary: null }) });
+    const finding = findings.find((f) => f.text.startsWith('Not connected'));
+    expect(finding?.status).toBe('problem');
+    expect(finding?.fix?.[0]).toContain(`claim?site=${UUID}`);
+    expect(findings.filter((f) => /connected/i.test(f.text))).toHaveLength(1);
+  });
+
+  it('flags a rules file without the read-only credential, and one Patchstack refuses', async () => {
+    expect(problems(await doctor(project({ build_id: 'b'.repeat(64) })))).toEqual([
+      "The guard's rules file has no read-only rules credential, so the published app cannot fetch rule updates or report attacks without the site key",
+    ]);
+    expect(problems(await doctor(project(), { net: network({ token: 401 }) }))).toEqual([
+      'Patchstack refused the read-only rules credential (the site key was replaced, or the site was removed)',
+    ]);
+    const offline = await doctor(project(), { net: network({ token: 'down' }) });
+    expect(problems(offline)).toEqual([]);
+    expect(offline.find((f) => f.status === 'unknown')?.text).toBe('Could not reach Patchstack to check the read-only rules credential');
+  });
+
+  it('flags a map that is not linked to the guard', async () => {
+    expect(problems(await doctor(project({ rules_reader: READER })))).toEqual([
+      "The app's map is not linked to the guard, so rules written for this app's own inputs can only report, not block",
+    ]);
+  });
+
+  it('flags a guard that is not wired', async () => {
+    const cwd = project();
+    writeFileSync(join(cwd, 'server.js'), "import http from 'node:http';\nhttp.createServer((req, res) => res.end('ok')).listen(3000);\n");
+    expect(problems(await doctor(cwd))).toEqual(['Blocking attacks needs a server']);
+  });
+
+  describe('with --url', () => {
+    it('passes a live app that carries the widget and blocks the test attack', async () => {
+      const cwd = project();
+      writeFileSync(join(cwd, '.patchstackrc.json'), JSON.stringify({ siteUuid: UUID, widget: true, claimed: true }));
+      const findings = await doctor(cwd, { url: 'https://app.example' });
+      expect(findings.filter((f) => f.text.startsWith('The live app')).map((f) => [f.status, f.text])).toEqual([
+        ['ok', 'The live app carries the Patchstack widget for this site'],
+        ['ok', "The live app's guard blocked a test attack"],
+      ]);
+    });
+
+    it('flags a live app that lets the test attack through', async () => {
+      const findings = await doctor(project(), { url: 'https://app.example', net: network({ attack: 200 }) });
+      expect(problems(findings)).toEqual(['The live app let a test attack through (it answered 200 to ?file=../../../../etc/passwd)']);
+    });
+
+    it('sends no test attack to a page that does not load', async () => {
+      const net = network({ page: 404 });
+      const findings = await doctor(project(), { url: 'https://app.example', net });
+      expect(findings.find((f) => f.text.startsWith('The live app'))?.status).toBe('unknown');
+      expect(net.calls.some((url) => url.includes('file='))).toBe(false);
+    });
+  });
+
+  it('ends by telling whoever runs it to fix each problem and run it again', () => {
+    const lines = renderDoctor([{ status: 'problem', text: 'x', fix: ['Run: a', 'Then: b'] }], { url: 'https://app.example' }).join('\n');
+    expect(lines).toContain('  ✗ x\n      Fix: Run: a\n           Then: b');
+    expect(lines).toContain('1 problem to fix in the project. Fix each ✗ above as its Fix line says, then run npx @patchstack/connect doctor again until none is left.');
+  });
+
+  it('keeps the owner\'s steps apart from what the project needs, so an assistant does not wait on them', () => {
+    const lines = renderDoctor([{ status: 'problem', text: 'Not connected', fix: ['Open the link'], owner: true }]).join('\n');
+    expect(lines).toContain('✗ Not connected (for the app owner)');
+    expect(lines).not.toContain('to fix in the project');
+    expect(lines).toContain('1 step for the app owner');
+  });
+});

From 7696f1e204f77c7186d91fa662d819f81e26482f Mon Sep 17 00:00:00 2001
From: Mario Tarosso <mariojgt2@gmail.com>
Date: Mon, 26 Oct 2026 11:44:16 +0000
Subject: [PATCH 2/2] doctor: say whether the published app fetches its rules

doctor now reads Patchstack's record of the app's rules fetches from
monitor/pulse/sync-status/<uuid>, with the token from the credential it
already checks (the site key when this machine holds one, otherwise the
read-only credential). It says when the published app last fetched its
rules and how many, and never fetches rules itself, which would be
recorded as a fetch and fake the signal.

An app with no visitors does not fetch, so an old or missing fetch is a
question until doctor --url has just visited the app, and a problem
after. A fetch only on the site key is reported as such, not as the
published app. A server without the endpoint is reported as not
reporting syncing yet.

AGENT-INSTALL.md discloses the extra token request and the read.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 AGENT-INSTALL.md     |   2 +-
 src/cli.ts           |  10 +--
 src/client.ts        |   7 +++
 src/doctor.ts        | 145 ++++++++++++++++++++++++++++++++++++-------
 tests/doctor.test.ts |  54 ++++++++++++++--
 5 files changed, 185 insertions(+), 33 deletions(-)

diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md
index 990371c..020c28e 100644
--- a/AGENT-INSTALL.md
+++ b/AGENT-INSTALL.md
@@ -86,7 +86,7 @@ Every command at a glance — what it does, whether it reads your source, what i
 | `guide` | Print this project's setup status: what is left to do and the four steps, with tailored commands. `--full` adds this reference. | Reads local protection wiring for verification | Nothing | Nothing |
 | `status` | Re-print the site UUID + dashboard URL and check whether the site still exists (active / removed / could not verify) and whether it is connected to an account. | No | The connected note in `.patchstackrc.json`, when it changed | Site-existence and connection checks |
 | `next` | Say where the project stands and the one thing to do now: connect the account (with the link), or go live (with the same steps `go-live` prints, or asking where the app is hosted when the project does not say). Answers the "done" the summary ends on. | Reads the project files `guide` and `go-live` read | The connected note in `.patchstackrc.json`, when it changed | The site UUID, to the public claim page that says whether it is connected (skipped once `.patchstackrc.json` records that it is) |
-| `doctor [--url <live app>]` | Check that everything Patchstack needs works, and print each problem with its fix: the install, the site, the account, the guard's wiring, its rules file, the read-only rules credential, the map link and the build steps. A problem only the app's owner can fix (connecting the account, publishing) is marked as theirs. Exits 1 when it finds a problem. | Reads the project files `guide` and `protect --check` read | Nothing | The site UUID, to the public claim page that says whether it is connected (skipped once `.patchstackrc.json` records that it is); the read-only rules credential from the guard's rules file, once, to `monitor/pulse/token`, to check Patchstack still accepts it (the token it returns is not kept or used); with `--url`, two GET requests to that address: its page, and the same page with a test attack in a `file` parameter |
+| `doctor [--url <live app>]` | Check that everything Patchstack needs works, and print each problem with its fix: the install, the site, the account, the guard's wiring, its rules file, the read-only rules credential, the map link, the build steps, and whether the published app fetches its rules. A problem only the app's owner can fix (connecting the account, publishing) is marked as theirs. Exits 1 when it finds a problem. | Reads the project files `guide` and `protect --check` read | Nothing | The site UUID, to the public claim page that says whether it is connected (skipped once `.patchstackrc.json` records that it is); the read-only rules credential from the guard's rules file, and the site key when this machine holds one, each once to `monitor/pulse/token`, to check Patchstack accepts them; one GET with that token to `monitor/pulse/sync-status/<your site uuid>`, which answers only when the published app (read-only credential) and a key-holding copy last fetched rules, and how many (doctor never fetches rules itself, which would be recorded as a fetch); with `--url`, two GET requests to that address: its page, and the same page with a test attack in a `file` parameter, which another firewall in front of the app may also flag |
 | `vulns` | Show what Patchstack found in this project's packages: vulnerabilities by severity and outdated packages, as counts, with the link that shows the details. Package names are shown in the dashboard once the site is connected. | No | Nothing | The site UUID, to the public claim page that returns the counts |
 | `go-live [--host <name>]` | Show how to add the project's API key to its host and deploy, in three steps. The host is read from project files (`vercel.json`, `netlify.toml`, `wrangler.toml`, `fly.toml`, `render.yaml`, `railway.json`, `amplify.yml`, `Procfile`, `.replit`, a Lovable project's packages) or named with `--host`. The commands it prints read the key from `.patchstackrc.local.json` as they run; it never prints the key. | Reads those project files only | Nothing | Nothing |
 | `widget [--remove]` | Add the Patchstack Connector widget tag to the root page (in a workspace repo, the app package's root page), or take the tag Connect added out with `--remove` (a tag added by hand is left alone). Saves the choice as `"widget"` in `.patchstackrc.json`, which `scan` and `mark-build` follow; `setup --widget` saves the same choice. | Reads the root page to find where the tag goes | `.patchstackrc.json`; the widget `<script>` tag in the root HTML shell or framework root | Nothing |
diff --git a/src/cli.ts b/src/cli.ts
index e93c083..f16b507 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -198,10 +198,12 @@ Usage:
                                                      project, and say how to fix each problem: install,
                                                      site, account, protection wiring, the guard's rules
                                                      file and its read-only credential, the map link and
-                                                     the build steps. Sends the site UUID to the public
-                                                     claim page and asks Patchstack whether it accepts the
-                                                     read-only credential; with --url, also requests the
-                                                     live app's page and one test attack. Writes nothing.
+                                                     the build steps, and whether the published app
+                                                     fetches its rules. Sends the site UUID to the public
+                                                     claim page, asks Patchstack whether it accepts the
+                                                     credentials and when the app last fetched rules;
+                                                     with --url, also requests the live app's page and
+                                                     one test attack. Writes nothing.
                                                      Exits 1 when it finds a problem
   patchstack-connect vulns                           Show what Patchstack found in this project's
                                                      packages: vulnerabilities by severity and
diff --git a/src/client.ts b/src/client.ts
index e215281..c5c6a2b 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -129,6 +129,13 @@ export function authFailureMessage(status: number, config: Config): string | nul
 }
 
 /** Build the live Patchstack for JavaScript rules URL corresponding to a manifest endpoint override. */
+/** Where a site's own credential reads when its app last fetched rules, beside the rules endpoint. */
+export function buildSyncStatusUrl(manifestEndpoint: string, siteUuid: string): string {
+  const url = new URL(buildRulesUrl(manifestEndpoint, siteUuid));
+  url.pathname = url.pathname.replace(/\/rules\/([^/]+)$/, '/sync-status/$1');
+  return url.toString();
+}
+
 export function buildRulesUrl(manifestEndpoint: string, siteUuid: string): string {
   const url = new URL(manifestEndpoint);
   const path = url.pathname.replace(/\/$/, '');
diff --git a/src/doctor.ts b/src/doctor.ts
index 91b2757..4e09b29 100644
--- a/src/doctor.ts
+++ b/src/doctor.ts
@@ -9,7 +9,7 @@ import { readFileSync } from 'node:fs';
 
 import { readBuildStamp } from './build-id.js';
 import { findRulesFile, ruleBundleOf } from './build-stamp.js';
-import { buildClaimUrl, type ClaimPreview } from './client.js';
+import { buildClaimUrl, buildSyncStatusUrl, type ClaimPreview } from './client.js';
 import { assertConnectableEndpoint } from './endpoint-policy.js';
 import { DEV_ONLY_INSTALL, guideMissing, needsSourceProductionMarker, type GuideState } from './guide.js';
 import { buildTokenUrl, parsePulseAuth } from './pulse-token.js';
@@ -34,16 +34,22 @@ export interface DoctorOptions {
   fetchImpl?: typeof fetch;
   /** Whether the site has an owner, from the public claim page. */
   claimPreview: (config: Config) => Promise<ClaimPreview>;
+  /** How long to give the live app to finish the rules check its visit started, before reading sync status. */
+  settleMs?: number;
 }
 
 const READER = /^rr_[0-9a-f]{48}-\d+$/;
 const PROBE = '../../../../etc/passwd';
 const LIVE_TIMEOUT_MS = 10_000;
+/** A published app re-checks its rules every few minutes while it has visitors; older than this is worth a look. */
+const SYNC_STALE_MS = 2 * 60 * 60 * 1000;
 
-/** Ask Patchstack whether it accepts a credential, without keeping the token it hands back. */
-async function credentialAccepted(config: Config, credential: string, fetchImpl: typeof fetch): Promise<'accepted' | 'refused' | 'unreachable'> {
+type Exchange = { verdict: 'accepted' | 'refused' | 'unreachable'; token: string | null };
+
+/** Ask Patchstack whether it accepts a credential. The token is used only for the sync-status read below. */
+async function exchangeCredential(config: Config, credential: string, fetchImpl: typeof fetch): Promise<Exchange> {
   const parsed = parsePulseAuth(credential);
-  if (parsed === null) return 'refused';
+  if (parsed === null) return { verdict: 'refused', token: null };
   try {
     const url = buildTokenUrl(config.endpoint);
     assertConnectableEndpoint(config, url);
@@ -54,31 +60,34 @@ async function credentialAccepted(config: Config, credential: string, fetchImpl:
       signal: AbortSignal.timeout(config.timeoutMs),
     });
 
-    return response.ok ? 'accepted' : response.status === 401 || response.status === 403 ? 'refused' : 'unreachable';
+    if (!response.ok) return { verdict: response.status === 401 || response.status === 403 ? 'refused' : 'unreachable', token: null };
+    const token = ((await response.json().catch(() => null)) as { access_token?: unknown } | null)?.access_token;
+
+    return { verdict: 'accepted', token: typeof token === 'string' && token !== '' ? token : null };
   } catch {
-    return 'unreachable';
+    return { verdict: 'unreachable', token: null };
   }
 }
 
 /** The guard's rules file: where it is, the read-only credential in it, and whether the map is linked. */
-async function rulesFileFindings(cwd: string, config: Config, fetchImpl: typeof fetch): Promise<DoctorFinding[]> {
+async function rulesFileFindings(cwd: string, config: Config, fetchImpl: typeof fetch): Promise<{ findings: DoctorFinding[]; token: string | null }> {
   const location = findRulesFile(cwd);
   if (location.kind === 'none') {
-    return [{
+    return { token: null, findings: [{
       status: 'problem',
       text: "Patchstack cannot find the guard's rules file, so setup cannot keep its rules current",
       fix: ['Run: npx @patchstack/connect protect', 'Then: npx @patchstack/connect setup'],
-    }];
+    }] };
   }
   if (location.kind === 'unreadable') {
-    return [{
+    return { token: null, findings: [{
       status: 'problem',
       text: `The guard's rules file is not valid JSON (${location.paths.join(', ')})`,
       fix: ['Restore it from version control, or delete it and run: npx @patchstack/connect protect', 'Then: npx @patchstack/connect setup'],
-    }];
+    }] };
   }
   if (location.kind === 'ambiguous') {
-    return [{
+    return { token: null, findings: [{
       status: 'problem',
       text: `Two Patchstack guards are installed, each with its own rules file (${location.paths.join(', ')})`,
       fix: [
@@ -86,7 +95,7 @@ async function rulesFileFindings(cwd: string, config: Config, fetchImpl: typeof
         'Remove the other guard and its rules file, after checking nothing in the app imports that guard.',
         'Then: npx @patchstack/connect setup',
       ],
-    }];
+    }] };
   }
 
   let bundle: Record<string, unknown> | null = null;
@@ -96,6 +105,7 @@ async function rulesFileFindings(cwd: string, config: Config, fetchImpl: typeof
     // Read as missing below.
   }
   const findings: DoctorFinding[] = [];
+  let token: string | null = null;
   const reader = (bundle?._patchstack as { rules_reader?: unknown } | undefined)?.rules_reader;
   if (typeof reader !== 'string' || !READER.test(reader)) {
     findings.push({
@@ -104,7 +114,8 @@ async function rulesFileFindings(cwd: string, config: Config, fetchImpl: typeof
       fix: ['Run: npx @patchstack/connect setup (it writes the credential; it needs the site key on this machine)', 'Then publish the app again.'],
     });
   } else {
-    const verdict = await credentialAccepted(config, reader, fetchImpl);
+    const { verdict, token: readerToken } = await exchangeCredential(config, reader, fetchImpl);
+    token = readerToken;
     findings.push(
       verdict === 'accepted'
         ? { status: 'ok', text: 'The read-only rules credential works: the published app can fetch rule updates and report attacks' }
@@ -127,17 +138,87 @@ async function rulesFileFindings(cwd: string, config: Config, fetchImpl: typeof
     findings.push({ status: 'ok', text: "The app's map is linked to the guard" });
   }
 
-  return findings;
+  return { findings, token };
+}
+
+/** "3 minutes ago", "5 hours ago", "2 days ago". */
+function ago(at: number, now: number): string {
+  const minutes = Math.max(0, Math.round((now - at) / 60_000));
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+  const days = Math.round(hours / 24);
+  return `${days} day${days === 1 ? '' : 's'} ago`;
+}
+
+type Fetch = { at: string; rule_count: number | null } | null;
+
+/**
+ * Whether the published app fetches its rules, from Patchstack's own record of rules fetches.
+ *
+ * The published app fetches on the read-only credential; a copy holding the site key (the workspace, or a
+ * deployment that sets PATCHSTACK_API_KEY) on the key. doctor reads the record and never fetches rules
+ * itself, which would be recorded as a fetch. An app with no visitors does not fetch, so an old fetch is
+ * only a problem once `visited` says doctor has just sent the live app a request.
+ */
+async function syncFindings(config: Config, token: string, visited: boolean, fetchImpl: typeof fetch): Promise<DoctorFinding[]> {
+  let body: { rules_fetches?: { reader?: Fetch; site_key?: Fetch } };
+  try {
+    const url = buildSyncStatusUrl(config.endpoint, config.siteUuid as string);
+    assertConnectableEndpoint(config, url);
+    const response = await fetchImpl(url, {
+      headers: { Accept: 'application/json', Authorization: `Bearer ${token}`, ...connectHeaders() },
+      signal: AbortSignal.timeout(config.timeoutMs),
+    });
+    if (response.status === 404) return [{ status: 'unknown', text: 'Patchstack does not report rules syncing for this site yet' }];
+    if (!response.ok) return [{ status: 'unknown', text: 'Could not get the rules sync status from Patchstack' }];
+    body = (await response.json()) as typeof body;
+  } catch {
+    return [{ status: 'unknown', text: 'Could not reach Patchstack to check whether the published app fetches its rules' }];
+  }
+
+  const now = Date.now();
+  const reader = body.rules_fetches?.reader ?? null;
+  const key = body.rules_fetches?.site_key ?? null;
+  const at = (fetch: Fetch) => (fetch === null ? NaN : Date.parse(fetch.at));
+  const count = (fetch: Fetch) => (fetch?.rule_count == null ? '' : ` (${fetch.rule_count} rule${fetch.rule_count === 1 ? '' : 's'})`);
+  const visit = 'Run: npx @patchstack/connect doctor --url <your live app> (it visits the app, which makes it check its rules), then look again.';
+
+  if (reader !== null && now - at(reader) <= SYNC_STALE_MS) {
+    return [{ status: 'ok', text: `The published app fetched its rules from Patchstack ${ago(at(reader), now)}${count(reader)}` }];
+  }
+  const notSyncing = [
+    'Publish the app again on the latest @patchstack/connect.',
+    'Check the guard is wired: npx @patchstack/connect protect --check',
+    'Then: npx @patchstack/connect doctor --url <your live app>',
+  ];
+  if (reader !== null) {
+    const text = `The published app last fetched its rules from Patchstack ${ago(at(reader), now)}${count(reader)}`;
+    return [visited
+      ? { status: 'problem', text: `${text}, and did not fetch them when doctor just visited it`, fix: notSyncing }
+      : { status: 'unknown', text: `${text}. An app with no visitors does not fetch`, fix: [visit] }];
+  }
+  if (key !== null) {
+    return [{
+      status: 'unknown',
+      text: `Only a copy holding the site key has fetched rules (${ago(at(key), now)}): a published app that sets PATCHSTACK_API_KEY fetches that way; otherwise the published app has never fetched them`,
+      fix: visited ? notSyncing : [visit],
+    }];
+  }
+
+  return [visited
+    ? { status: 'problem', text: 'The published app has never fetched its rules from Patchstack, even when doctor just visited it', fix: notSyncing }
+    : { status: 'unknown', text: 'The published app has never fetched its rules from Patchstack', fix: ['If the app is published, ' + visit.charAt(0).toLowerCase() + visit.slice(1), 'If it is not published yet, publish it.'] }];
 }
 
 /** The live app: whether it carries the widget and whether its guard stops a test attack. */
-async function liveFindings(url: string, state: GuideState, fetchImpl: typeof fetch): Promise<DoctorFinding[]> {
+async function liveFindings(url: string, state: GuideState, fetchImpl: typeof fetch): Promise<{ findings: DoctorFinding[]; reached: boolean }> {
   let page: URL;
   try {
     page = new URL(url);
     if (page.protocol !== 'https:' && page.protocol !== 'http:') throw new Error('not http');
   } catch {
-    return [{ status: 'unknown', text: `${url} is not a web address; pass the live app's address, e.g. --url https://your-app.example` }];
+    return { reached: false, findings: [{ status: 'unknown', text: `${url} is not a web address; pass the live app's address, e.g. --url https://your-app.example` }] };
   }
 
   const findings: DoctorFinding[] = [];
@@ -146,7 +227,7 @@ async function liveFindings(url: string, state: GuideState, fetchImpl: typeof fe
     const html = await response.text();
     // A page that does not load says nothing about the guard either, so the test attack is not sent.
     if (!response.ok) {
-      return [{ status: 'unknown', text: `The live app answered ${response.status}, so it could not be checked (is it published? a private publish shows a sign-in page)` }];
+      return { reached: false, findings: [{ status: 'unknown', text: `The live app answered ${response.status}, so it could not be checked (is it published? a private publish shows a sign-in page)` }] };
     }
     if (!state.widgetOptOut && state.siteUuid !== null) {
       findings.push(
@@ -156,7 +237,7 @@ async function liveFindings(url: string, state: GuideState, fetchImpl: typeof fe
       );
     }
   } catch {
-    return [{ status: 'unknown', text: `Could not reach ${page.origin}` }];
+    return { reached: false, findings: [{ status: 'unknown', text: `Could not reach ${page.origin}` }] };
   }
 
   const probe = new URL(page);
@@ -181,7 +262,7 @@ async function liveFindings(url: string, state: GuideState, fetchImpl: typeof fe
     findings.push({ status: 'unknown', text: `Could not reach ${page.origin} for the test attack` });
   }
 
-  return findings;
+  return { findings, reached: true };
 }
 
 /**
@@ -237,8 +318,28 @@ export async function runDoctorChecks(cwd: string, state: GuideState, config: Co
     findings.push({ status: 'ok', text: 'Your pages carry the marker that tells Patchstack when the app is live' });
   }
 
-  if (state.protectionApplicable && state.protectionWired) findings.push(...await rulesFileFindings(cwd, config, fetchImpl));
-  if (options.url) findings.push(...await liveFindings(options.url, state, fetchImpl));
+  let readerToken: string | null = null;
+  if (state.protectionApplicable && state.protectionWired) {
+    const rules = await rulesFileFindings(cwd, config, fetchImpl);
+    findings.push(...rules.findings);
+    readerToken = rules.token;
+  }
+  let visited = false;
+  if (options.url) {
+    const live = await liveFindings(options.url, state, fetchImpl);
+    findings.push(...live.findings);
+    visited = live.reached;
+  }
+  if (state.protectionApplicable && state.protectionWired) {
+    // The site key on this machine when there is one, otherwise the read-only credential checked above.
+    const key = config.pulseAuth ?? config.apiKey;
+    const token = typeof key === 'string' && key !== '' ? (await exchangeCredential(config, key, fetchImpl)).token ?? readerToken : readerToken;
+    if (token !== null) {
+      // A visit can start the app's rules check in the background; give it a moment to be recorded.
+      if (visited) await new Promise((resolve) => setTimeout(resolve, options.settleMs ?? 3_000));
+      findings.push(...await syncFindings(config, token, visited, fetchImpl));
+    }
+  }
 
   // Problems first, in the order found, then what could not be checked, then what passed.
   const rank: Record<DoctorStatus, number> = { problem: 0, unknown: 1, ok: 2 };
diff --git a/tests/doctor.test.ts b/tests/doctor.test.ts
index 985fcd6..dfb972b 100644
--- a/tests/doctor.test.ts
+++ b/tests/doctor.test.ts
@@ -50,27 +50,35 @@ function project(patchstack: Record<string, unknown> | null = { rules_reader: RE
   return cwd;
 }
 
-/** Patchstack's token endpoint answering `status`, and a live app answering the page and the test attack. */
-function network({ token = 200, page = 200, attack = 403 }: { token?: number | 'down'; page?: number; attack?: number } = {}) {
+const minutesAgo = (minutes: number) => new Date(Date.now() - minutes * 60_000).toISOString();
+type SyncAnswer = { reader?: { at: string; rule_count: number } | null; site_key?: { at: string; rule_count: number } | null } | number;
+
+/** Patchstack's token and sync-status endpoints, and a live app answering the page and the test attack. */
+function network({ token = 200, page = 200, attack = 403, sync = { reader: { at: minutesAgo(3), rule_count: 17 }, site_key: null } }: { token?: number | 'down'; page?: number; attack?: number; sync?: SyncAnswer } = {}) {
   const calls: string[] = [];
-  const fetchImpl = vi.fn(async (input: string | URL) => {
+  const auth: string[] = [];
+  const fetchImpl = vi.fn(async (input: string | URL, init: RequestInit = {}) => {
     const url = String(input);
     calls.push(url);
     if (url.endsWith('/token')) {
       if (token === 'down') throw new Error('offline');
-      return new Response('{}', { status: token });
+      return new Response(token === 200 ? '{"access_token":"reader-token","expires_in":3600}' : '{}', { status: token });
+    }
+    if (url.includes('/sync-status/')) {
+      auth.push(String((init.headers as Record<string, string>)?.Authorization));
+      return typeof sync === 'number' ? new Response('{}', { status: sync }) : Response.json({ site_uuid: UUID, rules_fetches: { reader: null, site_key: null, ...sync } });
     }
     if (url.includes('file=')) return new Response(attack === 403 ? '{"error":"This request has been blocked by Patchstack."}' : '<html></html>', { status: attack });
     return new Response(`<html><script src="https://cdn.patchstack.com/patchstack-widget.js" data-site-uuid="${UUID}"></script></html>`, { status: page });
   }) as unknown as typeof fetch;
-  return { fetchImpl, calls };
+  return { fetchImpl, calls, auth };
 }
 
 const claimed = async (): Promise<ClaimPreview> => ({ state: 'claimed', summary: null });
 async function doctor(cwd: string, options: { url?: string; claimPreview?: () => Promise<ClaimPreview>; net?: ReturnType<typeof network>; config?: Partial<Config> } = {}) {
   const net = options.net ?? network();
   const state = await collectGuideState(cwd);
-  return runDoctorChecks(cwd, state, config(options.config), { url: options.url ?? null, fetchImpl: net.fetchImpl, claimPreview: options.claimPreview ?? claimed });
+  return runDoctorChecks(cwd, state, config(options.config), { url: options.url ?? null, fetchImpl: net.fetchImpl, claimPreview: options.claimPreview ?? claimed, settleMs: 0 });
 }
 const problems = (findings: DoctorFinding[]) => findings.filter((f) => f.status === 'problem').map((f) => f.text);
 
@@ -148,6 +156,40 @@ describe('doctor', () => {
     });
   });
 
+  describe('whether the published app fetches its rules', () => {
+    const syncText = (findings: DoctorFinding[]) => findings.find((f) => /fetched|never fetched|rules syncing/.test(f.text));
+
+    it('passes an app that fetched them recently, reading the record with the token and never fetching rules itself', async () => {
+      const net = network();
+      const finding = syncText(await doctor(project(), { net }));
+      expect(finding).toMatchObject({ status: 'ok', text: 'The published app fetched its rules from Patchstack 3 minutes ago (17 rules)' });
+      expect(net.auth).toEqual(['Bearer reader-token']);
+      expect(net.calls.some((url) => url.includes('/rules/'))).toBe(false);
+    });
+
+    it('treats an old fetch as a question until doctor has visited the app, then as a problem', async () => {
+      const stale = { reader: { at: minutesAgo(300), rule_count: 17 } };
+      expect(syncText(await doctor(project(), { net: network({ sync: stale }) }))?.status).toBe('unknown');
+      const visited = syncText(await doctor(project(), { url: 'https://app.example', net: network({ sync: stale }) }));
+      expect(visited).toMatchObject({ status: 'problem', text: 'The published app last fetched its rules from Patchstack 5 hours ago (17 rules), and did not fetch them when doctor just visited it' });
+    });
+
+    it('flags an app that has never fetched them once doctor has visited it', async () => {
+      const finding = syncText(await doctor(project(), { url: 'https://app.example', net: network({ sync: { reader: null } }) }));
+      expect(finding).toMatchObject({ status: 'problem', text: 'The published app has never fetched its rules from Patchstack, even when doctor just visited it' });
+    });
+
+    it('does not call a key-holding copy the published app', async () => {
+      const finding = syncText(await doctor(project(), { net: network({ sync: { reader: null, site_key: { at: minutesAgo(10), rule_count: 17 } } }) }));
+      expect(finding?.status).toBe('unknown');
+      expect(finding?.text).toContain('Only a copy holding the site key has fetched rules (10 minutes ago)');
+    });
+
+    it('says so when Patchstack does not report syncing yet', async () => {
+      expect(syncText(await doctor(project(), { net: network({ sync: 404 }) }))).toMatchObject({ status: 'unknown', text: 'Patchstack does not report rules syncing for this site yet' });
+    });
+  });
+
   it('ends by telling whoever runs it to fix each problem and run it again', () => {
     const lines = renderDoctor([{ status: 'problem', text: 'x', fix: ['Run: a', 'Then: b'] }], { url: 'https://app.example' }).join('\n');
     expect(lines).toContain('  ✗ x\n      Fix: Run: a\n           Then: b');