@reticlehq/server 2.4.0 → 2.6.0

package/dist/telemetry/feedback-context.d.ts

@@ -1,15 +1,10 @@
 import { McpScope, type Feedback } from '@reticlehq/core';
 /** The context fields — the whole `Feedback` shape minus what the author supplies. */
 export type FeedbackContext = Pick<Feedback, 'stack' | 'stackMajor' | 'runtime' | 'engine' | 'driver' | 'client' | 'clientVersion' | 'mcpScope'>;
-/**
- * The project's framework and its MAJOR version, or `{}` when package.json is absent, unreadable, or
- * names nothing we recognize. The major comes from `parseMajor` — the same range parser `reticle init`
- * uses to decide React 19 source mapping — so a range like `^15.0.0-canary.3` narrows the same way in
- * both places instead of via a second, subtly different reader.
- */
 export declare function detectStack(cwd: string, read?: (path: string) => string): {
     stack?: string;
     stackMajor?: number;
+    stackSource?: 'cwd' | 'workspace';
 };
 /**
  * User scope unless the project checks in its own MCP registration. `reticle init` deliberately
@@ -27,6 +22,28 @@ export interface SessionFacts {
     engine?: string;
     /** True when Reticle drives the page over CDP rather than observing the human's own browser. */
     driven?: boolean;
+    /** What the APP said it is running, from the SDK's hello. The only session-scoped stack evidence. */
+    adapters?: string[];
 }
+/**
+ * Reconcile what the DIRECTORY says with what the APP says.
+ *
+ * `detectStack` reads the daemon's cwd, which is not the session's project whenever one daemon
+ * serves several apps — the normal case for anyone with two dev servers, and the default in the
+ * fixtures. Reported from the field: feedback filed from an astro session arrived stamped
+ * `"stack":"sveltekit"`, because that was the directory the daemon happened to be started in. The
+ * sessionId was passed and ignored.
+ *
+ * The rule: keep the directory's answer only while the app agrees with it. An adapter that implies a
+ * different family means the directory is describing somebody else's project, so the app's own
+ * report wins — less specific, and true, which is the right trade for an attribution field.
+ */
+export declare function reconcileStack(fromCwd: {
+    stack?: string;
+    stackMajor?: number;
+}, adapters: readonly string[] | undefined): {
+    stack?: string;
+    stackMajor?: number;
+};
 /** Assemble the full context. Every field independently optional — a partial context still ships. */
 export declare function feedbackContext(cwd: string, session?: SessionFacts): FeedbackContext;

package/dist/telemetry/feedback-context.js

@@ -9,10 +9,11 @@
  * holds to. Detection is entirely best-effort: an unreadable package.json or an SDK too old to report
  * its runtime yields `undefined`, never a throw and never a guess.
  */
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
 import { AppRuntime, McpScope, PageDriver } from '@reticlehq/core';
 import { parseMajor } from '../init/detect.js';
+import { findWorkspaceApps } from '../init/run.js';
 /**
  * Dependency → reported stack, in resolution order. Meta-frameworks come FIRST: a Next app also
  * depends on react, and reporting `react` for it would collapse the single most important segment
@@ -44,10 +45,10 @@ const PROJECT_MCP_FILES = ['.mcp.json', join('.cursor', 'mcp.json'), join('.vsco
  * uses to decide React 19 source mapping — so a range like `^15.0.0-canary.3` narrows the same way in
  * both places instead of via a second, subtly different reader.
  */
-export function detectStack(cwd, read = readFile) {
+function stackOfManifest(dir, read) {
     let pkg;
     try {
-        pkg = JSON.parse(read(join(cwd, PACKAGE_JSON)));
+        pkg = JSON.parse(read(join(dir, PACKAGE_JSON)));
     }
     catch {
         return {};
@@ -62,6 +63,65 @@ export function detectStack(cwd, read = readFile) {
     }
     return {};
 }
+export function detectStack(cwd, read = readFile) {
+    // The cwd wins when it IS an app — never redirect away from the real answer.
+    const here = stackOfManifest(cwd, read);
+    if (here.stack !== undefined)
+        return { ...here, stackSource: 'cwd' };
+    // Otherwise look for the app. The daemon's cwd is wherever the agent's client happened to launch,
+    // which for a real repo is the ROOT while the app sits in `frontend/`, `web/`, or a declared
+    // workspace. Reading one directory and giving up is why this returned nothing for every project
+    // that actually had Reticle set up: 0 of 77 instrumented projects, and 0 of 166 `size: huge` ones.
+    // The bigger the repo, the more certainly we failed.
+    //
+    // `findWorkspaceApps` is init's discovery, reused rather than reimplemented: it already reads
+    // declared workspaces (pnpm-workspace.yaml, package.json `workspaces`) AND scans top-level
+    // directories, and it was widened once already for a repo shape a user hit twice. A second
+    // detector here would drift from it the first time either changed.
+    try {
+        for (const app of findWorkspaceApps(profileIo(cwd))) {
+            const found = stackOfManifest(join(cwd, app), read);
+            // Reported as `workspace` so the share of projects needing discovery is measurable — that
+            // number is what says whether our inference needs an agent to correct it.
+            if (found.stack !== undefined)
+                return { ...found, stackSource: 'workspace' };
+        }
+    }
+    catch {
+        // Discovery touches the filesystem; a permission error must never cost us the profile event.
+    }
+    return {};
+}
+/**
+ * The three filesystem methods `findWorkspaceApps` needs, rooted at `cwd`.
+ *
+ * Deliberately not the whole `InitIo`: this path must not be able to write, exec or print. What it
+ * cannot do is a stronger guarantee than a rule saying it shouldn't.
+ */
+function profileIo(cwd) {
+    const abs = (rel) => (isAbsolute(rel) ? rel : join(cwd, rel));
+    return {
+        readFile: (rel) => {
+            try {
+                return readFileSync(abs(rel), 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        exists: (rel) => existsSync(abs(rel)),
+        listDirs: (rel) => {
+            try {
+                return readdirSync(abs(rel), { withFileTypes: true })
+                    .filter((e) => e.isDirectory() && !e.name.startsWith('.') && 'node_modules' !== e.name)
+                    .map((e) => e.name);
+            }
+            catch {
+                return [];
+            }
+        },
+    };
+}
 /**
  * User scope unless the project checks in its own MCP registration. `reticle init` deliberately
  * registers ONCE at user scope, so `project` here means the team wired it up by hand — which is
@@ -116,6 +176,43 @@ function detectClient() {
         return {};
     }
 }
+/**
+ * Which cwd-derived stacks each SDK adapter is consistent with.
+ *
+ * The adapter names a UI library; the directory may name a meta-framework built on it. `react` and
+ * `next` are the same app described at two levels, so the more specific one is kept. `react` and
+ * `sveltekit` are not — that pairing means the daemon's directory is not this session's project.
+ */
+const ADAPTER_IMPLIES = {
+    react: ['react', 'next', 'remix'],
+    svelte: ['svelte', 'sveltekit'],
+    vue: ['vue', 'nuxt'],
+    solid: ['solid'],
+    angular: ['angular'],
+};
+/**
+ * Reconcile what the DIRECTORY says with what the APP says.
+ *
+ * `detectStack` reads the daemon's cwd, which is not the session's project whenever one daemon
+ * serves several apps — the normal case for anyone with two dev servers, and the default in the
+ * fixtures. Reported from the field: feedback filed from an astro session arrived stamped
+ * `"stack":"sveltekit"`, because that was the directory the daemon happened to be started in. The
+ * sessionId was passed and ignored.
+ *
+ * The rule: keep the directory's answer only while the app agrees with it. An adapter that implies a
+ * different family means the directory is describing somebody else's project, so the app's own
+ * report wins — less specific, and true, which is the right trade for an attribution field.
+ */
+export function reconcileStack(fromCwd, adapters) {
+    const claimed = adapters?.find((adapter) => adapter in ADAPTER_IMPLIES);
+    if (claimed === undefined)
+        return fromCwd;
+    const consistent = ADAPTER_IMPLIES[claimed] ?? [];
+    if (fromCwd.stack !== undefined && consistent.includes(fromCwd.stack))
+        return fromCwd;
+    // The major belonged to the directory's framework, so it cannot travel with a different stack.
+    return { stack: claimed };
+}
 function asRuntime(value) {
     return Object.values(AppRuntime).find((known) => known === value);
 }
@@ -131,7 +228,10 @@ export function feedbackContext(cwd, session) {
     const engine = asEngine(session?.engine);
     const client = detectClient();
     return {
-        ...detectStack(cwd),
+        // Session-scoped when the app reports something that contradicts the directory — see
+        // reconcileStack. A daemon serving two apps otherwise stamps both with whichever one it was
+        // started next to.
+        ...reconcileStack(detectStack(cwd), session?.adapters),
         ...client,
         ...(runtime !== undefined ? { runtime } : {}),
         ...(engine !== undefined ? { engine } : {}),

package/dist/telemetry/feedback-delivery.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Telling the reporter that a BACKGROUND feedback delivery failed.
+ *
+ * The agent's `reticle_feedback` no longer waits for the POST — a ~340ms network round-trip on the
+ * one call an agent makes mid-task is the product blocking the user's work to talk about itself. But
+ * not waiting reopens the exact hole the awaited version was written to close: `sent` used to be
+ * unconditional, so a DNS miss and a 4xx both reported "filed", and this is the ONLY qualitative
+ * channel the product has. A lost report that was announced as filed is worse than no channel.
+ *
+ * So the wait goes and the honesty stays: the receipt says ACCEPTED (validated, redacted, queued),
+ * never "delivered", and if the send then fails the agent is told on its next tool result through
+ * the same one-shot envelope the update and skew nudges use. Told once — a reporter who cannot fix
+ * the network does not need it repeated, and a banner on every call is one agents learn to skip.
+ */
+/** Record that a queued report never made it. */
+export declare function noteFeedbackUndelivered(reason: string): void;
+/** The undelivered-feedback notice, once. */
+export declare function takeFeedbackUndelivered(): string | undefined;
+/** Tests only — drop the module state so each case starts clean. */
+export declare function resetFeedbackDelivery(): void;

package/dist/telemetry/feedback-delivery.js

@@ -0,0 +1,30 @@
+/**
+ * Telling the reporter that a BACKGROUND feedback delivery failed.
+ *
+ * The agent's `reticle_feedback` no longer waits for the POST — a ~340ms network round-trip on the
+ * one call an agent makes mid-task is the product blocking the user's work to talk about itself. But
+ * not waiting reopens the exact hole the awaited version was written to close: `sent` used to be
+ * unconditional, so a DNS miss and a 4xx both reported "filed", and this is the ONLY qualitative
+ * channel the product has. A lost report that was announced as filed is worse than no channel.
+ *
+ * So the wait goes and the honesty stays: the receipt says ACCEPTED (validated, redacted, queued),
+ * never "delivered", and if the send then fails the agent is told on its next tool result through
+ * the same one-shot envelope the update and skew nudges use. Told once — a reporter who cannot fix
+ * the network does not need it repeated, and a banner on every call is one agents learn to skip.
+ */
+/** Set when a background feedback send failed and the reporter has not been told yet. */
+let pending;
+/** Record that a queued report never made it. */
+export function noteFeedbackUndelivered(reason) {
+    pending = reason;
+}
+/** The undelivered-feedback notice, once. */
+export function takeFeedbackUndelivered() {
+    const notice = pending;
+    pending = undefined;
+    return notice;
+}
+/** Tests only — drop the module state so each case starts clean. */
+export function resetFeedbackDelivery() {
+    pending = undefined;
+}

package/dist/telemetry/feedback-outbox.d.ts

@@ -0,0 +1,22 @@
+/** One queued report: the payload, plus what is needed to find and remove it again. */
+export interface OutboxEntry {
+    id: string;
+    t: string;
+    payload: unknown;
+}
+export declare function outboxPath(home?: string): string;
+/**
+ * Persist a report and return its id. Never throws: failing to queue must not also fail the send
+ * that was about to happen anyway.
+ */
+export declare function queueFeedback(payload: unknown, now?: () => Date, home?: string): string | null;
+/** Read every queued report. A malformed line is skipped, never fatal — the rest still matter. */
+export declare function readOutbox(home?: string): OutboxEntry[];
+/**
+ * Drop a report that was delivered. Rewrites the file without it.
+ *
+ * A rewrite rather than a tombstone because the file's whole purpose is "what still needs sending" —
+ * a reader should be able to `cat` it and see exactly the backlog, with no filtering rule to learn.
+ * Volume is a handful of lines a week, so the cost is irrelevant.
+ */
+export declare function markDelivered(id: string | null, home?: string): void;

package/dist/telemetry/feedback-outbox.js

@@ -0,0 +1,87 @@
+/**
+ * A durable outbox for feedback, written BEFORE the network is touched.
+ *
+ * Feedback is the only qualitative channel this product has, and it carries an agent's whole
+ * root-cause analysis — often an hour of driving distilled into one payload. It was sent with the
+ * same 2-second fire-and-forget budget as a usage counter, with no retry and no persistence, so a
+ * 1.3-second network hiccup destroyed the report outright. Measured to the collector from one
+ * machine with a WARM DNS cache: dns 0.003s, connect 0.233s, tls 0.467s, total 0.694s — roughly a
+ * third of the entire budget spent before a byte of payload moves, and that is the good case. A
+ * fresh short-lived CLI process pays cold DNS and a cold route on top.
+ *
+ * So the order is inverted: write it down first, then try to send. A failed send is then a queued
+ * report rather than a lost one, and `sent: false` becomes a statement about the network instead of
+ * an epitaph.
+ *
+ * JSONL, appended, one payload per line. Append-only is the point — a crash mid-write costs at most
+ * the line being written, never the ones already there.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { ReticleDir } from '@reticlehq/core';
+export function outboxPath(home = homedir()) {
+    return join(home, ReticleDir.ROOT, 'feedback-outbox.jsonl');
+}
+/**
+ * Persist a report and return its id. Never throws: failing to queue must not also fail the send
+ * that was about to happen anyway.
+ */
+export function queueFeedback(payload, now = () => new Date(), home = homedir()) {
+    const id = randomUUID();
+    try {
+        mkdirSync(join(home, ReticleDir.ROOT), { recursive: true });
+        const entry = { id, t: now().toISOString(), payload };
+        appendFileSync(outboxPath(home), `${JSON.stringify(entry)}\n`, 'utf8');
+        return id;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read every queued report. A malformed line is skipped, never fatal — the rest still matter. */
+export function readOutbox(home = homedir()) {
+    try {
+        const path = outboxPath(home);
+        if (!existsSync(path))
+            return [];
+        return readFileSync(path, 'utf8')
+            .split('\n')
+            .filter((line) => 0 < line.trim().length)
+            .flatMap((line) => {
+            try {
+                return [JSON.parse(line)];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Drop a report that was delivered. Rewrites the file without it.
+ *
+ * A rewrite rather than a tombstone because the file's whole purpose is "what still needs sending" —
+ * a reader should be able to `cat` it and see exactly the backlog, with no filtering rule to learn.
+ * Volume is a handful of lines a week, so the cost is irrelevant.
+ */
+export function markDelivered(id, home = homedir()) {
+    if (null === id)
+        return;
+    try {
+        const remaining = readOutbox(home).filter((entry) => entry.id !== id);
+        const path = outboxPath(home);
+        if (0 === remaining.length) {
+            writeFileSync(path, '', 'utf8');
+            return;
+        }
+        writeFileSync(path, `${remaining.map((entry) => JSON.stringify(entry)).join('\n')}\n`, 'utf8');
+    }
+    catch {
+        // A report that stays queued after a successful send is a duplicate at worst. Losing one is not.
+    }
+}

package/dist/telemetry/feedback.d.ts

@@ -39,8 +39,21 @@ export declare function feedbackDisabled(env?: NodeJS.ProcessEnv): boolean;
 /** What the author supplies; the environment context is detected, never asked for. */
 export type FeedbackInput = Pick<Feedback, 'source' | 'kind' | 'text' | 'trace' | 'rating' | 'need' | 'impact' | 'currentApproach' | 'model'>;
 export interface FeedbackReceipt {
-    /** False when a kill switch is on — the report was DROPPED, and the caller is told so plainly. */
+    /**
+     * DELIVERY confirmed. Only ever true when the send was awaited and the endpoint accepted it —
+     * never as an optimistic stand-in for "we handed it to the emitter". That distinction is the whole
+     * value of this field: it was once unconditional, so a DNS miss and a 4xx both reported "filed".
+     *
+     * A backgrounded send (the agent tool) therefore returns `sent: false` with `accepted: true` —
+     * see below. It is not a failure, and the note says so.
+     */
     sent: boolean;
+    /**
+     * Validated, redacted and handed to the emitter. TRUE says the report is well-formed and on its
+     * way; it does NOT say it arrived. If a backgrounded send then fails, the reporter is told on its
+     * next tool result — see feedback-delivery.ts.
+     */
+    accepted: boolean;
     reason?: string;
     /** Which redaction rules fired. Empty when nothing needed removing. */
     redacted: string[];
@@ -56,6 +69,14 @@ export declare function submitFeedback(input: FeedbackInput, opts?: {
     cwd?: string;
     session?: SessionFacts;
     env?: NodeJS.ProcessEnv;
+    /**
+     * Return as soon as the report is validated and queued, instead of waiting out the POST.
+     *
+     * Used by the AGENT tool: ~340ms of network on a call made mid-task is the product blocking the
+     * user's work to talk about itself. NOT used by `reticle feedback`, where a human typed the
+     * command and is waiting for an answer — there, confirmed delivery is the answer.
+     */
+    background?: boolean;
 }): Promise<FeedbackReceipt>;
 /**
  * The receipt's context PLUS the fields the emitter stamps on every event regardless of kind — the

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.d.ts

@@ -6,6 +6,13 @@ export interface GitFacts {
     origin?: string;
     /** Which forge hosts it, bucketed. Absent unless state is `remote`. */
     forge?: RepoForge;
+    /**
+     * The directory holding `.git` — the repo boundary. Absent only when state is `none`.
+     *
+     * Never sent: it is a local path. It exists so an UNPUSHED repo can still key its projectId to
+     * something stable across every directory inside it, which a raw cwd is not.
+     */
+    root?: string;
 }
 /** `git@github.com:Acme/Web.git` / `https://u:p@github.com/Acme/Web` → `github.com/acme/web`. */
 export declare const normalizeGitOrigin: (url: string) => string;

package/dist/telemetry/git-facts.js

@@ -88,17 +88,17 @@ export function gitFacts(cwd, read = defaultRead, exists = defaultExists) {
             }
             catch {
                 // A `.git` with no readable config is still a repo — report it as one rather than as absent.
-                return { state: GitState.LOCAL_ONLY };
+                return { state: GitState.LOCAL_ONLY, root: dir };
             }
             // The url line inside the [remote "origin"] section — the first url after that header wins.
             const section = config.split(/\[remote\s+"origin"\]/)[1];
             const url = section?.match(/^\s*url\s*=\s*(.+)$/m)?.[1];
             if (url === undefined)
-                return { state: GitState.LOCAL_ONLY };
+                return { state: GitState.LOCAL_ONLY, root: dir };
             const origin = normalizeGitOrigin(url);
-            if (origin === '')
-                return { state: GitState.LOCAL_ONLY };
-            return { state: GitState.REMOTE, origin, forge: forgeOf(origin) };
+            if ('' === origin)
+                return { state: GitState.LOCAL_ONLY, root: dir };
+            return { state: GitState.REMOTE, origin, forge: forgeOf(origin), root: dir };
         }
         const parent = dirname(dir);
         if (parent === dir)

package/dist/telemetry/project-profile.js

@@ -180,13 +180,14 @@ export function profileProject(cwd, now) {
         featuresUsed.push(FeatureFamily.BUG_CAPSULES);
     if (hasHistory)
         featuresUsed.push(FeatureFamily.CROSS_RUN_HISTORY);
-    const { stack, stackMajor } = detectStack(cwd);
+    const { stack, stackMajor, stackSource } = detectStack(cwd);
     const ageWeeks = projectAgeWeeks(cwd, now);
     const git = gitFacts(cwd);
     return {
         git: git.state,
         ...(git.forge !== undefined ? { forge: git.forge } : {}),
         ...(stack !== undefined ? { stack } : {}),
+        ...(stackSource !== undefined ? { stackSource } : {}),
         ...(stackMajor !== undefined ? { stackMajor } : {}),
         size: sizeBucket(countSourceFiles(cwd)),
         monorepo: isMonorepo(cwd),

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

@@ -41,7 +41,15 @@ export declare class SessionMetrics {
      */
     recordBrowserLatency(ms: number): void;
     /** A call for a tool that does not exist. Non-zero means our surface is confusing the agent. */
-    recordUnknownTool(): void;
+    /**
+     * An agent reached for a tool that does not exist — and WHAT it reached for.
+     *
+     * The name is the point. A count says the surface confused someone; the name says which
+     * capability they expected us to have, in their own vocabulary. Safe to keep: it is a name from
+     * our own namespace, never app data. Bounded and truncated, because a guess is a short
+     * identifier and anything longer is not one.
+     */
+    recordUnknownTool(name?: string): void;
     recordToolCall(tool: string, args?: Record<string, unknown>): void;
     /**
      * One failed tool call. Grouped by fingerprint, but stored WITH its skeleton message and the tool
@@ -62,6 +70,28 @@ export declare class SessionMetrics {
         breadcrumb: string[];
         inFlight: string | undefined;
     };
+    /**
+     * Ask the agent for a verdict, once, when it has driven the page without asking for one.
+     *
+     * Measured 2026-08-10/11: of 170 sessions that made a tool call, 140 produced no verdict — and
+     * **137 of those never called a verdict-producing tool even once.** They drove the app 269 times
+     * with `reticle_act` and never asked whether it worked. This counter already existed
+     * (`abandonedActions`, non-zero in 58 sessions); it was reported to US and never to the agent.
+     *
+     * Three is the threshold because the median verdict-less session made four tool calls: any higher
+     * and it never fires for the sessions that need it. Re-arms after a verdict, so a second
+     * abandoned run is caught — the loop can break more than once in a long session.
+     */
+    takeUnverifiedNudge(): string | undefined;
+    /**
+     * An app's SDK dialled this daemon.
+     *
+     * Zero of these at shutdown means the daemon ran and no app ever connected — a broken install.
+     * Non-zero with no tool calls is the opposite problem. See SessionSummary.appConnects.
+     */
+    recordAppConnected(): void;
+    /** 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.
@@ -80,12 +110,26 @@ export declare class SessionMetrics {
      * express failure misses the only question worth asking: how often can people not get a browser?
      */
     recordConnectAttempt(kind: BrowserLaunchKind): (failure?: ConnectFailure) => void;
-    recordClient(name: string): void;
+    recordClient(name: string, version?: string): void;
+    /**
+     * The agent's client went away.
+     *
+     * This is the only part of `endReason` that a query cannot derive from the counters: "the client
+     * detached" and "the agent stopped asking" produce identical numbers and are different findings —
+     * one is the task ending, the other is us losing them.
+     */
+    recordClientLeft(): void;
+    /** How many times in a row the current tool has been called. Read by the friction invite. */
+    get currentRun(): number;
+    /** Reticle invited the agent to send feedback. The denominator for feedback_submitted. */
+    recordFeedbackPrompt(): void;
+    /** Which tool surface was advertised to agents this session. */
+    recordSurface(surface: string): void;
     /**
      * Roll the counters into the event payload. `final` marks a clean shutdown; a periodic flush passes
      * false so a session killed before it can exit is not lost entirely (see the flush note in cli.ts).
      */
-    summarize(final: boolean): SessionSummary;
+    summarize(final: boolean, exit?: SessionSummary['exit']): SessionSummary;
     /** True when nothing at all happened — a flush of an idle daemon is not worth an event. */
     get empty(): boolean;
     /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */