@reticlehq/server 2.4.0 → 2.5.0

package/dist/telemetry/feedback.js

@@ -24,8 +24,11 @@
 import { FeedbackSchema, FEEDBACK_TEXT_MAX, FEEDBACK_TRACE_MAX, FEEDBACK_FIELD_MAX, TelemetryEventKind, } from '@reticlehq/core';
 import { platform } from 'node:os';
 import { getTelemetry } from './telemetry.js';
-import { SERVER_VERSION } from '../server-version.js';
+import { noteFeedbackUndelivered } from './feedback-delivery.js';
+import { isReticleSourceCheckout } from './dev-repo.js';
+import { SERVER_VERSION } from '../version/server-version.js';
 import { feedbackContext } from './feedback-context.js';
+import { markDelivered, outboxPath, queueFeedback } from './feedback-outbox.js';
 /** Kills the feedback channel ONLY — adoption counters keep flowing. */
 export const FEEDBACK_ENV = 'RETICLE_FEEDBACK';
 /** What replaces a redacted match. Visible on purpose: a reader must see that something was removed. */
@@ -67,7 +70,7 @@ export function redactFeedbackText(input, max) {
             removed.add(label);
             // A rule with a leading capture keeps it (the scheme, the `api_key=` key) so the reader still
             // sees WHAT was removed, not just that something was.
-            const prefix = typeof groups[0] === 'string' ? groups[0] : '';
+            const prefix = 'string' === typeof groups[0] ? groups[0] : '';
             return `${prefix}${REDACTED}`;
         });
     }
@@ -76,7 +79,7 @@ export function redactFeedbackText(input, max) {
 /** True when the feedback channel is switched off on its own (the emitter's switches apply as well). */
 export function feedbackDisabled(env = process.env) {
     const value = (env[FEEDBACK_ENV] ?? '').toLowerCase();
-    return value === '0' || value === 'false' || value === 'off' || value === 'no';
+    return '0' === value || 'false' === value || 'off' === value || 'no' === value;
 }
 /**
  * The fields an author writes, and therefore the fields that must be redacted. ONE list, used both to
@@ -118,7 +121,7 @@ export async function submitFeedback(input, opts = {}) {
     // addition. Deriving the set means a sixth field is covered the moment it exists.
     const redactions = new Map();
     for (const [key, value] of Object.entries(input)) {
-        if (typeof value !== 'string' || value === '')
+        if (typeof value !== 'string' || '' === value)
             continue;
         if (!AUTHOR_WRITTEN_FIELDS.has(key))
             continue;
@@ -127,13 +130,25 @@ export async function submitFeedback(input, opts = {}) {
     const body = redactions.get('text') ?? { text: '', removed: [] };
     const redacted = [...new Set([...redactions.values()].flatMap((r) => r.removed))];
     if (feedbackDisabled(env)) {
-        return { sent: false, reason: `feedback is disabled by ${FEEDBACK_ENV}`, redacted, context };
+        return {
+            sent: false,
+            accepted: false,
+            reason: `feedback is disabled by ${FEEDBACK_ENV}`,
+            redacted,
+            context,
+        };
     }
     const telemetry = getTelemetry();
     if (!telemetry.enabled) {
         return {
             sent: false,
-            reason: 'telemetry is disabled on this machine, so feedback has nowhere to go',
+            accepted: false,
+            // Named precisely, because the commonest cause is not what the old wording suggested: a
+            // Reticle SOURCE CHECKOUT disables telemetry by cwd, and that is exactly where release runs and
+            // contributor sessions happen — so the reports most worth having were the ones silently lost.
+            reason: isReticleSourceCheckout(opts.cwd ?? process.cwd())
+                ? 'this is a Reticle source checkout, where telemetry is disabled by design — so feedback has nowhere to go. Open an issue at https://github.com/reticlehq/reticle/issues instead, or run from the app you are verifying.'
+                : `telemetry is disabled on this machine, so feedback has nowhere to go. Re-enable with \`reticle telemetry enable\`, or open an issue at https://github.com/reticlehq/reticle/issues.`,
             redacted,
             context,
         };
@@ -151,13 +166,57 @@ export async function submitFeedback(input, opts = {}) {
     if (!parsed.success) {
         return {
             sent: false,
+            accepted: false,
             reason: parsed.error.issues[0]?.message ?? 'invalid feedback',
             redacted,
             context,
         };
     }
-    await telemetry.emit(TelemetryEventKind.FEEDBACK_SUBMITTED, { feedback: parsed.data });
-    return { sent: true, redacted, context };
+    // BACKGROUND: return now, deliver after. The agent calls this mid-task and a ~340ms POST is the
+    // product blocking the user's work to talk about itself. The honesty that the awaited version was
+    // written for is kept elsewhere: `sent` stays false (nothing is confirmed yet), `accepted` says
+    // the report is well-formed and queued, and a send that then fails reaches the reporter on its
+    // next tool result instead of vanishing.
+    // Written down BEFORE the network is touched, on both paths. A failed send is then a queued report
+    // rather than a lost one — see feedback-outbox. Reported from the field: a 1.3s hiccup destroyed a
+    // root-cause analysis that took an hour of driving to produce, and it survived only because the
+    // reporter happened to have written the markdown by hand first.
+    const queued = queueFeedback(parsed.data);
+    if (true === opts.background) {
+        void telemetry
+            .emit(TelemetryEventKind.FEEDBACK_SUBMITTED, { feedback: parsed.data })
+            .then((ok) => {
+            if (ok)
+                markDelivered(queued);
+            else
+                noteFeedbackUndelivered('the telemetry endpoint did not accept it');
+        })
+            .catch((error) => {
+            noteFeedbackUndelivered(error instanceof Error ? error.message : String(error));
+        });
+        return { sent: false, accepted: true, redacted, context };
+    }
+    // `sent` reflects DELIVERY, not handing the payload to the emitter. It was unconditional, so a DNS
+    // miss or a 4xx both reported "filed" — and this is the only qualitative channel the product has,
+    // so a silent failure here loses the report AND tells the reporter it worked.
+    const delivered = await telemetry.emit(TelemetryEventKind.FEEDBACK_SUBMITTED, {
+        feedback: parsed.data,
+    });
+    if (delivered) {
+        markDelivered(queued);
+        return { sent: true, accepted: true, redacted, context };
+    }
+    // Undelivered, but no longer lost. `accepted` is true when it reached the outbox: the report is
+    // well-formed and on disk, which is a materially different situation from "it is gone".
+    return {
+        sent: false,
+        accepted: queued !== null,
+        reason: queued !== null
+            ? `the report could not be delivered (the network call failed or was rejected), but it is SAVED at ${outboxPath()} and nothing was lost. It will be retried; you can also open an issue at https://github.com/reticlehq/reticle/issues with the same detail.`
+            : 'the report could not be delivered and could not be saved locally either — it was NOT filed. Retry, or open an issue at https://github.com/reticlehq/reticle/issues with the same detail.',
+        redacted,
+        context,
+    };
 }
 /**
  * The receipt's context PLUS the fields the emitter stamps on every event regardless of kind — the

package/dist/telemetry/git-facts.js

@@ -96,7 +96,7 @@ export function gitFacts(cwd, read = defaultRead, exists = defaultExists) {
             if (url === undefined)
                 return { state: GitState.LOCAL_ONLY };
             const origin = normalizeGitOrigin(url);
-            if (origin === '')
+            if ('' === origin)
                 return { state: GitState.LOCAL_ONLY };
             return { state: GitState.REMOTE, origin, forge: forgeOf(origin) };
         }

package/dist/telemetry/session-metrics.d.ts

@@ -62,6 +62,8 @@ export declare class SessionMetrics {
         breadcrumb: string[];
         inFlight: string | undefined;
     };
+    /** One action driven at the page. Settled by the next verdict; see #unsettledActions. */
+    recordAction(): void;
     recordVerification(): void;
     /**
      * One defect found in the app under test — the outcome number, kept broken down by kind.

package/dist/telemetry/session-metrics.js

@@ -21,6 +21,17 @@ import { describeToolParams } from './argument-shape.js';
 import { machineSnapshot } from './machine-snapshot.js';
 /** Cap the distinct error shapes held in memory — a pathological loop must not grow unbounded. */
 const MAX_ERROR_KINDS = 40;
+/** Distinct tool names whose repeat-runs are tracked. Its own cap: the tool surface, not error shapes. */
+const MAX_REPEAT_TOOLS = 64;
+/**
+ * Tool errors that all mean the same thing to a user: the agent asked, and there was no app it could
+ * reach. Three different messages, one experience — "nothing is connected" — and it is the error
+ * that ends most sessions before a single verification happens.
+ *
+ * `multiple sessions connected` belongs here too: the agent could not reach AN app because it could
+ * not tell which one, and the outcome is identical.
+ */
+const NO_SESSION_ERROR = /no browser session connected|no connected session with id|multiple sessions connected/i;
 /** Cap distinct MCP clients recorded; more than a handful on one daemon is already the story. */
 const MAX_CLIENTS = 8;
 /** Bounds on the parameter map. Our own schemas are already finite; these are a belt-and-braces cap. */
@@ -71,6 +82,25 @@ export class SessionMetrics {
      * capped: the kind vocabulary is a bounded enum plus oracle names, not user data.
      */
     #seenBugKinds = new Set();
+    /**
+     * Tool errors meaning "the agent could not reach an app at all" — the single biggest drop-off in
+     * the funnel, and until now reachable only by unpacking `errors[]` in HogQL. 74% of daemons never
+     * call a tool, and of the sessions that made exactly one call, most bounced on this.
+     */
+    #noSessionErrors = 0;
+    /** Longest back-to-back run per tool — a retry loop, which `toolCounts` cannot distinguish. */
+    #repeatRuns = new Map();
+    #lastTool;
+    #currentRun = 0;
+    /**
+     * Actions driven since the last verdict — the run that is left hanging if the loop stops here.
+     *
+     * NOT `actions - verifications`. That difference ignores ORDER, so a verdict that drove nothing
+     * (a `flow_verify` over saved flows) silently paid for a genuinely abandoned action elsewhere, and
+     * a session could verify first and act after and look settled. What is abandoned is the trailing
+     * run, which is exactly what the field claims to mean.
+     */
+    #unsettledActions = 0;
     #clients = new Set();
     #startedAt;
     #now;
@@ -120,6 +150,16 @@ export class SessionMetrics {
         this.#unknownToolCalls += 1;
     }
     recordToolCall(tool, args) {
+        // A run of the same tool back to back. Five calls to reticle_act is engagement; five in a row
+        // after four failures is an agent stuck, and toolCounts reports both as "5".
+        this.#currentRun = tool === this.#lastTool ? this.#currentRun + 1 : 1;
+        this.#lastTool = tool;
+        if (this.#currentRun > 1) {
+            const best = this.#repeatRuns.get(tool) ?? 0;
+            if (this.#currentRun > best &&
+                (this.#repeatRuns.has(tool) || this.#repeatRuns.size < MAX_REPEAT_TOOLS))
+                this.#repeatRuns.set(tool, this.#currentRun);
+        }
         this.#toolCalls += 1;
         bump(this.#toolCounts, tool);
         this.#inFlight = tool;
@@ -150,6 +190,8 @@ export class SessionMetrics {
      */
     recordToolError(message, tool) {
         this.#toolErrors += 1;
+        if (NO_SESSION_ERROR.test(message))
+            this.#noSessionErrors += 1;
         const fingerprint = fingerprintError(message);
         const existing = this.#errorKinds.get(fingerprint);
         if (existing !== undefined) {
@@ -194,8 +236,14 @@ export class SessionMetrics {
     get trail() {
         return { breadcrumb: [...this.#breadcrumb], inFlight: this.#inFlight };
     }
+    /** One action driven at the page. Settled by the next verdict; see #unsettledActions. */
+    recordAction() {
+        this.#unsettledActions += 1;
+    }
     recordVerification() {
         this.#verifications += 1;
+        // A verdict settles whatever was outstanding, however many actions it took to get there.
+        this.#unsettledActions = 0;
     }
     /**
      * One defect found in the app under test — the outcome number, kept broken down by kind.
@@ -258,6 +306,12 @@ export class SessionMetrics {
             verifications: this.#verifications,
             bugsFound: this.#bugsFound,
             ...(this.#bugKinds.size > 0 ? { bugKinds: Object.fromEntries(this.#bugKinds) } : {}),
+            ...(this.#noSessionErrors > 0 ? { noSessionErrors: this.#noSessionErrors } : {}),
+            ...(this.#repeatRuns.size > 0
+                ? { consecutiveRepeats: Object.fromEntries(this.#repeatRuns) }
+                : {}),
+            // Absent rather than zero, so the PRESENCE of the field is the signal on a dashboard.
+            ...(this.#unsettledActions > 0 ? { abandonedActions: this.#unsettledActions } : {}),
             ...(this.#toolParams.size > 0
                 ? {
                     toolParams: Object.fromEntries([...this.#toolParams].map(([tool, params]) => [tool, Object.fromEntries(params)])),
@@ -277,17 +331,22 @@ export class SessionMetrics {
     }
     /** True when nothing at all happened — a flush of an idle daemon is not worth an event. */
     get empty() {
-        return (this.#toolCalls === 0 &&
-            this.#verifications === 0 &&
-            this.#toolErrors === 0 &&
-            this.#bugsFound === 0 &&
-            this.#sdkFailures === 0);
+        return (0 === this.#toolCalls &&
+            0 === this.#verifications &&
+            0 === this.#toolErrors &&
+            0 === this.#bugsFound &&
+            0 === this.#sdkFailures);
     }
     /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */
     reset() {
         this.#toolCalls = 0;
         this.#toolErrors = 0;
         this.#verifications = 0;
+        this.#noSessionErrors = 0;
+        this.#repeatRuns.clear();
+        this.#lastTool = undefined;
+        this.#currentRun = 0;
+        this.#unsettledActions = 0;
         this.#toolCounts.clear();
         this.#toolParams.clear();
         this.#errorKinds.clear();
@@ -302,7 +361,10 @@ export class SessionMetrics {
         this.#unknownToolCalls = 0;
         this.#bugsFound = 0;
         this.#bugKinds.clear();
-        this.#seenBugKinds.clear();
+        // #seenBugKinds is deliberately NOT cleared. It is not a window counter — it is the
+        // session-lifetime memory behind `repeat` on bug_found, and zeroing it made the same defect,
+        // found again after a flush, report as a newly distinct one. Sessions run to 11.5 hours in the
+        // data, so that was up to 23 chances to count one defect many times.
     }
 }
 function bump(map, key) {

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,20 @@
-import { TelemetryEventKind, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type McpConnection, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
+import { TelemetryEventKind, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type McpConnection, type McpOutage, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
+/**
+ * Feedback gets its own, much larger budget — and a retry.
+ *
+ * 2s + drop is right for a usage counter: the metric is worthless if it costs the user latency, and
+ * losing one changes nothing. Feedback is the opposite on both counts. It is the only qualitative
+ * channel the product has, it carries an agent's entire root-cause analysis, and losing one loses
+ * work that cannot be reconstructed.
+ *
+ * Measured to the collector with a WARM DNS cache: dns 0.003s, connect 0.233s, tls 0.467s, total
+ * 0.694s — a third of the old budget gone before any payload moves, on the good path. A fresh
+ * short-lived CLI process pays cold DNS and a cold route on top, which is exactly the case that
+ * failed in the field and then succeeded on retry from a warmer process.
+ */
+export declare const FEEDBACK_TIMEOUT_MS = 15000;
+export declare const FEEDBACK_RETRIES = 1;
+export declare const FEEDBACK_RETRY_BACKOFF_MS = 750;
 /** The current telemetry state and which control set it — what `reticle telemetry status` prints. */
 export declare const describeTelemetry: (env?: NodeJS.ProcessEnv, dir?: string, cwd?: string) => {
     enabled: boolean;
@@ -38,6 +54,8 @@ export interface TelemetryExtra {
     init?: InitOutcome;
     /** `bug_found`: one defect Reticle found in the app under test. */
     bug?: BugFound;
+    /** `mcp_connection_lost`: the agent lost its tools — which stage, and why. */
+    outage?: McpOutage;
 }
 export interface Telemetry {
     /**
@@ -45,7 +63,14 @@ export interface Telemetry {
      * CLI process can exit immediately instead of waiting out the POST (use it from command entry
      * points; daemon-side events send in-process).
      */
-    emit(kind: TelemetryEventKind, extra?: TelemetryExtra): Promise<void>;
+    /**
+     * Send one event. Resolves to whether it was DELIVERED.
+     *
+     * Almost every caller ignores the result and should — a lost metric must never surface to a user.
+     * `reticle_feedback` is the exception: it hands a receipt to an agent, and reporting "filed" for a
+     * send that failed loses the report and lies about it in the same breath.
+     */
+    emit(kind: TelemetryEventKind, extra?: TelemetryExtra): Promise<boolean>;
     readonly enabled: boolean;
     /** True the very first run on this machine — the CLI emits INSTALL alongside the first INVOKE. */
     readonly firstRun: boolean;

package/dist/telemetry/telemetry.js

@@ -16,11 +16,11 @@
  */
 import { spawn } from 'node:child_process';
 import { randomUUID, createHash } from 'node:crypto';
-import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';
+import { appendFileSync, readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
-import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, } from '@reticlehq/core';
-import { SERVER_VERSION } from '../server-version.js';
+import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, isSessionScoped, } from '@reticlehq/core';
+import { SERVER_VERSION } from '../version/server-version.js';
 const RETICLE_DIR = join(homedir(), '.reticle');
 const ID_FILE = join(RETICLE_DIR, 'telemetry-id');
 const NOTICE_FILE = join(RETICLE_DIR, 'telemetry-notice-shown');
@@ -43,6 +43,22 @@ const POSTHOG_KEY = 'phc_q4yCxKMXHfWQ43VAz4HxJXZFLqFi4nBbg5v3avemggYo';
  */
 const POSTHOG_PERSONLESS = { $process_person_profile: false };
 const SEND_TIMEOUT_MS = 2000;
+/**
+ * Feedback gets its own, much larger budget — and a retry.
+ *
+ * 2s + drop is right for a usage counter: the metric is worthless if it costs the user latency, and
+ * losing one changes nothing. Feedback is the opposite on both counts. It is the only qualitative
+ * channel the product has, it carries an agent's entire root-cause analysis, and losing one loses
+ * work that cannot be reconstructed.
+ *
+ * Measured to the collector with a WARM DNS cache: dns 0.003s, connect 0.233s, tls 0.467s, total
+ * 0.694s — a third of the old budget gone before any payload moves, on the good path. A fresh
+ * short-lived CLI process pays cold DNS and a cold route on top, which is exactly the case that
+ * failed in the field and then succeeded on retry from a warmer process.
+ */
+export const FEEDBACK_TIMEOUT_MS = 15_000;
+export const FEEDBACK_RETRIES = 1;
+export const FEEDBACK_RETRY_BACKOFF_MS = 750;
 /**
  * The sender a `detach: true` emit runs in a disowned child (argv: [url, body]) — an in-process fetch
  * keeps Node's event loop alive until the POST finishes, which taxed every short-lived CLI command
@@ -59,6 +75,7 @@ const Env = {
     DISABLE: 'RETICLE_TELEMETRY', // "0" / "false" / "off" → disabled
     DO_NOT_TRACK: 'DO_NOT_TRACK', // the cross-tool opt-out convention (any truthy value)
     URL: 'RETICLE_TELEMETRY_URL', // override the PostHog host (EU cloud / self-hosted)
+    FILE: 'RETICLE_TELEMETRY_FILE', // record to a local JSONL file and send NOTHING — see the sink note
     KEY: 'RETICLE_TELEMETRY_KEY', // override the PostHog project key
     CI: 'CI', // presence marks a CI environment
     VITEST: 'VITEST', // set by vitest — unit tests must never phone home
@@ -67,6 +84,11 @@ const isDisabled = (env, cwd = process.cwd()) => {
     const off = new Set(['0', 'false', 'off', 'no']);
     if (off.has((env[Env.DISABLE] ?? '').toLowerCase()))
         return true;
+    // Recording to a local file is not "phoning home", and the guards below exist to stop us phoning
+    // home. Chief among them is the source-checkout rule — which is exactly where a release sweep is
+    // driven from, so a sink that inherited it would record nothing and look like it had worked.
+    if ((env[Env.FILE] ?? '') !== '')
+        return false;
     if (env[Env.VITEST] !== undefined)
         return true; // a test run is not a user
     // Developing Reticle is not using Reticle. The `.env` carrying RETICLE_TELEMETRY=0 is gitignored,
@@ -75,8 +97,21 @@ const isDisabled = (env, cwd = process.cwd()) => {
     if (isReticleSourceCheckout(cwd))
         return true;
     const dnt = env[Env.DO_NOT_TRACK];
-    return typeof dnt === 'string' && dnt !== '' && dnt !== '0';
+    return 'string' === typeof dnt && dnt !== '' && dnt !== '0';
 };
+/**
+ * Would telemetry be on here if we ignored the source-checkout guard alone?
+ *
+ * That guard exists so a fresh clone does not phone home on a contributor's first `reticle serve` —
+ * a rule about PASSIVE collection. Feedback is never passive: somebody typed it. Applying the guard
+ * to it means anyone dogfooding from their own checkout files nothing and is told "not sent, unknown
+ * reason", which silently loses every report from exactly the people most likely to write good ones.
+ * Reported from the field, and the reporter only escaped it by happening to run from another repo.
+ *
+ * Every explicit opt-out still applies — RETICLE_TELEMETRY=0, DO_NOT_TRACK, the persisted opt-out
+ * file, and a test run. This lifts one implicit guard for one user-initiated event kind.
+ */
+const onlyBlockedBySourceCheckout = (env, cwd) => isDisabled(env, cwd) && !isDisabled(env, '/');
 /** Read (or mint-and-persist) the anonymous machine id. `firstRun` is true the run that created it. */
 const resolveIdentity = () => {
     try {
@@ -172,7 +207,8 @@ export const setTelemetryEnabled = (enabled, dir = RETICLE_DIR) => {
     mkdirSync(dir, { recursive: true });
     writeFileSync(optOutFile, '1', 'utf8');
 };
-const NOOP = { emit: async () => { }, enabled: false, firstRun: false };
+// A disabled emitter delivers nothing, and says so — `false` is the honest answer, not a courtesy.
+const NOOP = { emit: () => Promise.resolve(false), enabled: false, firstRun: false };
 /**
  * Build the telemetry emitter for this process. Resolves identity + opt-out ONCE; each `emit` builds a
  * fully-validated core event, maps it into PostHog capture shape, and fires a best-effort POST.
@@ -182,7 +218,9 @@ const NOOP = { emit: async () => { }, enabled: false, firstRun: false };
 export const createTelemetry = (opts) => {
     const env = opts.env ?? process.env;
     const cwd = opts.cwd ?? process.cwd();
-    if (isDisabled(env, cwd))
+    // A source checkout silences metrics but must not silence FEEDBACK — see onlyBlockedBySourceCheckout.
+    const feedbackOnly = onlyBlockedBySourceCheckout(env, cwd);
+    if (isDisabled(env, cwd) && !feedbackOnly)
         return NOOP;
     try {
         if (existsSync(OPT_OUT_FILE))
@@ -192,13 +230,15 @@ export const createTelemetry = (opts) => {
         /* unreadable home dir — fall through; the env-var opt-outs above still apply */
     }
     const apiKey = env[Env.KEY] ?? POSTHOG_KEY;
-    if (apiKey === '')
+    if ('' === apiKey)
         return NOOP; // no key baked in (dev/test build) — nowhere to send, stay silent
     const now = opts.now ?? (() => Date.now());
     const doFetch = opts.fetchImpl ?? fetch;
     const url = `${(env[Env.URL] ?? DEFAULT_URL).replace(/\/+$/, '')}${TELEMETRY_PATH}`;
     const ci = env[Env.CI] !== undefined && env[Env.CI] !== '';
     const os = platform();
+    // Negated so it reads the way people say it: UTC+2 is +120, not -120.
+    const tzOffsetMin = -new Date().getTimezoneOffset();
     const { anonymousId, firstRun } = resolveIdentity();
     /**
      * One id per PROCESS, minted in memory and never persisted — which is exactly right: a daemon run
@@ -212,7 +252,22 @@ export const createTelemetry = (opts) => {
         ((command, args) => {
             spawn(command, args, { detached: true, stdio: 'ignore' }).unref();
         });
+    /**
+     * Returns whether the event was actually DELIVERED.
+     *
+     * Every caller but one ignores this and should: a lost metric must never surface to a user. The
+     * exception is `reticle_feedback`, which hands a receipt back to an agent — `sent: true` there was
+     * unconditional, so a DNS miss or a 4xx both read as "filed", and the only qualitative channel the
+     * product has could fail silently while telling the reporter it had worked.
+     *
+     * A detached send reports false: it is handed to a disowned child precisely so the caller does not
+     * wait, so its outcome is genuinely unknown and claiming success would be the same lie.
+     */
     const emit = async (kind, extra) => {
+        // In a Reticle source checkout the emitter carries FEEDBACK and nothing else: somebody typed the
+        // feedback, and no metric is worth phoning home from a contributor's clone.
+        if (feedbackOnly && TelemetryEventKind.FEEDBACK_SUBMITTED !== kind)
+            return false;
         const event = {
             v: TELEMETRY_EVENT_VERSION,
             anonymousId,
@@ -223,6 +278,7 @@ export const createTelemetry = (opts) => {
             version: opts.version,
             ci,
             os,
+            tzOffsetMin,
             projectIdSource,
             ...(extra?.actor !== undefined ? { actor: extra.actor } : {}),
             ...(extra?.command !== undefined ? { command: extra.command } : {}),
@@ -237,19 +293,22 @@ export const createTelemetry = (opts) => {
             ...(extra?.connection !== undefined ? { connection: extra.connection } : {}),
             ...(extra?.init !== undefined ? { init: extra.init } : {}),
             ...(extra?.bug !== undefined ? { bug: extra.bug } : {}),
+            ...(extra?.outage !== undefined ? { outage: extra.outage } : {}),
         };
         // Map the core contract onto PostHog's capture shape: id/name/time move up, the rest are properties.
         // The feedback body is FLATTENED into `feedback_*` properties rather than sent as a nested object:
         // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
         // would be invisible to the exact "which stacks report the most bugs" question this exists to
         // answer. One prefix keeps them grouped in the UI without a nested path.
-        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, outage, ...rest } = event;
         // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
         // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
+        // `sessionId` rides only on events that happened inside a daemon run. A one-shot CLI command
+        // mints a per-process id that joins to nothing and inflates every session count — see
+        // isSessionScoped for the measurement.
         const properties = {
             ...rest,
-            sessionId: eventSessionId,
-            $session_id: eventSessionId,
+            ...(isSessionScoped(name) ? { sessionId: eventSessionId, $session_id: eventSessionId } : {}),
         };
         // Each block is flattened under its own prefix rather than nested. PostHog filters, breakdowns and
         // insight builders all operate on TOP-LEVEL properties, so a nested `project.stack` is invisible to
@@ -269,37 +328,68 @@ export const createTelemetry = (opts) => {
             connection,
             init,
             bug,
+            outage,
         };
         for (const [prefix, block] of Object.entries(blocks)) {
             for (const [key, value] of Object.entries(block ?? {})) {
                 properties[`${prefix}_${key}`] = value;
             }
         }
-        const body = JSON.stringify({
-            api_key: apiKey,
-            batch: [
-                {
-                    event: name,
-                    distinct_id: distinctId,
-                    timestamp: new Date(ts).toISOString(),
-                    properties: { ...properties, ...POSTHOG_PERSONLESS },
-                },
-            ],
-        });
+        const capture = {
+            event: name,
+            distinct_id: distinctId,
+            timestamp: new Date(ts).toISOString(),
+            properties: { ...properties, ...POSTHOG_PERSONLESS },
+        };
+        const body = JSON.stringify({ api_key: apiKey, batch: [capture] });
+        const filePath = env[Env.FILE];
+        if (filePath !== undefined && filePath !== '') {
+            // The SAME payload the wire would have carried, built by the same code path and redacted by
+            // the same rules — so what a run records is what a user would have sent. One JSON object per
+            // line, appended, so a whole sweep lands in one file in order.
+            try {
+                appendFileSync(filePath, `${JSON.stringify(capture)}\n`, 'utf8');
+                return true;
+            }
+            catch {
+                return false; // a sink that cannot write must not take the daemon down
+            }
+        }
         try {
-            if (extra?.detach === true && opts.fetchImpl === undefined) {
+            if (true === extra?.detach && opts.fetchImpl === undefined) {
                 spawnDetached(process.execPath, ['-e', DETACHED_SEND_SCRIPT, url, body]);
-                return;
+                return false; // handed off, outcome unknowable from here
+            }
+            // Feedback is slower and retried; everything else keeps the fire-and-forget budget.
+            const isFeedback = TelemetryEventKind.FEEDBACK_SUBMITTED === kind;
+            const timeoutMs = isFeedback ? FEEDBACK_TIMEOUT_MS : SEND_TIMEOUT_MS;
+            const attempts = 1 + (isFeedback ? FEEDBACK_RETRIES : 0);
+            for (let attempt = 0; attempt < attempts; attempt += 1) {
+                if (0 < attempt) {
+                    await new Promise((r) => setTimeout(r, FEEDBACK_RETRY_BACKOFF_MS * attempt));
+                }
+                try {
+                    const response = await doFetch(url, {
+                        method: 'POST',
+                        headers: { 'content-type': 'application/json' },
+                        body,
+                        signal: AbortSignal.timeout(timeoutMs),
+                    });
+                    // A 4xx is a rejected payload, not a delivery. It must not read as filed. It is also not
+                    // worth retrying — the payload will be rejected again — so only a THROW (timeout, DNS,
+                    // connection reset) goes round again.
+                    return response.ok !== false;
+                }
+                catch (error) {
+                    if (attempt === attempts - 1)
+                        throw error;
+                }
             }
-            await doFetch(url, {
-                method: 'POST',
-                headers: { 'content-type': 'application/json' },
-                body,
-                signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
-            });
+            return false;
         }
         catch {
             /* best-effort: a lost metric must never surface to the user */
+            return false;
         }
     };
     return { emit, enabled: true, firstRun };

package/dist/telemetry/verification-of.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Which tool results count as a completed verification, as one pure rule.
+ *
+ * It used to live inline in `runTool` and read `status === 'pass'`, mapping everything else to
+ * "no verdict". That was wrong in both directions at once, and the shape of the error is visible in
+ * the production data:
+ *
+ *   - a FAILING suite emitted nothing, so `verification_completed` only ever fired on greens while
+ *     `bugsInResult` fired on the reds — bugs with no verifications to divide them by;
+ *   - an EMPTY suite ("all 0 flows pass") emitted `verified: yes, passed: true`.
+ *
+ * Extracted because a rule this easy to get wrong, feeding the one number shown to investors, should
+ * be readable and testable on its own rather than inferred from a ternary inside a dispatcher.
+ */
+import { type BrowserBrand, type Verification } from '@reticlehq/core';
+/**
+ * The verification payload for a result, or undefined when nothing was verified.
+ *
+ * `falseGreenCaught` is the one that matters: the assertion PASSED and Reticle still refused to call
+ * it verified. That is the product's thesis reduced to a boolean.
+ */
+export declare function verificationOf(toolName: string, result: Record<string, unknown>, durationMs: number, brand?: BrowserBrand): Verification | undefined;