@reticlehq/server 2.11.0 → 2.13.0

package/dist/session/lease-visibility.js

@@ -0,0 +1,76 @@
+/**
+ * Telling the human that the agent went somewhere they cannot see.
+ *
+ * A lease is a separate pooled context, and it is the highest-value path in the product for
+ * autonomous work. It also has one failure mode that is entirely about people: the HUD lives in the
+ * human's OWN tab, so while an agent drives a lease that tab shows nothing at all. An idle agent and
+ * a busy one are then indistinguishable from the only seat a human occupies.
+ *
+ * That is not hypothetical. An agent followed the daemon's own throttle recommendation into a lease,
+ * drove fifteen calls, and the developer watching an empty HUD asked why nothing was running. The
+ * product was working perfectly and looked broken, which is the worst combination available.
+ *
+ * The fix rides on machinery that already exists — `pushNarration` posts `ReticleCommand.NARRATE`
+ * and every SDK in the field already renders it — so nothing here moves the wire contract. It is a
+ * message to tabs that are ALREADY connected, not a new capability.
+ */
+/**
+ * Shown on a watching human's HUD when an agent takes a lease.
+ *
+ * States the fact and its consequence, because the fact alone ("agent leased a context") does not
+ * tell somebody why their screen is still. The consequence is the whole reason to say anything.
+ */
+export const AGENT_DRIVING_ELSEWHERE = 'An agent is driving a separate leased context — its actions will not appear in this tab.';
+/** Shown when the lease is released, so a HUD that went quiet is explained in both directions. */
+export const AGENT_DRIVING_HERE_AGAIN = 'The agent released its separate context — this tab is live again.';
+/**
+ * Shown to a tab that CONNECTS while a lease is already open.
+ *
+ * The acquire-time notice only reaches tabs that were already connected, so opening the app — or
+ * merely reloading it — during a lease landed somebody on a silent HUD with nothing explaining it.
+ * That is the same dark-HUD failure the acquire notice exists to prevent, arrived at from the other
+ * direction, and it is the more common one: a person opens the dashboard BECAUSE they want to watch.
+ *
+ * Worded for arrival rather than for a change of state — nothing just happened from this tab's point
+ * of view, so "an agent is driving elsewhere" would describe an event it never saw.
+ */
+export const AGENT_ALREADY_DRIVING_ELSEWHERE = 'An agent is already driving a separate leased context — its actions will not appear in this tab.';
+/**
+ * Whether a session arriving now should be told a lease is already running.
+ *
+ * Same rules as `watchersToNotify`, expressed for one session: never tell a leased context about
+ * itself, and never tell somebody watching app A about a lease against app B.
+ */
+export function shouldGreetWithLeaseNotice(session, leasedSessionIds, leasedProjectIds) {
+    if (leasedSessionIds.includes(session.id))
+        return false;
+    if (0 === leasedSessionIds.length)
+        return false;
+    return leasedProjectIds.some((projectId) => projectId === undefined || session.projectId === undefined || session.projectId === projectId);
+}
+/**
+ * Which connected sessions belong to a human who should be told.
+ *
+ * Two exclusions, both deliberate:
+ *
+ * - Leased sessions. They ARE the agent's context; narrating "an agent is driving elsewhere" into
+ *   the tab doing the driving is noise, and with several leases open they would talk about each
+ *   other. Membership comes from the pool rather than an id prefix, because a naming convention is
+ *   not a fact and `pool.leasedSessionIds()` is.
+ *
+ * - Other projects. One daemon serves many, and somebody watching app A does not need to hear about
+ *   a lease taken against app B. A session that declares no project is NOT excluded: an older SDK
+ *   sends no projectId, and silently dropping those would reintroduce the dark HUD for exactly the
+ *   people least likely to work out why.
+ *
+ * Pure: no IO, no clock, no session objects. The caller does the posting.
+ */
+export function watchersToNotify(sessions, leasedSessionIds, projectId) {
+    const leased = new Set(leasedSessionIds);
+    return sessions
+        .filter((session) => !leased.has(session.id))
+        .filter((session) => projectId === undefined ||
+        session.projectId === undefined ||
+        session.projectId === projectId)
+        .map((session) => session.id);
+}

package/dist/session/live-control-tools.js

@@ -3,12 +3,7 @@ import { noteEmptyRead } from '../tools/observed-nothing.js';
 import { AGENT_ASK_NOTICE, AGENT_WAITING_NOTICE, PresenterTone, SessionState, YIELD_WITHOUT_SESSION_NOTE, } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
-import { asNumber, asString } from '../tools/tools-helpers.js';
-import { waitForReady, RETICLE_LOOP_GUIDE } from './session-readiness.js';
-import { recoveryFor } from '../tools/error-recovery.js';
-/** Default + ceiling for the readiness wait — keep it short so a truly-missing app fails fast. */
-const WAIT_READY_DEFAULT_MS = 5000;
-const WAIT_READY_MAX_MS = 30000;
+import { asString } from '../tools/tools-helpers.js';
 /**
  * Is this a turn ending with nothing attached, rather than a call about a specific tab?
  *
@@ -225,42 +220,6 @@ export const LIVE_CONTROL_TOOLS = [
             return Promise.resolve(out);
         },
     },
-    {
-        name: ReticleTool.WAIT_READY,
-        description: 'Block until the app is connected, then continue — call this once right after init so your ' +
-            'first real tool call does not lose the race with the SDK connecting its WebSocket. Returns as ' +
-            'soon as a session exists (no latency if one already does), or after `timeoutMs` with a ' +
-            'recovery hint if none appears.',
-        inputSchema: {
-            timeoutMs: z
-                .number()
-                .optional()
-                .describe('How long to wait for a session (ms). Default 5000, max 30000.'),
-        },
-        outputSchema: {
-            ready: z.boolean(),
-            sessionCount: z.number(),
-            loop: z.string().optional(),
-            recovery: z.string().optional(),
-        },
-        handler: async (deps, args) => {
-            const requested = asNumber(args['timeoutMs']) ?? WAIT_READY_DEFAULT_MS;
-            const timeoutMs = Math.max(0, Math.min(requested, WAIT_READY_MAX_MS));
-            const ready = await waitForReady({
-                count: () => deps.sessions.count(),
-                timeoutMs,
-                now: deps.now,
-                sleep: (ms) => new Promise((res) => setTimeout(res, ms)),
-            });
-            // The first response a fresh agent gets — carry the loop guide so it learns how to drive Reticle.
-            if (ready)
-                return { ready: true, sessionCount: deps.sessions.count(), loop: RETICLE_LOOP_GUIDE };
-            const recovery = recoveryFor('no browser session connected');
-            return recovery !== undefined
-                ? { ready: false, sessionCount: 0, recovery }
-                : { ready: false, sessionCount: 0 };
-        },
-    },
 ];
 /**
  * The single actionable next-move for a pending mark: point the agent at the source (or the element

package/dist/session/no-session-diagnosis.d.ts

@@ -18,6 +18,7 @@
  * Pure: everything it needs is passed in, so the probe that discovers listening ports stays out of
  * the hot resolve() path and this stays unit-testable.
  */
+import { NoSessionReason } from '@reticlehq/core';
 import { type LeaseBrowserState } from './lease-availability.js';
 export interface NoSessionFacts {
     /** Whether ANY session has connected to this daemon since it booted. */
@@ -117,6 +118,16 @@ export interface NoSessionFacts {
      * install never finished" to the user-facing diagnosis rather than only to telemetry.
      */
     daemonUpMs?: number;
+    /**
+     * Well-known Reticle ports other than `port` that currently accept a connection.
+     *
+     * Remaining half of #261. We cannot see an SDK dialling a port we are not on, but we can see that
+     * a well-known Reticle port has a listener. That is an observation: somebody else's daemon, another
+     * project, and an unrelated process all look the same from here. The sentence that reports it
+     * names the ports and refuses the conclusion. Absent or empty means nothing else was listening,
+     * which is the common case and must not gain a paragraph.
+     */
+    siblingListeners?: readonly number[];
 }
 /**
  * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session
@@ -124,4 +135,26 @@ export interface NoSessionFacts {
  * generic one that contradicts it.
  */
 export declare const SELF_RECOVERING_MARKER = "Then call reticle_sessions again \u2014 it will appear within a second of the page loading.";
+/**
+ * The diagnosis, and the CODE for the branch that produced it.
+ *
+ * The prose has always been well-ranked and it was the only output, so the population that installs
+ * Reticle and never gets an app connected arrived as one undifferentiated silence. "Restarted the
+ * dev server and it still did not connect" and "never started the app" need opposite fixes and were
+ * the same absence (#615).
+ *
+ * One function returning both, rather than a classifier beside the writer. A reason computed
+ * separately would drift from the sentence the user is actually shown, and then the metric would
+ * describe a diagnosis nobody received.
+ */
+export declare function explainNoSession(facts: NoSessionFacts): {
+    reason: NoSessionReason;
+    message: string;
+};
+/**
+ * The message alone, for the callers that render it.
+ *
+ * Kept as the narrow surface it always was: most callers want the sentence, and handing them the
+ * pair would spread a telemetry concern across every error path that shows a user this text.
+ */
 export declare function diagnoseNoSession(facts: NoSessionFacts): string;

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

@@ -18,8 +18,10 @@
  * Pure: everything it needs is passed in, so the probe that discovers listening ports stays out of
  * the hot resolve() path and this stays unit-testable.
  */
+import { NoSessionReason } from '@reticlehq/core';
 import { leaseCaveat } from './lease-availability.js';
 import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
+import { siblingListenerNote } from '../cli/sibling-ports.js';
 import { STALL_AFTER_MS } from './stall-clock.js';
 /** The one framework whose most likely cause differs from every other framework's. */
 const NUXT = 'nuxt';
@@ -217,6 +219,24 @@ function portMismatchClause(facts) {
         ` Either restart the daemon on ${String(configured)}, or update \`.reticle.json\` to` +
         ` ${String(facts.port)} and restart the dev server so the app picks it up.`);
 }
+/**
+ * A listener on a well-known Reticle port we did not bind. Observation, not a cause.
+ *
+ * Leading space so the caller can concatenate it unconditionally. Empty when there is nothing to
+ * say, including when the occupied sibling is already the configured-port mismatch — that sentence
+ * already named both numbers, and repeating 4460 as a second "cause" would overclaim.
+ */
+function siblingListenerClause(facts) {
+    const occupied = facts.siblingListeners ?? [];
+    if (0 === occupied.length)
+        return '';
+    const mismatch = facts.projectPort;
+    const extra = mismatch !== undefined && mismatch !== facts.port
+        ? occupied.filter((port) => port !== mismatch)
+        : occupied;
+    const note = siblingListenerNote(facts.port, extra);
+    return note === undefined ? '' : ` ${note}`;
+}
 /**
  * The tail every "the app is wired and silent" branch ends with, ranked.
  *
@@ -228,7 +248,7 @@ function rankedCauses(facts) {
     const nuxt = facts.framework?.toLowerCase() === NUXT ? `${NUXT_STALE_BUNDLE} ` : '';
     return (`${nuxt}${REAL_CAUSES} If none of those, the app may be dialling a different daemon than this ` +
         `one (on ${String(facts.port)}): check the app's reticle port matches ` +
-        `${String(facts.port)}.${portMismatchClause(facts)} ${NON_LOCALHOST_GATE}`);
+        `${String(facts.port)}.${portMismatchClause(facts)}${siblingListenerClause(facts)} ${NON_LOCALHOST_GATE}`);
 }
 /**
  * The scope answer, when the config was somewhere else all along.
@@ -281,7 +301,30 @@ function stallClause(facts) {
         '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. ');
 }
-export function diagnoseNoSession(facts) {
+function alreadyListeningClause(listening) {
+    if (0 === listening.length)
+        return '';
+    if (1 === listening.length) {
+        const port = listening[0];
+        return (` An app is already listening on ${String(port)}; just open http://localhost:${String(port)} ` +
+            '— do not start a second stack.');
+    }
+    return (` An app is already listening on ${listening.join(', ')}; just open one of those URLs — do not ` +
+        'start a second stack.');
+}
+/**
+ * The diagnosis, and the CODE for the branch that produced it.
+ *
+ * The prose has always been well-ranked and it was the only output, so the population that installs
+ * Reticle and never gets an app connected arrived as one undifferentiated silence. "Restarted the
+ * dev server and it still did not connect" and "never started the app" need opposite fixes and were
+ * the same absence (#615).
+ *
+ * One function returning both, rather than a classifier beside the writer. A reason computed
+ * separately would drift from the sentence the user is actually shown, and then the metric would
+ * describe a diagnosis nobody received.
+ */
+export function explainNoSession(facts) {
     const { everConnected, initialized, listening, port } = facts;
     // Named when known: a claim about a missing file is a claim about ONE directory.
     const where = facts.directory === undefined
@@ -292,19 +335,23 @@ export function diagnoseNoSession(facts) {
         // from the field (#157): an aged-out lease produced "the tab was closed … ask the human to
         // reopen the app", which is wrong on every clause — there is no human tab, and the recovery it
         // names is unavailable to the caller while the one that works goes unmentioned. The reporter
-        // went looking for a port mismatch. Hedged rather than swapped: a human tab may ALSO have
-        // closed, and this does not know which session went.
+        // went looking for a port mismatch.
+        //
+        // The hedge that used to close this branch ("if you were driving a human tab instead…") is
+        // gone with the reason for it. `leaseExpired` was a lifetime count of reaps, so it could not
+        // tell which session went and had to cover both; it now names the session that actually
+        // departed (#611), so this branch is only reached when the thing that vanished WAS the lease.
         if (true === facts.leaseExpired) {
-            return ('no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
-                'is correct. This daemon has expired at least one pooled lease, so the likeliest cause is ' +
-                'that a lease you were using aged out; 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). Re-acquire ' +
-                'with reticle_lease {action:"acquire", url} and carry on. If you were driving a human tab ' +
-                `instead, it went away — reopen it or run ${OPEN_CMD_BARE}. ${RETRY}`);
+            return reason(NoSessionReason.LEASE_EXPIRED, 'no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
+                'is correct. The session that went away was a pooled lease and it aged out; 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). Re-acquire with reticle_lease {action:"acquire", url} and ' +
+                `carry on.${alreadyListeningClause(listening)} ${RETRY}`);
         }
-        return ('no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
+        return reason(NoSessionReason.TAB_GONE, 'no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
             'is correct. The tab was closed, navigated away, or hard-reloaded. Ask the human to reopen ' +
-            `the app (or run ${OPEN_CMD_BARE}), or reload the tab. ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
+            `the app (or run ${OPEN_CMD_BARE}), or reload the tab.${alreadyListeningClause(listening)} ` +
+            `${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
     }
     // 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
@@ -315,13 +362,13 @@ export function diagnoseNoSession(facts) {
             ? `${unattributedListeners(listening)} If the dev server is not running, start it first ` +
                 '(the command is in `next_action`).'
             : unattributedListeners(listening);
-        return `${RESTARTED_LEAD} ${OPEN_THE_APP} ${listeners} ${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`;
+        return reason(NoSessionReason.APP_NOT_REOPENED, `${RESTARTED_LEAD} ${OPEN_THE_APP} ${listeners} ${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
     }
     // 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 ('no browser session connected, and this daemon has never seen one. ' +
+        return reason(NoSessionReason.CONFIG_ELSEWHERE, 'no browser session connected, and this daemon has never seen one. ' +
             `${configsElsewhereClause(facts)} ${unattributedListeners(listening)} ${OPEN_THE_APP} ` +
             `${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
     }
@@ -341,7 +388,7 @@ export function diagnoseNoSession(facts) {
         // So: report what was actually checked, name the directory, and name the case where the absence
         // is expected rather than diagnostic.
         if (!initialized) {
-            return ('no browser session connected. Two things to weigh, and neither of them is proof. ' +
+            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 (${SCANNED_PORTS}), so the dev server ` +
                 'may not be running — START IT YOURSELF, in the background, using the command in ' +
                 "`next_action` (it is read from this project's own scripts; if there is none, that field " +
@@ -353,9 +400,9 @@ export function diagnoseNoSession(facts) {
                 `file ${INIT_CMD} writes, so the app may carry no Reticle SDK — but check the app's ` +
                 'OWN directory before re-running `init`: 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)} ${leaseAdvice(URL_THEN_LEASE, facts)} ${RETRY}`);
+                `carries the SDK without that file at all.${searchedClause(facts)}${siblingListenerClause(facts)} ${leaseAdvice(URL_THEN_LEASE, facts)} ${RETRY}`);
         }
-        return (`${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. ${OPEN_THE_APP} ` +
             'Nothing is listening on the ports Reticle scans ' +
             `(${SCANNED_PORTS}) either, and the most common reason for that is a dev server that is not ` +
             'running: start it yourself in the background with the command in `next_action` — it is read ' +
@@ -371,23 +418,34 @@ export function diagnoseNoSession(facts) {
             // 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
             // only move that can recover the :7699 case.
-            `the app IS running, ask the human for its URL rather than assuming it is down. ${leaseAdvice(URL_THEN_LEASE, facts)} ` +
-            // Reachable only for a project that HAS been through `init` — the uninstrumented case is
-            // answered above, leading with that certainty instead of behind this scan's guess.
-            `${RETRY}`);
+            `the app IS running, ask the human for its URL rather than assuming it is down. ${leaseAdvice(URL_THEN_LEASE, facts)}` +
+            `${siblingListenerClause(facts)} ${RETRY}`);
     }
     if (!initialized) {
-        return ('no browser session connected, and this daemon has never seen one. ' +
+        return reason(NoSessionReason.NO_CONFIG, 'no browser session connected, and this daemon has never seen one. ' +
             `What was actually checked: there is no \`.reticle.json\` in ${where}. That is the file ` +
             `${INIT_CMD} writes, so the app may carry no Reticle SDK — but it is not proof, and the ` +
             'same absence 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. Check the app's OWN " +
             `directory: if it has no config, run ${INIT_CMD} there and restart the dev server; if it ` +
             `has one, the app is wired and simply has no page open — ${OPEN_CMD}. ` +
-            `${unattributedListeners(listening)}${searchedClause(facts)} ${RETRY}`);
+            `${unattributedListeners(listening)}${searchedClause(facts)}${siblingListenerClause(facts)} ${RETRY}`);
     }
-    return (`${stallClause(facts)}no browser session connected, and this daemon has never seen one for this project, which is ` +
+    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} ${unattributedListeners(listening)} ` +
         'If the page IS open and still does not appear, the app is wired and the SDK is not reaching ' +
         `this daemon (on ${String(port)}). ${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
 }
+/** Pair a branch's verdict with its prose, so neither can be produced without the other. */
+function reason(code, message) {
+    return { reason: code, message };
+}
+/**
+ * The message alone, for the callers that render it.
+ *
+ * Kept as the narrow surface it always was: most callers want the sentence, and handing them the
+ * pair would spread a telemetry concern across every error path that shows a user this text.
+ */
+export function diagnoseNoSession(facts) {
+    return explainNoSession(facts).message;
+}

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

@@ -29,6 +29,18 @@ interface NextActionFacts {
     initialized: boolean;
     listening: readonly number[];
     dev: DevCommand | undefined;
+    /** Configs found in other workspace directories: positive evidence of a scope mismatch. */
+    configsElsewhere?: readonly {
+        directory: string;
+        projectId?: string;
+    }[];
+    /**
+     * The sentence for a live daemon elsewhere that this project's app is actually connected to.
+     *
+     * Passed rendered rather than as ports, because the rule that produces it lives in the module that
+     * owns "which daemon is whose" and this file must stay pure. Absent when there is no split.
+     */
+    splitBrain?: string;
     /**
      * An app for this project has connected on this port before, from durable state.
      *

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

@@ -18,12 +18,52 @@ const INIT_COMMAND = 'reticle init';
 const OPEN_COMMAND = 'reticle open';
 const LOCALHOST = 'http://localhost';
 export function nextActionFor(facts) {
+    // FIRST, above every other cause, because it is the only one supported by positive evidence about
+    // a daemon rather than by an absence. This project's own connection record names a live daemon
+    // that is not this one, which means the app is up and instrumented and the agent is simply looking
+    // at the wrong process. Every branch below would send it to fix something that is not broken —
+    // start a dev server that is running, open a page that is open, or re-run `init` over a config
+    // that works — and the agent has no way to suspect the real cause from here.
+    const splitBrain = facts.splitBrain;
+    if (splitBrain !== undefined) {
+        return { action: NoSessionAction.DAEMON_SPLIT, reason: splitBrain };
+    }
     if (facts.everConnected) {
+        const listening = facts.listening;
+        const only = 1 === listening.length ? listening[0] : undefined;
+        const bound = 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.`;
         return {
             action: NoSessionAction.REOPEN_APP,
+            ...(only === undefined
+                ? {}
+                : { command: `${OPEN_COMMAND} ${LOCALHOST}:${String(only)}`, port: only }),
             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}.',
+                'reticle_lease {action:"acquire", url}.' +
+                bound,
+        };
+    }
+    const configsElsewhere = facts.configsElsewhere ?? [];
+    if (!facts.initialized && configsElsewhere.length > 0) {
+        const named = configsElsewhere
+            .map((config) => config.projectId === undefined
+            ? config.directory
+            : `${config.directory} ('${config.projectId}')`)
+            .join(', ');
+        const projectIds = configsElsewhere.flatMap((config) => config.projectId === undefined ? [] : [config.projectId]);
+        const leaseAlternative = 0 === projectIds.length
+            ? ''
+            : ' Alternatively, acquire the app URL explicitly with reticle_lease ' +
+                '{action:"acquire", url, projectId} using the matching projectId above.';
+        return {
+            action: NoSessionAction.OPEN_APP,
+            reason: `a \`.reticle.json\` was found outside this daemon's directory: ${named}. This is a ` +
+                "scope problem, not an install problem. Restart the daemon from the app's directory (or " +
+                `point it there), then open the app.${leaseAlternative}`,
         };
     }
     if (0 === facts.listening.length) {
@@ -41,9 +81,22 @@ export function nextActionFor(facts) {
             action: NoSessionAction.START_DEV_SERVER,
             command: dev.command,
             ...(dev.port === undefined ? {} : { port: dev.port }),
-            reason: 'nothing is listening on the ports Reticle scans, so the app is not running. This is the ' +
-                `project's own \`${dev.script}\` script — run it in the background, tell the human it is ` +
-                'running, then call reticle_sessions again.',
+            // "Probably", to match the branch above it and the paragraph beside it.
+            //
+            // The same fact was stated at two confidence levels by one function: no dev script said the
+            // app was "probably not running", and THIS branch — the one that hands over a command to run
+            // — asserted it flatly. That is the branch where being wrong costs something, because the
+            // agent then starts a SECOND dev server on a second port, which the guard below calls the
+            // exact confusion this probe exists to prevent.
+            //
+            // It also contradicted its own payload: the prose beside it says the scan is narrow, that a
+            // server on any other port is invisible to it, and that a running app should be checked for
+            // rather than assumed away. Measured on a machine with three dev servers up on ports the scan
+            // does not cover, it reported the app was not running.
+            reason: 'nothing is listening on the ports Reticle scans, so the app is probably not running — ' +
+                'though that scan is narrow, so if it IS up on another port, ask for its URL instead of ' +
+                `starting a second one. This is the project's own \`${dev.script}\` script — run it in the ` +
+                'background, tell the human it is running, then call reticle_sessions again.',
         };
     }
     // Something IS up. Whatever else is true, do NOT hand back a start command: a second dev server on
@@ -68,12 +121,30 @@ export function nextActionFor(facts) {
                 `\`${OPEN_COMMAND} <url>\`.`,
         };
     }
+    // Two causes sit under this branch and only one of them is fixed by opening a page.
+    //
+    // The prose diagnosis next door already ranks them and puts the stale bundle first: `init` writes
+    // the plugin into a config the RUNNING dev server has already read, so the served bundle carries
+    // no SDK and reloading it cannot ever produce a session. This function — the half an agent
+    // actually executes — used to say only "open the app", which is the answer to the OTHER cause.
+    // An agent that follows it opens a bundle with no Reticle in it, sees no session, and has been
+    // given no reason to suspect the one thing that would have worked.
+    //
+    // Named only while nothing has EVER connected. Once a session has been here the wiring is proven
+    // and sending an agent to restart a working dev server is a wild goose chase.
+    const neverConnected = true !== facts.previouslyConnected;
     return {
         action: NoSessionAction.OPEN_APP,
         command: `${OPEN_COMMAND} ${LOCALHOST}:${String(only)}`,
         port: only,
-        reason: 'this project is wired and a dev server is listening — Reticle only ever sees a page a ' +
-            'browser has LOADED, and nothing has loaded one.',
+        reason: neverConnected
+            ? 'this project is wired and a dev server is listening, but no app has ever connected to ' +
+                'this daemon — Reticle only ever sees a page a browser has LOADED, and nothing has loaded ' +
+                'one. If opening it does not produce a session, the dev server is older than the Reticle ' +
+                'plugin and its bundle carries no SDK: restart the dev server (do not rely on HMR) and ' +
+                'load the page again.'
+            : 'this project is wired and a dev server is listening — Reticle only ever sees a page a ' +
+                'browser has LOADED, and nothing has loaded one.',
     };
 }
 /** The same action as one sentence, for the prose message the human reads. */

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

@@ -19,11 +19,23 @@ interface NoSessionWatchOptions {
     directory?: string;
     probe?: () => Promise<number[]>;
     /**
-     * How many pooled leases have aged out, if a pool exists. Injected as a reader rather than the
-     * pool itself: the diagnosis needs one number, and taking the whole pool would tie the session
-     * layer to the browser layer for it.
+     * Well-known Reticle ports other than ours that currently accept a connection.
+     *
+     * Remaining half of #261. Injected so tests can pin the observation without opening a socket.
+     * Production (no `probe` override) probes those ports itself. A test that injects `probe` and
+     * omits this is opting out: it owns the scan.
+     */
+    occupiedSiblings?: () => Promise<readonly number[]>;
+    /**
+     * Whether a given session id belonged to a pooled lease that aged out, if a pool exists.
+     * Injected as a predicate rather than the pool itself: the diagnosis needs one answer, and
+     * taking the whole pool would tie the session layer to the browser layer for it.
+     *
+     * Was a lifetime `reapedLeases: () => number` count, asked as `> 0`. That latched: after the
+     * first reap, every closed human tab was reported as an expired lease for the rest of the
+     * daemon's life, and the recovery it named would have thrown away the app session (#611).
      */
-    reapedLeases?: () => number;
+    wasReapedLease?: (sessionId: string) => boolean;
     /**
      * Opens a URL in a browser Reticle owns, and resolves once it is open.
      *
@@ -53,8 +65,8 @@ export declare function startNoSessionWatch(options: NoSessionWatchOptions): ()
  * adjacent blocks in the bootstrap.
  */
 export declare function wireSessionScope(sessions: SessionManager, activeProjectId: string | undefined, port: number, 
-/** Reader for the pool's aged-out-lease count; omitted when this daemon runs no pool. */
-reapedLeases?: () => number, 
+/** Asks the pool whether a session id was a lease it aged out; omitted when there is no pool. */
+wasReapedLease?: (sessionId: string) => boolean, 
 /** Opens a URL in a Reticle-owned browser (the pool). Omitted ⇒ auto-attach is off. */
 attach?: (url: string) => Promise<unknown>): () => void;
 export {};