@reticlehq/server 3.3.0 → 3.4.0

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.

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

@@ -9,13 +9,14 @@
  * It only probes while NOTHING is connected. Once a session is live the question is moot, and a
  * daemon that outlives the agent by hours has no business scanning ports it does not need.
  */
+import { probeRouteStatus } from './dev-server/route-status-probe.js';
 import { probeDevServers, probeDevServerStates } from './dev-server/dev-server-probe.js';
 import { homedir } from 'node:os';
 import { registeredElsewhere } from '../../memory/recall/registered-projects.js';
 import { explainNoSession } from './no-session-diagnosis.js';
 import { detectDevCommand } from './dev-server/dev-command.js';
 import { nextActionFor, renderNextAction } from './no-session-next-action.js';
-import { readProjectFramework, readProjectId, readProjectPort, } from '../../command/cli/ports/resolve/cli-port.js';
+import { 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';
 import { isAlive, reticleStateHome } from '../../command/daemon/daemon.js';
@@ -24,6 +25,8 @@ import { stallUptime } from './stall-clock.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
 import { findOccupiedSiblings } from '../../command/cli/ports/sibling-ports.js';
 import { isAuthRefusalReason } from '../bridge/auth-failure-reason.js';
+import { devServersForProject } from '@reticlehq/core';
+import { readDevServers } from '../../command/daemon/dev-servers.js';
 /** Slow enough to be free, fast enough that a dev server started 15s ago is already reflected. */
 const REFRESH_MS = 15_000;
 /** The URL an auto-attach opens. `localhost` for the same reason the probe uses it: both stacks. */
@@ -63,6 +66,15 @@ export function startNoSessionWatch(options) {
      */
     let slowListeners = [];
     let siblingListeners = [];
+    /**
+     * What the last-known route answered, cached beside the port scan for the same reason the scan
+     * is cached: the hint is read synchronously, so every fact it carries has to be gathered before
+     * it is asked. Keyed by URL so a status is never attributed to a route other than the one it
+     * came from — a fresh departure on a different URL reads as "not asked yet", not as the old
+     * answer.
+     */
+    let lastKnownStatus;
+    const routeStatus = options.routeStatus ?? probeRouteStatus;
     let running = false;
     /** Ports auto-attach has already spent its one attempt on. Bounded: never a loop, never a retry. */
     const attempted = new Set();
@@ -155,6 +167,31 @@ export function startNoSessionWatch(options) {
      * Bounded by construction: one attempt per port per daemon. A failure is recorded, never retried —
      * a retry loop against a broken Chromium install would spin for the daemon's whole life.
      */
+    const ownDevServerPorts = options.ownDevServerPorts ??
+        (() => devServersForProject(readDevServers(stateDir), {
+            projectId: readProjectId(directory),
+            root: directory,
+        }).map((entry) => entry.port));
+    /**
+     * Is `port` demonstrably this project's app? Either its dev server announced it, or this
+     * project's own last session was on it. Anything else is a guess, and a guess that opens a
+     * browser is worse than the sentence the diagnosis already writes about the ports it saw.
+     */
+    const attributable = (port) => {
+        if (ownDevServerPorts().includes(port))
+            return true;
+        const known = options.sessions.lastKnown?.();
+        const projectId = readProjectId(directory);
+        if (known === undefined || projectId === undefined || known.projectId !== projectId) {
+            return false;
+        }
+        try {
+            return Number(new URL(known.url).port) === port;
+        }
+        catch {
+            return false;
+        }
+    };
     const autoAttach = async (ports) => {
         const attach = options.attach;
         if (attach === undefined)
@@ -166,6 +203,8 @@ export function startNoSessionWatch(options) {
             return;
         if (!isWired())
             return;
+        if (!attributable(only))
+            return;
         attempted.add(only);
         try {
             await attach(`${LOCALHOST}:${String(only)}`);
@@ -193,6 +232,14 @@ export function startNoSessionWatch(options) {
                     : options.probe === undefined
                         ? await findOccupiedSiblings(options.port, probeDaemon)
                         : [];
+            // Asked once per departed URL, on the same background cadence as the port scan, and never
+            // on the hint's own path. A url already answered is not asked again; a new departure is.
+            const known = options.sessions.lastKnown?.();
+            if (known !== undefined && lastKnownStatus?.url !== known.url) {
+                const status = await routeStatus(known.url);
+                if (status !== undefined)
+                    lastKnownStatus = { url: known.url, status };
+            }
             await autoAttach(ports);
         })
             .catch(() => {
@@ -225,6 +272,21 @@ export function startNoSessionWatch(options) {
      */
     const lastCloseWasAuthFailure = () => isAuthRefusalReason(options.sessions.lastClosure?.()?.reason) &&
         true !== options.sessions.connectedSinceLastClosure?.();
+    /**
+     * A hello refused for anything but its token, while it is still the bridge's current state.
+     *
+     * Only closures that carry the refused page count: the bridge attaches one exactly when a HELLO
+     * was turned away, so an origin or handshake-pool refusal (which has its own sentence on
+     * `resolve`) is not mistaken for one. Same ordering clause as the token refusal above.
+     */
+    const currentHelloRefusal = () => {
+        const closure = options.sessions.lastClosure?.();
+        if (closure?.page === undefined || isAuthRefusalReason(closure.reason))
+            return undefined;
+        if (true === options.sessions.connectedSinceLastClosure?.())
+            return undefined;
+        return { reason: closure.reason, ...closure.page };
+    };
     const nextAction = (scope) => {
         const split = splitBrain();
         return nextActionFor({
@@ -235,8 +297,18 @@ export function startNoSessionWatch(options) {
             // Read when asked, like every other fact here: a page can dial at any moment, and a daemon
             // that cached "nothing has been refused" at boot would keep saying so.
             authRefused: lastCloseWasAuthFailure(),
+            ...(() => {
+                const refused = currentHelloRefusal();
+                return refused === undefined ? {} : { helloRefused: refused.reason };
+            })(),
             ...(split === undefined ? {} : { splitBrain: split }),
             listening,
+            // 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.
+            ...(() => {
+                const known = options.sessions.lastKnown?.();
+                return known === undefined ? {} : { lastKnownUrl: known.url };
+            })(),
             // 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: detectDevCommand(directory),
@@ -272,12 +344,19 @@ export function startNoSessionWatch(options) {
             // beside it still said the tab had been closed. One fact, two answers, and only one of them
             // was right. Read when asked, like the rest: a page can be refused at any moment.
             authRefused: lastCloseWasAuthFailure(),
+            ...(() => {
+                const refused = currentHelloRefusal();
+                return refused === undefined ? {} : { helloRefused: refused };
+            })(),
             // Ranks the causes. Read when asked, like the rest: `init` writes this file after the daemon
             // starts on an ordinary first install.
             ...(() => {
                 const framework = readProjectFramework(directory);
                 return framework === undefined ? {} : { framework };
             })(),
+            // A desktop app is opened by its own dev command, never by a browser URL or a lease. Read when
+            // asked, like the framework: `init` may wire the app after this daemon started.
+            ...(readProjectIsDesktop(directory) ? { desktop: true } : {}),
             // Decided from the session that actually went away, not from a lifetime tally: the lease
             // sentence is only right when the thing that vanished WAS a lease.
             leaseExpired: (() => {
@@ -289,7 +368,14 @@ export function startNoSessionWatch(options) {
             // has none to name.
             ...(() => {
                 const known = options.sessions.lastKnown?.();
-                return undefined === known ? {} : { lastKnownUrl: known.url };
+                if (undefined === known)
+                    return {};
+                // The status rides only when it was fetched for THIS url. A departure since the fetch
+                // means the cached answer is about a route nobody is asking about.
+                const status = lastKnownStatus !== undefined && lastKnownStatus.url === known.url
+                    ? { lastKnownStatus: lastKnownStatus.status }
+                    : {};
+                return { lastKnownUrl: known.url, ...status };
             })(),
             // How long this daemon has been waiting with no app. The diagnosis uses it to surface
             // "install never finished" — the same condition telemetry already knows about.

package/dist/portal/session/session-health.js

@@ -29,7 +29,8 @@ export const PENDING_NAVIGATION_NOTICE_MS = 10_000;
  */
 const SKEW_VERDICT_WARNING = 'version skew: `dispatched` and `settled` on this session mean the event was sent, NOT that the ' +
     'app acted on it — a skewed pair drops actions silently. Re-read the control (aria-checked, ' +
-    'data-state, its text) before trusting any verdict from this session, and converge the versions:';
+    'data-state, its text) before trusting any verdict from this session, and converge the versions ' +
+    '(see session.versionSkew).';
 /**
  * The age of the oldest request that STARTED and never completed, or undefined when there is none
  * worth reporting.
@@ -100,7 +101,7 @@ export function healthEnvelope(session) {
     // a skewed link makes the ACTION unreliable, and there is no point warning about the quality of an
     // observation of something that may never have happened.
     if (health.versionSkew !== undefined) {
-        return { session: health, warning: `${SKEW_VERDICT_WARNING} ${health.versionSkew}` };
+        return { session: health, warning: SKEW_VERDICT_WARNING };
     }
     return health.throttled ? { session: health, warning: THROTTLED_WARNING } : { session: health };
 }

package/dist/portal/session/session-manager.d.ts

@@ -14,6 +14,17 @@ interface ResolveScope {
 }
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export declare function originOf(url: string | undefined): string | undefined;
+/** What a refused hello said about itself: the page it was on and the project it claimed. */
+export interface RefusedPage {
+    readonly url?: string;
+    readonly projectId?: string;
+}
+/** One bridge-initiated close, with the page that was turned away when the hello named one. */
+export interface ClosureRecord {
+    readonly at: number;
+    readonly reason: string;
+    readonly page?: RefusedPage;
+}
 export declare class SessionManager {
     #private;
     /** Set the active project's default resolve scope (called once at daemon wiring). */
@@ -57,13 +68,16 @@ export declare class SessionManager {
     setNoSessionNextAction(next: (() => NoSessionNextAction | undefined) | undefined): void;
     noSessionNextAction(): NoSessionNextAction | undefined;
     everConnected(): boolean;
-    /** Record a bridge-initiated close so `resolve` can explain a session that vanished. */
-    noteClosure(reason: string, at: number): void;
+    /**
+     * Record a bridge-initiated close so `resolve` can explain a session that vanished.
+     *
+     * `page` is what the refused hello said about itself, when it said anything. A refusal is the one
+     * piece of positive evidence the no-session diagnosis has, and "a page was refused" without WHICH
+     * page leaves the reader unable to tell their app from another project's tab on the same port.
+     */
+    noteClosure(reason: string, at: number, page?: RefusedPage): void;
     /** The most recent bridge-initiated close, if any. */
-    lastClosure(): {
-        at: number;
-        reason: string;
-    } | undefined;
+    lastClosure(): ClosureRecord | undefined;
     connectedSinceLastClosure(): boolean;
     /**
      * The id of the session that most recently went away, if any.

package/dist/portal/session/session-manager.js

@@ -325,9 +325,15 @@ export class SessionManager {
     everConnected() {
         return this.#everConnected;
     }
-    /** Record a bridge-initiated close so `resolve` can explain a session that vanished. */
-    noteClosure(reason, at) {
-        this.#recentClosures.push({ at, reason });
+    /**
+     * Record a bridge-initiated close so `resolve` can explain a session that vanished.
+     *
+     * `page` is what the refused hello said about itself, when it said anything. A refusal is the one
+     * piece of positive evidence the no-session diagnosis has, and "a page was refused" without WHICH
+     * page leaves the reader unable to tell their app from another project's tab on the same port.
+     */
+    noteClosure(reason, at, page) {
+        this.#recentClosures.push({ at, reason, ...(page === undefined ? {} : { page }) });
         if (this.#recentClosures.length > MAX_REMEMBERED_CLOSURES)
             this.#recentClosures.shift();
         this.#connectedSinceLastClosure = false;
@@ -512,6 +518,16 @@ export class SessionManager {
         const allThrottled = bestScore >= 1;
         const RECENCY_GAP_MS = allThrottled ? 0 : 1_000;
         const clearWinner = runnerUp === undefined || best.ms + RECENCY_GAP_MS < runnerUp.ms;
+        // Healthy tabs heartbeat on the same cadence, so the recency gap between two of them is noise.
+        // When exactly one has the window focus it is the one a human is looking at: tabs piled up one
+        // per `init` run, and every tool called without a sessionId was refused while one of them was
+        // plainly the tab in front. Only among healthy ones — focus says nothing about a wedged tab.
+        const focused = allThrottled ? [] : candidates.filter((x) => x.s.health().focused);
+        const [onlyFocused, secondFocused] = focused;
+        if (!clearWinner && onlyFocused !== undefined && secondFocused === undefined) {
+            onlyFocused.s.markAgentActivity();
+            return onlyFocused.s;
+        }
         if (!clearWinner) {
             // Ambiguous: list sessions with their health so the agent can choose.
             const detail = all

package/dist/portal/session/session-reaper.d.ts

@@ -22,6 +22,34 @@ export declare function composeEndedNotice(base: string, undelivered: string[]):
  * not a crash, since the agent is still connected and revives on its next action. Returns the ids.
  */
 export declare function reapIdleSessions(sessions: SessionManager): string[];
+/**
+ * Drop sessions that have ENDED, gone quiet and lost their socket, so a listing stops offering them.
+ *
+ * `reticle_session { action: "end" }` sets state and nothing else -- it never calls
+ * `sessions.remove`. `SessionManager.list()` does not filter by state, and `reapIdleSessions`
+ * above skips ended sessions by design. The only code path in the whole server that removes a
+ * session is the socket `close` handler in bridge.ts. So an ended session whose socket is already
+ * gone has nothing left that can remove it, and the row is listed for the life of the daemon
+ * (#938).
+ *
+ * That is what the field report describes: `{ ended: true }` three times, the row back on the next
+ * `reticle_sessions` call each time, still there after every tab on the origin was closed, 17 hours
+ * attached. And Reticle's own advice for a stale session is
+ * `Call reticle_session{action:"end"} to free this session` -- which is the one thing that does not
+ * free it.
+ *
+ * Deliberately NOT "remove on end". The panel is client-side, so `setState` has already pushed the
+ * ended state to the browser and the HUD keeps it; but `end` is documented idempotent, and removing
+ * immediately would make a second call fail to resolve. Waiting for the session to go quiet keeps
+ * that, keeps a just-ended session inspectable, and still collects the case that actually hurts: a
+ * row nobody can get rid of.
+ *
+ * Only once the socket is no longer open. An ended session whose tab is still connected but quiet
+ * belongs to a page that holds a live connection; dropping the record would orphan that socket,
+ * leaving a connection the daemon no longer tracks. Such a session is still removed the ordinary
+ * way, by the `close` handler, when the tab goes.
+ */
+export declare function reapEndedSessions(sessions: SessionManager, staleAfterMs?: number): string[];
 /** End every active session immediately (the agent / MCP client disconnected → WARN). Returns ended ids. */
 export declare function endAllSessions(sessions: SessionManager, reason: string): string[];
 /**

package/dist/portal/session/session-reaper.js

@@ -1,4 +1,4 @@
-import { PresenterTone, SESSION_LIFECYCLE, UNDELIVERED_NOTES_LABEL } from '@reticlehq/core';
+import { PresenterTone, SESSION_LEASE, SESSION_LIFECYCLE, UNDELIVERED_NOTES_LABEL, } from '@reticlehq/core';
 import { log } from '../../log.js';
 /**
  * Server-authoritative session liveness. The browser idle timer is throttled in a backgrounded tab
@@ -51,6 +51,50 @@ export function reapIdleSessions(sessions) {
         log('session_reaped_idle', { sessions: ended });
     return ended;
 }
+/**
+ * Drop sessions that have ENDED, gone quiet and lost their socket, so a listing stops offering them.
+ *
+ * `reticle_session { action: "end" }` sets state and nothing else -- it never calls
+ * `sessions.remove`. `SessionManager.list()` does not filter by state, and `reapIdleSessions`
+ * above skips ended sessions by design. The only code path in the whole server that removes a
+ * session is the socket `close` handler in bridge.ts. So an ended session whose socket is already
+ * gone has nothing left that can remove it, and the row is listed for the life of the daemon
+ * (#938).
+ *
+ * That is what the field report describes: `{ ended: true }` three times, the row back on the next
+ * `reticle_sessions` call each time, still there after every tab on the origin was closed, 17 hours
+ * attached. And Reticle's own advice for a stale session is
+ * `Call reticle_session{action:"end"} to free this session` -- which is the one thing that does not
+ * free it.
+ *
+ * Deliberately NOT "remove on end". The panel is client-side, so `setState` has already pushed the
+ * ended state to the browser and the HUD keeps it; but `end` is documented idempotent, and removing
+ * immediately would make a second call fail to resolve. Waiting for the session to go quiet keeps
+ * that, keeps a just-ended session inspectable, and still collects the case that actually hurts: a
+ * row nobody can get rid of.
+ *
+ * Only once the socket is no longer open. An ended session whose tab is still connected but quiet
+ * belongs to a page that holds a live connection; dropping the record would orphan that socket,
+ * leaving a connection the daemon no longer tracks. Such a session is still removed the ordinary
+ * way, by the `close` handler, when the tab goes.
+ */
+export function reapEndedSessions(sessions, staleAfterMs = SESSION_LEASE.STALE_AFTER_MS) {
+    const dropped = [];
+    // Snapshot first: `remove` mutates the map this iterates.
+    for (const session of [...sessions.all()]) {
+        if (!session.isEnded())
+            continue;
+        if (session.socketOpen())
+            continue;
+        if (session.staleMs() < staleAfterMs)
+            continue;
+        if (sessions.remove(session))
+            dropped.push(session.id);
+    }
+    if (dropped.length > 0)
+        log('session_reaped_ended', { sessions: dropped });
+    return dropped;
+}
 /** End every active session immediately (the agent / MCP client disconnected → WARN). Returns ended ids. */
 export function endAllSessions(sessions, reason) {
     const ended = [];
@@ -81,6 +125,10 @@ export class SessionReaper {
             return;
         this.#timer = setInterval(() => {
             reapIdleSessions(this.#sessions);
+            // Second rule, same sweep, kept as its own function: one ends a live session that went
+            // quiet, the other collects one that already ended. Merging them would put "end this" and
+            // "forget this" behind a single condition.
+            reapEndedSessions(this.#sessions);
         }, this.#intervalMs);
         this.#timer.unref();
     }