ccdeck 3.36.8 → 3.37.0

package/src/server/reports.mjs

@@ -7,8 +7,12 @@
 // WHAT GOES OUT, to api.ccdeck.dev, while `prefs.reports` is true and the
 // machine has not vetoed it (reportsVetoed):
 //
-//   - an "install" event the first time,
+//   - an "install" event the first time, with the ccdeck.dev page its command
+//     was copied from when the command said (`--ref`, install-ref.mjs) — a
+//     page name, never anything about the person,
 //   - an "update" event, with the version it came from, when the version moves,
+//     and how the new one arrived: the deck's own update, the desktop app's
+//     updater, npx, npm, or a source checkout,
 //   - an "active" event at most once a UTC day, which is how many people use
 //     ccdeck gets counted without counting anything else about them, and which
 //     alone also carries coarse counts of how much: how many sessions,
@@ -16,15 +20,30 @@
 //     and that day's date — numbers, never their names (see usage-day.mjs) —
 //     and which of the deck's features were used that day, as fixed names
 //     ("usage-history", "account-switch") and nothing about what was done
-//     with them (feature-use.mjs),
+//     with them (feature-use.mjs), and how the deck held up and who runs it:
+//     how long this run took to start, that day's peak memory and how many
+//     events it took in, each as a bucket ("2s", "512m", "1k"), the Claude and
+//     Codex plan as its category ("max-20x", "plus") and nothing else from the
+//     credentials it is read off, and how many Claude accounts and paired
+//     machines the deck holds, as capped counts (depth-facts.mjs),
+//   - an "uninstall" event when somebody runs `ccdeck --uninstall`, with the
+//     reason they picked from a short list if they picked one (bin/cli/leaving.js),
 //   - an "activated" event, once, when a new install's first session arrives:
 //     how long after the install it came, as a bucket ("5m", "1h", "1d", "7d",
 //     "later"), and whether it was a Claude or a Codex session (activation.mjs),
+//   - a "rated" event, once, if somebody answers the one question the deck asks
+//     about itself after about a week of use — "How useful is ccdeck to you?" —
+//     with the number picked, 0 to 10, and how many days the deck had been used
+//     as a range ("7-13", "30-89"); nothing for a question put off or left
+//     unanswered (rating.mjs),
 //   - errors: a request handler that threw on this server, or an error the page
-//     caught, with home folders, email addresses and key-shaped strings
-//     scrubbed out before they leave,
+//     caught, with every path outside the deck's own package, project folder
+//     names, the host of every web address, every IP address and the machine
+//     name a network error carries, email addresses and key-shaped strings
+//     scrubbed out before they leave (see scrub),
 //   - a "ping" heartbeat, every ten minutes or so while the deck runs, which
-//     moves the install's "last seen" so the admin can show who is online now.
+//     moves the install's "last seen" so the admin can show who is online now,
+//     and is counted per day, which is how long the deck stays open.
 //     It writes no event and carries the install id alone — no facts, no
 //     fingerprint.
 //
@@ -61,24 +80,38 @@
 //
 // NOTHING HERE THROWS OR WAITS FOR ANYBODY. A report that cannot be sent is
 // dropped: it is a nicety for the people who make ccdeck, and no part of the
-// deck depends on it.
+// deck depends on it. An event a check-in owes is tried again on the heartbeat,
+// less often the longer the API stays out of reach; one the API itself refuses
+// (its 400, 413 or 422 problem+json) is not sent again, since the same body would
+// be refused the same way. A 4xx the edge in front of it answers with is tried again.
 
 import { createHash, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, unlink } from "node:fs/promises";
 import { arch as osArch, cpus as osCpus, homedir, hostname, platform as osPlatform, totalmem } from "node:os";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { inApp } from "./app-host.mjs";
+import { stripBom, writeFileAtomic } from "./atomic-write.mjs";
+import { deckDataDir } from "./deck-home.mjs";
 import { reportsVetoed } from "./deck-prefs.mjs";
-import { isGitCheckout } from "./install-layout.mjs";
-import { heldPrefs, prefsRead } from "./prefs-state.mjs";
+import { prefsDir } from "./prefs-path.mjs";
+import { isGitCheckout, isNpxInstall } from "./install-layout.mjs";
+import { bootFoundNoPrefs, heldPrefs, prefsRead } from "./prefs-state.mjs";
 import { RUNNING_VERSION } from "./running-version.mjs";
 import { FEATURES, usageDay, utcDay } from "./usage-day.mjs";
 import { setupFacts, sinceInstallBucket, whenSetupKnown } from "./activation.mjs";
+import { notedRef, refSlug } from "./install-ref.mjs";
+import {
+  CLAUDE_PLANS, CODEX_PLANS, cappedCount, deckDepth, eventsBucket, launchBucket, memoryBucket, updateVia,
+} from "./depth-facts.mjs";
+import { daysUsedBucket, normaliseRating, ratingDue, ratingStage, scoreOf } from "./rating.mjs";
 
 export const REPORTS_API = "https://api.ccdeck.dev";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const TIMEOUT_MS = 6000;
-/** How often a long-running deck checks whether a new day wants its "active". */
+/** How often a long-running deck checks in whatever the heartbeat found. The beat
+ *  already sends what is due — a new day's "active", a check-in that failed —
+ *  so this is the floor under it, not the schedule. */
 const CHECK_IN_EVERY_MS = 6 * 60 * 60 * 1000;
 /** The heartbeat's beat: a lighter timer than the check-in that only moves the
  *  install's "last seen", so the admin can count who is online now. Ten minutes,
@@ -86,15 +119,26 @@ const CHECK_IN_EVERY_MS = 6 * 60 * 60 * 1000;
  *  not all beat on the same tick. */
 const PING_EVERY_MS = 10 * 60 * 1000;
 const PING_JITTER_MS = 2 * 60 * 1000;
+/** The longest a 429's or a 503's Retry-After is waited for: a header that asks
+ *  for a week does not silence a deck for one. */
+const RETRY_AFTER_MAX_MS = 24 * 60 * 60 * 1000;
+/** How long a report waits for the CLI versions it is about to carry: a couple
+ *  of `--version` answers (cli-versions.mjs). One not known by then is left out. */
+const CLI_PROBE_WAIT_MS = 8_000;
 /** Errors per hour this deck may send, and how long one error is not repeated. */
 const ERRORS_PER_HOUR = 20;
 const SAME_ERROR_QUIET_MS = 60 * 60 * 1000;
 const MESSAGE_MAX = 500;
 const STACK_MAX = 4000;
 
+/** Why somebody uninstalled, when they said: the answers `ccdeck --uninstall`
+ *  offers (bin/cli/leaving.js), and nothing else ever leaves as a reason. */
+export const UNINSTALL_REASONS = Object.freeze(["not-useful", "too-noisy", "broken", "other-tool", "privacy", "other"]);
+
 const EMPTY_REPORT = Object.freeze({
   installId: "", lastVersion: "", lastActiveDay: "", forget: "", usage: null,
-  installedAt: "", firstSessionAt: "", firstProvider: "", activationSent: false,
+  installedAt: "", firstSessionAt: "", firstProvider: "", activationSent: false, ref: "", selfUpdate: null,
+  rating: normaliseRating(null),
 });
 
 /** Is this deck sending reports right now? The switch, which is on unless
@@ -210,16 +254,38 @@ function intlLocale() {
 }
 
 /** The shell as a bare name — "zsh", "bash", "fish". `SHELL` names it on POSIX;
- *  on Windows there is no `SHELL` (unless a Git-Bash-style one set it), so the
- *  hints are PowerShell's `PSModulePath` and cmd's `ComSpec`. */
+ *  on Windows there is no `SHELL` (unless a Git-Bash-style one set it), so it is
+ *  read off what each shell leaves for what it starts (windowsShell). */
 export function shellToken(env = process.env, platform = process.platform) {
   const sh = env?.SHELL;
   if (sh) return token(baseName(sh), TOKEN_CAPS.shell);
-  if (platform === "win32") {
-    if (env?.PSModulePath) return "pwsh";
-    const comSpec = env?.ComSpec ?? env?.COMSPEC;
-    return comSpec ? token(baseName(comSpec), TOKEN_CAPS.shell) : "cmd";
-  }
+  if (platform === "win32") return windowsShell(env);
+  return undefined;
+}
+
+/**
+ * The Windows shell that started the deck — "pwsh", "powershell", "cmd" — or
+ * nothing when it cannot be told.
+ *
+ * Not `PSModulePath` being set, nor `ComSpec`: Windows sets both machine-wide,
+ * so every process has them — cmd.exe, Windows PowerShell, and the desktop app
+ * started from the Start menu — and every Windows deck used to say "pwsh".
+ * What PowerShell adds for what it starts is its user module folder, under the
+ * user's profile: Documents\PowerShell\Modules for PowerShell 7,
+ * Documents\WindowsPowerShell\Modules for Windows PowerShell. cmd.exe defines
+ * `PROMPT`. PowerShell is asked first, because npm's .cmd shim runs through
+ * cmd.exe even from a PowerShell prompt.
+ */
+function windowsShell(env) {
+  const profile = String(env?.USERPROFILE ?? "").replace(/[\\/]+$/, "").toLowerCase();
+  const userModules = profile
+    ? String(env?.PSModulePath ?? "").split(";")
+      .map(p => p.trim().replace(/[\\/]+$/, "").toLowerCase())
+      .filter(p => p.startsWith(`${profile}\\`) || p.startsWith(`${profile}/`))
+    : [];
+  if (userModules.some(p => /[\\/]powershell[\\/]modules$/.test(p))) return "pwsh";
+  if (userModules.some(p => /[\\/]windowspowershell[\\/]modules$/.test(p))) return "powershell";
+  if (env?.PROMPT) return token(baseName(env?.ComSpec ?? env?.COMSPEC ?? "cmd"), TOKEN_CAPS.shell) ?? "cmd";
   return undefined;
 }
 
@@ -284,22 +350,132 @@ export function installFacts({
   return facts;
 }
 
+// One folder or file name of a path. One in the middle may hold spaces ("Bob
+// Smith", "Application Support"), because the separator after it says where it
+// ends; the last stops at the first space, so the words after a path are kept.
+const NAME = String.raw`[^\s\\/:'"\`<>|?*;,]`;
+const MIDDLE = String.raw`${NAME}(?:[^\\/\r\n:'"\`<>|?*;,]*${NAME})?[\\/]`;
+const LAST = String.raw`[^\s\\/:'"\`<>|?*;,()]+`;
+const TAIL = String.raw`(?:${MIDDLE})*(?:${LAST})?`;
+/** A path in any shape an error carries one: a file:// URL, a ~ path, a drive
+ *  path, a UNC path, an absolute POSIX path. Not an address — `https://host/x`
+ *  starts after a colon and its path after the host, or after the `<deck>` or
+ *  `<host>` that host is sent as (hideOrigin) — and not `node:internal/…`.
+ *  A `:42:7` after it is left where it is. */
+export const PATH_PATTERN = String.raw`(?<![\w.~/\\\]-]|<(?:deck|host)>)(?:file://(?:/[A-Za-z]:)?[^\s:'"\`<>()]*|~[\\/]${TAIL}|[A-Za-z]:[\\/]${TAIL}|\\\\(?:[?.]\\)?(?:[A-Za-z]:\\)?${TAIL}|/(?=${NAME})${TAIL}|(?<!:)//(?=${NAME})${TAIL})`;
+/** A folder name in Claude Code's encoding of a project's path, every character
+ *  but letters and digits made a dash: `-home-alice-acme`, `C--Users-Bob-acme`. */
+export const PROJECT_PATTERN = String.raw`(?<![\w-])(?:[A-Za-z]--|-[A-Za-z0-9][\w.]*-)[\w.-]*`;
+/** The folders under home whose name is kept in front of a scrubbed path: the
+ *  two CLIs the deck reads. They say which side an error came from, and name nobody. */
+const KEPT_HOME_FOLDERS = new Set([".claude", ".codex"]);
+
+/** What a path outside the deck is sent as: `<path>`, or `~/<path>` and
+ *  `~/.claude/<path>` for one under the home folder. */
+function hidePath(path) {
+  if (!path.startsWith("~")) return "<path>";
+  const sep = path[1];
+  const [top, ...rest] = path.slice(2).split(/[\\/]/);
+  if (!top) return path;
+  if (!KEPT_HOME_FOLDERS.has(top)) return `~${sep}<path>`;
+  return rest.join("") ? `~${sep}${top}${sep}<path>` : path;
+}
+
+/** The scheme and host of an address (with its port, and a user in front of the
+ *  host): a deck opened from another machine is opened by that machine's name,
+ *  and every frame of the page carries it. The second group is the bundle's
+ *  `/assets/` after it, which only the deck's own page loads scripts from. */
+export const ORIGIN_PATTERN = String.raw`\b(https?|wss?)://[^\s/?#\\'"\x60<>(),;]+(?=(/assets/)?)`;
+
+/** What an address is sent as: `<deck>/assets/…` for the page's own scripts, so
+ *  a frame still says where in the bundle; `https://<host>/…` for any other. */
+function hideOrigin(_origin, scheme, assets) {
+  return assets ? "<deck>" : `${scheme}://<host>`;
+}
+
+const OCTET = String.raw`(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)`;
+const IPV4 = String.raw`${OCTET}(?:\.${OCTET}){3}`;
+const HEX = String.raw`[0-9A-Fa-f]{1,4}`;
+/** An IPv6 address: compressed with a `::` or all eight groups there, with a
+ *  digit in it (`Face::Add` is code), an IPv4 address allowed at its end
+ *  (`::ffff:192.168.1.5`), and a port Node glues on with no brackets
+ *  (`fd7a:115c::5:4317`) taken along, since nothing tells it from the last group. */
+const IPV6 = String.raw`(?=[0-9A-Fa-f:]*\d)(?=[0-9A-Fa-f:]*::|(?:${HEX}:){7})(?:(?:${HEX})?:)+(?:${IPV4}|${HEX})?`;
+const ZONE = String.raw`%[\w-]+(?:\.[\w-]+)*`;
+/** The loopback and the any-address, plain or mapped: they name nobody. */
+const KEPT_IPV6 = String.raw`(?:::1?|::ffff:(?:127(?:\.\d{1,3}){3}|0\.0\.0\.0))`;
+
+/** Every IPv4 and IPv6 address, bracketed or bare, but the loopback and the
+ *  any-address, so `connect ECONNREFUSED 127.0.0.1:4317` stays readable. Not a
+ *  version: an IPv4 address is four parts, never one after a slash
+ *  (`Chrome/130.0.0.0`) or a dash (`node-22.18.0`). */
+export const ADDRESS_PATTERN = String.raw`(?<![\w:.%-])(?:\[(?!${KEPT_IPV6}\])${IPV6}(?:${ZONE})?\]|(?!${KEPT_IPV6}(?::\d{1,5})?(?![\w:%]|\.\d))${IPV6}(?:${ZONE})?(?![\w%]|\.\d))|(?<![\w./-])(?!127\.|0\.0\.0\.0\b)${IPV4}(?![\w-]|\.\d)`;
+
+/** A host name, with a letter in it somewhere: one of all digits is an IPv4 address. */
+const HOST = String.raw`(?=[\w.-]*[A-Za-z])[A-Za-z0-9][\w-]*(?:\.[\w-]+)*`;
+/** A host name where a network error puts one: after a DNS or connect failure
+ *  (`getaddrinfo ENOTFOUND bobs-pc`), glued to a port (`bobs-pc:4317`), or
+ *  ending in a local-network suffix (.local, .lan, .home, .internal, .ts.net).
+ *  Not localhost, and not a file:line:col frame: a port has no second number
+ *  after it. */
+export const HOST_PATTERN = String.raw`(?<![\w.@/\\%-])(?!localhost(?![\w-]|\.\w))(?:(?<=\b(?:(?:getaddrinfo|connect) E[A-Z_]+|ENOTFOUND|EAI_AGAIN) )${HOST}|${HOST}(?=:\d{1,5}(?![\w:-]|\.\w))|${HOST}\.(?:local|lan|home|internal|ts\.net)(?![\w-]|\.\w))`;
+
+const escapeRegExp = s => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Every spelling of `dir` a stack or a message can use — the path, and the
+ *  file:// URL an ES module's frames carry — as a pattern for `dir` and the
+ *  separator after it, so `/x/ccdeck-fork` is not taken for `/x/ccdeck`. */
+function spellings(dir) {
+  const windows = /^(?:[A-Za-z]:[\\/]|\\\\)/.test(dir);
+  const url = pathToFileURL(dir, { windows }).href.replace(/\/$/, "");
+  return new RegExp(`(?:${escapeRegExp(url)}|${escapeRegExp(dir)})(?=[\\\\/])`, windows ? "gi" : "g");
+}
+
 /**
  * Take out of an error what could say who someone is.
  *
+ * No path outside the deck's own package leaves. A path inside it keeps its
+ * place in the package — `ccdeck/src/server/tail.mjs:42:7`, however the deck was
+ * installed — so a stack still says where the bug is and reads the same on every
+ * machine; so does a dependency npx put beside it (`node_modules/ws/…`). Every
+ * other path becomes `<path>` (`~/.claude/<path>` under the home folder, see
+ * hidePath), and a project folder in Claude Code's encoding `<project>`: either
+ * would name what somebody works on.
+ *
+ * No host leaves either. The page's frames name the machine the deck was opened
+ * by (`http://alices-macbook.local:4317/assets/…`); they become `<deck>/assets/…`,
+ * which still says where in the bundle and reads the same on every machine, and
+ * any other address keeps its scheme and path and loses its host (hideOrigin).
+ * An address with no scheme in front goes the same way: every IPv4 and IPv6
+ * address (ADDRESS_PATTERN), and a host name where a network error puts one
+ * (HOST_PATTERN: `getaddrinfo ENOTFOUND bobs-pc.local`, `bobs-pc:4317`), becomes
+ * `<host>`, a port kept apart from it left in place. The loopback and the
+ * any-address stay — `connect ECONNREFUSED 127.0.0.1:4317` names nobody, and
+ * says which port.
+ *
  * The catch-all for long opaque strings deliberately stops at a slash: with one
  * in it, the pattern swallowed every long file path, and a stack whose frames
  * read `at save (~/.<secret>.mjs:40:3)` tells nobody where the bug is.
  * The API scrubs again;
- * this is the pass that means it never has to: this user's home folder, anyone
- * else's home folder, email addresses, and strings shaped like keys and tokens.
+ * this is the pass that means it never has to: paths, project folders, hosts
+ * and addresses, email addresses, and strings shaped like keys and tokens.
  */
-export function scrub(text, home = homedir()) {
+export function scrub(text, home = homedir(), root = PKG_ROOT) {
   let out = String(text ?? "");
-  if (home && home.length > 1) out = out.split(home).join("~");
+  if (root && root.length > 1) {
+    out = out.replace(spellings(root), "ccdeck");
+    if (basename(dirname(root)) === "node_modules") out = out.replace(spellings(dirname(root)), "node_modules");
+  }
+  // Never half a name: a home of /home/al is not the start of /home/alice.
+  if (home && home.length > 1) out = out.replace(new RegExp(`${escapeRegExp(home)}(?![\\w.-])`, "g"), "~");
   return out
     .replace(/\/(?:home|Users)\/[^/\s:'"]+/g, "~")
     .replace(/[A-Za-z]:\\(?:Users|Documents and Settings)\\[^\\\r\n:'"]+/gi, "~")
+    .replace(new RegExp(PATH_PATTERN, "g"), hidePath)
+    .replace(new RegExp(PROJECT_PATTERN, "g"), "<project>")
+    .replace(new RegExp(ORIGIN_PATTERN, "g"), hideOrigin)
+    .replace(new RegExp(ADDRESS_PATTERN, "g"), "<host>")
+    .replace(new RegExp(HOST_PATTERN, "g"), "<host>")
     .replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, "<email>")
     .replace(
       /\b(?:sk-ant-[A-Za-z0-9_-]{8,}|sk-[A-Za-z0-9_-]{20,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abpr]-[A-Za-z0-9-]{10,}|eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}|[A-Fa-f0-9]{40,}|[A-Za-z0-9+_=-]{48,})/g,
@@ -318,10 +494,16 @@ export function scrub(text, home = homedir()) {
  * @param {NodeJS.ProcessEnv} [deps.env]
  * @param {ReturnType<typeof installFacts>} [deps.facts]
  * @param {string} [deps.home]
+ * @param {string} [deps.root] the deck's own package, whose paths an error keeps (see scrub)
  * @param {Promise<unknown>} [deps.ready] what start() waits for: the prefs read at import
  * @param {() => { claudeVersion?: string, codexVersion?: string }} [deps.versions] the CLI
  *   versions to fold into the facts, read fresh on every send so a background
  *   probe's answer rides along the moment it arrives. Default: none.
+ * @param {() => Promise<unknown>} [deps.probe] asks the CLIs their versions again,
+ *   for `versions` to answer with: started by start() once the prefs say reports
+ *   are on, again on each new UTC day, and waited for — never past
+ *   CLI_PROBE_WAIT_MS — before an install, update or "active" goes out.
+ *   Default: none.
  * @param {ReturnType<typeof import("./usage-day.mjs").createUsageDay>} [deps.usage]
  *   the day's tally: the "active" report carries the last finished day's totals,
  *   read only when an "active" is about to be sent, and the tally is saved into
@@ -330,6 +512,27 @@ export function scrub(text, home = homedir()) {
  *   boot set up, folded into install, update and active (activation.mjs).
  * @param {() => Promise<unknown>} [deps.setupKnown] what start() waits for besides the
  *   prefs, so the first install event carries the setup. Bounded.
+ * @param {() => string | undefined} [deps.reference] the ref this run's command
+ *   carried (install-ref.mjs), for the install event alone.
+ * @param {(ctx: { setup: object, prefs: object }) => Promise<object>} [deps.depth] the
+ *   plans, accounts and paired machines the "active" carries (depth-facts.mjs),
+ *   read only when one is about to go. Default: none — the deck's own reporter
+ *   passes deckDepth, so no test reads a real credentials file.
+ * @param {() => number} [deps.launchedIn] ms from this process starting to the
+ *   deck listening, read once by start(), which runs as the deck starts listening.
+ * @param {() => number} [deps.memory] the process's resident memory in bytes,
+ *   sampled on the heartbeat's beat for the usage day's peak.
+ * @param {boolean} [deps.npx] this copy runs out of an npx cache, which is how an
+ *   npm install that changed version under it updated.
+ * @param {() => number} [deps.uptime] how long this deck has been up, in ms: the
+ *   question about the deck is never asked in the minutes after a launch.
+ * @param {() => boolean} [deps.firstRun] this run's boot found no settings file:
+ *   the deck had never run here, so an install id made now is a real install and
+ *   its first session is timed. Default: the boot read's own answer.
+ * @param {{ read: () => Promise<unknown>, write: (kept: object | null) => Promise<void> }} [deps.ratingKept]
+ *   where the question's outcome is kept a second time, out of reach of an
+ *   older deck's write of prefs.json (ratingFile). Default: none — the deck's
+ *   own reporter passes ratingFile(), so no test writes beside a real prefs.json.
  */
 export function createReporter({
   fetchImpl = globalThis.fetch,
@@ -338,16 +541,28 @@ export function createReporter({
   env = process.env,
   facts = installFacts({ env }),
   home = homedir(),
+  root = PKG_ROOT,
   ready = prefsRead,
   versions = () => ({}),
+  probe = async () => {},
   usage = usageDay,
   setup = setupFacts,
   setupKnown = () => whenSetupKnown(),
+  reference = notedRef,
+  depth = async () => ({}),
+  launchedIn = () => process.uptime() * 1000,
+  memory = () => process.memoryUsage.rss(),
+  npx = false,
+  uptime = () => process.uptime() * 1000,
+  firstRun = bootFoundNoPrefs,
+  ratingKept = null,
 } = {}) {
   const errorsSent = [];
   const lastSentAt = new Map();
   let timer = null;
   let pingTimer = null;
+  /** How long this run took to start, read when start() runs; null before. */
+  let launchMs = null;
 
   /** The CLI versions to add to the facts right now, tokenised and omitted when
    *  not yet known — read on every send so the background probe's result appears
@@ -364,6 +579,41 @@ export function createReporter({
     }
   }
 
+  /** The UTC day the CLIs were last asked their versions, and the asking under way. */
+  let probedDay = "";
+  let probing = null;
+
+  /** Ask the CLIs their versions, at most once a UTC day — so a deck left running
+   *  for a week says the Claude Code it has now, not the one it booted with — and
+   *  resolve once the answer is in. Never rejects. */
+  function probeVersions() {
+    try {
+      const today = utcDay(now());
+      if (!probing && probedDay !== today) {
+        probedDay = today;
+        probing = Promise.resolve()
+          .then(() => probe())
+          .catch(() => { /* a probe that could not run leaves the versions as they were */ })
+          .finally(() => { probing = null; });
+      }
+    } catch {
+      // A clock that cannot say the day; the report goes with what is known.
+    }
+    return probing ?? Promise.resolve();
+  }
+
+  /** The versions fresh for a report about to carry them: the day's probe, waited
+   *  for, but never past CLI_PROBE_WAIT_MS — a version not known by then is left
+   *  out, and rides on a later report. */
+  async function versionsReady() {
+    let timer;
+    await Promise.race([
+      probeVersions(),
+      new Promise(r => { timer = setTimeout(r, CLI_PROBE_WAIT_MS); timer.unref?.(); }),
+    ]);
+    clearTimeout(timer);
+  }
+
   /** The full facts an event carries: the fixed install facts, plus whatever CLI
    *  versions are known this moment. */
   function factsNow() {
@@ -384,6 +634,25 @@ export function createReporter({
     }
   }
 
+  /** Whether this is the deck's first run here. Never throws: a run it cannot
+   *  tell is not one. */
+  function isFirstRun() {
+    try {
+      return firstRun() === true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** This run's ref, if it is one. Never throws. */
+  function refNow() {
+    try {
+      return refSlug(reference());
+    } catch {
+      return undefined;
+    }
+  }
+
   /** The coarse usage the "active" report carries: the last finished day before
    *  `today`, its date as `usageDay` and its counts beside it. Nothing at all
    *  when there is no such day yet — a first launch has no yesterday — and only
@@ -400,12 +669,45 @@ export function createReporter({
       // The features used that day, as names off the fixed list — an empty list
       // is a real answer (the deck ran, nothing was opened), not a missing one.
       out.features = Array.isArray(raw.features) ? raw.features.filter(f => FEATURES.includes(f)) : [];
+      // How hard the deck worked that day, as buckets (depth-facts.mjs). A peak
+      // of zero is a day no beat sampled, and null events a day this deck did
+      // not count in full (usage-day.mjs): neither says anything.
+      addIf(out, "events", eventsBucket(raw.events));
+      addIf(out, "deckMemory", raw.peakMb > 0 ? memoryBucket(raw.peakMb) : undefined);
       return out;
     } catch {
       return {};
     }
   }
 
+  /** What the "active" says about the deck beyond its day: how long this run
+   *  took to start, as a bucket, and the plans, accounts and paired machines
+   *  the depth provider reads — each only as a word off its list or a capped
+   *  count (depth-facts.mjs). A reading that throws costs the report nothing. */
+  async function depthNow() {
+    const out = {};
+    addIf(out, "launch", launchMs == null ? undefined : launchBucket(launchMs));
+    try {
+      const d = (await depth({ setup: setupNow(), prefs: prefs.current() })) ?? {};
+      addIf(out, "claudePlan", CLAUDE_PLANS.includes(d.claudePlan) ? d.claudePlan : undefined);
+      addIf(out, "codexPlan", CODEX_PLANS.includes(d.codexPlan) ? d.codexPlan : undefined);
+      addIf(out, "accounts", cappedCount(d.accounts));
+      addIf(out, "machines", cappedCount(d.machines));
+    } catch {
+      // A plan or a count that could not be read is left out.
+    }
+    return out;
+  }
+
+  /** The deck's memory into the day's tally, which keeps the day's highest. */
+  function samplePeak() {
+    try {
+      usage.notePeak?.(memory() / (1024 * 1024));
+    } catch {
+      // A reading that failed this beat; the next one tries again.
+    }
+  }
+
   /** The tally the last save wrote, so a save with nothing new writes nothing. */
   let usageSaved = -1;
 
@@ -435,6 +737,9 @@ export function createReporter({
     }
   }
 
+  /** What became of a send: "sent"; "refused" — the API saying no to this body,
+   *  which it will say again to the same body, so it is final; or "failed" —
+   *  anything else, worth another try. */
   async function call(method, path, body) {
     try {
       const res = await fetchImpl(REPORTS_API + path, {
@@ -443,12 +748,94 @@ export function createReporter({
         body: body === undefined ? undefined : JSON.stringify(body),
         signal: AbortSignal.timeout(TIMEOUT_MS),
       });
-      return res.ok;
+      if (res.ok) return "sent";
+      if (res.status === 429 || res.status === 503) waitAsAsked(res);
+      return refusedByApi(res) ? "refused" : "failed";
+    } catch {
+      return "failed";
+    }
+  }
+
+  /** Whether an answer is the API's own verdict on the body: a 400, 413 or 422
+   *  it wrote as application/problem+json, the only way it turns a body down.
+   *  Any other 4xx — a 403 or 404 Cloudflare answers with itself (a challenge,
+   *  a rule, a tunnel being moved), a proxy's 401 — says nothing about the body,
+   *  and a later try can get through, so it is tried again like a 5xx. */
+  function refusedByApi(res) {
+    try {
+      if (res.status !== 400 && res.status !== 413 && res.status !== 422) return false;
+      const type = String(res.headers?.get?.("content-type") ?? "").toLowerCase();
+      return type.split(";")[0].trim() === "application/problem+json";
     } catch {
       return false;
     }
   }
 
+  /** Delivered, or refused for good: either way nothing more to send. */
+  const settled = outcome => outcome !== "failed";
+
+  /** Check-ins in a row that ended still owing something, and the earliest the
+   *  timers may check in again, by `now` — so a laptop that slept through the
+   *  wait tries on its first beat awake. */
+  let failedInARow = 0;
+  let retryAt = 0;
+  /** The earliest the timers may send anything at all — a check-in or the
+   *  heartbeat — because the API asked for the wait (a Retry-After), whichever
+   *  request it answered. Kept apart from the backoff, which is the check-ins'
+   *  own: a check-in that owes nothing more clears that, and not this. */
+  let askedWaitUntil = 0;
+
+  /** A Retry-After, in seconds or as a date, moves the next try out to it. */
+  function waitAsAsked(res) {
+    try {
+      const raw = String(res.headers?.get?.("retry-after") ?? "").trim();
+      if (!raw) return;
+      const at = now().getTime();
+      const ms = /^\d+$/.test(raw) ? Number(raw) * 1000 : Date.parse(raw) - at;
+      if (Number.isFinite(ms) && ms > 0) askedWaitUntil = Math.max(askedWaitUntil, at + Math.min(ms, RETRY_AFTER_MAX_MS));
+    } catch {
+      // A header that will not read: the backoff alone decides.
+    }
+  }
+
+  /** Whether the API's own Retry-After has passed. Never throws. */
+  function askedWaitOver() {
+    try {
+      return now().getTime() >= askedWaitUntil;
+    } catch {
+      return true;
+    }
+  }
+
+  /** After a check-in: one that still owes something waits half a beat before
+   *  the next try — so the first is the next beat, however long this one took
+   *  to fail — then twice that each time, up to the six-hour check-in; one that
+   *  owes nothing clears the wait. Never throws. */
+  function afterCheckIn() {
+    try {
+      if (!checkInDue()) {
+        failedInARow = 0;
+        retryAt = 0;
+        return;
+      }
+      failedInARow++;
+      const wait = Math.min((PING_EVERY_MS / 2) * 2 ** (failedInARow - 1), CHECK_IN_EVERY_MS);
+      retryAt = Math.max(retryAt, now().getTime() + wait);
+    } catch {
+      // A clock that cannot say: the next beat tries again.
+    }
+  }
+
+  /** Whether the timers may check in now: the backoff, and any wait the API
+   *  asked for, both over. Never throws. */
+  function retryDue() {
+    try {
+      return now().getTime() >= retryAt && askedWaitOver();
+    } catch {
+      return true;
+    }
+  }
+
   /** Change the reporter's state, but only while it still belongs to `installId`:
    *  a switch-off that landed in between has the last word. */
   function remember(installId, change) {
@@ -457,14 +844,40 @@ export function createReporter({
     );
   }
 
+  /** Check-ins under way, so a beat that lands during a slow one does not start
+   *  a second beside it and send the same install twice. */
+  let checkingIn = 0;
+
   /** Send whatever is due: a pending deletion, then install or update, then
    *  today's "active". Never throws: a floating rejection here would be an
    *  unhandled one, and Node's answer to those is to end the process. */
   async function checkIn() {
+    checkingIn++;
     try {
       await sendWhatIsDue();
     } catch {
       // A settings file that cannot be written this minute; the next check-in tries again.
+    } finally {
+      checkingIn--;
+      afterCheckIn();
+    }
+  }
+
+  /** Whether a check-in has something to send: the conditions sendWhatIsDue
+   *  acts on, read off the prefs and the clock alone — no network — so the
+   *  heartbeat can ask on every beat. Never throws. */
+  function checkInDue() {
+    try {
+      if (reportsVetoed(env)) return false;
+      const p = prefs.current();
+      const r = p.report;
+      if (r.forget) return true;
+      if (!reportsOn(p, env)) return false;
+      if (!r.installId || r.lastVersion !== facts.version || r.lastActiveDay !== utcDay(now())) return true;
+      if (r.installedAt && !r.activationSent && (r.firstSessionAt || usage.firstUse?.())) return true;
+      return r.rating.score !== null && !r.rating.sent;
+    } catch {
+      return false;
     }
   }
 
@@ -474,45 +887,72 @@ export function createReporter({
     if (reportsVetoed(env)) return;
     const p = prefs.current();
     const { forget } = p.report ?? EMPTY_REPORT;
-    if (forget && (await call("DELETE", `/v1/app/installs/${encodeURIComponent(forget)}`))) {
+    // Only a deletion that landed is done with: one refused stays owed, and is
+    // asked again as a failed one is, rather than dropped.
+    if (forget && (await call("DELETE", `/v1/app/installs/${encodeURIComponent(forget)}`)) === "sent") {
       await prefs.update(prev => (prev.report.forget === forget ? { report: { ...prev.report, forget: "" } } : undefined));
     }
     if (!reportsOn(prefs.current(), env)) return;
 
     // The id is made here, the first time there is something to send under it.
     if (!prefs.current().report.installId) {
+      const fresh = isFirstRun();
       await prefs.update(prev =>
         prev.reports === false || prev.report.installId
           ? undefined
-          // When the id is made is when this install began: the clock the first
-          // session is measured against. Kept here, never sent as a time.
-          : { report: { ...prev.report, installId: randomUUID(), installedAt: now().toISOString() } },
+          // On a first run, when the id is made is when this install began: the
+          // clock the first session is measured against. Kept here, never sent as
+          // a time. A deck that ran here before — one upgraded from a version
+          // with no reports, which had no id to keep — gets none, and is never
+          // timed: its first session was long ago, and "now" would be a lie.
+          : { report: { ...prev.report, installId: randomUUID(), installedAt: fresh ? now().toISOString() : "" } },
       );
     }
     const { installId, lastVersion, lastActiveDay } = prefs.current().report;
     if (!installId) return;
+    const today = utcDay(now());
+    // The CLI versions ride on install, update and "active", and those go out at a
+    // boot more often than not: so they are asked for first, and on a new day
+    // asked again.
+    if (lastVersion !== facts.version || lastActiveDay !== today) await versionsReady();
     if (!lastVersion) {
-      if (await call("POST", "/v1/app/events", { installId, kind: "install", ...factsNow(), ...setupNow() })) {
-        await remember(installId, { lastVersion: facts.version });
+      // The site page the command came from: one an earlier try of this install
+      // could not send, else this run's. Kept until the install gets out, then
+      // never again — only a new install has a page to come from.
+      const ref = refSlug(prefs.current().report.ref) ?? refNow();
+      const body = { installId, kind: "install", ...factsNow(), ...setupNow() };
+      addIf(body, "ref", ref);
+      // Refused by the API is as done as sent: the same body would be refused again.
+      if (settled(await call("POST", "/v1/app/events", body))) {
+        await remember(installId, { lastVersion: facts.version, ref: "" });
+      } else if (ref) {
+        await remember(installId, { ref });
       }
     } else if (lastVersion !== facts.version) {
-      if (await call("POST", "/v1/app/events", { installId, kind: "update", fromVersion: lastVersion, ...factsNow(), ...setupNow() })) {
-        await remember(installId, { lastVersion: facts.version });
+      const body = { installId, kind: "update", fromVersion: lastVersion, ...factsNow(), ...setupNow() };
+      // How it arrived: the deck's own update if it wrote that it started one
+      // from this version, else what the channel says (depth-facts.mjs).
+      addIf(body, "via", updateVia({
+        marker: prefs.current().report.selfUpdate, lastVersion, channel: facts.channel, npx, now: now(),
+      }));
+      if (settled(await call("POST", "/v1/app/events", body))) {
+        await remember(installId, { lastVersion: facts.version, selfUpdate: null });
       }
     }
 
-    const today = utcDay(now());
     if (lastActiveDay !== today) {
       // Usage rides on the "active" event alone, and is read only here — the one
       // report it belongs to — so a checkIn that sends nothing new never asks the
       // deck for its counts.
       const used = coarseUsage(today);
-      if (await call("POST", "/v1/app/events", { installId, kind: "active", ...factsNow(), ...setupNow(), ...used })) {
+      const held = await depthNow();
+      if (settled(await call("POST", "/v1/app/events", { installId, kind: "active", ...factsNow(), ...setupNow(), ...used, ...held }))) {
         if (used.usageDay) usage.markSent(used.usageDay);
         await remember(installId, { lastActiveDay: today });
       }
     }
     await sendActivation();
+    await sendRating();
     await saveUsage();
   }
 
@@ -521,7 +961,8 @@ export function createReporter({
    * after the install it came, in a bucket, and which CLI it came from.
    *
    * Only for an install whose start this deck saw — `installedAt` is made with
-   * the id, so an install from before this version has none and is never
+   * the id, on a first run only, so an install from before this version, or one
+   * whose id was made over an older deck's settings, has none and is never
    * measured: its first session was long ago, and "now" would be a lie. The time
    * is taken from the first use this run heard, so a session that arrived before
    * the first check-in had an id is still dated when it happened. A send that
@@ -540,7 +981,140 @@ export function createReporter({
     const body = { installId: r.installId, kind: "activated", ...factsNow(), ...setupNow() };
     addIf(body, "firstSession", sinceInstallBucket(r.installedAt, r.firstSessionAt));
     addIf(body, "firstProvider", r.firstProvider === "codex" || r.firstProvider === "claude" ? r.firstProvider : undefined);
-    if (await call("POST", "/v1/app/events", body)) await remember(r.installId, { activationSent: true });
+    if (settled(await call("POST", "/v1/app/events", body))) await remember(r.installId, { activationSent: true });
+  }
+
+  /** The deck starting an update of its own — the Upgrade press, the npx
+   *  relaunch onto the latest, or the update it runs while nobody is looking
+   *  (lifecycle.mjs) — written down so the "update" the next version sends can
+   *  say so. Only the version it started from and when; never throws. */
+  async function noteSelfUpdate() {
+    try {
+      const p = prefs.current();
+      if (!reportsOn(p, env) || !p.report.installId) return;
+      await remember(p.report.installId, { selfUpdate: { from: facts.version, at: now().toISOString() } });
+    } catch {
+      // Unsaid, the update is credited to its channel instead.
+    }
+  }
+
+  /** The answer to the deck's one question, said once — tried again at the next
+   *  check-in when it cannot get through. The score and how long the deck had
+   *  been used, as a range; nothing else about the question ever leaves. */
+  async function sendRating() {
+    const p = prefs.current();
+    const r = p.report;
+    if (!reportsOn(p, env) || !r.installId || r.rating.score === null || r.rating.sent) return;
+    const days = usage.daysUsed?.() ?? 0;
+    const body = { installId: r.installId, kind: "rated", ...factsNow(), score: r.rating.score, daysUsed: daysUsedBucket(days) };
+    if (settled(await call("POST", "/v1/app/events", body))) {
+      await remember(r.installId, { rating: { ...prefs.current().report.rating, sent: true } });
+      await keepRating();
+    }
+  }
+
+  /** Should the page ask "How useful is ccdeck to you?" now? Only while reports
+   *  are on and there is an install to send the answer under (rating.mjs says
+   *  the rest). Never throws. */
+  function ratingAsk() {
+    try {
+      const p = prefs.current();
+      if (!reportsOn(p, env) || !p.report.installId) return false;
+      return ratingDue(p.report.rating, usage.daysUsed?.() ?? 0, now(), uptime());
+    } catch {
+      return false;
+    }
+  }
+
+  /** The question answered: kept, then sent. A second answer, from a second tab,
+   *  changes nothing. Resolves to whether it was kept; never throws. */
+  async function rate(score) {
+    try {
+      const picked = scoreOf(score);
+      const p = prefs.current();
+      if (picked === null || !reportsOn(p, env) || !p.report.installId || p.report.rating.score !== null) return false;
+      await remember(p.report.installId, { rating: { ...p.report.rating, score: picked, sent: false } });
+      await keepRating();
+      await sendRating();
+      return prefs.current().report.rating.score === picked;
+    } catch {
+      return false;
+    }
+  }
+
+  /** "Not now": the question waits a month, and after the second time it stops.
+   *  Resolves to whether it was kept; never throws. */
+  async function rateLater() {
+    try {
+      const p = prefs.current();
+      const r = p.report.rating;
+      if (!reportsOn(p, env) || !p.report.installId || r.score !== null) return false;
+      await remember(p.report.installId, { rating: { ...r, later: r.later + 1, laterAt: now().toISOString() } });
+      await keepRating();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** The question's outcome, kept a second time beside prefs.json (ratingFile)
+   *  under the install it belongs to — or taken off the disk once there is no
+   *  install to keep it for, so switching reports off forgets the id there too.
+   *  Never throws. */
+  async function keepRating() {
+    try {
+      if (!ratingKept) return;
+      const p = prefs.current();
+      const { installId, rating } = p.report;
+      await ratingKept.write(reportsOn(p, env) && installId ? { installId, rating } : null);
+    } catch {
+      // Unkept, the outcome still lives in prefs.json, as it always did.
+    }
+  }
+
+  /** The kept outcome, back into the prefs when it is further along than what
+   *  prefs.json says: an older deck wrote that file in between, and its write
+   *  drops every key it does not know, the rating among them — so the question
+   *  would be asked again, and a second answer sent. Only under the install it
+   *  was kept for. Never throws. */
+  async function restoreRating() {
+    try {
+      if (!ratingKept) return;
+      const kept = await ratingKept.read();
+      const p = prefs.current();
+      if (!reportsOn(p, env) || !p.report.installId || kept?.installId !== p.report.installId) return;
+      const rating = normaliseRating(kept.rating);
+      if (ratingStage(rating) > ratingStage(p.report.rating)) await remember(p.report.installId, { rating });
+    } catch {
+      // A kept file that will not read: what prefs.json says stands.
+    }
+  }
+
+  /** Whether a report would go out right now: reports on, the machine not
+   *  vetoing them, and an install id to send under. `ccdeck --uninstall` asks
+   *  before it asks the person anything. Never throws. */
+  async function willReport() {
+    try {
+      await Promise.resolve(ready).catch(() => {});
+      const p = prefs.current();
+      return reportsOn(p, env) && Boolean(p.report.installId);
+    } catch {
+      return false;
+    }
+  }
+
+  /** The install leaving: `ccdeck --uninstall`, with the reason picked off
+   *  UNINSTALL_REASONS if one was. The id stays: a deck run again later is the
+   *  same install coming back. Resolves to whether it got through; never throws. */
+  async function reportUninstall(reason) {
+    try {
+      if (!(await willReport())) return false;
+      const body = { installId: prefs.current().report.installId, kind: "uninstall", ...factsNow() };
+      addIf(body, "reason", UNINSTALL_REASONS.includes(reason) ? reason : undefined);
+      return (await call("POST", "/v1/app/events", body)) === "sent";
+    } catch {
+      return false;
+    }
   }
 
   /** The first session this run heard, sent the moment it lands rather than at
@@ -559,11 +1133,13 @@ export function createReporter({
    *  dropped if it cannot get through, and it never throws. No id yet means the
    *  first check-in has not run, so there is nothing to be online under and
    *  nothing is sent; the check-in that makes the id is what puts this deck
-   *  online, and the ping only keeps that fresh. */
+   *  online, and the ping only keeps that fresh. Not while a Retry-After the
+   *  API sent — on a ping or a check-in — is still running: it asked to be left
+   *  alone that long, and the heartbeat is the request sent most often. */
   async function ping() {
     try {
       const p = prefs.current();
-      if (!reportsOn(p, env) || !p.report.installId) return;
+      if (!reportsOn(p, env) || !p.report.installId || !askedWaitOver()) return;
       await call("POST", "/v1/app/ping", { installId: p.report.installId });
     } catch {
       // The lightest of the niceties: a heartbeat that could not be sent is gone.
@@ -581,6 +1157,7 @@ export function createReporter({
       reports: false,
       report: { ...EMPTY_REPORT, forget: prev.report.installId || prev.report.forget },
     }));
+    await keepRating();
     await checkIn();
   }
 
@@ -592,7 +1169,7 @@ export function createReporter({
   async function reportError(where, error) {
     const p = prefs.current();
     if (!reportsOn(p, env) || !p.report.installId) return false;
-    const message = scrub(error?.message ?? error, home).slice(0, MESSAGE_MAX).trim();
+    const message = scrub(error?.message ?? error, home, root).slice(0, MESSAGE_MAX).trim();
     if (!message) return false;
     const at = now().getTime();
     while (errorsSent.length && at - errorsSent[0] > SAME_ERROR_QUIET_MS) errorsSent.shift();
@@ -600,11 +1177,23 @@ export function createReporter({
     if (errorsSent.length >= ERRORS_PER_HOUR || at - (lastSentAt.get(key) ?? -Infinity) < SAME_ERROR_QUIET_MS) return false;
     errorsSent.push(at);
     lastSentAt.set(key, at);
-    const stack = typeof error?.stack === "string" ? scrub(error.stack, home).slice(0, STACK_MAX) : undefined;
+    const stack = typeof error?.stack === "string" ? scrub(error.stack, home, root).slice(0, STACK_MAX) : undefined;
     // Less the runtime, and less the deviceId — an error is not one of the events
     // the fingerprint rides on, so the personal field never leaves on one.
     const { runtime: _runtime, deviceId: _deviceId, ...fields } = factsNow();
-    return call("POST", "/v1/app/errors", { installId: p.report.installId, ...fields, where, message, stack });
+    return (await call("POST", "/v1/app/errors", { installId: p.report.installId, ...fields, where, message, stack })) === "sent";
+  }
+
+  /** One beat. Whatever a check-in still owes goes first: a boot check-in that
+   *  could not get through (a login item started before the Wi-Fi), or a UTC day
+   *  with no "active" yet. Left to the six-hour timer, that was hours of awake
+   *  time — Node's timers stand still while the machine sleeps, so on a laptop it
+   *  could be days, and a day the deck was used could end unsaid. Not before a
+   *  check-in that could not get through has waited its turn (afterCheckIn), so
+   *  an API that is down is not asked again every ten minutes. Then the ping. */
+  async function beat() {
+    if (!checkingIn && checkInDue() && retryDue()) await checkIn();
+    await ping();
   }
 
   /** The heartbeat timer, rescheduled from itself so each beat carries fresh
@@ -613,7 +1202,8 @@ export function createReporter({
    *  tally if it moved, so a deck that stops loses ten minutes of it at most. */
   function scheduleNextPing() {
     pingTimer = setTimeout(() => {
-      void ping();
+      samplePeak();
+      void beat();
       void saveUsage();
       scheduleNextPing();
     }, PING_EVERY_MS + Math.floor(Math.random() * PING_JITTER_MS));
@@ -621,16 +1211,34 @@ export function createReporter({
   }
 
   /** Check in once the prefs are read, and every few hours after; and beat a
-   *  heartbeat on its own, lighter timer. Both timers never hold the process
-   *  open. The first check-in already puts a freshly launched deck online, so the
-   *  first ping is a full interval out — nothing pings at boot. */
+   *  heartbeat on its own, lighter timer, which also sends whatever a check-in
+   *  still owes (beat). Both timers never hold the process open. The first
+   *  check-in already puts a freshly launched deck online, so the first ping is
+   *  a full interval out — nothing pings at boot. */
   function start() {
-    Promise.all([Promise.resolve(ready).catch(() => {}), Promise.resolve(setupKnown()).catch(() => {})])
+    // start() runs as the deck starts listening (index.mjs), so this is the
+    // launch: process start to ready. A second start() keeps the first answer.
+    if (launchMs == null) {
+      try {
+        const ms = launchedIn();
+        launchMs = Number.isFinite(ms) && ms >= 0 ? ms : null;
+      } catch {
+        launchMs = null;
+      }
+    }
+    samplePeak();
+    const prefsIn = Promise.resolve(ready).catch(() => {});
+    // The CLIs are asked their versions as soon as the prefs say reports are on —
+    // past boot, beside the wait for the setup — so the first check-in, which
+    // waits for the answer, is held up by little or nothing.
+    prefsIn.then(() => { if (reportsOn(prefs.current(), env)) void probeVersions(); }).catch(() => {});
+    Promise.all([prefsIn, Promise.resolve(setupKnown()).catch(() => {})])
       .then(restoreUsage)
+      .then(restoreRating)
       .then(checkIn)
       .then(() => usage.onFirstUse?.(() => void onFirstSession()));
     if (!timer) {
-      timer = setInterval(() => void checkIn(), CHECK_IN_EVERY_MS);
+      timer = setInterval(() => { if (retryDue()) void checkIn(); }, CHECK_IN_EVERY_MS);
       timer.unref?.();
     }
     if (!pingTimer) scheduleNextPing();
@@ -643,7 +1251,10 @@ export function createReporter({
     pingTimer = null;
   }
 
-  return { checkIn, ping, setReports, reportError, restoreUsage, saveUsage, sendActivation, start, stop };
+  return {
+    checkIn, ping, setReports, reportError, restoreUsage, restoreRating, saveUsage, sendActivation, willReport,
+    reportUninstall, noteSelfUpdate, ratingAsk, rate, rateLater, sendRating, start, stop,
+  };
 }
 
 // ── the deck's own providers ─────────────────────────────────────────────────
@@ -654,22 +1265,52 @@ export function createReporter({
 // `--version` that imports it for nothing. The day's usage tally is imported
 // directly: usage-day.mjs imports nothing.
 
-// The CLI versions, detected once in the background, off the boot path. The
-// first send starts the probe (past boot, and not while the machine has vetoed
-// reports) and reads back an empty answer; the version rides along on the
-// reports that follow, once the probe has filled this cache.
+// The CLI versions, detected in the background, off the boot path: the reporter
+// runs this once the prefs say reports are on (never under the machine's veto),
+// and again on each new UTC day (probeVersions). The last answer is kept until
+// the next one lands, and a probe that comes back with less — a wedged shim, a
+// timeout — does not take a version it knew away.
 let cliVersionCache = {};
-let cliProbeStarted = false;
-function deckCliVersions() {
-  if (!cliProbeStarted && !reportsVetoed(process.env)) {
-    cliProbeStarted = true;
-    import("./cli-versions.mjs")
-      .then(m => m.detectCliVersions())
-      .then(v => { cliVersionCache = { ...cliVersionCache, ...v }; })
-      .catch(() => { /* a probe that could not run leaves the versions unsent */ });
-  }
-  return cliVersionCache;
+async function probeCliVersions() {
+  const { detectCliVersions } = await import("./cli-versions.mjs");
+  cliVersionCache = { ...cliVersionCache, ...(await detectCliVersions()) };
+}
+
+/**
+ * Where the question's outcome is kept a second time: rating.json, beside
+ * prefs.json. A 3.36.x deck shares that folder — the desktop app before it
+ * updates, an `npx ccdeck@3.36.9` — and its normalise drops every key it does
+ * not know the first time it writes prefs.json, report.rating among them. It
+ * never writes this file. `dir` is the deck's data dir, read when it is used.
+ * Only the install id and the question's state go in it; `write(null)` takes
+ * it off the disk.
+ */
+export function ratingFile(dir) {
+  const path = () => join(prefsDir(dir ?? deckDataDir()), "rating.json");
+  return {
+    async read() {
+      try {
+        return JSON.parse(stripBom(await readFile(path(), "utf8")));
+      } catch {
+        return null;
+      }
+    },
+    async write(kept) {
+      const at = path();
+      if (!kept) {
+        await unlink(at).catch(err => { if (err?.code !== "ENOENT") throw err; });
+        return;
+      }
+      await mkdir(dirname(at), { recursive: true, mode: 0o700 });
+      await writeFileAtomic(at, JSON.stringify(kept) + "\n");
+      // The install id is kept as close as prefs.json keeps it.
+      await chmod(at, 0o600).catch(() => {});
+    },
+  };
 }
 
 /** The deck's own reporter. */
-export const reporter = createReporter({ versions: deckCliVersions });
+export const reporter = createReporter({
+  versions: () => cliVersionCache, probe: probeCliVersions, depth: deckDepth, npx: isNpxInstall(PKG_ROOT),
+  ratingKept: ratingFile(),
+});