@reticlehq/server 3.2.0 → 3.4.0

package/dist/portal/session/dev-server/dev-command.js

@@ -10,6 +10,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { desktopLaunch } from '@reticlehq/init';
 /**
  * Script names checked, in order.
  *
@@ -47,23 +48,26 @@ function pinnedPort(script) {
     const port = Number.parseInt(digits, 10);
     return Number.isSafeInteger(port) ? port : undefined;
 }
-/** The scripts block of a package.json, or an empty one for anything unreadable/unparseable. */
-function readScripts(raw) {
+/** The parsed package.json, or undefined for anything unreadable/unparseable. */
+function readManifest(raw) {
     if (raw === undefined)
-        return {};
+        return undefined;
     try {
-        const parsed = JSON.parse(raw);
-        if (null === parsed || 'object' !== typeof parsed)
-            return {};
-        const scripts = parsed.scripts;
-        if (null === scripts || 'object' !== typeof scripts)
-            return {};
-        return scripts;
+        return JSON.parse(raw);
     }
     catch {
-        return {};
+        return undefined;
     }
 }
+/** The scripts block of a parsed package.json, or an empty one. */
+function scriptsOf(manifest) {
+    if (null === manifest || 'object' !== typeof manifest)
+        return {};
+    const scripts = manifest.scripts;
+    if (null === scripts || 'object' !== typeof scripts)
+        return {};
+    return scripts;
+}
 /**
  * The dev command for the project in `directory`, or undefined when there is not one to be sure of.
  *
@@ -71,9 +75,23 @@ function readScripts(raw) {
  * default disk reader.
  */
 export function detectDevCommand(directory, read = readTextFile) {
-    const scripts = readScripts(read(join(directory, PACKAGE_JSON)));
+    const manifest = readManifest(read(join(directory, PACKAGE_JSON)));
+    const scripts = scriptsOf(manifest);
     const manager = LOCKFILES.find(({ file }) => read(join(directory, file)) !== undefined)?.manager ??
         DEFAULT_PACKAGE_MANAGER;
+    // A desktop shell's `dev` is its renderer's dev server, which no window ever opens onto. init's
+    // rule decides which launcher it is, so the command the daemon hands an agent and the one init
+    // spawns are the same.
+    const desktop = desktopLaunch(manifest);
+    if (desktop !== undefined) {
+        if ('command' in desktop)
+            return { command: desktop.command };
+        const command = `${manager} run ${desktop.script}`;
+        return {
+            command: 0 < desktop.args.length ? `${command} ${desktop.args}` : command,
+            script: desktop.script,
+        };
+    }
     for (const script of DEV_SCRIPTS) {
         const body = scripts[script];
         if ('string' !== typeof body || 0 === body.trim().length)

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/dev-server-probe.js

@@ -64,6 +64,15 @@ export function classifyPort(port, probe) {
  * accepts v4-mapped connections — so between the two, every ordinary bind is covered.
  */
 export const PROBE_HOSTS = ['127.0.0.1', '::1'];
+/**
+ * The name the probe gives in its Host header, whichever address it dialled.
+ *
+ * Node names the dialled address, so the `::1` probe sent `Host: [::1]:4200`. Angular's SSR dev
+ * server validates Host, answered 400, and printed `ERROR: Bad Request ("http://[::1]:4200/")` into
+ * the user's dev terminal on every sweep, for as long as the daemon ran. The address picks the
+ * family; the header says what a browser on this machine would.
+ */
+const PROBE_HOST_HEADER = 'localhost';
 /**
  * Does this port serve a DOCUMENT — i.e. is it a dev server rather than merely something listening?
  *
@@ -76,7 +85,14 @@ function probeState(port, host) {
         // Whether the SOCKET came up is tracked separately from whether a response did, because that is
         // the whole difference between "nothing is there" and "something is there and still compiling".
         let connected = false;
-        const req = request({ host, port, path: '/', method: 'GET', timeout: HTTP_PROBE_TIMEOUT_MS }, (res) => {
+        const req = request({
+            host,
+            port,
+            path: '/',
+            method: 'GET',
+            timeout: HTTP_PROBE_TIMEOUT_MS,
+            headers: { host: `${PROBE_HOST_HEADER}:${String(port)}` },
+        }, (res) => {
             const answer = looksLikeDevServer(res.statusCode ?? 0, res.headers['content-type']);
             res.resume(); // drain, so the socket closes rather than lingering
             resolve(answer ? PortState.SERVES_DOCUMENT : PortState.CLOSED);

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

@@ -0,0 +1,24 @@
+/**
+ * What does the route a tab died on answer right now?
+ *
+ * A route that throws server-side tears the page down and the SDK never reconnects, so the daemon
+ * is left with an empty session list and the URL it last saw (#862). The URL alone cannot separate
+ * "the route 500s" from "somebody closed the tab" — one plain GET can, and the daemon is the only
+ * party placed to make it: the page is gone, the agent is inside an MCP call, and the daemon is on
+ * the same machine as the dev server.
+ *
+ * What it refuses to do, because this runs unattended in a diagnostic loop:
+ *   - only loopback hostnames — the daemon is localhost-only and a diagnostic must not reach out;
+ *   - only `http:` — `https:` on localhost means a self-signed certificate, and fetching it with
+ *     verification off would be a posture change for a status code;
+ *   - GET only, redirects not followed, the body never read — the status is the only thing that
+ *     leaves the socket, and it is drained so the connection closes rather than lingers;
+ *   - an error or a timeout is `undefined`, never a status. No fact is better than a wrong one.
+ *
+ * Same shape as its neighbour `dev-server-probe.ts`, which asks a port whether it serves a document; this asks
+ * one exact path what it answers.
+ */
+/** Short on purpose: a dev server that has not answered a route in this long is not going to. */
+export declare const ROUTE_STATUS_TIMEOUT_MS = 2000;
+/** The HTTP status `url` answers a GET with, or undefined when there is no answer to report. */
+export declare function probeRouteStatus(url: string, timeoutMs?: number): Promise<number | undefined>;

package/dist/portal/session/dev-server/route-status-probe.js

@@ -0,0 +1,57 @@
+/**
+ * What does the route a tab died on answer right now?
+ *
+ * A route that throws server-side tears the page down and the SDK never reconnects, so the daemon
+ * is left with an empty session list and the URL it last saw (#862). The URL alone cannot separate
+ * "the route 500s" from "somebody closed the tab" — one plain GET can, and the daemon is the only
+ * party placed to make it: the page is gone, the agent is inside an MCP call, and the daemon is on
+ * the same machine as the dev server.
+ *
+ * What it refuses to do, because this runs unattended in a diagnostic loop:
+ *   - only loopback hostnames — the daemon is localhost-only and a diagnostic must not reach out;
+ *   - only `http:` — `https:` on localhost means a self-signed certificate, and fetching it with
+ *     verification off would be a posture change for a status code;
+ *   - GET only, redirects not followed, the body never read — the status is the only thing that
+ *     leaves the socket, and it is drained so the connection closes rather than lingers;
+ *   - an error or a timeout is `undefined`, never a status. No fact is better than a wrong one.
+ *
+ * Same shape as its neighbour `dev-server-probe.ts`, which asks a port whether it serves a document; this asks
+ * one exact path what it answers.
+ */
+import { request } from 'node:http';
+import { isLoopbackHostname } from '@reticlehq/core';
+/** Short on purpose: a dev server that has not answered a route in this long is not going to. */
+export const ROUTE_STATUS_TIMEOUT_MS = 2_000;
+const HTTP = 'http:';
+/** The HTTP status `url` answers a GET with, or undefined when there is no answer to report. */
+export function probeRouteStatus(url, timeoutMs = ROUTE_STATUS_TIMEOUT_MS) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return Promise.resolve(undefined);
+    }
+    if (parsed.protocol !== HTTP || !isLoopbackHostname(parsed.hostname)) {
+        return Promise.resolve(undefined);
+    }
+    return new Promise((resolve) => {
+        const req = request({
+            host: parsed.hostname,
+            port: parsed.port,
+            path: `${parsed.pathname}${parsed.search}`,
+            method: 'GET',
+            timeout: timeoutMs,
+        }, (res) => {
+            const status = res.statusCode;
+            res.resume(); // drain, so the socket closes rather than lingering
+            resolve(status);
+        });
+        req.once('timeout', () => {
+            req.destroy();
+            resolve(undefined);
+        });
+        req.once('error', () => resolve(undefined));
+        req.end();
+    });
+}

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/observed-state.d.ts

@@ -48,6 +48,8 @@ export declare class ObservedState {
     actedRefs(): ReadonlySet<string>;
     /** Every driven control's label, for matching across re-renders. */
     actedLabels(): ReadonlySet<string>;
+    recordProvedLabel(label: string): void;
+    provedLabels(): ReadonlySet<string>;
     /**
      * Record bridge-side sampling as a blind spot.
      *
@@ -58,3 +60,12 @@ export declare class ObservedState {
     noteRateLimited(dropped: number): void;
     blindSpots(): Readonly<Record<string, number>>;
 }
+/**
+ * The snapshot-shaped labels an act reply names its control by: the testid, and `role "name"`.
+ *
+ * The TESTID first: it is the strongest identity a control has and it survives any re-render.
+ * Coverage previously matched only on `role "name"`, so a control with a testid but no accessible
+ * name — or on a stack where the act reply carried neither — was unrecognisable after a re-render,
+ * and coverage read `exercised: 0` however much work had been done.
+ */
+export declare function controlLabelsOf(payload: unknown): string[];

package/dist/portal/session/facts/observed-state.js

@@ -105,6 +105,18 @@ export class ObservedState {
     actedLabels() {
         return this.#actedLabels;
     }
+    /**
+     * Controls whose action came back `verified: "yes"` on a declared consequence — the PROVED level
+     * of the coverage ledger. Same label identity as `actedLabels`, so the two compare directly.
+     */
+    #provedLabels = new Set();
+    recordProvedLabel(label) {
+        if (label.length > 0)
+            this.#provedLabels.add(label);
+    }
+    provedLabels() {
+        return this.#provedLabels;
+    }
     /**
      * Record bridge-side sampling as a blind spot.
      *
@@ -119,3 +131,25 @@ export class ObservedState {
         return this.#blindSpots;
     }
 }
+/**
+ * The snapshot-shaped labels an act reply names its control by: the testid, and `role "name"`.
+ *
+ * The TESTID first: it is the strongest identity a control has and it survives any re-render.
+ * Coverage previously matched only on `role "name"`, so a control with a testid but no accessible
+ * name — or on a stack where the act reply carried neither — was unrecognisable after a re-render,
+ * and coverage read `exercised: 0` however much work had been done.
+ */
+export function controlLabelsOf(payload) {
+    if (typeof payload !== 'object' || null === payload)
+        return [];
+    const record = payload;
+    const labels = [];
+    const testid = record['testid'];
+    if ('string' === typeof testid && testid.length > 0)
+        labels.push(testid);
+    const role = record['role'];
+    const name = record['name'];
+    if ('string' === typeof role && 'string' === typeof name && role.length > 0 && name.length > 0)
+        labels.push(`${role} "${name}"`);
+    return labels;
+}

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

@@ -91,6 +91,20 @@ export interface NoSessionFacts {
      * already read it; the message did not.
      */
     authRefused?: boolean;
+    /**
+     * The bridge refused the last hello for something OTHER than its token — a protocol number out of
+     * range, or a hello that failed the wire schema outright — and nothing has connected since.
+     *
+     * The same positive evidence as `authRefused`, with a different fix. Without it the daemon had
+     * recorded the refusal and `init` still ended on "the SDK is in the page and never dialled the
+     * bridge", about a page that dialled and was turned away. `reason` follows the `cause — fix`
+     * shape the bridge writes; the page and project are what the refused hello said about itself.
+     */
+    helloRefused?: {
+        reason: string;
+        url?: string;
+        projectId?: string;
+    };
     /**
      * The framework `.reticle.json` declares, when there is one.
      *
@@ -100,6 +114,14 @@ export interface NoSessionFacts {
      * hint the agent reads hours later never mentioned it.
      */
     framework?: string;
+    /**
+     * The project is a desktop shell (Electron, Tauri), read from the project the way `doctor` reads it.
+     *
+     * Its page exists only inside its own window, so every "open the app's URL in a browser" and
+     * every lease offer below is the wrong move there: it loads the renderer without the shell's IPC
+     * bridge or native APIs, which is not the app being verified. Absent means web.
+     */
+    desktop?: boolean;
     /**
      * `.reticle.json` files found OUTSIDE this daemon's directory — a workspace app, a repo root.
      *
@@ -144,6 +166,13 @@ export interface NoSessionFacts {
      * or the ring has forgotten — inventing a URL is worse than the silence this exists to end.
      */
     lastKnownUrl?: string;
+    /**
+     * What a plain GET of `lastKnownUrl` answered, done out of band by the watch after the session
+     * went. The one fact that separates a server error from a closed tab and from an install
+     * problem (#808, option 3). Present only when the fetch got an HTTP status back — a failed or
+     * timed-out fetch is no fact, and this stays absent rather than guessing.
+     */
+    lastKnownStatus?: number;
 }
 /**
  * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session

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

@@ -17,6 +17,10 @@ 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';
+/** How every hello-refusal reason the bridge records separates its cause from its fix. */
+const CAUSE_FIX_SEPARATOR = ' — ';
+/** The lowest HTTP status that means the server itself failed to answer the route. */
+const SERVER_ERROR_FLOOR = 500;
 /** The one framework whose most likely cause differs from every other framework's. */
 const NUXT = 'nuxt';
 /**
@@ -49,6 +53,8 @@ const URL_THEN_LEASE = 'Once you have that URL, open it with reticle_lease {acti
  * diagnosed the problem.
  */
 function leaseAdvice(base, facts) {
+    if (true === facts.desktop)
+        return DESKTOP_NO_BROWSER;
     const caveat = leaseCaveat(facts.leaseBrowser);
     return caveat === undefined ? base : `${base} ${caveat}`;
 }
@@ -180,6 +186,25 @@ function slowListenerClause(facts) {
 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).';
+/**
+ * The desktop twin of OPEN_THE_APP. A desktop app's page exists only inside its own window, and the
+ * guidance used to send an Electron user to a browser URL — which reaches the renderer's dev server
+ * and none of the app around it.
+ */
+const DESKTOP_OPEN_THE_APP = 'This is a desktop app, and Reticle sees it only from inside its own window, so the commonest ' +
+    'cause by a distance is that the desktop app is not running: start it yourself, in the ' +
+    "background, with the project's desktop dev command (the script that runs `tauri dev`, " +
+    '`electron-vite dev`, `electron-forge start` or `electron .`), not the plain web dev server.';
+/** Why the browser and lease routes are withheld for a desktop app. Replaces the lease offer. */
+const DESKTOP_NO_BROWSER = 'Do not open its URL in a browser or with a lease: that loads the renderer outside the desktop ' +
+    'shell, without its IPC bridge or native APIs, so it is not the app you are verifying.';
+function openTheApp(facts) {
+    return true === facts.desktop ? DESKTOP_OPEN_THE_APP : OPEN_THE_APP;
+}
+/** The "(or run open)" aside — a desktop window is reopened by the app, not by a browser command. */
+function orOpenCommand(facts) {
+    return true === facts.desktop ? '' : ` (or run ${OPEN_CMD_BARE})`;
+}
 /**
  * What a machine-wide port scan can and cannot say.
  *
@@ -334,6 +359,22 @@ export function explainNoSession(facts) {
             '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.');
     }
+    // Beside the token refusal and for the same reason: a turned-away hello is current, positive
+    // evidence, and every branch below reasons from an absence.
+    if (facts.helloRefused !== undefined) {
+        const { reason: said, url, projectId } = facts.helloRefused;
+        const split = said.indexOf(CAUSE_FIX_SEPARATOR);
+        const cause = -1 === split ? said : said.slice(0, split);
+        const fix = -1 === split ? undefined : said.slice(split + CAUSE_FIX_SEPARATOR.length);
+        const page = undefined === url || '' === url ? 'a page' : `the page at ${url}`;
+        const project = undefined === projectId ? '' : ` (project ${projectId})`;
+        return reason(
+        // ponytail: shares the token refusal's code, because a new code is a telemetry wire change
+        // and that surface has its own owner; split it out as `hello_refused` there.
+        NoSessionReason.AUTH_REFUSED, `no browser session connected: ${page}${project} dialled this daemon and was REFUSED ` +
+            `because ${cause}${undefined === fix ? '' : `; fix: ${fix}`}. Only an SDK dials the ` +
+            'bridge, so the app is running and instrumented — do not go looking for a stopped dev server.');
+    }
     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):
@@ -347,9 +388,25 @@ export function explainNoSession(facts) {
                 `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)}`);
         }
+        // Ranked above TAB_GONE because it is not an absence: the route itself answered. A tab that a
+        // 5xx tore down and a tab a human closed produce the same empty list, and until the watch asked
+        // the route, they produced the same sentence. Present tense throughout — "answers ... right
+        // now" — because a 500 now does not prove the teardown was a 500 then, and saying so would
+        // turn an observation into a story.
+        if (facts.lastKnownStatus !== undefined &&
+            facts.lastKnownStatus >= SERVER_ERROR_FLOOR &&
+            facts.lastKnownUrl !== undefined &&
+            '' !== facts.lastKnownUrl) {
+            return reason(NoSessionReason.ROUTE_SERVER_ERROR, 'no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
+                `is correct. The page was torn down while on ${facts.lastKnownUrl}, and that route answers ` +
+                `HTTP ${String(facts.lastKnownStatus)} right now — a server error in the app, not a closed ` +
+                'tab and not an install problem. A route that throws server-side tears the page down and ' +
+                'the SDK cannot reconnect to it. Fix the route, then reload the tab' +
+                `${orOpenCommand(facts)}.${alreadyListeningClause(listening)} ${RETRY}`);
+        }
         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());
+            `the app${orOpenCommand(facts)}, 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
@@ -360,14 +417,14 @@ 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} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, `${DO_NOT_REINSTALL} ${listeners} ${rankedCauses(facts)}`);
+        return reason(NoSessionReason.APP_NOT_REOPENED, `${RESTARTED_LEAD} ${openTheApp(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, `${DO_NOT_REINSTALL} ${listeners} ${rankedCauses(facts)}`);
     }
     // A config found elsewhere outranks every "you may have no SDK" branch below: those reason from
     // 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 ' +
+            `${configsElsewhereClause(facts)} ${openTheApp(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, 'This daemon was started somewhere that is not the project, which is the normal outcome when ' +
             `an editor launches it from your home directory. ${unattributedListeners(listening)} ` +
             `${rankedCauses(facts)}`);
     }
@@ -399,7 +456,7 @@ export function explainNoSession(facts) {
                 '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} ` +
+        return reason(NoSessionReason.NO_LISTENER, `${stallClause(facts)}no browser session connected, and this daemon has never seen one. ${openTheApp(facts)} ` +
             'Nothing is listening on the ports Reticle scans either, and the usual reason is a dev ' +
             'server that is not running: start it yourself in the background with the command in ' +
             '`next_action`, tell the human in one line that it is running, then open the app in a ' +
@@ -428,7 +485,7 @@ export function explainNoSession(facts) {
             `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 ` +
+        `wired for Reticle. ${openTheApp(facts)} If the page IS open and still does not appear, the SDK ` +
         `is not reaching this daemon (on ${String(port)}). ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, `${unattributedListeners(listening)} ${rankedCauses(facts)}`);
 }
 /**