@reticlehq/server 2.7.0 → 2.9.0

package/dist/session/session.js

@@ -1,7 +1,10 @@
+import { recordImpact } from '../impact/impact-recorder.js';
 import { LastAct } from './last-act.js';
 import { commandTimeoutMessage } from './command-timeout.js';
 import { readHealthEvent } from './session-health.js';
-import { PendingCommands } from './pending-commands.js';
+/** The HUD does not need 200 frames to watch a counter climb; the last state always lands. */
+const IMPACT_PUSH_DEBOUNCE_MS = 700;
+import { PendingCommands, CommandTimeoutError } from './pending-commands.js';
 import { span } from '../trace.js';
 import { AppRuntime, EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
 import { RingBuffer } from '../events/ring-buffer.js';
@@ -18,6 +21,33 @@ import { buildSessionInfo } from './session-info.js';
 const DEFAULT_COMMAND_TIMEOUT_MS = 8000;
 /** Prefix on correlated command ids (c1, c2, …) — distinguishes them from mark ids. */
 const COMMAND_ID_PREFIX = 'c';
+/**
+ * Commands that may be re-issued against the connection that replaced this session.
+ *
+ * Reads only, and the boundary is the point. Re-reading a page costs nothing and answers the same
+ * question the caller asked. An act cannot be replayed: it may already have been dispatched in the
+ * page that went away, and performing it a second time behind the caller's back is a double submit
+ * nobody asked for. A replaced act still errors, and the caller's own retry — with the same id,
+ * which is still the right one — is the safe path.
+ */
+/**
+ * How far to walk a chain of replacements before giving up.
+ *
+ * Generous for the real case (a page reloading a handful of times while a call is in flight) and
+ * small enough that a cycle costs nothing. The number is a backstop, not a policy: a chain longer
+ * than this means something is re-dialling in a loop, and that is a different problem.
+ */
+const MAX_SUCCESSOR_HOPS = 32;
+const REBINDABLE_COMMANDS = new Set([
+    ReticleCommand.SNAPSHOT,
+    ReticleCommand.QUERY,
+    ReticleCommand.MATCH,
+    ReticleCommand.INSPECT,
+    ReticleCommand.STATE_READ,
+    ReticleCommand.STORAGE_READ,
+    ReticleCommand.CAPABILITIES,
+    ReticleCommand.ANIMATIONS,
+]);
 /** Prefix on minted action ids (a1, a2, …) — the journal's action identity, independent of commands. */
 const ACTION_ID_PREFIX = 'a';
 /** ws readyState for an OPEN socket — guard fire-and-forget pushes against a closing tab. */
@@ -192,8 +222,12 @@ export class Session {
         if (event.type === EventType.HUMAN_MARK) {
             // A human pinned a mistake to an element. Narrow at the boundary; an invalid mark is ignored.
             const parsed = HumanMarkDataSchema.safeParse(event.data);
-            if (parsed.success)
+            if (parsed.success) {
                 this.#review.add(parsed.data, this.elapsed());
+                // The impact record's `marks` field existed and nothing ever wrote it: the report would
+                // have shown a permanent zero next to a page covered in pins.
+                recordImpact({ marks: 1 });
+            }
         }
         if (event.type === EventType.ROUTE_CHANGE) {
             // Keep the reported URL live across SPA navigation. The SDK already emits route.change on
@@ -215,8 +249,18 @@ export class Session {
             : seen;
         this.#observed.observe(attributed);
         this.#buffer.push(attributed, t, byteSize);
-        for (const listener of this.#listeners)
-            listener(attributed);
+        // Each subscriber is independent, and this runs inside the websocket's `message` handler — a
+        // NON-async callback, so a sync throw here escapes every try/catch the tool call is wrapped in
+        // and becomes an uncaughtException, which the daemon answers by exiting. One observer's bug must
+        // not cost the fleet its daemon. Same rule the session-ready fan-out already follows.
+        for (const listener of this.#listeners) {
+            try {
+                listener(attributed);
+            }
+            catch {
+                /* an event observer must never break the session it observes */
+            }
+        }
     }
     // Passthroughs to ObservedState, which owns the per-session facts that must SURVIVE buffer
     // eviction: refs the agent drove, and what the layer could not see. See observed-state.ts.
@@ -397,6 +441,12 @@ export class Session {
             if ('string' === typeof ref)
                 this.recordActedRef(ref);
         }
+        // The page already re-dialled under this same id. Nothing has been sent yet, so handing the
+        // command to the live connection cannot perform anything twice — it is the call the agent would
+        // have made itself after a `reticle_sessions` round trip, minus the round trip.
+        const successor = this.#liveSuccessor();
+        if (successor !== undefined)
+            return successor.command(name, args, timeoutMs);
         const id = this.#pending.nextId(COMMAND_ID_PREFIX);
         const payload = JSON.stringify({
             kind: MessageKind.COMMAND,
@@ -425,7 +475,27 @@ export class Session {
                 this.recordActedLabelFrom(result);
             return result;
         })
-            .finally(() => recordBrowserLatency(Date.now() - sentAt));
+            .finally(() => recordBrowserLatency(Date.now() - sentAt))
+            .catch((error) => {
+            // The replacement landed while this command was on the wire, which is the reported case:
+            // `reticle_navigate` reloads the page, the reload sends a fresh HELLO carrying the same id,
+            // and the `reticle_snapshot` already in flight is rejected by the displaced session.
+            // A TIMEOUT is not a replacement. The catch fired on any rejection, so a command that had
+            // simply not been answered in budget was read as "you were replaced, ask again" — and
+            // against a page re-dialling in a loop that turned one read into hundreds of commands on the
+            // wire, minutes of wall clock, and an answer still quoting the budget it had blown.
+            const next = error instanceof CommandTimeoutError ? undefined : this.#liveSuccessor();
+            if (next === undefined || !REBINDABLE_COMMANDS.has(name))
+                throw error;
+            // What is LEFT of the caller's budget, not a fresh copy of it. Re-issuing with the original
+            // timeout means a caller who granted 8s can wait 16, and across a chain of replacements the
+            // total is unbounded — a wait nobody asked for, on the path that exists to save a round trip.
+            // A budget already spent means there is nothing left to retry into, so the error stands.
+            const remaining = timeoutMs - (Date.now() - sentAt);
+            if (remaining <= 0)
+                throw error;
+            return next.command(name, args, remaining);
+        });
     }
     handleResult(result) {
         this.#pending.settle(result);
@@ -437,8 +507,52 @@ export class Session {
             listener();
         this.#disconnectListeners.clear();
     }
+    /**
+     * The connection that took this session's id over, once one has.
+     *
+     * Set by the bridge at the moment it displaces this session, so the two facts a replaced handle
+     * needs — that it was replaced, and by whom — arrive together. Without it, every tool call holding
+     * this handle could only report "session replaced by a newer connection claiming the same id", and
+     * the caller's only recovery was `reticle_sessions` plus a retry: two round trips to rediscover an
+     * id the daemon was already holding, and which had not even changed.
+     */
+    #successor;
+    succeededBy(next) {
+        // A session is never its own replacement; guarding here keeps `command` from recursing forever
+        // if a registry ever re-adds the same object.
+        if (next !== this)
+            this.#successor = next;
+    }
+    /**
+     * The replacement, but only while it can actually answer.
+     *
+     * A successor is recorded once and never cleared, so without this a session that was replaced an
+     * hour ago keeps handing commands to a socket that has since closed — and the caller pays the full
+     * timeout to learn it, turning an instant "session replaced" into a wait. The point of delegating
+     * was to save the caller a round trip; delegating to a dead socket costs them more than the error
+     * did.
+     */
+    #liveSuccessor() {
+        // Walked, not just read one hop. Two replacements in quick succession — a page that reloads
+        // twice — leave a CHAIN, and the handle the caller holds points at a session that is itself
+        // already displaced. Stopping at the first dead link fails safe and also fails: the open page is
+        // one hop further on, and the caller gets back exactly the error this exists to remove.
+        //
+        // Bounded, because `succeededBy` refuses self-succession but nothing prevents a cycle, and an
+        // unbounded walk over one is a hang — which is worse than the error it was trying to avoid.
+        let next = this.#successor;
+        for (let hops = 0; next !== undefined && hops < MAX_SUCCESSOR_HOPS; hops += 1) {
+            if (next.#socket.readyState === WS_OPEN)
+                return next;
+            next = next.#successor;
+        }
+        return undefined;
+    }
     /** End this transport without letting a stale socket remove its replacement session. */
     disconnect(reason) {
+        // "Longest run" means the longest SESSION, and it used to be fed a single tool call's duration
+        // - so the report's superlative was a number in milliseconds that never grew past a click.
+        recordImpact({}, { runMs: this.elapsed() });
         this.rejectAll(reason);
         try {
             this.#socket.close(1008, reason);
@@ -515,10 +629,37 @@ export class Session {
      * Push a lifecycle state to the panel with optional human-facing `text`. State changes still flow
      * through `setState`; an auto-ended session rides a `warn` tone so the panel can shout "agent stopped".
      */
+    /**
+     * Push the impact record to this tab's HUD.
+     *
+     * Debounced: the record changes on every tool call, and the panel does not need 200 frames to
+     * show a counter going up. The LAST state always lands, because the timer re-reads the store
+     * when it fires rather than capturing a snapshot when it was scheduled.
+     */
+    pushImpact(read, immediate = false) {
+        if (immediate) {
+            // A tab that just connected has nothing to show yet, so its first record goes out at once -
+            // waiting a debounce here is a report that reads "nothing recorded" over a month of history.
+            const first = read();
+            if (first !== undefined)
+                this.#post(ReticleCommand.IMPACT, { snapshot: first });
+            return;
+        }
+        if (this.#impactTimer !== undefined)
+            return;
+        this.#impactTimer = setTimeout(() => {
+            this.#impactTimer = undefined;
+            const snapshot = read();
+            if (snapshot !== undefined)
+                this.#post(ReticleCommand.IMPACT, { snapshot });
+        }, IMPACT_PUSH_DEBOUNCE_MS);
+        this.#impactTimer.unref?.();
+    }
     pushPresenter(state, text, tone) {
         this.#post(ReticleCommand.PRESENTER, buildPresenterArgs(state, text, tone));
     }
     /** Fire-and-forget a narration row to the live panel (so a resolved mark shows "✓ fixed"). */
+    #impactTimer;
     pushNarration(text) {
         this.#post(ReticleCommand.NARRATE, { text, level: 'info' });
     }

package/dist/telemetry/app-instrumented.d.ts

@@ -33,5 +33,13 @@ export interface InstrumentationFacts {
  * never be the reason a session fails to register.
  */
 export declare function reportAppInstrumented(facts: InstrumentationFacts, now?: () => number): void;
+/**
+ * Has an app connected to this daemon run at all?
+ *
+ * The same flag `reportAppInstrumented` uses for idempotency, read from outside. The stall check
+ * needs exactly this question and must not answer it from a window counter, which resets on every
+ * flush and would then report a long-instrumented daemon as freshly stalled.
+ */
+export declare function appEverConnected(): boolean;
 /** Tests only. */
 export declare function resetAppInstrumented(): void;

package/dist/telemetry/app-instrumented.js

@@ -47,6 +47,16 @@ export function reportAppInstrumented(facts, now = () => Date.now()) {
         /* never let a metric interfere with a page connecting */
     }
 }
+/**
+ * Has an app connected to this daemon run at all?
+ *
+ * The same flag `reportAppInstrumented` uses for idempotency, read from outside. The stall check
+ * needs exactly this question and must not answer it from a window counter, which resets on every
+ * flush and would then report a long-instrumented daemon as freshly stalled.
+ */
+export function appEverConnected() {
+    return reported;
+}
 /** Tests only. */
 export function resetAppInstrumented() {
     reported = false;

package/dist/telemetry/automation-hint.d.ts

@@ -0,0 +1,17 @@
+import { AutomationHint } from '@reticlehq/core';
+export interface AutomationInput {
+    env: NodeJS.ProcessEnv;
+    fileExists: (path: string) => boolean;
+    hasTty: boolean;
+}
+/**
+ * The most specific signal that fires, or undefined.
+ *
+ * Ordered most specific first: a container inside a Codespace with no terminal is one fact about the
+ * run, and sending the weakest of the three would waste the field. Omitted rather than sent as a
+ * "none" value, so its presence is itself the signal — the convention every other advisory field
+ * here follows.
+ */
+export declare function resolveAutomationHint(input: AutomationInput): AutomationHint | undefined;
+/** The real reading, taken once per process. */
+export declare function currentAutomationHint(env: NodeJS.ProcessEnv): AutomationHint | undefined;

package/dist/telemetry/automation-hint.js

@@ -0,0 +1,71 @@
+/**
+ * An ADVISORY marker that a run looks automated, for the runs `ci` cannot see.
+ *
+ * `ci` is a single environment variable, which is exactly right for a GitHub Actions runner and
+ * blind to everything else: our own gate has run from a datacenter and landed in the user data
+ * indistinguishable from somebody at a laptop.
+ *
+ * ADVISORY, and never a filter. A real person works inside a container, inside a Codespace, and over
+ * an ssh session with no terminal attached, and every one of them is a user. Nothing may drop a row
+ * because this is set; it exists so a surprising number can be looked at from a second angle, and a
+ * hint that starts being used as an exclusion has stopped being a hint. Absent means "nothing here
+ * looked automated", never "a human was present".
+ *
+ * WHAT WAS REJECTED, so nobody re-proposes it:
+ *  - IP address, ASN or datacenter geolocation. Not knowable client-side, and it is a stronger
+ *    identifier than anything else we collect. The one signal that would actually separate a cloud
+ *    sandbox from a laptop is the one we will not collect.
+ *  - Hostname patterns (`runner-*`, `ip-10-*`). A hostname is user data, and matching names is
+ *    guesswork dressed as a measurement — a guessed dimension and a measured one are
+ *    indistinguishable once they are in the same column.
+ *  - Process ancestry. Costs a spawn on a path that must never tax a command, and reads the name of
+ *    somebody else's program to classify our own user.
+ *  - `npm_config_user_agent`. Says which package manager ran us, which every route shares.
+ *  - An absent `$DISPLAY`. Every Linux server, every ssh session, and a large share of genuine
+ *    developer machines trip it; it separates nothing.
+ */
+import { existsSync } from 'node:fs';
+import { AutomationHint } from '@reticlehq/core';
+/** Container runtimes drop one of these at the filesystem root. */
+const CONTAINER_MARKERS = ['/.dockerenv', '/run/.containerenv'];
+/** Hosted dev environments that declare themselves. Self-declared, never inferred. */
+const HOSTED_WORKSPACE_ENV = [
+    'CODESPACES',
+    'GITPOD_WORKSPACE_ID',
+    'CLOUD_SHELL',
+    'REMOTE_CONTAINERS',
+];
+/**
+ * The most specific signal that fires, or undefined.
+ *
+ * Ordered most specific first: a container inside a Codespace with no terminal is one fact about the
+ * run, and sending the weakest of the three would waste the field. Omitted rather than sent as a
+ * "none" value, so its presence is itself the signal — the convention every other advisory field
+ * here follows.
+ */
+export function resolveAutomationHint(input) {
+    if (CONTAINER_MARKERS.some((m) => input.fileExists(m)))
+        return AutomationHint.CONTAINER;
+    if (HOSTED_WORKSPACE_ENV.some((k) => (input.env[k] ?? '') !== ''))
+        return AutomationHint.HOSTED_WORKSPACE;
+    if (!input.hasTty)
+        return AutomationHint.NO_TTY;
+    return undefined;
+}
+/** The real reading, taken once per process. */
+export function currentAutomationHint(env) {
+    return resolveAutomationHint({
+        env,
+        fileExists: (p) => {
+            try {
+                return existsSync(p);
+            }
+            catch {
+                return false; // an unreadable root is not evidence of anything
+            }
+        },
+        // Both ends, because a piped stdout alone is how `reticle status | jq` looks, and that is a
+        // person typing.
+        hasTty: true === process.stdout.isTTY || true === process.stdin.isTTY,
+    });
+}

package/dist/telemetry/bug-found.d.ts

@@ -6,24 +6,22 @@ import { type BugFound } from '@reticlehq/core';
  * nothing about sessions and should stay that way. The emission site owns the dedup flag.
  */
 export type BugCandidate = Omit<BugFound, 'repeat'>;
+export declare function bugsInResult(toolName: string, result: Record<string, unknown>): BugCandidate[];
 /**
- * `bug.attribution` was REMOVED, deliberately, and this note is here so it is not re-added casually.
- *
- * It shipped twice and was wrong both times. First it stamped `app` on every contradiction, including
- * `request-never-settled` — which Reticle raises from the ABSENCE of a settle event, so a dev-overlay
- * poll manufactured it with the app doing nothing wrong. That was fixed, and a real drive then found
- * it still inverted: across two full runs, EVERY `attribution: 'app'` was a misattribution, while the
- * one defect that genuinely was a bad agent predicate carried none. One session would have published
- * "2 defects in the app" against a true count of 0.
+ * Crawl anomaly kinds that are CONTRADICTIONS rather than single-channel faults.
  *
- * A metric that is confidently wrong about WHOSE fault a defect is, is worse than no metric: it is
- * the number a founder steers on, and it points at the customer. Counting nothing is recoverable;
- * publishing a false accusation about somebody's product is not.
+ * `reticle_crawl` returns both classes in one `anomalies` array — a console error is one channel
+ * complaining, while a UI that advanced over a failed write is two channels disagreeing. Only the
+ * second presents as success, and collapsing them would inflate the one claim that has to be exact.
  *
- * Bringing it back needs evidence that actually separates the cases. It does not exist in the payload
- * today: `element.present` covers "the button is missing", "the API is down" and "the agent mistyped
- * a testid" identically, and `signal.absent` covers both a signal the app never fired and a ref
- * Reticle drove into nothing. Until a verdict carries the reason it came out that way, the honest
- * output is no owner at all.
+ * DERIVED from core's `ContradictionKind`, never hand-listed. The first version copied the twelve
+ * strings into a literal here, which matched on the day it was written and would have silently
+ * misclassified the thirteenth: a new contradiction kind would have been counted as an ordinary
+ * fault, quietly deflating the exact number we intend to publish. A copied enum is a drift hazard
+ * wherever it appears; it is a correctness hazard when the thing that drifts is a public claim.
  */
-export declare function bugsInResult(toolName: string, result: Record<string, unknown>): BugCandidate[];
+/**
+ * The route the app was on when this result was produced — extracted from the tool result so the
+ * fingerprint can identify the same defect across sessions without sending the route itself.
+ */
+export declare function routeOf(result: Record<string, unknown>): string | undefined;

package/dist/telemetry/bug-found.js

@@ -16,7 +16,7 @@
  * anyone's app: that a class of defect was found, never what it was found in.
  */
 import { ReticleTool } from '../tools/tool-names.js';
-import { BugSource, ContradictionKind } from '@reticlehq/core';
+import { BugAttribution, BugSource, ContradictionKind, isAbsenceDerived, } from '@reticlehq/core';
 /** Cap per tool call — a pathological crawl must not turn one call into a thousand events. */
 const MAX_BUGS_PER_CALL = 25;
 function kindsOf(value) {
@@ -90,25 +90,35 @@ function couldNotRun(failure) {
         true === failure.couldNotRun);
 }
 /**
- * `bug.attribution` was REMOVED, deliberately, and this note is here so it is not re-added casually.
+ * WHOSE fault a contradiction was.
  *
- * It shipped twice and was wrong both times. First it stamped `app` on every contradiction, including
- * `request-never-settled` — which Reticle raises from the ABSENCE of a settle event, so a dev-overlay
- * poll manufactured it with the app doing nothing wrong. That was fixed, and a real drive then found
- * it still inverted: across two full runs, EVERY `attribution: 'app'` was a misattribution, while the
- * one defect that genuinely was a bad agent predicate carried none. One session would have published
- * "2 defects in the app" against a true count of 0.
+ * `attribution` shipped twice and was wrong both times. It stamped `app` on every contradiction,
+ * including `request-never-settled` — which Reticle raises from the ABSENCE of a settle event, so a
+ * dev-overlay poll manufactured it with the app doing nothing wrong. Across two full real drives
+ * EVERY `attribution: 'app'` was a misattribution, while the one defect that genuinely was a bad
+ * agent predicate carried none. A metric confidently wrong about whose fault a defect is, is worse
+ * than no metric: it is the number a founder steers on, and it points at the customer.
  *
- * A metric that is confidently wrong about WHOSE fault a defect is, is worse than no metric: it is
- * the number a founder steers on, and it points at the customer. Counting nothing is recoverable;
- * publishing a false accusation about somebody's product is not.
+ * The evidence that was missing then exists now, and it is already drawn in core for the verdict:
+ * `ABSENCE_DERIVED_CONTRADICTIONS` separates the kinds inferred from something NOT having happened
+ * inside a window Reticle chose the end of, from the kinds positively OBSERVED — a request that came
+ * back failed, a signal the app fired that disagrees with its own screen, a written field echoed
+ * back changed. Only the second class is evidence against the app, and it is the same line that
+ * decides whether a verdict may say `no`. Reusing it rather than inventing a second judgement beside
+ * it is the whole point: every historical misattribution was an absence-derived kind, so this rule
+ * produces zero of them on the data that broke the last two versions.
  *
- * Bringing it back needs evidence that actually separates the cases. It does not exist in the payload
- * today: `element.present` covers "the button is missing", "the API is down" and "the agent mistyped
- * a testid" identically, and `signal.absent` covers both a signal the app never fired and a ref
- * Reticle drove into nothing. Until a verdict carries the reason it came out that way, the honest
- * output is no owner at all.
+ * Everything else — a failed assertion, a replay regression, a crawl anomaly that is not a
+ * contradiction — is `unclassified`, which is a VALUE and not a gap. A failed `element.present`
+ * covers "the button is missing", "the API is down" and "the agent mistyped a testid" identically,
+ * and a console error can be the app, a browser extension or a framework dev overlay. Guessing there
+ * puts a guess into the one number we intend to publish. See issue #122.
  */
+function attributionOf(kind) {
+    return CONTRADICTION_KINDS.has(kind) && !isAbsenceDerived(kind)
+        ? BugAttribution.APP
+        : BugAttribution.UNCLASSIFIED;
+}
 export function bugsInResult(toolName, result) {
     // `reticle_run` is a WRAPPER: its handler calls runTool on the real tool, which already reported
     // that result's defects under the real tool's name — then the outer chokepoint reports the very
@@ -133,6 +143,7 @@ export function bugsInResult(toolName, result) {
             kind,
             falseGreen: passed,
             tool: toolName,
+            attribution: attributionOf(kind),
         });
     }
     // 2. Crawl anomalies — found autonomously, with nobody writing a test. Crawl reports its own
@@ -148,8 +159,9 @@ export function bugsInResult(toolName, result) {
             // — even though no assertion was made. See the definition on `falseGreen`.
             falseGreen: CONTRADICTION_KINDS.has(kind),
             tool: toolName,
-            // Nobody wrote a predicate here, so there is no bad request to blame: a crawl anomaly is a
-            // fault the app produced on its own.
+            // Same kind, same owner, wherever it arrives. A `request-never-settled` found by the crawler
+            // is no better evidence about whose fault it was than one found by an assertion.
+            attribution: attributionOf(kind),
         });
     }
     // 3. A failed assertion — the agent declared a consequence and it did not hold.
@@ -167,7 +179,9 @@ export function bugsInResult(toolName, result) {
             kind,
             falseGreen: false,
             tool: toolName,
-            // Omitted when the label cannot say whose fault it was — see ASSERTION_ATTRIBUTION.
+            // The assertion label cannot say whose fault it was: `element.present` covers a missing
+            // button, a downed API and a mistyped testid identically.
+            attribution: BugAttribution.UNCLASSIFIED,
         });
     }
     // 4. Replay failures — a saved flow that used to pass no longer does. That is a regression caught,
@@ -184,8 +198,11 @@ export function bugsInResult(toolName, result) {
                 kind: 'flow-regression',
                 falseGreen: false,
                 tool: toolName,
-                // A saved flow that used to pass and no longer does is a regression in the app. Rows that
-                // never RAN are skipped above precisely so Reticle's own failures do not land here.
+                // A flow that used to pass and no longer does is a regression SOMEWHERE, and the row does
+                // not say where: the app changed, or a selector strategy of ours did. Rows that never RAN
+                // are skipped above, which keeps Reticle's outright failures out of the count entirely, but
+                // that is a weaker fact than the positive evidence `app` requires.
+                attribution: BugAttribution.UNCLASSIFIED,
             });
         }
     }
@@ -204,4 +221,18 @@ export function bugsInResult(toolName, result) {
  * fault, quietly deflating the exact number we intend to publish. A copied enum is a drift hazard
  * wherever it appears; it is a correctness hazard when the thing that drifts is a public claim.
  */
+/**
+ * The route the app was on when this result was produced — extracted from the tool result so the
+ * fingerprint can identify the same defect across sessions without sending the route itself.
+ */
+export function routeOf(result) {
+    const status = result['status'];
+    if ('object' === typeof status && status !== null) {
+        const r = status['route'];
+        if ('string' === typeof r && r.length > 0)
+            return r;
+    }
+    const r = result['route'];
+    return 'string' === typeof r && r.length > 0 ? r : undefined;
+}
 const CONTRADICTION_KINDS = new Set(Object.values(ContradictionKind));

package/dist/telemetry/cli-telemetry.js

@@ -8,6 +8,7 @@ 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';
+import { resolveInstallSource } from './install-source.js';
 /**
  * Report that a person ran a `reticle` subcommand.
  *
@@ -45,7 +46,12 @@ export function reportCliRun(argv) {
     // 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 });
+        void telemetry.emit(TelemetryEventKind.RETICLE_INSTALLED, {
+            detach: true,
+            // WHICH published route brought this machine in. Self-declared by the channel, never inferred
+            // — see install-source.ts for which of the four routes can actually carry the marker.
+            installSource: resolveInstallSource(),
+        });
     if (!isHumanCliCommand(command))
         return;
     void telemetry.emit(TelemetryEventKind.CLI_COMMAND_RUN, {

package/dist/telemetry/daemon-telemetry.js

@@ -13,6 +13,8 @@ import { profileProject } from './project-profile.js';
 import { startUpdateCheck } from '../update/update-nudge.js';
 import { markDaemonStart } from './mcp-connection.js';
 import { markInstrumentationClock } from './app-instrumented.js';
+import { markStallClock, reportInstrumentationStall } from './instrumentation-stall.js';
+import { readProjectId } from '../cli/cli-port.js';
 /** Let the daemon finish coming up before walking the source tree for a profile. */
 const PROJECT_PROFILE_DELAY_MS = 5_000;
 /**
@@ -57,6 +59,8 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
     // Same clock, different half of the install: one measures how long before an AGENT attached, this
     // one how long before an APP did. The gap between them is the funnel.
     markInstrumentationClock(now());
+    // The other half of the same question: how long before an app arrives, and a report if none does.
+    markStallClock(now());
     // One profile per daemon start: what kind of project this is and how deeply Reticle is used in it.
     // Deferred off the boot path — it walks the source tree, and nothing about a daemon coming up
     // should wait on a filesystem scan.
@@ -71,6 +75,17 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
         }
     }, PROJECT_PROFILE_DELAY_MS).unref();
     const flushWindow = () => {
+        // BEFORE the idle return, and that ordering is the whole point: a stalled install produces an
+        // empty window by definition — no app, so no tool calls, so nothing to roll up. Checking it
+        // after the early return would make the one case this event exists for the one case it never
+        // sees. It is self-limiting (once per run, never after an app connects), so running it on every
+        // tick costs a comparison.
+        reportInstrumentationStall({
+            // Same test `app_instrumented` uses for the same field, so the success and failure events
+            // stay directly comparable: a stamped projectId means `init` has run here.
+            initialized: readProjectId(cwd) !== undefined,
+            agentAttached: metrics.agentEverAttached,
+        }, now);
         if (metrics.empty)
             return; // an idle window is not worth an event
         // NOT daemon_stopped: the daemon is still running. See SESSION_PROGRESS.
@@ -93,6 +108,15 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
             stopped ??= (async () => {
                 clearInterval(flush);
                 clearTimeout(firstFlush);
+                // Last chance to say that no app ever arrived. The periodic path cannot report an
+                // UNATTENDED stall at all — that daemon idle-exits at five minutes and the periodic
+                // threshold is ten — so without this the event only ever describes daemons with an agent
+                // attached, which is not the population it was built to measure. Self-limiting: if the
+                // interval already reported, this returns false and emits nothing.
+                reportInstrumentationStall({
+                    initialized: readProjectId(cwd) !== undefined,
+                    agentAttached: metrics.agentEverAttached,
+                }, now, { atShutdown: true });
                 // The rich one: the whole session in a single event — duration, the tool histogram, error
                 // shapes, verifications, browser launches. This is what replaced the per-tool-call event.
                 await getTelemetry().emit(TelemetryEventKind.DAEMON_STOPPED, {

package/dist/telemetry/feedback.js

@@ -147,7 +147,7 @@ export async function submitFeedback(input, opts = {}) {
             // 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.'
+                ? '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,

package/dist/telemetry/init-telemetry.js

@@ -12,6 +12,7 @@
  */
 import { TelemetryEventKind } from '@reticlehq/core';
 import { getTelemetry } from './telemetry.js';
+import { resolveInstallSource } from './install-source.js';
 /** Classified init failures — our own vocabulary, never a raw error or a path. */
 export const InitFailure = {
     /** Run outside a project root. The single most common first-run mistake. */
@@ -25,7 +26,14 @@ export const InitFailure = {
 /** Report one init outcome. Best-effort; setup must never fail because a metric did. */
 export function reportInitOutcome(init) {
     try {
-        void getTelemetry().emit(TelemetryEventKind.INIT_COMPLETED, { init, detach: true });
+        void getTelemetry().emit(TelemetryEventKind.INIT_COMPLETED, {
+            init,
+            detach: true,
+            // The other half of attribution: `reticle_installed` says a machine arrived, this says the
+            // setup on it finished, and only together do they say which route converts. Same self-declared
+            // marker, same refusal to infer — see install-source.ts.
+            installSource: resolveInstallSource(),
+        });
     }
     catch {
         /* a metric must never break `reticle init` */