@reticlehq/server 3.8.2 → 3.10.0

package/dist/surface/tools/lease-coverage-tools.js

@@ -0,0 +1,128 @@
+/**
+ * `reticle_lease { action: "coverage" }` — which code of a leased page ran, as the JS engine counted it.
+ *
+ * A caller outside the app cannot see which branches a drive reached. The JS engine can: each script's block
+ * ranges carry a count. This reads them from the lease's own Playwright page, the way
+ * `reticle_network_mock` reaches it, so it needs no change to the app.
+ *
+ * A take returns what ran since the previous take, and coverage keeps running across a reload.
+ * Start it on acquire (`jsCoverage: true`) to see the code that runs while the page loads; a start
+ * after the load misses it.
+ */
+import { z } from 'zod';
+import { ReticleTool, asNumber, asString } from '@reticlehq/core';
+import { sessionIdShape } from './tool-kit.js';
+export const LeaseCoverageMode = { START: 'start', TAKE: 'take' };
+/** Ranges one take returns when the caller sets no cap. */
+export const DEFAULT_MAX_COVERAGE_RANGES = 20_000;
+const MAX_COVERAGE_RANGES = 200_000;
+const NOT_A_LEASE = 'reticle_lease { action: "coverage" } reads a leased tab only. Acquire one with reticle_lease { action: "acquire", url, jsCoverage: true }, then pass its sessionId.';
+const CANNOT_MEASURE = 'This leased page cannot measure JS coverage. Coverage needs Chromium, and a page that is still open.';
+const WAS_NOT_RUNNING = 'Coverage was not running, so this take holds nothing. It runs now: do the work, then take again. To see the code that runs while the page loads, acquire with jsCoverage: true.';
+/**
+ * Flatten each script's functions into one range list, keep the scripts `urlContains` names, and
+ * stop at `maxRanges`. What the cap drops is counted in `truncated`, beside the value.
+ */
+export function flattenCoverage(entries, maxRanges, urlContains) {
+    const kept = entries.filter((e) => urlContains === undefined || e.url.includes(urlContains));
+    const scripts = [];
+    let rangeCount = 0;
+    let droppedRanges = 0;
+    let droppedScripts = 0;
+    for (const entry of kept) {
+        const ranges = entry.functions.flatMap((f) => f.ranges);
+        const room = maxRanges - rangeCount;
+        if (room <= 0 && 0 < ranges.length) {
+            droppedScripts += 1;
+            droppedRanges += ranges.length;
+            continue;
+        }
+        const taken = ranges
+            .slice(0, Math.max(0, room))
+            .map(({ startOffset, endOffset, count }) => ({ startOffset, endOffset, count }));
+        droppedRanges += ranges.length - taken.length;
+        rangeCount += taken.length;
+        scripts.push({ url: entry.url, ranges: taken });
+    }
+    const filteredOut = entries.length - kept.length;
+    return {
+        scripts,
+        scriptCount: scripts.length,
+        rangeCount,
+        ...(0 < filteredOut ? { filteredOut } : {}),
+        ...(0 < droppedRanges
+            ? { truncated: { scripts: droppedScripts, ranges: droppedRanges, maxRanges } }
+            : {}),
+    };
+}
+/** The acquire argument that starts coverage before the page's first script. */
+export const LEASE_JS_COVERAGE_ARG = z
+    .boolean()
+    .optional()
+    .describe('Start JS coverage before the page runs its first script, so reticle_lease { action: "coverage" } also counts the code that runs while the page loads.');
+export const LEASE_COVERAGE_TOOL = {
+    name: ReticleTool.LEASE_COVERAGE,
+    description: 'JS coverage of a leased tab: which code ran. { mode: "start" } starts it; { mode: "take" } (the default) returns, for each script, its url and block ranges { startOffset, endOffset, count } since the previous take. A count of 0 is code that did not run. Acquire with jsCoverage: true to include the code that runs while the page loads. Use urlContains to keep only your own scripts; a take that hits maxRanges says what it dropped in `truncated`.',
+    example: { mode: 'take', urlContains: '/src/' },
+    inputSchema: {
+        mode: z
+            .enum([LeaseCoverageMode.START, LeaseCoverageMode.TAKE])
+            .optional()
+            .describe('"start" starts coverage; "take" (default) returns what ran since the previous take.'),
+        urlContains: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('Keep only the scripts whose url contains this text, for example "/src/".'),
+        maxRanges: z
+            .number()
+            .int()
+            .min(1)
+            .max(MAX_COVERAGE_RANGES)
+            .optional()
+            .describe(`The most ranges one take returns. Default ${String(DEFAULT_MAX_COVERAGE_RANGES)}.`),
+        ...sessionIdShape,
+    },
+    outputSchema: {
+        running: z.boolean().describe('Whether coverage runs on the page after this call.'),
+        scripts: z
+            .array(z.object({
+            url: z.string(),
+            ranges: z.array(z.object({ startOffset: z.number(), endOffset: z.number(), count: z.number() })),
+        }))
+            .optional(),
+        scriptCount: z.number().optional(),
+        rangeCount: z.number().optional(),
+        filteredOut: z
+            .number()
+            .optional()
+            .describe('Scripts left out because their url did not contain urlContains.'),
+        truncated: z
+            .object({ scripts: z.number(), ranges: z.number(), maxRanges: z.number() })
+            .optional()
+            .describe('Present when the take hit maxRanges: the scripts and ranges it dropped. Absent means nothing was dropped.'),
+        hint: z.string().optional(),
+    },
+    handler: async (deps, args) => {
+        const session = deps.sessions.resolve(asString(args['sessionId']));
+        const coverage = deps.pool?.coverageOf(session.id);
+        if (coverage === undefined) {
+            throw new Error(NOT_A_LEASE);
+        }
+        if (LeaseCoverageMode.START === args['mode']) {
+            if (!(await coverage.start())) {
+                throw new Error(CANNOT_MEASURE);
+            }
+            return { running: true };
+        }
+        const entries = await coverage.take();
+        if (entries === undefined) {
+            if (!(await coverage.start())) {
+                throw new Error(CANNOT_MEASURE);
+            }
+            return { running: true, scripts: [], scriptCount: 0, rangeCount: 0, hint: WAS_NOT_RUNNING };
+        }
+        const maxRanges = asNumber(args['maxRanges']) ?? DEFAULT_MAX_COVERAGE_RANGES;
+        return { running: true, ...flattenCoverage(entries, maxRanges, asString(args['urlContains'])) };
+    },
+};

package/dist/surface/tools/lease-hint.d.ts

@@ -17,7 +17,8 @@
  * So: rank by what the daemon actually knows, and fall back to the differential only when it knows
  * nothing. A cause we hold positive evidence against is not printed at all.
  */
-import type { LeaseReaderFailure } from './lease-readiness.js';
+import { LeaseNotReadyReason } from '@reticlehq/core';
+import { HeldLeaseReload, type LeaseReaderFailure } from './lease-readiness.js';
 /** What the daemon can say for certain at the moment a lease comes back unconnected. */
 export interface LeaseEvidence {
     /** A dial WAS made and turned away, with the reason. The only certain cause there is. */
@@ -56,6 +57,13 @@ export interface LeaseEvidence {
      */
     dialledUrl?: string;
 }
+/**
+ * The last sentence of every not-connected hint. It is true for an MCP caller, which keeps the
+ * lease. The CLI releases the lease itself, and puts `LEASE_RELEASED_SENTENCE` in its place.
+ */
+export declare const LEASE_KEPT_SENTENCE = "The tab stays leased. Release it with reticle_lease{action:\"release\"}.";
+/** The sentence for a lease that is already released. */
+export declare const LEASE_RELEASED_SENTENCE = "The lease is released.";
 export declare function leaseNotConnectedHint(url: string, port: number, evidence?: LeaseEvidence): string;
 /**
  * The leased page was still loading when the wait ran out, so nothing has failed yet: a slow first
@@ -65,3 +73,36 @@ export declare function leaseNotConnectedHint(url: string, port: number, evidenc
 export declare function leaseStillLoadingHint(url: string, waitedMs: number): string;
 /** The hint for a lease whose zero-install reader did not run (#1701). The lease is already released. */
 export declare function leaseReaderFailedHint(url: string, failure: LeaseReaderFailure): string;
+/** What `reticle_lease` answers for a held lease that it loaded again and that did not connect. */
+export interface KeptLeaseAnswer {
+    sessionId: string;
+    url: string;
+    ready: false;
+    notReadyReason: LeaseNotReadyReason;
+    reused: true;
+    expiresInMs: number;
+    leased: number;
+    queued: number;
+    hint: string;
+}
+/**
+ * The answer for a held lease that is kept although its page did not connect (#1924). The tab is
+ * kept, because its context holds the cookies: a new context starts signed out. `reload` says
+ * whether its page loaded again; `cause` is why it did not connect, or why it did not load.
+ */
+export declare function keptLeaseAnswer(lease: {
+    sessionId: string;
+    origin: string;
+    url: string;
+    reload: HeldLeaseReload;
+}, pool: {
+    leaseTtlMs(): number;
+    activeCount(): number;
+    queuedCount(): number;
+}, cause: string): KeptLeaseAnswer;
+/**
+ * Why a held lease's page did not load again, said from what the daemon can check: whether
+ * anything accepts a connection on the page's port. Only asked of a loopback URL, where the probe
+ * reaches the same server the browser does.
+ */
+export declare function notLoadedCause(url: string, portAccepts: ((port: number) => Promise<boolean>) | undefined): Promise<string>;

package/dist/surface/tools/lease-hint.js

@@ -18,6 +18,7 @@
  * nothing. A cause we hold positive evidence against is not printed at all.
  */
 import { isLoopbackHostname, LeaseNotReadyReason } from '@reticlehq/core';
+import { HeldLeaseReload } from './lease-readiness.js';
 import { INIT_COMMAND } from '../../portal/session/no-session-next-action.js';
 const NUXT = 'nuxt';
 const PORT_DIFFERENTIAL = "The usual cause is a PORT MISMATCH: the app's SDK connects to the port it was BUILT with, so a " +
@@ -37,7 +38,14 @@ const REAL_CAUSES = 'Causes that produce exactly this and are NOT a port problem
 const NUXT_FIRST = 'This project is Nuxt: the most likely cause by a distance is a dev server that predates the ' +
     'Reticle plugin, because Nuxt does NOT register a newly added plugin on HMR. Restart `nuxt dev` ' +
     'and re-acquire before investigating anything else.';
-const RELEASE = 'The tab stays leased either way — release it with reticle_lease{action:"release"}.';
+/**
+ * The last sentence of every not-connected hint. It is true for an MCP caller, which keeps the
+ * lease. The CLI releases the lease itself, and puts `LEASE_RELEASED_SENTENCE` in its place.
+ */
+export const LEASE_KEPT_SENTENCE = 'The tab stays leased. Release it with reticle_lease{action:"release"}.';
+const RELEASE = LEASE_KEPT_SENTENCE;
+/** The sentence for a lease that is already released. */
+export const LEASE_RELEASED_SENTENCE = 'The lease is released.';
 const PRODUCTION_STUB = ' If this is a production build (`vite build`, `next build`, `next start`, or a deployed site), it strips ' +
     'Reticle or replaces it with an inert stub by design; point the lease at the dev server instead.';
 function isRemoteUrl(url) {
@@ -168,8 +176,49 @@ export function leaseStillLoadingHint(url, waitedMs) {
 /** The hint for a lease whose zero-install reader did not run (#1701). The lease is already released. */
 export function leaseReaderFailedHint(url, failure) {
     return failure.reason === LeaseNotReadyReason.NOT_HTML_DOCUMENT
-        ? `${url} is not an HTML page, so no SDK can connect to it. The lease is released. ` +
+        ? `${url} is not an HTML page, so no SDK can connect to it. ${LEASE_RELEASED_SENTENCE} ` +
             'Acquire an HTML page of the app instead.'
-        : `The zero-install reader failed on ${url}: ${failure.cause}. The lease is released. ` +
+        : `The zero-install reader failed on ${url}: ${failure.cause}. ${LEASE_RELEASED_SENTENCE} ` +
             'If the tab closed during setup, acquire again.';
 }
+/**
+ * The answer for a held lease that is kept although its page did not connect (#1924). The tab is
+ * kept, because its context holds the cookies: a new context starts signed out. `reload` says
+ * whether its page loaded again; `cause` is why it did not connect, or why it did not load.
+ */
+export function keptLeaseAnswer(lease, pool, cause) {
+    const reloaded = lease.reload === HeldLeaseReload.RELOADED;
+    const what = reloaded
+        ? 'Acquire loaded its page again, but the page did not connect.'
+        : `Acquire could not load ${lease.url} in it again: ${cause}`;
+    return {
+        sessionId: lease.sessionId,
+        url: lease.url,
+        ready: false,
+        notReadyReason: LeaseNotReadyReason.SDK_NEVER_DIALLED,
+        reused: true,
+        expiresInMs: pool.leaseTtlMs(),
+        leased: pool.activeCount(),
+        queued: pool.queuedCount(),
+        hint: `You already hold a lease on ${lease.origin}: ${lease.sessionId}. ${what} The tab and its ` +
+            'context are kept, so its cookies and sign-in are kept. A new context has no cookies: ' +
+            'release this lease first only if you want one, and pass seedStorage to start it signed in.' +
+            (reloaded ? ` ${cause}` : ' Acquire again when the app answers.'),
+    };
+}
+/**
+ * Why a held lease's page did not load again, said from what the daemon can check: whether
+ * anything accepts a connection on the page's port. Only asked of a loopback URL, where the probe
+ * reaches the same server the browser does.
+ */
+export async function notLoadedCause(url, portAccepts) {
+    const target = URL.canParse(url) ? new URL(url) : undefined;
+    if (portAccepts === undefined || target === undefined || !isLoopbackHostname(target.hostname)) {
+        return 'the page did not load. The app may be restarting.';
+    }
+    const defaultPort = 'https:' === target.protocol ? '443' : '80';
+    const port = '' === target.port ? defaultPort : target.port;
+    return (await portAccepts(Number(port)).catch(() => false))
+        ? `the server on port ${port} accepted the connection, but the page did not finish loading. It may still be compiling.`
+        : `nothing accepts connections on port ${port}. The app may be restarting.`;
+}

package/dist/surface/tools/lease-readiness.d.ts

@@ -43,6 +43,27 @@ export declare function notReadyReason(answered: boolean, session: unknown, fail
  * failure than the one being fixed.
  */
 export declare function probeLeaseAlive(session: ProbeableSession | undefined, timeoutMs?: number): Promise<boolean>;
+/**
+ * The longest `reticle_lease { action: "acquire" }` waits for its tab to be ready, when the caller
+ * gives no `timeout_ms`. It is the longest wait before this bound existed: the connect wait, the
+ * wait after the reader, and the loading grace rounds. So no acquire that was ready before is now
+ * refused.
+ */
+export declare const LEASE_READY_TIMEOUT_MS: number;
+/**
+ * A connect wait for `connectOrInject` that ends at the deadline. Each wait is one connect wait at
+ * most, so the reader still goes in at the same time. A wait that starts after the deadline looks
+ * once and does not sleep.
+ */
+export declare function connectWaitUntil(deadline: number, now: () => number, sleeper?: (ms: number) => Promise<void>): (isConnected: () => boolean) => Promise<boolean>;
+/**
+ * Wait until the leased tab is registered, answers a probe and is visible, or the deadline passes.
+ *
+ * A row in the sessions map is not proof that the next call works (#1650): the tab can be attached
+ * and answer nothing. So `ready` waits for a reply. Returns the reason at the deadline, or
+ * `undefined` when the tab is ready. It always looks once, also when the deadline has passed.
+ */
+export declare function awaitLeaseAnswering(registered: () => ProbeableSession | undefined, deadline: number, now: () => number, sleeper?: (ms: number) => Promise<void>): Promise<LeaseNotReadyReason | undefined>;
 /**
  * Poll until the leased tab's SDK has actually registered on the bridge, so the sessionId we return
  * is immediately usable (the page navigates first, then connects a moment later — without this wait
@@ -90,4 +111,30 @@ export declare function moveReusedLease(tabUrl: () => string | undefined, reques
     url: string;
     arrived: boolean;
 } | undefined>;
+/** What loading a held lease's tab again found. */
+export declare const HeldLeaseReload: {
+    /** Its tab had already registered, so nothing was loaded again. */
+    readonly REGISTERED: "registered";
+    /** The page loaded again. Its SDK may or may not have dialled in since. */
+    readonly RELOADED: "reloaded";
+    /** The page is still open, but it did not load: the server did not answer, or it timed out. */
+    readonly NOT_LOADED: "not-loaded";
+    /** The page is closed, or its context is gone. Nothing is left to keep. */
+    readonly GONE: "gone";
+};
+export type HeldLeaseReload = (typeof HeldLeaseReload)[keyof typeof HeldLeaseReload];
+/**
+ * Load a held lease's tab again in its own context, and wait for its SDK to dial in (#1924).
+ *
+ * A held lease whose tab never registered used to be released, and a new context minted. That
+ * context has no cookies, so a tab the agent had signed in to was closed and replaced by a
+ * signed-out one, and the retry could not get the sign-in back. The context is the sign-in, so the
+ * retry keeps it and only loads the page again. The reader the first acquire injected is an init
+ * script of that page, so it runs again on the new document by itself.
+ *
+ * A navigation that fails is not a closed tab: a dev server that restarts refuses the connection
+ * for a moment, and the context with its cookies is still there. `isOpen` asks the page something,
+ * which tells the two apart. A tab that has registered already is left alone.
+ */
+export declare function reconnectHeldLease(goto: (timeoutMs: number) => Promise<boolean>, isOpen: () => Promise<boolean>, isLoading: () => Promise<boolean>, isRegistered: () => boolean, deadline: number, now: () => number): Promise<HeldLeaseReload>;
 export {};

package/dist/surface/tools/lease-readiness.js

@@ -6,6 +6,7 @@
  */
 import { LeaseNotReadyReason, ReticleCommand, RETICLE_URL_PARAM } from '@reticlehq/core';
 import { NotHtmlDocumentError } from '../../portal/pool/zero-install.js';
+import { waitForReconnect } from '../../portal/session/session-reconnect.js';
 /**
  * How long a liveness probe waits for the tab to say anything at all.
  *
@@ -74,6 +75,52 @@ const LEASE_READY_POLL_MS = 100;
 /** Extra readiness waits allowed while the leased page is still loading (each one is ~10 s). */
 const LEASE_LOADING_GRACE_ROUNDS = 3;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** One connect wait: how long a tab gets to dial in before the zero-install reader goes in. */
+const LEASE_CONNECT_WAIT_MS = LEASE_READY_ATTEMPTS * LEASE_READY_POLL_MS;
+/**
+ * The longest `reticle_lease { action: "acquire" }` waits for its tab to be ready, when the caller
+ * gives no `timeout_ms`. It is the longest wait before this bound existed: the connect wait, the
+ * wait after the reader, and the loading grace rounds. So no acquire that was ready before is now
+ * refused.
+ */
+export const LEASE_READY_TIMEOUT_MS = LEASE_CONNECT_WAIT_MS * (2 + LEASE_LOADING_GRACE_ROUNDS);
+/** `waitForReconnect` waits for `current` to differ from `previous`: these two always differ. */
+const NOT_REGISTERED = {};
+const REGISTERED = {};
+/**
+ * A connect wait for `connectOrInject` that ends at the deadline. Each wait is one connect wait at
+ * most, so the reader still goes in at the same time. A wait that starts after the deadline looks
+ * once and does not sleep.
+ */
+export function connectWaitUntil(deadline, now, sleeper = sleep) {
+    return (isConnected) => waitForReconnect({
+        current: () => (isConnected() ? REGISTERED : undefined),
+        previous: NOT_REGISTERED,
+        timeoutMs: Math.min(LEASE_CONNECT_WAIT_MS, Math.max(0, deadline - now())),
+        now,
+        sleep: sleeper,
+        pollMs: LEASE_READY_POLL_MS,
+    });
+}
+/**
+ * Wait until the leased tab is registered, answers a probe and is visible, or the deadline passes.
+ *
+ * A row in the sessions map is not proof that the next call works (#1650): the tab can be attached
+ * and answer nothing. So `ready` waits for a reply. Returns the reason at the deadline, or
+ * `undefined` when the tab is ready. It always looks once, also when the deadline has passed.
+ */
+export async function awaitLeaseAnswering(registered, deadline, now, sleeper = sleep) {
+    for (;;) {
+        const session = registered();
+        const reason = session === undefined
+            ? LeaseNotReadyReason.SDK_STOPPED_ANSWERING
+            : notReadyReason(await probeLeaseAlive(session), session);
+        if (reason === undefined || now() >= deadline) {
+            return reason;
+        }
+        await sleeper(LEASE_READY_POLL_MS);
+    }
+}
 /**
  * Poll until the leased tab's SDK has actually registered on the bridge, so the sessionId we return
  * is immediately usable (the page navigates first, then connects a moment later — without this wait
@@ -203,3 +250,82 @@ export async function moveReusedLease(tabUrl, requested, goto, now) {
     }
     return { navigated: true, url: requested, arrived: pageOf(tabUrl()) === target };
 }
+/** What loading a held lease's tab again found. */
+export const HeldLeaseReload = {
+    /** Its tab had already registered, so nothing was loaded again. */
+    REGISTERED: 'registered',
+    /** The page loaded again. Its SDK may or may not have dialled in since. */
+    RELOADED: 'reloaded',
+    /** The page is still open, but it did not load: the server did not answer, or it timed out. */
+    NOT_LOADED: 'not-loaded',
+    /** The page is closed, or its context is gone. Nothing is left to keep. */
+    GONE: 'gone',
+};
+/**
+ * Load a held lease's tab again in its own context, and wait for its SDK to dial in (#1924).
+ *
+ * A held lease whose tab never registered used to be released, and a new context minted. That
+ * context has no cookies, so a tab the agent had signed in to was closed and replaced by a
+ * signed-out one, and the retry could not get the sign-in back. The context is the sign-in, so the
+ * retry keeps it and only loads the page again. The reader the first acquire injected is an init
+ * script of that page, so it runs again on the new document by itself.
+ *
+ * A navigation that fails is not a closed tab: a dev server that restarts refuses the connection
+ * for a moment, and the context with its cookies is still there. `isOpen` asks the page something,
+ * which tells the two apart. A tab that has registered already is left alone.
+ */
+export async function reconnectHeldLease(goto, isOpen, isLoading, isRegistered, deadline, now) {
+    if (isRegistered()) {
+        return HeldLeaseReload.REGISTERED;
+    }
+    // Bounded by the acquire's own deadline. Playwright reads a timeout of 0 as "none", so at least
+    // 1 ms; and raced too, because a frozen page can hold the navigation past its own timeout.
+    const budget = Math.max(1, deadline - now());
+    const went = await answerWithin(Promise.resolve(budget).then(goto), budget + HELD_PAGE_ANSWER_MS, false);
+    if (!went) {
+        return (await pageStillOpen(isOpen)) ? HeldLeaseReload.NOT_LOADED : HeldLeaseReload.GONE;
+    }
+    const loading = () => answerWithin(isLoading(), HELD_PAGE_ANSWER_MS, false);
+    await connectOrInject({ isLoading: loading }, isRegistered, connectWaitUntil(deadline, now));
+    return HeldLeaseReload.RELOADED;
+}
+/**
+ * How long one question to a held page may take. A page that answers does so in milliseconds; a
+ * frozen one (a script in an endless loop) never does, and must not hold the acquire with it.
+ */
+const HELD_PAGE_ANSWER_MS = 250;
+/** `work`'s answer, or `fallback` when it rejects or has not answered within `ms`. */
+async function answerWithin(work, ms, fallback) {
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            resolve(fallback);
+        }, ms);
+    });
+    try {
+        return await Promise.race([work.catch(() => fallback), late]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** How many times a page whose navigation failed is asked whether it is still there. */
+const OPEN_PROBE_ATTEMPTS = 3;
+/**
+ * Whether a page still answers, after a navigation on it failed.
+ *
+ * Asked more than once, because the first question right after a failed navigation is often lost
+ * ("Execution context was destroyed") on a page that is still open, and the next one is answered.
+ * A closed page, or a page whose context is closed, refuses every time. A frozen page never answers,
+ * so each question is bounded, and it reads as gone.
+ */
+async function pageStillOpen(isOpen) {
+    for (let attempt = 0; attempt < OPEN_PROBE_ATTEMPTS; attempt++) {
+        const asked = Promise.resolve().then(isOpen);
+        if (await answerWithin(asked, HELD_PAGE_ANSWER_MS, false)) {
+            return true;
+        }
+        await sleep(LEASE_READY_POLL_MS);
+    }
+    return false;
+}

package/dist/surface/tools/lease-seed.d.ts

@@ -24,6 +24,11 @@ export declare const NAV_CERT_REFUSED: string;
 export declare const NAV_FAILED_QUESTION = "is the app running there?";
 /** What a lease navigation that ran out of time tells the caller to do. */
 export declare const NAV_TIMEOUT_ADVICE: string;
+/**
+ * What a lease navigation that ran out of time tells the caller when the server accepted the
+ * connection: it is running and most likely compiling the route, so starting it again is wrong (#2005).
+ */
+export declare const NAV_COMPILING_ADVICE: string;
 /**
  * The sentence for a lease whose first navigation failed.
  *
@@ -35,7 +40,17 @@ export declare const NAV_TIMEOUT_ADVICE: string;
  * hunting for a dev server that is up instead of retrying, so the timeout sentence names both
  * cases and leads with the retry.
  */
-export declare function navFailureMessage(url: string, err: unknown, seed?: SeedStorage): string;
+export declare function navFailureMessage(url: string, err: unknown, seed?: SeedStorage, serverAccepted?: boolean): string;
+/**
+ * Whether the server behind a timed-out lease navigation accepted a connection.
+ *
+ * Only asked after a timeout and only of a loopback URL: the port probe reaches `localhost`, so a
+ * remote host would be answered by whatever listens locally on the same port. Never rejects; any
+ * doubt is `false`, which keeps the generic timeout advice.
+ */
+export declare function serverAcceptedAfterTimeout(url: string, err: unknown, seed: SeedStorage | undefined, portAccepts: ((port: number) => Promise<boolean>) | undefined): Promise<boolean>;
+/** Whether a path is a sign-in page, by its name: `/login`, `/signin`, `/auth/login` and similar. */
+export declare const isAuthPath: (pathname: string) => boolean;
 /**
  * Determine if a required seedStorage application precondition failed.
  *

package/dist/surface/tools/lease-seed.js

@@ -2,7 +2,7 @@
  * Seeded storage for a lease, and the errors a lease's navigation throws: what a caller may see of
  * them without seeing the secrets it seeded. Split from lease-tools.ts, which crossed the line cap.
  */
-import { REDACTED_VALUE, scrubKnownSecrets } from '@reticlehq/core';
+import { isLoopbackHostname, REDACTED_VALUE, scrubKnownSecrets, } from '@reticlehq/core';
 function redactExactValue(text, value) {
     if (0 === value.length)
         return text;
@@ -95,6 +95,12 @@ export const NAV_FAILED_QUESTION = 'is the app running there?';
 /** What a lease navigation that ran out of time tells the caller to do. */
 export const NAV_TIMEOUT_ADVICE = 'If the app is running, a dev server compiling a route for the first time can take longer than ' +
     'that: retry the acquire. If it is not running, start it first.';
+/**
+ * What a lease navigation that ran out of time tells the caller when the server accepted the
+ * connection: it is running and most likely compiling the route, so starting it again is wrong (#2005).
+ */
+export const NAV_COMPILING_ADVICE = 'The server accepted the connection, so it is running and is probably still compiling this ' +
+    'route: wait a few seconds, then acquire the lease again. Do not start another dev server.';
 /** Lead of the timeout sentence, before the budget ("within 30 s", or "in time" when unknown). */
 const NAV_TIMEOUT_LEAD = 'the page did not finish loading';
 const NAV_TIMEOUT_UNKNOWN_BUDGET = 'in time';
@@ -111,7 +117,7 @@ const PLAYWRIGHT_TIMEOUT = /Timeout (\d+)ms exceeded/;
  * hunting for a dev server that is up instead of retrying, so the timeout sentence names both
  * cases and leads with the retry.
  */
-export function navFailureMessage(url, err, seed) {
+export function navFailureMessage(url, err, seed, serverAccepted = false) {
     const reason = cleanNavError(err, seed);
     // A certificate the browser refused is not an app that is down: the server answered, with a cert
     // no CA here vouches for (a self-signed or mkcert dev certificate). Asking "is the app running?"
@@ -125,8 +131,36 @@ export function navFailureMessage(url, err, seed) {
     const within = budgetMs === undefined
         ? NAV_TIMEOUT_UNKNOWN_BUDGET
         : `within ${String(Number(budgetMs) / 1000)} s`;
-    return `could not open ${url} — ${NAV_TIMEOUT_LEAD} ${within} (${reason}). ${NAV_TIMEOUT_ADVICE}`;
+    const advice = serverAccepted ? NAV_COMPILING_ADVICE : NAV_TIMEOUT_ADVICE;
+    return `could not open ${url} — ${NAV_TIMEOUT_LEAD} ${within} (${reason}). ${advice}`;
+}
+/**
+ * Whether the server behind a timed-out lease navigation accepted a connection.
+ *
+ * Only asked after a timeout and only of a loopback URL: the port probe reaches `localhost`, so a
+ * remote host would be answered by whatever listens locally on the same port. Never rejects; any
+ * doubt is `false`, which keeps the generic timeout advice.
+ */
+export async function serverAcceptedAfterTimeout(url, err, seed, portAccepts) {
+    if (portAccepts === undefined || NAV_TIMED_OUT !== cleanNavError(err, seed)) {
+        return false;
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (!isLoopbackHostname(parsed.hostname)) {
+        return false;
+    }
+    const defaultPort = 'https:' === parsed.protocol ? 443 : 80;
+    const port = '' === parsed.port ? defaultPort : Number(parsed.port);
+    return portAccepts(port).catch(() => false);
 }
+/** Whether a path is a sign-in page, by its name: `/login`, `/signin`, `/auth/login` and similar. */
+export const isAuthPath = (pathname) => /(?:^|\/)(?:login|signin|sign-in|auth\/login|auth\/signin|session\/new)(?:$|\/)/i.test(pathname);
 /**
  * Determine if a required seedStorage application precondition failed.
  *
@@ -159,7 +193,6 @@ export function evaluateSeedPrecondition(requestedUrl, actualUrl, seed, navStatu
         return `seeded storage precondition not established: cross-origin redirect from ${reqParsed.origin} to ${actParsed.origin} skipped origin-scoped storage injection`;
     }
     // Clear redirect to an authentication/login endpoint when the requested URL was not a login page
-    const isAuthPath = (pathname) => /(?:^|\/)(?:login|signin|sign-in|auth\/login|auth\/signin|session\/new)(?:$|\/)/i.test(pathname);
     if (!isAuthPath(reqParsed.pathname) && isAuthPath(actParsed.pathname)) {
         return `seeded authentication precondition not established: redirected from ${reqParsed.pathname} to login page (${actParsed.pathname})`;
     }

package/dist/surface/tools/lease-tools.d.ts

@@ -10,50 +10,11 @@
  * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
  */
 import { type SeedStorage } from '@reticlehq/core';
-import { HudVisibility } from '@reticlehq/core';
 import { type ToolDef, type ToolDeps } from './tool-kit.js';
 import { type BrowserPool } from '../../portal/pool/browser-pool.js';
 export { sessionMutationPort, sessionPerturbationPort, suiteFixturePort, suiteFixtureSeed, } from './session-ports.js';
-/**
- * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
- * adopts them on connect. Pure; falls back to plain concatenation if the URL can't be parsed.
- */
-export declare function appendReticleParams(url: string, session: string, projectId?: string, hud?: HudVisibility): string;
+export { appendReticleParams, carryReticleIdentity, resolveLeasedSessionId, } from './lease-url-identity.js';
 export { cleanNavError, evaluateSeedPrecondition, scrubSeedFromError } from './lease-seed.js';
-/**
- * The session a lease's tab actually registered as, or undefined while nothing has.
- *
- * Normally that is the lease id: `appendReticleParams` stamps `__reticle_session` on the URL and the
- * SDK adopts it. An app that passes an explicit `session` to `connect()` keeps its own name instead,
- * which is legitimate — a single-app fixture does it deliberately so a battery can address it by a
- * known id. Matching on the lease id alone could never see those tabs, so the lease reported
- * `ready: false` and a hint blaming a port mismatch while the session was connected and driveable.
- *
- * The URL marker is the evidence, and it is what makes this safe: two concurrent leases on one origin
- * carry different markers, so neither can adopt the other's tab. Parsed rather than substring-matched,
- * so `lease-abc` cannot claim `lease-abcdef`.
- */
-export declare function resolveLeasedSessionId(sessions: {
-    get: (id: string) => unknown;
-    all: () => {
-        id: string;
-        url?: string;
-    }[];
-}, leaseId: string): string | undefined;
-/**
- * Carry a claimed identity across a navigation.
- *
- * A LEASED tab is addressed by `__reticle_session` in its URL: that param is how the pool finds the
- * context it opened, and — since succession was tightened — it is also the ONLY thing that lets the
- * reconnecting document inherit the lease. `reticle_navigate` sent the caller's raw URL, so the very
- * first navigation stripped the marker, the tab re-announced as an ordinary anonymous session, and
- * the lease was orphaned: "no sessions are connected at all", with a browser window still open on
- * screen. A leased browser that cannot survive being navigated is not a usable one.
- *
- * A tab that claims nothing is left exactly as it was — this must never bolt Reticle's params onto
- * a human's own URL.
- */
-export declare function carryReticleIdentity(fromUrl: string | undefined, toUrl: string): string;
 /**
  * Acquire a leased, SDK-connected context for a caller that is not the lease TOOL (the parallel suite).
  * Returns the session id plus its release; the caller must release in a finally so a crashed flow never
@@ -63,6 +24,7 @@ export declare function acquireLeasedSession(pool: {
     acquire: (url: string, opts: {
         sessionId: string;
         seedStorage?: SeedStorage;
+        ignoreHTTPSErrors?: boolean;
     }) => Promise<{
         sessionId: string;
         release: () => Promise<void>;
@@ -83,7 +45,7 @@ export declare function acquireLeasedSession(pool: {
         id: string;
         url?: string;
     }[];
-}, url: string, projectId?: string, seedStorage?: SeedStorage): Promise<{
+}, url: string, projectId?: string, seedStorage?: SeedStorage, ignoreHTTPSErrors?: boolean): Promise<{
     sessionId: string;
     release: () => Promise<void>;
 }>;