@reticlehq/server 3.8.2 → 3.10.0

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.
  *
@@ -178,15 +187,16 @@ const INIT_CMD = '`npx @reticlehq/server init`';
  * against it, and it has to be read before the "nothing is listening" sentence rather than after —
  * the reader acts on the first claim.
  */
-function slowListenerClause(facts) {
+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 ` +
         'server compiling its first route looks like — so something IS running there and you should ' +
-        'open it rather than start it. Setting that aside: ');
+        `open it rather than start it.${after}`);
 }
 /**
  * The commonest first-run state there is (#320).
@@ -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,28 +523,35 @@ 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)}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 ' +
                 'the Vite or Babel plugin carries the SDK without that file at all.' +
                 `${searchedClause(facts)}${siblingListenerClause(facts)} ${leaseAdvice(URL_THEN_LEASE, facts)}`);
         }
+        // A wired project whose own port accepted a connection and answered nothing yet is compiling,
+        // not down. "Start it yourself" here starts a second dev server.
+        if ((facts.slowListeners ?? []).length > 0) {
+            return reason(NoSessionReason.NO_LISTENER, `${stallClause(facts)}no browser session connected, and this daemon has never seen one. ` +
+                `${slowListenerClause(facts)} Do not start a second dev server. ` +
+                `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
@@ -519,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.
@@ -102,6 +104,11 @@ interface NextActionFacts {
      * project's own runner (see `initCommandIn`). Absent means the generic npx spelling.
      */
     init?: string;
+    /**
+     * Several direct child folders are apps with a dev script, and this folder has no package.json.
+     * Absent or short means there is no choice to hand the agent. See `childDevApps`.
+     */
+    childApps?: readonly string[];
 }
 /** The port a tombstone URL names, when it names one — anything unparseable names no port. */
 export declare function portOfUrl(url: string): number | undefined;
@@ -123,6 +130,13 @@ export declare const INIT_COMMAND = "npx @reticlehq/server init";
  * agent asks first. The lease changes nothing, so it needs no question.
  */
 export declare function wiringConsent(init?: string): string;
+/**
+ * The offer for the first session in an unwired web app: check it now with the lease, then ask
+ * before `init`. The one text for the plugin's SessionStart hook and the first tool call of each
+ * agent connection. The hook cannot import this, so it keeps a copy, and
+ * `plugin-init-nudge.test.ts` fails when the two are not the same.
+ */
+export declare function firstSessionOffer(init?: string): string;
 /** The zero-install call, with the URL only when it can be named without guessing. */
 export declare function zeroInstallLease(url: string | undefined): string;
 export declare function nextActionFor(facts: NextActionFacts): NoSessionNextAction;

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

@@ -18,8 +18,9 @@ import { detectNonJsEcosystem, noPackageJsonMessage } from '@reticlehq/init';
 export function portOfUrl(url) {
     try {
         const raw = new URL(url).port;
-        if ('' === raw)
+        if ('' === raw) {
             return undefined;
+        }
         const port = Number(raw);
         return Number.isSafeInteger(port) && port > 0 ? port : undefined;
     }
@@ -45,8 +46,9 @@ export function departedPortGone(facts) {
  * 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)
+    if (raw === undefined) {
         return undefined;
+    }
     let url;
     try {
         url = new URL(raw);
@@ -54,10 +56,12 @@ function reopenableUrl(raw) {
     catch {
         return undefined;
     }
-    if ('http:' !== url.protocol && 'https:' !== url.protocol)
+    if ('http:' !== url.protocol && 'https:' !== url.protocol) {
         return undefined;
-    for (const param of Object.values(RETICLE_URL_PARAM))
+    }
+    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 };
 }
@@ -78,6 +82,17 @@ export function wiringConsent(init = INIT_COMMAND) {
         'build config and starts the dev server. Ask the user before you wire the app. If they ' +
         `agree, run \`${init}\` in the app's folder. If they decline, do not ask again.`);
 }
+/**
+ * The offer for the first session in an unwired web app: check it now with the lease, then ask
+ * before `init`. The one text for the plugin's SessionStart hook and the first tool call of each
+ * agent connection. The hook cannot import this, so it keeps a copy, and
+ * `plugin-init-nudge.test.ts` fails when the two are not the same.
+ */
+export function firstSessionOffer(init = INIT_COMMAND) {
+    return (`This web app can be checked now with no install: \`${zeroInstallLease(undefined)}\` opens ` +
+        "the running app in Reticle's own browser and changes no file. To keep Reticle wired to this " +
+        `app: ${wiringConsent(init)}`);
+}
 const OPEN_COMMAND = `${CLI} open`;
 const LOCALHOST = 'http://localhost';
 /**
@@ -99,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 — ';
     }
@@ -243,6 +266,19 @@ export function nextActionFor(facts) {
                 'args: { action: "acquire", url, projectId } }, or restart the daemon from the app\'s own directory.',
         };
     }
+    // A wired project whose only port accepted a connection and answered nothing yet: a dev server
+    // compiling its first route. It is up, so a start command would start a second one.
+    const compiling = facts.slowListeners?.[0];
+    if (true === facts.initialized && 0 === facts.listening.length && compiling !== undefined) {
+        return {
+            action: NoSessionAction.OPEN_APP,
+            command: `${OPEN_COMMAND} ${LOCALHOST}:${String(compiling)}`,
+            port: compiling,
+            reason: `port ${String(compiling)} accepted a connection but did not answer in time, which is a dev ` +
+                'server compiling its first route. The app IS running. Do not start a second dev server. ' +
+                'Wait for the compile to finish, then open it.',
+        };
+    }
     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
@@ -251,10 +287,23 @@ 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) {
+                return {
+                    action: NoSessionAction.START_DEV_SERVER,
+                    reason: notRunning +
+                        `but this folder has no package.json, and ${childApps.length} child folders are apps ` +
+                        `with a dev script: ${childApps.join(', ')}. Reticle cannot tell which one you mean, so ` +
+                        'there is no command to hand you. Pick one, then run Reticle from that folder or ask ' +
+                        'the human which app to start.' +
+                        stoppedNote,
+                };
+            }
             if (facts.exists !== undefined && !facts.exists('package.json')) {
                 const ecosystem = detectNonJsEcosystem(facts.exists);
                 if (ecosystem !== undefined) {

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 { detectDevCommandInProject, initCommandIn } from './dev-server/dev-command.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
                 ? {}
                 : {
@@ -480,6 +513,7 @@ export function startNoSessionWatch(options) {
                     ...(known.departedTo === undefined ? {} : { departedTo: known.departedTo }),
                 }),
             dev: detectDevCommandInProject(dir),
+            childApps: childDevApps(dir),
             init: initCommandIn(dir),
         });
         return { facts, next };
@@ -525,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.
             ...(() => {
@@ -540,6 +575,7 @@ 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),
+            childApps: childDevApps(directory),
             // This project's own runner and app folder, so the agent can wire it itself.
             init: initCommandIn(directory),
         });
@@ -568,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/page-commands/undeclared-command.d.ts

@@ -18,8 +18,14 @@
  * answers rather than a set lookup at the call site.
  */
 import { type CommandResult } from '@reticlehq/core';
-/** Why nothing was sent, in a sentence, or undefined when the command should go. */
-export declare function refusalForUndeclared(name: string, declared: readonly string[] | undefined): string | undefined;
+/**
+ * Why nothing was sent, in a sentence, or undefined when the command should go.
+ *
+ * `behind` is the caller's sentence for a page SDK older than this daemon. A newer command
+ * (`render`, `match`) is then missing because of the version, and the list of commands alone
+ * does not say that.
+ */
+export declare function refusalForUndeclared(name: string, declared: readonly string[] | undefined, behind?: string): string | undefined;
 /**
  * The refusal as a finished result, or undefined when the command should be sent.
  *
@@ -27,4 +33,4 @@ export declare function refusalForUndeclared(name: string, declared: readonly st
  * cannot get the envelope subtly wrong -- an `ok: true` refusal would be read as a command that
  * worked, which is the one shape this must never produce.
  */
-export declare function refusedResult(name: string, declared: readonly string[] | undefined, id: string): CommandResult | undefined;
+export declare function refusedResult(name: string, declared: readonly string[] | undefined, id: string, behind?: string): CommandResult | undefined;

package/dist/portal/session/page-commands/undeclared-command.js

@@ -18,16 +18,25 @@
  * answers rather than a set lookup at the call site.
  */
 import { MessageKind } from '@reticlehq/core';
-/** Why nothing was sent, in a sentence, or undefined when the command should go. */
-export function refusalForUndeclared(name, declared) {
+/**
+ * Why nothing was sent, in a sentence, or undefined when the command should go.
+ *
+ * `behind` is the caller's sentence for a page SDK older than this daemon. A newer command
+ * (`render`, `match`) is then missing because of the version, and the list of commands alone
+ * does not say that.
+ */
+export function refusalForUndeclared(name, declared, behind) {
     // Too old to say. Unknown, never "nothing".
-    if (declared === undefined)
+    if (declared === undefined) {
         return undefined;
-    if (declared.includes(name))
+    }
+    if (declared.includes(name)) {
         return undefined;
+    }
     return (`this page does not serve "${name}". It declared ${String(declared.length)} command(s) when ` +
         `it connected, and this is not one of them: ${declared.join(', ')}. Nothing was sent, so ` +
-        'nothing happened -- this is a refusal, not a failure of the app.');
+        'nothing happened -- this is a refusal, not a failure of the app.' +
+        (behind === undefined ? '' : ` ${behind}`));
 }
 /**
  * The refusal as a finished result, or undefined when the command should be sent.
@@ -36,8 +45,8 @@ export function refusalForUndeclared(name, declared) {
  * cannot get the envelope subtly wrong -- an `ok: true` refusal would be read as a command that
  * worked, which is the one shape this must never produce.
  */
-export function refusedResult(name, declared, id) {
-    const error = refusalForUndeclared(name, declared);
+export function refusedResult(name, declared, id, behind) {
+    const error = refusalForUndeclared(name, declared, behind);
     return error === undefined
         ? undefined
         : { kind: MessageKind.COMMAND_RESULT, id, ok: false, error };

package/dist/portal/session/recorded-gaps.d.ts

@@ -49,7 +49,7 @@ export declare function probeMarkers(tabs: readonly ProbedTab[]): Promise<boolea
 /**
  * The `engineBlindSpots` field for a verdict result: what this engine could not observe in the
  * session so far. Notes this verdict's own comparison first, so a `compare` clears the arithmetic
- * spot on the result that ran it. `claims`: the inline intent, then the run's declared intents.
+ * spot on the result that ran it. `claims`: the inline intent, or else the run's declared intents.
  */
 export declare function engineBlindSpotsField(sessionId: string, predicate: Predicate | undefined, intent: unknown, declared: readonly {
     statement: string;

package/dist/portal/session/recorded-gaps.js

@@ -162,12 +162,15 @@ const comparedSeen = new Set();
 /**
  * The `engineBlindSpots` field for a verdict result: what this engine could not observe in the
  * session so far. Notes this verdict's own comparison first, so a `compare` clears the arithmetic
- * spot on the result that ran it. `claims`: the inline intent, then the run's declared intents.
+ * spot on the result that ran it. `claims`: the inline intent, or else the run's declared intents.
  */
 export function engineBlindSpotsField(sessionId, predicate, intent, declared) {
     if (computesComparison(predicate))
         comparedSeen.add(sessionId);
-    const claims = [text(intent), ...declared.map((each) => each.statement)];
+    // A call that names its own intent is judged on that intent alone. The run's open intents can be
+    // an earlier task's, and judging them reported that task's claim on this one (#1938).
+    const own = text(intent);
+    const claims = own === undefined ? declared.map((each) => each.statement) : [own];
     return {
         [ENGINE_BLIND_SPOTS_FIELD]: engineBlindSpots({
             canvasSeen: canvasSeen.has(sessionId),