@reticlehq/server 2.2.1 → 2.4.0

package/dist/telemetry/session-metrics.js

@@ -0,0 +1,329 @@
+/**
+ * The in-process session accumulator — the reason Reticle's telemetry bill does not scale with how
+ * hard people use it.
+ *
+ * The old design emitted one event per MCP tool call. That reads as harmless until you multiply it
+ * out: a single agent verification loop is 50–200 tool calls, so a thousand daily users would push
+ * millions of events a day, and PostHog bills per ingested event. Worse, it was millions of events
+ * answering a question that ONE property answers better — `{reticle_act: 40, reticle_assert: 12}`
+ * tells you the session was a real verification loop, where 52 separate rows tell you only that 52
+ * things happened, with the shape scattered across them.
+ *
+ * So counts live here, in memory, and leave as a single `daemon_stopped` event.
+ *
+ * Everything recorded is a COUNT or a fingerprint. No tool arguments, no results, no selectors, no
+ * URLs, no error messages — the accumulator has no way to hold them, which is a stronger guarantee
+ * than a rule saying it shouldn't.
+ */
+import { BrowserLaunchKind, } from '@reticlehq/core';
+import { errorSkeleton, fingerprintError } from './error-fingerprint.js';
+import { describeToolParams } from './argument-shape.js';
+import { machineSnapshot } from './machine-snapshot.js';
+/** Cap the distinct error shapes held in memory — a pathological loop must not grow unbounded. */
+const MAX_ERROR_KINDS = 40;
+/** Cap distinct MCP clients recorded; more than a handful on one daemon is already the story. */
+const MAX_CLIENTS = 8;
+/** Bounds on the parameter map. Our own schemas are already finite; these are a belt-and-braces cap. */
+const MAX_PARAM_TOOLS = 60;
+const MAX_PARAMS_PER_TOOL = 24;
+/**
+ * How many recent tool calls to remember for the crash breadcrumb.
+ *
+ * Twelve is roughly one verification loop — enough to see the APPROACH (`snapshot → act → act →
+ * assert`) rather than just the last step, which is what turns "it crashed in act-tools" into "it
+ * crashed acting on a page it had just navigated away from". Names only, so this is a dozen short
+ * strings and costs nothing to hold.
+ */
+const BREADCRUMB_LENGTH = 12;
+/**
+ * Mutable counters for one daemon lifetime. A plain class, not a store: it is process-local, it never
+ * persists, and it dies with the daemon.
+ */
+export class SessionMetrics {
+    #toolCalls = 0;
+    #toolErrors = 0;
+    #verifications = 0;
+    #toolCounts = new Map();
+    #toolParams = new Map();
+    /** Ring of the most recent tool NAMES — the agent's approach run, for a crash report. */
+    #breadcrumb = [];
+    /** The tool currently in flight, so a crash can name its trigger point. */
+    #inFlight;
+    #sdkFailures = 0;
+    #sdkFailureKinds = new Map();
+    #errorKinds = new Map();
+    #connections = new Map();
+    #toolTiming = new Map();
+    #busyMs = 0;
+    #concurrent = 0;
+    #peakConcurrent = 0;
+    #unknownToolCalls = 0;
+    #bugsFound = 0;
+    #browserMs = 0;
+    #browserCommands = 0;
+    #bugKinds = new Map();
+    /**
+     * Kinds already reported this session — the dedup key, deliberately SEPARATE from `#bugKinds`.
+     *
+     * `#bugKinds` is capped at MAX_ERROR_KINDS, and once full a genuinely new kind is never inserted,
+     * so asking it "have I seen this?" answers no forever and marks every later occurrence as first —
+     * inflating the distinct-defect count precisely where a session got interesting. This set is not
+     * capped: the kind vocabulary is a bounded enum plus oracle names, not user data.
+     */
+    #seenBugKinds = new Set();
+    #clients = new Set();
+    #startedAt;
+    #now;
+    /** Clock injected — this file must stay testable without a real one, per the repo's clock rule. */
+    constructor(now) {
+        this.#now = now;
+        this.#startedAt = now();
+    }
+    /**
+     * Record a call starting. Returns a function to call when it finishes — that closure is what makes
+     * timing correct under CONCURRENCY: several agents can be inside `runTool` at once, so a single
+     * "last start time" field would attribute one tool's duration to another. Each call carries its own.
+     */
+    startToolCall(tool, args) {
+        this.recordToolCall(tool, args);
+        this.#concurrent += 1;
+        if (this.#concurrent > this.#peakConcurrent)
+            this.#peakConcurrent = this.#concurrent;
+        let settled = false;
+        return (durationMs) => {
+            if (settled)
+                return; // a double-settle would corrupt the concurrency count
+            settled = true;
+            this.#concurrent = Math.max(0, this.#concurrent - 1);
+            this.#busyMs += durationMs;
+            const timing = this.#toolTiming.get(tool) ?? { totalMs: 0, maxMs: 0 };
+            timing.totalMs += durationMs;
+            timing.maxMs = Math.max(timing.maxMs, durationMs);
+            this.#toolTiming.set(tool, timing);
+        };
+    }
+    /**
+     * Time spent waiting on the BROWSER, across all commands.
+     *
+     * Compared against `busyMs` this answers the question a single total cannot: of the time an agent
+     * spends inside Reticle, how much is us and how much is the app under test? Without the split a
+     * 4-second `reticle_act` is unattributable — it could be our overhead or the app taking 4 seconds
+     * to settle, and those have opposite fixes. A high ratio here is a finding about their app; a low
+     * one alongside a high `busyMs` is a performance bug of ours.
+     */
+    recordBrowserLatency(ms) {
+        this.#browserMs += ms;
+        this.#browserCommands += 1;
+    }
+    /** A call for a tool that does not exist. Non-zero means our surface is confusing the agent. */
+    recordUnknownTool() {
+        this.#unknownToolCalls += 1;
+    }
+    recordToolCall(tool, args) {
+        this.#toolCalls += 1;
+        bump(this.#toolCounts, tool);
+        this.#inFlight = tool;
+        this.#breadcrumb.push(tool);
+        if (this.#breadcrumb.length > BREADCRUMB_LENGTH)
+            this.#breadcrumb.shift();
+        if (args === undefined)
+            return;
+        // Which PARAMETERS get used, per tool — names only (plus a short allowlist of our own enums).
+        // Bounded by our own schemas: a tool has a fixed handful of declared parameters, so this map
+        // cannot grow with traffic the way a value-carrying one would.
+        let perTool = this.#toolParams.get(tool);
+        if (perTool === undefined) {
+            if (this.#toolParams.size >= MAX_PARAM_TOOLS)
+                return;
+            perTool = new Map();
+            this.#toolParams.set(tool, perTool);
+        }
+        for (const param of describeToolParams(args)) {
+            if (perTool.size < MAX_PARAMS_PER_TOOL || perTool.has(param))
+                bump(perTool, param);
+        }
+    }
+    /**
+     * One failed tool call. Grouped by fingerprint, but stored WITH its skeleton message and the tool
+     * that produced it — a bare fingerprint could be ranked and never diagnosed, which made the top
+     * error in the dashboard a number nobody could act on.
+     */
+    recordToolError(message, tool) {
+        this.#toolErrors += 1;
+        const fingerprint = fingerprintError(message);
+        const existing = this.#errorKinds.get(fingerprint);
+        if (existing !== undefined) {
+            existing.count += 1;
+            return;
+        }
+        // Stop growing once the cap is hit; the tail is noise and the head is what gets fixed.
+        if (this.#errorKinds.size >= MAX_ERROR_KINDS)
+            return;
+        this.#errorKinds.set(fingerprint, {
+            fingerprint,
+            count: 1,
+            message: errorSkeleton(message),
+            ...(tool !== undefined ? { tool } : {}),
+        });
+    }
+    /**
+     * A failure reported by the IN-PAGE half of Reticle, over the bridge.
+     *
+     * Kept in its own bucket rather than mixed into tool errors: a broken observer and a failing tool
+     * call are different defects with different owners, and merging them would hide the browser-side
+     * one inside a much larger pile. Same treatment otherwise — fingerprinted, variables stripped.
+     */
+    recordSdkFailure(site, message) {
+        this.#sdkFailures += 1;
+        const fingerprint = fingerprintError(`${site}|${message}`);
+        const existing = this.#sdkFailureKinds.get(fingerprint);
+        if (existing !== undefined) {
+            existing.count += 1;
+            return;
+        }
+        if (this.#sdkFailureKinds.size >= MAX_ERROR_KINDS)
+            return;
+        this.#sdkFailureKinds.set(fingerprint, {
+            fingerprint,
+            count: 1,
+            message: errorSkeleton(message),
+            tool: site,
+        });
+    }
+    /** The agent's recent approach run + the call in flight — context for a crash report. */
+    get trail() {
+        return { breadcrumb: [...this.#breadcrumb], inFlight: this.#inFlight };
+    }
+    recordVerification() {
+        this.#verifications += 1;
+    }
+    /**
+     * One defect found in the app under test — the outcome number, kept broken down by kind.
+     *
+     * Returns TRUE when this kind is new to the session. Every occurrence is still counted; the flag
+     * only lets a reader separate "how many distinct defects" from "how often they were hit", which
+     * are different claims and were previously indistinguishable in the data.
+     */
+    recordBug(kind) {
+        this.#bugsFound += 1;
+        if (this.#bugKinds.size < MAX_ERROR_KINDS || this.#bugKinds.has(kind))
+            bump(this.#bugKinds, kind);
+        const first = !this.#seenBugKinds.has(kind);
+        this.#seenBugKinds.add(kind);
+        return first;
+    }
+    /**
+     * One connection ATTEMPT. Call before the attempt; settle it with the outcome.
+     *
+     * The previous version counted only successes, and counted them inconsistently — incrementing
+     * before the await on the CDP path and after it on the launch path — so one number meant attempts,
+     * the others meant successes, and nothing in the data said which. A connection metric that cannot
+     * express failure misses the only question worth asking: how often can people not get a browser?
+     */
+    recordConnectAttempt(kind) {
+        const stats = this.#connections.get(kind) ?? { attempts: 0, successes: 0 };
+        stats.attempts += 1;
+        this.#connections.set(kind, stats);
+        let settled = false;
+        return (failure) => {
+            if (settled)
+                return;
+            settled = true;
+            if (failure === undefined) {
+                stats.successes += 1;
+                return;
+            }
+            stats.failures ??= {};
+            stats.failures[failure] = (stats.failures[failure] ?? 0) + 1;
+        };
+    }
+    recordClient(name) {
+        if (this.#clients.size < MAX_CLIENTS)
+            this.#clients.add(name.slice(0, 64));
+    }
+    /**
+     * 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) {
+        const machine = machineSnapshot();
+        return {
+            durationMs: Math.max(0, this.#now() - this.#startedAt),
+            toolCalls: this.#toolCalls,
+            toolCounts: Object.fromEntries(this.#toolCounts),
+            toolErrors: this.#toolErrors,
+            ...(this.#errorKinds.size > 0 ? { errors: [...this.#errorKinds.values()] } : {}),
+            sdkFailures: this.#sdkFailures,
+            ...(this.#sdkFailureKinds.size > 0 ? { sdkErrors: [...this.#sdkFailureKinds.values()] } : {}),
+            verifications: this.#verifications,
+            bugsFound: this.#bugsFound,
+            ...(this.#bugKinds.size > 0 ? { bugKinds: Object.fromEntries(this.#bugKinds) } : {}),
+            ...(this.#toolParams.size > 0
+                ? {
+                    toolParams: Object.fromEntries([...this.#toolParams].map(([tool, params]) => [tool, Object.fromEntries(params)])),
+                }
+                : {}),
+            ...(this.#connections.size > 0 ? { connections: Object.fromEntries(this.#connections) } : {}),
+            ...(this.#toolTiming.size > 0 ? { toolTiming: Object.fromEntries(this.#toolTiming) } : {}),
+            busyMs: this.#busyMs,
+            browserMs: this.#browserMs,
+            browserCommands: this.#browserCommands,
+            peakConcurrentTools: this.#peakConcurrent,
+            unknownToolCalls: this.#unknownToolCalls,
+            ...(machine !== undefined ? { machine } : {}),
+            ...(this.#clients.size > 0 ? { clients: [...this.#clients] } : {}),
+            final,
+        };
+    }
+    /** True when nothing at all happened — a flush of an idle daemon is not worth an event. */
+    get empty() {
+        return (this.#toolCalls === 0 &&
+            this.#verifications === 0 &&
+            this.#toolErrors === 0 &&
+            this.#bugsFound === 0 &&
+            this.#sdkFailures === 0);
+    }
+    /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */
+    reset() {
+        this.#toolCalls = 0;
+        this.#toolErrors = 0;
+        this.#verifications = 0;
+        this.#toolCounts.clear();
+        this.#toolParams.clear();
+        this.#errorKinds.clear();
+        this.#sdkFailures = 0;
+        this.#sdkFailureKinds.clear();
+        this.#connections.clear();
+        this.#toolTiming.clear();
+        this.#busyMs = 0;
+        this.#browserMs = 0;
+        this.#browserCommands = 0;
+        this.#peakConcurrent = 0;
+        this.#unknownToolCalls = 0;
+        this.#bugsFound = 0;
+        this.#bugKinds.clear();
+        this.#seenBugKinds.clear();
+    }
+}
+function bump(map, key) {
+    map.set(key, (map.get(key) ?? 0) + 1);
+}
+/**
+ * The process-wide accumulator. A module singleton because the two call sites that feed it — the tool
+ * chokepoint and the MCP error boundary — are far apart in the graph and threading a metrics object
+ * through every ToolDeps would be a large, purely mechanical change for no added safety.
+ */
+let current;
+export const getSessionMetrics = (now = () => Date.now()) => (current ??= new SessionMetrics(now));
+/** Record one browser round-trip. Free-function form so the session hot path is a single call. */
+export const recordBrowserLatency = (ms) => {
+    getSessionMetrics().recordBrowserLatency(ms);
+};
+/** Narrow-and-record one in-page failure. Keeps the session hot path to a single call. */
+export const recordSdkFailure = (failure) => {
+    getSessionMetrics().recordSdkFailure(failure.site, failure.message);
+};
+/** Tests only — drop the singleton so each case starts from zero. */
+export const resetSessionMetrics = () => {
+    current = undefined;
+};

package/dist/telemetry/telemetry.d.ts

@@ -1,23 +1,51 @@
-import { TelemetryEventKind } from '@reticlehq/core';
+import { TelemetryEventKind, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type McpConnection, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
 /** The current telemetry state and which control set it — what `reticle telemetry status` prints. */
-export declare const describeTelemetry: (env?: NodeJS.ProcessEnv, dir?: string) => {
+export declare const describeTelemetry: (env?: NodeJS.ProcessEnv, dir?: string, cwd?: string) => {
     enabled: boolean;
     reason: string;
     policyUrl: string;
 };
 /** Persist (or lift) the machine-wide opt-out — `reticle telemetry disable` / `enable`. */
 export declare const setTelemetryEnabled: (enabled: boolean, dir?: string) => void;
+/**
+ * The per-event extras — one optional block per event kind, so a payload can only ever be attached
+ * to the event it belongs to. `feedback` is the only one carrying author-written text, and it only
+ * ever arrives from `submitFeedback`, which redacts and validates it first. Nothing else may set it.
+ */
+export interface TelemetryExtra {
+    detach?: boolean;
+    actor?: TelemetryActor;
+    /** `cli_command_run`: which subcommand a human ran. */
+    command?: string;
+    /** `cli_command_run`: flag NAMES present on the invocation. Never values. */
+    flags?: string[];
+    /** `daemon_stopped`: the whole session rolled up. Replaces the old per-tool-call event. */
+    session?: SessionSummary;
+    /** `project_profiled`: the project's shape and depth-of-use. */
+    project?: ProjectProfile;
+    /** `verification_completed`: one verdict. */
+    verification?: Verification;
+    /** `version_changed`: update or rollback. */
+    versionChange?: VersionChange;
+    /** `runtime_crashed`: a fingerprinted crash. */
+    crash?: Crash;
+    feedback?: Feedback;
+    /** `identified`: a self-declared identity. Opt-in, typed by a human, never inferred. */
+    identity?: Identity;
+    /** `mcp_client_connected`: a client attached, and whether it had attached before. */
+    connection?: McpConnection;
+    /** `init_completed`: how `reticle init` went. */
+    init?: InitOutcome;
+    /** `bug_found`: one defect Reticle found in the app under test. */
+    bug?: BugFound;
+}
 export interface Telemetry {
     /**
      * Fire one event, non-blocking. `detach: true` hands the send to a disowned child so a short-lived
      * CLI process can exit immediately instead of waiting out the POST (use it from command entry
      * points; daemon-side events send in-process).
      */
-    emit(kind: TelemetryEventKind, extra?: {
-        sessionMs?: number;
-        tool?: string;
-        detach?: boolean;
-    }): Promise<void>;
+    emit(kind: TelemetryEventKind, extra?: TelemetryExtra): Promise<void>;
     readonly enabled: boolean;
     /** True the very first run on this machine — the CLI emits INSTALL alongside the first INVOKE. */
     readonly firstRun: boolean;
@@ -38,4 +66,3 @@ export declare const createTelemetry: (opts: {
 }) => Telemetry;
 export declare const getTelemetry: () => Telemetry;
 export { TelemetryEventKind };
-//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry/telemetry.js

@@ -19,7 +19,7 @@ import { randomUUID, createHash } from 'node:crypto';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
-import { TelemetryEventKind, TELEMETRY_EVENT_VERSION } from '@reticlehq/core';
+import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, } from '@reticlehq/core';
 import { SERVER_VERSION } from '../server-version.js';
 const RETICLE_DIR = join(homedir(), '.reticle');
 const ID_FILE = join(RETICLE_DIR, 'telemetry-id');
@@ -53,6 +53,8 @@ const DETACHED_SEND_SCRIPT = "fetch(process.argv[1],{method:'POST',headers:{'con
     `body:process.argv[2],signal:AbortSignal.timeout(${SEND_TIMEOUT_MS})})` +
     '.catch(()=>{}).finally(()=>process.exit(0))';
 /** Env var names — mirror cloud-sync's `RETICLE_*` convention. */
+import { isReticleSourceCheckout } from './dev-repo.js';
+import { gitFacts } from './git-facts.js';
 const Env = {
     DISABLE: 'RETICLE_TELEMETRY', // "0" / "false" / "off" → disabled
     DO_NOT_TRACK: 'DO_NOT_TRACK', // the cross-tool opt-out convention (any truthy value)
@@ -61,12 +63,17 @@ const Env = {
     CI: 'CI', // presence marks a CI environment
     VITEST: 'VITEST', // set by vitest — unit tests must never phone home
 };
-const isDisabled = (env) => {
+const isDisabled = (env, cwd = process.cwd()) => {
     const off = new Set(['0', 'false', 'off', 'no']);
     if (off.has((env[Env.DISABLE] ?? '').toLowerCase()))
         return true;
     if (env[Env.VITEST] !== undefined)
         return true; // a test run is not a user
+    // Developing Reticle is not using Reticle. The `.env` carrying RETICLE_TELEMETRY=0 is gitignored,
+    // so it only exists on the machine that made it — a fresh clone would phone home on a
+    // contributor's first `reticle serve`. The repo marker is committed, so this guarantee travels.
+    if (isReticleSourceCheckout(cwd))
+        return true;
     const dnt = env[Env.DO_NOT_TRACK];
     return typeof dnt === 'string' && dnt !== '' && dnt !== '0';
 };
@@ -88,8 +95,31 @@ const resolveIdentity = () => {
         return { anonymousId: randomUUID(), firstRun: false };
     }
 };
-/** One-way project fingerprint: distinct-count of this = "projects Reticle is used in", reveals nothing. */
-const projectFingerprint = (cwd) => createHash('sha256').update(cwd).digest('hex').slice(0, 32);
+/**
+ * One-way project fingerprint: distinct-count of this = "projects Reticle is used in", reveals nothing.
+ *
+ * Prefers a hash of the git ORIGIN over a hash of the cwd. The contract in `@reticlehq/core` always
+ * said "one-way hash of the git remote (or cwd)", but the implementation only ever hashed the path —
+ * which meant the same repo cloned by four teammates, or checked out twice on one machine, counted as
+ * four separate projects. That inflates the project count and, worse, makes team adoption look like
+ * unrelated individuals. Hashing the origin dedupes a real project down to one id across every clone.
+ *
+ * Still one-way, still non-reversible, and still exactly what the published policy describes: the
+ * remote URL itself never leaves the machine, only its SHA-256. The URL is normalized first (scheme,
+ * credentials, `.git` suffix and case removed) so `git@github.com:acme/web.git` and
+ * `https://github.com/Acme/web` are recognized as the same project rather than two.
+ */
+const projectFingerprint = (cwd) => {
+    const { origin } = gitFacts(cwd);
+    return {
+        projectId: createHash('sha256')
+            .update(origin ?? cwd)
+            .digest('hex')
+            .slice(0, 32),
+        // Reported alongside so the analytics knows whether this id is comparable to another machine's.
+        source: origin !== undefined ? ProjectIdSource.GIT_ORIGIN : ProjectIdSource.CWD,
+    };
+};
 /** Print the opt-out notice exactly once per machine (honest disclosure, the OSS-trust bar). */
 const showNoticeOnce = () => {
     try {
@@ -106,8 +136,17 @@ const showNoticeOnce = () => {
     }
 };
 /** The current telemetry state and which control set it — what `reticle telemetry status` prints. */
-export const describeTelemetry = (env = process.env, dir = RETICLE_DIR) => {
-    if (isDisabled(env)) {
+export const describeTelemetry = (env = process.env, dir = RETICLE_DIR, cwd = process.cwd()) => {
+    // Report the reason that ACTUALLY applies. Saying "environment variable" when the real cause is
+    // the source-checkout guard would send a contributor hunting for a variable that is not set.
+    if (isReticleSourceCheckout(cwd)) {
+        return {
+            enabled: false,
+            reason: 'this is a Reticle source checkout — developing it is not using it',
+            policyUrl: POLICY_URL,
+        };
+    }
+    if (isDisabled(env, cwd)) {
         return { enabled: false, reason: 'disabled by environment variable', policyUrl: POLICY_URL };
     }
     if (existsSync(join(dir, 'telemetry-opt-out'))) {
@@ -142,7 +181,8 @@ const NOOP = { emit: async () => { }, enabled: false, firstRun: false };
  */
 export const createTelemetry = (opts) => {
     const env = opts.env ?? process.env;
-    if (isDisabled(env))
+    const cwd = opts.cwd ?? process.cwd();
+    if (isDisabled(env, cwd))
         return NOOP;
     try {
         if (existsSync(OPT_OUT_FILE))
@@ -160,7 +200,13 @@ export const createTelemetry = (opts) => {
     const ci = env[Env.CI] !== undefined && env[Env.CI] !== '';
     const os = platform();
     const { anonymousId, firstRun } = resolveIdentity();
-    const projectId = projectFingerprint(opts.cwd ?? process.cwd());
+    /**
+     * One id per PROCESS, minted in memory and never persisted — which is exactly right: a daemon run
+     * IS the session, and a restarted daemon is genuinely a new one. Ephemeral by construction, so it
+     * adds no durable identifier to the machine.
+     */
+    const sessionId = randomUUID();
+    const { projectId, source: projectIdSource } = projectFingerprint(opts.cwd ?? process.cwd());
     showNoticeOnce();
     const spawnDetached = opts.spawnImpl ??
         ((command, args) => {
@@ -170,17 +216,65 @@ export const createTelemetry = (opts) => {
         const event = {
             v: TELEMETRY_EVENT_VERSION,
             anonymousId,
+            sessionId,
             projectId,
             event: kind,
             ts: now(),
             version: opts.version,
             ci,
             os,
-            ...(extra?.sessionMs !== undefined ? { sessionMs: extra.sessionMs } : {}),
-            ...(extra?.tool !== undefined ? { tool: extra.tool } : {}),
+            projectIdSource,
+            ...(extra?.actor !== undefined ? { actor: extra.actor } : {}),
+            ...(extra?.command !== undefined ? { command: extra.command } : {}),
+            ...(extra?.flags !== undefined ? { flags: extra.flags } : {}),
+            ...(extra?.session !== undefined ? { session: extra.session } : {}),
+            ...(extra?.project !== undefined ? { project: extra.project } : {}),
+            ...(extra?.verification !== undefined ? { verification: extra.verification } : {}),
+            ...(extra?.versionChange !== undefined ? { versionChange: extra.versionChange } : {}),
+            ...(extra?.crash !== undefined ? { crash: extra.crash } : {}),
+            ...(extra?.feedback !== undefined ? { feedback: extra.feedback } : {}),
+            ...(extra?.identity !== undefined ? { identity: extra.identity } : {}),
+            ...(extra?.connection !== undefined ? { connection: extra.connection } : {}),
+            ...(extra?.init !== undefined ? { init: extra.init } : {}),
+            ...(extra?.bug !== undefined ? { bug: extra.bug } : {}),
         };
         // Map the core contract onto PostHog's capture shape: id/name/time move up, the rest are properties.
-        const { anonymousId: distinctId, event: name, ts, ...properties } = event;
+        // The feedback body is FLATTENED into `feedback_*` properties rather than sent as a nested object:
+        // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
+        // would be invisible to the exact "which stacks report the most bugs" question this exists to
+        // answer. One prefix keeps them grouped in the UI without a nested path.
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, ...rest } = event;
+        // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
+        // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
+        const properties = {
+            ...rest,
+            sessionId: eventSessionId,
+            $session_id: eventSessionId,
+        };
+        // Each block is flattened under its own prefix rather than nested. PostHog filters, breakdowns and
+        // insight builders all operate on TOP-LEVEL properties, so a nested `project.stack` is invisible to
+        // the exact "which stacks retain best" question these exist to answer — you would have to drop to
+        // raw HogQL for every chart. One prefix per block keeps them grouped in the property list without
+        // paying that cost. The two genuine maps (`toolCounts`, `errorKinds`) stay objects: their keys are
+        // open-ended, so flattening them would mint an unbounded number of property names, which is the one
+        // thing that actually degrades a PostHog project.
+        const blocks = {
+            feedback,
+            session,
+            project,
+            verification,
+            version: versionChange,
+            crash,
+            identity,
+            connection,
+            init,
+            bug,
+        };
+        for (const [prefix, block] of Object.entries(blocks)) {
+            for (const [key, value] of Object.entries(block ?? {})) {
+                properties[`${prefix}_${key}`] = value;
+            }
+        }
         const body = JSON.stringify({
             api_key: apiKey,
             batch: [
@@ -217,4 +311,3 @@ export const createTelemetry = (opts) => {
 let singleton;
 export const getTelemetry = () => (singleton ??= createTelemetry({ version: SERVER_VERSION }));
 export { TelemetryEventKind };
-//# sourceMappingURL=telemetry.js.map

package/dist/token-auth.d.ts

@@ -21,4 +21,3 @@ export declare function isLoopbackHost(hostHeader: string | undefined): boolean;
  * non-loopback value fails, which is what kills a rebound `http://evil.com` page reading the plane.
  */
 export declare function isLocalWebOrigin(origin: string | undefined, referer: string | undefined): boolean;
-//# sourceMappingURL=token-auth.d.ts.map

package/dist/token-auth.js

@@ -68,4 +68,3 @@ export function isLocalWebOrigin(origin, referer) {
     }
     return true;
 }
-//# sourceMappingURL=token-auth.js.map

package/dist/tools/act-capsule.d.ts

@@ -0,0 +1,23 @@
+import type { ExpectedLink } from '../capsule/divergence.js';
+import type { DivergenceCapsule } from '../capsule/capsule.js';
+import type { ToolDeps } from './tool-kit.js';
+interface CapsuleSaveInputs {
+    deps: ToolDeps;
+    verdict: {
+        pass: boolean;
+        failureReason?: string;
+    };
+    capsule?: DivergenceCapsule | undefined;
+    links: readonly ExpectedLink[];
+    args: Record<string, unknown>;
+    actResult: {
+        result?: unknown;
+    };
+    actedSource?: {
+        file: string;
+        line: number;
+    };
+}
+/** Returns the capsule id when one was written, or undefined when there was nothing to save. */
+export declare function saveFailedAssertCapsule(inputs: CapsuleSaveInputs): Promise<string | undefined>;
+export {};

package/dist/tools/act-capsule.js

@@ -0,0 +1,47 @@
+/**
+ * Persist a failed assertion as a replayable fail-to-pass capsule.
+ *
+ * : a red assertion is the ONE moment the evidence explaining it is in hand. Persist it as a
+        // replayable fail-to-pass capsule so the bug survives the turn — and becomes a regression flow
+        // the moment it goes green. Best-effort: capturing evidence must never fail the run that found it.
+ *
+ * Split out of act-tools.ts when it crossed the 600-line cap. The seam is real: this is the only
+ * part of the act path that writes to disk, and it is best-effort by design — capturing evidence
+ * must never fail the run that found it.
+ */
+import { ActionType, AnchorKind } from '@reticlehq/core';
+import { CapsuleStore, capsuleId } from '../capsule/capsule-store.js';
+import { ReticleTool } from './tool-names.js';
+import { asRecord, asString } from './tools-helpers.js';
+/** Returns the capsule id when one was written, or undefined when there was nothing to save. */
+export async function saveFailedAssertCapsule(inputs) {
+    const { deps, verdict, capsule, links, args, actResult, actedSource } = inputs;
+    if (verdict.pass || capsule === undefined)
+        return undefined;
+    const id = capsuleId(deps.now(), asString(args['ref']) ?? 'assert');
+    const expectedText = links
+        .map((l) => ('name' in l ? `${l.kind} ${String(l.name)}` : l.kind))
+        .join(' AND ');
+    const saved = await new CapsuleStore(deps.fs, deps.reticleRoot).save({
+        version: 1,
+        id,
+        createdAt: deps.now(),
+        origin: 'failed-assert',
+        expected: expectedText.length > 0 ? expectedText : 'declared consequence',
+        observed: capsule.firstDivergence?.observed ?? verdict.failureReason ?? 'not observed',
+        steps: [
+            {
+                tool: ReticleTool.ACT,
+                anchor: {
+                    kind: AnchorKind.TESTID,
+                    value: asString(asRecord(actResult.result)['testid']) ?? asString(args['ref']) ?? '',
+                    // Carried so the saved capsule — which outlives this turn and becomes a regression flow
+                    // when it goes green — still knows which file the failure came from.
+                    ...(actedSource === undefined ? {} : { source: actedSource }),
+                },
+                action: (asString(args['action']) ?? ActionType.CLICK),
+            },
+        ],
+    });
+    return saved ? id : undefined;
+}

package/dist/tools/act-danger.d.ts

@@ -0,0 +1,7 @@
+import { ActionType } from '@reticlehq/core';
+export declare function assertNotDestructive(action: ActionType, innerArgs: Record<string, unknown>, inspected: unknown): void;
+/**
+ * A drag is judged on BOTH ends. Dropping a harmless row onto "Delete" is destructive, and the
+ * source alone never says so.
+ */
+export declare function assertDragNotDestructive(innerArgs: Record<string, unknown>, from: unknown, to: unknown): void;