@reticlehq/server 2.4.0 → 2.5.0

package/dist/session/session-reconnect.js

@@ -0,0 +1,42 @@
+/**
+ * Block until a reloaded page has re-announced itself under the same session id.
+ *
+ * A reload tears the SDK down. The id survives (see session-continuity), and the daemon replaces the
+ * old Session with a new one when the page says HELLO again — so "is it back?" is exactly "does a
+ * DIFFERENT object hold this id now?". Identity, not a flag: the returning page always constructs a
+ * new Session, and nothing else can claim an id it already owns.
+ *
+ * Polls a live getter rather than subscribing, because there is no reconnect event to subscribe to
+ * and inventing one for this would be a wire change for a two-second wait.
+ */
+/**
+ * How often to look for the reconnected session.
+ *
+ * 25ms, not 100. What is being polled is an in-memory map lookup — no I/O, no browser round-trip —
+ * while the thing being waited for is an EVENT (the reloaded page's HELLO). At 100ms the agent paid
+ * up to a full interval of dead time after the page was already back, on every navigate-with-reload.
+ * Measured across the fixture fleet, `reticle_navigate` clustered at 105 / 202-206 / 308 / 407ms —
+ * the poll grid, visible in the data. Four times the checks of something this cheap costs nothing
+ * anyone can measure.
+ */
+const DEFAULT_POLL_MS = 25;
+/**
+ * How long a reload is worth waiting for before answering "not confirmed".
+ *
+ * A production build is back in well under a second; a cold dev-server route rebuild is the slow
+ * case this budget is sized for. It is a CEILING, not a delay — the common path returns on the first
+ * or second poll.
+ */
+export const RELOAD_RECONNECT_TIMEOUT_MS = 5000;
+export async function waitForReconnect(opts) {
+    const poll = opts.pollMs ?? DEFAULT_POLL_MS;
+    const start = opts.now();
+    for (;;) {
+        const live = opts.current();
+        if (live !== undefined && live !== opts.previous)
+            return true;
+        if (opts.now() - start >= opts.timeoutMs)
+            return false;
+        await opts.sleep(poll);
+    }
+}

package/dist/session/session.d.ts

@@ -3,7 +3,7 @@ import { LastAct } from './last-act.js';
 import { type PageRuntime } from './command-timeout.js';
 import { type SessionHealth } from './session-health.js';
 export type { SessionHealth };
-import { PresenterTone, SessionState, type CommandResult, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
+import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
 import type { JournalReader, JournalRecorder } from '../journal/journal-recorder.js';
 import { type EventQueryOptions } from '../journal/journal-query.js';
 import { type AmbientCounts } from '../journal/ambient.js';
@@ -27,6 +27,8 @@ export declare class Session {
     title: string;
     adapters: string[];
     hasCapabilities: boolean;
+    /** Set when the page's SDK version differs from the daemon's (see version-skew.ts). */
+    versionSkew?: string;
     /**
      * Extra key names this app declared sensitive via `connect({ redact: { keys } })`. Held so the
      * DRIVEN path can redact them too — a request body the daemon captures from the network stack
@@ -46,10 +48,12 @@ export declare class Session {
      * `runtime` is optional so an older SDK (which does not report it) still works — it simply loses
      * the desktop-specific timeout diagnosis rather than breaking.
      */
-    applyHealth(hidden: boolean, focused: boolean, runtime?: string, engine?: string): void;
+    applyHealth(hidden: boolean, focused: boolean, runtime?: string, engine?: string, brand?: BrowserBrand): void;
     /** The shell (web/electron/tauri) and rendering engine the SDK reported. Undefined on an older SDK. */
     get runtime(): PageRuntime | undefined;
     get engine(): string | undefined;
+    /** The browser brand the SDK reported. Absent (never guessed) when the page did not say. */
+    get brand(): BrowserBrand | undefined;
     /** Throttled if the tab is hidden OR we have not heard from it recently. */
     throttled(): boolean;
     /** The attachable health block — single source of truth for the tools. */
@@ -60,6 +64,14 @@ export declare class Session {
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event: ReticleEvent, byteSize?: number): void;
     recordActedRef(ref: string): void;
+    actedLabels(): ReadonlySet<string>;
+    /**
+     * Derive the snapshot-shaped label (`button "Deploy"`) from an act reply and remember it.
+     *
+     * Same shape the interactive snapshot emits, so coverage can match a control the agent drove
+     * against the same control after a re-render gave it a different ref.
+     */
+    private recordActedLabelFrom;
     actedRefs(): ReadonlySet<string>;
     noteRateLimited(dropped: number): void;
     blindSpots(): Readonly<Record<string, number>>;

package/dist/session/session.js

@@ -2,7 +2,8 @@ import { LastAct } from './last-act.js';
 import { commandTimeoutMessage } from './command-timeout.js';
 import { readHealthEvent } from './session-health.js';
 import { PendingCommands } from './pending-commands.js';
-import { EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
+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';
 import { filterEvents, mergeEventsBySeq, } from '../journal/journal-query.js';
 import {} from '../journal/ambient.js';
@@ -13,6 +14,7 @@ import { ReviewStore } from './review-store.js';
 import { buildSessionRecommendation } from './session-recommendation.js';
 import { buildPresenterArgs } from './presenter-args.js';
 import { buildSessionLease } from './session-lease.js';
+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';
@@ -32,6 +34,8 @@ export class Session {
     title;
     adapters;
     hasCapabilities;
+    /** Set when the page's SDK version differs from the daemon's (see version-skew.ts). */
+    versionSkew;
     /**
      * Extra key names this app declared sensitive via `connect({ redact: { keys } })`. Held so the
      * DRIVEN path can redact them too — a request body the daemon captures from the network stack
@@ -50,6 +54,8 @@ export class Session {
     /** Which shell the page reported (PAGE_HEALTH). Undefined until the first report lands. */
     #runtime;
     #engine;
+    /** Which browser the page said it is (chrome/edge/arc/…). Undefined on an SDK too old to report one. */
+    #brand;
     #focused = true;
     /** Liveness: wall-clock of the last AGENT command (distinct from browser chatter / lastSeen). */
     #lastAgentActivityAt;
@@ -101,14 +107,18 @@ export class Session {
      * `runtime` is optional so an older SDK (which does not report it) still works — it simply loses
      * the desktop-specific timeout diagnosis rather than breaking.
      */
-    applyHealth(hidden, focused, runtime, engine) {
+    applyHealth(hidden, focused, runtime, engine, brand) {
         this.#hidden = hidden;
         this.#focused = focused;
-        if (runtime === 'electron' || runtime === 'tauri' || runtime === 'web') {
+        if (AppRuntime.ELECTRON === runtime ||
+            AppRuntime.TAURI === runtime ||
+            AppRuntime.WEB === runtime) {
             this.#runtime = runtime;
         }
         if (engine !== undefined)
             this.#engine = engine;
+        if (brand !== undefined)
+            this.#brand = brand;
     }
     /** The shell (web/electron/tauri) and rendering engine the SDK reported. Undefined on an older SDK. */
     get runtime() {
@@ -117,6 +127,10 @@ export class Session {
     get engine() {
         return this.#engine;
     }
+    /** The browser brand the SDK reported. Absent (never guessed) when the page did not say. */
+    get brand() {
+        return this.#brand;
+    }
     /** Throttled if the tab is hidden OR we have not heard from it recently. */
     throttled() {
         return this.#hidden || this.lastSeenMs() > SESSION_HEALTH.STALE_THRESHOLD_MS;
@@ -137,29 +151,19 @@ export class Session {
         return recommendation === undefined ? base : { ...base, recommendation };
     }
     info() {
-        const base = {
-            sessionId: this.id,
+        return buildSessionInfo({
+            id: this.id,
             url: this.url,
-            ...(this.projectId === undefined ? {} : { projectId: this.projectId }),
+            projectId: this.projectId,
             title: this.title,
             adapters: this.adapters,
             hasCapabilities: this.hasCapabilities,
+            versionSkew: this.versionSkew,
             hidden: this.#hidden,
-            ...this.health(),
-        };
-        if (this.staleMs() > SESSION_LEASE.STALE_AFTER_MS) {
-            base.stale = true;
-            base.cleanup_suggestion =
-                'Call reticle_session{action:"end"} to free this session before starting new work.';
-        }
-        // Surface human bug reports in reticle_sessions (only when > 0, so a clean session adds nothing).
-        const marks = this.#review.pendingCount();
-        if (marks > 0) {
-            base.pendingMarks = marks;
-            const s = marks === 1 ? '' : 's';
-            base.review_suggestion = `The human flagged ${String(marks)} issue${s} on this tab — call reticle_session{action:"review"} to see and fix ${marks === 1 ? 'it' : 'them'}.`;
-        }
-        return base;
+            health: () => this.health(),
+            staleMs: () => this.staleMs(),
+            pendingMarkCount: () => this.#review.pendingCount(),
+        });
     }
     /** Wall-clock age of the session in milliseconds. */
     staleMs() {
@@ -169,7 +173,7 @@ export class Session {
     pushEvent(event, byteSize) {
         if (event.type === EventType.PAGE_HEALTH) {
             const r = readHealthEvent(event.data);
-            this.applyHealth(r.hidden ?? this.#hidden, r.focused ?? this.#focused, r.runtime, r.engine);
+            this.applyHealth(r.hidden ?? this.#hidden, r.focused ?? this.#focused, r.runtime, r.engine, r.brand);
         }
         // The in-page half of Reticle reporting its own failure — recorded like a tool error
         // (fingerprinted, variables stripped) so a broken observer is as visible as a broken tool.
@@ -195,7 +199,7 @@ export class Session {
             // pushState/replaceState/popstate; without this the URL stays frozen at the hello value, and
             // URL-based CDP correlation (real input) silently breaks after the first client-side nav.
             const to = event.data['to'];
-            if (typeof to === 'string' && to.length > 0)
+            if ('string' === typeof to && to.length > 0)
                 this.url = to;
         }
         const t = this.elapsed();
@@ -218,6 +222,35 @@ export class Session {
     recordActedRef(ref) {
         this.#observed.recordActedRef(ref);
     }
+    actedLabels() {
+        return this.#observed.actedLabels();
+    }
+    /**
+     * Derive the snapshot-shaped label (`button "Deploy"`) from an act reply and remember it.
+     *
+     * Same shape the interactive snapshot emits, so coverage can match a control the agent drove
+     * against the same control after a re-render gave it a different ref.
+     */
+    recordActedLabelFrom(result) {
+        const payload = result.result;
+        if (typeof payload !== 'object' || null === payload)
+            return;
+        const record = payload;
+        // The TESTID first: it is the strongest identity a control has and it survives any re-render.
+        // Coverage previously matched only on `role "name"`, so a control with a testid but no accessible
+        // name — or on a stack where the act reply carried neither — was unrecognisable after a
+        // re-render, and coverage read `exercised: 0` however much work had been done.
+        const testid = record['testid'];
+        if ('string' === typeof testid && testid.length > 0)
+            this.#observed.recordActedLabel(testid);
+        const role = record['role'];
+        const name = record['name'];
+        if (typeof role !== 'string' || typeof name !== 'string')
+            return;
+        if (0 === role.length || 0 === name.length)
+            return;
+        this.#observed.recordActedLabel(`${role} "${name}"`);
+    }
     actedRefs() {
         return this.#observed.actedRefs();
     }
@@ -348,7 +381,7 @@ export class Session {
         // still wrong, and it made the number depend on which tool the agent happened to use.
         if (name === ReticleCommand.ACT) {
             const ref = args['ref'];
-            if (typeof ref === 'string')
+            if ('string' === typeof ref)
                 this.recordActedRef(ref);
         }
         const id = this.#pending.nextId(COMMAND_ID_PREFIX);
@@ -369,7 +402,17 @@ export class Session {
         }));
         this.#socket.send(payload);
         const sentAt = Date.now(); // browser-leg timing; see recordBrowserLatency for why it is split out
-        return awaited.finally(() => recordBrowserLatency(Date.now() - sentAt));
+        // Traced because this is the boundary that decides whether a slow tool call is OUR overhead or
+        // the app taking its time — the split telemetry reports in aggregate, made visible per call.
+        return span('browser.command', { command: name, sessionId: this.id }, () => awaited)
+            .then((result) => {
+            // The label is only knowable from the REPLY — the request carries a ref, and a ref dies with
+            // the next re-render. Recorded here so coverage survives frameworks that replace nodes.
+            if (name === ReticleCommand.ACT)
+                this.recordActedLabelFrom(result);
+            return result;
+        })
+            .finally(() => recordBrowserLatency(Date.now() - sentAt));
     }
     handleResult(result) {
         this.#pending.settle(result);
@@ -490,7 +533,7 @@ export class Session {
         // still wrong, and it made the number depend on which tool the agent happened to use.
         if (name === ReticleCommand.ACT) {
             const ref = args['ref'];
-            if (typeof ref === 'string')
+            if ('string' === typeof ref)
                 this.recordActedRef(ref);
         }
         const id = this.#pending.nextId(COMMAND_ID_PREFIX);

package/dist/session/state-select.d.ts

@@ -4,4 +4,4 @@
  * without paying the truncation tax); the server re-exports it for its back-compat fallback path
  * (an older browser that returns the whole store) and for the predicate engine's `state` assertion.
  */
-export { selectPath, capDepth, type PathSelection } from '@reticlehq/core';
+export { selectPath, capDepth, projectComponentState, type PathSelection } from '@reticlehq/core';

package/dist/session/state-select.js

@@ -4,4 +4,4 @@
  * without paying the truncation tax); the server re-exports it for its back-compat fallback path
  * (an older browser that returns the whole store) and for the predicate engine's `state` assertion.
  */
-export { selectPath, capDepth } from '@reticlehq/core';
+export { selectPath, capDepth, projectComponentState } from '@reticlehq/core';

package/dist/status-payload.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What `GET /status` answers — the daemon describing itself.
+ *
+ * Carries the daemon's OWN version, because a daemon outlives every agent attached to it: after an
+ * upgrade the new CLI attaches to the old daemon and serves its code, and until this field existed
+ * there was no surface anywhere — not /status, not `reticle status` — naming the version actually
+ * answering requests. See describeDaemonSkew.
+ */
+import type { SessionInfo } from './session/session-info.js';
+interface StatusPayload {
+    running: true;
+    version: string;
+    /** The wire contract this daemon speaks — what another process compares against, not the version. */
+    contract: string;
+    sessionCount: number;
+    sessions: SessionInfo[];
+}
+export declare function statusPayload(sessionCount: number, sessions: SessionInfo[]): StatusPayload;
+export {};

package/dist/status-payload.js

@@ -0,0 +1,11 @@
+import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
+import { SERVER_VERSION } from './version/server-version.js';
+export function statusPayload(sessionCount, sessions) {
+    return {
+        running: true,
+        version: SERVER_VERSION,
+        contract: CONTRACT_FINGERPRINT,
+        sessionCount,
+        sessions,
+    };
+}

package/dist/telemetry/argument-shape.js

@@ -57,10 +57,19 @@ export function describeParam(name, value) {
         return name;
     return `${name}:${allowed.has(value) ? value : OTHER_VALUE}`;
 }
+/**
+ * Parameters that carry no information about how the tool is USED, and so are not counted.
+ *
+ * `sessionId` is accepted by nearly every tool and passed on nearly every call, so counting it
+ * produced a row per tool saying only "the agent addressed a session" — in one real day's export it
+ * was a third of the toolParams block. This histogram exists to answer "is anyone using the argument
+ * we shipped last release", and a parameter every call carries can never answer it.
+ */
+const UNINFORMATIVE_PARAMS = new Set(['sessionId']);
 /** Every parameter an agent actually passed to one tool call, reduced to names (+ safe enums). */
 export function describeToolParams(args) {
     return Object.keys(args)
-        .filter((key) => args[key] !== undefined)
+        .filter((key) => args[key] !== undefined && !UNINFORMATIVE_PARAMS.has(key))
         .map((key) => describeParam(key, args[key]))
         .sort();
 }

package/dist/telemetry/browser-mode.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Was this verification watched by a person, or run by a machine?
+ *
+ * A verification's cost and its meaning both depend on it. A headless run is CI or an unattended
+ * agent loop — it should be fast, and there is nobody to notice a wrong answer. A headed run has a
+ * human in front of it. And the most common case of all is neither: the SDK in somebody's own dev
+ * server, in their own browser, which Reticle never launched at all.
+ *
+ * Recorded once at daemon start, because that is when the decision is made and it does not change
+ * for the daemon's life. Defaults to ATTACHED, which is the honest answer when Reticle launched
+ * nothing: claiming "headless" for a browser we did not open would be a guess about somebody's
+ * machine.
+ */
+export declare const BrowserMode: {
+    /** Reticle launched the browser with no display — CI, or an unattended agent loop. */
+    readonly HEADLESS: "headless";
+    /** Reticle launched a visible browser — a human is watching. */
+    readonly HEADED: "headed";
+    /** Reticle launched nothing: the SDK connected from a browser somebody else opened. */
+    readonly ATTACHED: "attached";
+};
+export type BrowserMode = (typeof BrowserMode)[keyof typeof BrowserMode];
+/** Record how this daemon drives a browser. Called once, at start. */
+export declare function setBrowserMode(mode: BrowserMode): void;
+export declare function getBrowserMode(): BrowserMode;
+/** Tests only — restore the default so cases do not leak into each other. */
+export declare function resetBrowserMode(): void;

package/dist/telemetry/browser-mode.js

@@ -0,0 +1,33 @@
+/**
+ * Was this verification watched by a person, or run by a machine?
+ *
+ * A verification's cost and its meaning both depend on it. A headless run is CI or an unattended
+ * agent loop — it should be fast, and there is nobody to notice a wrong answer. A headed run has a
+ * human in front of it. And the most common case of all is neither: the SDK in somebody's own dev
+ * server, in their own browser, which Reticle never launched at all.
+ *
+ * Recorded once at daemon start, because that is when the decision is made and it does not change
+ * for the daemon's life. Defaults to ATTACHED, which is the honest answer when Reticle launched
+ * nothing: claiming "headless" for a browser we did not open would be a guess about somebody's
+ * machine.
+ */
+export const BrowserMode = {
+    /** Reticle launched the browser with no display — CI, or an unattended agent loop. */
+    HEADLESS: 'headless',
+    /** Reticle launched a visible browser — a human is watching. */
+    HEADED: 'headed',
+    /** Reticle launched nothing: the SDK connected from a browser somebody else opened. */
+    ATTACHED: 'attached',
+};
+let current = BrowserMode.ATTACHED;
+/** Record how this daemon drives a browser. Called once, at start. */
+export function setBrowserMode(mode) {
+    current = mode;
+}
+export function getBrowserMode() {
+    return current;
+}
+/** Tests only — restore the default so cases do not leak into each other. */
+export function resetBrowserMode() {
+    current = BrowserMode.ATTACHED;
+}

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

@@ -1,20 +1,3 @@
-/**
- * Counting the defects Reticle actually finds.
- *
- * Every other metric in this product measures whether Reticle is USED. This one measures whether it
- * WORKS — and it is the only number that can honestly be put in front of an investor or published,
- * because it counts outcomes for users rather than activity by them.
- *
- * It is read off tool RESULTS at the single chokepoint every tool already crosses, rather than
- * emitted from the four places that produce findings. That is deliberate: the detectors are pure
- * functions and should stay that way, and reading results means a fifth source of findings is covered
- * the day it starts returning one of these shapes, instead of the day someone remembers to instrument
- * it.
- *
- * What is sent is the KIND from Reticle's own findings vocabulary — `signal-contradicted`,
- * `console-error`, `duplicate-request`. Never a selector, a URL, an element, or a description of
- * anyone's app: that a class of defect was found, never what it was found in.
- */
 import { type BugFound } from '@reticlehq/core';
 /**
  * A defect as the CLASSIFIER sees it — everything except `repeat`.
@@ -24,10 +7,23 @@ import { type BugFound } from '@reticlehq/core';
  */
 export type BugCandidate = Omit<BugFound, 'repeat'>;
 /**
- * The defects in one tool result.
+ * `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.
  *
- * Ordering matters for the false-green flag: a contradiction found alongside a PASSING assertion is
- * the case the product exists for — the screen looked right, the write failed, and every other tool
- * on the market would have called it green. That pairing is what `falseGreen` marks.
+ * 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

@@ -15,6 +15,7 @@
  * `console-error`, `duplicate-request`. Never a selector, a URL, an element, or a description of
  * 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';
 /** Cap per tool call — a pathological crawl must not turn one call into a thousand events. */
 const MAX_BUGS_PER_CALL = 25;
@@ -24,7 +25,7 @@ function kindsOf(value) {
     return value
         .map((entry) => {
         const kind = entry?.kind;
-        return typeof kind === 'string' ? kind : undefined;
+        return 'string' === typeof kind ? kind : undefined;
     })
         .filter((kind) => kind !== undefined);
 }
@@ -35,16 +36,111 @@ function kindsOf(value) {
  * the case the product exists for — the screen looked right, the write failed, and every other tool
  * on the market would have called it green. That pairing is what `falseGreen` marks.
  */
+/**
+ * The verdict this result carries, whatever envelope it arrived in.
+ *
+ * `reticle_assert` reports a top-level boolean `pass`. `reticle_act_and_wait` — the tool agents
+ * actually reach for, and the one whose description calls it the act->observe->assert loop — reports
+ * `verdict.pass` with the summary at `verified`. Reading only `result.pass` meant a FAILED
+ * act_and_wait produced no bug at all, and a contradiction found next to a PASSING one was recorded
+ * with `falseGreen: false` — deflating the single number this product exists to publish, by the
+ * shape of its own envelope.
+ */
+function verdictOf(result) {
+    if ('boolean' === typeof result['pass'])
+        return result['pass'];
+    const verdict = result['verdict'];
+    if ('object' === typeof verdict && verdict !== null) {
+        const nested = verdict['pass'];
+        if ('boolean' === typeof nested)
+            return nested;
+    }
+    // `verified` is the field the agent is told to gate on; "unknown" is deliberately not a verdict.
+    const verified = result['verified'];
+    if ('yes' === verified)
+        return true;
+    if ('no' === verified)
+        return false;
+    return undefined;
+}
+/** The assertion label, from either envelope — act_and_wait nests it under `verdict`. */
+function assertionOf(result) {
+    if (result['assertion'] !== undefined)
+        return result['assertion'];
+    const verdict = result['verdict'];
+    return 'object' === typeof verdict && verdict !== null
+        ? verdict['assertion']
+        : undefined;
+}
+/**
+ * A verdict that could not be reached is not a defect found. `inconclusive` is set when the
+ * assertion was never evaluated — an under-specified call, or nothing instrumented to read — so
+ * counting it would put the agent's own mistakes into the number we publish.
+ */
+function isInconclusive(result) {
+    const verdict = result['verdict'];
+    return ('object' === typeof verdict &&
+        verdict !== null &&
+        'string' === typeof verdict['inconclusive']);
+}
+/** A suite row whose replay never STARTED — see SuiteFlowResult.couldNotRun. */
+function couldNotRun(failure) {
+    return ('object' === typeof failure &&
+        failure !== null &&
+        true === failure.couldNotRun);
+}
+/**
+ * `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 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
+    // same object again as `reticle_run`. One sweep of 34 events was a perfect mirror image:
+    // flow-regression x8/reticle_flow_verify AND x8/reticle_run; assertion-failed x8/reticle_verify_change
+    // AND x8/reticle_run. Sixteen of the thirty-four were echoes, and a headline number that doubles
+    // because of HOW a tool was reached is not a measurement.
+    //
+    // Nothing is lost by staying silent here: when the inner tool refuses or throws, the wrapper
+    // returns { error, tool, params, hint }, which carries no verdict and no failures to classify.
+    if (toolName === ReticleTool.RUN)
+        return [];
     const bugs = [];
-    const passed = result['pass'] === true;
+    const verdict = verdictOf(result);
+    const passed = true === verdict;
     // 1. Contradictions — channels disagreeing. Invisible to a human watching the screen.
     for (const kind of kindsOf(result['contradictions'])) {
-        bugs.push({ source: BugSource.CONTRADICTION, kind, falseGreen: passed, tool: toolName });
+        // A contradiction is two of the APP's own channels disagreeing — never the agent's phrasing.
+        // Omitted for the one kind Reticle can produce on its own: see contradictionAttribution.
+        bugs.push({
+            source: BugSource.CONTRADICTION,
+            kind,
+            falseGreen: passed,
+            tool: toolName,
+        });
     }
     // 2. Crawl anomalies — found autonomously, with nobody writing a test. Crawl reports its own
     //    contradictions inside `anomalies` too, so classify by kind rather than by which array it sat in.
     for (const kind of kindsOf(result['anomalies'])) {
+        // Crawl reports contradictions in this array too, so the same kind must get the 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.
         bugs.push({
             source: BugSource.CRAWL,
             kind,
@@ -52,28 +148,44 @@ 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.
         });
     }
     // 3. A failed assertion — the agent declared a consequence and it did not hold.
     //    Only when nothing above already explained it, or one defect would be counted twice.
-    if (result['pass'] === false && bugs.length === 0) {
-        const reason = result['assertion'];
+    // A red the APP earned, not one Reticle produced. `verified: "unknown"` is the honesty layer
+    // saying nothing was proved either way, and a top-level `error` is a refusal — measured over one
+    // sweep, every bug_found emitted was one of these two: "no session connected" from reticle_run and
+    // an unverifiable suite from reticle_verify_change, counted as defects in the user's app.
+    const reticleFailure = 'unknown' === result['verified'] || 'string' === typeof result['error'];
+    if (false === verdict && 0 === bugs.length && !isInconclusive(result) && !reticleFailure) {
+        const reason = assertionOf(result);
+        const kind = 'string' === typeof reason && reason.length > 0 ? reason.slice(0, 64) : 'assertion-failed';
         bugs.push({
             source: BugSource.ASSERTION,
-            kind: typeof reason === 'string' && reason.length > 0 ? reason.slice(0, 64) : 'assertion-failed',
+            kind,
             falseGreen: false,
             tool: toolName,
+            // Omitted when the label cannot say whose fault it was — see ASSERTION_ATTRIBUTION.
         });
     }
     // 4. Replay failures — a saved flow that used to pass no longer does. That is a regression caught,
     //    which is a different and stronger claim than "a check failed".
-    if (result['status'] === 'fail' && Array.isArray(result['failures'])) {
-        for (const _failure of result['failures'].slice(0, MAX_BUGS_PER_CALL)) {
+    if ('fail' === result['status'] && Array.isArray(result['failures'])) {
+        for (const failure of result['failures'].slice(0, MAX_BUGS_PER_CALL)) {
+            // A suite that failed because nothing could RUN is not a regression in the user's app. This
+            // rule never looked past `status`, so a project whose flow files did not resolve reported one
+            // "defect found" per flow — Reticle's own failure, published as the customer's.
+            if (couldNotRun(failure))
+                continue;
             bugs.push({
                 source: BugSource.REPLAY,
                 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.
             });
         }
     }