@reticlehq/server 3.9.0 → 3.10.1

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

@@ -55,8 +55,9 @@ 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)
+    if (true === facts.desktop) {
         return DESKTOP_NO_BROWSER;
+    }
     const caveat = leaseCaveat(facts.leaseBrowser);
     return caveat === undefined ? base : `${base} ${caveat}`;
 }
@@ -87,12 +88,14 @@ const TAB_GONE_WHAT = 'The tab was closed, navigated away, or hard-reloaded.';
  * page down is no longer the same dead end as "the human closed the tab".
  */
 function tabGoneWhat(url) {
-    if (undefined === url || '' === url)
+    if (undefined === url || '' === url) {
         return TAB_GONE_WHAT;
+    }
     const torn = pageTornDownWhileOn(url);
     const first = torn.charAt(0);
-    if ('' === first)
+    if ('' === first) {
         return TAB_GONE_WHAT;
+    }
     return `${first.toUpperCase()}${torn.slice(1)}. ${TAB_GONE_WHAT}`;
 }
 /**
@@ -158,6 +161,12 @@ const DO_NOT_REINSTALL = 'Re-running the install is the wrong move here: it cann
  * evidence that was never gathered.
  */
 const SCANNED_PORTS = [...DEV_SERVER_PORTS].join(', ');
+/**
+ * The project's own sources the scan adds to the well-known list (reticle#1367, reticle#1543).
+ *
+ * Named in the "nothing else" sentences so that "the scan is partial" says what it did check.
+ */
+const PROJECT_PORT_SOURCES = "the port in this project's dev script and `.env` files, and the ports of earlier sessions";
 /**
  * How to say "open the app" to an agent that may have no `reticle` binary.
  *
@@ -180,8 +189,9 @@ const INIT_CMD = '`npx @reticlehq/server init`';
  */
 function slowListenerClause(facts, after = '') {
     const slow = facts.slowListeners ?? [];
-    if (0 === slow.length)
+    if (0 === slow.length) {
         return '';
+    }
     const ports = slow.join(', ');
     const subject = 1 === slow.length ? `Port ${ports} ACCEPTED` : `Ports ${ports} ACCEPTED`;
     return (`${subject} a connection but did not answer in time, which is what a server-rendered dev ` +
@@ -216,6 +226,22 @@ function openTheApp(facts) {
 function orOpenCommand(facts) {
     return true === facts.desktop ? '' : ` (or run ${OPEN_CMD_BARE})`;
 }
+/**
+ * The start advice's lead when processes in this folder listen. Empty when none do.
+ *
+ * Names ports and no URL. It ends where the caller's "start it" begins, so an agent whose listeners
+ * are only its own tools still gets the app started.
+ */
+function folderListenerClause(facts) {
+    const ports = facts.folderListeners ?? [];
+    if (0 === ports.length) {
+        return '';
+    }
+    const named = ports.map((port) => `:${String(port)}`).join(', ');
+    return (`No port Reticle scans serves a page, but processes in this folder listen on ${named}. ` +
+        'Reticle cannot tell if one is this app, because agent tools listen here too. ' +
+        'If one of them IS this app, open its URL. If none is, ');
+}
 /**
  * What a machine-wide port scan can and cannot say.
  *
@@ -224,7 +250,14 @@ function orOpenCommand(facts) {
  * is up and never dialled" is unsound: those ports can belong to anything, and the app's own port
  * may not be in the scanned set at all.
  */
-function unattributedListeners(listening) {
+function unattributedListeners(facts) {
+    const { listening } = facts;
+    const folder = facts.folderListeners ?? [];
+    if (0 < folder.length && 0 === listening.length) {
+        const named = folder.map((port) => `:${String(port)}`).join(', ');
+        return (`No port the scan covers serves a page, but processes in this folder listen on ${named}. ` +
+            'Reticle cannot tell if one is this app, because agent tools listen here too.');
+    }
     if (0 === listening.length) {
         return (`No listener found that I can attribute to this project: the scan covers ${SCANNED_PORTS} ` +
             'across the whole machine, so an app on any other port is invisible to it.');
@@ -242,8 +275,9 @@ function unattributedListeners(listening) {
  */
 function portMismatchClause(facts) {
     const configured = facts.projectPort;
-    if (configured === undefined || configured === facts.port)
+    if (configured === undefined || configured === facts.port) {
         return '';
+    }
     return (` They already disagree: \`.reticle.json\` says port ${String(configured)} and this daemon is` +
         ` on ${String(facts.port)}, so the SDK is dialling ${String(configured)} and nothing is there.` +
         ` Either restart the daemon on ${String(configured)}, or update \`.reticle.json\` to` +
@@ -258,8 +292,9 @@ function portMismatchClause(facts) {
  */
 function siblingListenerClause(facts) {
     const occupied = facts.siblingListeners ?? [];
-    if (0 === occupied.length)
+    if (0 === occupied.length) {
         return '';
+    }
     const mismatch = facts.projectPort;
     const extra = mismatch !== undefined && mismatch !== facts.port
         ? occupied.filter((port) => port !== mismatch)
@@ -291,8 +326,9 @@ function rankedCauses(facts) {
  */
 function configsElsewhereClause(facts) {
     const configs = facts.configsElsewhere ?? [];
-    if (0 === configs.length)
+    if (0 === configs.length) {
         return '';
+    }
     const named = configs
         .map((c) => (c.projectId === undefined ? c.directory : `${c.directory} ('${c.projectId}')`))
         .join(', ');
@@ -303,10 +339,12 @@ function configsElsewhereClause(facts) {
 /** Where we looked, when we found nothing. An absence nobody can check is not evidence. */
 function searchedClause(facts) {
     const searched = facts.searchedDirectories ?? [];
-    if (0 === searched.length)
+    if (0 === searched.length) {
         return '';
-    if ((facts.configsElsewhere ?? []).length > 0)
+    }
+    if ((facts.configsElsewhere ?? []).length > 0) {
         return '';
+    }
     return ` I looked in: ${searched.join(', ')}. If your app is not in that list, that is the answer — this daemon is standing somewhere else.`;
 }
 /**
@@ -318,20 +356,24 @@ function searchedClause(facts) {
  */
 function stallClause(facts) {
     const { daemonUpMs, initialized, everConnected } = facts;
-    if (everConnected)
+    if (everConnected) {
         return '';
-    if (!initialized)
+    }
+    if (!initialized) {
         return '';
-    if (daemonUpMs === undefined || daemonUpMs < STALL_AFTER_MS)
+    }
+    if (daemonUpMs === undefined || daemonUpMs < STALL_AFTER_MS) {
         return '';
+    }
     const minutes = Math.round(daemonUpMs / 60_000);
     return (`This daemon has been running for ${String(minutes)} minutes and no app has connected. ` +
         'The most likely cause is that the dev server was not restarted after adding the Reticle ' +
         'plugin, so the running bundle carries no SDK. Restart the dev server first. ');
 }
 function alreadyListeningClause(listening) {
-    if (0 === listening.length)
+    if (0 === listening.length) {
         return '';
+    }
     if (1 === listening.length) {
         const port = listening[0];
         return (` Something is serving a page on :${String(port)}; it may not be this app — just open ` +
@@ -450,9 +492,9 @@ export function explainNoSession(facts) {
     // wiring is unproven, printed by a daemon holding proof that it is.
     if (true === facts.previouslyConnected) {
         const listeners = 0 === listening.length
-            ? `${unattributedListeners(listening)} If the dev server is not running, start it first ` +
+            ? `${unattributedListeners(facts)} If the dev server is not running, start it first ` +
                 '(the command is in `next_action`).'
-            : unattributedListeners(listening);
+            : unattributedListeners(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
@@ -461,7 +503,7 @@ export function explainNoSession(facts) {
     if (!initialized && (facts.configsElsewhere ?? []).length > 0) {
         return reason(NoSessionReason.CONFIG_ELSEWHERE, 'no browser session connected, and this daemon has never seen one. ' +
             `${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)} ` +
+            `an editor launches it from your home directory. ${unattributedListeners(facts)} ` +
             `${rankedCauses(facts)}`);
     }
     if (0 === listening.length) {
@@ -481,12 +523,12 @@ export function explainNoSession(facts) {
         // is expected rather than diagnostic.
         if (!initialized) {
             return reason(NoSessionReason.NO_LISTENER_NO_CONFIG, 'no browser session connected. Two things to weigh, and neither of them is proof. ' +
-                `(1) ${slowListenerClause(facts, ' Setting that aside: ')}Nothing is listening on the ports Reticle scans, so the ` +
-                'dev server may not be running: START IT YOURSELF, in the background, using the command ' +
+                `(1) ${slowListenerClause(facts, ' Setting that aside: ')}${folderListenerClause(facts) ||
+                    'Nothing is listening on the ports Reticle scans, so the 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. ` +
-                `${ZERO_INSTALL} ${RETRY}`, `The scan covers ${SCANNED_PORTS} and nothing else, so a server on any other port is ` +
+                `${ZERO_INSTALL} ${RETRY}`, `The scan covers ${SCANNED_PORTS}, plus ${PROJECT_PORT_SOURCES}, 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 ' +
@@ -501,15 +543,15 @@ export function explainNoSession(facts) {
                 `Wait for the first compile to finish, then open the app (the command is in \`next_action\`). ${RETRY}`, `${leaseAdvice(URL_THEN_LEASE, facts)}${siblingListenerClause(facts)}`);
         }
         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 ' +
+            `${folderListenerClause(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 ' +
             `browser. ${RETRY}`, 
         // The caveat is in the detail rather than omitted because the scan is NARROW: an empty result
         // is not proof of absence. Reported twice, once against a server answering 200 on :7699 and
         // once against one on :5000 under a custom hostname. The common defaults are in the scanned
         // set, which narrows the gap and cannot close it — anything passed to `--port` is invisible.
-        `The scan covers ${SCANNED_PORTS} and nothing else, so it is not proof: a server on any other ` +
+        `The scan covers ${SCANNED_PORTS}, plus ${PROJECT_PORT_SOURCES}, and nothing else, so it is not proof: a server on any other ` +
             'port is invisible to it. If the app IS running, ask the human for its URL rather than ' +
             // Deliberately NOT offering reticle_lease here, and a test pins that: a lease opens a URL, and
             // if nothing is listening there is nothing at any URL to open. Asking for the real one is the
@@ -526,11 +568,11 @@ export function explainNoSession(facts) {
             'there and restart the dev server; if it has one, the app is wired and simply has no page ' +
             `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)}`);
+            `plugin. ${unattributedListeners(facts)}${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. ${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)}`);
+        `is not reaching this daemon (on ${String(port)}). ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, `${unattributedListeners(facts)} ${rankedCauses(facts)}`);
 }
 /**
  * Pair a branch's verdict with its prose, so neither can be produced without the other.

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

@@ -30,6 +30,8 @@ interface NextActionFacts {
     listening: readonly number[];
     /** Scanned ports that serve a page from a process that cannot be tied to this project. */
     otherListeners?: readonly number[];
+    /** Ports that processes in this folder listen on. See `NoSessionFacts.folderListeners`. */
+    folderListeners?: readonly number[];
     dev: DevCommand | undefined;
     /**
      * File-existence predicate for the project root, pure for testing.

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

@@ -114,7 +114,15 @@ function neverWired(facts) {
  * The start advice's first claim when no port is this project's. A scan that heard a page it could
  * not tie to this project says so, because "nothing is listening" is then false.
  */
-function notThisProject(others) {
+function notThisProject(others, folder = []) {
+    // First: the folder is nearer to this app than a machine-wide scan. It is still no URL to hand
+    // over, because agent tools listen in this folder too (reticle#1543).
+    if (0 < folder.length) {
+        const ports = folder.map((port) => `:${String(port)}`).join(', ');
+        return (`processes in this folder listen on ${ports}, and Reticle cannot tell if one is this app, ` +
+            'because agent tools listen here too — if one of them IS this app, open it instead of ' +
+            'starting a second one, ');
+    }
     if (others === undefined || 0 === others.length) {
         return 'nothing is listening on the ports Reticle scans, so the app is probably not running — ';
     }
@@ -279,9 +287,10 @@ export function nextActionFor(facts) {
         const stoppedNote = stopped === undefined
             ? ''
             : ` The session that was on ${redactUrl(stopped.url)} is gone and nothing listens there now.`;
-        const notRunning = departedPortIsGone
+        const folder = facts.folderListeners ?? [];
+        const notRunning = departedPortIsGone && 0 === folder.length
             ? "nothing answers on the port this project's app was last on, so the app is probably not running — "
-            : notThisProject(facts.otherListeners);
+            : notThisProject(facts.otherListeners, folder);
         if (dev === undefined) {
             const childApps = facts.childApps ?? [];
             if (1 < childApps.length) {

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

@@ -74,6 +74,12 @@ interface NoSessionWatchOptions {
      * to it. Injected for tests; a test that injects `probe` and omits this observes no folder.
      */
     listenerDirectory?: (port: number) => string | undefined;
+    /**
+     * Every TCP port on this machine with a listener (reticle#1543).
+     *
+     * Injected for tests; a test that injects `probe` and omits this observes no listener.
+     */
+    listeningPorts?: () => 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.

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, resolve } from 'node:path';
+import { join, parse, 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 { childDevApps, detectDevCommandInProject, initCommandIn, } from './dev-server/dev-command.js';
+import { envFilePorts } from './dev-server/project-ports.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';
@@ -27,10 +28,11 @@ import { daemonsServingProjectElsewhere, projectDaemonsElsewhere, projectlessNot
 import { stallUptime } from './stall-clock.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
 import { findOccupiedSiblings } from '../../command/cli/ports/sibling-ports.js';
+import { captureLookup, findListeningPorts } from '../../command/cli/ports/port-holder.js';
 import { isAuthRefusalReason } from '../bridge/auth-failure-reason.js';
 import { devServersForProject } from '@reticlehq/core';
 import { readDevServers } from '../../command/daemon/dev-servers.js';
-import { servingDirectoryOf } from './serving-directory.js';
+import { listenerFolders, servingDirectoryOf } from './serving-directory.js';
 import { within } from './zero-install-first-call.js';
 /** Slow enough to be free, fast enough that a dev server started 15s ago is already reflected. */
 const REFRESH_MS = 15_000;
@@ -77,6 +79,16 @@ export function startNoSessionWatch(options) {
         (options.probe === undefined
             ? (port) => servingDirectoryOf(`${LOCALHOST}:${String(port)}`)
             : () => undefined);
+    const listeningPorts = options.listeningPorts ??
+        (options.probe === undefined
+            ? () => findListeningPorts(captureLookup)
+            : () => []);
+    /**
+     * The folder of each listener outside `listening`, `slowListeners` and the Reticle daemons.
+     *
+     * Beside `listenerDirs` and never in `listening`: see `NoSessionFacts.folderListeners`.
+     */
+    let unscannedFolders = new Map();
     let siblingListeners = [];
     /**
      * What the last-known route answered, cached beside the port scan for the same reason the scan
@@ -163,7 +175,7 @@ export function startNoSessionWatch(options) {
         if (projectId === undefined) {
             return projectlessNote(options.port, projectDaemonsElsewhere(options.port, stateDir, isAlive));
         }
-        return splitBrainNote(options.port, daemonsServingProjectElsewhere(projectId, options.port, stateDir, isAlive, (port) => hasProjectConnectedBefore(stateDir, port, projectId)));
+        return splitBrainNote(options.port, daemonsServingProjectElsewhere(projectId, options.port, stateDir, isAlive, (port) => hasProjectConnectedBefore(stateDir, port, projectId)), { projectId, home: stateDir });
     };
     // Every path that registers a session goes through SessionManager.add, so this is the one hook
     // that makes the bit durable. Recorded per port + projectId so a shared 4400 cannot make one
@@ -208,6 +220,10 @@ export function startNoSessionWatch(options) {
         if (pinned !== undefined) {
             ports.add(pinned);
         }
+        // A script that reads its port from `.env` pins nothing in `package.json` (reticle#1543).
+        for (const port of envFilePorts(directory)) {
+            ports.add(port);
+        }
         const known = options.sessions.lastKnown?.();
         const knownPort = known === undefined ? undefined : portOfUrl(known.url);
         if (knownPort !== undefined) {
@@ -223,6 +239,19 @@ export function startNoSessionWatch(options) {
         }
         return [...ports];
     };
+    /**
+     * The ports that processes in `dir` listen on, without the ones in `shown`.
+     *
+     * Nothing for the home folder or a filesystem root. A daemon an editor starts there holds every
+     * process on the machine inside its "folder", so the answer would prove nothing.
+     */
+    const folderListeners = (dir, shown) => {
+        const folder = resolve(dir);
+        if (folder === homedir() || folder === parse(folder).root) {
+            return [];
+        }
+        return [...unscannedFolders.entries()].flatMap(([port, cwd]) => within(cwd, folder) && !shown.includes(port) ? [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
@@ -300,6 +329,8 @@ export function startNoSessionWatch(options) {
                     : options.probe === undefined
                         ? await findOccupiedSiblings(options.port, probeDaemon)
                         : [];
+            const reported = new Set([options.port, ...siblingListeners, ...ports, ...slowListeners]);
+            unscannedFolders = listenerFolders(listeningPorts().filter((port) => !reported.has(port)), unscannedFolders, listenerDirectory);
             // 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?.();
@@ -447,6 +478,7 @@ export function startNoSessionWatch(options) {
                 : {}),
             listening: heard,
             slowListeners: slow,
+            folderListeners: folderListeners(dir, heard),
             port: options.port,
             directory: dir,
             previouslyConnected,
@@ -473,6 +505,7 @@ export function startNoSessionWatch(options) {
             listening: heard,
             ...(0 === others.length ? {} : { otherListeners: others }),
             slowListeners: slow,
+            folderListeners: folderListeners(dir, heard),
             ...(known === undefined
                 ? {}
                 : {
@@ -526,6 +559,7 @@ export function startNoSessionWatch(options) {
             ...(split === undefined ? {} : { splitBrain: split }),
             listening: observedListening(),
             slowListeners,
+            folderListeners: folderListeners(directory, observedListening()),
             // 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.
             ...(() => {
@@ -570,6 +604,7 @@ export function startNoSessionWatch(options) {
             ...scope,
             listening: observedListening(),
             slowListeners,
+            folderListeners: folderListeners(directory, observedListening()),
             port: options.port,
             // The directory `initialized` was decided in. Named in the message because "there is no
             // `.reticle.json`" is a claim about ONE directory, and a reader standing somewhere else

package/dist/portal/session/serving-directory.d.ts

@@ -37,6 +37,16 @@ export interface DevProxy {
  * only: a remote page's port says nothing about any process on this machine.
  */
 export declare function servingDirectoryOf(origin: string, io?: ServingDirectoryIo): string | undefined;
+/** How many ports one scan asks about. Each lookup blocks the daemon for two `lsof` runs. */
+export declare const MAX_FOLDER_LOOKUPS = 16;
+/**
+ * The folder of each port in `ports`, or undefined when it cannot be read.
+ *
+ * `known` is the last scan's answer. A port that stays open keeps it, so a machine with many
+ * listeners pays once. A port past the bound waits for the next scan. A closed port leaves the map,
+ * so the next process on it is asked about.
+ */
+export declare function listenerFolders(ports: readonly number[], known: ReadonlyMap<number, string | undefined>, directoryOf: (port: number) => string | undefined): Map<number, string | undefined>;
 /**
  * The live answers for a worktree-scoped resolve: the calling agent's checkout (from the directory
  * its MCP proxy runs in) and each tab's checkout (from the dev server that served it).

package/dist/portal/session/serving-directory.js

@@ -40,13 +40,15 @@ function readOrUndefined(path) {
 function readPortless() {
     const dir = process.env[PORTLESS_STATE_DIR_ENV] ?? join(homedir(), PORTLESS_STATE_DIR);
     const port = Number(readOrUndefined(join(dir, PORTLESS_PORT_FILE))?.trim());
-    if (!Number.isInteger(port))
+    if (!Number.isInteger(port)) {
         return undefined;
+    }
     let routes = [];
     try {
         const parsed = PortlessRoutesSchema.safeParse(JSON.parse(readOrUndefined(join(dir, PORTLESS_ROUTES_FILE)) ?? '[]'));
-        if (parsed.success)
+        if (parsed.success) {
             routes = parsed.data;
+        }
     }
     catch {
         // A table being rewritten reads as empty: the page stays unplaced, never placed wrong.
@@ -75,27 +77,55 @@ export function servingDirectoryOf(origin, io = liveIo) {
     catch {
         return undefined;
     }
-    if (!isLoopbackHostname(url.hostname) && !isLocalhostSubdomain(url.hostname))
+    if (!isLoopbackHostname(url.hostname) && !isLocalhostSubdomain(url.hostname)) {
         return undefined;
+    }
     // Exact first: a dev proxy serves every worktree on one port, under the name it announced.
     const byUrl = io.devServers().find((entry) => originOf(entry.url) === url.origin);
-    if (byUrl !== undefined)
+    if (byUrl !== undefined) {
         return byUrl.root;
+    }
     const pagePort = '' === url.port ? DEFAULT_PORT[url.protocol] : Number(url.port);
-    if (pagePort === undefined)
+    if (pagePort === undefined) {
         return undefined;
+    }
     // Behind a dev proxy the page's port is the proxy's, and `lsof` on it names the proxy's folder.
     // The proxy's route table names the dev server's own port.
     const proxy = isLocalhostSubdomain(url.hostname) ? io.devProxy?.() : undefined;
     const route = proxy?.routes.find((r) => r.hostname === url.hostname.toLowerCase());
-    if (route === undefined && true === proxy?.ports.includes(pagePort))
+    if (route === undefined && true === proxy?.ports.includes(pagePort)) {
         return undefined;
+    }
     const port = route?.port ?? pagePort;
     const announced = io.devServers().find((entry) => entry.port === port);
-    if (announced !== undefined)
+    if (announced !== undefined) {
         return announced.root;
+    }
     return io.listenerCwd(port) ?? undefined;
 }
+/** How many ports one scan asks about. Each lookup blocks the daemon for two `lsof` runs. */
+export const MAX_FOLDER_LOOKUPS = 16;
+/**
+ * The folder of each port in `ports`, or undefined when it cannot be read.
+ *
+ * `known` is the last scan's answer. A port that stays open keeps it, so a machine with many
+ * listeners pays once. A port past the bound waits for the next scan. A closed port leaves the map,
+ * so the next process on it is asked about.
+ */
+export function listenerFolders(ports, known, directoryOf) {
+    const folders = new Map();
+    let lookups = 0;
+    for (const port of ports) {
+        if (known.has(port)) {
+            folders.set(port, known.get(port));
+        }
+        else if (lookups < MAX_FOLDER_LOOKUPS) {
+            lookups += 1;
+            folders.set(port, directoryOf(port));
+        }
+    }
+    return folders;
+}
 /** The checkout whose dev server serves `origin` right now, or undefined. */
 function checkoutServing(origin) {
     const serving = servingDirectoryOf(origin);
@@ -122,8 +152,9 @@ export function liveCheckoutSource(placeOrigin = checkoutServing) {
                 : undefined;
         },
         ofTab: (tab) => {
-            if (placed.has(tab))
+            if (placed.has(tab)) {
                 return placed.get(tab);
+            }
             const origin = originOf(tab.url);
             const checkout = origin === undefined ? undefined : placeOrigin(origin);
             placed.set(tab, checkout);

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

@@ -64,6 +64,8 @@ export declare class SessionManager {
     isParked(sessionId: string): boolean;
     remove(session: Session): boolean;
     get(sessionId: string): Session | undefined;
+    /** The id the same tab connected as after this session's page went away, if one has. */
+    successorId(sessionId: string): string | undefined;
     /**
      * Did this id belong to a session that has since disconnected?
      *
@@ -149,6 +151,14 @@ export declare class SessionManager {
     /** Every departed session's URL, oldest first. The port scan has to see all of them, not only the newest. */
     tombstoneUrls(): readonly string[];
     resolve(sessionId?: string, scope?: ResolveScope): Session;
+    /**
+     * Resolve the session for a call that only some sessions can serve.
+     *
+     * With no sessionId, resolve() chooses by health and recency alone. A lease that could resize the
+     * page lost to a focused tab that could not, and the call was refused (#1959). Here, when exactly
+     * one candidate can serve the call, that candidate is chosen.
+     */
+    resolveServing(sessionId: string | undefined, canServe: (session: Session) => boolean | Promise<boolean>): Promise<Session>;
 }
 export interface Tab {
     id: string;