@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,457 @@
+/**
+ * Turning "no browser session connected" from a dead end into a next action.
+ *
+ * The daemon can tell these cases apart, and each has a different, concrete fix:
+ *
+ *   - a session was here and went away    -> the tab closed or reloaded; reopen it
+ *   - something is listening, never dialled, project not wired -> run `reticle init` in THAT app
+ *   - something is listening, project wired -> port mismatch or a stale build; restart the dev server
+ *   - nothing is listening anywhere       -> there is no app running; start it
+ *
+ * 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/telemetry';
+import { leaseCaveat } from './presence/lease-availability.js';
+import { DEV_SERVER_PORTS } from '../../command/cli/ports/resolve/cli-port.js';
+import { siblingListenerNote } from '../../command/cli/ports/sibling-ports.js';
+import { STALL_AFTER_MS } from './stall-clock.js';
+import { pageTornDownWhileOn } from '@reticlehq/engine/evidence/page-teardown.js';
+/** The one framework whose most likely cause differs from every other framework's. */
+const NUXT = 'nuxt';
+/**
+ * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session
+ * recovery: a message that already carries its own next action must not be handed a second, more
+ * generic one that contradicts it.
+ */
+export const SELF_RECOVERING_MARKER = 'Then call reticle_sessions again — it will appear within a second of the page loading.';
+const RETRY = SELF_RECOVERING_MARKER;
+/**
+ * The no-shell path, for the branches where a BLIND lease would be wrong.
+ *
+ * A lease opens a URL, so offering one while nothing is listening is offering to open nothing —
+ * which is why these branches deliberately withheld it, and a test pins that. But withholding it
+ * left an agent with no CLI holding no path at all: reported from Windows, where the MCP server was
+ * registered and every tool advertised while no `reticle` binary existed on disk, so every remedy
+ * offered was a shell command that could not be run.
+ *
+ * The resolution is the ORDER, not the offer. Get the URL first — which these branches already tell
+ * the reader to do — and then the lease is the way to open it without a shell.
+ */
+const URL_THEN_LEASE = 'Once you have that URL, open it with reticle_lease {action:"acquire", url} rather than a shell ' +
+    'command — it needs no CLI on PATH (reach it with reticle_run {tool:"reticle_lease"} if it is ' +
+    'not advertised directly).';
+/**
+ * The lease advice, with the reason it cannot be taken when that is the case.
+ *
+ * A function rather than a constant so the caveat cannot be forgotten at one of the six sites that
+ * offer the lease — which is exactly how the offer came to be made by the command that had already
+ * diagnosed the problem.
+ */
+function leaseAdvice(base, facts) {
+    const caveat = leaseCaveat(facts.leaseBrowser);
+    return caveat === undefined ? base : `${base} ${caveat}`;
+}
+/**
+ * The way out that needs no human at all.
+ *
+ * Only offered when the app is known to carry the SDK: leasing an uninstrumented app just burns a
+ * browser and comes back `ready:false`.
+ */
+const SELF_SERVE = 'You do not have to wait for the human: reticle_lease {action:"acquire", url} opens a browser ' +
+    'Reticle drives itself, and returns a sessionId you can use immediately (reach it with ' +
+    'reticle_run {tool:"reticle_lease"} if it is not advertised directly; release it when you finish).';
+/** The hedge that is true for every vanished tab we did not watch leave. */
+const TAB_GONE_WHAT = 'The tab was closed, navigated away, or hard-reloaded.';
+/**
+ * What happened to the tab, with the last URL named when we still hold it.
+ *
+ * Without the URL this is the sentence the field has always seen. With it, a route that tore the
+ * page down is no longer the same dead end as "the human closed the tab".
+ */
+function tabGoneWhat(url) {
+    if (undefined === url || '' === url)
+        return TAB_GONE_WHAT;
+    const torn = pageTornDownWhileOn(url);
+    const first = torn.charAt(0);
+    if ('' === first)
+        return TAB_GONE_WHAT;
+    return `${first.toUpperCase()}${torn.slice(1)}. ${TAB_GONE_WHAT}`;
+}
+/**
+ * The one cause that produces a PERFECTLY healthy everything and still never connects.
+ *
+ * The SDK refuses to dial from a page that is not on localhost unless `allowNonLocalhost` is set.
+ * That is deliberate — Reticle must not be reachable from a page it does not trust — but the refusal
+ * happens page-side, so the daemon sees only silence, `doctor` sees only a healthy daemon, and every
+ * checklist item passes. Reported from the field by an agent on a hosts-file alias (the normal setup
+ * for white-label and multi-tenant apps): the whole setup was lost to a flag named in no checklist,
+ * and `init`'s own fallback snippet guards on `hostname === 'localhost'`, so on such a host the
+ * connect never runs and there is not even a console line to find.
+ *
+ * Only offered on the wired-and-listening branch: that is where a correctly installed app that
+ * cannot connect actually lands.
+ */
+const NON_LOCALHOST_GATE = 'One more cause that leaves every other check healthy: if the app is served on anything other ' +
+    'than localhost (a hosts-file alias, a LAN IP, a tunnel), the SDK refuses to connect unless it ' +
+    'is given `allowNonLocalhost: true` AND a pairing token — the flag alone is NOT sufficient off ' +
+    'localhost, which cost one reporter their whole setup until they read our compiled SDK by hand. ' +
+    'The token is the one in `~/.reticle/pairing-token`, passed as `token` to the same connect(). ' +
+    'The refusal is page-side, so nothing here can see it: check the browser console for that ' +
+    "message and pass both in the app's reticle.connect().";
+/**
+ * The causes for an app that is wired and still silent.
+ *
+ * Every one of these is indistinguishable from "no SDK installed" from every surface an agent can
+ * reach, so a message that names only a missing SDK and a wrong port hands the agent the wrong
+ * differential — which ends with it reporting Reticle as unwired on an app that is correctly wired.
+ */
+const REAL_CAUSES = 'Causes that produce exactly this and are NOT a port problem, in the order they actually occur: ' +
+    '(a) the SDK is in the bundle but `connect()` is never reached — a dev-mode guard or a missing ' +
+    'runtime-config value returning early, which emits nothing at all, so grep the app for the ' +
+    'connect call and confirm it runs; (b) the dev server was started BEFORE the Reticle plugin was ' +
+    'added, so it is not in the bundle at all — restart the dev server, do not rely on HMR; ' +
+    '(c) a peer dependency is missing, typically `@reticlehq/react` in a non-React app, so the ' +
+    "dynamic import fails silently; (d) this daemon's working directory is not the project, so it is " +
+    'scoped to the wrong app entirely — check the directory named above is really where your app ' +
+    'lives.';
+/** Nuxt's most likely cause is (b), and Nuxt is the framework where it is nearly certain. */
+const NUXT_STALE_BUNDLE = 'This project is Nuxt: the most likely cause by a distance is a dev server that predates the ' +
+    'Reticle plugin. Nuxt does NOT register a newly added plugin on HMR, so the running bundle ' +
+    'carries no SDK however correct the config is — STOP and restart `nuxt dev`, then reload the ' +
+    'page, before investigating anything else.';
+/**
+ * The lead when durable state proves this project has connected on this port before.
+ *
+ * Durable state outranks this process: a daemon that has served nothing since boot must not name a
+ * port mismatch as the likely cause when it holds a record of this project connecting on this port.
+ */
+const RESTARTED_LEAD = 'no browser session connected. This daemon has served none since it started, but it is a NEW ' +
+    'process — an app for this project HAS connected on this port before, which is recorded ' +
+    'durably. So the wiring is correct and the port is correct: what is failing now is the SDK ' +
+    'reaching initialise on the page.';
+/** Why the obvious move is the wrong one here. Reasoning, so it rides in the detail. */
+const DO_NOT_REINSTALL = 'Re-running the install is the wrong move here: it cannot help on a project that has ' +
+    'demonstrably connected, and it can overwrite a working config.';
+/**
+ * The ports the scan actually covers, rendered for the message.
+ *
+ * Derived from DEV_SERVER_PORTS rather than re-typed: a message that lists ports the scan does not
+ * check, or omits ones it does, is a new version of the same defect — a confident claim about
+ * evidence that was never gathered.
+ */
+const SCANNED_PORTS = [...DEV_SERVER_PORTS].join(', ');
+/**
+ * How to say "open the app" to an agent that may have no `reticle` binary.
+ *
+ * Reticle registers its MCP server as `npx @reticlehq/server mcp`, so the ordinary install puts
+ * NOTHING on PATH: a remedy naming a bare `reticle` binary is unrunnable on most machines that read
+ * it — and a half-failed install can advertise every tool while no CLI exists on disk. So every
+ * remedy here has to be a command that works from a bare npm environment.
+ *
+ * Init-time messages keep the short form on purpose: there, the reader is already running the CLI.
+ */
+const OPEN_CMD = '`npx @reticlehq/server open <url>`';
+const OPEN_CMD_BARE = '`npx @reticlehq/server open`';
+const INIT_CMD = '`npx @reticlehq/server init`';
+/**
+ * The one sentence that stops the scan lying about a server that is running.
+ *
+ * A port that accepted a connection and then said nothing is evidence FOR the app being up, not
+ * 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) {
+    const slow = facts.slowListeners ?? [];
+    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: ');
+}
+/**
+ * The commonest first-run state there is (#320).
+ *
+ * Reticle sees a page only once a browser has LOADED it, so a wired app that nobody has opened
+ * produces exactly the same empty list as a broken install.
+ */
+const OPEN_THE_APP = 'Reticle only ever sees a page that is LOADED, so the commonest cause by a distance is that no ' +
+    `browser has opened the app yet: run ${OPEN_CMD} with the app's own URL (or ask the ` +
+    'human to open it).';
+/**
+ * What a machine-wide port scan can and cannot say.
+ *
+ * It finds listeners anywhere on localhost and knows nothing about who owns them. On a machine
+ * running more than one repo — the normal case — "something is listening, so this project's server
+ * 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) {
+    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.');
+    }
+    return (`Something is listening on port ${listening.join(', ')}, but I cannot attribute any of it to ` +
+        `this project: that is a machine-wide scan of ${SCANNED_PORTS}, so on a machine running more ` +
+        "than one repo those are as likely to be somebody else's dev server, and the app's own port " +
+        'may not be in the set at all. Treat them as unattributed rather than as evidence.');
+}
+/**
+ * The mismatch, stated with both numbers, when we can actually see one. Empty otherwise.
+ *
+ * Leading space so the caller can concatenate it unconditionally without producing a double space
+ * in the common case where there is nothing to say.
+ */
+function portMismatchClause(facts) {
+    const configured = facts.projectPort;
+    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` +
+        ` ${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.
+ *
+ * One place, because the ranking is the whole fix: a hint that lists "no server", "no SDK" and
+ * "no tab" at equal weight is a hint the reader has to rank itself, with strictly less evidence
+ * than the daemon has.
+ */
+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)}${siblingListenerClause(facts)} ${NON_LOCALHOST_GATE}`);
+}
+/**
+ * The scope answer, when the config was somewhere else all along.
+ *
+ * This OUTRANKS every "you may have no SDK" sentence in this file, because it is positive evidence:
+ * a `.reticle.json` in `apps/web` means that app has been through `init` whatever the daemon's own
+ * directory looks like. Naming the directories rather than adopting one is deliberate — several
+ * configs means several projects, and choosing silently is how an agent gets a confident verdict
+ * about an app it never touched.
+ */
+function configsElsewhereClause(facts) {
+    const configs = facts.configsElsewhere ?? [];
+    if (0 === configs.length)
+        return '';
+    const named = configs
+        .map((c) => (c.projectId === undefined ? c.directory : `${c.directory} ('${c.projectId}')`))
+        .join(', ');
+    return (`A \`.reticle.json\` WAS found outside this daemon's directory: ${named}. So the app is wired ` +
+        'and this is a SCOPE problem, not an install problem. Restart the daemon from the ' +
+        "app's directory (or point it there) rather than installing anything.");
+}
+/** 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)
+        return '';
+    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.`;
+}
+/**
+ * A leading sentence when the daemon has been up long enough that no app is coming.
+ *
+ * Only fires for a WIRED project (initialized) that has NEVER connected and is past the
+ * threshold. An unwired project already names the install gap as its primary cause; adding a time
+ * sentence there would double-blame.
+ */
+function stallClause(facts) {
+    const { daemonUpMs, initialized, everConnected } = facts;
+    if (everConnected)
+        return '';
+    if (!initialized)
+        return '';
+    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)
+        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 alone is not enough to tell the branches apart afterwards: "restarted the dev server
+ * and it still did not connect" and "never started the app" need opposite fixes and read as 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
+        ? 'the directory this daemon is running in'
+        : `the directory this daemon is running in (${facts.directory})`;
+    // Before everything, including `everConnected`: a refusal is the only positive evidence here,
+    // and it is CURRENT. Every branch below reasons from an absence, and an absence cannot outrank
+    // a page that dialled this daemon and was turned away.
+    if (true === facts.authRefused) {
+        return reason(NoSessionReason.AUTH_REFUSED, 'no browser session connected, and the reason is not the app: this daemon REFUSED the last ' +
+            'page that dialled it, because the pairing token it presented is not the one this daemon ' +
+            'holds. Only an SDK dials the bridge, so the wiring is correct and the app is running. ' +
+            'Restart the dev server so it picks up the current token.', 'The token is read by the build plugin when the dev server STARTS, so the usual cause is a ' +
+            'daemon restarted (or a `~/.reticle` cleared) after the dev server was already up. If the ' +
+            'two were started from different environments — an editor spawning the MCP server globally ' +
+            'while the dev server runs from a shell — they can be reading different `~/.reticle` ' +
+            'directories instead. The page says the same thing in the browser console.');
+    }
+    if (everConnected) {
+        // A reaped lease first, because it is the one cause with POSITIVE evidence behind it. Calling
+        // it "the tab was closed, ask the human to reopen the app" is wrong on every clause (#157):
+        // there is no human tab, and the recovery that works goes unmentioned.
+        //
+        // No hedge, because none is needed: `leaseExpired` 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 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. Re-acquire ' +
+                `with reticle_lease {action:"acquire", url} and carry on. ${RETRY}`, 'A lease is a headless context, not a human tab, and it takes its cookies with it, so an ' +
+                `authenticated app needs signing in again.${alreadyListeningClause(listening)}`);
+        }
+        return reason(NoSessionReason.TAB_GONE, 'no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
+            `is correct. ${tabGoneWhat(facts.lastKnownUrl)} Ask the human to reopen ` +
+            `the app (or run ${OPEN_CMD_BARE}), or reload the tab. ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, alreadyListeningClause(listening).trim());
+    }
+    // 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
+    // connection. It is also the branch that stops the daemon contradicting itself — a hint that the
+    // 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 ` +
+                '(the command is in `next_action`).'
+            : unattributedListeners(listening);
+        return reason(NoSessionReason.APP_NOT_REOPENED, `${RESTARTED_LEAD} ${OPEN_THE_APP} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, `${DO_NOT_REINSTALL} ${listeners} ${rankedCauses(facts)}`);
+    }
+    // A config found elsewhere outranks every "you may have no SDK" branch below: those reason from
+    // an absence in ONE directory, and this is a file we read in another. Ranked here so the reader is
+    // never sent through an install on a project that has demonstrably been installed.
+    if (!initialized && (facts.configsElsewhere ?? []).length > 0) {
+        return reason(NoSessionReason.CONFIG_ELSEWHERE, 'no browser session connected, and this daemon has never seen one. ' +
+            `${configsElsewhereClause(facts)} ${OPEN_THE_APP} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, 'This daemon was started somewhere that is not the project, which is the normal outcome when ' +
+            `an editor launches it from your home directory. ${unattributedListeners(listening)} ` +
+            `${rankedCauses(facts)}`);
+    }
+    if (0 === listening.length) {
+        // Lead with the stronger EVIDENCE, and do not overstate what it is.
+        //
+        // `initialized` is one thing only: whether a `.reticle.json` sits in the directory this daemon
+        // is running in. It is NOT "this project has never been through `reticle init`", and the two
+        // come apart constantly — a monorepo whose daemon runs at the root while the app lives in
+        // `apps/web`, or any app wired by the babel/vite plugin rather than by `init`. An earlier
+        // version of this branch asserted the strong claim and led with it, on the reasoning that it was
+        // a certainty while the port scan was a guess. It is not a certainty. Caught driving Reticle's
+        // OWN repo, where the message told an agent the project had never been through `init` about a
+        // fixture that is instrumented and working — "the one sentence I was most likely to act on was
+        // wrong", which is the exact failure this whole file exists to prevent.
+        //
+        // So: report what was actually checked, name the directory, and name the case where the absence
+        // 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 ' +
+                '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. ${RETRY}`, `The scan covers ${SCANNED_PORTS} 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)}`);
+        }
+        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 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 ` +
+            '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
+            // only move that can recover the :7699 case.
+            `assuming it is down. The \`next_action\` command is read from this project's own scripts, ` +
+            'and says so rather than guessing when there is none. ' +
+            `${leaseAdvice(URL_THEN_LEASE, facts)}${siblingListenerClause(facts)}`);
+    }
+    if (!initialized) {
+        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}, which is the file ` +
+            `${INIT_CMD} writes, so the app may carry no Reticle SDK. 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}. ${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)}`);
+    }
+    return reason(NoSessionReason.SDK_NOT_REACHING_DAEMON, `${stallClause(facts)}no browser session connected, and this daemon has never seen one for this project, which is ` +
+        `wired for Reticle. ${OPEN_THE_APP} If the page IS open and still does not appear, the SDK ` +
+        `is not reaching this daemon (on ${String(port)}). ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, `${unattributedListeners(listening)} ${rankedCauses(facts)}`);
+}
+/**
+ * Pair a branch's verdict with its prose, so neither can be produced without the other.
+ *
+ * TWO pieces of prose now. `message` is the lead: what is true and what to do about it, in about
+ * four sentences. `detail` is the differential behind it -- the port-scan caveat, the ranked causes,
+ * the lease offer -- which is the part that was making this five hundred words in one paragraph.
+ *
+ * Split rather than deleted. Almost every clause in `detail` exists because somebody was sent the
+ * wrong way without it, and the reader who needs it is the agent about to spend a drive on a guess.
+ * The reader who does not is the person watching `reticle init`, who gets the lead.
+ */
+function reason(code, message, detail) {
+    return { reason: code, message, ...(undefined === detail ? {} : { detail }) };
+}
+/**
+ * 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) {
+    const { message, detail } = explainNoSession(facts);
+    return undefined === detail ? message : `${message} ${detail}`;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * "No browser session connected", as something an agent can RUN.
+ *
+ * The prose diagnosis next door is good and it is prose: the agent has to read four hedged sentences
+ * and decide which of them is about its situation. This is the same decision, decided here, as one
+ * value plus one literal command — so the branch happens in the daemon, which has the evidence,
+ * rather than in the agent, which does not.
+ *
+ * The rule that outranks helpfulness: never invent a command. If the project has no dev script, this
+ * says there is none. A command that does not exist sends the agent chasing a phantom error in its
+ * own repo.
+ *
+ * Pure. The facts arrive from the watch; nothing here touches the disk or the clock.
+ */
+import { NoSessionAction } from '@reticlehq/core';
+import type { DevCommand } from './dev-server/dev-command.js';
+/** The executable half of the no-session payload. */
+export interface NoSessionNextAction {
+    action: NoSessionAction;
+    /** The literal command to run. Absent whenever it could not be sourced without guessing. */
+    command?: string;
+    /** The port this action is about — where the app is, or where the dev script will put it. */
+    port?: number;
+    /** One sentence: why this is the action, and — when there is no command — why there is none. */
+    reason: string;
+}
+interface NextActionFacts {
+    everConnected: boolean;
+    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.
+     *
+     * Outranks `initialized`, which is only ever "is there a `.reticle.json` in the ONE directory this
+     * daemon stands in". In a monorepo, or under an editor that starts the MCP server from the user's
+     * home, that answer is no for projects that are wired and have connected — and the action handed
+     * back was `reticle init`, which is the one action that cannot help and can overwrite the config
+     * that works.
+     */
+    previouslyConnected?: boolean;
+    /**
+     * A page reached this daemon and was REFUSED on the pairing token, and nothing has connected since.
+     *
+     * The second clause is load-bearing, and belongs to whoever computes this rather than to the
+     * branches that read it: a refusal the daemon merely REMEMBERS says nothing about why nothing is
+     * connected right now, and a branch that treats it as current blames the token for a closed tab.
+     *
+     * Positive evidence, and the only fact here that proves the app is both running and instrumented:
+     * nothing dials the bridge but an SDK, so a refused hello means the wiring works and the daemon
+     * would not serve it. That happens whenever an IDE registers the MCP server GLOBALLY -- the daemon
+     * starts with a cwd of `/` or `$HOME`, finds no `.reticle.json` there, and refuses every page
+     * while `doctor` run from the app directory reports the project wired (#685).
+     *
+     * Without it, `initialized: false` plus a listening port reads as "the app may carry no SDK" and
+     * the action handed back is `reticle init` -- over a config that already works, which is the one
+     * action that cannot help and can overwrite it.
+     */
+    authRefused?: boolean;
+}
+export declare function nextActionFor(facts: NextActionFacts): NoSessionNextAction;
+/** The same action as one sentence, for the prose message the human reads. */
+export declare function renderNextAction(next: NoSessionNextAction): string;
+export {};