@canonry/canonry 7.62.0 → 7.63.0

package/dist/{chunk-2HNTNKFC.js → chunk-Q4U2GJME.js}

@@ -9,14 +9,14 @@ import {
   normalizeCloudflareWorkerEvent,
   sessionizeJourneyRequests,
   verifyRequestSignature
-} from "./chunk-SYQLUOR7.js";
+} from "./chunk-SG2OPR7J.js";
 import {
   currentOutcomeAttribution,
   getRequestContext,
   registerRequestContext,
   requestAuditIdentity,
   sanitizeRequestContext
-} from "./chunk-LAILXR2F.js";
+} from "./chunk-QNFX7ZCT.js";
 import {
   SentimentIdempotencyConflict,
   SentimentRepository,
@@ -154,7 +154,7 @@ import {
   userSessions,
   users,
   writeNegativeReviewMaxStars
-} from "./chunk-RGD5SDT3.js";
+} from "./chunk-HNZQVIPS.js";
 import {
   ADS_ACTIVATE_SCOPE,
   ADS_ACTIVATION_ABSOLUTE_MAX_ENTITIES,
@@ -258,6 +258,7 @@ import {
   GoogleMarketingProviders,
   GtmConnectionStates,
   GtmSnapshotKinds,
+  HEALTH_NO_LONGER_URGENT,
   InsightActionGroups,
   JOURNEY_LIST_VISITS_PER_VISITOR,
   JOURNEY_LOOKBACK_DAYS,
@@ -514,6 +515,7 @@ import {
   classifySkillFile,
   classifySurfaceFromCategory,
   classifyTrafficPath,
+  cloudflareQueuePullTrafficSourceConfigSchema,
   cloudflareTrafficSourceConfigSchema,
   cloudflareWorkerIngestRequestSchema,
   cloudflareWorkerIngestResponseSchema,
@@ -618,6 +620,7 @@ import {
   findDuplicateLocationLabels,
   forbidden,
   formatAiReferralClassSummary,
+  formatCalendarDay,
   formatCanonryPluginUpdateHint,
   formatCanonryPluginVersionMismatch,
   formatIsoDate,
@@ -739,6 +742,7 @@ import {
   isRetryableHttpError,
   isStrictSemver,
   isSweepProvider,
+  isTransientNetworkError,
   isVertexGroundingRedirect,
   isVisibilityCompareClassMetric,
   isoDateDaysBeforeInTimeZone,
@@ -1117,6 +1121,7 @@ import {
   trafficConnectCloudflareResponseSchema,
   trafficConnectVercelRequestSchema,
   trafficConnectWordpressRequestSchema,
+  trafficDeclareGapRequestSchema,
   trafficEventsResponseSchema,
   trafficResetRequestSchema,
   trafficSampleClassifierSchema,
@@ -1158,7 +1163,7 @@ import {
   wordpressSchemaDeployResultDtoSchema,
   wordpressSchemaStatusResultDtoSchema,
   wordpressStatusDtoSchema
-} from "./chunk-U6CNJC2Y.js";
+} from "./chunk-TKLE2Y6H.js";
 
 // ../api-routes/src/user-session.ts
 import crypto2 from "crypto";
@@ -8381,16 +8386,111 @@ import { z as z2 } from "zod";
 
 // ../api-routes/src/notifications/alert.ts
 import { z } from "zod";
+
+// ../api-routes/src/notifications/health-copy.ts
+var HEALTH_CHECK_LABELS = {
+  "db.file.present": "Database missing",
+  "config.file.present": "Config file missing",
+  "canonry.version.current": "Canonry update available",
+  "google.auth.connection": "Search Console sign-in",
+  "google.auth.property-access": "Search Console access",
+  "google.auth.redirect-uri": "Google sign-in setup",
+  "google.auth.scopes": "Search Console permissions",
+  "gbp.auth.connection": "Business Profile sign-in",
+  "gbp.auth.scopes": "Business Profile permissions",
+  "gbp.account.access": "Business Profile access",
+  "gbp.data.recent-sync": "Business Profile sync stalled",
+  "gbp.places.api-key": "Places API key",
+  "gbp.reviews.access": "Review alerts limited",
+  "gbp.reviews.delivery": "Review alert not delivered",
+  "bing.auth.connection": "Bing sign-in",
+  "bing.auth.site-access": "Bing site access",
+  "wordpress.publish.connection": "WordPress publishing",
+  "ga.auth.connection": "GA4 sign-in",
+  "ga.data.recent-data": "GA4 data stopped",
+  "gsc.data.recent-data": "Search Console data stopped",
+  "report.sweeps": "Monthly report sweeps",
+  "report.models": "Monthly report models",
+  "report.daily-data": "Monthly report data gaps",
+  "report.ai-referral-bursts": "AI referral spikes",
+  "ads.auth.connection": "OpenAI ads sign-in",
+  "ads.data.recent-sync": "OpenAI ads sync stalled",
+  "google-ads.auth.connection": "Google Ads sign-in",
+  "google-ads.auth.scopes": "Google Ads permissions",
+  "google-ads.account.context": "Google Ads account",
+  "google-ads.data.recent-snapshot": "Google Ads data stale",
+  "gtm.auth.connection": "Tag Manager sign-in",
+  "gtm.auth.scopes": "Tag Manager permissions",
+  "gtm.container.context": "Tag Manager container",
+  "gtm.data.recent-snapshot": "Tag Manager data stale",
+  "gtm.runtime.firing": "Tags not firing",
+  "google-ads.sync.recent-failures": "Google Ads sync failing",
+  "gtm.sync.recent-failures": "Tag Manager sync failing",
+  "gbp.sync.recent-failures": "Business Profile sync failing",
+  "ga.sync.recent-failures": "GA4 sync failing",
+  "gsc.sync.recent-failures": "Search Console sync failing",
+  "config.providers": "AI provider keys",
+  "config.agent-providers": "Agent provider keys",
+  "traffic.source.connected": "Traffic sync failing",
+  "traffic.source.recent-data": "Traffic data stopped",
+  "traffic.source.sync-lag": "Traffic sync behind",
+  "traffic.source.queue-backlog": "Traffic backlog",
+  "traffic.source.worker-version": "Cloudflare worker out of date",
+  "traffic.source.credentials": "Traffic source sign-in",
+  "traffic.source.scopes": "Traffic source permissions",
+  "traffic.source.cache-blindspot": "Traffic hidden by cache",
+  "backlinks.source.connected": "Backlinks source",
+  "content.winnability.coverage": "Content analysis incomplete",
+  "agent.skills.installed": "Agent skills missing",
+  "agent.skills.current": "Agent skills outdated",
+  "agent.skills.trigger-surface": "Agent skill setup",
+  "gsc.api.reachable": "Can't reach Search Console",
+  "ga.api.reachable": "Can't reach GA4",
+  "gbp.api.reachable": "Can't reach Business Profile",
+  "google-ads.api.reachable": "Can't reach Google Ads",
+  "gtm.api.reachable": "Can't reach Tag Manager",
+  "bing.api.reachable": "Can't reach Bing",
+  "ads.api.reachable": "Can't reach OpenAI ads",
+  "site.reachability": "Website down"
+};
+var HEALTH_FIXED_LINES = {
+  "google.auth.refresh-unreachable": "Google is reachable again.",
+  "ga.auth.refresh-unreachable": "Google is reachable again.",
+  "gbp.auth.refresh-unreachable": "Google is reachable again.",
+  "traffic.sync-lag.unrecovered-skip": "The traffic gap is closed.",
+  "traffic.source.all-errored-recently": "Traffic syncs are working again.",
+  "traffic.queue-backlog.remaining": "The traffic backlog is cleared.",
+  "traffic.worker-version.stale": "The Cloudflare worker is up to date.",
+  "gbp.auth.no-connection": "Business Profile is connected."
+};
+function firstSentence(text, max2 = 180) {
+  if (!text) return null;
+  const end = text.search(/[.!?](?:\s|$)/u);
+  const sentence = (end === -1 ? text : text.slice(0, end + 1)).trim();
+  if (!sentence) return null;
+  return sentence.length <= max2 ? sentence : `${sentence.slice(0, max2 - 1)}\u2026`;
+}
+var HEALTH_NO_SIGNAL_CODE = "health.no-signal";
+function plainHealthCopy(check, remediation) {
+  if (check.alert) return check.alert;
+  if (check.code === HEALTH_NO_SIGNAL_CODE) {
+    return { label: "Health unknown", line: "No health check produced a result, so health is unknown, not confirmed.", next: null };
+  }
+  return {
+    label: HEALTH_CHECK_LABELS[check.id] ?? "Health check failing",
+    line: firstSentence(check.summary) ?? check.summary,
+    next: firstSentence(remediation)
+  };
+}
+
+// ../api-routes/src/notifications/alert.ts
 var alertSeveritySchema = z.enum(["critical", "warning", "success", "info"]);
 var AlertSeverities = alertSeveritySchema.enum;
 var AlertFieldLabels = {
-  status: "Status",
-  check: "Check",
-  previously: "Was",
   remediation: "What to do",
-  newlyFailing: "New",
-  cleared: "Cleared",
-  alsoFailing: "Also failing",
+  next: "Next",
+  alsoOpen: "Also open",
+  fixed: "Fixed",
   event: "Event",
   run: "Run",
   changes: "Changes",
@@ -8401,6 +8501,7 @@ var AlertFieldLabels = {
   replied: "Replied",
   source: "Source"
 };
+var CANONRY_ALERT_CATEGORY = "\u{1F4C8} Canonry";
 var HEALTH_EVENTS = /* @__PURE__ */ new Set([
   "health.degraded",
   "health.recovered",
@@ -8418,58 +8519,86 @@ function bulletList(lines) {
   return omitted > 0 ? `${body}
 \u2022 \u2026and ${omitted} more` : body;
 }
+var MAX_ALSO_OPEN = 3;
+function fixedLines(cleared) {
+  const named = [...new Set(cleared.map((code) => HEALTH_FIXED_LINES[code]).filter((line) => line !== void 0))];
+  const unnamed = cleared.filter((code) => HEALTH_FIXED_LINES[code] === void 0).length;
+  if (unnamed === 0) return named;
+  return [...named, `${unnamed} ${named.length > 0 ? "other " : ""}problem${unnamed === 1 ? "" : "s"} fixed.`];
+}
+function labelList(labels) {
+  const counts2 = /* @__PURE__ */ new Map();
+  for (const label of labels) counts2.set(label, (counts2.get(label) ?? 0) + 1);
+  const entries = [...counts2].map(([label, count10]) => count10 > 1 ? `${label} (${count10})` : label);
+  const shown = entries.slice(0, MAX_ALSO_OPEN);
+  const more = entries.length - shown.length;
+  return [...shown.map((entry) => `\u2022 ${entry}`), ...more > 0 ? [`\u2022 and ${more} more`] : []].join("\n");
+}
 function healthView(payload) {
   const { health, project } = payload;
   const urgentEvent = payload.event === "health.urgent" || payload.event === "health.urgent-resolved";
   const recovered = payload.event === "health.recovered" || payload.event === "health.urgent-resolved";
-  const severity = recovered ? AlertSeverities.success : urgentEvent || health.status === "fail" ? AlertSeverities.critical : AlertSeverities.warning;
-  const fields = [
-    {
-      label: AlertFieldLabels.status,
-      value: recovered ? urgentEvent ? "resolved" : "recovered" : urgentEvent ? "urgent" : health.status,
-      compact: true
-    },
-    { label: AlertFieldLabels.check, value: health.code, compact: true }
-  ];
-  if (health.previousStatus) {
-    fields.push({ label: AlertFieldLabels.previously, value: health.previousStatus, compact: true });
-  }
-  if (health.remediation) {
-    fields.push({ label: AlertFieldLabels.remediation, value: health.remediation });
+  const website = health.code.startsWith("site.reachability.");
+  const base = {
+    category: CANONRY_ALERT_CATEGORY,
+    url: payload.dashboardUrl,
+    footer: project.canonicalDomain,
+    timestamp: health.checkedAt
+  };
+  if (recovered) {
+    const fixed2 = fixedLines(health.cleared ?? []);
+    if (website) {
+      return { ...base, severity: AlertSeverities.success, title: `${project.name}: Website is back up`, body: "The website answers again.", fields: [] };
+    }
+    if (urgentEvent) {
+      const eased = health.summary.startsWith(HEALTH_NO_LONGER_URGENT);
+      const several = (health.cleared?.length ?? 0) > 1;
+      return {
+        ...base,
+        severity: AlertSeverities.success,
+        title: `${project.name}: ${eased || several ? "No longer urgent" : "Urgent problem fixed"}`,
+        body: firstSentence(eased ? health.summary.slice(HEALTH_NO_LONGER_URGENT.length) : health.summary) ?? "The urgent problem is resolved.",
+        fields: []
+      };
+    }
+    return {
+      ...base,
+      severity: AlertSeverities.success,
+      title: `${project.name}: Back to normal`,
+      body: fixed2.length > 0 ? fixed2.join(" ") : "Every check passes again.",
+      fields: []
+    };
   }
+  const failing = health.failing;
   const added = health.added ?? [];
-  if (added.length > 0) {
-    const statusOf = /* @__PURE__ */ new Map();
-    for (const check of health.failing) if (!statusOf.has(check.code)) statusOf.set(check.code, check.status);
-    fields.push({
-      label: `${AlertFieldLabels.newlyFailing} (${added.length})`,
-      value: bulletList(added.map((code) => `${statusOf.get(code) ?? health.status}: ${code}`))
-    });
-  }
-  const cleared = health.cleared ?? [];
-  if (cleared.length > 0) {
-    fields.push({
-      label: `${AlertFieldLabels.cleared} (${cleared.length})`,
-      value: bulletList(cleared)
-    });
-  }
-  const newlyFailing = new Set(added);
-  const others = health.failing.filter((check) => check.code !== health.code && !newlyFailing.has(check.code));
+  const newest = added.map((code) => failing.find((check) => check.code === code)).find((check) => check !== void 0);
+  const lead = newest ?? failing.find((check) => check.code === health.code) ?? failing.at(0);
+  const copy = lead ? lead.code === health.code ? plainHealthCopy({ ...lead, summary: health.summary }, lead.remediation ?? health.remediation) : plainHealthCopy(lead, lead.remediation ?? null) : plainHealthCopy({ id: "", status: health.status, code: health.code, summary: health.summary }, health.remediation);
+  const leadStatus = lead?.status ?? health.status;
+  const severity = urgentEvent || leadStatus === "fail" ? AlertSeverities.critical : AlertSeverities.warning;
+  const fields = [];
+  if (copy.next) fields.push({ label: AlertFieldLabels.next, value: copy.next });
+  const others = failing.filter((check) => check !== lead);
+  const otherNew = others.filter((check) => added.includes(check.code));
+  const standing = others.filter((check) => !added.includes(check.code));
   if (others.length > 0) {
     fields.push({
-      label: `${AlertFieldLabels.alsoFailing} (${others.length})`,
-      value: bulletList(others.map((check) => `${check.status} \u2014 ${check.code}`))
+      label: AlertFieldLabels.alsoOpen,
+      value: labelList([
+        ...otherNew.map((check) => `${plainHealthCopy(check, null).label} (new)`),
+        ...standing.map((check) => plainHealthCopy(check, null).label)
+      ])
     });
   }
-  const website = health.code.startsWith("site.reachability.");
+  const fixed = fixedLines(health.cleared ?? []);
+  if (fixed.length > 0) fields.push({ label: AlertFieldLabels.fixed, value: fixed.map((line) => `\u2022 ${line}`).join("\n") });
+  const label = website ? "Website down" : copy.label;
   return {
+    ...base,
     severity,
-    title: website ? recovered ? `${project.name} website is back up` : `${project.name} website is down` : urgentEvent ? recovered ? `${project.name}: urgent problem resolved` : `${project.name}: urgent problem` : recovered ? `${project.name} recovered` : `${project.name} \u2014 measurement degraded`,
-    body: health.summary,
-    fields,
-    url: payload.dashboardUrl,
-    footer: project.canonicalDomain,
-    timestamp: health.checkedAt
+    title: `${project.name}: ${label}${urgentEvent ? " (urgent)" : ""}`,
+    body: copy.line,
+    fields
   };
 }
 function runView(payload) {
@@ -8494,6 +8623,7 @@ function runView(payload) {
   }
   return {
     severity: failed ? AlertSeverities.critical : AlertSeverities.info,
+    category: CANONRY_ALERT_CATEGORY,
     title: payload.project.name,
     fields,
     url: payload.dashboardUrl,
@@ -8533,6 +8663,7 @@ function reviewView(payload) {
     fields.push(sourceField);
     return {
       severity: AlertSeverities.warning,
+      category: CANONRY_ALERT_CATEGORY,
       title: `${project.name}: new ${review.starRating}-star review`,
       body: review.comment ? review.comment.length > 500 ? `${review.comment.slice(0, 499)}\u2026` : review.comment : "Rating only, no text.",
       fields,
@@ -8543,6 +8674,7 @@ function reviewView(payload) {
   }
   return {
     severity: AlertSeverities.warning,
+    category: CANONRY_ALERT_CATEGORY,
     title: `${project.name}: ${reviews.length} new negative reviews`,
     body: bulletList(reviews.map((r) => {
       const text = r.comment ? ` "${snippet(r.comment)}"` : "";
@@ -8564,6 +8696,7 @@ function ratingView(payload) {
   const single = ratings.length === 1 ? ratings[0] : null;
   return {
     severity: AlertSeverities.warning,
+    category: CANONRY_ALERT_CATEGORY,
     title: single ? `${project.name}: Google rating fell to ${single.rating}` : `${project.name}: Google rating fell at ${ratings.length} locations`,
     body: single ? line(single) : bulletList(ratings.map(line)),
     fields: [
@@ -8622,7 +8755,10 @@ function renderDiscord(view) {
   return {
     username: "Canonry",
     embeds: [{
-      title: `${SEVERITY_ICONS[view.severity]} ${view.title}`,
+      // The category line names who is speaking; the embed's colour carries
+      // the severity, so the title stays the problem alone.
+      ...view.category ? { author: { name: view.category } } : {},
+      title: view.category ? view.title : `${SEVERITY_ICONS[view.severity]} ${view.title}`,
       ...view.body ? { description: clamp(view.body, DISCORD_MAX_DESCRIPTION) } : {},
       color: DISCORD_COLORS[view.severity],
       fields: view.fields.map((field) => ({
@@ -8652,6 +8788,7 @@ function renderSlack(view) {
     text: headline,
     attachments: [{
       color: SLACK_COLORS[view.severity],
+      ...view.category ? { author_name: view.category } : {},
       title: headline,
       ...absoluteLink(view.url) ? { title_link: absoluteLink(view.url) } : {},
       ...view.body ? { text: clamp(view.body, SLACK_MAX_TEXT) } : {},
@@ -26331,23 +26468,29 @@ async function resolveHostAddresses(hostname, resolveAddresses) {
   }
   if (isLocalhostName(hostname)) return LOCALHOST_ADDRESSES;
   if (resolveAddresses) return await resolveAddresses(hostname);
-  try {
-    const [ipv4, ipv6] = await Promise.allSettled([dns2.resolve4(hostname), dns2.resolve6(hostname)]);
-    const unique3 = /* @__PURE__ */ new Map();
-    if (ipv4.status === "fulfilled") {
-      for (const address of ipv4.value) {
-        unique3.set(`4:${address}`, { address, family: 4 });
-      }
+  const first = await queryHostAddresses(hostname);
+  if (first.addresses.length > 0 || !first.transient) return first.addresses;
+  await new Promise((resolve) => setTimeout(resolve, DNS_RETRY_DELAY_MS + Math.random() * DNS_RETRY_DELAY_MS));
+  return (await queryHostAddresses(hostname)).addresses;
+}
+var DNS_RETRY_DELAY_MS = 500;
+async function queryHostAddresses(hostname) {
+  const [ipv4, ipv6] = await Promise.allSettled([dns2.resolve4(hostname), dns2.resolve6(hostname)]);
+  const unique3 = /* @__PURE__ */ new Map();
+  if (ipv4.status === "fulfilled") {
+    for (const address of ipv4.value) {
+      unique3.set(`4:${address}`, { address, family: 4 });
     }
-    if (ipv6.status === "fulfilled") {
-      for (const address of ipv6.value) {
-        unique3.set(`6:${address}`, { address, family: 6 });
-      }
+  }
+  if (ipv6.status === "fulfilled") {
+    for (const address of ipv6.value) {
+      unique3.set(`6:${address}`, { address, family: 6 });
     }
-    return [...unique3.values()];
-  } catch {
-    return [];
   }
+  return {
+    addresses: [...unique3.values()],
+    transient: [ipv4, ipv6].some((result) => result.status === "rejected" && isTransientNetworkError(result.reason))
+  };
 }
 function isBlockedAddress(address, options) {
   return blockedAddressReason(address, { allowLoopback: options.allowLoopback }) !== null;
@@ -41190,7 +41333,7 @@ var routeCatalog = [
     method: "post",
     path: "/api/v1/projects/{name}/traffic/sources/{id}/reset",
     summary: "Advance lastSyncedAt to NOW and clear the error state",
-    description: "Operator recovery: advances `lastSyncedAt` to NOW, sets `status` back to `connected`, and clears `last_error`. WordPress resets also clear `last_cursor` and the pending-window marker, then record an unrecovered skip through the reset instant so the next drain cannot combine an old cursor with a new window. That prevents replay but is not a historical repair. Generic WordPress replace-mode backfill is unavailable because the plugin feed cannot prove retained coverage; use a retention-aware repair and explicitly declare any unrecoverable span. Common trigger: an idle Vercel/Cloud Run source whose `lastSyncedAt` has aged past upstream retention (`request-logs` ~14d, Cloud Logging 30d) and now throws on every sync. `advanceToNow: true` is required (no implicit reset). Archived sources are rejected with 400 \u2014 re-connect them via the appropriate `traffic/connect/*` endpoint instead.",
+    description: "Operator recovery: advances `lastSyncedAt` to NOW, sets `status` back to `connected`, and clears `last_error`. WordPress resets also clear `last_cursor` and the pending-window marker, then record an unrecovered skip through the reset instant so the next drain cannot combine an old cursor with a new window. That prevents replay but is not a historical repair. Generic WordPress replace-mode backfill is unavailable because the plugin feed cannot prove retained coverage; record the skipped span with `POST /traffic/sources/{id}/declare-gap` once it cannot be recovered. Common trigger: an idle Vercel/Cloud Run source whose `lastSyncedAt` has aged past upstream retention (`request-logs` ~14d, Cloud Logging 30d) and now throws on every sync. `advanceToNow: true` is required (no implicit reset). Archived sources are rejected with 400 \u2014 re-connect them via the appropriate `traffic/connect/*` endpoint instead.",
     tags: ["traffic"],
     parameters: [
       nameParameter,
@@ -41216,6 +41359,36 @@ var routeCatalog = [
       404: errorResponse("Project or traffic source not found.")
     }
   },
+  {
+    method: "post",
+    path: "/api/v1/projects/{name}/traffic/sources/{id}/declare-gap",
+    summary: "Record a source's unrecovered skip as lost and clear it",
+    description: "Records the span a source skipped, through `skippedThroughAt`, as data that cannot be recovered, clears the marker so the `traffic.sync-lag.unrecovered-skip` doctor check passes, and writes a `traffic.source.gap-declared` audit entry with the span. Rollups are untouched. Meant for WordPress, whose plugin feed cannot prove a historical repair, and for any source whose provider no longer retains the span; a recoverable gap should be backfilled instead. `skippedThroughAt` must repeat the current marker exactly, so a newer skip recorded since the operator looked is refused, not cleared.",
+    tags: ["traffic"],
+    parameters: [
+      nameParameter,
+      { name: "id", in: "path", required: true, description: "Traffic source ID.", schema: stringSchema }
+    ],
+    requestBody: {
+      required: true,
+      content: {
+        "application/json": {
+          schema: {
+            type: "object",
+            required: ["skippedThroughAt"],
+            properties: {
+              skippedThroughAt: { type: "string", description: "The source's current `skippedThroughAt`, exactly as read." }
+            }
+          }
+        }
+      }
+    },
+    responses: {
+      200: jsonResponse("Gap recorded; the source no longer reports an unrecovered skip.", "TrafficSourceDetailDto"),
+      400: errorResponse("No gap is recorded, or `skippedThroughAt` does not match the current one."),
+      404: errorResponse("Project or traffic source not found.")
+    }
+  },
   {
     method: "get",
     path: "/api/v1/projects/{name}/traffic/sources",
@@ -43073,7 +43246,17 @@ function post(value, mediaMode = "exact") {
   const mediaSourceUrlsComplete = media.every(
     (item2) => item2.mediaFormat === "PHOTO" && typeof item2.sourceUrl === "string"
   );
-  if (!mediaSourceUrlsComplete && mediaMode === "exact")
+  const providerImageUrls = media.map((item2) => {
+    if (item2.mediaFormat !== "PHOTO" || typeof item2.googleUrl !== "string") return null;
+    try {
+      const url = new URL(item2.googleUrl);
+      return url.protocol === "https:" && /^lh\d+\.googleusercontent\.com$/u.test(url.hostname) && !url.username && !url.password && !url.port && !url.hash ? url.href : null;
+    } catch {
+      return null;
+    }
+  });
+  const providerImagesComplete = providerImageUrls.length > 0 && providerImageUrls.every((url) => url !== null);
+  if (!mediaSourceUrlsComplete && !providerImagesComplete && mediaMode === "exact" && raw.state !== GbpLocalPostStates.REJECTED)
     throw new GbpLocalPostResponseError("UNSUPPORTED_MEDIA");
   const parsed = gbpLocalPostDtoSchema.safeParse({
     name: raw.name,
@@ -43084,7 +43267,8 @@ function post(value, mediaMode = "exact") {
     actionType: action?.actionType ?? null,
     articleUrl: action?.url ?? null,
     imageUrls: mediaSourceUrlsComplete ? media.map((item2) => item2.sourceUrl) : [],
-    ...mediaMode === "discovery" ? { mediaSourceUrlsComplete } : {},
+    ...mediaMode === "discovery" || !mediaSourceUrlsComplete ? { mediaSourceUrlsComplete } : {},
+    ...providerImagesComplete ? { providerImageUrls } : {},
     createTime: raw.createTime,
     updateTime: raw.updateTime,
     searchUrl: raw.searchUrl ?? null
@@ -43593,11 +43777,16 @@ async function exchangeCode(clientId, clientSecret, code, redirectUri) {
 function escapeRegExp2(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+var TOKEN_REFRESH_RETRY = {
+  maxRetries: 1,
+  isRetryable: isTransientNetworkError,
+  computeDelayMs: (_attempt, _err, jitteredMs) => 500 + jitteredMs
+};
 async function refreshAccessToken(clientId, clientSecret, currentRefreshToken) {
   validateClientId(clientId);
   validateClientSecret(clientSecret);
   validateRefreshToken(currentRefreshToken);
-  const res = await fetch(GOOGLE_TOKEN_URL, {
+  const res = await withRetry(() => fetch(GOOGLE_TOKEN_URL, {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded" },
     body: new URLSearchParams({
@@ -43607,7 +43796,7 @@ async function refreshAccessToken(clientId, clientSecret, currentRefreshToken) {
       grant_type: "refresh_token"
     }),
     signal: AbortSignal.timeout(GOOGLE_REQUEST_TIMEOUT_MS)
-  });
+  }), TOKEN_REFRESH_RETRY);
   if (res.status === 429) {
     throw new GoogleAuthError("Google OAuth rate limit exceeded", 429);
   }
@@ -62428,7 +62617,7 @@ async function runBackfillTask(options) {
     }
   };
   if (sourceRow2.sourceType === TrafficSourceTypes.wordpress) {
-    markFailed("Generic WordPress replace backfill is unavailable because retained coverage is unproven. Use a retention-aware repair that declares the unrecoverable span.");
+    markFailed(`Generic WordPress replace backfill is unavailable because retained coverage is unproven. Record a span that cannot be recovered with \`canonry traffic declare-gap ${project.name} --source ${sourceRow2.id}\`.`);
     reportBackfill({ status: OutcomeStatuses.failed, reasonCode: OutcomeReasonCodes.UNSUPPORTED });
     return;
   }
@@ -64713,7 +64902,7 @@ async function trafficRoutes(app, opts) {
     }
     if (sourceRow2.sourceType !== TrafficSourceTypes["cloud-run"] && sourceRow2.sourceType !== TrafficSourceTypes.wordpress && sourceRow2.sourceType !== TrafficSourceTypes.vercel) {
       throw validationError(
-        `Backfill for source type "${sourceRow2.sourceType}" is not implemented yet \u2014 generic replace backfill supports only cloud-run and vercel; WordPress requires a retention-aware repair.`
+        `Backfill for source type "${sourceRow2.sourceType}" is not implemented yet \u2014 generic replace backfill supports only cloud-run and vercel; a WordPress gap is recorded with \`canonry traffic declare-gap\`.`
       );
     }
     if (!isAuthoritativeTrafficSource(app.db, sourceRow2)) {
@@ -64721,7 +64910,7 @@ async function trafficRoutes(app, opts) {
     }
     if (sourceRow2.sourceType === TrafficSourceTypes.wordpress) {
       throw validationError(
-        "Generic WordPress replace backfill is unavailable because retained coverage is unproven. Use a retention-aware repair that declares the unrecoverable span."
+        `Generic WordPress replace backfill is unavailable because retained coverage is unproven. Record a span that cannot be recovered with \`canonry traffic declare-gap ${project.name} --source ${sourceRow2.id}\`.`
       );
     }
     const requestedDays = request.body?.days ?? DEFAULT_BACKFILL_DAYS;
@@ -64979,6 +65168,40 @@ async function trafficRoutes(app, opts) {
     });
     return buildSourceDetail(project.id, updatedRow, new Date(Date.now() - 24 * 60 * 6e4).toISOString());
   }));
+  app.post("/projects/:name/traffic/sources/:id/declare-gap", async (request) => {
+    const project = resolveProject(app.db, request.params.name);
+    const parsed = trafficDeclareGapRequestSchema.safeParse(request.body ?? {});
+    if (!parsed.success) {
+      throw validationError("`skippedThroughAt` must repeat the source's recorded skip.");
+    }
+    let updatedRow;
+    app.db.transaction((tx) => {
+      const sourceRow2 = tx.select().from(trafficSources).where(and69(eq80(trafficSources.projectId, project.id), eq80(trafficSources.id, request.params.id))).get();
+      if (!sourceRow2) {
+        throw notFound("traffic source", request.params.id);
+      }
+      if (!sourceRow2.skippedThroughAt) {
+        throw validationError(`Traffic source "${sourceRow2.id}" has no unrecovered gap to declare.`);
+      }
+      if (sourceRow2.skippedThroughAt !== parsed.data.skippedThroughAt) {
+        throw validationError(
+          `Traffic source "${sourceRow2.id}" now records a gap through ${sourceRow2.skippedThroughAt}, not ${parsed.data.skippedThroughAt}. Look at it again before declaring it.`
+        );
+      }
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      tx.update(trafficSources).set({ skippedThroughAt: null, updatedAt: now }).where(eq80(trafficSources.id, sourceRow2.id)).run();
+      writeAuditLog(tx, auditFromRequest(request, {
+        projectId: project.id,
+        actor: "api",
+        action: "traffic.source.gap-declared",
+        entityType: "traffic_source",
+        entityId: sourceRow2.id,
+        diff: { skippedThroughAt: sourceRow2.skippedThroughAt, sourceType: sourceRow2.sourceType }
+      }));
+      updatedRow = tx.select().from(trafficSources).where(eq80(trafficSources.id, sourceRow2.id)).get();
+    });
+    return buildSourceDetail(project.id, updatedRow, new Date(Date.now() - 24 * 60 * 6e4).toISOString());
+  });
   app.get("/projects/:name/traffic/sources", async (request) => {
     const project = resolveProject(app.db, request.params.name);
     const rows = app.db.select().from(trafficSources).where(eq80(trafficSources.projectId, project.id)).orderBy(desc39(trafficSources.createdAt)).all();
@@ -66479,7 +66702,12 @@ function unreachable(step, err, details) {
     code: step.code,
     summary: `Could not reach Google to ${step.action}: ${error}`,
     remediation: "Check that this host can resolve and connect to Google (DNS filtering, firewall, or proxy), then re-run. The credential was not tested.",
-    details: { ...details, error }
+    details: { ...details, error },
+    alert: {
+      label: "Can't reach Google",
+      line: "The server couldn't reach Google, so GA4 data didn't refresh.",
+      next: "Nothing yet. If it repeats, check the server's internet or DNS."
+    }
   };
 }
 async function checkServiceAccount(conn) {
@@ -67450,7 +67678,12 @@ async function resolveGbpToken(ctx) {
         status: CheckStatuses.fail,
         code: "gbp.auth.no-connection",
         summary: `No Google Business Profile connection for ${ctx.project.canonicalDomain}, but ${ctx.project.name} still has selected locations.`,
-        remediation: `Run \`canonry gbp connect ${ctx.project.name}\` to authorize.`
+        remediation: `Run \`canonry gbp connect ${ctx.project.name}\` to authorize.`,
+        alert: {
+          label: "Business Profile not connected",
+          line: `Business Profile isn't connected for ${ctx.project.canonicalDomain}, but locations are still selected.`,
+          next: `Connect it with \`cnry gbp connect ${ctx.project.name}\`, or deselect its locations.`
+        }
       }
     };
   }
@@ -67479,7 +67712,12 @@ async function resolveGbpToken(ctx) {
           code: "gbp.auth.refresh-unreachable",
           summary: `Could not reach Google to refresh the GBP token: ${error}`,
           remediation: "Check that this host can resolve and connect to Google (DNS filtering, firewall, or proxy), then re-run. The stored grant was not tested.",
-          details: { domain: conn.domain, error }
+          details: { domain: conn.domain, error },
+          alert: {
+            label: "Can't reach Google",
+            line: "The server couldn't reach Google, so Business Profile data didn't refresh.",
+            next: "Nothing yet. If it repeats, check the server's internet or DNS."
+          }
         }
       };
     }
@@ -68034,7 +68272,12 @@ async function resolveAccessToken(ctx) {
           code: "google.auth.refresh-unreachable",
           summary: `Could not reach Google to refresh the GSC token: ${error}`,
           remediation: "Check that this host can resolve and connect to Google (DNS filtering, firewall, or proxy), then re-run. The stored grant was not tested.",
-          details: { domain: conn.domain, error }
+          details: { domain: conn.domain, error },
+          alert: {
+            label: "Can't reach Google",
+            line: "The server couldn't reach Google, so Search Console data didn't refresh.",
+            next: "Nothing yet. If it repeats, check the server's internet or DNS."
+          }
         }
       };
     }
@@ -68565,6 +68808,18 @@ function loadProbes(ctx) {
     configJson: r.configJson
   }));
 }
+function unrecoveredAlert(projectName, unrecovered) {
+  const through = unrecovered.map((m) => m.skippedThroughAt).sort().at(-1);
+  const day = formatCalendarDay(through.slice(0, 10));
+  const wordpress = unrecovered.filter((m) => m.sourceType === TrafficSourceTypes.wordpress);
+  const next = unrecovered.length === 1 ? wordpress.length === 1 ? `Record it as lost with \`cnry traffic declare-gap ${projectName} --source ${unrecovered[0].id}\`.` : `Backfill it with \`cnry traffic backfill ${projectName} --source ${unrecovered[0].id} --days N\`.` : "Record each WordPress gap with `cnry traffic declare-gap`, and backfill the others.";
+  const names = unrecovered.map((m) => m.displayName).join(", ");
+  return {
+    label: `Traffic gap before ${day}`,
+    line: wordpress.length === unrecovered.length ? `A stretch of traffic before ${day} is missing for ${names}. WordPress can't replay it.` : `A stretch of traffic before ${day} is missing for ${names}.`,
+    next
+  };
+}
 var sourceConnectedCheck = {
   id: "traffic.source.connected",
   category: CheckCategories.integrations,
@@ -68610,6 +68865,15 @@ var sourceConnectedCheck = {
           erroredIds: errored.map((s) => s.id),
           failuresInARow,
           lastSyncedAt: lastDataAt
+        },
+        alert: recovering ? {
+          label: "Traffic sync failed",
+          line: `The last traffic sync for ${errored.map((s) => s.displayName).join(", ")} failed.`,
+          next: "Nothing yet. The next sync usually recovers."
+        } : {
+          label: "Traffic sync failing",
+          line: `Traffic syncs for ${errored.map((s) => s.displayName).join(", ")} failed ${failuresInARow} times in a row${lastDataAt ? `, with no new data since ${formatCalendarDay(lastDataAt.slice(0, 10))}` : ""}.`,
+          next: `Check the source with \`cnry traffic sources ${ctx.project.name}\`, then reconnect it if needed.`
         }
       };
     }
@@ -68999,7 +69263,7 @@ var syncLagCheck = {
       const unrecoveredWordpress = unrecovered.filter((m) => m.sourceType === "wordpress");
       const unrecoveredOtherSources = unrecovered.filter((m) => m.sourceType !== "wordpress");
       const remediation = [
-        unrecoveredWordpress.length > 0 ? "For WordPress, do not run generic replace-mode backfill: the plugin feed cannot prove it still retains every bucket in the gap. Keep existing rollups intact and use a retention-aware repair that explicitly declares the unrecoverable span." : null,
+        unrecoveredWordpress.length > 0 ? "For WordPress, do not run generic replace-mode backfill: the plugin feed cannot prove it still retains every bucket in the gap. Once you accept the span is lost, record it with `canonry traffic declare-gap <project> --source <id>`, which keeps existing rollups and clears this check." : null,
         unrecoveredOtherSources.length > 0 ? "Recover each non-WordPress gap with `canonry traffic backfill <project> --source <id> --days N --wait`, choosing N so the window reaches back past the skipped instant and stays inside the provider's log retention. This clears only when a backfill actually covers the span." : null
       ].filter((part) => part !== null).join(" ");
       return {
@@ -69007,7 +69271,8 @@ var syncLagCheck = {
         code: "traffic.sync-lag.unrecovered-skip",
         summary: `${unrecovered.length} traffic source(s) previously skipped traffic that has not been backfilled: ${unrecovered.map((m) => `${m.displayName} (skipped through ${m.skippedThroughAt})`).join(", ")}. Current lag may look healthy; the gap does not close on its own.`,
         remediation,
-        details
+        details,
+        alert: unrecoveredAlert(ctx.project.name, unrecovered)
       };
     }
     const discarding = measured.filter((m) => m.discarding);
@@ -69066,29 +69331,33 @@ var QUEUE_NOT_VISIBLE_STOPS = [
   CloudflareQueueDrainStopReasons["empty-pulls"],
   CloudflareQueueDrainStopReasons["unleased-only"]
 ];
-function queueResidualCause(stopReasons) {
+function queueResidualCause(stopReasons, projectName, sourceId) {
   const readRuns = "Read why each sync stopped with `canonry runs <project> --kind traffic-sync --format json` (`syncSummary.stopReason`).";
   if (stopReasons.every((reason) => reason !== null && QUEUE_LIMIT_STOPS.includes(reason))) {
     return {
       cause: "The drain stopped at its time limit or pull cap before the Queue was empty.",
-      remediation: "If the backlog keeps growing, messages will pass the Queue's retention and be dropped. Shorten the traffic-sync schedule interval, or raise `CANONRY_CLOUDFLARE_QUEUE_SYNC_DEADLINE_MS` (default 4 minutes per sync)."
+      remediation: "If the backlog keeps growing, messages will pass the Queue's retention and be dropped. Shorten the traffic-sync schedule interval, or raise `CANONRY_CLOUDFLARE_QUEUE_SYNC_DEADLINE_MS` (default 4 minutes per sync).",
+      next: "If it keeps growing, sync more often, or the oldest requests expire from the queue."
     };
   }
   if (stopReasons.every((reason) => reason !== null && QUEUE_NOT_VISIBLE_STOPS.includes(reason))) {
     return {
       cause: "Cloudflare returned no more messages to pull while still counting them, so they were leased or not yet visible. The drain stopped before its time limit, so raising the limit does not help.",
-      remediation: "Later syncs pull them as they become visible. If the count does not fall across syncs, check the Queue in the Cloudflare dashboard for in-flight or delayed messages before they pass the Queue's retention."
+      remediation: "Later syncs pull them as they become visible. If the count does not fall across syncs, check the Queue in the Cloudflare dashboard for in-flight or delayed messages before they pass the Queue's retention.",
+      next: "Nothing yet. Later syncs pull them once Cloudflare releases them."
     };
   }
   if (stopReasons.every((reason) => reason === CloudflareQueueDrainStopReasons.error)) {
     return {
       cause: "The last sync failed before the Queue was empty.",
-      remediation: `Fix the sync error, then run \`canonry traffic sync <project> --source <id>\`. ${readRuns}`
+      remediation: `Fix the sync error, then run \`canonry traffic sync <project> --source <id>\`. ${readRuns}`,
+      next: `Fix the sync error, then run \`cnry traffic sync ${projectName} --source ${sourceId ?? "<id>"}\`.`
     };
   }
   return {
     cause: "The last sync stopped before the Queue was empty.",
-    remediation: `${readRuns} If it hit its time limit, shorten the traffic-sync schedule interval or raise \`CANONRY_CLOUDFLARE_QUEUE_SYNC_DEADLINE_MS\` (default 4 minutes per sync).`
+    remediation: `${readRuns} If it hit its time limit, shorten the traffic-sync schedule interval or raise \`CANONRY_CLOUDFLARE_QUEUE_SYNC_DEADLINE_MS\` (default 4 minutes per sync).`,
+    next: `See why the last sync stopped with \`cnry runs ${projectName} --kind traffic-sync\`.`
   };
 }
 var queueBacklogCheck = {
@@ -69131,13 +69400,22 @@ var queueBacklogCheck = {
     const remaining = measured.filter((source) => (source.queueBacklogCount ?? 0) > 0);
     const total = remaining.reduce((sum, source) => sum + source.queueBacklogCount, 0);
     if (total > CLOUDFLARE_QUEUE_RESIDUAL_WARN_COUNT) {
-      const { cause, remediation } = queueResidualCause(remaining.map((source) => stopReasons.get(source.id) ?? null));
+      const { cause, remediation, next } = queueResidualCause(
+        remaining.map((source) => stopReasons.get(source.id) ?? null),
+        ctx.project.name,
+        remaining.length === 1 ? remaining[0].id : null
+      );
       return {
         status: CheckStatuses.warn,
         code: "traffic.queue-backlog.remaining",
         summary: `${total.toLocaleString("en-US")} message(s) remained across ${remaining.length} Cloudflare Queue source(s) after the last sync, more than the ${CLOUDFLARE_QUEUE_RESIDUAL_WARN_COUNT.toLocaleString("en-US")} that can arrive while a drain runs. ${cause}`,
         remediation,
-        details
+        details,
+        alert: {
+          label: "Traffic backlog",
+          line: `${total.toLocaleString("en-US")} site requests are waiting to be processed. Normal is under ${CLOUDFLARE_QUEUE_RESIDUAL_WARN_COUNT.toLocaleString("en-US")}.`,
+          next
+        }
       };
     }
     if (total > 0) {
@@ -69157,6 +69435,25 @@ var queueBacklogCheck = {
     };
   }
 };
+function cloudflareReconnectCommand(projectName, source) {
+  const base = `cnry traffic connect cloudflare ${projectName}`;
+  if (!isCloudflareQueuePull(source)) return `\`${base}\``;
+  const parsed = cloudflareQueuePullTrafficSourceConfigSchema.safeParse(source.configJson);
+  if (!parsed.success) {
+    return `\`${base} --delivery-mode queue-pull\` with its Queue options (\`cnry traffic sources ${projectName}\`)`;
+  }
+  const config = parsed.data;
+  const options = [
+    "--delivery-mode queue-pull",
+    `--account-id ${config.accountId}`,
+    `--queue-id ${config.queueId}`,
+    `--queue-name ${config.queueName}`,
+    `--retention-seconds ${config.retentionSeconds}`,
+    ...config.zoneId ? [`--zone-id ${config.zoneId}`] : [],
+    "--api-token-file <path>"
+  ];
+  return `\`${base} ${options.join(" ")}\``;
+}
 var workerVersionCheck = {
   id: "traffic.source.worker-version",
   category: CheckCategories.integrations,
@@ -69165,6 +69462,7 @@ var workerVersionCheck = {
   run: (ctx) => {
     if (!ctx.project) return skippedNoProject5();
     const sources = loadProbes(ctx).filter((source) => isActiveSource(source) && isCloudflareWorkerSource(source));
+    const probeById = new Map(sources.map((source) => [source.id, source]));
     if (sources.length === 0) {
       return {
         status: CheckStatuses.skipped,
@@ -69193,7 +69491,12 @@ var workerVersionCheck = {
         code: "traffic.worker-version.stale",
         summary: `${stale.length} Cloudflare Worker source(s) most recently reported a version that differs from the generated version.`,
         remediation: "Regenerate and redeploy each source's Cloudflare Worker from the credential-owning host with `canonry traffic connect cloudflare <project>` and the source's existing delivery-mode options; then verify its route or Queue binding.",
-        details
+        details,
+        alert: {
+          label: "Cloudflare worker out of date",
+          line: `The Cloudflare traffic worker for ${stale.map((source) => source.displayName).join(", ")} doesn't match this server's version.`,
+          next: stale.length === 1 ? `Redeploy it with ${cloudflareReconnectCommand(ctx.project.name, probeById.get(stale[0].sourceId))}.` : `Redeploy each in its own delivery mode: ${stale.map((source) => `${source.displayName}: ${cloudflareReconnectCommand(ctx.project.name, probeById.get(source.sourceId))}`).join("; ")}.`
+        }
       };
     }
     const waiting = measured.filter((source) => source.state === "waiting-for-first-event");
@@ -69692,6 +69995,7 @@ async function runChecks(ctx, checks, options = {}) {
       summary: output.summary,
       remediation: output.remediation ?? null,
       details: output.details,
+      ...output.alert ? { alert: output.alert } : {},
       durationMs: Date.now() - checkStarted
     });
   }
@@ -69718,8 +70022,9 @@ function supersede(definition2, result, failedCauses) {
   if (threw(definition2, result)) return result;
   const causes = (definition2.supersededBy ?? []).filter((id) => failedCauses.has(id));
   if (causes.length === 0) return result;
+  const { alert: _symptomAlert, ...symptom } = result;
   return {
-    ...result,
+    ...symptom,
     status: CheckStatuses.skipped,
     code: `${definition2.id}.superseded`,
     summary: `Superseded by failing ${causes.join(", ")}, which names the cause. ${result.summary}`,