@reticlehq/server 3.1.0 → 3.3.0

package/dist/portal/pool/storage-seed.d.ts

@@ -2,7 +2,7 @@ import { type SeedStorage } from '@reticlehq/core';
 import type { InitScriptHandle, PooledContext, PooledCookie, PooledPage } from './pool-contract.js';
 export declare function targetOriginOf(navUrl: string): string | undefined;
 export declare function normalizeCookies(cookies: SeedStorage['cookies'], navUrl: string): PooledCookie[];
-export interface StorageSeedResult {
+interface StorageSeedResult {
     handle?: InitScriptHandle;
     checkError?: () => void;
 }
@@ -21,3 +21,4 @@ export interface StorageSeedResult {
  * has resolved, ensuring one-time semantics (reloads or future navigations do not reapply the seed).
  */
 export declare function seedStorageInto(context: PooledContext, page: PooledPage, targetUrl: string, seed: SeedStorage): Promise<StorageSeedResult | void>;
+export {};

package/dist/portal/pool/zero-install.d.ts

@@ -0,0 +1,27 @@
+export interface InjectedConnect {
+    url: string;
+    /** Absent when this daemon runs without a pairing token; the bridge then asks for none. */
+    token?: string;
+}
+/**
+ * The connect options a page is given when WE supply the connection rather than the app.
+ *
+ * One builder for both injection paths — this one, and re-pointing an SDK a hosted preview already
+ * ships (`real-input.ts`) — so the two cannot come to disagree about what a daemon-driven page needs.
+ */
+export declare function injectedConnectArgs(opts: InjectedConnect): Record<string, unknown>;
+/**
+ * The script for a page: install the SDK if the page has none, then connect it to this daemon.
+ *
+ * The guard is on the SINGLETON, not on a timer: a page that loaded its own SDK already holds
+ * `__reticleInstance`, and evaluating a second copy would register a second session for one tab.
+ * `connect` is a no-op once connected, so calling it on the page's own instance is safe.
+ */
+export declare function zeroInstallScript(bundle: string, opts: InjectedConnect): string;
+/**
+ * The single-file build, or undefined when this install has none.
+ *
+ * Read once and kept: it is ~450KB and identical for every lease. Absent means an older browser
+ * package or a broken install, and the caller then behaves exactly as it did before this existed.
+ */
+export declare function readReaderBundle(): string | undefined;

package/dist/portal/pool/zero-install.js

@@ -0,0 +1,54 @@
+/**
+ * The zero-install reader: how a page whose app never ran `init` still reaches a verdict.
+ *
+ * `@reticlehq/browser` builds itself into one file (`dist/reticle-inject.js`). The daemon reads that
+ * file as TEXT and evaluates it in a leased page that never connected, so the server never imports DOM
+ * code and the page needs no build step. What comes back is an ordinary session that reports no
+ * framework adapter and no source mapping, which is the honest description of what it can see.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+/** The subpath `@reticlehq/browser` exports its single-file build under. */
+const READER_SPECIFIER = '@reticlehq/browser/inject';
+/**
+ * The connect options a page is given when WE supply the connection rather than the app.
+ *
+ * One builder for both injection paths — this one, and re-pointing an SDK a hosted preview already
+ * ships (`real-input.ts`) — so the two cannot come to disagree about what a daemon-driven page needs.
+ */
+export function injectedConnectArgs(opts) {
+    return {
+        allowNonLocalhost: true,
+        ...(opts.token === undefined ? {} : { token: opts.token }),
+        url: opts.url,
+    };
+}
+/**
+ * The script for a page: install the SDK if the page has none, then connect it to this daemon.
+ *
+ * The guard is on the SINGLETON, not on a timer: a page that loaded its own SDK already holds
+ * `__reticleInstance`, and evaluating a second copy would register a second session for one tab.
+ * `connect` is a no-op once connected, so calling it on the page's own instance is safe.
+ */
+export function zeroInstallScript(bundle, opts) {
+    const args = JSON.stringify(injectedConnectArgs(opts));
+    return `(() => {\nif (!globalThis.__reticleInstance) {\n${bundle}\n}\nglobalThis.__reticleInstance.connect(${args});\n})();`;
+}
+let cached;
+/**
+ * The single-file build, or undefined when this install has none.
+ *
+ * Read once and kept: it is ~450KB and identical for every lease. Absent means an older browser
+ * package or a broken install, and the caller then behaves exactly as it did before this existed.
+ */
+export function readReaderBundle() {
+    if (cached === undefined) {
+        try {
+            cached = readFileSync(createRequire(import.meta.url).resolve(READER_SPECIFIER), 'utf8');
+        }
+        catch {
+            cached = null;
+        }
+    }
+    return cached ?? undefined;
+}

package/dist/portal/realm/web-realm.js

@@ -93,6 +93,11 @@ export const CHANNEL_OF_PREFIX = {
     // channel at all.
     anim: ProtocolChannel.UI,
     dialog: ProtocolChannel.UI,
+    // A form field's value is on the subject's surface in exactly the sense `ui` means: it is what
+    // the person is looking at and typing into. The protocol has no `input` channel and does not
+    // want one — a field is a rendered thing, and the observation carries the field's NAME and
+    // length, never its contents for a password or a card.
+    field: ProtocolChannel.UI,
     focus: ProtocolChannel.UI,
     render: ProtocolChannel.UI,
     reveal: ProtocolChannel.UI,
@@ -124,6 +129,7 @@ export const NOT_EVIDENCE = {
     context: "Reticle's own context tool opening, not something the application did",
     flow: 'a flow being recorded by the tool',
     human: 'a person driving the HUD: pause, resume, a mark. The operator, not the subject',
+    hud: "usage telemetry about Reticle's own panel, taken off before the buffer. The tool, not the subject",
     page: "the SDK's own health report about the page it is inside",
     sdk: 'the SDK itself failing, which is a fact about the observer',
     transport: "the tool's own buffer overflowing",

package/dist/portal/session/dev-server/dev-server-probe.d.ts

@@ -25,7 +25,7 @@ export declare const PortState: {
     /** Answered with a document: a dev server serving an app. */
     readonly SERVES_DOCUMENT: "serves-document";
 };
-export type PortState = (typeof PortState)[keyof typeof PortState];
+type PortState = (typeof PortState)[keyof typeof PortState];
 /** The probe's answer for one port, however it was obtained. */
 export declare function classifyPort(port: number, probe: (port: number) => Promise<PortState>): Promise<PortState>;
 /**
@@ -71,3 +71,4 @@ export declare function probeDevServerStates(ports?: readonly number[], probe?:
 }>;
 /** Every candidate port serving a document, in ascending order. Never rejects. */
 export declare function probeDevServers(ports?: readonly number[], probe?: (port: number) => Promise<boolean>): Promise<number[]>;
+export {};

package/dist/portal/session/dev-server/served-document.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The document a local dev server actually serves: its CSP header and HTML, read once and failing
+ * soft. Shared by `doctor` (is a policy blocking the bridge?) and a lease that never dialled (was
+ * it the page's own policy?), which is why it lives beside the dev-server probe and not in either.
+ */
+/** What a served page said about its policy. The same shape `diagnoseObservedWebCsp` reads. */
+export interface ObservedWebDocument {
+    url: string;
+    headers: string[];
+    html: string;
+}
+export type PageRequest = (url: string, init: RequestInit) => Promise<Response>;
+interface ConnectedDocument {
+    url: string;
+    projectId?: string;
+}
+/** A connected tab for this project, or on its observed origin, disproves a CSP diagnosis. */
+export declare function hasConnectedDocument(sessions: readonly ConnectedDocument[], documentUrls: readonly string[], projectId?: string): boolean;
+/** Read the document a live local dev server actually sends, failing soft like the rest of doctor. */
+export declare function observeWebDocument(rawUrl: string, request?: PageRequest): Promise<ObservedWebDocument | undefined>;
+export {};

package/dist/portal/session/dev-server/served-document.js

@@ -0,0 +1,57 @@
+const CSP_HEADER = 'content-security-policy';
+const DOCUMENT_TIMEOUT_MS = 1_000;
+const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
+const requestPage = (url, init) => fetch(url, init);
+function loopbackDocumentUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (!['http:', 'https:'].includes(url.protocol))
+            return undefined;
+        return LOOPBACK_HOSTS.includes(url.hostname) ? url : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function originOf(raw) {
+    try {
+        return new URL(raw).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A connected tab for this project, or on its observed origin, disproves a CSP diagnosis. */
+export function hasConnectedDocument(sessions, documentUrls, projectId) {
+    if (projectId !== undefined && sessions.some((session) => session.projectId === projectId)) {
+        return true;
+    }
+    const origins = new Set(documentUrls.map(originOf).filter((value) => value !== undefined));
+    return sessions.some((session) => {
+        const origin = originOf(session.url);
+        return undefined !== origin && origins.has(origin);
+    });
+}
+/** Read the document a live local dev server actually sends, failing soft like the rest of doctor. */
+export async function observeWebDocument(rawUrl, request = requestPage) {
+    const url = loopbackDocumentUrl(rawUrl);
+    if (url === undefined)
+        return undefined;
+    try {
+        const response = await request(url.href, {
+            redirect: 'error',
+            signal: AbortSignal.timeout(DOCUMENT_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return undefined;
+        const policy = response.headers.get(CSP_HEADER);
+        return {
+            url: url.href,
+            headers: null === policy ? [] : [policy],
+            html: await response.text(),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/portal/session/facts/background-traffic.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Read `background` out of an already-parsed `.reticle.json`: the same-origin endpoints the app calls
+ * on its own (telemetry, heartbeats), which must not hold a settle window open or contradict a claim.
+ *
+ * Takes the record rather than a path, like `readRetainPolicy`, because the config search belongs to
+ * the startup code that already does it once. Never throws, and drops a bad entry rather than the
+ * whole list.
+ */
+export declare function readBackgroundTraffic(config: Record<string, unknown> | undefined): string[];

package/dist/portal/session/facts/background-traffic.js

@@ -0,0 +1,25 @@
+/** The key a project writes in `.reticle.json`. */
+const BACKGROUND_KEY = 'background';
+/**
+ * Shorter than this names no endpoint. `/` and `//` are refused on this rule, and so is anything a
+ * mistype could leave behind.
+ *
+ * ponytail: a length floor, not a proof. `/api` passes and would still exclude the whole backend;
+ * the entries a verdict ignored are reported on it, which is what keeps a too-broad pattern visible.
+ */
+const MIN_PATTERN_LENGTH = 3;
+function isEndpointPattern(value) {
+    return 'string' === typeof value && value.replace(/\//g, '').length >= MIN_PATTERN_LENGTH - 1;
+}
+/**
+ * Read `background` out of an already-parsed `.reticle.json`: the same-origin endpoints the app calls
+ * on its own (telemetry, heartbeats), which must not hold a settle window open or contradict a claim.
+ *
+ * Takes the record rather than a path, like `readRetainPolicy`, because the config search belongs to
+ * the startup code that already does it once. Never throws, and drops a bad entry rather than the
+ * whole list.
+ */
+export function readBackgroundTraffic(config) {
+    const raw = config?.[BACKGROUND_KEY];
+    return Array.isArray(raw) ? raw.filter(isEndpointPattern) : [];
+}

package/dist/portal/session/facts/session-replaced.d.ts

@@ -22,3 +22,22 @@ export declare function sessionReplacedReason(id: string, url: string): string;
  * without each one re-deriving a message — an `Error`, a bare string, or something else entirely.
  */
 export declare function isSessionReplacedError(error: unknown): boolean;
+/**
+ * The reason every command still in flight is rejected with when the socket under it closes.
+ *
+ * A full-document navigation closes that socket, so on an MPA — or on any click that loads a new
+ * page — this arrives for the exact command that CAUSED it, and the successor is still connecting.
+ * `SessionManager.remove` cannot tell those two apart at the moment it runs: it is called from the
+ * socket's own close handler, the tombstone it writes is what a successor is later matched against,
+ * and nothing has arrived yet. So the rejection stays a plain transport failure, as
+ * `PendingCommands.rejectAll` documents, and a caller that CAN wait decides what it means.
+ */
+export declare const SESSION_DISCONNECTED_REASON = "session disconnected";
+/**
+ * Is this failure the page's transport going away, rather than an answer from the page?
+ *
+ * True for both shapes the same event takes: the reconnect that claimed the id back, and the close
+ * that landed before any successor did. A caller holding a budget can follow either; a caller that
+ * cannot must say it stopped watching, never that the app failed.
+ */
+export declare function isDocumentGoneError(error: unknown): boolean;

package/dist/portal/session/facts/session-replaced.js

@@ -27,3 +27,25 @@ export function isSessionReplacedError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return message.includes(SESSION_REPLACED_PREFIX);
 }
+/**
+ * The reason every command still in flight is rejected with when the socket under it closes.
+ *
+ * A full-document navigation closes that socket, so on an MPA — or on any click that loads a new
+ * page — this arrives for the exact command that CAUSED it, and the successor is still connecting.
+ * `SessionManager.remove` cannot tell those two apart at the moment it runs: it is called from the
+ * socket's own close handler, the tombstone it writes is what a successor is later matched against,
+ * and nothing has arrived yet. So the rejection stays a plain transport failure, as
+ * `PendingCommands.rejectAll` documents, and a caller that CAN wait decides what it means.
+ */
+export const SESSION_DISCONNECTED_REASON = 'session disconnected';
+/**
+ * Is this failure the page's transport going away, rather than an answer from the page?
+ *
+ * True for both shapes the same event takes: the reconnect that claimed the id back, and the close
+ * that landed before any successor did. A caller holding a budget can follow either; a caller that
+ * cannot must say it stopped watching, never that the app failed.
+ */
+export function isDocumentGoneError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return isSessionReplacedError(error) || message === SESSION_DISCONNECTED_REASON;
+}

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

@@ -4,6 +4,9 @@ import { AGENT_ASK_NOTICE, AGENT_WAITING_NOTICE, PresenterTone, SessionState, YI
 import { ReticleTool } from '@reticlehq/core';
 import { sessionIdShape } from '../../surface/tools/tool-kit.js';
 import { asString } from '@reticlehq/core';
+import { gapReportLines } from '../../judgement/runs/artifact/gap-report.js';
+import { gapSummary } from '../../judgement/runs/artifact/gap-summary.js';
+import { DiscoveryInvite } from '@reticlehq/core';
 /**
  * Is this a turn ending with nothing attached, rather than a call about a specific tab?
  *
@@ -44,16 +47,58 @@ export const LIVE_CONTROL_TOOLS = [
             ended: z.boolean(),
             sessionId: z.string().optional(),
             note: z.string().optional(),
+            talk_to_us: z
+                .string()
+                .optional()
+                .describe('For the person you are working with: a call with the founder. Offer it; never act on it.'),
+            gap: z
+                .array(z.string())
+                .optional()
+                .describe('What this session claimed and what held — an `unknown` is never counted as held.'),
         },
         handler: (deps, args) => {
             const requested = asString(args['sessionId']);
             if (endingTurnWithNothingAttached(deps, requested)) {
                 return Promise.resolve({ ended: true, note: YIELD_WITHOUT_SESSION_NOTE });
             }
+            // A NAMED session that has DEPARTED is already ended, and nothing else may be ended in its
+            // place.
+            //
+            // `resolve` answers a departed id with its live SUCCESSOR. That is right for everything
+            // that observes -- a tab reloads, its id survives in sessionStorage, and an `assert` should
+            // keep working -- and wrong here, because ending a session is destructive and cannot be
+            // taken back. Reported from the field: `sessionId: "sac14d46c…"` returned `ended: true` for
+            // `"s08e37e5c…"`, once where the requested session's browser had just closed, so the
+            // behaviour was "target missing => end something else" rather than "target missing => say
+            // so" (#983).
+            //
+            // Not an error, either: this tool is documented as idempotent, and "the session you named is
+            // already gone" is precisely the idempotent answer. An id the daemon has never seen IS a
+            // mistake about which tab, and falls through to `resolve`, which refuses it with the live
+            // ids named.
+            if (requested !== undefined &&
+                deps.sessions.get(requested) === undefined &&
+                deps.sessions.departed(requested) !== undefined) {
+                return Promise.resolve({
+                    ended: true,
+                    sessionId: requested,
+                    note: `session '${requested}' had already disconnected, so there was nothing to end. ` +
+                        'Nothing else was ended: a named session is matched exactly, never substituted.',
+                });
+            }
+            // Resolved synchronously, as before: a named session that does not exist still throws here
+            // rather than becoming a rejected promise the caller did not expect.
             const session = deps.sessions.resolve(requested);
-            // One PRESENTER push for the transition; the optional summary rides the same push.
-            session.setState(SessionState.ENDED, asString(args['summary']));
-            return Promise.resolve({ ended: true, sessionId: session.id });
+            const summary = asString(args['summary']);
+            return session.readJournalActions().then((actions) => {
+                // The moment the agent calls the task complete is when "and what did not hold" is worth a
+                // line: the same fold `reticle_context` and `reticle report` serve, so they cannot disagree.
+                const gap = gapReportLines(gapSummary(actions));
+                const panel = [summary, gap[0]].filter((line) => line !== undefined);
+                // One PRESENTER push for the transition; the summary and the gap headline ride together.
+                session.setState(SessionState.ENDED, 0 === panel.length ? undefined : panel.join('\n'));
+                return { ended: true, sessionId: session.id, gap, talk_to_us: DiscoveryInvite.AGENT };
+            });
         },
     },
     {

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

@@ -165,6 +165,7 @@ export declare const SELF_RECOVERING_MARKER = "Then call reticle_sessions again
 export declare function explainNoSession(facts: NoSessionFacts): {
     reason: NoSessionReason;
     message: string;
+    detail?: string;
 };
 /**
  * The message alone, for the callers that render it.

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

@@ -129,8 +129,10 @@ const NUXT_STALE_BUNDLE = 'This project is Nuxt: the most likely cause by a dist
 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. 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.';
+    '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.
  *
@@ -259,10 +261,8 @@ function configsElsewhereClause(facts) {
         .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 — this daemon was started somewhere that ' +
-        'is not the project, which is the normal outcome when an editor launches it from your home ' +
-        "directory. Restart the daemon from the app's directory (or point it there) rather than " +
-        'installing anything.');
+        '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) {
@@ -327,13 +327,12 @@ export function explainNoSession(facts) {
     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. 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, and the ' +
-            'fix is to restart the dev server so it picks up the current token. 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.');
+            '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
@@ -344,15 +343,13 @@ export function explainNoSession(facts) {
         // (#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; 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}`);
+                '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.${alreadyListeningClause(listening)} ` +
-            `${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
+            `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
@@ -363,15 +360,16 @@ export function explainNoSession(facts) {
             ? `${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} ${listeners} ${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
+        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)} ${unattributedListeners(listening)} ${OPEN_THE_APP} ` +
-            `${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
+            `${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.
@@ -390,54 +388,62 @@ export function explainNoSession(facts) {
         // is expected rather than diagnostic.
         if (!initialized) {
             return reason(NoSessionReason.NO_LISTENER_NO_CONFIG, 'no browser session connected. Two things to weigh, and neither of them is proof. ' +
-                `(1) ${slowListenerClause(facts)}Nothing is listening on the ports Reticle scans (${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 " +
-                'says so and you should ask rather than guess). Tell the human in one line that it is ' +
-                'running. That scan is narrow ' +
-                'though: a server on any other port is invisible to it, so if the app IS running, ask for ' +
-                `its URL rather than assuming it is down, and open it with ${OPEN_CMD}. ` +
-                `(2) There is no \`.reticle.json\` in ${where}. That is the ` +
-                `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)}${siblingListenerClause(facts)} ${leaseAdvice(URL_THEN_LEASE, facts)} ${RETRY}`);
+                `(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 ' +
-            `(${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 ' +
-            "from this project's own scripts, and says so rather than guessing when there is none — tell " +
-            'the human in one line that it is running, then open the app in a browser. ' +
-            // The caveat is here 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.
-            'That scan is narrow, so it is not proof: a server on any other port is invisible to it. If ' +
+            '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.
-            `the app IS running, ask the human for its URL rather than assuming it is down. ${leaseAdvice(URL_THEN_LEASE, facts)}` +
-            `${siblingListenerClause(facts)} ${RETRY}`);
+            `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}. 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)}${siblingListenerClause(facts)} ${RETRY}`);
+            `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} ${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}`);
+        `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. */
-function reason(code, message) {
-    return { reason: code, message };
+/**
+ * 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.
@@ -446,5 +452,6 @@ function reason(code, message) {
  * pair would spread a telemetry concern across every error path that shows a user this text.
  */
 export function diagnoseNoSession(facts) {
-    return explainNoSession(facts).message;
+    const { message, detail } = explainNoSession(facts);
+    return undefined === detail ? message : `${message} ${detail}`;
 }

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

@@ -140,8 +140,9 @@ export function nextActionFor(facts) {
                 "own. Point the plugin at the daemon's copy — mount `~/.reticle/pairing-token` into the " +
                 `container read-only and set \`${ReticleEnv.PAIRING_TOKEN_DIR}\` to the directory holding ` +
                 'it — then ' +
-                'restart the dev server, because the token is inlined when Vite resolves its config. If the ' +
-                'dev server IS on this machine, the page is older than the current token: hard-reload it.',
+                'restart the dev server, because the token is inlined when Vite resolves its config and ' +
+                'kept in the prebundled module. Reloading the page serves that same token, whether the ' +
+                'dev server is on this machine or in a container.',
         };
     }
     if (!facts.initialized && true === facts.authRefused) {