@reticlehq/server 3.2.0 → 3.4.0

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

@@ -69,6 +69,19 @@ interface NextActionFacts {
      * action that cannot help and can overwrite it.
      */
     authRefused?: boolean;
+    /**
+     * The bridge refused the last hello for a non-token reason (protocol or wire-contract skew), in
+     * the bridge's own `cause — fix` sentence. Current, like `authRefused`: nothing connected since.
+     * Every other action below would send the agent to start, open or re-wire an app that is running,
+     * instrumented and being turned away.
+     */
+    helloRefused?: string;
+    /**
+     * The url the session that went away was on, from the daemon's own tombstone. Positive evidence
+     * about where THIS project's app lives, which the port scan is not: the scan is machine-wide, and
+     * its one hit is as likely to be another repo's dev server as this one's.
+     */
+    lastKnownUrl?: string;
 }
 export declare function nextActionFor(facts: NextActionFacts): NoSessionNextAction;
 /** The same action as one sentence, for the prose message the human reads. */

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

@@ -12,7 +12,29 @@
  *
  * Pure. The facts arrive from the watch; nothing here touches the disk or the clock.
  */
-import { NoSessionAction, ReticleEnv } from '@reticlehq/core';
+import { NoSessionAction, RETICLE_URL_PARAM, ReticleEnv } from '@reticlehq/core';
+/**
+ * The departed session's url as a human would type it: the params a Reticle launcher stamps on a
+ * lease are stripped, because reopening WITH them would adopt the dead lease's identity. Undefined
+ * for a url that does not parse, or one with no port to name (a desktop webview's opaque origin).
+ */
+function reopenableUrl(raw) {
+    if (raw === undefined)
+        return undefined;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if ('http:' !== url.protocol && 'https:' !== url.protocol)
+        return undefined;
+    for (const param of Object.values(RETICLE_URL_PARAM))
+        url.searchParams.delete(param);
+    const port = '' === url.port ? ('https:' === url.protocol ? 443 : 80) : Number(url.port);
+    return { url: url.toString(), port };
+}
 /** `reticle init`, the only command here that is Reticle's own and so cannot be wrong. */
 const INIT_COMMAND = 'reticle init';
 const OPEN_COMMAND = 'reticle open';
@@ -28,6 +50,13 @@ export function nextActionFor(facts) {
     if (splitBrain !== undefined) {
         return { action: NoSessionAction.DAEMON_SPLIT, reason: splitBrain };
     }
+    if (facts.helloRefused !== undefined) {
+        return {
+            action: NoSessionAction.OPEN_APP,
+            reason: `a page dialled this daemon and was refused (${facts.helloRefused}); do that, then reload ` +
+                'the page — the SDK does not retry after a refusal.',
+        };
+    }
     // `authRefused` is checked here and not only further down, because this branch short-circuits.
     //
     // Both refusal branches below were already written and already right, and neither could be
@@ -44,16 +73,24 @@ export function nextActionFor(facts) {
     if (facts.everConnected && true !== facts.authRefused) {
         const listening = facts.listening;
         const only = 1 === listening.length ? listening[0] : undefined;
-        const bound = 0 === listening.length
-            ? ''
+        // The departed session's own url first: it is where this project's app demonstrably was, while
+        // a lone port from the scan may belong to anybody.
+        const known = reopenableUrl(facts.lastKnownUrl);
+        const bound = known !== undefined
+            ? ` It was last on ${known.url}; reopen that — do not start a second stack.`
+            : 0 === listening.length
+                ? ''
+                : only === undefined
+                    ? ` An app is already listening on ${listening.join(', ')}; just open the URL the human names — do not start a second stack.`
+                    : ` An app is already listening on ${String(only)}; just open ${LOCALHOST}:${String(only)} — do not start a second stack.`;
+        const target = known !== undefined
+            ? { command: `${OPEN_COMMAND} ${known.url}`, port: known.port }
             : only === undefined
-                ? ` An app is already listening on ${listening.join(', ')}; just open the URL the human names — do not start a second stack.`
-                : ` An app is already listening on ${String(only)}; just open ${LOCALHOST}:${String(only)} — do not start a second stack.`;
+                ? {}
+                : { command: `${OPEN_COMMAND} ${LOCALHOST}:${String(only)}`, port: only };
         return {
             action: NoSessionAction.REOPEN_APP,
-            ...(only === undefined
-                ? {}
-                : { command: `${OPEN_COMMAND} ${LOCALHOST}:${String(only)}`, port: only }),
+            ...target,
             reason: 'a session was connected to this daemon earlier, so the wiring is correct — the tab was ' +
                 'closed, reloaded, or the lease aged out. Reopen the app, or take one you own with ' +
                 'reticle_lease {action:"acquire", url}.' +
@@ -108,7 +145,9 @@ export function nextActionFor(facts) {
             // does not cover, it reported the app was not running.
             reason: 'nothing is listening on the ports Reticle scans, so the app is probably not running — ' +
                 'though that scan is narrow, so if it IS up on another port, ask for its URL instead of ' +
-                `starting a second one. This is the project's own \`${dev.script}\` script — run it in the ` +
+                `starting a second one. This is the project's own ` +
+                (undefined === dev.script ? 'launcher' : `\`${dev.script}\` script`) +
+                ` — run it in the ` +
                 'background, tell the human it is running, then call reticle_sessions again.',
         };
     }

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

@@ -45,6 +45,24 @@ interface NoSessionWatchOptions {
      * Omitted on a daemon with no pool, and auto-attach is then simply off.
      */
     attach?: (url: string) => Promise<unknown>;
+    /**
+     * The ports THIS project's dev servers announced into the registry the build plugins write.
+     *
+     * Auto-attach opens a port only when it can be attributed to this project. The port scan is
+     * machine-wide, so its one hit is as likely to be another repo's app as this one's — and now that
+     * the attach path can launch an installed Chrome, a wrong guess parks a hidden headless browser on
+     * somebody else's app. Injected for tests; production reads the registry scoped by projectId/root.
+     */
+    ownDevServerPorts?: () => readonly number[];
+    /**
+     * What the route the last session was on answers right now, as an HTTP status, or undefined
+     * when there is no answer to report.
+     *
+     * Injected so tests can pin the observation without opening a socket. Production (no override)
+     * asks the route itself — see route-status-probe. The one fact that separates a route that 500s
+     * from a closed tab (#808, option 3).
+     */
+    routeStatus?: (url: string) => Promise<number | undefined>;
     /**
      * Where the durable "an app has connected here before" bit lives. The daemon's state home unless
      * a test says otherwise.

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

@@ -9,13 +9,14 @@
  * It only probes while NOTHING is connected. Once a session is live the question is moot, and a
  * daemon that outlives the agent by hours has no business scanning ports it does not need.
  */
+import { probeRouteStatus } from './dev-server/route-status-probe.js';
 import { probeDevServers, probeDevServerStates } from './dev-server/dev-server-probe.js';
 import { homedir } from 'node:os';
 import { registeredElsewhere } from '../../memory/recall/registered-projects.js';
 import { explainNoSession } from './no-session-diagnosis.js';
 import { detectDevCommand } from './dev-server/dev-command.js';
 import { nextActionFor, renderNextAction } from './no-session-next-action.js';
-import { readProjectFramework, readProjectId, readProjectPort, } from '../../command/cli/ports/resolve/cli-port.js';
+import { readProjectFramework, readProjectId, readProjectIsDesktop, readProjectPort, } from '../../command/cli/ports/resolve/cli-port.js';
 import { discoverProjectConfigs } from '../../command/cli/config/config-discovery.js';
 import { hasProjectConnectedBefore, rememberConnected, } from '../../memory/recall/prior/connection-memory.js';
 import { isAlive, reticleStateHome } from '../../command/daemon/daemon.js';
@@ -24,6 +25,8 @@ import { stallUptime } from './stall-clock.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
 import { findOccupiedSiblings } from '../../command/cli/ports/sibling-ports.js';
 import { isAuthRefusalReason } from '../bridge/auth-failure-reason.js';
+import { devServersForProject } from '@reticlehq/core';
+import { readDevServers } from '../../command/daemon/dev-servers.js';
 /** Slow enough to be free, fast enough that a dev server started 15s ago is already reflected. */
 const REFRESH_MS = 15_000;
 /** The URL an auto-attach opens. `localhost` for the same reason the probe uses it: both stacks. */
@@ -63,6 +66,15 @@ export function startNoSessionWatch(options) {
      */
     let slowListeners = [];
     let siblingListeners = [];
+    /**
+     * What the last-known route answered, cached beside the port scan for the same reason the scan
+     * is cached: the hint is read synchronously, so every fact it carries has to be gathered before
+     * it is asked. Keyed by URL so a status is never attributed to a route other than the one it
+     * came from — a fresh departure on a different URL reads as "not asked yet", not as the old
+     * answer.
+     */
+    let lastKnownStatus;
+    const routeStatus = options.routeStatus ?? probeRouteStatus;
     let running = false;
     /** Ports auto-attach has already spent its one attempt on. Bounded: never a loop, never a retry. */
     const attempted = new Set();
@@ -155,6 +167,31 @@ export function startNoSessionWatch(options) {
      * Bounded by construction: one attempt per port per daemon. A failure is recorded, never retried —
      * a retry loop against a broken Chromium install would spin for the daemon's whole life.
      */
+    const ownDevServerPorts = options.ownDevServerPorts ??
+        (() => devServersForProject(readDevServers(stateDir), {
+            projectId: readProjectId(directory),
+            root: directory,
+        }).map((entry) => entry.port));
+    /**
+     * Is `port` demonstrably this project's app? Either its dev server announced it, or this
+     * project's own last session was on it. Anything else is a guess, and a guess that opens a
+     * browser is worse than the sentence the diagnosis already writes about the ports it saw.
+     */
+    const attributable = (port) => {
+        if (ownDevServerPorts().includes(port))
+            return true;
+        const known = options.sessions.lastKnown?.();
+        const projectId = readProjectId(directory);
+        if (known === undefined || projectId === undefined || known.projectId !== projectId) {
+            return false;
+        }
+        try {
+            return Number(new URL(known.url).port) === port;
+        }
+        catch {
+            return false;
+        }
+    };
     const autoAttach = async (ports) => {
         const attach = options.attach;
         if (attach === undefined)
@@ -166,6 +203,8 @@ export function startNoSessionWatch(options) {
             return;
         if (!isWired())
             return;
+        if (!attributable(only))
+            return;
         attempted.add(only);
         try {
             await attach(`${LOCALHOST}:${String(only)}`);
@@ -193,6 +232,14 @@ export function startNoSessionWatch(options) {
                     : options.probe === undefined
                         ? await findOccupiedSiblings(options.port, probeDaemon)
                         : [];
+            // Asked once per departed URL, on the same background cadence as the port scan, and never
+            // on the hint's own path. A url already answered is not asked again; a new departure is.
+            const known = options.sessions.lastKnown?.();
+            if (known !== undefined && lastKnownStatus?.url !== known.url) {
+                const status = await routeStatus(known.url);
+                if (status !== undefined)
+                    lastKnownStatus = { url: known.url, status };
+            }
             await autoAttach(ports);
         })
             .catch(() => {
@@ -225,6 +272,21 @@ export function startNoSessionWatch(options) {
      */
     const lastCloseWasAuthFailure = () => isAuthRefusalReason(options.sessions.lastClosure?.()?.reason) &&
         true !== options.sessions.connectedSinceLastClosure?.();
+    /**
+     * A hello refused for anything but its token, while it is still the bridge's current state.
+     *
+     * Only closures that carry the refused page count: the bridge attaches one exactly when a HELLO
+     * was turned away, so an origin or handshake-pool refusal (which has its own sentence on
+     * `resolve`) is not mistaken for one. Same ordering clause as the token refusal above.
+     */
+    const currentHelloRefusal = () => {
+        const closure = options.sessions.lastClosure?.();
+        if (closure?.page === undefined || isAuthRefusalReason(closure.reason))
+            return undefined;
+        if (true === options.sessions.connectedSinceLastClosure?.())
+            return undefined;
+        return { reason: closure.reason, ...closure.page };
+    };
     const nextAction = (scope) => {
         const split = splitBrain();
         return nextActionFor({
@@ -235,8 +297,18 @@ export function startNoSessionWatch(options) {
             // Read when asked, like every other fact here: a page can dial at any moment, and a daemon
             // that cached "nothing has been refused" at boot would keep saying so.
             authRefused: lastCloseWasAuthFailure(),
+            ...(() => {
+                const refused = currentHelloRefusal();
+                return refused === undefined ? {} : { helloRefused: refused.reason };
+            })(),
             ...(split === undefined ? {} : { splitBrain: split }),
             listening,
+            // The url the departed tab was on — the same tombstone the prose diagnosis quotes, so the
+            // command and the sentence beside it name the same page.
+            ...(() => {
+                const known = options.sessions.lastKnown?.();
+                return known === undefined ? {} : { lastKnownUrl: known.url };
+            })(),
             // Read when asked, like everything else here: a `package.json` can gain a dev script, and a
             // daemon that cached "there is none" at boot would keep saying so for the rest of the day.
             dev: detectDevCommand(directory),
@@ -272,12 +344,19 @@ export function startNoSessionWatch(options) {
             // beside it still said the tab had been closed. One fact, two answers, and only one of them
             // was right. Read when asked, like the rest: a page can be refused at any moment.
             authRefused: lastCloseWasAuthFailure(),
+            ...(() => {
+                const refused = currentHelloRefusal();
+                return refused === undefined ? {} : { helloRefused: refused };
+            })(),
             // Ranks the causes. Read when asked, like the rest: `init` writes this file after the daemon
             // starts on an ordinary first install.
             ...(() => {
                 const framework = readProjectFramework(directory);
                 return framework === undefined ? {} : { framework };
             })(),
+            // A desktop app is opened by its own dev command, never by a browser URL or a lease. Read when
+            // asked, like the framework: `init` may wire the app after this daemon started.
+            ...(readProjectIsDesktop(directory) ? { desktop: true } : {}),
             // Decided from the session that actually went away, not from a lifetime tally: the lease
             // sentence is only right when the thing that vanished WAS a lease.
             leaseExpired: (() => {
@@ -289,7 +368,14 @@ export function startNoSessionWatch(options) {
             // has none to name.
             ...(() => {
                 const known = options.sessions.lastKnown?.();
-                return undefined === known ? {} : { lastKnownUrl: known.url };
+                if (undefined === known)
+                    return {};
+                // The status rides only when it was fetched for THIS url. A departure since the fetch
+                // means the cached answer is about a route nobody is asking about.
+                const status = lastKnownStatus !== undefined && lastKnownStatus.url === known.url
+                    ? { lastKnownStatus: lastKnownStatus.status }
+                    : {};
+                return { lastKnownUrl: known.url, ...status };
             })(),
             // How long this daemon has been waiting with no app. The diagnosis uses it to surface
             // "install never finished" — the same condition telemetry already knows about.

package/dist/portal/session/presence/attachment-history.d.ts

@@ -15,11 +15,22 @@
  * The clock is injected, per the repo rule: this is arithmetic over timestamps, and a test that
  * needs to wait four seconds to check a four-second gap is a test nobody runs.
  */
-/** What an agent needs to know about the continuity of one session. */
+/**
+ * What an agent needs to know about the continuity of one session.
+ *
+ * Every field here measures the SDK-to-daemon LINK. None of them measures the app: the origin the
+ * page was served from can stop answering entirely without any of these moving, because the socket
+ * that reports them is between the daemon and a document the browser is already holding. Reported
+ * as a false read of app health in #938, where a tab whose dev server was dead carried `outages: 0`
+ * and `connectedSinceMs: 11min` and was taken for a healthy app.
+ */
 interface Attachment {
     /** How long THIS attachment has lasted. Resets on reconnect — it is not the session's lifetime. */
     connectedSinceMs: number;
-    /** How many times this session dropped and came back. Zero means it never left. */
+    /**
+     * How many times this session dropped and came back. Zero means the LINK never dropped; it does
+     * not mean the app behind it is alive.
+     */
     outages: number;
     /** The most recent gap, when there has been one. */
     lastOutage?: {

package/dist/portal/session/session-health.d.ts

@@ -38,6 +38,22 @@ export interface SessionHealth {
      * on `reticle_sessions` or `reticle_lease` is not on the surface it reads every call.
      */
     versionSkew?: string;
+    /**
+     * The session's event ledger, once it has grown enough to be worth a reader's attention.
+     *
+     * Present only past `LEDGER_NOTICE_FRACTION` of the cap, so a healthy session costs nothing --
+     * the same rule `pendingNavigationMs` follows. A ledger below that is doing its job quietly.
+     *
+     * It is here because nothing reported it. A repeating uncaught error wrote one session's ledger
+     * until the disk was full; neither the daemon nor `doctor` nor any
+     * health counter said a word, and the user found out when the disk was full (#986). A cap bounds
+     * the damage but does not make the writing visible, and this block is the surface an agent
+     * already reads on every act and assert.
+     */
+    ledger?: {
+        bytes: number;
+        capBytes: number;
+    };
 }
 /**
  * How long a request may be in flight before it is worth reporting on session health.
@@ -84,6 +100,18 @@ interface BufferEnvelope {
  * so a clean/empty result there is trustworthy and costs zero tokens.
  */
 export declare function bufferEnvelope(session: HealthSubject): BufferEnvelope;
+/**
+ * The session registered under `session.id` NOW, for describing a tab after a call that may have
+ * replaced its document. A reload or full navigation registers a new Session under the same id, and
+ * the object a handler resolved first is the page that unloaded; it reported itself hidden on the way
+ * out, so its health said "throttled" about a tab that was fine. Optional-called because test doubles
+ * are partial registries.
+ */
+export declare function currentOf<S extends {
+    id: string;
+}>(registry: {
+    get?: (id: string) => S | undefined;
+}, session: S): S;
 /** The `session` (and optional throttled `warning`) block spliced onto act/assert results. */
 interface HealthEnvelope {
     session?: SessionHealth;
@@ -142,4 +170,37 @@ interface HealthReport {
  * keep its previous value instead of silently flipping a session to "visible" on a partial report.
  */
 export declare function readHealthEvent(data: Record<string, unknown>): HealthReport;
+/**
+ * The ledger block for the health payload, or nothing when it is not worth saying.
+ *
+ * Absent below `LEDGER_NOTICE_FRACTION` of the cap, and absent when the size has not been measured
+ * yet -- a reader must be able to tell "not measured" from "empty", and a zero reported before the
+ * first append would be a claim rather than a reading.
+ */
+export declare function ledgerNotice(ledger: {
+    bytes: number;
+    capBytes: number;
+} | undefined): {
+    ledger?: {
+        bytes: number;
+        capBytes: number;
+    };
+};
+/**
+ * Every health field that is present only when it means something.
+ *
+ * One place answers "which optional facts belong on the health block", so a session does not have
+ * to know the rule for each. A healthy session gets an empty object back and its health block
+ * carries only the fields that are always true.
+ */
+export declare function healthNotices(events: readonly ReticleEvent[], elapsed: number, ledger: {
+    bytes: number;
+    capBytes: number;
+} | undefined): {
+    pendingNavigationMs?: number;
+    ledger?: {
+        bytes: number;
+        capBytes: number;
+    };
+};
 export {};

package/dist/portal/session/session-health.js

@@ -1,4 +1,4 @@
-import { BrowserBrand, EventType, BUFFER_EVICTION_WARNING, THROTTLED_STARVED_NOTE, THROTTLED_WARNING, } from '@reticlehq/core';
+import { BrowserBrand, EventType, BUFFER_EVICTION_WARNING, THROTTLED_STARVED_NOTE, SESSION_HEALTH, THROTTLED_WARNING, } from '@reticlehq/core';
 /**
  * How long a request may be in flight before it is worth reporting on session health.
  *
@@ -29,7 +29,8 @@ export const PENDING_NAVIGATION_NOTICE_MS = 10_000;
  */
 const SKEW_VERDICT_WARNING = 'version skew: `dispatched` and `settled` on this session mean the event was sent, NOT that the ' +
     'app acted on it — a skewed pair drops actions silently. Re-read the control (aria-checked, ' +
-    'data-state, its text) before trusting any verdict from this session, and converge the versions:';
+    'data-state, its text) before trusting any verdict from this session, and converge the versions ' +
+    '(see session.versionSkew).';
 /**
  * The age of the oldest request that STARTED and never completed, or undefined when there is none
  * worth reporting.
@@ -68,6 +69,16 @@ export function bufferEnvelope(session) {
         return {};
     return { buffer: { held: total, dropped, note: BUFFER_EVICTION_WARNING } };
 }
+/**
+ * The session registered under `session.id` NOW, for describing a tab after a call that may have
+ * replaced its document. A reload or full navigation registers a new Session under the same id, and
+ * the object a handler resolved first is the page that unloaded; it reported itself hidden on the way
+ * out, so its health said "throttled" about a tab that was fine. Optional-called because test doubles
+ * are partial registries.
+ */
+export function currentOf(registry, session) {
+    return registry.get?.(session.id) ?? session;
+}
 /**
  * Build the health envelope for a tool result. When the session is **nominal** (focused, not
  * throttled, no escape-hatch recommendation) the block is OMITTED entirely — a healthy session
@@ -90,7 +101,7 @@ export function healthEnvelope(session) {
     // a skewed link makes the ACTION unreliable, and there is no point warning about the quality of an
     // observation of something that may never have happened.
     if (health.versionSkew !== undefined) {
-        return { session: health, warning: `${SKEW_VERDICT_WARNING} ${health.versionSkew}` };
+        return { session: health, warning: SKEW_VERDICT_WARNING };
     }
     return health.throttled ? { session: health, warning: THROTTLED_WARNING } : { session: health };
 }
@@ -152,3 +163,32 @@ export function readHealthEvent(data) {
         brand: Object.values(BrowserBrand).find((known) => known === data['brand']),
     };
 }
+/**
+ * The ledger block for the health payload, or nothing when it is not worth saying.
+ *
+ * Absent below `LEDGER_NOTICE_FRACTION` of the cap, and absent when the size has not been measured
+ * yet -- a reader must be able to tell "not measured" from "empty", and a zero reported before the
+ * first append would be a claim rather than a reading.
+ */
+export function ledgerNotice(ledger) {
+    if (ledger === undefined || 0 >= ledger.capBytes)
+        return {};
+    const fraction = ledger.bytes / ledger.capBytes;
+    return fraction < SESSION_HEALTH.LEDGER_NOTICE_FRACTION ? {} : { ledger };
+}
+/**
+ * Every health field that is present only when it means something.
+ *
+ * One place answers "which optional facts belong on the health block", so a session does not have
+ * to know the rule for each. A healthy session gets an empty object back and its health block
+ * carries only the fields that are always true.
+ */
+export function healthNotices(events, elapsed, ledger) {
+    // From event t=0, not a cursor: a wedge that began before the current action is exactly the case
+    // a per-window reading cannot see, and is the one both reporters hit.
+    const stuck = pendingNavigationMs(events, elapsed);
+    return {
+        ...(stuck === undefined ? {} : { pendingNavigationMs: stuck }),
+        ...ledgerNotice(ledger),
+    };
+}

package/dist/portal/session/session-info.d.ts

@@ -45,6 +45,12 @@ export interface SessionInfo {
      * A tab that dropped for four seconds and came back is indistinguishable from one that never left
      * (#117), and that difference decides whether a verdict over the window can be trusted. Attached
      * by `SessionManager.list()`, which is the layer that sees every connect and disconnect.
+     *
+     * Scoped to the SDK-to-daemon LINK, and the names do not say so on their own. A zombie tab whose
+     * dev server had died reported `outages: 0` and `connectedSinceMs: 11min`, and both were correct:
+     * the page's socket was still attached to the daemon. Read as app health, they said the app was
+     * up while nothing was listening on the port (#938). The describe() on the `reticle_sessions`
+     * output schema carries that caveat, because that is where an agent reads it.
      */
     attachment?: {
         connectedSinceMs: number;

package/dist/portal/session/session-manager.d.ts

@@ -14,6 +14,17 @@ interface ResolveScope {
 }
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export declare function originOf(url: string | undefined): string | undefined;
+/** What a refused hello said about itself: the page it was on and the project it claimed. */
+export interface RefusedPage {
+    readonly url?: string;
+    readonly projectId?: string;
+}
+/** One bridge-initiated close, with the page that was turned away when the hello named one. */
+export interface ClosureRecord {
+    readonly at: number;
+    readonly reason: string;
+    readonly page?: RefusedPage;
+}
 export declare class SessionManager {
     #private;
     /** Set the active project's default resolve scope (called once at daemon wiring). */
@@ -22,6 +33,15 @@ export declare class SessionManager {
     add(session: Session): Session | undefined;
     remove(session: Session): boolean;
     get(sessionId: string): Session | undefined;
+    /**
+     * Did this id belong to a session that has since disconnected?
+     *
+     * `resolve` answers a departed id with its live SUCCESSOR, which is what keeps a reload working
+     * for everything that observes. A caller that is about to do something DESTRUCTIVE needs the
+     * other answer: whether the thing it named is still there. Ending a session it did not name is
+     * not a recoverable mistake (#983).
+     */
+    departed(sessionId: string): SessionIdentity | undefined;
     list(): SessionInfo[];
     /** Continuity for one session — "has this been attached the whole time I am reasoning about?" */
     attachmentOf(sessionId: string): ReturnType<AttachmentHistory['of']>;
@@ -48,13 +68,16 @@ export declare class SessionManager {
     setNoSessionNextAction(next: (() => NoSessionNextAction | undefined) | undefined): void;
     noSessionNextAction(): NoSessionNextAction | undefined;
     everConnected(): boolean;
-    /** Record a bridge-initiated close so `resolve` can explain a session that vanished. */
-    noteClosure(reason: string, at: number): void;
+    /**
+     * Record a bridge-initiated close so `resolve` can explain a session that vanished.
+     *
+     * `page` is what the refused hello said about itself, when it said anything. A refusal is the one
+     * piece of positive evidence the no-session diagnosis has, and "a page was refused" without WHICH
+     * page leaves the reader unable to tell their app from another project's tab on the same port.
+     */
+    noteClosure(reason: string, at: number, page?: RefusedPage): void;
     /** The most recent bridge-initiated close, if any. */
-    lastClosure(): {
-        at: number;
-        reason: string;
-    } | undefined;
+    lastClosure(): ClosureRecord | undefined;
     connectedSinceLastClosure(): boolean;
     /**
      * The id of the session that most recently went away, if any.