@reticlehq/server 3.3.0 → 3.5.0

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

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

@@ -17,6 +17,10 @@ import { DEV_SERVER_PORTS } from '../../command/cli/ports/resolve/cli-port.js';
 import { siblingListenerNote } from '../../command/cli/ports/sibling-ports.js';
 import { STALL_AFTER_MS } from './stall-clock.js';
 import { pageTornDownWhileOn } from '@reticlehq/engine/evidence/page-teardown.js';
+/** How every hello-refusal reason the bridge records separates its cause from its fix. */
+const CAUSE_FIX_SEPARATOR = ' — ';
+/** The lowest HTTP status that means the server itself failed to answer the route. */
+const SERVER_ERROR_FLOOR = 500;
 /** The one framework whose most likely cause differs from every other framework's. */
 const NUXT = 'nuxt';
 /**
@@ -49,6 +53,8 @@ const URL_THEN_LEASE = 'Once you have that URL, open it with reticle_lease {acti
  * diagnosed the problem.
  */
 function leaseAdvice(base, facts) {
+    if (true === facts.desktop)
+        return DESKTOP_NO_BROWSER;
     const caveat = leaseCaveat(facts.leaseBrowser);
     return caveat === undefined ? base : `${base} ${caveat}`;
 }
@@ -180,6 +186,25 @@ function slowListenerClause(facts) {
 const OPEN_THE_APP = 'Reticle only ever sees a page that is LOADED, so the commonest cause by a distance is that no ' +
     `browser has opened the app yet: run ${OPEN_CMD} with the app's own URL (or ask the ` +
     'human to open it).';
+/**
+ * The desktop twin of OPEN_THE_APP. A desktop app's page exists only inside its own window, and the
+ * guidance used to send an Electron user to a browser URL — which reaches the renderer's dev server
+ * and none of the app around it.
+ */
+const DESKTOP_OPEN_THE_APP = 'This is a desktop app, and Reticle sees it only from inside its own window, so the commonest ' +
+    'cause by a distance is that the desktop app is not running: start it yourself, in the ' +
+    "background, with the project's desktop dev command (the script that runs `tauri dev`, " +
+    '`electron-vite dev`, `electron-forge start` or `electron .`), not the plain web dev server.';
+/** Why the browser and lease routes are withheld for a desktop app. Replaces the lease offer. */
+const DESKTOP_NO_BROWSER = 'Do not open its URL in a browser or with a lease: that loads the renderer outside the desktop ' +
+    'shell, without its IPC bridge or native APIs, so it is not the app you are verifying.';
+function openTheApp(facts) {
+    return true === facts.desktop ? DESKTOP_OPEN_THE_APP : OPEN_THE_APP;
+}
+/** The "(or run open)" aside — a desktop window is reopened by the app, not by a browser command. */
+function orOpenCommand(facts) {
+    return true === facts.desktop ? '' : ` (or run ${OPEN_CMD_BARE})`;
+}
 /**
  * What a machine-wide port scan can and cannot say.
  *
@@ -334,6 +359,22 @@ export function explainNoSession(facts) {
             'while the dev server runs from a shell — they can be reading different `~/.reticle` ' +
             'directories instead. The page says the same thing in the browser console.');
     }
+    // Beside the token refusal and for the same reason: a turned-away hello is current, positive
+    // evidence, and every branch below reasons from an absence.
+    if (facts.helloRefused !== undefined) {
+        const { reason: said, url, projectId } = facts.helloRefused;
+        const split = said.indexOf(CAUSE_FIX_SEPARATOR);
+        const cause = -1 === split ? said : said.slice(0, split);
+        const fix = -1 === split ? undefined : said.slice(split + CAUSE_FIX_SEPARATOR.length);
+        const page = undefined === url || '' === url ? 'a page' : `the page at ${url}`;
+        const project = undefined === projectId ? '' : ` (project ${projectId})`;
+        return reason(
+        // ponytail: shares the token refusal's code, because a new code is a telemetry wire change
+        // and that surface has its own owner; split it out as `hello_refused` there.
+        NoSessionReason.AUTH_REFUSED, `no browser session connected: ${page}${project} dialled this daemon and was REFUSED ` +
+            `because ${cause}${undefined === fix ? '' : `; fix: ${fix}`}. Only an SDK dials the ` +
+            'bridge, so the app is running and instrumented — do not go looking for a stopped dev server.');
+    }
     if (everConnected) {
         // A reaped lease first, because it is the one cause with POSITIVE evidence behind it. Calling
         // it "the tab was closed, ask the human to reopen the app" is wrong on every clause (#157):
@@ -347,9 +388,25 @@ export function explainNoSession(facts) {
                 `with reticle_lease {action:"acquire", url} and carry on. ${RETRY}`, 'A lease is a headless context, not a human tab, and it takes its cookies with it, so an ' +
                 `authenticated app needs signing in again.${alreadyListeningClause(listening)}`);
         }
+        // Ranked above TAB_GONE because it is not an absence: the route itself answered. A tab that a
+        // 5xx tore down and a tab a human closed produce the same empty list, and until the watch asked
+        // the route, they produced the same sentence. Present tense throughout — "answers ... right
+        // now" — because a 500 now does not prove the teardown was a 500 then, and saying so would
+        // turn an observation into a story.
+        if (facts.lastKnownStatus !== undefined &&
+            facts.lastKnownStatus >= SERVER_ERROR_FLOOR &&
+            facts.lastKnownUrl !== undefined &&
+            '' !== facts.lastKnownUrl) {
+            return reason(NoSessionReason.ROUTE_SERVER_ERROR, 'no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
+                `is correct. The page was torn down while on ${facts.lastKnownUrl}, and that route answers ` +
+                `HTTP ${String(facts.lastKnownStatus)} right now — a server error in the app, not a closed ` +
+                'tab and not an install problem. A route that throws server-side tears the page down and ' +
+                'the SDK cannot reconnect to it. Fix the route, then reload the tab' +
+                `${orOpenCommand(facts)}.${alreadyListeningClause(listening)} ${RETRY}`);
+        }
         return reason(NoSessionReason.TAB_GONE, 'no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
             `is correct. ${tabGoneWhat(facts.lastKnownUrl)} Ask the human to reopen ` +
-            `the app (or run ${OPEN_CMD_BARE}), or reload the tab. ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, alreadyListeningClause(listening).trim());
+            `the app${orOpenCommand(facts)}, or reload the tab. ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, alreadyListeningClause(listening).trim());
     }
     // Ranked ahead of every "we have never seen one" branch below, because it is the one fact that
     // OUTRANKS them: those branches all reason from an absence, and this reasons from a recorded
@@ -360,14 +417,14 @@ export function explainNoSession(facts) {
             ? `${unattributedListeners(listening)} If the dev server is not running, start it first ` +
                 '(the command is in `next_action`).'
             : unattributedListeners(listening);
-        return reason(NoSessionReason.APP_NOT_REOPENED, `${RESTARTED_LEAD} ${OPEN_THE_APP} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, `${DO_NOT_REINSTALL} ${listeners} ${rankedCauses(facts)}`);
+        return reason(NoSessionReason.APP_NOT_REOPENED, `${RESTARTED_LEAD} ${openTheApp(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, `${DO_NOT_REINSTALL} ${listeners} ${rankedCauses(facts)}`);
     }
     // A config found elsewhere outranks every "you may have no SDK" branch below: those reason from
     // an absence in ONE directory, and this is a file we read in another. Ranked here so the reader is
     // never sent through an install on a project that has demonstrably been installed.
     if (!initialized && (facts.configsElsewhere ?? []).length > 0) {
         return reason(NoSessionReason.CONFIG_ELSEWHERE, 'no browser session connected, and this daemon has never seen one. ' +
-            `${configsElsewhereClause(facts)} ${OPEN_THE_APP} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, 'This daemon was started somewhere that is not the project, which is the normal outcome when ' +
+            `${configsElsewhereClause(facts)} ${openTheApp(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, 'This daemon was started somewhere that is not the project, which is the normal outcome when ' +
             `an editor launches it from your home directory. ${unattributedListeners(listening)} ` +
             `${rankedCauses(facts)}`);
     }
@@ -399,7 +456,7 @@ export function explainNoSession(facts) {
                 'the Vite or Babel plugin carries the SDK without that file at all.' +
                 `${searchedClause(facts)}${siblingListenerClause(facts)} ${leaseAdvice(URL_THEN_LEASE, facts)}`);
         }
-        return reason(NoSessionReason.NO_LISTENER, `${stallClause(facts)}no browser session connected, and this daemon has never seen one. ${OPEN_THE_APP} ` +
+        return reason(NoSessionReason.NO_LISTENER, `${stallClause(facts)}no browser session connected, and this daemon has never seen one. ${openTheApp(facts)} ` +
             'Nothing is listening on the ports Reticle scans either, and the usual reason is a dev ' +
             'server that is not running: start it yourself in the background with the command in ' +
             '`next_action`, tell the human in one line that it is running, then open the app in a ' +
@@ -428,7 +485,7 @@ export function explainNoSession(facts) {
             `plugin. ${unattributedListeners(listening)}${searchedClause(facts)}${siblingListenerClause(facts)}`);
     }
     return reason(NoSessionReason.SDK_NOT_REACHING_DAEMON, `${stallClause(facts)}no browser session connected, and this daemon has never seen one for this project, which is ` +
-        `wired for Reticle. ${OPEN_THE_APP} If the page IS open and still does not appear, the SDK ` +
+        `wired for Reticle. ${openTheApp(facts)} If the page IS open and still does not appear, the SDK ` +
         `is not reaching this daemon (on ${String(port)}). ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, `${unattributedListeners(listening)} ${rankedCauses(facts)}`);
 }
 /**

package/dist/portal/session/no-session-next-action.d.ts

@@ -69,6 +69,19 @@ interface NextActionFacts {
      * action that cannot help and can overwrite it.
      */
     authRefused?: boolean;
+    /**
+     * The bridge refused the last hello for a non-token reason (protocol or wire-contract skew), in
+     * the bridge's own `cause — fix` sentence. Current, like `authRefused`: nothing connected since.
+     * Every other action below would send the agent to start, open or re-wire an app that is running,
+     * instrumented and being turned away.
+     */
+    helloRefused?: string;
+    /**
+     * The url the session that went away was on, from the daemon's own tombstone. Positive evidence
+     * about where THIS project's app lives, which the port scan is not: the scan is machine-wide, and
+     * its one hit is as likely to be another repo's dev server as this one's.
+     */
+    lastKnownUrl?: string;
 }
 export declare function nextActionFor(facts: NextActionFacts): NoSessionNextAction;
 /** The same action as one sentence, for the prose message the human reads. */

package/dist/portal/session/no-session-next-action.js

@@ -12,7 +12,29 @@
  *
  * Pure. The facts arrive from the watch; nothing here touches the disk or the clock.
  */
-import { NoSessionAction, ReticleEnv } from '@reticlehq/core';
+import { NoSessionAction, RETICLE_URL_PARAM, ReticleEnv } from '@reticlehq/core';
+/**
+ * The departed session's url as a human would type it: the params a Reticle launcher stamps on a
+ * lease are stripped, because reopening WITH them would adopt the dead lease's identity. Undefined
+ * for a url that does not parse, or one with no port to name (a desktop webview's opaque origin).
+ */
+function reopenableUrl(raw) {
+    if (raw === undefined)
+        return undefined;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if ('http:' !== url.protocol && 'https:' !== url.protocol)
+        return undefined;
+    for (const param of Object.values(RETICLE_URL_PARAM))
+        url.searchParams.delete(param);
+    const port = '' === url.port ? ('https:' === url.protocol ? 443 : 80) : Number(url.port);
+    return { url: url.toString(), port };
+}
 /** `reticle init`, the only command here that is Reticle's own and so cannot be wrong. */
 const INIT_COMMAND = 'reticle init';
 const OPEN_COMMAND = 'reticle open';
@@ -28,6 +50,13 @@ export function nextActionFor(facts) {
     if (splitBrain !== undefined) {
         return { action: NoSessionAction.DAEMON_SPLIT, reason: splitBrain };
     }
+    if (facts.helloRefused !== undefined) {
+        return {
+            action: NoSessionAction.OPEN_APP,
+            reason: `a page dialled this daemon and was refused (${facts.helloRefused}); do that, then reload ` +
+                'the page — the SDK does not retry after a refusal.',
+        };
+    }
     // `authRefused` is checked here and not only further down, because this branch short-circuits.
     //
     // Both refusal branches below were already written and already right, and neither could be
@@ -44,16 +73,24 @@ export function nextActionFor(facts) {
     if (facts.everConnected && true !== facts.authRefused) {
         const listening = facts.listening;
         const only = 1 === listening.length ? listening[0] : undefined;
-        const bound = 0 === listening.length
-            ? ''
+        // The departed session's own url first: it is where this project's app demonstrably was, while
+        // a lone port from the scan may belong to anybody.
+        const known = reopenableUrl(facts.lastKnownUrl);
+        const bound = known !== undefined
+            ? ` It was last on ${known.url}; reopen that — do not start a second stack.`
+            : 0 === listening.length
+                ? ''
+                : only === undefined
+                    ? ` An app is already listening on ${listening.join(', ')}; just open the URL the human names — do not start a second stack.`
+                    : ` An app is already listening on ${String(only)}; just open ${LOCALHOST}:${String(only)} — do not start a second stack.`;
+        const target = known !== undefined
+            ? { command: `${OPEN_COMMAND} ${known.url}`, port: known.port }
             : only === undefined
-                ? ` An app is already listening on ${listening.join(', ')}; just open the URL the human names — do not start a second stack.`
-                : ` An app is already listening on ${String(only)}; just open ${LOCALHOST}:${String(only)} — do not start a second stack.`;
+                ? {}
+                : { command: `${OPEN_COMMAND} ${LOCALHOST}:${String(only)}`, port: only };
         return {
             action: NoSessionAction.REOPEN_APP,
-            ...(only === undefined
-                ? {}
-                : { command: `${OPEN_COMMAND} ${LOCALHOST}:${String(only)}`, port: only }),
+            ...target,
             reason: 'a session was connected to this daemon earlier, so the wiring is correct — the tab was ' +
                 'closed, reloaded, or the lease aged out. Reopen the app, or take one you own with ' +
                 'reticle_lease {action:"acquire", url}.' +
@@ -108,7 +145,9 @@ export function nextActionFor(facts) {
             // does not cover, it reported the app was not running.
             reason: 'nothing is listening on the ports Reticle scans, so the app is probably not running — ' +
                 'though that scan is narrow, so if it IS up on another port, ask for its URL instead of ' +
-                `starting a second one. This is the project's own \`${dev.script}\` script — run it in the ` +
+                `starting a second one. This is the project's own ` +
+                (undefined === dev.script ? 'launcher' : `\`${dev.script}\` script`) +
+                ` — run it in the ` +
                 'background, tell the human it is running, then call reticle_sessions again.',
         };
     }

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

@@ -45,6 +45,24 @@ interface NoSessionWatchOptions {
      * Omitted on a daemon with no pool, and auto-attach is then simply off.
      */
     attach?: (url: string) => Promise<unknown>;
+    /**
+     * The ports THIS project's dev servers announced into the registry the build plugins write.
+     *
+     * Auto-attach opens a port only when it can be attributed to this project. The port scan is
+     * machine-wide, so its one hit is as likely to be another repo's app as this one's — and now that
+     * the attach path can launch an installed Chrome, a wrong guess parks a hidden headless browser on
+     * somebody else's app. Injected for tests; production reads the registry scoped by projectId/root.
+     */
+    ownDevServerPorts?: () => readonly number[];
+    /**
+     * What the route the last session was on answers right now, as an HTTP status, or undefined
+     * when there is no answer to report.
+     *
+     * Injected so tests can pin the observation without opening a socket. Production (no override)
+     * asks the route itself — see route-status-probe. The one fact that separates a route that 500s
+     * from a closed tab (#808, option 3).
+     */
+    routeStatus?: (url: string) => Promise<number | undefined>;
     /**
      * Where the durable "an app has connected here before" bit lives. The daemon's state home unless
      * a test says otherwise.