@reticlehq/server 2.12.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/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. */
@@ -134,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,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 { leaseCaveat } from './lease-availability.js';
 import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
 import { siblingListenerNote } from '../cli/sibling-ports.js';
@@ -300,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
@@ -311,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
@@ -334,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}`);
     }
@@ -360,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 " +
@@ -374,7 +402,7 @@ export function diagnoseNoSession(facts) {
                 '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)} ${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 ' +
@@ -394,7 +422,7 @@ export function diagnoseNoSession(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 ' +
@@ -403,8 +431,21 @@ export function diagnoseNoSession(facts) {
             `has one, the app is wired and simply has no page open — ${OPEN_CMD}. ` +
             `${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

@@ -34,6 +34,13 @@ interface NextActionFacts {
         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,33 @@ 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 ?? [];
@@ -100,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

@@ -27,11 +27,15 @@ interface NoSessionWatchOptions {
      */
     occupiedSiblings?: () => Promise<readonly 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.
+     * 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.
      *
@@ -61,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 {};

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

@@ -10,13 +10,14 @@
  * daemon that outlives the agent by hours has no business scanning ports it does not need.
  */
 import { probeDevServers, probeDevServerStates } from './dev-server-probe.js';
-import { diagnoseNoSession } from './no-session-diagnosis.js';
+import { explainNoSession } from './no-session-diagnosis.js';
 import { detectDevCommand } from './dev-command.js';
 import { nextActionFor, renderNextAction } from './no-session-next-action.js';
 import { readProjectFramework, readProjectId, readProjectPort } from '../cli/cli-port.js';
 import { discoverProjectConfigs } from '../cli/config-discovery.js';
 import { hasProjectConnectedBefore, rememberConnected } from './connection-memory.js';
-import { reticleStateHome } from '../daemon/daemon.js';
+import { isAlive, reticleStateHome } from '../daemon/daemon.js';
+import { daemonsServingProjectElsewhere, splitBrainNote } from '../daemon/daemon-resolve.js';
 import { stallUptime } from './stall-clock.js';
 import { probeDaemon } from '../mcp/mcp-proxy.js';
 import { findOccupiedSiblings } from '../cli/sibling-ports.js';
@@ -102,6 +103,19 @@ export function startNoSessionWatch(options) {
      * is the same over-confident claim this whole file exists to remove, pointing the other way.
      */
     const connectedBefore = () => hasProjectConnectedBefore(stateDir, options.port, readProjectId(directory));
+    /**
+     * The split brain, asked fresh every time like everything else here.
+     *
+     * Cheap — a directory listing of `~/.reticle` and a few small JSON reads — and only ever reached
+     * on a daemon with no session, which is the state this whole file exists for. Reading it once at
+     * boot would miss the ordinary case entirely: the app connects to the other daemon SECONDS after
+     * this one starts, which is precisely the window the agent then spends being told to start a dev
+     * server that is already running.
+     */
+    const splitBrain = () => {
+        const projectId = readProjectId(directory);
+        return splitBrainNote(options.port, daemonsServingProjectElsewhere(projectId, options.port, stateDir, isAlive, (port) => hasProjectConnectedBefore(stateDir, port, projectId)));
+    };
     // 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
     // project's success into evidence about another's.
@@ -171,20 +185,27 @@ export function startNoSessionWatch(options) {
     refresh();
     const timer = setInterval(refresh, REFRESH_MS);
     timer.unref();
-    const nextAction = (scope) => nextActionFor({
-        everConnected: options.sessions.everConnected(),
-        initialized: scope.initialized,
-        ...(scope.configsElsewhere === undefined ? {} : { configsElsewhere: scope.configsElsewhere }),
-        previouslyConnected: connectedBefore(),
-        listening,
-        // Read when asked, like everything else here: a `package.json` can gain a dev script, and a
-        // daemon that cached "there is none" at boot would keep saying so for the rest of the day.
-        dev: detectDevCommand(directory),
-    });
+    const nextAction = (scope) => {
+        const split = splitBrain();
+        return nextActionFor({
+            everConnected: options.sessions.everConnected(),
+            initialized: scope.initialized,
+            ...(scope.configsElsewhere === undefined ? {} : { configsElsewhere: scope.configsElsewhere }),
+            previouslyConnected: connectedBefore(),
+            ...(split === undefined ? {} : { splitBrain: split }),
+            listening,
+            // Read when asked, like everything else here: a `package.json` can gain a dev script, and a
+            // daemon that cached "there is none" at boot would keep saying so for the rest of the day.
+            dev: detectDevCommand(directory),
+        });
+    };
     options.sessions.setNoSessionNextAction(() => nextAction(projectScopeFacts()));
-    options.sessions.setNoSessionHint(() => {
+    // ONE call for both registrations below. The prose and the branch code have to come from the
+    // same evaluation or they can describe different branches - the facts are read when asked, so two
+    // calls a moment apart can genuinely disagree (#615).
+    const explain = () => {
         const scope = projectScopeFacts();
-        return (diagnoseNoSession({
+        return explainNoSession({
             everConnected: options.sessions.everConnected(),
             // Read WHEN ASKED, for the same reason `projectPort` below is: `.reticle.json` is routinely
             // written by `init` after this daemon started — that is the ordinary first-install order — and
@@ -209,7 +230,12 @@ export function startNoSessionWatch(options) {
                 const framework = readProjectFramework(directory);
                 return framework === undefined ? {} : { framework };
             })(),
-            leaseExpired: (options.reapedLeases?.() ?? 0) > 0,
+            // Decided from the session that actually went away, not from a lifetime tally: the lease
+            // sentence is only right when the thing that vanished WAS a lease.
+            leaseExpired: (() => {
+                const departed = options.sessions.lastDeparted();
+                return departed === undefined ? false : (options.wasReapedLease?.(departed) ?? false);
+            })(),
             // How long this daemon has been waiting with no app. The diagnosis uses it to surface
             // "install never finished" — the same condition telemetry already knows about.
             ...(() => {
@@ -224,16 +250,22 @@ export function startNoSessionWatch(options) {
                 return configured === undefined ? {} : { projectPort: configured };
             })(),
             ...(0 === siblingListeners.length ? {} : { siblingListeners }),
-        }) +
+        });
+    };
+    options.sessions.setNoSessionHint(() => {
+        const scope = projectScopeFacts();
+        return (explain().message +
             // Prose for the human, then the literal command for the agent. Both consume the same scope
             // facts so a discovered workspace config cannot become an `init` recommendation below it.
             ` ${renderNextAction(nextAction(scope))}` +
             (attachFailure ?? ''));
     });
+    options.sessions.setNoSessionReason(() => explain().reason);
     return () => {
         clearInterval(timer);
         options.sessions.setConnectionRecorder(undefined);
         options.sessions.setNoSessionHint(undefined);
+        options.sessions.setNoSessionReason(undefined);
         options.sessions.setNoSessionNextAction(undefined);
     };
 }
@@ -244,8 +276,8 @@ export function startNoSessionWatch(options) {
  * adjacent blocks in the bootstrap.
  */
 export function wireSessionScope(sessions, activeProjectId, port, 
-/** Reader for the pool's aged-out-lease count; omitted when this daemon runs no pool. */
-reapedLeases, 
+/** Asks the pool whether a session id was a lease it aged out; omitted when there is no pool. */
+wasReapedLease, 
 /** Opens a URL in a Reticle-owned browser (the pool). Omitted ⇒ auto-attach is off. */
 attach) {
     if (activeProjectId !== undefined)
@@ -254,7 +286,7 @@ attach) {
         sessions,
         port,
         initialized: activeProjectId !== undefined,
-        ...(reapedLeases === undefined ? {} : { reapedLeases }),
+        ...(wasReapedLease === undefined ? {} : { wasReapedLease }),
         ...(attach === undefined ? {} : { attach }),
     });
 }

package/dist/session/pending-commands.d.ts

@@ -11,6 +11,16 @@ import type { CommandResult } from '@reticlehq/core';
  */
 export declare class CommandTimeoutError extends Error {
 }
+/**
+ * The transport under this command was displaced by a newer connection claiming the same id.
+ *
+ * Typed, not a string to match on, because the two failures need OPPOSITE handling and the only
+ * thing separating them used to be the wording of a message. A read can simply be re-asked on the
+ * successor; a WRITE cannot — nobody can prove it did not land — so the honest answer is that the
+ * outcome went unobserved, which is a verdict this engine already has a word for.
+ */
+export declare class SessionReplacedError extends Error {
+}
 export declare class PendingCommands {
     #private;
     /** Next correlation id. Monotonic per session, so a reply can never match an earlier command. */
@@ -20,5 +30,5 @@ export declare class PendingCommands {
     /** Resolve the command this reply belongs to. Unknown ids are ignored, never thrown on. */
     settle(result: CommandResult): void;
     /** Reject everything still in flight — used on disconnect, so no caller waits on a dead socket. */
-    rejectAll(reason: string): void;
+    rejectAll(reason: string, replaced?: boolean): void;
 }

package/dist/session/pending-commands.js

@@ -10,6 +10,16 @@
  */
 export class CommandTimeoutError extends Error {
 }
+/**
+ * The transport under this command was displaced by a newer connection claiming the same id.
+ *
+ * Typed, not a string to match on, because the two failures need OPPOSITE handling and the only
+ * thing separating them used to be the wording of a message. A read can simply be re-asked on the
+ * successor; a WRITE cannot — nobody can prove it did not land — so the honest answer is that the
+ * outcome went unobserved, which is a verdict this engine already has a word for.
+ */
+export class SessionReplacedError extends Error {
+}
 export class PendingCommands {
     #pending = new Map();
     #seq = 0;
@@ -39,10 +49,10 @@ export class PendingCommands {
         pending.resolve(result);
     }
     /** Reject everything still in flight — used on disconnect, so no caller waits on a dead socket. */
-    rejectAll(reason) {
+    rejectAll(reason, replaced = false) {
         for (const [id, pending] of this.#pending) {
             clearTimeout(pending.timer);
-            pending.reject(new Error(reason));
+            pending.reject(replaced ? new SessionReplacedError(reason) : new Error(reason));
             this.#pending.delete(id);
         }
     }

package/dist/session/resolve-within.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Resolve a session, or spend the caller's stated budget waiting for one to arrive.
+ *
+ * Every tool that takes a `timeout_ms` used to resolve the session as its FIRST statement, so an
+ * empty session map threw before the budget was ever consulted. A caller that said "wait up to
+ * thirty seconds for the app" was refused in under a millisecond, and the only way to actually wait
+ * was to poll `reticle_sessions` blind.
+ *
+ * That is the wrong answer to the commonest situation in the product. The moment an agent has run
+ * `init` and restarted the dev server is exactly the moment there is no session yet and one is about
+ * to appear — and `no_session` is the refusal agents hit most. An agent that gets refused rarely
+ * retries; it concludes and moves on. Spending the budget it already asked for turns the most common
+ * dead end into a wait that ends in a verdict.
+ *
+ * Deliberately narrow in two ways.
+ *
+ * Only the EMPTY case waits. A `sessionId` that names a session which is not connected while others
+ * are is a different error with a different fix, and waiting on it would hide a typo behind a
+ * timeout.
+ *
+ * The original error is what gets thrown on expiry, never a generic timeout message. That error
+ * carries the daemon's whole diagnosis — the port scan, the next action, the literal command — and
+ * it is the single most valuable string this product emits to an agent that has nothing connected.
+ * Replacing it with "timed out" would trade the answer for a stopwatch reading.
+ */
+/** Just the part of the session manager this needs, so a test does not have to build one. */
+export interface ResolvableSessions<S> {
+    resolve: (sessionId?: string) => S;
+    count: () => number;
+}
+export declare function resolveSessionWithin<S>(sessions: ResolvableSessions<S>, sessionId: string | undefined, timeoutMs: number, deps: {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}): Promise<S>;