@reticlehq/server 2.4.0 → 2.5.0

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

@@ -1,13 +1,3 @@
-/**
- * Report that a person ran a `reticle` subcommand.
- *
- * `_daemon` is EXCLUDED, and that exclusion is the whole point of this function. `reticle mcp` and
- * `reticle serve` start the daemon by re-running this very binary, so the child re-entered the CLI
- * entry point and emitted a second event for what a person experienced as ONE action. The old
- * `invoke` metric was therefore inflated ~2x — and inflated worst on the agent-driven sessions that
- * matter most, while one-shot commands like `version` counted once. That skewed the RATIO between
- * commands, not merely the scale, which is the kind of error you cannot correct for after the fact.
- * The daemon\'s own lifecycle is already reported by `daemon_started` / `daemon_stopped`; a spawned
- * daemon is not a CLI run.
- */
+/** True when this command represents a person typing something. Exported for the gate. */
+export declare function isHumanCliCommand(command: string): boolean;
 export declare function reportCliRun(argv: readonly string[]): void;

package/dist/telemetry/cli-telemetry.js

@@ -4,8 +4,8 @@
  * Lives in its own module so `cli.ts` stays a dispatcher, and so the `_daemon` exclusion below sits
  * next to the explanation of why it exists rather than buried in a startup function.
  */
-import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
-import { DAEMON_INNER_COMMAND, knownCommand } from '../cli-parse.js';
+import { TelemetryEventKind } from '@reticlehq/core';
+import { DAEMON_INNER_COMMAND, knownCommand } from '../cli/cli-parse.js';
 import { getTelemetry } from './telemetry.js';
 import { describeCliFlags } from './argument-shape.js';
 /**
@@ -20,22 +20,45 @@ import { describeCliFlags } from './argument-shape.js';
  * The daemon\'s own lifecycle is already reported by `daemon_started` / `daemon_stopped`; a spawned
  * daemon is not a CLI run.
  */
+/**
+ * The agent's MCP transport, not a person. `reticle mcp` is what an MCP client runs to open a stdio
+ * connection — nobody types it. Measured over one real day it was 475 of 561 `cli_command_run`
+ * events (85%), on an event whose whole purpose is human intent, and the agent attaching is already
+ * reported by `mcp_client_connected` with strictly more detail (reconnect, daemon age, client).
+ *
+ * `serve` is NOT excluded: nothing spawns it on a person's behalf, so typing it is a real act.
+ */
+const AGENT_TRANSPORT_COMMAND = 'mcp';
+/** True when this command represents a person typing something. Exported for the gate. */
+export function isHumanCliCommand(command) {
+    return command !== AGENT_TRANSPORT_COMMAND && command !== DAEMON_INNER_COMMAND;
+}
 export function reportCliRun(argv) {
     const firstArg = argv[0];
     if (firstArg === DAEMON_INNER_COMMAND)
         return;
+    const command = knownCommand(firstArg);
     const telemetry = getTelemetry();
+    // FIRST — before the human-command filter. The install happened whichever command ran, and on most
+    // machines the very first contact is the agent spawning `reticle mcp`, which that filter excludes.
+    // Measured over one sweep: 15 `init_completed` and ZERO `reticle_installed`, in a run that
+    // installed the SDK into nine apps — the top of every funnel, missing.
     // `detach` so a quick command (`version`/`gate`) exits immediately instead of waiting out the POST.
     if (telemetry.firstRun)
         void telemetry.emit(TelemetryEventKind.RETICLE_INSTALLED, { detach: true });
+    if (!isHumanCliCommand(command))
+        return;
     void telemetry.emit(TelemetryEventKind.CLI_COMMAND_RUN, {
         detach: true,
-        actor: TelemetryActor.HUMAN,
+        // No `actor`: with the agent's transport excluded, this event is human BY DEFINITION. It was
+        // constant `human` on all 561 events in a real day — zero information, and wrong for the 475
+        // that were the agent. `actor` stays where it earns its place: verification_completed and
+        // bug_found, where it splits the agent's own loop from a human/CI-triggered run.
         // A fixed, low-cardinality vocabulary WE define, so it is safe to send whole and it is the closest
         // honest read we have on intent: `verify` and `gate` mean something very different from `status`.
         // An unrecognized first arg reports as `unknown` rather than being echoed — an echo would put
         // whatever someone mistyped, including a path or a URL, straight onto the wire.
-        command: knownCommand(firstArg),
+        command,
         // Which flags were PRESENT, by name only — never their values. `--http-token` alone makes that
         // rule absolute rather than case-by-case; `--drive` and `--storage-state` carry a URL and a path.
         flags: describeCliFlags(argv),

package/dist/telemetry/daemon-telemetry.d.ts

@@ -1,3 +1,22 @@
+/**
+ * How often a long-lived daemon flushes its counters.
+ *
+ * ponytail: coarse on purpose. A daemon that is SIGKILLed — OOM, a closed laptop, `kill -9` — never
+ * reaches its shutdown handler, so without this the whole session's counters die with it. Thirty
+ * minutes bounds that loss to one window while keeping the event volume near zero for the common case
+ * (most daemons stop cleanly and send exactly one summary). If the lost windows ever show up as a
+ * real gap, the upgrade is a small on-disk journal replayed at the next start, not a shorter timer.
+ */
+/**
+ * How often a running daemon rolls up its window.
+ *
+ * Exported because it is the BOUND ON WHAT IS LOST: a daemon that has served a tool never
+ * idle-exits, so nothing calls shutdown, so its last partial window dies with the process. At 30
+ * minutes against a median 28-minute session that meant the median session reported nothing at all.
+ * Only non-empty windows emit, so a shorter interval costs nothing on the 74% of daemons that never
+ * serve a tool.
+ */
+export declare const SESSION_FLUSH_MS: number;
 /** Stops the timers this installed. Called from the daemon's shutdown path. */
 export interface DaemonTelemetry {
     /**

package/dist/telemetry/daemon-telemetry.js

@@ -23,7 +23,16 @@ const PROJECT_PROFILE_DELAY_MS = 5_000;
  * (most daemons stop cleanly and send exactly one summary). If the lost windows ever show up as a
  * real gap, the upgrade is a small on-disk journal replayed at the next start, not a shorter timer.
  */
-const SESSION_FLUSH_MS = 30 * 60 * 1000;
+/**
+ * How often a running daemon rolls up its window.
+ *
+ * Exported because it is the BOUND ON WHAT IS LOST: a daemon that has served a tool never
+ * idle-exits, so nothing calls shutdown, so its last partial window dies with the process. At 30
+ * minutes against a median 28-minute session that meant the median session reported nothing at all.
+ * Only non-empty windows emit, so a shorter interval costs nothing on the 74% of daemons that never
+ * serve a tool.
+ */
+export const SESSION_FLUSH_MS = 5 * 60 * 1000;
 /**
  * Report the daemon as started, profile the project once, and keep the session counters flushing.
  * Every timer is `unref`'d so telemetry can never be the reason a daemon refuses to exit.
@@ -51,7 +60,8 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
     const flush = setInterval(() => {
         if (metrics.empty)
             return; // an idle window is not worth an event
-        void getTelemetry().emit(TelemetryEventKind.DAEMON_STOPPED, {
+        // NOT daemon_stopped: the daemon is still running. See SESSION_PROGRESS.
+        void getTelemetry().emit(TelemetryEventKind.SESSION_PROGRESS, {
             session: metrics.summarize(false),
         });
         metrics.reset();

package/dist/telemetry/dev-repo.js

@@ -21,7 +21,7 @@ export function isReticleSourceCheckout(cwd) {
         if (existsSync(pkg)) {
             try {
                 const parsed = JSON.parse(readFileSync(pkg, 'utf8'));
-                const name = typeof parsed === 'object' && parsed !== null
+                const name = 'object' === typeof parsed && parsed !== null
                     ? parsed.name
                     : undefined;
                 if (name === MONOREPO_NAME)
@@ -42,7 +42,7 @@ export function isReticleSourceCheckout(cwd) {
 /** Strip one layer of matching quotes from a .env value. */
 function unquote(value) {
     const first = value[0];
-    if ((first === '"' || first === "'") && value.endsWith(first) && value.length >= 2) {
+    if (('"' === first || "'" === first) && value.endsWith(first) && value.length >= 2) {
         return value.slice(1, -1);
     }
     return value;
@@ -67,13 +67,13 @@ export function loadDotEnv(dir, env = process.env) {
     }
     for (const raw of text.split('\n')) {
         const line = raw.trim();
-        if (line.length === 0 || line.startsWith('#'))
+        if (0 === line.length || line.startsWith('#'))
             continue;
         const eq = line.indexOf('=');
         if (eq <= 0)
             continue; // not a KEY=value pair — skip rather than fail the whole file
         const key = line.slice(0, eq).trim();
-        if (key.length === 0 || env[key] !== undefined)
+        if (0 === key.length || env[key] !== undefined)
             continue;
         env[key] = unquote(line.slice(eq + 1).trim());
     }

package/dist/telemetry/error-fingerprint.js

@@ -19,6 +19,25 @@ import { createHash } from 'node:crypto';
  * quoted value often contains the very numbers and paths the later rules would only partly catch.
  */
 const VARIABLE_PARTS = [
+    // ── Identifiers and credentials FIRST ────────────────────────────────────────────────────────
+    //
+    // The rules below this block were written to make messages GROUPABLE — blank the variable parts so
+    // the same defect hashes the same everywhere. Redaction was a side effect of that, and a side
+    // effect is not a guarantee. A telemetry audit caught `bob@acme.com` arriving verbatim in
+    // `crash_message`; probing further, API-key-shaped tokens survived intact and a JWT was only
+    // half-masked. This function also feeds `session.errors[]` on EVERY session summary, so the
+    // exposure was every session that logged an error naming a user, not a rare crash path.
+    //
+    // Order matters: these run before the generic patterns, because `\d+` and the hex rule would chew
+    // a token into pieces that no longer match a credential shape while still leaking most of it —
+    // which is exactly what happened to the JWT.
+    /[\w.+-]+@[\w-]+\.[\w.-]+/g, // email addresses
+    /\beyJ[\w-]*\.[\w-]*\.?[\w-]*/g, // JWTs (header segment is always base64 `eyJ`)
+    /\b(?:sk|pk|rk|ghp|gho|ghs|ghu|ghr|github_pat|xox[abposr]|AKIA|ASIA|glpat)[_-][A-Za-z0-9_-]{8,}/gi,
+    // Anything else long enough and dense enough to be a secret rather than a word. The catch-all for
+    // formats nobody here has seen: on a privacy boundary, unrecognised is not the same as safe.
+    /\b[A-Za-z0-9_-]{24,}\b/g,
+    // ── Then the grouping rules ──────────────────────────────────────────────────────────────────
     /"[^"]*"|'[^']*'|`[^`]*`/g, // quoted values — names, selectors, snippets
     /\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, // URLs
     /(?:\/[\w.-]+){2,}\/?/g, // POSIX-ish paths
@@ -53,7 +72,7 @@ export function reticleFrames(stack) {
         if (!/@reticlehq[/\\]|[/\\]reticle[/\\]dist[/\\]/.test(line))
             continue;
         const location = line.match(/([\w.-]+\.(?:js|mjs|cjs|ts)):(\d+)/);
-        if (location === null)
+        if (null === location)
             continue;
         // `at Object.runTool (/path/to/invoke-tool.js:88:3)` → `runTool`. The function name is half the
         // value of a frame in an RCA — "it died in act-tools.js" narrows to a file, "it died in
@@ -62,7 +81,7 @@ export function reticleFrames(stack) {
         const where = `${location[1] ?? ''}:${location[2] ?? ''}`;
         // `Object.` / `Module.` prefixes are V8 noise that make the same function look like two.
         const name = fn?.replace(/^(?:Object|Module|Function)\./, '');
-        frames.push(name === undefined || name === '' ? where : `${name}@${where}`);
+        frames.push(name === undefined || '' === name ? where : `${name}@${where}`);
     }
     return frames;
 }

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

@@ -1,4 +1,4 @@
-import { TelemetryAction } from '../cli-parse.js';
+import { TelemetryAction } from '../cli/cli-parse.js';
 /**
  * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the human half of the feedback channel.
  *

package/dist/telemetry/feedback-cli.js

@@ -1,8 +1,8 @@
 import { FeedbackKind, FeedbackSource } from '@reticlehq/core';
-import { BUG_FLAG, RATING_FLAG } from '../cli-parse.js';
+import { BUG_FLAG, RATING_FLAG } from '../cli/cli-parse.js';
 import { describeFeedbackPayload, submitFeedback } from './feedback.js';
 import { describeTelemetry, setTelemetryEnabled } from './telemetry.js';
-import { TelemetryAction } from '../cli-parse.js';
+import { TelemetryAction } from '../cli/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.
@@ -18,7 +18,7 @@ export async function handleFeedback(text, rating, bug) {
     const line = (s) => {
         process.stdout.write(`${s}\n`);
     };
-    if (text === '' && rating === undefined) {
+    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;
@@ -28,7 +28,7 @@ export async function handleFeedback(text, rating, bug) {
         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,
+        text: '' === text ? `rated ${String(rating)}/5 with no comment` : text,
         ...(rating !== undefined ? { rating } : {}),
     });
     line(`sending      ${JSON.stringify(describeFeedbackPayload(receipt.context))}`);

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

@@ -27,6 +27,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

@@ -116,6 +116,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 +168,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