@reticlehq/server 3.5.0 → 3.7.0

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

@@ -12,10 +12,12 @@
  * the hot resolve() path and this stays unit-testable.
  */
 import { NoSessionReason } from '@reticlehq/core/telemetry';
+import { redactUrl } from '@reticlehq/core';
 import { leaseCaveat } from './presence/lease-availability.js';
 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 { departedPortGone } from './no-session-next-action.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 = ' — ';
@@ -28,7 +30,7 @@ const NUXT = 'nuxt';
  * recovery: a message that already carries its own next action must not be handed a second, more
  * generic one that contradicts it.
  */
-export const SELF_RECOVERING_MARKER = 'Then call reticle_sessions again — it will appear within a second of the page loading.';
+export const SELF_RECOVERING_MARKER = 'Then call reticle_session { action: "list" } again — it will appear within a second of the page loading.';
 const RETRY = SELF_RECOVERING_MARKER;
 /**
  * The no-shell path, for the branches where a BLIND lease would be wrong.
@@ -61,12 +63,21 @@ function leaseAdvice(base, facts) {
 /**
  * The way out that needs no human at all.
  *
- * Only offered when the app is known to carry the SDK: leasing an uninstrumented app just burns a
- * browser and comes back `ready:false`.
+ * Offered here when the app is known to carry the SDK. An app that carries none is offered
+ * {@link ZERO_INSTALL} instead, which says what a lease on it can and cannot see.
  */
 const SELF_SERVE = 'You do not have to wait for the human: reticle_lease {action:"acquire", url} opens a browser ' +
     'Reticle drives itself, and returns a sessionId you can use immediately (reach it with ' +
     'reticle_run {tool:"reticle_lease"} if it is not advertised directly; release it when you finish).';
+/**
+ * The way past an app nobody wired, without waiting for the wiring.
+ *
+ * A lease on a page that never dials in hands it the zero-install reader, so an MCP-only install
+ * (a plugin, a hand-written `npx … mcp` config — `init` never ran) still gets a verdict on the first
+ * call instead of a diagnosis it stops at. The URL and the command live in the next action.
+ */
+const ZERO_INSTALL = 'You can get a verdict NOW with nothing installed: reticle_lease on the app URL supplies the ' +
+    'SDK itself (no component state or source file:line until it is wired) — the next action names it.';
 /** The hedge that is true for every vanished tab we did not watch leave. */
 const TAB_GONE_WHAT = 'The tab was closed, navigated away, or hard-reloaded.';
 /**
@@ -323,11 +334,12 @@ function alreadyListeningClause(listening) {
         return '';
     if (1 === listening.length) {
         const port = listening[0];
-        return (` An app is already listening on ${String(port)}; just open http://localhost:${String(port)} ` +
-            '— do not start a second stack.');
+        return (` Something is serving a page on :${String(port)}; it may not be this app — just open ` +
+            `http://localhost:${String(port)} rather than starting a second stack.`);
     }
-    return (` An app is already listening on ${listening.join(', ')}; just open one of those URLs — do not ` +
-        'start a second stack.');
+    const ports = listening.map((p) => `:${String(p)}`).join(', ');
+    return (` Something is serving a page on ${ports}; those listeners may not be this ` +
+        'app — open the URL that belongs to this project rather than starting a second stack.');
 }
 /**
  * The diagnosis, and the CODE for the branch that produced it.
@@ -404,6 +416,30 @@ export function explainNoSession(facts) {
                 'the SDK cannot reconnect to it. Fix the route, then reload the tab' +
                 `${orOpenCommand(facts)}.${alreadyListeningClause(listening)} ${RETRY}`);
         }
+        // Ranked above TAB_GONE because it is not a hedge: the SDK reported the departure while the
+        // old document was still alive, so this is where the tab WENT rather than one of several
+        // opposite situations. Ranked below ROUTE_SERVER_ERROR because that branch names a defect in
+        // the app itself. Only reached when the departure note arrived fresh — a stale note is no
+        // fact, and the tombstone already refused to carry one (#1256).
+        if (facts.departedTo !== undefined && '' !== facts.departedTo) {
+            return reason(NoSessionReason.NAVIGATED_AWAY, 'no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
+                // Redacted: a redirect target can carry credentials (OAuth callbacks, reset links), and
+                // this message is agent-facing. The raw value stays on the tombstone for matching.
+                `is correct. The page navigated away to ${redactUrl(facts.departedTo)} just before the ` +
+                'connection closed — that is where the tab went, not a closed tab and not an install ' +
+                `problem. Ask the human to go back to the app${orOpenCommand(facts)}, or reload the tab. ` +
+                `${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, alreadyListeningClause(listening).trim());
+        }
+        // The dev server that served this session has stopped: the departed session's own port no
+        // longer answers, so "ask the human to reopen the app" points at a dead socket. Keyed on that
+        // port, as the next action is (#1421) — the prose and the executable half agree on the story.
+        // No "already listening" clause: whatever else answers is not where this app was.
+        if (facts.lastKnownUrl !== undefined && departedPortGone(facts)) {
+            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)} The dev server that served it has stopped ` +
+                '— nothing answers on that port any more — so start the app again (the command is in ' +
+                `\`next_action\`). ${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${orOpenCommand(facts)}, or reload the tab. ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, alreadyListeningClause(listening).trim());
@@ -449,7 +485,8 @@ export function explainNoSession(facts) {
                 'dev server may not be running: START IT YOURSELF, in the background, using the command ' +
                 'in `next_action`, and tell the human in one line that it is running. ' +
                 `(2) There is no \`.reticle.json\` in ${where}, which is the file ${INIT_CMD} writes, so ` +
-                `the app may carry no Reticle SDK. Check the app's OWN directory before re-running it. ${RETRY}`, `The scan covers ${SCANNED_PORTS} and nothing else, so a server on any other port is ` +
+                `the app may carry no Reticle SDK. Check the app's OWN directory before re-running it. ` +
+                `${ZERO_INSTALL} ${RETRY}`, `The scan covers ${SCANNED_PORTS} and nothing else, so a server on any other port is ` +
                 'invisible to it: if the app IS running, ask for its URL rather than assuming it is down, ' +
                 `and open it with ${OPEN_CMD}. The missing config is not proof either — in a monorepo the ` +
                 'daemon often runs at the root while the app lives in a subdirectory, and an app wired by ' +
@@ -480,7 +517,7 @@ export function explainNoSession(facts) {
             `${INIT_CMD} writes, so the app may carry no Reticle SDK. Check the app's OWN directory: ` +
             `if it has no config, run ${INIT_CMD} ` +
             'there and restart the dev server; if it has one, the app is wired and simply has no page ' +
-            `open — ${OPEN_CMD}. ${RETRY}`, 'That absence is not proof: the same one is expected in a monorepo whose daemon runs at the ' +
+            `open — ${OPEN_CMD}. ${ZERO_INSTALL} ${RETRY}`, 'That absence is not proof: the same one is expected in a monorepo whose daemon runs at the ' +
             'root while the app lives in a subdirectory, or in an app wired by the Vite or Babel ' +
             `plugin. ${unattributedListeners(listening)}${searchedClause(facts)}${siblingListenerClause(facts)}`);
     }

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

@@ -29,6 +29,11 @@ interface NextActionFacts {
     initialized: boolean;
     listening: readonly number[];
     dev: DevCommand | undefined;
+    /**
+     * File-existence predicate for the project root, pure for testing.
+     * Used to recognize non-JS ecosystems (e.g. Flutter) when no dev script exists.
+     */
+    exists?: (file: string) => boolean;
     /** Configs found in other workspace directories: positive evidence of a scope mismatch. */
     configsElsewhere?: readonly {
         directory: string;
@@ -82,7 +87,33 @@ interface NextActionFacts {
      * its one hit is as likely to be another repo's dev server as this one's.
      */
     lastKnownUrl?: string;
+    /** Ports that accepted a connection and answered nothing in time: up, not gone. */
+    slowListeners?: readonly number[];
+    /**
+     * Where the departed tab was seen heading, when the SDK reported it fresh (#1256). The
+     * next-action reason must agree with the diagnosis: when this is present the tab was not
+     * closed, it navigated away.
+     */
+    departedTo?: string;
+    /**
+     * The command that wires THIS project for good — `init` in the app's own folder through the
+     * project's own runner (see `initCommandIn`). Absent means the generic npx spelling.
+     */
+    init?: string;
 }
+/** The port a tombstone URL names, when it names one — anything unparseable names no port. */
+export declare function portOfUrl(url: string): number | undefined;
+/**
+ * The departed session's own port no longer answers. Direct evidence, because the scan always
+ * covers that port — unlike an empty scan, which proves nothing the moment another project
+ * happens to be listening (#1421). A slow listener is up, not gone, and a url with no explicit
+ * port was never scanned, so neither counts.
+ */
+export declare function departedPortGone(facts: {
+    lastKnownUrl?: string;
+    listening: readonly number[];
+    slowListeners?: readonly number[];
+}): boolean;
 export declare function nextActionFor(facts: NextActionFacts): NoSessionNextAction;
 /** The same action as one sentence, for the prose message the human reads. */
 export declare function renderNextAction(next: NoSessionNextAction): string;

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

@@ -12,7 +12,33 @@
  *
  * Pure. The facts arrive from the watch; nothing here touches the disk or the clock.
  */
-import { NoSessionAction, RETICLE_URL_PARAM, ReticleEnv } from '@reticlehq/core';
+import { NoSessionAction, RETICLE_URL_PARAM, ReticleEnv, redactUrl } from '@reticlehq/core';
+import { detectNonJsEcosystem, noPackageJsonMessage } from '@reticlehq/init';
+/** The port a tombstone URL names, when it names one — anything unparseable names no port. */
+export function portOfUrl(url) {
+    try {
+        const raw = new URL(url).port;
+        if ('' === raw)
+            return undefined;
+        const port = Number(raw);
+        return Number.isSafeInteger(port) && port > 0 ? port : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The departed session's own port no longer answers. Direct evidence, because the scan always
+ * covers that port — unlike an empty scan, which proves nothing the moment another project
+ * happens to be listening (#1421). A slow listener is up, not gone, and a url with no explicit
+ * port was never scanned, so neither counts.
+ */
+export function departedPortGone(facts) {
+    const port = facts.lastKnownUrl === undefined ? undefined : portOfUrl(facts.lastKnownUrl);
+    return (port !== undefined &&
+        !facts.listening.includes(port) &&
+        !(facts.slowListeners ?? []).includes(port));
+}
 /**
  * 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
@@ -35,10 +61,29 @@ function reopenableUrl(raw) {
     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';
+/**
+ * Reticle's own commands, the only ones here that cannot be wrong. Spelled through `npx`, like the
+ * CLI's own messages: the default MCP registration runs Reticle through `npx` and puts no `reticle`
+ * bin on PATH, so a bare `reticle init` fails with "command not found" exactly where it is handed out.
+ */
+const CLI = 'npx @reticlehq/server';
+const INIT_COMMAND = `${CLI} init`;
+const OPEN_COMMAND = `${CLI} open`;
 const LOCALHOST = 'http://localhost';
+/**
+ * What a lease on an app with no SDK can see. The lease supplies the SDK itself (the zero-install
+ * reader), so an unwired app still gets a verdict — on what the page does, not on its source.
+ */
+const ZERO_INSTALL_SEES = 'the lease supplies the SDK itself: DOM, network, console and routes, but no component state ' +
+    'or source file:line until the app is wired';
+/** The zero-install call, with the URL only when it can be named without guessing. */
+function zeroInstallLease(url) {
+    return `reticle_lease {action:"acquire", url:"${url ?? "<the app's URL>"}"}`;
+}
+/** Nothing here says this project was ever wired: no config, no recorded connection, no session. */
+function neverWired(facts) {
+    return !facts.initialized && true !== facts.previouslyConnected && !facts.everConnected;
+}
 export function nextActionFor(facts) {
     // FIRST, above every other cause, because it is the only one supported by positive evidence about
     // a daemon rather than by an absence. This project's own connection record names a live daemon
@@ -70,7 +115,11 @@ export function nextActionFor(facts) {
     // (`connectedSinceLastClosure` in the manager). Read as the weaker "a refusal was recorded at
     // some point", the flip trades this bug for its mirror image and blames the token for a tab the
     // human closed. The ordering belongs to the fact; what this branch does with it is then obvious.
-    if (facts.everConnected && true !== facts.authRefused) {
+    // A departed session whose port is ALSO gone is the one shape where "reopen that" points at a
+    // dead socket and forbids the restart that fixes it (#1421). Keyed on that port itself, not on
+    // an empty scan: another project listening elsewhere says nothing about this one.
+    const departedPortIsGone = facts.everConnected && true !== facts.authRefused && departedPortGone(facts);
+    if (facts.everConnected && true !== facts.authRefused && !departedPortIsGone) {
         const listening = facts.listening;
         const only = 1 === listening.length ? listening[0] : undefined;
         // The departed session's own url first: it is where this project's app demonstrably was, while
@@ -81,19 +130,26 @@ export function nextActionFor(facts) {
             : 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.`;
+                    ? ` Something is serving a page on ${listening.map((p) => `:${String(p)}`).join(', ')}; it may not be this app — open the URL the human names rather than starting a second stack.`
+                    : ` Something is serving a page on :${String(only)}; it may not be this app — just open ${LOCALHOST}:${String(only)} rather than starting a second stack.`;
         const target = known !== undefined
             ? { command: `${OPEN_COMMAND} ${known.url}`, port: known.port }
             : only === undefined
                 ? {}
                 : { command: `${OPEN_COMMAND} ${LOCALHOST}:${String(only)}`, port: only };
+        // Where the tab was seen heading, when the SDK reported it fresh — the next action must
+        // tell the same story as the diagnosis (#1256).
+        const departedTo = facts.departedTo;
         return {
             action: NoSessionAction.REOPEN_APP,
             ...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}.' +
+            reason: 'a session was connected to this daemon earlier, so the wiring is correct — ' +
+                // Agrees with the diagnosis: when the SDK saw the page leave, "the tab was closed" is
+                // the wrong story. Redacted like the diagnosis — this reason is agent-facing too.
+                (departedTo === undefined || '' === departedTo
+                    ? 'the tab was closed, reloaded, or the lease aged out. '
+                    : `the page navigated away to ${redactUrl(departedTo)}. `) +
+                'Reopen the app, or take one you own with reticle_lease {action:"acquire", url}.' +
                 bound,
         };
     }
@@ -116,50 +172,11 @@ export function nextActionFor(facts) {
                 `point it there), then open the app.${leaseAlternative}`,
         };
     }
-    if (0 === facts.listening.length) {
-        const dev = facts.dev;
-        if (dev === undefined) {
-            return {
-                action: NoSessionAction.START_DEV_SERVER,
-                reason: 'nothing is listening on the ports Reticle scans, so the app is probably not running — ' +
-                    'but this project declares no dev script (no `dev`, `develop` or `start` in its ' +
-                    'package.json), so there is no command to hand you. Ask the human how their app is ' +
-                    'started, and for the URL it serves on.',
-            };
-        }
-        return {
-            action: NoSessionAction.START_DEV_SERVER,
-            command: dev.command,
-            ...(dev.port === undefined ? {} : { port: dev.port }),
-            // "Probably", to match the branch above it and the paragraph beside it.
-            //
-            // The same fact was stated at two confidence levels by one function: no dev script said the
-            // app was "probably not running", and THIS branch — the one that hands over a command to run
-            // — asserted it flatly. That is the branch where being wrong costs something, because the
-            // agent then starts a SECOND dev server on a second port, which the guard below calls the
-            // exact confusion this probe exists to prevent.
-            //
-            // It also contradicted its own payload: the prose beside it says the scan is narrow, that a
-            // server on any other port is invisible to it, and that a running app should be checked for
-            // rather than assumed away. Measured on a machine with three dev servers up on ports the scan
-            // 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 ` +
-                (undefined === dev.script ? 'launcher' : `\`${dev.script}\` script`) +
-                ` — run it in the ` +
-                'background, tell the human it is running, then call reticle_sessions again.',
-        };
-    }
-    // Something IS up. Whatever else is true, do NOT hand back a start command: a second dev server on
-    // a second port is the exact confusion the probe exists to prevent.
+    // A current pairing-token refusal is positive evidence that the app is running and instrumented.
+    // It must outrank an empty port scan, which only says the app is outside this daemon's scan set.
     const ports = facts.listening.join(', ');
     const only = 1 === facts.listening.length ? facts.listening[0] : undefined;
-    // A refused dial outranks the absence of a local config, for the same reason `previouslyConnected`
-    // does: it is positive evidence about the app, and `initialized` only ever answers "is there a
-    // `.reticle.json` in the ONE directory this daemon stands in". A globally-registered daemon stands
-    // in `/` or `$HOME`, so that answer is no for every project it serves -- and every page it turns
-    // away is proof that the project it turned away is wired.
+    const where = '' === ports ? 'on a port this daemon did not scan' : `${ports} listening`;
     // A refusal against a project that IS initialised here. The daemon has the config, so this is not
     // a scope problem — the page reached the right daemon and presented a credential it would not
     // accept. The usual cause is a dev server that shares no filesystem with the daemon (Docker, a
@@ -171,7 +188,7 @@ export function nextActionFor(facts) {
         return {
             action: NoSessionAction.OPEN_APP,
             ...(only === undefined ? {} : { port: only }),
-            reason: `a page dialled this daemon and was refused on the pairing token (${ports} listening), so ` +
+            reason: `a page dialled this daemon and was refused on the pairing token (${where}), so ` +
                 'the app IS running and instrumented and this project IS wired — the page simply presented ' +
                 'a token this daemon does not own. The usual cause is a dev server that does not share a ' +
                 'filesystem with the daemon (Docker, a devcontainer, WSL): the build plugin reads the token ' +
@@ -184,12 +201,17 @@ export function nextActionFor(facts) {
                 'dev server is on this machine or in a container.',
         };
     }
+    // A refused dial outranks the absence of a local config, for the same reason `previouslyConnected`
+    // does: it is positive evidence about the app, and `initialized` only ever answers "is there a
+    // `.reticle.json` in the ONE directory this daemon stands in". A globally-registered daemon stands
+    // in `/` or `$HOME`, so that answer is no for every project it serves -- and every page it turns
+    // away is proof that the project it turned away is wired.
     if (!facts.initialized && true === facts.authRefused) {
         return {
             action: NoSessionAction.OPEN_APP,
             ...(only === undefined ? {} : { port: only }),
             reason: `a page dialled this daemon and was refused on the pairing token, so the app IS running ` +
-                `and instrumented (${ports} listening) — this is a SCOPE problem, not an install problem. ` +
+                `and instrumented (${where}) — this is a SCOPE problem, not an install problem. ` +
                 'This daemon was started outside the project (an IDE that registers the MCP server ' +
                 'globally starts it in `/` or your home directory), so it has no `.reticle.json` to match ' +
                 'the page against. Do NOT run `reticle init`: the config it would write is already correct ' +
@@ -197,14 +219,91 @@ export function nextActionFor(facts) {
                 "projectId}, or restart the daemon from the app's own directory.",
         };
     }
+    if (0 === facts.listening.length || departedPortIsGone) {
+        const dev = facts.dev;
+        // The start advice below follows a departed session whose port is gone. Name it, so the restart
+        // does not read as if nothing had ever run here (#1421).
+        const stopped = departedPortIsGone ? reopenableUrl(facts.lastKnownUrl) : undefined;
+        const stoppedNote = stopped === undefined
+            ? ''
+            : ` The session that was on ${redactUrl(stopped.url)} is gone and nothing listens there now.`;
+        const notRunning = departedPortIsGone
+            ? "nothing answers on the port this project's app was last on, so the app is probably not running — "
+            : 'nothing is listening on the ports Reticle scans, so the app is probably not running — ';
+        if (dev === undefined) {
+            if (facts.exists !== undefined && !facts.exists('package.json')) {
+                const ecosystem = detectNonJsEcosystem(facts.exists);
+                if (ecosystem !== undefined) {
+                    return {
+                        action: NoSessionAction.START_DEV_SERVER,
+                        reason: 'Flutter' === ecosystem
+                            ? noPackageJsonMessage(facts.exists)
+                            : `This looks like a ${ecosystem} project, with no package.json in this directory. ` +
+                                'There is no dev command to hand you. Ask the human how the app starts and which ' +
+                                'URL it serves. If the web app has its own package.json in another directory, ' +
+                                'run Reticle from that app directory instead.',
+                    };
+                }
+            }
+            return {
+                action: NoSessionAction.START_DEV_SERVER,
+                reason: notRunning +
+                    'but this project declares no dev script (no `dev`, `develop` or `start` in its ' +
+                    'package.json), so there is no command to hand you. Ask the human how their app is ' +
+                    'started, and for the URL it serves on.' +
+                    stoppedNote,
+            };
+        }
+        // The app can live one directory down; the command has to be runnable from where the daemon
+        // stands, so it carries its own `cd` (reticle#1368).
+        const inApp = dev.directory === undefined ? '' : `cd ${dev.directory} && `;
+        return {
+            action: NoSessionAction.START_DEV_SERVER,
+            command: `${inApp}${dev.command}`,
+            ...(dev.port === undefined ? {} : { port: dev.port }),
+            // "Probably", to match the branch above it and the paragraph beside it.
+            //
+            // The same fact was stated at two confidence levels by one function: no dev script said the
+            // app was "probably not running", and THIS branch — the one that hands over a command to run
+            // — asserted it flatly. That is the branch where being wrong costs something, because the
+            // agent then starts a SECOND dev server on a second port, which the guard below calls the
+            // exact confusion this probe exists to prevent.
+            //
+            // It also contradicted its own payload: the prose beside it says the scan is narrow, that a
+            // server on any other port is invisible to it, and that a running app should be checked for
+            // rather than assumed away. Measured on a machine with three dev servers up on ports the scan
+            // does not cover, it reported the app was not running.
+            reason: notRunning +
+                '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 ` +
+                (undefined === dev.script ? 'launcher' : `\`${dev.script}\` script`) +
+                (dev.directory === undefined ? '' : `, in \`${dev.directory}\``) +
+                ` — run it in the ` +
+                'background, tell the human it is running, then call reticle_sessions again.' +
+                stoppedNote +
+                (neverWired(facts)
+                    ? ` Once it is up, ${zeroInstallLease(dev.port === undefined ? undefined : `${LOCALHOST}:${String(dev.port)}`)} ` +
+                        `gets a verdict with nothing installed (${ZERO_INSTALL_SEES}); ` +
+                        `\`${facts.init ?? INIT_COMMAND}\` wires it for good — then restart the dev server and reload.`
+                    : ''),
+        };
+    }
+    // Something IS up. Whatever else is true, do NOT hand back a start command: a second dev server on
+    // a second port is the exact confusion the probe exists to prevent.
     if (!facts.initialized && true !== facts.previouslyConnected) {
+        // The port the project's own dev script pins outranks a lone listener: the scan is machine-wide.
+        const pinned = facts.dev?.port;
+        const target = pinned !== undefined && facts.listening.includes(pinned) ? pinned : only;
         return {
             action: NoSessionAction.RUN_INIT,
-            command: INIT_COMMAND,
-            ...(only === undefined ? {} : { port: only }),
+            command: facts.init ?? INIT_COMMAND,
+            ...(target === undefined ? {} : { port: target }),
             reason: `something is listening (${ports}) but no \`.reticle.json\` was found, so the app may ` +
-                "carry no Reticle SDK. Run this in the APP's own directory — in a monorepo that is not " +
-                'where this daemon stands — then restart the dev server.',
+                'carry no Reticle SDK. For a verdict NOW with nothing installed: ' +
+                `${zeroInstallLease(target === undefined ? undefined : `${LOCALHOST}:${String(target)}`)} — ` +
+                `${ZERO_INSTALL_SEES}. To wire it for good, run this command yourself (it runs in the ` +
+                "APP's own folder, not where this daemon stands), then restart the dev server and reload " +
+                'the page.',
         };
     }
     if (only === undefined) {
@@ -232,12 +331,12 @@ export function nextActionFor(facts) {
         command: `${OPEN_COMMAND} ${LOCALHOST}:${String(only)}`,
         port: only,
         reason: neverConnected
-            ? 'this project is wired and a dev server is listening, but no app has ever connected to ' +
+            ? 'this project is wired and something is listening on that port (it may not be this app), but no app has ever connected to ' +
                 'this daemon — Reticle only ever sees a page a browser has LOADED, and nothing has loaded ' +
                 'one. If opening it does not produce a session, the dev server is older than the Reticle ' +
                 'plugin and its bundle carries no SDK: restart the dev server (do not rely on HMR) and ' +
                 'load the page again.'
-            : 'this project is wired and a dev server is listening — Reticle only ever sees a page a ' +
+            : 'this project is wired and something is listening on that port (it may not be this app) — Reticle only ever sees a page a ' +
                 'browser has LOADED, and nothing has loaded one.',
     };
 }

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

@@ -17,7 +17,20 @@ interface NoSessionWatchOptions {
     initialized: boolean;
     /** Where that was decided — this daemon's working directory unless a caller says otherwise. */
     directory?: string;
-    probe?: () => Promise<number[]>;
+    /**
+     * File-existence predicate for the project directory. Injected for tests; defaults to
+     * checking the directory on disk.
+     */
+    exists?: (file: string) => boolean;
+    /**
+     * The background port scan. Injected for tests; production probes each port on both loopback
+     * families.
+     *
+     * Receives the candidate list — the well-known ports plus the ones that name THIS project
+     * (#1367) — so a test can pin the observation without opening a socket. A test that injects it
+     * owns the scan.
+     */
+    probe?: (ports: readonly number[]) => Promise<number[]>;
     /**
      * Well-known Reticle ports other than ours that currently accept a connection.
      *