@reticlehq/server 2.2.1 → 2.3.0

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

@@ -0,0 +1,31 @@
+import { TelemetryAction } from '../cli-parse.js';
+/**
+ * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the human half of the feedback channel.
+ *
+ * Kept to a single command with no prompts, no editor, and no account: the cost of telling us
+ * something has to be lower than the cost of shrugging and moving on, or we only ever hear from people
+ * angry enough to open an issue. A bare rating is a valid report; the words are optional garnish.
+ *
+ * What is sent is PRINTED before it goes, every time. A channel that carries free text and does not
+ * show you the payload is asking for trust it has not earned.
+ */
+export declare function handleFeedback(text: string, rating: number | undefined, bug: boolean): Promise<void>;
+/**
+ * `reticle identify` — opt-in, and it shows the consent notice before it sends anything.
+ *
+ * Deliberately NOT interactive: a prompt that appears in the middle of someone's work is pressure,
+ * and this is the one command where the user must be choosing freely. They type what they want to
+ * share, or they never run it at all.
+ */
+export declare function handleIdentify(parsed: {
+    context?: string;
+    company?: string;
+    email?: string;
+    forget: boolean;
+}): Promise<void>;
+/**
+ * `reticle telemetry [status|enable|disable]` — the user-facing control for anonymous usage metrics.
+ * `disable` persists a machine-wide opt-out (survives shells, unlike RETICLE_TELEMETRY=0); `status`
+ * says what's on, why, and where the full policy lives. Human-readable to stdout, like `doctor`.
+ */
+export declare function handleTelemetry(action: TelemetryAction): void;

package/dist/telemetry/feedback-cli.js

@@ -0,0 +1,102 @@
+import { FeedbackKind, FeedbackSource } from '@reticlehq/core';
+import { BUG_FLAG, RATING_FLAG } from '../cli-parse.js';
+import { describeFeedbackPayload, submitFeedback } from './feedback.js';
+import { describeTelemetry, setTelemetryEnabled } from './telemetry.js';
+import { TelemetryAction } from '../cli-parse.js';
+import { clearIdentity, IDENTIFY_NOTICE, readIdentity, saveIdentity, submitIdentity, UsageContextKind, } from './identify.js';
+/**
+ * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the human half of the feedback channel.
+ *
+ * Kept to a single command with no prompts, no editor, and no account: the cost of telling us
+ * something has to be lower than the cost of shrugging and moving on, or we only ever hear from people
+ * angry enough to open an issue. A bare rating is a valid report; the words are optional garnish.
+ *
+ * What is sent is PRINTED before it goes, every time. A channel that carries free text and does not
+ * show you the payload is asking for trust it has not earned.
+ */
+export async function handleFeedback(text, rating, bug) {
+    const line = (s) => {
+        process.stdout.write(`${s}\n`);
+    };
+    if (text === '' && rating === undefined) {
+        line(`usage: reticle feedback [${RATING_FLAG} 1-5] [${BUG_FLAG}] "what worked, what didn't"`);
+        line('       your words go to the maintainers; nothing from your app is ever included.');
+        process.exitCode = 1;
+        return;
+    }
+    const receipt = await submitFeedback({
+        source: FeedbackSource.HUMAN,
+        kind: bug ? FeedbackKind.BUG : FeedbackKind.EXPERIENCE,
+        // A rating with no words is a real report, but the schema wants text — say what the rating means.
+        text: text === '' ? `rated ${String(rating)}/5 with no comment` : text,
+        ...(rating !== undefined ? { rating } : {}),
+    });
+    line(`sending      ${JSON.stringify(describeFeedbackPayload(receipt.context))}`);
+    if (receipt.redacted.length > 0) {
+        line(`redacted     ${receipt.redacted.join(', ')} (removed before sending)`);
+    }
+    line(receipt.sent
+        ? 'thanks       your feedback is in. it genuinely changes what gets built next.'
+        : `not sent     ${receipt.reason ?? 'unknown reason'}`);
+}
+/**
+ * `reticle identify` — opt-in, and it shows the consent notice before it sends anything.
+ *
+ * Deliberately NOT interactive: a prompt that appears in the middle of someone's work is pressure,
+ * and this is the one command where the user must be choosing freely. They type what they want to
+ * share, or they never run it at all.
+ */
+export async function handleIdentify(parsed) {
+    const line = (s) => {
+        process.stdout.write(`${s}\n`);
+    };
+    if (parsed.forget) {
+        clearIdentity();
+        line('forgotten    the local identity file is deleted; nothing further is sent.');
+        line('             to have what was already sent removed, email support@reticlehq.com');
+        return;
+    }
+    const context = Object.values(UsageContextKind).find((k) => k === parsed.context);
+    if (context === undefined) {
+        const existing = readIdentity();
+        if (existing !== undefined)
+            line(`current      ${JSON.stringify(existing)}`);
+        line(`usage: reticle identify --context <${Object.values(UsageContextKind).join('|')}>`);
+        line('       [--company "Acme"] [--email you@acme.com] [--forget]');
+        line('');
+        line(IDENTIFY_NOTICE);
+        process.exitCode = existing === undefined ? 1 : 0;
+        return;
+    }
+    const identity = {
+        context,
+        ...(parsed.company !== undefined ? { company: parsed.company } : {}),
+        ...(parsed.email !== undefined ? { email: parsed.email } : {}),
+    };
+    line(IDENTIFY_NOTICE);
+    line('');
+    line(`sending      ${JSON.stringify(identity)}`);
+    saveIdentity(identity);
+    const sent = await submitIdentity(identity);
+    line(sent
+        ? 'thanks       saved and sent. we may reach out; `reticle identify --forget` undoes this.'
+        : 'not sent     telemetry is disabled on this machine, so it was saved locally only.');
+}
+/**
+ * `reticle telemetry [status|enable|disable]` — the user-facing control for anonymous usage metrics.
+ * `disable` persists a machine-wide opt-out (survives shells, unlike RETICLE_TELEMETRY=0); `status`
+ * says what's on, why, and where the full policy lives. Human-readable to stdout, like `doctor`.
+ */
+export function handleTelemetry(action) {
+    const line = (s) => {
+        process.stdout.write(`${s}\n`);
+    };
+    if (action !== TelemetryAction.STATUS) {
+        setTelemetryEnabled(action === TelemetryAction.ENABLE);
+    }
+    const state = describeTelemetry();
+    line(`telemetry    ${state.enabled ? 'enabled' : 'disabled'}  (${state.reason})`);
+    line(`policy       ${state.policyUrl}`);
+    if (state.enabled)
+        line('opt out      reticle telemetry disable  (or RETICLE_TELEMETRY=0 / DO_NOT_TRACK=1)');
+}

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

@@ -0,0 +1,32 @@
+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;
+};
+/**
+ * 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
+ * itself the interesting signal.
+ */
+export declare function detectMcpScope(cwd: string, exists?: (path: string) => boolean): McpScope;
+export declare function setMcpClientNameHook(hook: () => {
+    name?: string;
+    version?: string;
+} | undefined): void;
+/** What the connected session knows about itself — the shell it runs in and its rendering engine. */
+export interface SessionFacts {
+    runtime?: string;
+    engine?: string;
+    /** True when Reticle drives the page over CDP rather than observing the human's own browser. */
+    driven?: boolean;
+}
+/** 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

@@ -0,0 +1,143 @@
+/**
+ * The environment context stapled to every feedback report. Feedback without it is a complaint;
+ * feedback with it is a work item — "reticle_act misses the click" is unactionable, "reticle_act
+ * misses the click on Tauri + SvelteKit under a CDP driver" names the bug.
+ *
+ * Everything here is detected LOCALLY from files and env already on the machine, and every field is
+ * low-cardinality by construction (an enum, or a framework name off a fixed list). No paths, no repo
+ * names, no dependency inventory, no UA string — the same non-identifying bar the rest of telemetry
+ * 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 { AppRuntime, McpScope, PageDriver } from '@reticlehq/core';
+import { parseMajor } from '../init/detect.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
+ * we have into the generic bucket.
+ *
+ * Deliberately NOT reusing `init/detect.ts`. That module answers a different question — "which build
+ * integration do I install?" — so its enum stops at next/vite/sveltekit/html. Widening it to carry
+ * vue/astro/solid would make `reticle init` branch on frameworks it has no install path for.
+ */
+const STACK_BY_DEP = [
+    ['next', 'next'],
+    ['@sveltejs/kit', 'sveltekit'],
+    ['nuxt', 'nuxt'],
+    ['astro', 'astro'],
+    ['@remix-run/react', 'remix'],
+    ['@angular/core', 'angular'],
+    ['react', 'react'],
+    ['vue', 'vue'],
+    ['svelte', 'svelte'],
+    ['solid-js', 'solid'],
+    ['vite', 'vite'],
+];
+const PACKAGE_JSON = 'package.json';
+/** A project-scoped MCP registration lives in one of these; `reticle init` writes user scope instead. */
+const PROJECT_MCP_FILES = ['.mcp.json', join('.cursor', 'mcp.json'), join('.vscode', 'mcp.json')];
+/**
+ * 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 function detectStack(cwd, read = readFile) {
+    let pkg;
+    try {
+        pkg = JSON.parse(read(join(cwd, PACKAGE_JSON)));
+    }
+    catch {
+        return {};
+    }
+    const deps = { ...pkg.devDependencies, ...pkg.dependencies };
+    for (const [dep, stack] of STACK_BY_DEP) {
+        const range = deps[dep];
+        if (range === undefined)
+            continue;
+        const stackMajor = parseMajor(range);
+        return { stack, ...(stackMajor !== undefined ? { stackMajor } : {}) };
+    }
+    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
+ * itself the interesting signal.
+ */
+export function detectMcpScope(cwd, exists = fileExists) {
+    return PROJECT_MCP_FILES.some((file) => exists(join(cwd, file)))
+        ? McpScope.PROJECT
+        : McpScope.USER;
+}
+function readFile(path) {
+    return readFileSync(path, 'utf8');
+}
+function fileExists(path) {
+    try {
+        readFileSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The MCP client on the other end, self-reported in its `initialize` handshake (`claude-code`,
+ * `cursor-vscode`, …). Read through a HOOK rather than sniffing env vars: the handshake is the
+ * client's own claim about itself, while an env-var table is a guess that silently rots every time a
+ * vendor renames a variable. Unset (a CLI run with no MCP peer) simply reports no client.
+ */
+let clientNameHook;
+export function setMcpClientNameHook(hook) {
+    clientNameHook = hook;
+}
+/**
+ * The client's own name and version from its handshake.
+ *
+ * Note what is NOT here and cannot be: the MODEL. MCP's `clientInfo` carries a name, a title and a
+ * version and has no concept of a model, so the transport genuinely cannot tell us. The agent
+ * self-reports it on the feedback itself, which is the only mechanism available and a reliable one
+ * given the report is already something the agent authored.
+ */
+function detectClient() {
+    try {
+        const info = clientNameHook?.();
+        const name = info?.name;
+        const version = info?.version;
+        return {
+            ...(name !== undefined && name !== '' ? { client: name.slice(0, 64) } : {}),
+            ...(version !== undefined && version !== '' ? { clientVersion: version.slice(0, 32) } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function asRuntime(value) {
+    return Object.values(AppRuntime).find((known) => known === value);
+}
+function asEngine(value) {
+    // The SDK already narrows to blink/gecko/webkit before it reports, so anything else is a stale or
+    // hand-forged payload — drop it rather than widen the enum at the boundary.
+    const known = ['blink', 'gecko', 'webkit'];
+    return known.find((engine) => engine === value);
+}
+/** Assemble the full context. Every field independently optional — a partial context still ships. */
+export function feedbackContext(cwd, session) {
+    const runtime = asRuntime(session?.runtime);
+    const engine = asEngine(session?.engine);
+    const client = detectClient();
+    return {
+        ...detectStack(cwd),
+        ...client,
+        ...(runtime !== undefined ? { runtime } : {}),
+        ...(engine !== undefined ? { engine } : {}),
+        ...(session?.driven !== undefined
+            ? { driver: session.driven ? PageDriver.CDP : PageDriver.SDK }
+            : {}),
+        mcpScope: detectMcpScope(cwd),
+    };
+}

package/dist/telemetry/feedback.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The feedback channel — the one place in Reticle that sends words someone wrote.
+ *
+ * Reticle is built for agents, and until now nothing closed the loop: when a tool misbehaved, or a
+ * verification came back undecidable, or an observer simply could not see the thing that mattered,
+ * that knowledge died in the agent's context window. This module is the return path. An agent files a
+ * report through `reticle_feedback` when a tool fails it; a human files one through `reticle
+ * feedback` with a rating and their own words.
+ *
+ * Three properties are non-negotiable here, because free text is a different privacy class from the
+ * event counters the rest of telemetry sends:
+ *
+ *   1. NEVER PASSIVE. There is no code path that emits feedback on its own. Every event is the direct
+ *      result of an explicit call someone made carrying content they authored. Nothing is scraped
+ *      from the app, the DOM, the network log, or the repo.
+ *   2. REDACTED BEFORE THE WIRE. `redactFeedbackText` strips the credential/PII shapes that leak into
+ *      a pasted trace even when the author meant no harm. It runs client-side, so the redaction is
+ *      auditable in this repo rather than promised in a policy.
+ *   3. INDEPENDENTLY DISABLE-ABLE. `RETICLE_FEEDBACK=0` kills the channel while leaving anonymous
+ *      adoption metrics on — the setting an org wants when counters are fine but prose is not. Every
+ *      existing switch (`RETICLE_TELEMETRY=0`, `DO_NOT_TRACK`, `reticle telemetry disable`) still
+ *      disables it too, since it rides the same emitter.
+ */
+import { type Feedback } from '@reticlehq/core';
+import { type SessionFacts } from './feedback-context.js';
+/** Kills the feedback channel ONLY — adoption counters keep flowing. */
+export declare const FEEDBACK_ENV = "RETICLE_FEEDBACK";
+/** What replaces a redacted match. Visible on purpose: a reader must see that something was removed. */
+export declare const REDACTED = "[redacted]";
+export interface Redaction {
+    text: string;
+    /** Which rules fired, deduped. Surfaced back to the author so a redaction is never silent. */
+    removed: string[];
+}
+/** Strip credential/PII shapes and cap the length. Pure — the tests read like a spec of what leaks. */
+export declare function redactFeedbackText(input: string, max: number): Redaction;
+/** True when the feedback channel is switched off on its own (the emitter's switches apply as well). */
+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. */
+    sent: boolean;
+    reason?: string;
+    /** Which redaction rules fired. Empty when nothing needed removing. */
+    redacted: string[];
+    /** The exact context that went with it, echoed back so the send is never a black box. */
+    context: Partial<Feedback>;
+}
+/**
+ * Redact, validate, and emit one feedback report. Returns a receipt rather than throwing: a feedback
+ * send that fails must never take down the tool call that reported the failure — that would punish
+ * the exact behaviour we are trying to encourage.
+ */
+export declare function submitFeedback(input: FeedbackInput, opts?: {
+    cwd?: string;
+    session?: SessionFacts;
+    env?: NodeJS.ProcessEnv;
+}): Promise<FeedbackReceipt>;
+/**
+ * The receipt's context PLUS the fields the emitter stamps on every event regardless of kind — the
+ * reticle version, the OS, and whether this is CI. They are the single most-asked question of any bug
+ * report ("what version?"), so they are echoed here rather than left as an invisible claim: what the
+ * CLI prints is then genuinely everything that goes.
+ */
+export declare function describeFeedbackPayload(context: Partial<Feedback>): Record<string, unknown>;

package/dist/telemetry/feedback.js

@@ -0,0 +1,175 @@
+/**
+ * The feedback channel — the one place in Reticle that sends words someone wrote.
+ *
+ * Reticle is built for agents, and until now nothing closed the loop: when a tool misbehaved, or a
+ * verification came back undecidable, or an observer simply could not see the thing that mattered,
+ * that knowledge died in the agent's context window. This module is the return path. An agent files a
+ * report through `reticle_feedback` when a tool fails it; a human files one through `reticle
+ * feedback` with a rating and their own words.
+ *
+ * Three properties are non-negotiable here, because free text is a different privacy class from the
+ * event counters the rest of telemetry sends:
+ *
+ *   1. NEVER PASSIVE. There is no code path that emits feedback on its own. Every event is the direct
+ *      result of an explicit call someone made carrying content they authored. Nothing is scraped
+ *      from the app, the DOM, the network log, or the repo.
+ *   2. REDACTED BEFORE THE WIRE. `redactFeedbackText` strips the credential/PII shapes that leak into
+ *      a pasted trace even when the author meant no harm. It runs client-side, so the redaction is
+ *      auditable in this repo rather than promised in a policy.
+ *   3. INDEPENDENTLY DISABLE-ABLE. `RETICLE_FEEDBACK=0` kills the channel while leaving anonymous
+ *      adoption metrics on — the setting an org wants when counters are fine but prose is not. Every
+ *      existing switch (`RETICLE_TELEMETRY=0`, `DO_NOT_TRACK`, `reticle telemetry disable`) still
+ *      disables it too, since it rides the same emitter.
+ */
+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 { feedbackContext } from './feedback-context.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. */
+export const REDACTED = '[redacted]';
+/**
+ * The shapes that leak. Ordered most-specific first — a URL carrying inline credentials must be
+ * caught as a URL before the bare-token rule chews the middle out of it.
+ *
+ * This is a net, not a proof. It cannot catch a secret that looks like an ordinary word, which is
+ * exactly why the tool description tells the agent not to paste app source or user data in the first
+ * place. Defense in depth: instruct first, redact second, cap third.
+ */
+const REDACTIONS = [
+    // scheme://user:pass@host — the credential is in the authority section.
+    { pattern: /\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+:[^\s/@]+@/gi, label: 'url-credentials' },
+    { pattern: /\b[\w.%+-]+@[\w.-]+\.[a-z]{2,}\b/gi, label: 'email' },
+    // Credential assignments: the KEY stays (it is the useful part), the VALUE goes. The auth SCHEME
+    // (`Bearer`, `Basic`, `Token`) is consumed as part of the value, not left as the value — matching
+    // only `\S+` after the separator ate the word "Bearer" and published the secret right behind it.
+    {
+        pattern: /\b(authorization|api[-_]?key|secret|token|password|passwd|pwd)\b(?:\s*[:=]\s*|\s+)(?:(?:bearer|basic|token|digest)\s+)?\S+/gi,
+        label: 'credential-assignment',
+    },
+    // Vendor key formats that are self-identifying (sk-…, ghp_…, AKIA…, xoxb-…, eyJ… JWTs).
+    { pattern: /\b(?:sk|pk|rk)-[A-Za-z0-9_-]{16,}\b/g, label: 'vendor-key' },
+    { pattern: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, label: 'github-token' },
+    { pattern: /\bAKIA[0-9A-Z]{16}\b/g, label: 'aws-key' },
+    { pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, label: 'slack-token' },
+    { pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, label: 'jwt' },
+    // Home directories carry the account name, and a trace is full of them.
+    { pattern: /(?:\/Users\/|\/home\/|[A-Z]:\\Users\\)[^\s/\\:"']+/g, label: 'home-path' },
+];
+/** Strip credential/PII shapes and cap the length. Pure — the tests read like a spec of what leaks. */
+export function redactFeedbackText(input, max) {
+    const removed = new Set();
+    let text = input;
+    for (const { pattern, label } of REDACTIONS) {
+        text = text.replace(pattern, (_match, ...groups) => {
+            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] : '';
+            return `${prefix}${REDACTED}`;
+        });
+    }
+    return { text: text.slice(0, max), removed: [...removed] };
+}
+/** 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';
+}
+/**
+ * The fields an author writes, and therefore the fields that must be redacted. ONE list, used both to
+ * redact and to assemble — so a new field cannot be added to one and missed by the other.
+ *
+ * `model` is deliberately included: it is agent-supplied text like the rest, and while a model name
+ * is not sensitive, exempting it would re-introduce the "which fields are safe?" judgement call that
+ * caused the original gap.
+ */
+const AUTHOR_WRITTEN_FIELDS = new Set([
+    'text',
+    'trace',
+    'need',
+    'impact',
+    'currentApproach',
+    'model',
+]);
+/** Per-field caps; anything unlisted uses the standard field cap. */
+const FIELD_CAPS = {
+    text: FEEDBACK_TEXT_MAX,
+    trace: FEEDBACK_TRACE_MAX,
+    model: 64,
+};
+/**
+ * Redact, validate, and emit one feedback report. Returns a receipt rather than throwing: a feedback
+ * send that fails must never take down the tool call that reported the failure — that would punish
+ * the exact behaviour we are trying to encourage.
+ */
+export async function submitFeedback(input, opts = {}) {
+    const env = opts.env ?? process.env;
+    const context = feedbackContext(opts.cwd ?? process.cwd(), opts.session);
+    // Redact EVERY author-written field, derived from the input rather than listed.
+    //
+    // The first version named `text` and `trace` explicitly. When `need`, `impact` and
+    // `currentApproach` were added later they silently bypassed redaction entirely — three new
+    // free-text fields going to the wire raw, and a `currentApproach` reading "hardcoding the token
+    // sk-…" would have shipped the token. Enumerating the fields to protect is the same class of
+    // mistake as hand-copying an enum: correct on the day it is written, quietly wrong at the next
+    // 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 === '')
+            continue;
+        if (!AUTHOR_WRITTEN_FIELDS.has(key))
+            continue;
+        redactions.set(key, redactFeedbackText(value, FIELD_CAPS[key] ?? FEEDBACK_FIELD_MAX));
+    }
+    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 };
+    }
+    const telemetry = getTelemetry();
+    if (!telemetry.enabled) {
+        return {
+            sent: false,
+            reason: 'telemetry is disabled on this machine, so feedback has nowhere to go',
+            redacted,
+            context,
+        };
+    }
+    const parsed = FeedbackSchema.safeParse({
+        source: input.source,
+        kind: input.kind,
+        // Every author-written field, redacted. Built from the map so nothing can be forgotten here
+        // either — the field list exists in exactly one place.
+        ...Object.fromEntries([...redactions].filter(([, r]) => r.text !== '').map(([key, r]) => [key, r.text])),
+        text: body.text,
+        ...(input.rating !== undefined ? { rating: input.rating } : {}),
+        ...context,
+    });
+    if (!parsed.success) {
+        return {
+            sent: 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 };
+}
+/**
+ * The receipt's context PLUS the fields the emitter stamps on every event regardless of kind — the
+ * reticle version, the OS, and whether this is CI. They are the single most-asked question of any bug
+ * report ("what version?"), so they are echoed here rather than left as an invisible claim: what the
+ * CLI prints is then genuinely everything that goes.
+ */
+export function describeFeedbackPayload(context) {
+    return {
+        ...context,
+        version: SERVER_VERSION,
+        os: platform(),
+        ci: process.env['CI'] !== undefined,
+    };
+}

package/dist/telemetry/git-facts.d.ts

@@ -0,0 +1,21 @@
+import { GitState, RepoForge } from '@reticlehq/core';
+export interface GitFacts {
+    /** none | local_only (init'd, never pushed) | remote (has an origin). */
+    state: GitState;
+    /** The NORMALIZED origin — hashed by the caller, never sent raw. Absent unless state is `remote`. */
+    origin?: string;
+    /** Which forge hosts it, bucketed. Absent unless state is `remote`. */
+    forge?: RepoForge;
+}
+/** `git@github.com:Acme/Web.git` / `https://u:p@github.com/Acme/Web` → `github.com/acme/web`. */
+export declare const normalizeGitOrigin: (url: string) => string;
+/** Bucket a normalized origin by its host. Unknown hosts are `self_hosted` — never the host itself. */
+export declare function forgeOf(normalizedOrigin: string): RepoForge;
+type FileReader = (path: string) => string;
+type PathExists = (path: string) => boolean;
+/**
+ * Walk up from `cwd` looking for a `.git`, and report what is there. Never throws: an unreadable or
+ * malformed config reports the state we could confirm rather than failing a startup path.
+ */
+export declare function gitFacts(cwd: string, read?: FileReader, exists?: PathExists): GitFacts;
+export {};