@reticlehq/server 3.3.0 → 3.5.0

package/dist/memory/project/artifact-root-resolver.js

@@ -34,30 +34,57 @@ function daemonSitsInAProject(daemonRoot) {
         return false;
     }
 }
+/**
+ * Every project this machine knows the directory of: discovered `.reticle.json` files first, then
+ * the user-level registry. Read on each call, since `init` can run in another terminal while the
+ * daemon is up.
+ */
+function knownProjectCandidates() {
+    let registry = emptyProjectRegistry();
+    try {
+        const path = join(homedir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
+        registry = existsSync(path)
+            ? parseProjectRegistry(JSON.parse(readFileSync(path, 'utf8')))
+            : registry;
+    }
+    catch {
+        // A cache that cannot be read is an empty cache, never an error: the daemon still resolves
+        // through discovery, and falls back to its own root exactly as it did before this existed.
+    }
+    let discovery = { found: [], searched: [] };
+    try {
+        discovery = discoverProjectConfigs(process.cwd());
+    }
+    catch {
+        // Same reasoning: a diagnostic search that throws must not take a tool call with it.
+    }
+    return projectCandidatesFrom(discovery, registry);
+}
+/**
+ * The directory of the project a page announced, or undefined when this machine does not know it.
+ *
+ * A daemon is shared: started from `$HOME`, a monorepo root, or another project's MCP client, its
+ * cwd is often not the app that sent the HELLO. The version-skew remedy read `package.json` from
+ * cwd anyway, so it fell back to the generic sensor package and told a Next.js project to install
+ * `@reticlehq/browser` (#1135). This is the same lookup the artifact root uses, keyed by the page's
+ * own project id.
+ */
+export function projectDirectoryFor(projectId) {
+    if (projectId === undefined)
+        return undefined;
+    const directories = new Set(knownProjectCandidates()
+        .filter((candidate) => candidate.projectId === projectId)
+        .map((candidate) => candidate.directory));
+    // Two checkouts declaring one id are refused, as the artifact root refuses them: naming one of
+    // them would read the wrong app's package.json and prescribe its packages to the other.
+    return 1 === directories.size ? [...directories][0] : undefined;
+}
 export function artifactRootResolver(daemonRoot) {
     const daemonIsProject = daemonSitsInAProject(daemonRoot);
     return (projectId, origin) => {
-        let registry = emptyProjectRegistry();
-        try {
-            const path = join(homedir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
-            registry = existsSync(path)
-                ? parseProjectRegistry(JSON.parse(readFileSync(path, 'utf8')))
-                : registry;
-        }
-        catch {
-            // A cache that cannot be read is an empty cache, never an error: the daemon still resolves
-            // through discovery, and falls back to its own root exactly as it did before this existed.
-        }
-        let discovery = { found: [], searched: [] };
-        try {
-            discovery = discoverProjectConfigs(process.cwd());
-        }
-        catch {
-            // Same reasoning: a diagnostic search that throws must not take a tool call with it.
-        }
         const resolved = resolveArtifactRoot({
             projectId,
-            candidates: projectCandidatesFrom(discovery, registry),
+            candidates: knownProjectCandidates(),
             daemonRoot,
         });
         if (resolved.reason === ArtifactRootReason.MATCHED_PROJECT)

package/dist/memory/project/dir/reticle-dir.d.ts

@@ -33,6 +33,8 @@ export interface ReticleDirPaths {
     capsules: string;
     /**.../.reticle/flake.json (per-flow flake ledger) */
     flake: string;
+    /**.../.reticle/coverage.json (app-wide coverage ledger, all six levels) */
+    coverage: string;
     /**.../.reticle/assertion-tiers.json (last-passing assertion tiers; anti-reward-hacking baseline) */
     tiers: string;
 }

package/dist/memory/project/dir/reticle-dir.js

@@ -18,6 +18,7 @@ export function reticleDirPaths(root) {
         ambient: join(root, ReticleDir.AMBIENT_FILE),
         capsules: join(root, ReticleDir.CAPSULES_SUBDIR),
         flake: join(root, ReticleDir.FLAKE_FILE),
+        coverage: join(root, ReticleDir.COVERAGE_FILE),
         tiers: join(root, ReticleDir.TIERS_FILE),
     };
 }

package/dist/memory/project/project-tools.js

@@ -38,7 +38,9 @@ function numericDelta(before, after) {
  * "what's broken vs before" from the cloud. Absent creds / unreachable → undefined (agent stays local).
  */
 async function cloudRegression(deps, sessionId) {
-    const config = resolveCloudConfig(process.env);
+    // The same resolver every caller uses (stored key for a linked repo, else the exported one);
+    // the environment alone only for an embedder that wires no linked-credential port.
+    const config = await (deps.linkedCloud?.() ?? Promise.resolve(resolveCloudConfig(process.env)));
     if (null === config)
         return undefined;
     let projectId;

package/dist/portal/bridge/auth-failure-reason.d.ts

@@ -4,7 +4,7 @@
  * A daemon left running by one project answers the next project's app and rejects it on token, and
  * the SDK printed `bridge refused the connection: authentication failed`. That sends someone to
  * check a token which is perfectly correct — it is simply a DIFFERENT project's token. The two cases
- * need opposite fixes: "your token is wrong" versus "that daemon is not yours, stop it".
+ * need opposite fixes: "your token is wrong" versus "that daemon is not yours, use your own port".
  *
  * The discriminator is EVIDENCE, not derivation. The daemon and the SDK derive project ids by
  * different schemes (the SDK from its Vite root, the daemon from its own cwd), so comparing those

package/dist/portal/bridge/auth-failure-reason.js

@@ -4,7 +4,7 @@
  * A daemon left running by one project answers the next project's app and rejects it on token, and
  * the SDK printed `bridge refused the connection: authentication failed`. That sends someone to
  * check a token which is perfectly correct — it is simply a DIFFERENT project's token. The two cases
- * need opposite fixes: "your token is wrong" versus "that daemon is not yours, stop it".
+ * need opposite fixes: "your token is wrong" versus "that daemon is not yours, use your own port".
  *
  * The discriminator is EVIDENCE, not derivation. The daemon and the SDK derive project ids by
  * different schemes (the SDK from its Vite root, the daemon from its own cwd), so comparing those
@@ -62,7 +62,9 @@ export function authFailureReason(servedProjects, helloProject, helloToken) {
     if (helloProject !== undefined &&
         1 === servedProjects.size &&
         !servedProjects.has(helloProject)) {
-        const reason = `${DIFFERENT_PROJECT_PREFIX} — run \`reticle stop\` and retry`;
+        // Not "stop it": that daemon is serving somebody else's app. This project needs its own port,
+        // which the CLI and the build plugins both read from `.reticle.json`.
+        const reason = `${DIFFERENT_PROJECT_PREFIX} — set a free "port" in .reticle.json, then restart the dev server`;
         return Buffer.byteLength(reason, 'utf8') <= MAX_REASON_BYTES ? reason : PLAIN;
     }
     if (helloToken === undefined || 0 === helloToken.length)

package/dist/portal/bridge/bridge.d.ts

@@ -38,6 +38,14 @@ export declare const WS_CLOSE_REASON: {
      * refusal on this path: nothing about the app is wrong and retrying is the correct response.
      */
     readonly HANDSHAKE_POOL_FULL: string;
+    /**
+     * A page's HELLO failed the wire schema for a reason other than its protocol number — the SDK and
+     * this daemon are different releases whose contracts no longer agree. The socket is still closed
+     * with the short `invalid message` the SDK already prints; this is the sentence the no-session
+     * diagnosis records, because "never dialled the bridge" was what `init` said about a page this
+     * daemon had just turned away. Same `cause — fix` shape as the protocol-skew reasons.
+     */
+    readonly INVALID_HELLO: string;
 };
 interface BridgeOptions {
     port: number;
@@ -58,10 +66,11 @@ interface BridgeOptions {
      */
     server?: http.Server;
     /**
-     * The SDK-upgrade sentence to attach when a HELLO is skewed. Injected so the daemon can name
-     * this project's packages and package manager; tests that omit it get the no-project fallback.
+     * The SDK-upgrade sentence to attach when a HELLO is skewed, for the project that HELLO named.
+     * Injected so the daemon can name that project's packages and package manager; tests that omit
+     * it get the no-project fallback.
      */
-    sdkFix?: () => string;
+    sdkFix?: (projectId?: string) => string;
 }
 /**
  * The browser-facing half of the relay: a localhost WebSocket server. Each connection

package/dist/portal/bridge/bridge.js

@@ -69,6 +69,16 @@ export const WS_CLOSE_REASON = {
         'this dial never got to identify itself. Nothing is wrong with the app; the pool drains on its ' +
         'own and reloading the page reconnects. If it persists, something else on this machine is ' +
         'opening sockets to this port.',
+    /**
+     * A page's HELLO failed the wire schema for a reason other than its protocol number — the SDK and
+     * this daemon are different releases whose contracts no longer agree. The socket is still closed
+     * with the short `invalid message` the SDK already prints; this is the sentence the no-session
+     * diagnosis records, because "never dialled the bridge" was what `init` said about a page this
+     * daemon had just turned away. Same `cause — fix` shape as the protocol-skew reasons.
+     */
+    INVALID_HELLO: "invalid message: the page's hello does not match this daemon's wire contract — put " +
+        '@reticlehq/browser, the build plugin and @reticlehq/server on one release, run `reticle stop`, ' +
+        'then restart the dev server',
 };
 /**
  * A dial turned away at the ORIGIN gate, in words the reader can act on.
@@ -179,6 +189,25 @@ function helloProtocolMismatch(text) {
     }
     return null;
 }
+/**
+ * What a HELLO says about the page it came from, read loosely enough to survive the schema failing.
+ * Null when the message is not a hello at all — only an SDK sends one, so only then is a refusal
+ * evidence about an app.
+ */
+function peekHelloPage(text) {
+    try {
+        const json = JSON.parse(text);
+        if (json.kind !== MessageKind.HELLO)
+            return null;
+        return {
+            ...('string' === typeof json.url ? { url: json.url } : {}),
+            ...('string' === typeof json.projectId ? { projectId: json.projectId } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
 /** Normalize ws RawData (string | Buffer | Buffer[] | ArrayBuffer) into a UTF-8 string. */
 function rawToString(raw) {
     if ('string' === typeof raw)
@@ -436,10 +465,19 @@ export class Bridge {
                         // Told to the AGENT too, not only to the SDK that is about to stop retrying. Without this
                         // the next tool call answers "no browser session connected", which reads as "no app is
                         // running" — so an SDK too old to connect is invisible.
-                        this.sessions.noteClosure(reason, this.#clock());
+                        this.sessions.noteClosure(reason, this.#clock(), peekHelloPage(text) ?? {});
                         socket.close(WS_CLOSE.PROTOCOL_MISMATCH[0], reason);
                         return;
                     }
+                    // Recorded only for a HELLO on a socket that has none yet: that is a page being turned
+                    // away, and it used to leave no trace, so `init` reported "never dialled the bridge" about
+                    // a page this daemon had just refused. A malformed frame on a live session is a different
+                    // failure and says nothing about whether the app can connect.
+                    const refused = undefined === session ? peekHelloPage(text) : null;
+                    if (null !== refused) {
+                        log('hello_invalid', { ...refused });
+                        this.sessions.noteClosure(WS_CLOSE_REASON.INVALID_HELLO, this.#clock(), refused);
+                    }
                     socket.close(...WS_CLOSE.INVALID_MESSAGE);
                     return;
                 }
@@ -498,7 +536,10 @@ export class Bridge {
                             presented: parsed.token !== undefined && 0 < parsed.token.length,
                             tokenSource: this.#tokenSource,
                         });
-                        this.sessions.noteClosure(reason, this.#clock());
+                        this.sessions.noteClosure(reason, this.#clock(), {
+                            url: parsed.url,
+                            ...(parsed.projectId === undefined ? {} : { projectId: parsed.projectId }),
+                        });
                         socket.close(WS_CLOSE.AUTH_FAILED[0], reason);
                         return;
                     }
@@ -567,6 +608,9 @@ export class Bridge {
                     // The daemon is the single judge of skew, and HELLO is where the page announces itself.
                     // Reported on the session (reticle_sessions) AND queued for the next tool result, because an
                     // agent driving a flow never calls reticle_sessions and would never learn.
+                    // Read only if the page IS skewed: the fix reads the project's package.json and lockfile,
+                    // and a compatible page (nearly every HELLO) should not pay for that on connect.
+                    const fixForThisProject = () => this.#sdkFix(parsed.projectId);
                     const skew = describeSkew({
                         what: 'the page',
                         version: parsed.sdkVersion,
@@ -577,7 +621,9 @@ export class Bridge {
                         ...(parsed.contractParts === undefined
                             ? {}
                             : { contractParts: parsed.contractParts }),
-                        fix: this.#sdkFix(),
+                        get fix() {
+                            return fixForThisProject();
+                        },
                     }, {
                         version: SERVER_VERSION,
                         contract: CONTRACT_FINGERPRINT,

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

@@ -0,0 +1,25 @@
+import type { Page } from 'playwright';
+/**
+ * V8 JS coverage on a page Reticle drives — the raw half of "what of the app ever ran".
+ *
+ * Started once per page with `resetOnNavigation: false`, so a reload keeps counting instead of
+ * starting over. A take stops and immediately restarts: the counts it returns are since the last
+ * take, and the reader folds them as a union (see features/exhaust/code-coverage.ts).
+ *
+ * Chromium only. Anything else — or a page that closed — answers false/undefined rather than
+ * throwing: coverage is an addition to a drive, never a reason for one to fail.
+ */
+/** One script's coverage — the shape `stopJSCoverage` returns, narrowed to what is read. */
+export interface ScriptCoverage {
+    url: string;
+    functions: {
+        functionName: string;
+        ranges: {
+            startOffset: number;
+            endOffset: number;
+            count: number;
+        }[];
+    }[];
+}
+export declare function startJsCoverage(page: Page, covering: WeakSet<Page>): Promise<boolean>;
+export declare function takeJsCoverage(page: Page, covering: WeakSet<Page>): Promise<ScriptCoverage[] | undefined>;

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/input/viewport-tools.js

@@ -34,8 +34,8 @@ export const VIEWPORT_TOOLS = [
             recommendation: z.string().optional(),
         },
         handler: async (deps, args) => {
-            const width = clampDim(args['width']);
-            const height = clampDim(args['height']);
+            const width = clampDim('width', args['width']);
+            const height = clampDim('height', args['height']);
             const session = deps.sessions.resolve(asString(args['sessionId']));
             const provider = viewportProvider(deps);
             if (provider !== undefined) {
@@ -65,8 +65,18 @@ export const VIEWPORT_TOOLS = [
         },
     },
 ];
-/** Clamp a requested dimension into [MIN_DIM, MAX_DIM]; a missing/NaN value falls back to MIN_DIM. */
-function clampDim(value) {
-    const n = 'number' === typeof value && Number.isFinite(value) ? Math.round(value) : MIN_DIM;
-    return Math.max(MIN_DIM, Math.min(n, MAX_DIM));
+/**
+ * Clamp a requested dimension into [MIN_DIM, MAX_DIM]; a missing value falls back to MIN_DIM.
+ *
+ * A value that is PRESENT but not a finite number is refused, not read as missing: a client that
+ * sent `"1440"` meant 1440, and answering with a 64px page it never asked for made every later
+ * snapshot, click and screenshot on that page read as broken (#1118).
+ */
+function clampDim(key, value) {
+    if (value === undefined)
+        return MIN_DIM;
+    if ('number' !== typeof value || !Number.isFinite(value)) {
+        throw new Error(`${ReticleTool.VIEWPORT}: \`${key}\` must be a number of CSS px, got ${JSON.stringify(value)} — NOT applied`);
+    }
+    return Math.max(MIN_DIM, Math.min(Math.round(value), MAX_DIM));
 }

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)