@diffohq/diffo 0.8.0 → 0.10.0

package/dist/cli.mjs

@@ -17,9 +17,24 @@ import { stream, streamSSE } from "hono/streaming";
 * token only: under Claude Code the transient `zsh -c` carries
 * `~/.claude/shell-snapshots/…` in its arguments, which would match HARNESS. */
 const SHELL = /^-?(?:\/[^ ]*\/)?(?:sh|bash|zsh|fish|dash|ksh|csh|tcsh)(?:\s|$)/;
+/** The coding agents whose processes the ancestor walk recognises. Also the
+* vocabulary of the `agent` field in usage data, so a name never travels unless
+* it is on this list. */
+const HARNESS_NAMES = [
+	"claude",
+	"cursor",
+	"codex",
+	"copilot",
+	"windsurf",
+	"zed",
+	"aider",
+	"goose",
+	"cline",
+	"amp"
+];
 /** A harness name at the start of a path segment or token, never inside a word:
 * `/Users/sam/example/` must not read as `amp`. */
-const HARNESS = /(?:^|[/\s@_.-])(?:claude|cursor|codex|copilot|windsurf|zed|aider|goose|cline|amp)/i;
+const HARNESS = new RegExp(`(?:^|[/\\s@_.-])(${HARNESS_NAMES.join("|")})`, "i");
 function ownInvocation() {
 	return {
 		script: process.argv[1] ?? "",
@@ -34,15 +49,26 @@ function isOwnLauncher(command, own) {
 	const tail = own.args.length > 0 ? `${base} ${own.args.join(" ")}` : own.script;
 	return command === tail || command.endsWith(` ${tail}`) || command.endsWith(`/${tail}`);
 }
-function pickSessionAncestor(ancestors, own = ownInvocation()) {
+function pickSession(ancestors, own) {
 	for (const row of ancestors) {
 		const command = row.command.trim();
 		if (SHELL.test(command)) continue;
 		if (isOwnLauncher(command, own)) continue;
-		if (HARNESS.test(command)) return row.pid;
+		const match = HARNESS.exec(command);
+		if (match) return {
+			pid: row.pid,
+			harness: match[1].toLowerCase()
+		};
 	}
 	return null;
 }
+function pickSessionAncestor(ancestors, own = ownInvocation()) {
+	return pickSession(ancestors, own)?.pid ?? null;
+}
+/** Which agent the session is, by the same walk that finds it. */
+function pickSessionHarness(ancestors, own = ownInvocation()) {
+	return pickSession(ancestors, own)?.harness ?? null;
+}
 function readRow(pid) {
 	try {
 		const ppid = Number.parseInt(execFileSync("ps", [
@@ -87,6 +113,16 @@ function detectSessionPid() {
 		return null;
 	}
 }
+/** The agent this CLI runs under, or null from a plain terminal (and on Windows,
+* where the walk is not available). Only ever a name from HARNESS_NAMES. */
+function detectHarness() {
+	if (process.platform === "win32") return null;
+	try {
+		return pickSessionHarness(readAncestors(process.ppid));
+	} catch {
+		return null;
+	}
+}
 //#endregion
 //#region src/shared/review.ts
 const THREAD_INTENTS = ["fix", "question"];
@@ -1019,6 +1055,8 @@ For the reviewer:
   setup              Register diffo with the coding agents on this machine
                      (Claude Code, Cursor, VS Code, Copilot, and the shared
                      ~/.agents skills dir read by Codex, Gemini, Amp, Goose, …)
+  telemetry          Show whether anonymous usage data is on, or turn it
+                     off / on (telemetry off · telemetry on)
 
 For the agent (the AI that wrote the change):
   poll               Wait for the reviewer's feedback (blocking long-poll;
@@ -1358,7 +1396,33 @@ are left as they are, and opening a review keeps installed skills fresh
 automatically after upgrades.
 
 Example:
-  diffo setup`
+  diffo setup`,
+	telemetry: `diffo telemetry: anonymous usage data — see it, turn it off, turn it on
+
+Usage: diffo telemetry [status|on|off]
+
+Diffo reports two small anonymous events per review, "opened" and "finished":
+its version, your OS and Node major, the kind of review (working tree, branch,
+or pull request), which agent opened it, counts (threads, comments, whether
+layers were used, a coarse duration), and whether it runs from a source
+checkout (dev: true, so the maintainers' own use is filtered out). Never code,
+paths, repository or branch names, comment text, or anything about the pull
+request. One random id per machine tells returning machines from new ones;
+turning reporting off deletes it. Nothing is sent until the review page has
+shown you the notice once, and nothing from the review that showed it.
+
+  status   what is on, why it is off, and where the data goes (the default)
+  off      stop reporting on this machine, for good (a machine that has
+           reported sends one last event saying so, then nothing)
+  on       start again (a fresh id, not the old history)
+
+DIFFO_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1 turns it off for one process or
+for a fleet; CI does the same. DIFFO_TELEMETRY_DEBUG=1 writes every payload to
+the server log before it is sent. The full list, and where it goes:
+https://diffohq.github.io/diffo/telemetry
+
+Example:
+  diffo telemetry off`
 };
 function helpFor(topic) {
 	return topic && VERB_HELP[topic] || HELP_TEXT;
@@ -1370,6 +1434,7 @@ const VERBS = /* @__PURE__ */ new Set([
 	"layers",
 	"end",
 	"setup",
+	"telemetry",
 	"status",
 	"stop",
 	"clean",
@@ -1653,9 +1718,38 @@ function parseCleanVerb(rest) {
 		all: parsed.value.values.all === true
 	};
 }
+function parseTelemetryVerb(rest) {
+	const parsed = tryParse(() => parseArgs({
+		args: rest,
+		allowPositionals: true,
+		options: { help: {
+			type: "boolean",
+			short: "h"
+		} }
+	}));
+	if (!parsed.ok) return {
+		kind: "error",
+		message: parsed.message
+	};
+	const { values, positionals } = parsed.value;
+	if (values.help) return {
+		kind: "help",
+		topic: "telemetry"
+	};
+	const action = positionals[0] ?? "status";
+	if (positionals.length > 1 || action !== "status" && action !== "on" && action !== "off") return {
+		kind: "error",
+		message: "telemetry takes one of: status, on, off"
+	};
+	return {
+		kind: "telemetry",
+		action
+	};
+}
 function parseVerb(verb, rest) {
 	if (verb === "layers") return parseLayersVerb(rest);
 	if (verb === "clean") return parseCleanVerb(rest);
+	if (verb === "telemetry") return parseTelemetryVerb(rest);
 	const parsed = tryParse(() => parseArgs({
 		args: rest,
 		allowPositionals: true,
@@ -1865,7 +1959,6 @@ query($owner: String!, $name: String!, $number: Int!) {
             messageHeadline
             committedDate
             author { name user { login avatarUrl } }
-            statusCheckRollup { state }
           }
         }
       }
@@ -1880,6 +1973,24 @@ query($owner: String!, $name: String!, $number: Int!) {
     }
   }
 }`;
+/**
+* CI status, asked for on its own. Reading it needs the checks and statuses
+* scopes, which a fine-grained or SAML-limited token may lack while reading
+* everything else about the pull request; GraphQL answers that with a
+* FORBIDDEN error on this one field, and `gh` turns any error into a failed
+* call. Kept out of the PR query so a token that cannot see CI still opens
+* the review.
+*/
+const CHECKS_QUERY = `
+query($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      commits(last: 1) {
+        nodes { commit { statusCheckRollup { state } } }
+      }
+    }
+  }
+}`;
 /** The pages after the first of each connection the PR query opens. */
 const REVIEWS_QUERY = `
 query($owner: String!, $name: String!, $number: Int!, $cursor: String) {
@@ -2126,18 +2237,32 @@ var GhClient = class {
 			reviewNodes
 		};
 	}
+	/** CI on the head commit, best effort: a token without the checks scope
+	* gets `unknown` and the review opens anyway. Never throws. */
+	async checks(ref) {
+		try {
+			const rollup = ((await this.graphql(ref.host, CHECKS_QUERY, {
+				owner: ref.owner,
+				name: ref.repo,
+				number: ref.number
+			})).repository?.pullRequest?.commits.nodes.at(-1)?.commit)?.statusCheckRollup;
+			return checkState(rollup?.state);
+		} catch {
+			return "unknown";
+		}
+	}
 	async getPr(ref) {
-		const { viewer, pr, reviewNodes } = await this.head(ref);
-		return prInfo(ref, viewer, pr, reviewNodes);
+		const [{ viewer, pr, reviewNodes }, checks] = await Promise.all([this.head(ref), this.checks(ref)]);
+		return prInfo(ref, viewer, pr, reviewNodes, checks);
 	}
 	async listThreads(ref) {
 		const { pr, reviewNodes } = await this.head(ref);
 		return this.conversation(ref, pr, reviewNodes);
 	}
 	async fetchPr(ref) {
-		const { viewer, pr, reviewNodes } = await this.head(ref);
+		const [{ viewer, pr, reviewNodes }, checks] = await Promise.all([this.head(ref), this.checks(ref)]);
 		return {
-			pr: prInfo(ref, viewer, pr, reviewNodes),
+			pr: prInfo(ref, viewer, pr, reviewNodes, checks),
 			threads: await this.conversation(ref, pr, reviewNodes)
 		};
 	}
@@ -2251,9 +2376,8 @@ var GhClient = class {
 	}
 };
 /** The PR query's answer as a PrInfo, with every review page in hand. */
-function prInfo(ref, viewer, pr, reviewNodes) {
-	const commitNodes = pr.commits.nodes ?? [];
-	const commits = commitNodes.map((n) => {
+function prInfo(ref, viewer, pr, reviewNodes, checks) {
+	const commits = (pr.commits.nodes ?? []).map((n) => {
 		const c = n.commit;
 		const author = c.author;
 		return {
@@ -2263,7 +2387,6 @@ function prInfo(ref, viewer, pr, reviewNodes) {
 			at: String(c.committedDate ?? "")
 		};
 	});
-	const rollup = (commitNodes.at(-1)?.commit)?.statusCheckRollup;
 	const reviews = reviewNodes.map((r) => ({
 		id: String(r.id),
 		author: user(r.author),
@@ -2296,7 +2419,7 @@ function prInfo(ref, viewer, pr, reviewNodes) {
 			sha: String(pr.headRefOid)
 		},
 		commits,
-		checks: { state: checkState(rollup?.state) },
+		checks: { state: checks },
 		reviews: reviews.filter((r) => r.state !== "PENDING"),
 		approvals: [...latest.values()].filter((s) => s === "APPROVED").length,
 		changesRequested: [...latest.values()].filter((s) => s === "CHANGES_REQUESTED").length,
@@ -2514,6 +2637,25 @@ function branchExists(root, branch) {
 		return err.status !== 1;
 	}
 }
+/** {@link branchExists}, off the event loop, for the daemon's background sweep
+* over every repo it has ever reviewed. Same lean: true unless git said no. */
+async function branchExistsAsync(root, branch) {
+	try {
+		await execFileAsync("git", [
+			"show-ref",
+			"--verify",
+			"--quiet",
+			`refs/heads/${branch}`
+		], {
+			cwd: root,
+			encoding: "utf-8",
+			maxBuffer: MAX_BUFFER
+		});
+		return true;
+	} catch (err) {
+		return err.code !== 1;
+	}
+}
 /**
 * The name of the linked worktree we're in, or null in the main one. A linked
 * worktree's git dir is `<main>/.git/worktrees/<name>`, while the main worktree's
@@ -3148,7 +3290,17 @@ const SCHEMA_VERSION = 3;
 const REVIEWS_RESHAPED_AT = 2;
 var DiffoDb = class {
 	db;
+	closed = false;
 	path;
+	/**
+	* Opening is cheap on purpose: the schema, and one SQL statement for the TTL.
+	* Nothing here touches the filesystem beyond the database file, and nothing
+	* asks git. It used to: every open checked every review's branch with a
+	* `git show-ref`, across every repo this machine ever reviewed — 73 git
+	* processes, 1.5s, on a database a few weeks old, and an open constructs
+	* this five times. The checks live in {@link pruneRepo} (one repo, before its
+	* review loads) and {@link maintain} (everything, in the daemon's background).
+	*/
 	constructor(path = defaultDbPath()) {
 		this.path = path;
 		mkdirSync(dirname(path), {
@@ -3160,7 +3312,7 @@ var DiffoDb = class {
 		chmodSync(path, 384);
 		this.db.exec("PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 3000; PRAGMA journal_size_limit = 4194304;");
 		this.ensureSchema();
-		this.pruneVanishedRepos();
+		this.pruneExpiredReviews();
 	}
 	/**
 	* Creates what is missing and retires what is unknown. Runs at open, and
@@ -3229,38 +3381,69 @@ var DiffoDb = class {
 		}
 	}
 	/**
-	* Rows about a worktree that is gone can never be reached again — the path *is*
-	* the key. An unmounted volume looks the same as a deleted worktree, so its rows
-	* go too; the `servers` row needs its process dead as well, or a live server's
-	* claim could be dropped over a moment of unreachability.
+	* Reviews untouched for `REVIEW_TTL_DAYS` go on every open: one statement,
+	* no git, and the backstop for everything the two targeted sweeps below leave
+	* for later.
+	*/
+	pruneExpiredReviews() {
+		const cutoff = (/* @__PURE__ */ new Date(Date.now() - 5184e6)).toISOString();
+		const stale = this.db.prepare("DELETE FROM reviews WHERE updated_at < ?").run(cutoff);
+		if (Number(stale.changes) > 0) this.checkpoint();
+	}
+	/**
+	* Retire this one repo's reviews for branches it no longer has. The server
+	* runs it before loading the review it is about to serve, so a branch
+	* deleted since the last server start is forgotten before a namesake could
+	* inherit its threads. Only this repo's branches are asked about, so the
+	* cost is a handful of `git show-ref`s, once per server start, never per CLI
+	* call. Branch existence is asked of git rather than assumed — when git can't
+	* answer the row is kept, because guessing here deletes threads.
+	*/
+	pruneRepo(repoPath) {
+		const rows = this.db.prepare("SELECT DISTINCT branch FROM reviews WHERE repo_path = ?").all(repoPath);
+		let dropped = 0;
+		for (const { branch } of rows) {
+			if (branch === "" || branchExists(repoPath, branch)) continue;
+			dropped += this.dropReviews(repoPath, branch);
+		}
+		return dropped;
+	}
+	/**
+	* The full sweep, for a long-lived process with time on its hands: rows about
+	* repos that are gone, and reviews for branches that are. The daemon runs it
+	* once, a few seconds after it is serving; `diffo clean` runs it on demand.
+	* Git is asked asynchronously and one repo at a time, so a sweep over every
+	* repo this machine ever reviewed never blocks a request. A `close()` midway
+	* ends it quietly between steps.
+	*
+	* Rows about a worktree that is gone can never be reached again — the path
+	* *is* the key. An unmounted volume looks the same as a deleted worktree, so
+	* its rows go too; the `servers` row needs its process dead as well, or a live
+	* server's claim could be dropped over a moment of unreachability.
 	*/
-	pruneVanishedRepos() {
-		for (const { repo_path } of this.distinctRepoPaths("reviews")) if (!existsSync(repo_path)) this.db.prepare("DELETE FROM reviews WHERE repo_path = ?").run(repo_path);
+	async maintain() {
+		const report = { reviews: 0 };
+		if (this.closed) return report;
+		for (const { repo_path } of this.distinctRepoPaths("reviews")) if (!existsSync(repo_path)) report.reviews += this.dropReviews(repo_path);
 		for (const { repo_path } of this.distinctRepoPaths("repo_ports")) if (!existsSync(repo_path)) this.db.prepare("DELETE FROM repo_ports WHERE repo_path = ?").run(repo_path);
 		const worktrees = this.db.prepare("SELECT worktree_path, repo_path FROM worktrees").all();
 		for (const { worktree_path, repo_path } of worktrees) if (!existsSync(repo_path)) this.db.prepare("DELETE FROM worktrees WHERE worktree_path = ?").run(worktree_path);
 		const servers = this.db.prepare("SELECT repo_path, pid FROM servers").all();
 		for (const { repo_path, pid } of servers) if (!existsSync(repo_path) && !pidAlive$1(pid)) this.db.prepare("DELETE FROM servers WHERE repo_path = ?").run(repo_path);
-		this.pruneStaleReviews();
-	}
-	/**
-	* Reviews the reviewer can never return to: a branch that no longer exists, or
-	* one untouched for `REVIEW_TTL_DAYS`. Branch existence is asked of git rather
-	* than assumed — if git can't answer the row is kept, because guessing here
-	* deletes threads.
-	*/
-	pruneStaleReviews() {
-		const cutoff = (/* @__PURE__ */ new Date(Date.now() - 5184e6)).toISOString();
-		const stale = this.db.prepare("DELETE FROM reviews WHERE updated_at < ?").run(cutoff);
-		if (Number(stale.changes) > 0) {
-			this.checkpoint();
-			return;
-		}
 		const rows = this.db.prepare("SELECT DISTINCT repo_path, branch FROM reviews").all();
 		for (const { repo_path, branch } of rows) {
-			if (branch === "" || branchExists(repo_path, branch)) continue;
-			this.db.prepare("DELETE FROM reviews WHERE repo_path = ? AND branch = ?").run(repo_path, branch);
+			if (branch === "") continue;
+			const exists = await branchExistsAsync(repo_path, branch);
+			if (this.closed) return report;
+			if (!exists) report.reviews += this.dropReviews(repo_path, branch);
 		}
+		if (report.reviews > 0) this.checkpoint();
+		return report;
+	}
+	/** Every review of a repo, or only one branch's. Returns the rows dropped. */
+	dropReviews(repoPath, branch) {
+		const result = branch === void 0 ? this.db.prepare("DELETE FROM reviews WHERE repo_path = ?").run(repoPath) : this.db.prepare("DELETE FROM reviews WHERE repo_path = ? AND branch = ?").run(repoPath, branch);
+		return Number(result.changes);
 	}
 	/** Fold the write-ahead log back into the database file and truncate it. WAL
 	* only shrinks at a checkpoint, which a long-lived server never reaches. */
@@ -3358,6 +3541,7 @@ var DiffoDb = class {
 		else this.db.prepare("DELETE FROM servers WHERE repo_path = ? AND port = ?").run(repoPath, port);
 	}
 	close() {
+		this.closed = true;
 		this.db.close();
 	}
 };
@@ -3423,6 +3607,9 @@ var DeliveryQueue = class DeliveryQueue {
 	stalled = false;
 	stallTimer = null;
 	betweenPolls = false;
+	/** Why the agent is parked between polls: a reply just landed, or its poll
+	* ended on its own and the re-poll is expected. */
+	parked = "replied";
 	graceTimer = null;
 	lastDetach = null;
 	since = Date.now();
@@ -3570,7 +3757,7 @@ var DeliveryQueue = class DeliveryQueue {
 		if (this.awaitingReply) return this.stalled ? "stalled" : "delivered";
 		if (this.outlining() !== null) return "delivered";
 		if (this.waiter) return "polling";
-		if (this.betweenPolls) return "replied";
+		if (this.betweenPolls) return this.parked;
 		return this.lastDetach ?? "no-agent";
 	}
 	hasListener() {
@@ -3623,9 +3810,10 @@ var DeliveryQueue = class DeliveryQueue {
 		if (this.stallTimer !== null) clearTimeout(this.stallTimer);
 		this.stallTimer = null;
 	}
-	armGrace() {
+	armGrace(why = "replied") {
 		this.clearGrace();
 		this.betweenPolls = true;
+		this.parked = why;
 		const drop = () => {
 			this.graceTimer = null;
 			if (!this.betweenPolls) return;
@@ -3660,6 +3848,24 @@ var DeliveryQueue = class DeliveryQueue {
 		this.graceTimer = null;
 		this.betweenPolls = false;
 	}
+	/**
+	* A poll ended without `diffo end`: the poll window closed, or the process
+	* died under its harness. Neither means the agent left — the CLI tells the
+	* session to re-run the poll, and it usually does within moments — so the
+	* reviewer keeps an agent instead of being asked to invite one again. The
+	* agent parks in the same grace a reply uses: a named session is watched
+	* until its process is gone (or the cap), an unnamed one gets the fixed
+	* window. Only a session that is already dead reads as gone at once. When
+	* the grace runs out without a re-poll, the reason it fell to waiting is
+	* still the dead poll.
+	*/
+	pollDropped() {
+		this.lastDetach = "disconnected";
+		const pid = this.owner;
+		const isAlive = this.liveness.isAlive ?? pidAlive;
+		if (!(pid !== null && !isAlive(pid)) && !this.awaitingReply && this.outlining() === null) this.armGrace("repolling");
+		this.notify();
+	}
 	enqueueThreads(threadIds) {
 		const bucket = this.bucket();
 		for (const id of threadIds) bucket.threads.add(id);
@@ -3747,8 +3953,7 @@ var DeliveryQueue = class DeliveryQueue {
 			onAbort?.(() => {
 				if (this.waiter === waiter) {
 					this.releaseWaiter(null);
-					this.lastDetach = "disconnected";
-					this.notify();
+					this.pollDropped();
 				}
 			});
 		});
@@ -5993,6 +6198,286 @@ var ChangesetStore = class {
 	}
 };
 //#endregion
+//#region src/server/telemetry.ts
+/**
+* Anonymous usage data, Homebrew-style: on by default, announced in the review
+* page before the first event leaves, one command or variable to turn off. Two
+* events per review, `review_opened` and `review_finished`, and one last
+* `telemetry_disabled` when a machine that has reported turns it off; `send`
+* below is the authoritative list of what they carry, and the docs page links here. Never
+* paths, repo or branch names, code, comment text, or anything IP-derived. The
+* one identifier is a random UUID per machine, in a file of its own
+* (`~/.diffo/telemetry-id`) rather than the database: `DIFFO_DB` moves the
+* database, and one machine must count as one machine wherever it keeps state.
+*/
+const TELEMETRY_DOCS_URL = "https://diffohq.github.io/diffo/telemetry";
+/** PostHog Cloud, EU region. */
+const TELEMETRY_ENDPOINT = "https://eu.i.posthog.com/capture/";
+/** Public and write-only by design: adds events, reads nothing. */
+const TELEMETRY_KEY = "phc_nZqoJQbyccraPZwxsHaaAUPjf5z8k2QqdnWYedyhQzCx";
+/** A blocked host must never be felt. */
+const SEND_TIMEOUT_MS = 2e3;
+function defaultMachineIdPath() {
+	return join(homedir(), ".diffo", "telemetry-id");
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** One UUID and a newline, owner-readable like the database next to it. */
+function fileMachineIdStore(path = defaultMachineIdPath()) {
+	const read = () => {
+		try {
+			const id = readFileSync(path, "utf8").trim();
+			return UUID.test(id) ? id : null;
+		} catch {
+			return null;
+		}
+	};
+	const write = (id, flag) => {
+		try {
+			mkdirSync(dirname(path), {
+				recursive: true,
+				mode: 448
+			});
+			writeFileSync(path, `${id}\n`, {
+				flag,
+				mode: 384
+			});
+			return id;
+		} catch (err) {
+			if (flag === "wx" && err.code === "EEXIST") return read() ?? write(id, "w");
+			return null;
+		}
+	};
+	return {
+		read,
+		claim: (id) => write(id, "wx"),
+		clear() {
+			try {
+				rmSync(path, { force: true });
+			} catch {}
+		}
+	};
+}
+const KEY = {
+	enabled: "telemetry.enabled",
+	notice: "telemetry.notice",
+	noticeAt: "telemetry.notice_at"
+};
+const DEBUG_VAR = "DIFFO_TELEMETRY_DEBUG";
+/** `0`, `false` and the empty string mean unset, as most tools read them. */
+function isSet(value) {
+	if (value === void 0) return false;
+	const v = value.trim().toLowerCase();
+	return v !== "" && v !== "0" && v !== "false";
+}
+/** The variable that turns usage data off, in precedence order, or null. */
+function envOptOut(env) {
+	if (isSet(env.DO_NOT_TRACK)) return "DO_NOT_TRACK";
+	if (isSet(env.DIFFO_TELEMETRY_DISABLED)) return "DIFFO_TELEMETRY_DISABLED";
+	if (isSet(env.CI)) return "CI";
+	return null;
+}
+function reviewKindOf(spec, pr) {
+	if (pr) return "pr";
+	return spec.kind === "branch" ? "branch" : "tree";
+}
+const AGENT_NAMES = /* @__PURE__ */ new Set([...HARNESS_NAMES, "unknown"]);
+/** Whatever the CLI reported, narrowed to a name this build knows. */
+function agentNameOf(raw) {
+	return typeof raw === "string" && AGENT_NAMES.has(raw) ? raw : "other";
+}
+/** Coarse on purpose: low cardinality, and nobody's afternoon timed. */
+function durationBucket(ms) {
+	const min = ms / 6e4;
+	if (min < 5) return "<5m";
+	if (min < 15) return "5-15m";
+	if (min < 30) return "15-30m";
+	if (min < 60) return "30-60m";
+	return "1h+";
+}
+var Telemetry = class {
+	store;
+	ids;
+	env;
+	fetchImpl;
+	now;
+	log;
+	dev;
+	base;
+	/** Decided at open and kept for the finish, so the review that first shows the
+	* notice reports nothing at all. Undefined until the first open. */
+	armedReview;
+	openedAt;
+	inFlight = [];
+	/** The id this process settled on when the disk refused to keep one. */
+	fallbackId;
+	constructor(deps) {
+		this.store = deps.store;
+		this.ids = deps.ids;
+		this.env = deps.env ?? process.env;
+		this.fetchImpl = deps.fetch ?? globalThis.fetch;
+		this.now = deps.now ?? Date.now;
+		this.log = deps.log ?? (() => {});
+		this.dev = deps.dev ?? false;
+		this.base = {
+			version: deps.version ?? VERSION,
+			platform: deps.platform ?? process.platform,
+			arch: deps.arch ?? process.arch,
+			node: deps.nodeMajor ?? Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10),
+			dev: this.dev
+		};
+	}
+	status() {
+		const shared = {
+			notice: this.notice(),
+			machineId: this.readMachineId(),
+			dev: this.dev,
+			docs: TELEMETRY_DOCS_URL
+		};
+		const variable = envOptOut(this.env);
+		if (variable !== null) return {
+			enabled: false,
+			source: "env",
+			variable,
+			...shared
+		};
+		if (this.store.get(KEY.enabled) === "false") return {
+			enabled: false,
+			source: "setting",
+			...shared
+		};
+		return {
+			enabled: true,
+			source: "default",
+			...shared
+		};
+	}
+	/**
+	* Either way the machine id goes: back on means a new history, not the old one.
+	* Turning off a machine that has reported sends one last `telemetry_disabled`,
+	* so opt-outs can be counted; a machine that never reported, or one an
+	* environment variable already silenced, sends nothing. Returns whether it did.
+	*/
+	setEnabled(on, source) {
+		const farewell = !on && this.status().enabled && this.readMachineId() !== null;
+		if (farewell) this.send("telemetry_disabled", { source });
+		this.store.set(KEY.enabled, on ? "true" : "false");
+		this.ids.clear();
+		this.fallbackId = void 0;
+		if (on) this.store.set(KEY.notice, "acknowledged");
+		return farewell;
+	}
+	/** The review page rendered the notice; nothing is sent before this. */
+	noticeShown() {
+		if (this.notice() !== "pending") return;
+		this.store.set(KEY.notice, "shown");
+		this.store.set(KEY.noticeAt, new Date(this.now()).toISOString());
+	}
+	/** The reviewer dismissed the notice; it stays gone. */
+	acknowledge() {
+		if (this.notice() === "pending") this.noticeShown();
+		this.store.set(KEY.notice, "acknowledged");
+	}
+	/** A `diffo` open landed. Decides whether this review reports, and says so. */
+	reviewOpened(props) {
+		const armed = this.armed();
+		this.armedReview = armed;
+		this.openedAt = this.now();
+		if (armed) this.send("review_opened", {
+			kind: props.kind,
+			agent: props.agent
+		});
+		return armed;
+	}
+	/** Only for a review that was opened reporting, and is still on. */
+	reviewFinished(props) {
+		if (this.armedReview !== true || !this.armed()) return;
+		this.send("review_finished", {
+			kind: props.kind,
+			threads: props.threads,
+			comments: props.comments,
+			layers: props.layers,
+			...props.event ? { event: props.event } : {},
+			...this.openedAt !== void 0 ? { duration: durationBucket(this.now() - this.openedAt) } : {}
+		});
+	}
+	/** Every send so far, settled. Tests, and an orderly shutdown. */
+	async flush() {
+		await Promise.all(this.inFlight.splice(0));
+	}
+	notice() {
+		const raw = this.store.get(KEY.notice);
+		return raw === "shown" || raw === "acknowledged" ? raw : "pending";
+	}
+	/** On, and the notice has been on a screen at least once. */
+	armed() {
+		return this.status().enabled && this.notice() !== "pending";
+	}
+	readMachineId() {
+		return this.ids.read() ?? this.fallbackId ?? null;
+	}
+	/** The id on disk, minted on the first send; a disk that refuses it gets one
+	* id per process rather than one per event. */
+	machineId() {
+		const existing = this.readMachineId();
+		if (existing) return existing;
+		const id = randomUUID();
+		const claimed = this.ids.claim(id);
+		if (claimed === null) this.fallbackId = id;
+		return claimed ?? id;
+	}
+	send(event, properties) {
+		const payload = {
+			api_key: TELEMETRY_KEY,
+			event,
+			distinct_id: this.machineId(),
+			timestamp: new Date(this.now()).toISOString(),
+			properties: {
+				$lib: "diffo",
+				$lib_version: this.base.version,
+				$process_person_profile: false,
+				$geoip_disable: true,
+				...this.base,
+				...properties
+			}
+		};
+		if (isSet(this.env[DEBUG_VAR])) this.log(`telemetry: ${JSON.stringify(payload)}`);
+		let request;
+		try {
+			request = this.fetchImpl(TELEMETRY_ENDPOINT, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(payload),
+				signal: AbortSignal.timeout(SEND_TIMEOUT_MS)
+			});
+		} catch {
+			request = Promise.resolve();
+		}
+		const debug = isSet(this.env[DEBUG_VAR]);
+		this.inFlight.push(request.then((res) => {
+			if (debug) this.log(`telemetry: ${event} → ${res?.status ?? "sent"}`);
+		}, (err) => {
+			if (debug) this.log(`telemetry: ${event} failed: ${err?.message ?? String(err)}`);
+		}));
+	}
+};
+/** `diffo telemetry [status|on|off]`, for a human's terminal. */
+function describeTelemetry(status, asked, farewell = false) {
+	const lines = [];
+	if (status.enabled) {
+		lines.push(asked === "on" ? "usage data: on (turned on)" : "usage data: on", "  what: two anonymous events per review (opened, finished) — version, OS,", "        kind of review, agent, counts. Never code, paths, or comment text", "  off:  diffo telemetry off, or DIFFO_TELEMETRY_DISABLED=1 (DO_NOT_TRACK=1 counts too)");
+		if (status.notice === "pending") lines.push("  note: nothing has been sent yet; the review page shows a notice first");
+		if (status.dev) lines.push("  dev:  running from a source checkout; every event carries dev: true");
+	} else {
+		const why = status.source === "env" ? `${status.variable} is set` : asked === "off" ? "turned off" : "turned off with `diffo telemetry off`";
+		lines.push(`usage data: off (${why})`);
+		if (asked === "off" && farewell) lines.push("  sent: one last event saying this machine turned it off; nothing follows");
+		if (asked === "on" && status.source === "env") lines.push(`  note: it stays off while ${status.variable} is set`);
+		if (status.source === "setting") lines.push("  on:   diffo telemetry on");
+	}
+	lines.push(`  more: ${status.docs}`);
+	return lines.join("\n");
+}
+//#endregion
 //#region src/server/watcher.ts
 const DEBOUNCE_MS = 300;
 const MAX_COOLDOWN_MS = 5e3;
@@ -6115,6 +6600,9 @@ const POLL_HEARTBEAT_MS = 15e3;
 * aborts, and a listening poll blocks the daemon's idle reap.
 */
 const POLL_MAX_MS = 18e5;
+/** How long after listening the daemon starts the machine-wide database sweep:
+* past the first page load, which is what the sweep must never delay. */
+const MAINTENANCE_DELAY_MS = 5e3;
 function createApp(ctx, store, review, queue) {
 	const app = new Hono();
 	if (review && queue) queue.onBatchClosed((closed) => {
@@ -6185,6 +6673,31 @@ function createApp(ctx, store, review, queue) {
 		ctx.uiSettings.set("theme", theme);
 		return c.json({ ok: true });
 	});
+	const reviewKind = () => reviewKindOf(ctx.spec, ctx.pr !== void 0);
+	app.get("/api/telemetry", (c) => {
+		if (!ctx.telemetry) return c.json({ error: "telemetry unavailable" }, 503);
+		return c.json(ctx.telemetry.status());
+	});
+	app.put("/api/telemetry", async (c) => {
+		if (!ctx.telemetry) return c.json({ error: "telemetry unavailable" }, 503);
+		const body = await c.req.json().catch(() => null);
+		if (typeof body?.enabled === "boolean") ctx.telemetry.setEnabled(body.enabled, "ui");
+		else if (body?.notice === "shown") ctx.telemetry.noticeShown();
+		else if (body?.notice === "acknowledged") ctx.telemetry.acknowledge();
+		else return c.json({ error: "need {enabled: boolean} or {notice: \"shown\" | \"acknowledged\"}" }, 400);
+		return c.json(ctx.telemetry.status());
+	});
+	app.post("/api/telemetry/opened", async (c) => {
+		const body = await c.req.json().catch(() => null);
+		const armed = ctx.telemetry?.reviewOpened({
+			kind: reviewKind(),
+			agent: agentNameOf(body?.agent)
+		}) ?? false;
+		return c.json({
+			ok: true,
+			armed
+		});
+	});
 	const repoInfo = () => store?.get().repo ?? {
 		path: resolve(ctx.root),
 		name: "",
@@ -6543,6 +7056,13 @@ function createApp(ctx, store, review, queue) {
 			queue.enqueueFinish(coverage);
 		}
 		review.clearWithheld(batch.map((t) => t.id));
+		ctx.telemetry?.reviewFinished({
+			kind: reviewKind(),
+			threads: batch.length,
+			comments: batch.reduce((n, t) => n + t.messages.filter((m) => m.author === "reviewer").length, 0),
+			layers: (review.get().layers?.items.length ?? 0) > 0,
+			...event !== null ? { event } : {}
+		});
 		return c.json({
 			threads: review.get().threads,
 			prompt,
@@ -6865,11 +7385,22 @@ function startServer(options) {
 		throw new RepoAlreadyServedError(holder);
 	}
 	db.setPreferredPort(resolve(options.root), options.port);
+	const log = (message) => console.log(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString("en-GB", { hour12: false })}] ${message}`);
+	const retired = db.pruneRepo(resolve(options.root));
+	if (retired > 0) log(`retired ${retired} ${retired === 1 ? "review" : "reviews"} for branches this repo no longer has`);
 	const review = new ReviewStore(options.root, db, options.spec);
 	const queue = new DeliveryQueue();
 	queue.rescope(store.get().repo.branch);
 	rehydrateQueue(review, queue);
-	const log = (message) => console.log(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString("en-GB", { hour12: false })}] ${message}`);
+	const telemetry = options.telemetry ?? new Telemetry({
+		store: {
+			get: (key) => db.getUiSetting(key),
+			set: (key, value) => db.setUiSetting(key, value)
+		},
+		ids: fileMachineIdStore(),
+		log,
+		dev: SRC_STAMP !== null || IS_DEV
+	});
 	queue.subscribe((presence) => log(`agent ${presence}`));
 	const unsubscribeBatch = queue.onBatchClosed((closed) => {
 		const took = Math.round((closed.closedAt - closed.deliveredAt) / 1e3);
@@ -6931,6 +7462,7 @@ function startServer(options) {
 		...options,
 		...prContext ? { pr: prContext } : {},
 		idle,
+		telemetry,
 		onShutdownRequest: options.onShutdownRequest ?? (() => process.exit(0)),
 		uiSettings: {
 			get: (key) => db.getUiSetting(key),
@@ -6942,6 +7474,12 @@ function startServer(options) {
 		port: options.port,
 		hostname: "127.0.0.1"
 	});
+	const maintenance = setTimeout(() => {
+		db.maintain().then((report) => {
+			if (report.reviews > 0) log(`retired ${report.reviews} ${report.reviews === 1 ? "review" : "reviews"} whose repo or branch is gone`);
+		}).catch((err) => log(`database sweep failed: ${err.message}`));
+	}, MAINTENANCE_DELAY_MS);
+	maintenance.unref();
 	const deregister = () => {
 		try {
 			db.removeServer(review.repoPath, options.port);
@@ -6963,7 +7501,9 @@ function startServer(options) {
 		store,
 		review,
 		queue,
+		telemetry,
 		stopWatching: async () => {
+			clearTimeout(maintenance);
 			idle?.stop();
 			puller?.stop();
 			unsubscribeReconcile();
@@ -7569,6 +8109,7 @@ if (command.kind === "setup") {
 if (command.kind === "clean") {
 	const db = new DiffoDb();
 	try {
+		await db.maintain();
 		const entries = sweepWorktrees(db, void 0, {
 			force: command.force,
 			all: command.all
@@ -7686,6 +8227,21 @@ function printBaseHint(spec, files) {
 	if (!hint) return;
 	console.log(`this branch has ${hint.commits} ${hint.commits === 1 ? "commit" : "commits"} since ${hint.base}. Review them with \`diffo --base ${hint.base}\``);
 }
+/**
+* Tells the server a review was opened, and by which agent — the server decides
+* whether that is reported (see server/telemetry.ts). Best effort: an open never
+* waits on, or fails over, usage data.
+*/
+async function announceOpen(port) {
+	try {
+		await fetch(apiUrl(port, "/api/telemetry/opened"), {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ agent: detectHarness() ?? "unknown" }),
+			signal: AbortSignal.timeout(2e3)
+		});
+	} catch {}
+}
 async function fetchChangesetInfo(port) {
 	try {
 		return await (await fetch(apiUrl(port, "/api/changeset"), { signal: AbortSignal.timeout(2e3) })).json();
@@ -7829,6 +8385,26 @@ if (command.kind === "stop") {
 	}
 	process.exit(0);
 }
+if (command.kind === "telemetry") {
+	const db = new DiffoDb();
+	try {
+		const telemetry = new Telemetry({
+			store: {
+				get: (key) => db.getUiSetting(key),
+				set: (key, value) => db.setUiSetting(key, value)
+			},
+			ids: fileMachineIdStore(),
+			log: (line) => process.stderr.write(`diffo: ${line}\n`),
+			dev: SRC_STAMP !== null || process.env.ENV === "development"
+		});
+		const farewell = command.action === "status" ? false : telemetry.setEnabled(command.action === "on", "cli");
+		console.log(describeTelemetry(telemetry.status(), command.action, farewell));
+		await telemetry.flush();
+	} finally {
+		db.close();
+	}
+	process.exit(0);
+}
 if (command.kind === "poll") {
 	const port = await requireServer();
 	process.stderr.write("diffo: waiting for the reviewer. Keep this process attended: a tracked\nbackground task or the foreground, never detached. If it dies, just\nre-run it; feedback is held in the review and survives.\n");
@@ -8047,6 +8623,7 @@ if (existing !== null && takeOverPort === null) {
 	const url = reviewUrl(existing.port);
 	console.log(prOpen ? "diffo is already watching this pull request" : "diffo is already watching this repo");
 	await warnSpecMismatch(existing.port, spec);
+	await announceOpen(existing.port);
 	console.log(`→ ${url}`);
 	await printAgentNextStep(existing.port, prOpen?.pr);
 	process.exit(0);
@@ -8066,6 +8643,7 @@ if (existing !== null && takeOverPort !== null) {
 }
 if (!command.foreground) {
 	const daemonPort = await requireServer(command.port, spec.kind === "branch" ? spec.base : void 0, SRC_STAMP, prOpen ? command.target : void 0);
+	await announceOpen(daemonPort);
 	const url = reviewUrl(daemonPort);
 	await printChangesetSummary(daemonPort);
 	console.log(`→ ${url}`);
@@ -8107,6 +8685,10 @@ try {
 	}
 	throw err;
 }
+started.telemetry.reviewOpened({
+	kind: reviewKindOf(spec, prOpen !== null),
+	agent: detectHarness() ?? "unknown"
+});
 const { stats, repo } = started.store.get();
 const url = reviewUrl(port);
 const label = prOpen ? `pull request #${prOpen.pr.number} "${prOpen.pr.title}"` : specLabel(spec);