@reticlehq/server 3.3.0 → 3.4.0

package/dist/portal/input/js-coverage.js

@@ -0,0 +1,30 @@
+export async function startJsCoverage(page, covering) {
+    if (covering.has(page))
+        return true;
+    try {
+        await page.coverage.startJSCoverage({ resetOnNavigation: false });
+        covering.add(page);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function takeJsCoverage(page, covering) {
+    // Nothing collects until something asks: collection slows every script on the page. The first
+    // take starts it and has nothing to report yet.
+    if (!covering.has(page)) {
+        await startJsCoverage(page, covering);
+        return undefined;
+    }
+    try {
+        const entries = await page.coverage.stopJSCoverage();
+        covering.delete(page);
+        await startJsCoverage(page, covering);
+        return entries;
+    }
+    catch {
+        covering.delete(page);
+        return undefined;
+    }
+}

package/dist/portal/input/real-input.d.ts

@@ -9,6 +9,7 @@
  * Node-only. Playwright is loaded via DYNAMIC `import('playwright')` so non-CDP users never
  * pay for it; the type-only import is elided by `tsc`, so the build stays green without it.
  */
+import { type ScriptCoverage } from './js-coverage.js';
 import type { Browser, Page } from 'playwright';
 import { ActionType, DriveErrorCode } from '@reticlehq/core';
 import { type MockRule } from './network-mock.js';
@@ -77,6 +78,14 @@ export interface RealInputProvider {
      * Optional: a provider with no owned browser simply omits it.
      */
     setMocks?(sessionUrl: string, rules: MockRule[]): Promise<boolean>;
+    /**
+     * What of the app's own code ran since the last take (V8 coverage, Chromium only), or undefined
+     * when no driven page matches or collection had not started. The first call starts collecting,
+     * because collection slows every script on the page and a slower page can let a console error land
+     * after a clean-console check passed. Optional: a provider with no owned browser cannot see the
+     * engine's counters.
+     */
+    takeCodeCoverage?(sessionUrl: string): Promise<ScriptCoverage[] | undefined>;
     /**
      * Pin the correlated page's viewport to fixed pixel dimensions so a screenshot baseline is
      * reproducible across machines (the missing piece of CI-stable visual regression, alongside masks
@@ -144,6 +153,7 @@ interface CdpProviderOptions {
 export declare class CdpRealInputProvider implements RealInputProvider {
     #private;
     constructor(options: CdpProviderOptions);
+    takeCodeCoverage(sessionUrl: string): Promise<ScriptCoverage[] | undefined>;
     isAvailableFor(sessionUrl: string): Promise<boolean>;
     perform(sessionUrl: string, action: ActionType, box: ElementBox, args: RealInputArgs): Promise<RealInputResult>;
     /** PNG of the correlated page, or undefined if none matches. */
@@ -236,6 +246,7 @@ export declare class LaunchedRealInputProvider implements OwnedRealInputProvider
         width: number;
         height: number;
     }): Promise<boolean>;
+    takeCodeCoverage(_sessionUrl: string): Promise<ScriptCoverage[] | undefined>;
     /** Apply network-mock rules to the owned page; false before navigate / after dispose. */
     setMocks(_sessionUrl: string, rules: MockRule[]): Promise<boolean>;
     /** Close the owned browser once. Idempotent and safe before navigate. */

package/dist/portal/input/real-input.js

@@ -1,6 +1,18 @@
+/**
+ * Optional CDP/Playwright real-input mode.
+ *
+ * Synthetic `dispatchEvent` cannot drive native hover/pointer state (an onMouseEnter never
+ * fires, hit-testing never runs). When a CDP endpoint is configured, this module connects a
+ * Playwright `Browser` over CDP and drives REAL pointer/keyboard input against the element box
+ * the SDK resolves (viewport CSS px from getBoundingClientRect).
+ *
+ * Node-only. Playwright is loaded via DYNAMIC `import('playwright')` so non-CDP users never
+ * pay for it; the type-only import is elided by `tsc`, so the build stays green without it.
+ */
+import { takeJsCoverage } from './js-coverage.js';
 import { stampedDriveUrl } from './drive-url-stamp.js';
-import { chromiumLaunchOptions } from '../../chromium-launch-options.js';
-import { gotoOptions } from '../pool/playwright-launcher.js';
+import { launchChromium } from '../../launch-chromium.js';
+import { chromiumLaunchHint, gotoOptions } from '../pool/playwright-launcher.js';
 import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
@@ -131,6 +143,8 @@ export class CdpRealInputProvider {
     /** Pages already listening. #pageFor resolves on EVERY call, so without this each action would add
      *  another listener and every response would be emitted once per action taken so far. */
     #listening = new WeakSet();
+    /** Pages collecting V8 coverage — see js-coverage.ts. */
+    #covering = new WeakSet();
     #browser;
     constructor(options) {
         this.#cdpUrl = options.cdpUrl;
@@ -176,6 +190,10 @@ export class CdpRealInputProvider {
             this.#listen(page);
         return page;
     }
+    async takeCodeCoverage(sessionUrl) {
+        const page = await this.#pageFor(sessionUrl);
+        return page === undefined ? undefined : takeJsCoverage(page, this.#covering);
+    }
     async isAvailableFor(sessionUrl) {
         try {
             return (await this.#pageFor(sessionUrl)) !== undefined;
@@ -273,13 +291,14 @@ export const launchedChromium = async (headless) => {
     }
     const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.LAUNCHED);
     try {
-        const browser = await mod.chromium.launch(chromiumLaunchOptions(headless));
+        const browser = await launchChromium(mod.chromium, headless);
         settle();
         return browser;
     }
     catch (e) {
         settle(classifyConnectFailure(e));
-        throw new DriveError(DriveErrorCode.LAUNCH_FAILED, e instanceof Error ? e.message : String(e));
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new DriveError(DriveErrorCode.LAUNCH_FAILED, chromiumLaunchHint(msg) ?? msg);
     }
 };
 /**
@@ -296,6 +315,8 @@ export class LaunchedRealInputProvider {
     #onNetworkDetail;
     #browser;
     #page;
+    /** Pages collecting V8 coverage — see js-coverage.ts. */
+    #covering = new WeakSet();
     constructor(options) {
         this.#driveUrl = options.driveUrl;
         this.#headless = options.headless;
@@ -442,6 +463,10 @@ export class LaunchedRealInputProvider {
         await page.setViewportSize({ width: size.width, height: size.height });
         return true;
     }
+    takeCodeCoverage(_sessionUrl) {
+        const page = this.#livePage();
+        return page === undefined ? Promise.resolve(undefined) : takeJsCoverage(page, this.#covering);
+    }
     /** Apply network-mock rules to the owned page; false before navigate / after dispose. */
     async setMocks(_sessionUrl, rules) {
         const page = this.#livePage();

package/dist/portal/pool/playwright-launcher.d.ts

@@ -25,6 +25,12 @@ export declare function gotoOptions(timeoutMs: number | undefined): {
 export declare function playwrightLauncher(opts?: {
     headless?: boolean;
 }): Launcher;
+/**
+ * Turn Playwright's raw launch error into the one command that fixes it, or undefined when it is
+ * not a missing-browser failure. Shared by the pooled and the drive launch, so `reticle verify` on
+ * a fresh machine gets the same advice as a lease.
+ */
+export declare function chromiumLaunchHint(msg: string): string | undefined;
 /**
  * Resolve the pool's concurrency cap. An explicit RETICLE_MAX_CONTEXTS wins (clamped to
  * [1, hard ceiling]); otherwise scale with the machine but never above the CPU-derived ceiling.

package/dist/portal/pool/playwright-launcher.js

@@ -6,7 +6,7 @@
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
 import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
-import { chromiumLaunchOptions } from '../../chromium-launch-options.js';
+import { launchChromium } from '../../launch-chromium.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
 import { chromiumInstallCommand, chromiumInstallDepsCommand, bundledPlaywrightVersion, } from '../../command/cli/doctor/browser/chromium-hint.js';
@@ -105,27 +105,34 @@ export function playwrightLauncher(opts = {}) {
         // number that actually costs memory and the one that explains a slow machine.
         const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.POOLED);
         try {
-            const browser = wrapBrowser(await chromium.launch(chromiumLaunchOptions(headless)));
+            const browser = wrapBrowser(await launchChromium(chromium, headless));
             settle();
             return browser;
         }
         catch (err) {
             settle(classifyConnectFailure(err));
-            // Turn Playwright's raw "Executable doesn't exist" into the one command that fixes it.
             const msg = err instanceof Error ? err.message : String(err);
-            // Checked FIRST: Playwright's host-requirement validation error also contains
-            // "browserType.launch", so the generic check below would otherwise misdiagnose it as a
-            // missing binary and send the user through a fix that changes nothing.
-            if (/host system is missing dependencies/i.test(msg)) {
-                throw new Error(CHROMIUM_MISSING_DEPS_HINT);
-            }
-            if (/executable doesn.?t exist|playwright install|browsertype\.launch/i.test(msg)) {
-                throw new Error(CHROMIUM_MISSING_HINT);
-            }
-            throw err;
+            const hint = chromiumLaunchHint(msg);
+            throw hint !== undefined ? new Error(hint) : err;
         }
     };
 }
+/**
+ * Turn Playwright's raw launch error into the one command that fixes it, or undefined when it is
+ * not a missing-browser failure. Shared by the pooled and the drive launch, so `reticle verify` on
+ * a fresh machine gets the same advice as a lease.
+ */
+export function chromiumLaunchHint(msg) {
+    // Checked FIRST: Playwright's host-requirement validation error also contains
+    // "browserType.launch", so the generic check below would otherwise misdiagnose it as a
+    // missing binary and send the user through a fix that changes nothing.
+    if (/host system is missing dependencies/i.test(msg))
+        return CHROMIUM_MISSING_DEPS_HINT;
+    if (/executable doesn.?t exist|playwright install|browsertype\.launch/i.test(msg)) {
+        return CHROMIUM_MISSING_HINT;
+    }
+    return undefined;
+}
 const MAX_CONTEXTS_CEILING = 8;
 const MAX_CONTEXTS_FLOOR = 1;
 /**

package/dist/portal/session/dev-server/dev-command.d.ts

@@ -12,8 +12,8 @@
 export interface DevCommand {
     /** The literal shell command, e.g. `pnpm run dev`. */
     command: string;
-    /** The package.json script it runs. */
-    script: string;
+    /** The package.json script it runs. Absent when the command runs a CLI directly (`npx tauri dev`). */
+    script?: string;
     /** The port the script PINS, when it pins one. Absent means the tool picks — never a guess. */
     port?: number;
 }

package/dist/portal/session/dev-server/dev-command.js

@@ -10,6 +10,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { desktopLaunch } from '@reticlehq/init';
 /**
  * Script names checked, in order.
  *
@@ -47,23 +48,26 @@ function pinnedPort(script) {
     const port = Number.parseInt(digits, 10);
     return Number.isSafeInteger(port) ? port : undefined;
 }
-/** The scripts block of a package.json, or an empty one for anything unreadable/unparseable. */
-function readScripts(raw) {
+/** The parsed package.json, or undefined for anything unreadable/unparseable. */
+function readManifest(raw) {
     if (raw === undefined)
-        return {};
+        return undefined;
     try {
-        const parsed = JSON.parse(raw);
-        if (null === parsed || 'object' !== typeof parsed)
-            return {};
-        const scripts = parsed.scripts;
-        if (null === scripts || 'object' !== typeof scripts)
-            return {};
-        return scripts;
+        return JSON.parse(raw);
     }
     catch {
-        return {};
+        return undefined;
     }
 }
+/** The scripts block of a parsed package.json, or an empty one. */
+function scriptsOf(manifest) {
+    if (null === manifest || 'object' !== typeof manifest)
+        return {};
+    const scripts = manifest.scripts;
+    if (null === scripts || 'object' !== typeof scripts)
+        return {};
+    return scripts;
+}
 /**
  * The dev command for the project in `directory`, or undefined when there is not one to be sure of.
  *
@@ -71,9 +75,23 @@ function readScripts(raw) {
  * default disk reader.
  */
 export function detectDevCommand(directory, read = readTextFile) {
-    const scripts = readScripts(read(join(directory, PACKAGE_JSON)));
+    const manifest = readManifest(read(join(directory, PACKAGE_JSON)));
+    const scripts = scriptsOf(manifest);
     const manager = LOCKFILES.find(({ file }) => read(join(directory, file)) !== undefined)?.manager ??
         DEFAULT_PACKAGE_MANAGER;
+    // A desktop shell's `dev` is its renderer's dev server, which no window ever opens onto. init's
+    // rule decides which launcher it is, so the command the daemon hands an agent and the one init
+    // spawns are the same.
+    const desktop = desktopLaunch(manifest);
+    if (desktop !== undefined) {
+        if ('command' in desktop)
+            return { command: desktop.command };
+        const command = `${manager} run ${desktop.script}`;
+        return {
+            command: 0 < desktop.args.length ? `${command} ${desktop.args}` : command,
+            script: desktop.script,
+        };
+    }
     for (const script of DEV_SCRIPTS) {
         const body = scripts[script];
         if ('string' !== typeof body || 0 === body.trim().length)

package/dist/portal/session/dev-server/dev-server-probe.js

@@ -64,6 +64,15 @@ export function classifyPort(port, probe) {
  * accepts v4-mapped connections — so between the two, every ordinary bind is covered.
  */
 export const PROBE_HOSTS = ['127.0.0.1', '::1'];
+/**
+ * The name the probe gives in its Host header, whichever address it dialled.
+ *
+ * Node names the dialled address, so the `::1` probe sent `Host: [::1]:4200`. Angular's SSR dev
+ * server validates Host, answered 400, and printed `ERROR: Bad Request ("http://[::1]:4200/")` into
+ * the user's dev terminal on every sweep, for as long as the daemon ran. The address picks the
+ * family; the header says what a browser on this machine would.
+ */
+const PROBE_HOST_HEADER = 'localhost';
 /**
  * Does this port serve a DOCUMENT — i.e. is it a dev server rather than merely something listening?
  *
@@ -76,7 +85,14 @@ function probeState(port, host) {
         // Whether the SOCKET came up is tracked separately from whether a response did, because that is
         // the whole difference between "nothing is there" and "something is there and still compiling".
         let connected = false;
-        const req = request({ host, port, path: '/', method: 'GET', timeout: HTTP_PROBE_TIMEOUT_MS }, (res) => {
+        const req = request({
+            host,
+            port,
+            path: '/',
+            method: 'GET',
+            timeout: HTTP_PROBE_TIMEOUT_MS,
+            headers: { host: `${PROBE_HOST_HEADER}:${String(port)}` },
+        }, (res) => {
             const answer = looksLikeDevServer(res.statusCode ?? 0, res.headers['content-type']);
             res.resume(); // drain, so the socket closes rather than lingering
             resolve(answer ? PortState.SERVES_DOCUMENT : PortState.CLOSED);

package/dist/portal/session/dev-server/route-status-probe.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What does the route a tab died on answer right now?
+ *
+ * A route that throws server-side tears the page down and the SDK never reconnects, so the daemon
+ * is left with an empty session list and the URL it last saw (#862). The URL alone cannot separate
+ * "the route 500s" from "somebody closed the tab" — one plain GET can, and the daemon is the only
+ * party placed to make it: the page is gone, the agent is inside an MCP call, and the daemon is on
+ * the same machine as the dev server.
+ *
+ * What it refuses to do, because this runs unattended in a diagnostic loop:
+ *   - only loopback hostnames — the daemon is localhost-only and a diagnostic must not reach out;
+ *   - only `http:` — `https:` on localhost means a self-signed certificate, and fetching it with
+ *     verification off would be a posture change for a status code;
+ *   - GET only, redirects not followed, the body never read — the status is the only thing that
+ *     leaves the socket, and it is drained so the connection closes rather than lingers;
+ *   - an error or a timeout is `undefined`, never a status. No fact is better than a wrong one.
+ *
+ * Same shape as its neighbour `dev-server-probe.ts`, which asks a port whether it serves a document; this asks
+ * one exact path what it answers.
+ */
+/** Short on purpose: a dev server that has not answered a route in this long is not going to. */
+export declare const ROUTE_STATUS_TIMEOUT_MS = 2000;
+/** The HTTP status `url` answers a GET with, or undefined when there is no answer to report. */
+export declare function probeRouteStatus(url: string, timeoutMs?: number): Promise<number | undefined>;

package/dist/portal/session/dev-server/route-status-probe.js

@@ -0,0 +1,57 @@
+/**
+ * What does the route a tab died on answer right now?
+ *
+ * A route that throws server-side tears the page down and the SDK never reconnects, so the daemon
+ * is left with an empty session list and the URL it last saw (#862). The URL alone cannot separate
+ * "the route 500s" from "somebody closed the tab" — one plain GET can, and the daemon is the only
+ * party placed to make it: the page is gone, the agent is inside an MCP call, and the daemon is on
+ * the same machine as the dev server.
+ *
+ * What it refuses to do, because this runs unattended in a diagnostic loop:
+ *   - only loopback hostnames — the daemon is localhost-only and a diagnostic must not reach out;
+ *   - only `http:` — `https:` on localhost means a self-signed certificate, and fetching it with
+ *     verification off would be a posture change for a status code;
+ *   - GET only, redirects not followed, the body never read — the status is the only thing that
+ *     leaves the socket, and it is drained so the connection closes rather than lingers;
+ *   - an error or a timeout is `undefined`, never a status. No fact is better than a wrong one.
+ *
+ * Same shape as its neighbour `dev-server-probe.ts`, which asks a port whether it serves a document; this asks
+ * one exact path what it answers.
+ */
+import { request } from 'node:http';
+import { isLoopbackHostname } from '@reticlehq/core';
+/** Short on purpose: a dev server that has not answered a route in this long is not going to. */
+export const ROUTE_STATUS_TIMEOUT_MS = 2_000;
+const HTTP = 'http:';
+/** The HTTP status `url` answers a GET with, or undefined when there is no answer to report. */
+export function probeRouteStatus(url, timeoutMs = ROUTE_STATUS_TIMEOUT_MS) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return Promise.resolve(undefined);
+    }
+    if (parsed.protocol !== HTTP || !isLoopbackHostname(parsed.hostname)) {
+        return Promise.resolve(undefined);
+    }
+    return new Promise((resolve) => {
+        const req = request({
+            host: parsed.hostname,
+            port: parsed.port,
+            path: `${parsed.pathname}${parsed.search}`,
+            method: 'GET',
+            timeout: timeoutMs,
+        }, (res) => {
+            const status = res.statusCode;
+            res.resume(); // drain, so the socket closes rather than lingering
+            resolve(status);
+        });
+        req.once('timeout', () => {
+            req.destroy();
+            resolve(undefined);
+        });
+        req.once('error', () => resolve(undefined));
+        req.end();
+    });
+}

package/dist/portal/session/facts/observed-state.d.ts

@@ -48,6 +48,8 @@ export declare class ObservedState {
     actedRefs(): ReadonlySet<string>;
     /** Every driven control's label, for matching across re-renders. */
     actedLabels(): ReadonlySet<string>;
+    recordProvedLabel(label: string): void;
+    provedLabels(): ReadonlySet<string>;
     /**
      * Record bridge-side sampling as a blind spot.
      *
@@ -58,3 +60,12 @@ export declare class ObservedState {
     noteRateLimited(dropped: number): void;
     blindSpots(): Readonly<Record<string, number>>;
 }
+/**
+ * The snapshot-shaped labels an act reply names its control by: the testid, and `role "name"`.
+ *
+ * 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.
+ */
+export declare function controlLabelsOf(payload: unknown): string[];

package/dist/portal/session/facts/observed-state.js

@@ -105,6 +105,18 @@ export class ObservedState {
     actedLabels() {
         return this.#actedLabels;
     }
+    /**
+     * Controls whose action came back `verified: "yes"` on a declared consequence — the PROVED level
+     * of the coverage ledger. Same label identity as `actedLabels`, so the two compare directly.
+     */
+    #provedLabels = new Set();
+    recordProvedLabel(label) {
+        if (label.length > 0)
+            this.#provedLabels.add(label);
+    }
+    provedLabels() {
+        return this.#provedLabels;
+    }
     /**
      * Record bridge-side sampling as a blind spot.
      *
@@ -119,3 +131,25 @@ export class ObservedState {
         return this.#blindSpots;
     }
 }
+/**
+ * The snapshot-shaped labels an act reply names its control by: the testid, and `role "name"`.
+ *
+ * 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.
+ */
+export function controlLabelsOf(payload) {
+    if (typeof payload !== 'object' || null === payload)
+        return [];
+    const record = payload;
+    const labels = [];
+    const testid = record['testid'];
+    if ('string' === typeof testid && testid.length > 0)
+        labels.push(testid);
+    const role = record['role'];
+    const name = record['name'];
+    if ('string' === typeof role && 'string' === typeof name && role.length > 0 && name.length > 0)
+        labels.push(`${role} "${name}"`);
+    return labels;
+}

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

@@ -91,6 +91,20 @@ export interface NoSessionFacts {
      * already read it; the message did not.
      */
     authRefused?: boolean;
+    /**
+     * The bridge refused the last hello for something OTHER than its token — a protocol number out of
+     * range, or a hello that failed the wire schema outright — and nothing has connected since.
+     *
+     * The same positive evidence as `authRefused`, with a different fix. Without it the daemon had
+     * recorded the refusal and `init` still ended on "the SDK is in the page and never dialled the
+     * bridge", about a page that dialled and was turned away. `reason` follows the `cause — fix`
+     * shape the bridge writes; the page and project are what the refused hello said about itself.
+     */
+    helloRefused?: {
+        reason: string;
+        url?: string;
+        projectId?: string;
+    };
     /**
      * The framework `.reticle.json` declares, when there is one.
      *
@@ -100,6 +114,14 @@ export interface NoSessionFacts {
      * hint the agent reads hours later never mentioned it.
      */
     framework?: string;
+    /**
+     * The project is a desktop shell (Electron, Tauri), read from the project the way `doctor` reads it.
+     *
+     * Its page exists only inside its own window, so every "open the app's URL in a browser" and
+     * every lease offer below is the wrong move there: it loads the renderer without the shell's IPC
+     * bridge or native APIs, which is not the app being verified. Absent means web.
+     */
+    desktop?: boolean;
     /**
      * `.reticle.json` files found OUTSIDE this daemon's directory — a workspace app, a repo root.
      *
@@ -144,6 +166,13 @@ export interface NoSessionFacts {
      * or the ring has forgotten — inventing a URL is worse than the silence this exists to end.
      */
     lastKnownUrl?: string;
+    /**
+     * What a plain GET of `lastKnownUrl` answered, done out of band by the watch after the session
+     * went. The one fact that separates a server error from a closed tab and from an install
+     * problem (#808, option 3). Present only when the fetch got an HTTP status back — a failed or
+     * timed-out fetch is no fact, and this stays absent rather than guessing.
+     */
+    lastKnownStatus?: number;
 }
 /**
  * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session