@reticlehq/server 3.6.0 → 3.7.0

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

@@ -14,6 +14,31 @@
  */
 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
@@ -36,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
@@ -71,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
@@ -82,8 +130,8 @@ 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
@@ -124,8 +172,64 @@ export function nextActionFor(facts) {
                 `point it there), then open the app.${leaseAlternative}`,
         };
     }
-    if (0 === facts.listening.length) {
+    // 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;
+    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
+    // devcontainer, WSL): the build plugin reads-or-mints the pairing token from `$HOME/.reticle`,
+    // which over there is a different file, so it mints its own and every page is refused. The daemon
+    // holds every fact needed to say so, which is why the reason below says it rather than repeating
+    // `authentication failed`.
+    if (true === 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 (${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 ' +
+                'from `$HOME/.reticle/pairing-token`, which over there is a different file, so it mints its ' +
+                "own. Point the plugin at the daemon's copy — mount `~/.reticle/pairing-token` into the " +
+                `container read-only and set \`${ReticleEnv.PAIRING_TOKEN_DIR}\` to the directory holding ` +
+                'it — then ' +
+                'restart the dev server, because the token is inlined when Vite resolves its config and ' +
+                'kept in the prebundled module. Reloading the page serves that same token, whether the ' +
+                '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 (${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 ' +
+                'somewhere else. Take a context you own instead with reticle_lease {action:"acquire", url, ' +
+                "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);
@@ -143,10 +247,11 @@ export function nextActionFor(facts) {
             }
             return {
                 action: NoSessionAction.START_DEV_SERVER,
-                reason: 'nothing is listening on the ports Reticle scans, so the app is probably not running — ' +
+                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.',
+                    '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
@@ -168,69 +273,37 @@ export function nextActionFor(facts) {
             // 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 — ' +
+            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.',
+                '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.
-    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.
-    // 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
-    // devcontainer, WSL): the build plugin reads-or-mints the pairing token from `$HOME/.reticle`,
-    // which over there is a different file, so it mints its own and every page is refused. The daemon
-    // holds every fact needed to say so, which is why the reason below says it rather than repeating
-    // `authentication failed`.
-    if (true === 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 (${ports} listening), 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 ' +
-                'from `$HOME/.reticle/pairing-token`, which over there is a different file, so it mints its ' +
-                "own. Point the plugin at the daemon's copy — mount `~/.reticle/pairing-token` into the " +
-                `container read-only and set \`${ReticleEnv.PAIRING_TOKEN_DIR}\` to the directory holding ` +
-                'it — then ' +
-                'restart the dev server, because the token is inlined when Vite resolves its config and ' +
-                'kept in the prebundled module. Reloading the page serves that same token, whether the ' +
-                'dev server is on this machine or in a container.',
-        };
-    }
-    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. ` +
-                '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 ' +
-                'somewhere else. Take a context you own instead with reticle_lease {action:"acquire", url, ' +
-                "projectId}, or restart the daemon from the app's own directory.",
-        };
-    }
     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) {
@@ -258,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.js

@@ -13,11 +13,12 @@ import { probeRouteStatus } from './dev-server/route-status-probe.js';
 import { probeDevServerStates } from './dev-server/dev-server-probe.js';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
+import { callingClientDirectory } from '../../hooks/client-directory.js';
 import { registeredElsewhere } from '../../memory/recall/registered-projects.js';
 import { explainNoSession } from './no-session-diagnosis.js';
-import { detectDevCommandInProject } from './dev-server/dev-command.js';
-import { nextActionFor, renderNextAction } from './no-session-next-action.js';
+import { detectDevCommandInProject, initCommandIn } from './dev-server/dev-command.js';
+import { nextActionFor, portOfUrl, renderNextAction } from './no-session-next-action.js';
 import { DEV_SERVER_PORTS, readProjectFramework, readProjectId, readProjectIsDesktop, readProjectPort, } from '../../command/cli/ports/resolve/cli-port.js';
 import { discoverProjectConfigs } from '../../command/cli/config/config-discovery.js';
 import { hasProjectConnectedBefore, rememberConnected, } from '../../memory/recall/prior/connection-memory.js';
@@ -49,19 +50,6 @@ function attachFailureClause(port, reason) {
                 'rather than treating this as a problem with the app.'
             : ''));
 }
-/** The port a tombstone URL names, when it names one — anything unparseable names no port. */
-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;
-    }
-}
 /**
  * Start the watch. Returns a stop function; the timer is unref'd so it never holds the daemon up.
  *
@@ -70,6 +58,8 @@ function portOfUrl(url) {
  */
 export function startNoSessionWatch(options) {
     let listening = [];
+    /** Ports the last scan was asked about. A port absent from this set was not observed, so it is not "down". */
+    let probed = new Set();
     /**
      * Ports that accepted a connection and then answered nothing in time.
      *
@@ -159,8 +149,8 @@ export function startNoSessionWatch(options) {
      * this one starts, which is precisely the window the agent then spends being told to start a dev
      * server that is already running.
      */
-    const splitBrain = () => {
-        const projectId = readProjectId(directory);
+    const splitBrain = (dir = directory) => {
+        const projectId = readProjectId(dir);
         if (projectId === undefined) {
             return projectlessNote(options.port, projectDaemonsElsewhere(options.port, stateDir, isAlive));
         }
@@ -211,6 +201,13 @@ export function startNoSessionWatch(options) {
         const knownPort = known === undefined ? undefined : portOfUrl(known.url);
         if (knownPort !== undefined)
             ports.add(knownPort);
+        // Every departed project, not only the newest. B can still be serving on :3005 after A leaves
+        // on :5173, and a scan that never asked :3005 would report B's app as stopped.
+        for (const url of options.sessions.tombstoneUrls?.() ?? []) {
+            const port = portOfUrl(url);
+            if (port !== undefined)
+                ports.add(port);
+        }
         return [...ports];
     };
     /**
@@ -255,7 +252,10 @@ export function startNoSessionWatch(options) {
         }
     };
     const refresh = () => {
-        // Nothing to diagnose while a session is live, and no reason to scan.
+        // Nothing to diagnose while a session is live, and no reason to scan. What the last scan saw
+        // predates this session, so it is no observation of where the session goes on to depart from.
+        if (options.sessions.count() > 0)
+            probed = new Set();
         if (running || options.sessions.count() > 0)
             return;
         running = true;
@@ -267,6 +267,7 @@ export function startNoSessionWatch(options) {
             })
             : options.probe(candidates))
             .then(async (ports) => {
+            probed = new Set(candidates);
             listening = ports;
             siblingListeners =
                 options.occupiedSiblings !== undefined
@@ -329,6 +330,143 @@ export function startNoSessionWatch(options) {
             return undefined;
         return { reason: closure.reason, ...closure.page };
     };
+    /**
+     * The diagnosis for a client standing in a different project than this daemon.
+     *
+     * `everConnected` and the newest tombstone are facts about the process. Spent on a second
+     * project they say that project's wiring is done and name the first project's URL. A directory
+     * that has never had a session of its own has never connected, whatever else this daemon has seen.
+     * Ports count only when this project announced them or its own last session was on them, so the
+     * reopen command cannot fall through to somebody else's dev server.
+     */
+    const diagnosisFor = (dir) => {
+        const projectId = readProjectId(dir);
+        const initialized = projectId !== undefined;
+        // A tab that reported no project cannot be another project's: it is the daemon's own last tab,
+        // never "this daemon has never seen one" beside a refusal that names where it last saw it. A
+        // tab that named another project stays that project's (a second app is not told to reopen it).
+        const newest = options.sessions.lastKnown?.();
+        const unclaimed = newest !== undefined && newest.projectId === undefined ? newest : undefined;
+        const known = (projectId === undefined ? undefined : options.sessions.lastKnownFor?.(projectId)) ??
+            unclaimed;
+        const everConnected = (projectId !== undefined && true === options.sessions.everConnectedTo?.(projectId)) ||
+            unclaimed !== undefined;
+        const ownPorts = new Set(devServersForProject(readDevServers(stateDir), { projectId, root: dir }).map((entry) => entry.port));
+        if (known !== undefined) {
+            const port = portOfUrl(known.url);
+            if (port !== undefined)
+                ownPorts.add(port);
+        }
+        const heard = listening.filter((port) => ownPorts.has(port));
+        // Not in the last scan means we have not looked, not that the server stopped. Treating the
+        // gap as "down" is what tells a still-running app to start a second one.
+        for (const port of ownPorts) {
+            if (!probed.has(port) && !heard.includes(port))
+                heard.push(port);
+        }
+        const slow = slowListeners.filter((port) => ownPorts.has(port));
+        const closure = options.sessions.lastClosure?.();
+        const refusalIsThisProject = closure !== undefined &&
+            true !== options.sessions.connectedSinceLastClosure?.() &&
+            projectId !== undefined &&
+            closure.page?.projectId === projectId;
+        const helloRefused = refusalIsThisProject &&
+            closure !== undefined &&
+            closure.page !== undefined &&
+            !isAuthRefusalReason(closure.reason)
+            ? { reason: closure.reason, ...closure.page }
+            : undefined;
+        const discovery = initialized ? undefined : discoverProjectConfigs(dir);
+        const found = discovery === undefined ? [] : discovery.found.filter((config) => config.directory !== dir);
+        const registered = 0 < found.length ? [] : registeredElsewhere(homedir(), dir);
+        const configsElsewhere = 0 < found.length
+            ? found.map((config) => ({
+                directory: config.directory,
+                ...(config.projectId === undefined ? {} : { projectId: config.projectId }),
+            }))
+            : 0 < registered.length
+                ? registered.map((project) => ({
+                    directory: project.directory,
+                    ...(project.projectId === undefined ? {} : { projectId: project.projectId }),
+                }))
+                : undefined;
+        const framework = readProjectFramework(dir);
+        const configured = readProjectPort(dir);
+        const previouslyConnected = hasProjectConnectedBefore(stateDir, options.port, projectId);
+        const authRefused = refusalIsThisProject && closure !== undefined && isAuthRefusalReason(closure.reason);
+        const status = known !== undefined && lastKnownStatus !== undefined && lastKnownStatus.url === known.url
+            ? { lastKnownStatus: lastKnownStatus.status }
+            : {};
+        const departedTo = known?.departedTo;
+        const departed = departedTo === undefined || '' === departedTo ? {} : { departedTo };
+        const upMs = stallUptime(Date.now());
+        const facts = {
+            everConnected,
+            initialized,
+            ...(configsElsewhere === undefined ? {} : { configsElsewhere }),
+            ...(discovery !== undefined && configsElsewhere === undefined
+                ? { searchedDirectories: discovery.searched }
+                : {}),
+            listening: heard,
+            slowListeners: slow,
+            port: options.port,
+            directory: dir,
+            previouslyConnected,
+            authRefused,
+            ...(helloRefused === undefined ? {} : { helloRefused }),
+            ...(framework === undefined ? {} : { framework }),
+            ...(readProjectIsDesktop(dir) ? { desktop: true } : {}),
+            leaseExpired: known !== undefined && (options.wasReapedLease?.(known.id) ?? false),
+            ...(known === undefined ? {} : { lastKnownUrl: known.url, ...status, ...departed }),
+            ...(upMs === undefined ? {} : { daemonUpMs: upMs }),
+            ...(configured === undefined ? {} : { projectPort: configured }),
+            ...(0 === siblingListeners.length ? {} : { siblingListeners }),
+        };
+        const split = splitBrain(dir);
+        const next = nextActionFor({
+            everConnected,
+            initialized,
+            ...(configsElsewhere === undefined ? {} : { configsElsewhere }),
+            previouslyConnected,
+            exists: (file) => existsSync(join(dir, file)),
+            authRefused,
+            ...(helloRefused === undefined ? {} : { helloRefused: helloRefused.reason }),
+            ...(split === undefined ? {} : { splitBrain: split }),
+            listening: heard,
+            slowListeners: slow,
+            ...(known === undefined
+                ? {}
+                : {
+                    lastKnownUrl: known.url,
+                    ...(known.departedTo === undefined ? {} : { departedTo: known.departedTo }),
+                }),
+            dev: detectDevCommandInProject(dir),
+            init: initCommandIn(dir),
+        });
+        return { facts, next };
+    };
+    /**
+     * A call that named the client's project. Undefined means nobody named one (an embed, a test, a
+     * daemon answering itself), and the path below stays the one this watch was started with.
+     */
+    const callerAnswer = () => {
+        const caller = callingClientDirectory();
+        if (caller === undefined)
+            return undefined;
+        return diagnosisFor(caller);
+    };
+    /**
+     * `listening`, plus the departed session's port when no scan has looked at it since: not looked
+     * at is not stopped. Without it `reticle status` called a running Vite stopped because the only
+     * scan ran before the app was started.
+     */
+    const observedListening = () => {
+        const known = options.sessions.lastKnown?.();
+        const port = known === undefined ? undefined : portOfUrl(known.url);
+        return port === undefined || probed.has(port) || listening.includes(port)
+            ? listening
+            : [...listening, port];
+    };
     const nextAction = (scope) => {
         const split = splitBrain();
         return nextActionFor({
@@ -345,7 +483,8 @@ export function startNoSessionWatch(options) {
                 return refused === undefined ? {} : { helloRefused: refused.reason };
             })(),
             ...(split === undefined ? {} : { splitBrain: split }),
-            listening,
+            listening: observedListening(),
+            slowListeners,
             // The url the departed tab was on — the same tombstone the prose diagnosis quotes, so the
             // command and the sentence beside it name the same page.
             ...(() => {
@@ -360,13 +499,21 @@ export function startNoSessionWatch(options) {
             // Read when asked, like everything else here: a `package.json` can gain a dev script, and a
             // daemon that cached "there is none" at boot would keep saying so for the rest of the day.
             dev: detectDevCommandInProject(directory),
+            // This project's own runner and app folder, so the agent can wire it itself.
+            init: initCommandIn(directory),
         });
     };
-    options.sessions.setNoSessionNextAction(() => nextAction(projectScopeFacts()));
+    options.sessions.setNoSessionNextAction(() => {
+        const caller = callerAnswer();
+        return caller === undefined ? nextAction(projectScopeFacts()) : caller.next;
+    });
     // ONE call for both registrations below. The prose and the branch code have to come from the
     // same evaluation or they can describe different branches - the facts are read when asked, so two
     // calls a moment apart can genuinely disagree (#615).
     const explain = () => {
+        const caller = callerAnswer();
+        if (caller !== undefined)
+            return explainNoSession(caller.facts);
         const scope = projectScopeFacts();
         return explainNoSession({
             everConnected: options.sessions.everConnected(),
@@ -377,7 +524,7 @@ export function startNoSessionWatch(options) {
             // framework and its projectId, and whose real problem was a dev server older than the plugin.
             // The boot value still counts: it is the one the daemon scoped its sessions with.
             ...scope,
-            listening,
+            listening: observedListening(),
             slowListeners,
             port: options.port,
             // The directory `initialized` was decided in. Named in the message because "there is no
@@ -450,6 +597,16 @@ export function startNoSessionWatch(options) {
     // scope facts so a discovered workspace config cannot become an `init` recommendation below it,
     // and both come from ONE `explain()` call so they cannot describe different branches.
     const rendered = () => {
+        const caller = callerAnswer();
+        if (caller !== undefined) {
+            const { message, detail } = explainNoSession(caller.facts);
+            // The attach failure is about the daemon's own project. A call from that project still hears
+            // it. A call from another project must not be told that opening this one failed.
+            const callerDir = callingClientDirectory();
+            const ownProject = callerDir !== undefined && resolve(callerDir) === resolve(directory);
+            const lead = `${message} ${renderNextAction(caller.next)}${ownProject ? (attachFailure ?? '') : ''}`;
+            return { lead, full: undefined === detail ? lead : `${lead} ${detail}` };
+        }
         const scope = projectScopeFacts();
         const { message, detail } = explain();
         const lead = `${message} ${renderNextAction(nextAction(scope))}${attachFailure ?? ''}`;

package/dist/portal/session/presence/session-lease.js

@@ -8,7 +8,7 @@
  *
  * Any edit here is a per-session tax on every user: say it in as few words as still work.
  */
-const SESSION_LEASE_NOTICE = 'When you stop driving, call reticle_session {action:"yield", mode:"waiting"|"ask"}. The panel reads "live" until you do. {action:"end"} when the task is done; it revives on your next action.';
+const SESSION_LEASE_NOTICE = 'When you stop driving, call reticle_session {action:"yield", mode:"waiting"|"ask"}. The panel reads "live" until you do. {action:"end"} only when the task is done: it is final.';
 export function buildSessionLease(sessionId, openedAt) {
     return { sessionId, opened_at: openedAt, IMPORTANT: SESSION_LEASE_NOTICE };
 }