prreviewbuddy 0.62.0 → 0.63.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.63.0
+
+**Telemetry now records first use.** With telemetry on, PR Review Buddy sends one more event,
+`installation_started`, once per installation: the first time you run `prreviewbuddy` on its own,
+`review`, `open` or `agents`. It marks first use, not when the package was installed, and it adds
+no field. It carries the installation id, version, platform and a timestamp, and no agent. If it
+cannot reach the server it is tried again on your next such command, and never again once it
+arrives. The server keeps one per installation, so a repeat is acknowledged and not stored. Until now only reviews were counted, so somebody who tried PR Review Buddy and stopped
+before a review was invisible. Installations from before this version send it once, on their first
+command after upgrading.
+
+`prreviewbuddy` on its own now shows the one-time telemetry notice too, because it can now send.
+Its usage text is unchanged. An installation that already saw the telemetry notice, or turned telemetry
+on, is told once about this one addition; one that turned it off is told nothing. `--help`, `--version` and `config` send nothing and show no notice.
+`prreviewbuddy config set telemetry-upload off` and `PRB_TELEMETRY=off` stop this event exactly as
+they stop the others. The privacy page lists it: https://prreviewbuddy.com/privacy
+
 ## 0.62.0
 
 **Buddy AI has its own keys.** On a review, ⌘K B opens a Buddy AI menu. B O opens Buddy AI with

package/dist/{delete_review-LzUgEUzN.js → delete_review-CeJo9t7h.js}

@@ -13586,6 +13586,13 @@ var TIMEOUT_MS = 1500;
 */
 function project(record) {
 	const event = record.event;
+	if (event.event === "installation_started") return {
+		event: event.event,
+		installationId: record.anonymousId,
+		cliVersion: record.cliVersion,
+		platform: record.platform,
+		occurredAt: record.at
+	};
 	if (event.event !== "review_started" && event.event !== "review_finished") return null;
 	const base = {
 		event: event.event,
@@ -13614,13 +13621,38 @@ function send(record) {
 		if (!telemetryUploadEnabled()) return;
 		const payload = project(record);
 		if (!payload) return;
-		fetch(endpoint(), {
+		post(payload);
+	} catch {}
+}
+/**
+* Send one record and say whether the server took it. Never rejects.
+*
+* For the one caller that has to know: `installation_started` is sent until it lands, so it needs
+* a yes it can trust, which is a 2xx and nothing else. Asks the same question `send` does before
+* anything goes over the wire.
+*/
+async function deliver(record) {
+	try {
+		if (!telemetryUploadEnabled()) return false;
+		const payload = project(record);
+		return payload ? await post(payload) : false;
+	} catch {
+		return false;
+	}
+}
+async function post(payload) {
+	try {
+		const response = await fetch(endpoint(), {
 			method: "POST",
 			headers: { "content-type": "application/json" },
 			body: JSON.stringify(payload),
 			signal: AbortSignal.timeout(TIMEOUT_MS)
-		}).catch(() => {});
-	} catch {}
+		});
+		await response.body?.cancel().catch(() => {});
+		return response.ok;
+	} catch {
+		return false;
+	}
 }
 /**
 * Where to. Overridable so the endpoint can be pointed at a local server while it is being built,
@@ -13645,29 +13677,44 @@ var LOG_PATH = join(STORE_ROOT, "events.jsonl");
 * The gate is on **transmission only**. Writing a file the developer owns and can read, delete or
 * disable is a different act from sending to a server, and the consent that suits one does not
 * carry to the other, so `events.jsonl` keeps recording the full event union either way and the
-* question asked on first run is about the wire. Nineteen events are written here; two of them,
+* question asked on first run is about the wire. Twenty events are written here; three of them,
 * carrying eight fields between them, are the most that is ever sent.
 */
 function record(event) {
 	try {
-		const config = loadConfig();
-		if (!config.telemetry) return;
-		const line = {
-			anonymousId: config.anonymousId,
-			cliVersion: BUILD_VERSION,
-			platform: platformName(),
-			at: (/* @__PURE__ */ new Date()).toISOString(),
-			event
-		};
-		mkdirSync(STORE_ROOT, { recursive: true });
-		appendFileSync(LOG_PATH, `${JSON.stringify(line)}\n`, { mode: 384 });
+		const line = stamp(event);
+		if (!line) return;
+		append(line);
 		send(line);
 	} catch {}
 }
+/**
+* The line an event would be logged as, or `null` when the log is switched off.
+*
+* Split from `record` for `installation_started`, which is built and sent first and logged only
+* once the server has it: logging each attempt would leave one line per failed try for an event
+* that happens once.
+*/
+function stamp(event) {
+	const config = loadConfig();
+	if (!config.telemetry) return null;
+	return {
+		anonymousId: config.anonymousId,
+		cliVersion: BUILD_VERSION,
+		platform: platformName(),
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		event
+	};
+}
+/** Write one line to the log. Throws on a failed write; callers decide what that costs. */
+function append(line) {
+	mkdirSync(STORE_ROOT, { recursive: true });
+	appendFileSync(LOG_PATH, `${JSON.stringify(line)}\n`, { mode: 384 });
+}
 /** This review's own events, oldest first. The only reader, used to derive the rollup. */
 function readEvents(reviewId) {
 	try {
-		return readFileSync(LOG_PATH, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line)).filter((entry) => entry.event?.reviewId === reviewId).map((entry) => entry.event);
+		return readFileSync(LOG_PATH, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line)).map((entry) => entry.event).filter((event) => event !== void 0 && "reviewId" in event && event.reviewId === reviewId);
 	} catch {
 		return [];
 	}
@@ -16152,4 +16199,4 @@ function lineageIds(id) {
 	return [.../* @__PURE__ */ new Set([id, ...lineage.map((review) => review.id)])];
 }
 //#endregion
-export { REPOSITORY_SCOPE as $, presentedKissRunOf as $n, reviewsUrl as $t, reanalyseReview as A, saveJob as An, recommendationsOf as Ar, renderInlineText as At, RUNTIME_WORDS as B, followedRefName as Bn, clearAgentPreference as Br, removeWorktree as Bt, track as C, followedBranch as Cn, doneVerb as Cr, authorPreview as Ct, endRun as D, fail as Dn, questionsOutstanding as Dr, CODE_BLOCK_CLASS as Dt, completeRun as E, endedAt as En, issuesOutstanding as Er, renderMarkdown as Et, recordTelemetryUploadConsent as F, purposeOf as Fn, displayRef as Fr, MANAGED_ROOT as Ft, partFiles as G, kissDecisionsOf as Gn, AGENT_IDS as Gr, compactQueue as Gt, ARCHITECTURE_DIR as H, indexKeptIds as Hn, writeAgentPreference as Hr, modelHelpLines as Ht, telemetryUploadConsent as I, clearClaim as In, isCommitReview as Ir, createWorktree as It, storeArchitecture as J, lineagePosition as Jn, agentFor as Jr, readIndexToken as Jt, readArchitecture as K, latestKissRun as Kn, DEFAULT_AGENT_ID as Kr, queueForReview as Kt, waitingHistory as L, driverGone as Ln, git as Lr, holdWorktree as Lt, startJob as M, isLiveJob as Mn, WITHHELD_REASON as Mr, extractJsonText as Mt, readEvents as N, phasesFor as Nn, kissOutcome as Nr, objectWithAnyOf as Nt, reportRun as O, isTerminal as On, reviewerDispositions as Or, CODE_COPY_CLASS as Ot, record as P, progressSteps as Pn, resolveTarget as Pr, ReviewBeingDeletedError as Pt, QUOTE_LIMITS as Q, positionInLineage as Qn, readServerRecord as Qt, mapRuntimes as R, isClaimed as Rn, resolveAgent as Rr, isWorktreeHeld as Rt, isDriving as S, checkReview as Sn, readQueue as Sr, UNESTABLISHED_MOTIVATION as St, beginRun as T, allJobs as Tn, isQuestionOutstanding as Tr, GITHUB_MARKDOWN as Tt, checkArchitecture as U, indexReviewGroups as Un, CONFIG_PATH as Ur, relativeTime as Ut, describeRuntimes as V, groupByLineage as Vn, readAgentPreference as Vr, requestJobStop as Vt, loadArchitecture as W, kissDecisionRefusal as Wn, STORE_ROOT as Wr, activateQueued as Wt, trackedFiles as X, matchingWorkspaceIds as Xn, AgentCancelledError as Xr, clearServerRecordOwnedBy as Xt, storedScopes as Y, loadWorkspace as Yn, detectAgents as Yr, bootstrapUrl as Yt, ownersOf as Z, mutateWorkspace as Zn, AgentUnavailableError as Zr, ensureServer as Zt, liveUpdateFor as _, forgeResolver as _n, sectionOf as _r, removeNotification as _t, wasBlocked as a, writeServerRecord as an, touchWorkspace as ar, subjectOf as at, recordKissRun as b, fillFileUrlTemplate as bn, queueRemove as br, withUsageRecorded as bt, RefreshUnavailableError as c, feedbackUrl as cn, LIFECYCLES as cr, createPrUpdate as ct, mergeUpdateInto as d, MIN_WORKSPACE_PORT as dn, isLifecycle as dr, listNotifications as dt, serverEntryExists as en, previousKissResult as er, ancestorsOf as et, updateReview as f, parseWorkspacePort as fn, lifecycleChip as fr, markAllRead as ft, UpdateAlreadyRunningError as g, claimRequestUrl as gn, parseLifecycle as gr, readNotification as gt, askCheckout as h, writePortPreference as hn, offersLifecycle as hr, pruneNotifications as ht, liveJobsFor as i, workspaceUrl as in, summarise as ir, branchOf as it, runJob as j, PHASES as jn, describeAuthorship as jr, asString as jt, stopRun as k, loadJob as kn, processDiscussion as kr, escapeHtml as kt, cancelUpdate as l, DEFAULT_WORKSPACE_PORT as ln, activityAttributes as lr, eventName as lt, isUnchanged as m, statedWorkspacePort as mn, lifecyclePill as mr, markReadForReview as mt, deleteReview as n, stopChild as nn, reviewedCommit as nr, writeJsonAtomically as nt, discardJob as o, BUILD_VERSION as on, workspaceRevision as or, createArchitectureNotification as ot, refreshPrContext as p, resolveWorkspacePort as pn, lifecycleItemLabel as pr, markRead as pt, repositoryKey as q, lineageKeyFor as qn, agentById as qr, settleQueue as qt, lineageIds as r, stopServer as rn, reviewedRepositories as rr, announceJob as rt, FETCH_TIMEOUT_MS as s, PACKAGE_NAME as sn, workspaceStamps as sr, createPrState as st, deleteLineage as t, spawnServer as tn, recentWorkspaces as tr, isArchitectureId as tt, cancellableHere as u, MAX_WORKSPACE_PORT as un, activityLabel as ur, headline as ut, runningJobs as v, forgeFor as vn, queueAdd as vr, toneOf as vt, RUN_KINDS as w, reviewedShaOf as wn, isIssueOutstanding as wr, hasAuthorContent as wt, startKissJob as x, checkCodeFreshness as xn, queueStamp as xr, EXPLAIN_SIMPLY_PROMPT as xt, agentEnvOf as y, remoteHost as yn, queueAddMany as yr, unreadCount as yt, recordRuntimeBestEffort as z, decideKissRecommendation as zn, resolveModel as zr, readMarker as zt };
+export { storedScopes as $, loadWorkspace as $n, detectAgents as $r, bootstrapUrl as $t, reanalyseReview as A, endedAt as An, issuesOutstanding as Ar, renderMarkdown as At, telemetryUploadEnabled as B, clearClaim as Bn, isCommitReview as Br, createWorktree as Bt, track as C, remoteHost as Cn, queueAddMany as Cr, unreadCount as Ct, endRun as D, followedBranch as Dn, doneVerb as Dr, authorPreview as Dt, completeRun as E, checkReview as En, readQueue as Er, UNESTABLISHED_MOTIVATION as Et, record as F, PHASES as Fn, describeAuthorship as Fr, asString as Ft, describeRuntimes as G, groupByLineage as Gn, readAgentPreference as Gr, requestJobStop as Gt, mapRuntimes as H, isClaimed as Hn, resolveAgent as Hr, isWorktreeHeld as Ht, stamp as I, isLiveJob as In, WITHHELD_REASON as Ir, extractJsonText as It, loadArchitecture as J, kissDecisionRefusal as Jn, STORE_ROOT as Jr, activateQueued as Jt, ARCHITECTURE_DIR as K, indexKeptIds as Kn, writeAgentPreference as Kr, modelHelpLines as Kt, deliver as L, phasesFor as Ln, kissOutcome as Lr, objectWithAnyOf as Lt, startJob as M, isTerminal as Mn, reviewerDispositions as Mr, CODE_COPY_CLASS as Mt, append as N, loadJob as Nn, processDiscussion as Nr, escapeHtml as Nt, reportRun as O, reviewedShaOf as On, isIssueOutstanding as Or, hasAuthorContent as Ot, readEvents as P, saveJob as Pn, recommendationsOf as Pr, renderInlineText as Pt, storeArchitecture as Q, lineagePosition as Qn, agentFor as Qr, readIndexToken as Qt, recordTelemetryUploadConsent as R, progressSteps as Rn, resolveTarget as Rr, ReviewBeingDeletedError as Rt, isDriving as S, forgeFor as Sn, queueAdd as Sr, toneOf as St, beginRun as T, checkCodeFreshness as Tn, queueStamp as Tr, EXPLAIN_SIMPLY_PROMPT as Tt, recordRuntimeBestEffort as U, decideKissRecommendation as Un, resolveModel as Ur, readMarker as Ut, waitingHistory as V, driverGone as Vn, git as Vr, holdWorktree as Vt, RUNTIME_WORDS as W, followedRefName as Wn, clearAgentPreference as Wr, removeWorktree as Wt, readArchitecture as X, latestKissRun as Xn, DEFAULT_AGENT_ID as Xr, queueForReview as Xt, partFiles as Y, kissDecisionsOf as Yn, AGENT_IDS as Yr, compactQueue as Yt, repositoryKey as Z, lineageKeyFor as Zn, agentById as Zr, settleQueue as Zt, liveUpdateFor as _, resolveWorkspacePort as _n, lifecycleItemLabel as _r, markRead as _t, wasBlocked as a, spawnServer as an, recentWorkspaces as ar, isArchitectureId as at, recordKissRun as b, claimRequestUrl as bn, parseLifecycle as br, readNotification as bt, RefreshUnavailableError as c, workspaceUrl as cn, summarise as cr, branchOf as ct, mergeUpdateInto as d, PACKAGE_NAME as dn, workspaceStamps as dr, createPrState as dt, AgentCancelledError as ei, clearServerRecordOwnedBy as en, matchingWorkspaceIds as er, trackedFiles as et, updateReview as f, feedbackUrl as fn, LIFECYCLES as fr, createPrUpdate as ft, UpdateAlreadyRunningError as g, parseWorkspacePort as gn, lifecycleChip as gr, markAllRead as gt, askCheckout as h, MIN_WORKSPACE_PORT as hn, isLifecycle as hr, listNotifications as ht, liveJobsFor as i, serverEntryExists as in, previousKissResult as ir, ancestorsOf as it, runJob as j, fail as jn, questionsOutstanding as jr, CODE_BLOCK_CLASS as jt, stopRun as k, allJobs as kn, isQuestionOutstanding as kr, GITHUB_MARKDOWN as kt, cancelUpdate as l, writeServerRecord as ln, touchWorkspace as lr, subjectOf as lt, isUnchanged as m, MAX_WORKSPACE_PORT as mn, activityLabel as mr, headline as mt, deleteReview as n, readServerRecord as nn, positionInLineage as nr, QUOTE_LIMITS as nt, discardJob as o, stopChild as on, reviewedCommit as or, writeJsonAtomically as ot, refreshPrContext as p, DEFAULT_WORKSPACE_PORT as pn, activityAttributes as pr, eventName as pt, checkArchitecture as q, indexReviewGroups as qn, CONFIG_PATH as qr, relativeTime as qt, lineageIds as r, reviewsUrl as rn, presentedKissRunOf as rr, REPOSITORY_SCOPE as rt, FETCH_TIMEOUT_MS as s, stopServer as sn, reviewedRepositories as sr, announceJob as st, deleteLineage as t, AgentUnavailableError as ti, ensureServer as tn, mutateWorkspace as tr, ownersOf as tt, cancellableHere as u, BUILD_VERSION as un, workspaceRevision as ur, createArchitectureNotification as ut, runningJobs as v, statedWorkspacePort as vn, lifecyclePill as vr, markReadForReview as vt, RUN_KINDS as w, fillFileUrlTemplate as wn, queueRemove as wr, withUsageRecorded as wt, startKissJob as x, forgeResolver as xn, sectionOf as xr, removeNotification as xt, agentEnvOf as y, writePortPreference as yn, offersLifecycle as yr, pruneNotifications as yt, telemetryUploadConsent as z, purposeOf as zn, displayRef as zr, MANAGED_ROOT as zt };

package/dist/main.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $t as reviewsUrl, A as reanalyseReview, Bn as followedRefName, Bt as removeWorktree, F as recordTelemetryUploadConsent, Fn as purposeOf, Fr as displayRef, Ft as MANAGED_ROOT, Gr as AGENT_IDS, Hr as writeAgentPreference, Ht as modelHelpLines, I as telemetryUploadConsent, In as clearClaim, Jt as readIndexToken, Kr as DEFAULT_AGENT_ID, Kt as queueForReview, Ln as driverGone, Lr as git, M as startJob, Mr as WITHHELD_REASON, Nr as kissOutcome, On as isTerminal, P as record$1, Pn as progressSteps, Pr as resolveTarget, Qn as positionInLineage, Rn as isClaimed, Rr as resolveAgent, Sn as checkReview, Tn as allJobs, Ur as CONFIG_PATH, Ut as relativeTime, Vn as groupByLineage, Vr as readAgentPreference, Wr as STORE_ROOT, Xn as matchingWorkspaceIds, Yn as loadWorkspace, Yr as detectAgents, Yt as bootstrapUrl, Zn as mutateWorkspace, Zt as ensureServer, _ as liveUpdateFor, _n as forgeResolver, a as wasBlocked, b as recordKissRun, d as mergeUpdateInto, dn as MIN_WORKSPACE_PORT, f as updateReview, fn as parseWorkspacePort, g as UpdateAlreadyRunningError, hn as writePortPreference, i as liveJobsFor, in as workspaceUrl, ir as summarise, j as runJob, jn as PHASES, kn as loadJob, ln as DEFAULT_WORKSPACE_PORT, mn as statedWorkspacePort, n as deleteReview$1, on as BUILD_VERSION, qn as lineageKeyFor, qr as agentById, rn as stopServer, rr as reviewedRepositories, sn as PACKAGE_NAME, tr as recentWorkspaces, un as MAX_WORKSPACE_PORT, v as runningJobs, zr as resolveModel, zt as readMarker } from "./delete_review-LzUgEUzN.js";
+import { $n as loadWorkspace, $r as detectAgents, $t as bootstrapUrl, A as reanalyseReview, B as telemetryUploadEnabled, Bn as clearClaim, En as checkReview, F as record$1, Fn as PHASES, Gn as groupByLineage, Gr as readAgentPreference, Hn as isClaimed, Hr as resolveAgent, I as stamp, Ir as WITHHELD_REASON, Jr as STORE_ROOT, Kr as writeAgentPreference, Kt as modelHelpLines, L as deliver, Lr as kissOutcome, M as startJob, Mn as isTerminal, N as append, Nn as loadJob, Qt as readIndexToken, R as recordTelemetryUploadConsent, Rn as progressSteps, Rr as resolveTarget, Ur as resolveModel, Ut as readMarker, Vn as driverGone, Vr as git, Wn as followedRefName, Wt as removeWorktree, Xr as DEFAULT_AGENT_ID, Xt as queueForReview, Yr as AGENT_IDS, Zn as lineageKeyFor, Zr as agentById, _ as liveUpdateFor, a as wasBlocked, ar as recentWorkspaces, b as recordKissRun, cn as workspaceUrl, cr as summarise, d as mergeUpdateInto, dn as PACKAGE_NAME, er as matchingWorkspaceIds, f as updateReview, g as UpdateAlreadyRunningError, gn as parseWorkspacePort, hn as MIN_WORKSPACE_PORT, i as liveJobsFor, j as runJob, kn as allJobs, mn as MAX_WORKSPACE_PORT, n as deleteReview$1, nr as positionInLineage, pn as DEFAULT_WORKSPACE_PORT, qr as CONFIG_PATH, qt as relativeTime, rn as reviewsUrl, sn as stopServer, sr as reviewedRepositories, tn as ensureServer, tr as mutateWorkspace, un as BUILD_VERSION, v as runningJobs, vn as statedWorkspacePort, xn as forgeResolver, yn as writePortPreference, z as telemetryUploadConsent, zn as purposeOf, zr as displayRef, zt as MANAGED_ROOT } from "./delete_review-CeJo9t7h.js";
 import { basename, dirname, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -107,15 +107,24 @@ var AUDIENCES = {
 	reviewer: "writes it for somebody reviewing somebody else's work, with whether each one is worth raising"
 };
 function parse(argv) {
-	if (argv.length === 0) return { name: "help" };
+	if (argv.length === 0) return {
+		name: "help",
+		via: "bare"
+	};
 	const [head, ...rest] = argv;
-	if (head === "--help" || head === "-h" || head === "help") return { name: "help" };
+	if (head === "--help" || head === "-h" || head === "help") return {
+		name: "help",
+		via: "asked"
+	};
 	if (head === "--version" || head === "-v") return { name: "version" };
 	if (head === void 0 || !(head in VALUED)) return {
 		name: "error",
 		message: unknownCommand(head)
 	};
-	if (rest.includes("--help") || rest.includes("-h")) return { name: "help" };
+	if (rest.includes("--help") || rest.includes("-h")) return {
+		name: "help",
+		via: "asked"
+	};
 	const values = {};
 	const flags = /* @__PURE__ */ new Set();
 	const positional = [];
@@ -1217,12 +1226,26 @@ function unknownSetting(key, known) {
 * little else is attached to it. "Anonymous" is a word with a technical meaning strong enough to be
 * challenged on, and the claim below does not need it to be true.
 */
+/**
+* The one addition since the notice an installation already saw, or the yes it already gave. Not the
+* notice again: repeating what somebody was told reads as something else having changed.
+*/
+function telemetryFirstUseNotice() {
+	return [
+		"",
+		"Usage telemetry now also records first use: one event, once per installation, with the",
+		"same version, platform and timestamp fields as before. Nothing else changed.",
+		"Turn it off: `prreviewbuddy config set telemetry-upload off`",
+		"Details: https://prreviewbuddy.com/privacy",
+		""
+	].join("\n");
+}
 function telemetryNotice() {
 	return [
 		"",
-		"Non-identifying usage telemetry is on by default: review start and finish, version,",
-		"platform, agent, success and duration. Never your code, diffs, repository names or",
-		"review content.",
+		"Non-identifying usage telemetry is on by default: first use, review start and finish,",
+		"version, platform, agent, success and duration. Never your code, diffs, repository",
+		"names or review content.",
 		"Turn it off: `prreviewbuddy config set telemetry-upload off`",
 		"Details: https://prreviewbuddy.com/privacy",
 		""
@@ -3413,6 +3436,7 @@ async function uninstall(command, deps = REAL) {
 */
 var GREETING = "onboarding-shown";
 var TELEMETRY_NOTICE = "telemetry-notice-shown";
+var FIRST_USE_NOTICE = "telemetry-first-use-notice-shown";
 /** Whether this machine has been greeted. */
 function greeted() {
 	return shown(GREETING);
@@ -3433,6 +3457,13 @@ function telemetryNoticed() {
 function recordTelemetryNotice() {
 	record(TELEMETRY_NOTICE);
 }
+/** Whether this machine has been told that 0.63.0 added `installation_started` to what is sent. */
+function firstUseNoticed() {
+	return shown(FIRST_USE_NOTICE);
+}
+function recordFirstUseNotice() {
+	record(FIRST_USE_NOTICE);
+}
 /**
 * Unreadable reads as already shown.
 *
@@ -3473,16 +3504,108 @@ function record(name) {
 * Both are left alone, which is why the claim everywhere else is "every installation whose
 * behaviour changes is told once" rather than "every machine is told".
 *
+* **0.63.0 is such a change for everybody who sends.** `installation_started` joined what leaves
+* the machine, so an installation told the old list, or that said yes to it, is told once about the
+* addition, under its own marker. A no is still told nothing.
+*
 * **No terminal check.** The old question could not be asked without one. A disclosure has nobody
 * to wait for, and a headless install that transmits is exactly the install that must not be the
 * one nobody ever told. It costs a CI log three lines on a persisted home, once.
 */
 function noticeTelemetry(write) {
 	if (process.env.PRB_TELEMETRY === "off") return;
-	if (telemetryUploadConsent() !== null) return;
-	if (telemetryNoticed()) return;
-	write(telemetryNotice());
-	recordTelemetryNotice();
+	const consent = telemetryUploadConsent();
+	if (consent === false) return;
+	if (consent === null && !telemetryNoticed()) {
+		write(telemetryNotice());
+		recordTelemetryNotice();
+		recordFirstUseNotice();
+		return;
+	}
+	if (firstUseNoticed()) return;
+	write(telemetryFirstUseNotice());
+	recordFirstUseNotice();
+}
+//#endregion
+//#region src/product_commands.ts
+/**
+* Whether this command is somebody using the product, rather than asking about the binary or
+* changing a setting.
+*
+* One answer for two things, on purpose. These commands print the one-time telemetry notice, and
+* they are the commands that may send `installation_started`. If the lists ever differed, a
+* command could transmit before the installation had been told telemetry is on.
+*
+* `prreviewbuddy` on its own counts: it is somebody entering the product to see what it does.
+* `--help` and `--version` do not, nor `config` (where the setting is changed, and turning it off
+* must not need a disclosure first) or `uninstall`.
+*/
+function isProductCommand(command) {
+	switch (command.name) {
+		case "review":
+		case "open":
+		case "agents": return true;
+		case "help": return command.via === "bare";
+		default: return false;
+	}
+}
+//#endregion
+//#region ../../packages/review-harness/src/telemetry/installation_started.ts
+/**
+* Tell the server, once, that this installation was used.
+*
+* The review events only fire from inside a review job, so an installation that was tried and
+* left before its first review was invisible: nothing told "nobody installs this" apart from
+* "people install it and stop before reviewing". This is the event that sits in front of them.
+*
+* It means first meaningful use that telemetry saw, and the name has to survive that reading:
+* an installation from before the event existed sends it on its first command after upgrading,
+* and nothing on this machine knows when the package was actually installed.
+*
+* **Sent until it lands.** Every other event is best effort, because losing one review out of a
+* thousand changes nothing. Losing this one loses the installation from the funnel, so the marker
+* is written only after a 2xx, and every meaningful command until then tries again. Any failure
+* retries, a 422 included: a CLI that reached somebody before the API learned the event recovers
+* on its own once it has. `occurredAt` is the attempt's own time, never a remembered first try,
+* because the server refuses a timestamp more than two days from when it arrives and a stored
+* one would be refused forever.
+*
+* **Once is kept by the server, not here.** This side cannot know that a request it saw fail was
+* not stored: an acknowledgement lost after the row committed looks exactly like a failure, and two
+* commands started together on one home both pass the marker check before either has written it.
+* Both resend. The API holds one `installation_started` per installation under a unique index and
+* answers a repeat with a 200 it does not store, which also stops the retrying. The marker only
+* saves requests.
+*/
+var MARKER = join(STORE_ROOT, "installation-started-sent");
+/**
+* Send `installation_started` if this installation has not had it accepted yet. Never rejects.
+*
+* Asks whether it may send before it reads anything, so under `PRB_TELEMETRY=off` it creates no
+* identity, no marker and no log line: the kill switch is not a decision, and a machine that
+* unsets it tomorrow has still never been counted.
+*/
+async function announceInstallation() {
+	try {
+		if (!telemetryUploadEnabled()) return;
+		if (announced()) return;
+		const line = stamp({ event: "installation_started" });
+		if (!line || !await deliver(line)) return;
+		writeMarker();
+		append(line);
+	} catch {}
+}
+/** An unreadable home counts as already sent: failing closed on repetition. */
+function announced() {
+	try {
+		return existsSync(MARKER);
+	} catch {
+		return true;
+	}
+}
+function writeMarker() {
+	mkdirSync(STORE_ROOT, { recursive: true });
+	writeFileSync(MARKER, `${(/* @__PURE__ */ new Date()).toISOString()}\n`, { mode: 384 });
 }
 //#endregion
 //#region src/main.ts
@@ -3520,28 +3643,33 @@ function greet(command) {
 /**
 * The one-time telemetry disclosure, printed after the hello and before the work.
 *
-* The greeting's commands minus `config`, which is where the setting is changed: somebody typing
+* On the commands `isProductCommand` names, which are also the ones that may send
+* `installation_started`, so nothing is transmitted from a command that could not have disclosed
+* it. Not `config`, which is where the setting is changed: somebody typing
 * `config set telemetry-upload off` should be able to turn it off without being told first that it
-* is on. That was true when this was a question and it is still true now it is a notice.
+* is on.
 *
 * On stderr, like every other line here that is not a result, so `prreviewbuddy review | pbcopy`
 * still copies a URL. Unlike the question it replaced it takes no input and checks for no terminal:
 * there is nobody to wait for, and a headless install that transmits is the one that most needs
 * telling.
 */
-var NOTIFIED = [
-	"review",
-	"open",
-	"agents"
-];
 function notify(command) {
-	if (!NOTIFIED.includes(command.name)) return;
+	if (!isProductCommand(command)) return;
 	noticeTelemetry((chunk) => void process.stderr.write(chunk));
 }
 async function main(argv) {
 	const command = parse(argv);
 	greet(command);
 	notify(command);
+	const announced = isProductCommand(command) ? announceInstallation() : Promise.resolve();
+	try {
+		return await run(command);
+	} finally {
+		await announced;
+	}
+}
+async function run(command) {
 	switch (command.name) {
 		case "help":
 			out(HELP);

package/dist/server.js

@@ -1,4 +1,4 @@
-import { $ as REPOSITORY_SCOPE, $n as presentedKissRunOf, A as reanalyseReview, An as saveJob, Ar as recommendationsOf, At as renderInlineText, B as RUNTIME_WORDS, Bn as followedRefName, Br as clearAgentPreference, Bt as removeWorktree, C as track, Cn as followedBranch, Cr as doneVerb, Ct as authorPreview, D as endRun, Dn as fail, Dr as questionsOutstanding, Dt as CODE_BLOCK_CLASS, E as completeRun, En as endedAt, Er as issuesOutstanding, Et as renderMarkdown, F as recordTelemetryUploadConsent, Fn as purposeOf, Ft as MANAGED_ROOT, G as partFiles, Gn as kissDecisionsOf, Gr as AGENT_IDS, Gt as compactQueue, H as ARCHITECTURE_DIR, Hn as indexKeptIds, Hr as writeAgentPreference, I as telemetryUploadConsent, Ir as isCommitReview, It as createWorktree, J as storeArchitecture, Jn as lineagePosition, Jr as agentFor, Jt as readIndexToken, K as readArchitecture, Kn as latestKissRun, L as waitingHistory, Lr as git, Lt as holdWorktree, Mn as isLiveJob, Mr as WITHHELD_REASON, Mt as extractJsonText, N as readEvents, Nn as phasesFor, Nr as kissOutcome, Nt as objectWithAnyOf, O as reportRun, On as isTerminal, Or as reviewerDispositions, Ot as CODE_COPY_CLASS, P as record, Pn as progressSteps, Pt as ReviewBeingDeletedError, Q as QUOTE_LIMITS, Qt as readServerRecord, R as mapRuntimes, Rn as isClaimed, Rt as isWorktreeHeld, S as isDriving, Sn as checkReview, Sr as readQueue, St as UNESTABLISHED_MOTIVATION, T as beginRun, Tn as allJobs, Tr as isQuestionOutstanding, Tt as GITHUB_MARKDOWN, U as checkArchitecture, Un as indexReviewGroups, Ut as relativeTime$1, V as describeRuntimes, Vn as groupByLineage, Vr as readAgentPreference, Vt as requestJobStop, W as loadArchitecture, Wn as kissDecisionRefusal, Wr as STORE_ROOT, Wt as activateQueued, X as trackedFiles, Xr as AgentCancelledError, Xt as clearServerRecordOwnedBy, Y as storedScopes, Yn as loadWorkspace, Z as ownersOf, Zn as mutateWorkspace, Zr as AgentUnavailableError, _ as liveUpdateFor, _r as sectionOf, _t as removeNotification, a as wasBlocked, an as writeServerRecord, ar as touchWorkspace, at as subjectOf, bn as fillFileUrlTemplate, br as queueRemove, bt as withUsageRecorded, c as RefreshUnavailableError, cn as feedbackUrl, cr as LIFECYCLES, ct as createPrUpdate, d as mergeUpdateInto, dn as MIN_WORKSPACE_PORT, dr as isLifecycle, dt as listNotifications, en as serverEntryExists, er as previousKissResult, et as ancestorsOf, f as updateReview, fn as parseWorkspacePort, fr as lifecycleChip, ft as markAllRead, g as UpdateAlreadyRunningError, gn as claimRequestUrl, gr as parseLifecycle, gt as readNotification, h as askCheckout, hn as writePortPreference, hr as offersLifecycle, ht as pruneNotifications, i as liveJobsFor, it as branchOf, j as runJob, jr as describeAuthorship, jt as asString, k as stopRun, kn as loadJob, kr as processDiscussion, kt as escapeHtml$1, l as cancelUpdate, ln as DEFAULT_WORKSPACE_PORT, lr as activityAttributes, lt as eventName, m as isUnchanged, mn as statedWorkspacePort, mr as lifecyclePill, mt as markReadForReview, n as deleteReview, nn as stopChild, nr as reviewedCommit, nt as writeJsonAtomically, o as discardJob, on as BUILD_VERSION, or as workspaceRevision, ot as createArchitectureNotification, p as refreshPrContext, pn as resolveWorkspacePort, pr as lifecycleItemLabel, pt as markRead, q as repositoryKey, qt as settleQueue, r as lineageIds, rt as announceJob, s as FETCH_TIMEOUT_MS, sr as workspaceStamps, st as createPrState, t as deleteLineage, tn as spawnServer, tr as recentWorkspaces, tt as isArchitectureId, u as cancellableHere, un as MAX_WORKSPACE_PORT, ur as activityLabel, ut as headline, vn as forgeFor, vr as queueAdd, vt as toneOf, w as RUN_KINDS, wn as reviewedShaOf, wr as isIssueOutstanding, wt as hasAuthorContent, x as startKissJob, xn as checkCodeFreshness, xr as queueStamp, xt as EXPLAIN_SIMPLY_PROMPT, y as agentEnvOf, yn as remoteHost, yr as queueAddMany, yt as unreadCount$1, z as recordRuntimeBestEffort, zn as decideKissRecommendation, zr as resolveModel, zt as readMarker } from "./delete_review-LzUgEUzN.js";
+import { $ as storedScopes, $n as loadWorkspace, A as reanalyseReview, An as endedAt, Ar as issuesOutstanding, At as renderMarkdown, Br as isCommitReview, Bt as createWorktree, C as track, Cn as remoteHost, Cr as queueAddMany, Ct as unreadCount$1, D as endRun, Dn as followedBranch, Dr as doneVerb, Dt as authorPreview, E as completeRun, En as checkReview, Er as readQueue, Et as UNESTABLISHED_MOTIVATION, F as record, Fr as describeAuthorship, Ft as asString, G as describeRuntimes, Gn as groupByLineage, Gr as readAgentPreference, Gt as requestJobStop, H as mapRuntimes, Hn as isClaimed, Ht as isWorktreeHeld, In as isLiveJob, Ir as WITHHELD_REASON, It as extractJsonText, J as loadArchitecture, Jn as kissDecisionRefusal, Jr as STORE_ROOT, Jt as activateQueued, K as ARCHITECTURE_DIR, Kn as indexKeptIds, Kr as writeAgentPreference, Ln as phasesFor, Lr as kissOutcome, Lt as objectWithAnyOf, Mn as isTerminal, Mr as reviewerDispositions, Mt as CODE_COPY_CLASS, Nn as loadJob, Nr as processDiscussion, Nt as escapeHtml$1, O as reportRun, On as reviewedShaOf, Or as isIssueOutstanding, Ot as hasAuthorContent, P as readEvents, Pn as saveJob, Pr as recommendationsOf, Pt as renderInlineText, Q as storeArchitecture, Qn as lineagePosition, Qr as agentFor, Qt as readIndexToken, R as recordTelemetryUploadConsent, Rn as progressSteps, Rt as ReviewBeingDeletedError, S as isDriving, Sn as forgeFor, Sr as queueAdd, St as toneOf, T as beginRun, Tn as checkCodeFreshness, Tr as queueStamp, Tt as EXPLAIN_SIMPLY_PROMPT, U as recordRuntimeBestEffort, Un as decideKissRecommendation, Ur as resolveModel, Ut as readMarker, V as waitingHistory, Vr as git, Vt as holdWorktree, W as RUNTIME_WORDS, Wn as followedRefName, Wr as clearAgentPreference, Wt as removeWorktree, X as readArchitecture, Xn as latestKissRun, Y as partFiles, Yn as kissDecisionsOf, Yr as AGENT_IDS, Yt as compactQueue, Z as repositoryKey, Zt as settleQueue, _ as liveUpdateFor, _n as resolveWorkspacePort, _r as lifecycleItemLabel, _t as markRead, a as wasBlocked, an as spawnServer, ar as recentWorkspaces, at as isArchitectureId, bn as claimRequestUrl, br as parseLifecycle, bt as readNotification, c as RefreshUnavailableError, ct as branchOf, d as mergeUpdateInto, dr as workspaceStamps, dt as createPrState, ei as AgentCancelledError, en as clearServerRecordOwnedBy, et as trackedFiles, f as updateReview, fn as feedbackUrl, fr as LIFECYCLES, ft as createPrUpdate, g as UpdateAlreadyRunningError, gn as parseWorkspacePort, gr as lifecycleChip, gt as markAllRead, h as askCheckout, hn as MIN_WORKSPACE_PORT, hr as isLifecycle, ht as listNotifications, i as liveJobsFor, in as serverEntryExists, ir as previousKissResult, it as ancestorsOf, j as runJob, jn as fail, jr as questionsOutstanding, jt as CODE_BLOCK_CLASS, k as stopRun, kn as allJobs, kr as isQuestionOutstanding, kt as GITHUB_MARKDOWN, l as cancelUpdate, ln as writeServerRecord, lr as touchWorkspace, lt as subjectOf, m as isUnchanged, mn as MAX_WORKSPACE_PORT, mr as activityLabel, mt as headline, n as deleteReview, nn as readServerRecord, nt as QUOTE_LIMITS, o as discardJob, on as stopChild, or as reviewedCommit, ot as writeJsonAtomically, p as refreshPrContext, pn as DEFAULT_WORKSPACE_PORT, pr as activityAttributes, pt as eventName, q as checkArchitecture, qn as indexReviewGroups, qt as relativeTime$1, r as lineageIds, rr as presentedKissRunOf, rt as REPOSITORY_SCOPE, s as FETCH_TIMEOUT_MS, st as announceJob, t as deleteLineage, ti as AgentUnavailableError, tr as mutateWorkspace, tt as ownersOf, u as cancellableHere, un as BUILD_VERSION, ur as workspaceRevision, ut as createArchitectureNotification, vn as statedWorkspacePort, vr as lifecyclePill, vt as markReadForReview, w as RUN_KINDS, wn as fillFileUrlTemplate, wr as queueRemove, wt as withUsageRecorded, x as startKissJob, xr as sectionOf, xt as removeNotification, y as agentEnvOf, yn as writePortPreference, yr as offersLifecycle, yt as pruneNotifications, z as telemetryUploadConsent, zn as purposeOf, zt as MANAGED_ROOT } from "./delete_review-CeJo9t7h.js";
 import { basename, isAbsolute, join, relative, resolve } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createHash, randomUUID, timingSafeEqual } from "node:crypto";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prreviewbuddy",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "description": "Review a branch or pull request in an isolated checkout, from your terminal, with the coding agent you already have installed.",
   "license": "UNLICENSED",
   "homepage": "https://prreviewbuddy.com",