@reticlehq/server 2.7.0 → 2.8.0

package/dist/session/no-session-diagnosis.d.ts

@@ -27,6 +27,14 @@ interface NoSessionFacts {
     listening: readonly number[];
     /** The port this daemon is on — half of the mismatch the old message asked about. */
     port: number;
+    /**
+     * The directory `initialized` was decided in, named in the message when it is known.
+     *
+     * "There is no `.reticle.json`" is only ever true OF A DIRECTORY, and a reader who cannot see
+     * which one has to guess whether the claim is about their app at all — reported by someone whose
+     * app lives in `src/admin` while the daemon stands at the repo root.
+     */
+    directory?: string;
     /**
      * This daemon has reaped at least one EXPIRED pooled lease.
      *
@@ -34,6 +42,17 @@ interface NoSessionFacts {
      * evidence, not proof, and the message below is worded accordingly.
      */
     leaseExpired?: boolean;
+    /**
+     * The port `.reticle.json` configures for this project, when there is one.
+     *
+     * Half of a mismatch the daemon can settle rather than hint at: it knows the port it bound, and
+     * this is the number the app's SDK was built to dial. `doctor` already compares them and prints a
+     * precise line; the agent reading `why` was getting "check that the port matches" instead.
+     *
+     * Absent means no config, or one without a port, which is NOT a mismatch: a plugin-wired app has
+     * no `.reticle.json` at all and is working perfectly.
+     */
+    projectPort?: number;
 }
 /**
  * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session

package/dist/session/no-session-diagnosis.js

@@ -69,9 +69,57 @@ const NON_LOCALHOST_GATE = 'One more cause that leaves every other check healthy
     'is given `allowNonLocalhost: true` — the refusal is page-side, so nothing here can see it. ' +
     "Check the browser console for that message and pass the flag in the app's reticle.connect().";
 const SCANNED_PORTS = [...DEV_SERVER_PORTS].join(', ');
+/**
+ * The commonest first-run state there is, and until #320 the message named it nowhere.
+ *
+ * Reticle sees a page only once a browser has LOADED it. A wired app that nobody has opened produces
+ * exactly the same empty list as a broken install, and the reporter who hit it spent an afternoon
+ * re-verifying their init output, diffing their Vite config and curling their own page before
+ * discovering that one `reticle open` fixed it instantly.
+ */
+const OPEN_THE_APP = 'Reticle only ever sees a page that is LOADED, so the commonest cause by a distance is that no ' +
+    "browser has opened the app yet: run `reticle open <url>` with the app's own URL (or ask the " +
+    'human to open it).';
+/**
+ * What a machine-wide port scan can and cannot say.
+ *
+ * It finds listeners anywhere on localhost and knows nothing about who owns them. The old wording
+ * spent that as evidence — "something IS listening on port 5173, 8000, 8080, SO a server is up and
+ * has never dialled this daemon" — about three ports that belonged to three other repositories on
+ * the reporter's machine, while their own app sat on a port the scan does not cover. On any machine
+ * running more than one instrumented repo, which is the normal case here, that inference is unsound.
+ */
+function unattributedListeners(listening) {
+    if (0 === listening.length) {
+        return (`No listener found that I can attribute to this project: the scan covers ${SCANNED_PORTS} ` +
+            'across the whole machine, so an app on any other port is invisible to it.');
+    }
+    return (`Something is listening on port ${listening.join(', ')}, but I cannot attribute any of it to ` +
+        `this project: that is a machine-wide scan of ${SCANNED_PORTS}, so on a machine running more ` +
+        "than one repo those are as likely to be somebody else's dev server, and the app's own port " +
+        'may not be in the set at all. Treat them as unattributed rather than as evidence.');
+}
+/**
+ * The mismatch, stated with both numbers, when we can actually see one. Empty otherwise.
+ *
+ * Leading space so the caller can concatenate it unconditionally without producing a double space
+ * in the common case where there is nothing to say.
+ */
+function portMismatchClause(facts) {
+    const configured = facts.projectPort;
+    if (configured === undefined || configured === facts.port)
+        return '';
+    return (` They already disagree: \`.reticle.json\` says port ${String(configured)} and this daemon is` +
+        ` on ${String(facts.port)}, so the SDK is dialling ${String(configured)} and nothing is there.` +
+        ` Either restart the daemon on ${String(configured)}, or update \`.reticle.json\` to` +
+        ` ${String(facts.port)} and restart the dev server so the app picks it up.`);
+}
 export function diagnoseNoSession(facts) {
     const { everConnected, initialized, listening, port } = facts;
-    const ports = listening.join(', ');
+    // Named when known: a claim about a missing file is a claim about ONE directory.
+    const where = facts.directory === undefined
+        ? 'the directory this daemon is running in'
+        : `the directory this daemon is running in (${facts.directory})`;
     if (everConnected) {
         // A reaped lease first, because it is the one cause we have POSITIVE evidence for. Reported
         // from the field (#157): an aged-out lease produced "the tab was closed … ask the human to
@@ -80,14 +128,14 @@ export function diagnoseNoSession(facts) {
         // went looking for a port mismatch. Hedged rather than swapped: a human tab may ALSO have
         // closed, and this does not know which session went.
         if (true === facts.leaseExpired) {
-            return ('no browser session connected — but one WAS connected to this daemon earlier, so the wiring ' +
+            return ('no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
                 'is correct. This daemon has expired at least one pooled lease, so the likeliest cause is ' +
                 'that a lease you were using aged out; a lease is a headless context, not a human tab, and ' +
                 'it takes its cookies with it (so an authenticated app needs signing in again). Re-acquire ' +
                 'with reticle_lease {action:"acquire", url} and carry on. If you were driving a human tab ' +
                 `instead, it went away — reopen it or run \`reticle open\`. ${RETRY}`);
         }
-        return ('no browser session connected — but one WAS connected to this daemon earlier, so the wiring ' +
+        return ('no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
             'is correct. The tab was closed, navigated away, or hard-reloaded. Ask the human to reopen ' +
             `the app (or run \`reticle open\`), or reload the tab. ${SELF_SERVE} ${RETRY}`);
     }
@@ -111,16 +159,17 @@ export function diagnoseNoSession(facts) {
                 `(1) Nothing is listening on the ports Reticle scans (${SCANNED_PORTS}), so the dev server ` +
                 'may not be running — ask the human to start it (`npm run dev`). That scan is narrow ' +
                 'though: a server on any other port is invisible to it, so if the app IS running, ask for ' +
-                'its URL rather than assuming it is down. ' +
-                '(2) There is no `.reticle.json` in the directory this daemon is running in. That is the ' +
+                'its URL rather than assuming it is down, and open it with `reticle open <url>`. ' +
+                `(2) There is no \`.reticle.json\` in ${where}. That is the ` +
                 "file `reticle init` writes, so the app may carry no Reticle SDK — but check the app's " +
                 'OWN directory before re-running `init`: in a monorepo the daemon often runs at the root ' +
                 'while the app lives in a subdirectory, and an app wired by the Vite or Babel plugin ' +
                 `carries the SDK without that file at all. ${RETRY}`);
         }
-        return ('no browser session connected, and nothing is listening on the ports Reticle scans ' +
-            `(${SCANNED_PORTS}). The likeliest cause by far is that the dev server is not running: ask ` +
-            'the human to start it (`npm run dev`), then open the app in a browser. ' +
+        return (`no browser session connected, and this daemon has never seen one. ${OPEN_THE_APP} ` +
+            'Nothing is listening on the ports Reticle scans ' +
+            `(${SCANNED_PORTS}) either, and the most common reason for that is a dev server that is not ` +
+            'running: ask the human to start it (`npm run dev`), then open the app in a browser. ' +
             // The caveat is here rather than omitted because the scan is NARROW, and the old sentence
             // spent its confidence as though an empty result were proof of absence. Reported twice: a
             // scripted drive of 2.5.0 asserted the app was not running while it served 200 on :7699, and
@@ -137,15 +186,19 @@ export function diagnoseNoSession(facts) {
             `${RETRY}`);
     }
     if (!initialized) {
-        return (`no browser session connected, but something IS listening on port ${ports} — so a server is ` +
-            'up and has never dialled this daemon. This project has not been through `reticle init`, ' +
-            'which is what installs the SDK and wires it into the build, so the likeliest cause is that ' +
-            "the app carries no Reticle SDK. Ask the human to run `reticle init` in the app's directory " +
-            `and restart the dev server. ${RETRY}`);
+        return ('no browser session connected, and this daemon has never seen one. ' +
+            `What was actually checked: there is no \`.reticle.json\` in ${where}. That is the file ` +
+            '`reticle init` writes, so the app may carry no Reticle SDK — but it is not proof, and the ' +
+            'same absence is expected in a monorepo whose daemon runs at the root while the app lives in ' +
+            "a subdirectory, or in an app wired by the Vite or Babel plugin. Check the app's OWN " +
+            'directory: if it has no config, run `reticle init` there and restart the dev server; if it ' +
+            'has one, the app is wired and simply has no page open — `reticle open <url>`. ' +
+            `${unattributedListeners(listening)} ${RETRY}`);
     }
-    return (`no browser session connected, but something IS listening on port ${ports} and this project is ` +
-        `wired for Reticle — so the app is either serving a build made before the wiring landed, or ` +
-        `dialling a different daemon than this one (this daemon is on ${String(port)}). Ask the human ` +
-        'to restart the dev server and hard-reload the page; if it still does not appear, check that ' +
-        `the app's reticle port matches ${String(port)}. ${NON_LOCALHOST_GATE} ${SELF_SERVE} ${RETRY}`);
+    return ('no browser session connected, and this daemon has never seen one for this project, which is ' +
+        `wired for Reticle. ${OPEN_THE_APP} ${unattributedListeners(listening)} ` +
+        'If the page IS open and still does not appear, the app is either serving a build made before ' +
+        `the wiring landed or dialling a different daemon than this one (on ${String(port)}): restart ` +
+        "the dev server, hard-reload the page, and check that the app's reticle port matches " +
+        `${String(port)}.${portMismatchClause(facts)} ${NON_LOCALHOST_GATE} ${SELF_SERVE} ${RETRY}`);
 }

package/dist/session/no-session-watch.js

@@ -11,6 +11,7 @@
  */
 import { probeDevServers } from './dev-server-probe.js';
 import { diagnoseNoSession } from './no-session-diagnosis.js';
+import { readProjectPort } from '../cli/cli-port.js';
 /** Slow enough to be free, fast enough that a dev server started 15s ago is already reflected. */
 const REFRESH_MS = 15_000;
 /** Start the watch. Returns a stop function; the timer is unref'd so it never holds the daemon up. */
@@ -42,7 +43,18 @@ function startNoSessionWatch(options) {
         initialized: options.initialized,
         listening,
         port: options.port,
+        // The directory `initialized` was decided in. Named in the message because "there is no
+        // `.reticle.json`" is a claim about ONE directory, and a reader standing somewhere else
+        // cannot tell whether it is a claim about their app at all.
+        directory: options.directory ?? process.cwd(),
         leaseExpired: (options.reapedLeases?.() ?? 0) > 0,
+        // Read here rather than at boot: `.reticle.json` can be written by `init` after this daemon
+        // started, which is the ordinary first-install order, and a port cached from before it existed
+        // would make the daemon confidently report no mismatch on the one run where there is one.
+        ...(() => {
+            const configured = readProjectPort(options.directory ?? process.cwd());
+            return configured === undefined ? {} : { projectPort: configured };
+        })(),
     }));
     return () => {
         clearInterval(timer);

package/dist/session/ref-provenance.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Which tab a ref came out of, so the call that spends it cannot be routed to a different one.
+ *
+ * Reported from the field: three tabs of one project were connected, a snapshot was taken against a
+ * named session, and the act that followed omitted `sessionId`. Auto-selection picked a different
+ * tab, the ref legitimately did not exist there, and the refusal read "that ref is stale: refs are
+ * invalidated whenever the DOM re-renders" — a confident diagnosis of the wrong thing, and one that
+ * accuses the app under test. The recovery text then sends the agent to re-snapshot, which mints a
+ * fresh ref in whichever tab is chosen next, so the lesson it teaches is wrong either way.
+ *
+ * The quiet outcome is the worse one. Refs are minted from a per-document block, so the same number
+ * is a real, live, DIFFERENT element in the tab that was guessed: the identical call on a luckier day
+ * drives the wrong tab and returns a green about a page nobody asked about. That is a false green
+ * with extra steps, and it is the failure class this product exists to remove.
+ *
+ * Every `sessionId` description on the surface already promises that Reticle "refuses rather than
+ * guesses when ambiguous". This is the fact that makes the ambiguity visible: the tab a ref was
+ * handed out of is known at the moment it is handed out. Resolution is otherwise untouched — a call
+ * that names a session, carries no ref, or lands on the tab it looked at resolves silently, which is
+ * the cost the surface wording was rewritten to avoid.
+ *
+ * ponytail: one slot, not a per-ref map. It answers the reported shape — look at one tab, act on
+ * what you saw — for the cost of an assignment. A drive that interleaves refs from several tabs
+ * inside one turn needs per-ref provenance, and that is the upgrade if it ever shows up.
+ */
+/** Record that a tool handed out refs from this session. */
+export declare function noteRefsMinted(sessionId: string): void;
+export declare function refsLastMintedIn(): string | undefined;
+/** Test seam: the module holds one slot for the process, so a test has to be able to clear it. */
+export declare function forgetRefProvenance(): void;
+interface RefRouting {
+    /** The ref this call is about to spend, if it carries one. */
+    ref: string | undefined;
+    /** The `sessionId` the CALLER passed — when present, nothing was guessed. */
+    explicitSessionId: string | undefined;
+    /** The session resolution actually picked. */
+    chosenSessionId: string;
+    /**
+     * The connected sessions, read ONLY once a refusal is certain. A thunk because listing them walks
+     * every session and builds a health block each time, and the answer is wanted on the rare path.
+     */
+    connected: () => readonly {
+        sessionId: string;
+        url: string;
+    }[];
+}
+/**
+ * The refusal for a ref that belongs to another tab, or undefined when there is no ambiguity.
+ *
+ * Silent when the minting tab is no longer connected: that ref really is dead, and the stale-ref
+ * refusal that already exists is the honest answer for it.
+ */
+export declare function wrongTabRefusal(routing: RefRouting): string | undefined;
+export {};

package/dist/session/ref-provenance.js

@@ -0,0 +1,61 @@
+/**
+ * Which tab a ref came out of, so the call that spends it cannot be routed to a different one.
+ *
+ * Reported from the field: three tabs of one project were connected, a snapshot was taken against a
+ * named session, and the act that followed omitted `sessionId`. Auto-selection picked a different
+ * tab, the ref legitimately did not exist there, and the refusal read "that ref is stale: refs are
+ * invalidated whenever the DOM re-renders" — a confident diagnosis of the wrong thing, and one that
+ * accuses the app under test. The recovery text then sends the agent to re-snapshot, which mints a
+ * fresh ref in whichever tab is chosen next, so the lesson it teaches is wrong either way.
+ *
+ * The quiet outcome is the worse one. Refs are minted from a per-document block, so the same number
+ * is a real, live, DIFFERENT element in the tab that was guessed: the identical call on a luckier day
+ * drives the wrong tab and returns a green about a page nobody asked about. That is a false green
+ * with extra steps, and it is the failure class this product exists to remove.
+ *
+ * Every `sessionId` description on the surface already promises that Reticle "refuses rather than
+ * guesses when ambiguous". This is the fact that makes the ambiguity visible: the tab a ref was
+ * handed out of is known at the moment it is handed out. Resolution is otherwise untouched — a call
+ * that names a session, carries no ref, or lands on the tab it looked at resolves silently, which is
+ * the cost the surface wording was rewritten to avoid.
+ *
+ * ponytail: one slot, not a per-ref map. It answers the reported shape — look at one tab, act on
+ * what you saw — for the cost of an assignment. A drive that interleaves refs from several tabs
+ * inside one turn needs per-ref provenance, and that is the upgrade if it ever shows up.
+ */
+/** The session the last ref-bearing result was produced from. Undefined until something mints one. */
+let mintedIn;
+/** Record that a tool handed out refs from this session. */
+export function noteRefsMinted(sessionId) {
+    mintedIn = sessionId;
+}
+export function refsLastMintedIn() {
+    return mintedIn;
+}
+/** Test seam: the module holds one slot for the process, so a test has to be able to clear it. */
+export function forgetRefProvenance() {
+    mintedIn = undefined;
+}
+/**
+ * The refusal for a ref that belongs to another tab, or undefined when there is no ambiguity.
+ *
+ * Silent when the minting tab is no longer connected: that ref really is dead, and the stale-ref
+ * refusal that already exists is the honest answer for it.
+ */
+export function wrongTabRefusal(routing) {
+    if (routing.ref === undefined || routing.explicitSessionId !== undefined)
+        return undefined;
+    const source = mintedIn;
+    if (source === undefined || source === routing.chosenSessionId)
+        return undefined;
+    const connected = routing.connected();
+    if (!connected.some((s) => s.sessionId === source))
+        return undefined;
+    const listed = connected.map((s) => `'${s.sessionId}' (${s.url})`).join(', ');
+    return (`ref '${routing.ref}' was handed out by session '${source}', and this call named no sessionId so ` +
+        `it resolved to '${routing.chosenSessionId}'. A ref only means something in the tab it was taken ` +
+        'in — refs are minted per document, so the same one can point at a different element in another ' +
+        'tab — and Reticle refuses rather than guessing which tab you meant. Connected right now: ' +
+        `${listed}. Pass sessionId: '${source}' to act on the tab you looked at, or re-read the tab you ` +
+        'actually want first. Nothing was driven.');
+}

package/dist/session/session-lease.js

@@ -8,7 +8,7 @@
  *
  * Any edit here is a per-session tax on every user: say it in as few words as still work.
  */
-const SESSION_LEASE_NOTICE = 'When you stop driving, call reticle_session {action:"yield", mode:"waiting"|"ask"} — the panel reads "live" until you do. {action:"end"} when the task is done; it revives on your next action.';
+const SESSION_LEASE_NOTICE = 'When you stop driving, call reticle_session {action:"yield", mode:"waiting"|"ask"}. The panel reads "live" until you do. {action:"end"} when the task is done; it revives on your next action.';
 export function buildSessionLease(sessionId, openedAt) {
     return { sessionId, opened_at: openedAt, IMPORTANT: SESSION_LEASE_NOTICE };
 }

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,4 @@ 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'>;
-/**
- * `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.
- *
- * 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.
- *
- * 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.
- */
 export declare function bugsInResult(toolName: string, result: Record<string, unknown>): BugCandidate[];

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,
             });
         }
     }

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/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` */