@reticlehq/server 2.13.0 → 2.14.0

package/dist/session/fake-session.d.ts

@@ -0,0 +1,37 @@
+/**
+ * One complete, inert `Session` for tests that only care about two or three of its methods.
+ *
+ * Test-only. Every consumer of `Session` used to hand-roll a `Partial<Session>` and cast it through
+ * `as Session`, and the cast is the problem: it silences the type system, so a method added to
+ * `Session` breaks nothing at compile time and then throws at runtime inside files that have
+ * nothing to do with the change. That has now happened four times -- `occludedBy` (#227),
+ * `bufferHealth` (#228), the case recorded at the top of `assert-contradiction-plumbing.test.ts`,
+ * and `lostSince`, which needed the identical one-line stub added to seven files (#726).
+ *
+ * This returns a REAL `Session`, built with an inert socket and a frozen clock, so a new method
+ * arrives with a working default instead of `undefined`. `Session` holds `#private` fields, so a
+ * structural stub cannot be one -- constructing the real thing is what makes the guarantee hold.
+ *
+ * Overrides are applied as own properties, shadowing the prototype method for that instance. Pass
+ * only the behaviour a test actually asserts on; leave the rest to the defaults.
+ */
+import { type HelloMessage } from '@reticlehq/core';
+import { Session } from './session.js';
+/**
+ * The handshake a fake session reports.
+ *
+ * `sessionId: 'demo'` matches what the hand-rolled stubs used, so tests asserting on the id in a
+ * message keep passing without an override.
+ */
+export declare function fakeHello(overrides?: Partial<HelloMessage>): HelloMessage;
+/**
+ * A real `Session` with inert defaults, plus whatever this test needs it to do differently.
+ *
+ * @param overrides Written onto the instance after construction, shadowing the real member for
+ *   this session only. `runtime`, `engine`, `brand` and `actionCount` are getter-only accessors on
+ *   the prototype -- a plain assignment to one throws -- so those are redefined as instance values
+ *   instead. Overriding them is what a test wants: the real ones are fed by `applyHealth` and the
+ *   journal, which a fake session has neither of.
+ * @param hello Handshake fields, when a test cares about the id, url or redact keys.
+ */
+export declare function createFakeSession(overrides?: Partial<Session>, hello?: Partial<HelloMessage>): Session;

package/dist/session/fake-session.js

@@ -0,0 +1,81 @@
+/**
+ * One complete, inert `Session` for tests that only care about two or three of its methods.
+ *
+ * Test-only. Every consumer of `Session` used to hand-roll a `Partial<Session>` and cast it through
+ * `as Session`, and the cast is the problem: it silences the type system, so a method added to
+ * `Session` breaks nothing at compile time and then throws at runtime inside files that have
+ * nothing to do with the change. That has now happened four times -- `occludedBy` (#227),
+ * `bufferHealth` (#228), the case recorded at the top of `assert-contradiction-plumbing.test.ts`,
+ * and `lostSince`, which needed the identical one-line stub added to seven files (#726).
+ *
+ * This returns a REAL `Session`, built with an inert socket and a frozen clock, so a new method
+ * arrives with a working default instead of `undefined`. `Session` holds `#private` fields, so a
+ * structural stub cannot be one -- constructing the real thing is what makes the guarantee hold.
+ *
+ * Overrides are applied as own properties, shadowing the prototype method for that instance. Pass
+ * only the behaviour a test actually asserts on; leave the rest to the defaults.
+ */
+import { MessageKind, RETICLE_PROTOCOL_VERSION } from '@reticlehq/core';
+import { Session } from './session.js';
+/** Accepts and discards. A fake session is never expected to reach a peer. */
+const INERT_SOCKET = {
+    send: () => undefined,
+    close: () => undefined,
+};
+/** Frozen at 0, so `elapsed()`, `lastSeenMs()` and `agentIdleMs()` are all deterministic zeroes. */
+const FROZEN_CLOCK = () => 0;
+/**
+ * The handshake a fake session reports.
+ *
+ * `sessionId: 'demo'` matches what the hand-rolled stubs used, so tests asserting on the id in a
+ * message keep passing without an override.
+ */
+export function fakeHello(overrides = {}) {
+    return {
+        kind: MessageKind.HELLO,
+        protocolVersion: RETICLE_PROTOCOL_VERSION,
+        sessionId: 'demo',
+        url: 'http://localhost/',
+        title: 'Demo',
+        adapters: [],
+        ...overrides,
+    };
+}
+/** Whether `key` resolves to a getter somewhere on the prototype chain rather than a plain slot. */
+function isAccessor(target, key) {
+    let proto = target;
+    while (null !== proto) {
+        const descriptor = Object.getOwnPropertyDescriptor(proto, key);
+        if (undefined !== descriptor)
+            return undefined !== descriptor.get;
+        proto = Object.getPrototypeOf(proto);
+    }
+    return false;
+}
+/**
+ * A real `Session` with inert defaults, plus whatever this test needs it to do differently.
+ *
+ * @param overrides Written onto the instance after construction, shadowing the real member for
+ *   this session only. `runtime`, `engine`, `brand` and `actionCount` are getter-only accessors on
+ *   the prototype -- a plain assignment to one throws -- so those are redefined as instance values
+ *   instead. Overriding them is what a test wants: the real ones are fed by `applyHealth` and the
+ *   journal, which a fake session has neither of.
+ * @param hello Handshake fields, when a test cares about the id, url or redact keys.
+ */
+export function createFakeSession(overrides = {}, hello = {}) {
+    const session = new Session(fakeHello(hello), INERT_SOCKET, FROZEN_CLOCK);
+    for (const [key, value] of Object.entries(overrides)) {
+        if (isAccessor(session, key)) {
+            Object.defineProperty(session, key, {
+                value,
+                configurable: true,
+                enumerable: true,
+                writable: true,
+            });
+        }
+        else {
+            session[key] = value;
+        }
+    }
+    return session;
+}

package/dist/session/lease-visibility.d.ts

@@ -15,7 +15,7 @@
  * message to tabs that are ALREADY connected, not a new capability.
  */
 /** The minimum a session has to expose to be a candidate watcher. Structural, so tests need no SDK. */
-export interface WatcherCandidate {
+interface WatcherCandidate {
     id: string;
     projectId: string | undefined;
 }
@@ -65,3 +65,4 @@ export declare function shouldGreetWithLeaseNotice(session: WatcherCandidate, le
  * Pure: no IO, no clock, no session objects. The caller does the posting.
  */
 export declare function watchersToNotify(sessions: readonly WatcherCandidate[], leasedSessionIds: readonly string[], projectId: string | undefined): string[];
+export {};

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

@@ -157,6 +157,12 @@ export const LIVE_CONTROL_TOOLS = [
             // said nothing; the second means an agent is waiting on a channel that does not exist.
             return Promise.resolve(noteEmptyRead({ messages }, 'messages', {
                 noun: 'messages from the human since the last poll',
+                // The HUD no longer carries a text input — two boxes on one screen, and nothing said which
+                // was which. Nothing in the shipped product produces one of these today, so an empty queue
+                // here is structural rather than a quiet human, and a caller polling it deserves to know
+                // that rather than infer silence.
+                caveat: 'the HUD has no message box, so nothing currently sends on this channel — an empty ' +
+                    'queue here is not evidence about what the human thinks',
             }));
         },
     },

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

@@ -18,7 +18,7 @@
  * Pure: everything it needs is passed in, so the probe that discovers listening ports stays out of
  * the hot resolve() path and this stays unit-testable.
  */
-import { NoSessionReason } from '@reticlehq/core';
+import { NoSessionReason } from '@reticlehq/core/telemetry';
 import { type LeaseBrowserState } from './lease-availability.js';
 export interface NoSessionFacts {
     /** Whether ANY session has connected to this daemon since it booted. */
@@ -128,6 +128,15 @@ export interface NoSessionFacts {
      * which is the common case and must not gain a paragraph.
      */
     siblingListeners?: readonly number[];
+    /**
+     * The URL of the session that most recently disappeared, when the tombstone still holds it.
+     *
+     * A route that 500s tears the page down and the SDK never reconnects. `everConnected` already
+     * knew a tab HAD been here; without this the diagnosis could not say WHERE, so a server error
+     * and a closed tab read as the same empty list (#808). Absent when nothing was ever connected,
+     * or the ring has forgotten — inventing a URL is worse than the silence this exists to end.
+     */
+    lastKnownUrl?: string;
 }
 /**
  * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session
@@ -135,6 +144,13 @@ export interface NoSessionFacts {
  * generic one that contradicts it.
  */
 export declare const SELF_RECOVERING_MARKER = "Then call reticle_sessions again \u2014 it will appear within a second of the page loading.";
+/**
+ * The last URL a connected session was on when it disappeared without a successor HELLO.
+ *
+ * Shared with the observation-lost verdict so the two surfaces cannot drift into naming different
+ * routes for the same teardown (#808).
+ */
+export declare function pageTornDownWhileOn(url: string): string;
 /**
  * The diagnosis, and the CODE for the branch that produced it.
  *

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

@@ -18,7 +18,7 @@
  * Pure: everything it needs is passed in, so the probe that discovers listening ports stays out of
  * the hot resolve() path and this stays unit-testable.
  */
-import { NoSessionReason } from '@reticlehq/core';
+import { NoSessionReason } from '@reticlehq/core/telemetry';
 import { leaseCaveat } from './lease-availability.js';
 import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
 import { siblingListenerNote } from '../cli/sibling-ports.js';
@@ -75,13 +75,32 @@ function leaseAdvice(base, facts) {
 const SELF_SERVE = 'You do not have to wait for the human: reticle_lease {action:"acquire", url} opens a browser ' +
     'Reticle drives itself, and returns a sessionId you can use immediately (reach it with ' +
     'reticle_run {tool:"reticle_lease"} if it is not advertised directly; release it when you finish).';
+/** The hedge that is true for every vanished tab we did not watch leave. */
+const TAB_GONE_WHAT = 'The tab was closed, navigated away, or hard-reloaded.';
 /**
- * The ports the scan actually covers, rendered for the message.
+ * The last URL a connected session was on when it disappeared without a successor HELLO.
  *
- * Derived from DEV_SERVER_PORTS rather than re-typed: a message that lists ports the scan does not
- * check, or omits ones it does, is a new version of the same defect — a confident claim about
- * evidence that was never gathered.
+ * Shared with the observation-lost verdict so the two surfaces cannot drift into naming different
+ * routes for the same teardown (#808).
+ */
+export function pageTornDownWhileOn(url) {
+    return `the page was torn down while on ${url}`;
+}
+/**
+ * What happened to the tab, with the last URL named when we still hold it.
+ *
+ * Without the URL this is the sentence the field has always seen. With it, a route that tore the
+ * page down is no longer the same dead end as "the human closed the tab".
  */
+function tabGoneWhat(url) {
+    if (undefined === url || '' === url)
+        return TAB_GONE_WHAT;
+    const torn = pageTornDownWhileOn(url);
+    const first = torn.charAt(0);
+    if ('' === first)
+        return TAB_GONE_WHAT;
+    return `${first.toUpperCase()}${torn.slice(1)}. ${TAB_GONE_WHAT}`;
+}
 /**
  * The one cause that produces a PERFECTLY healthy everything and still never connects.
  *
@@ -138,6 +157,13 @@ const RESTARTED_LEAD = 'no browser session connected. This daemon has served non
     '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.';
+/**
+ * The ports the scan actually covers, rendered for the message.
+ *
+ * Derived from DEV_SERVER_PORTS rather than re-typed: a message that lists ports the scan does not
+ * check, or omits ones it does, is a new version of the same defect — a confident claim about
+ * evidence that was never gathered.
+ */
 const SCANNED_PORTS = [...DEV_SERVER_PORTS].join(', ');
 /**
  * How to say "open the app" to an agent that may have no `reticle` binary.
@@ -349,7 +375,7 @@ export function explainNoSession(facts) {
                 `carry on.${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. The tab was closed, navigated away, or hard-reloaded. Ask the human to reopen ' +
+            `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}`);
     }

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

@@ -51,6 +51,20 @@ interface NextActionFacts {
      * that works.
      */
     previouslyConnected?: boolean;
+    /**
+     * A page reached this daemon and was REFUSED on the pairing token.
+     *
+     * Positive evidence, and the only fact here that proves the app is both running and instrumented:
+     * nothing dials the bridge but an SDK, so a refused hello means the wiring works and the daemon
+     * would not serve it. That happens whenever an IDE registers the MCP server GLOBALLY -- the daemon
+     * starts with a cwd of `/` or `$HOME`, finds no `.reticle.json` there, and refuses every page
+     * while `doctor` run from the app directory reports the project wired (#685).
+     *
+     * Without it, `initialized: false` plus a listening port reads as "the app may carry no SDK" and
+     * the action handed back is `reticle init` -- over a config that already works, which is the one
+     * action that cannot help and can overwrite it.
+     */
+    authRefused?: boolean;
 }
 export declare function nextActionFor(facts: NextActionFacts): NoSessionNextAction;
 /** The same action as one sentence, for the prose message the human reads. */

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

@@ -103,6 +103,24 @@ export function nextActionFor(facts) {
     // a second port is the exact confusion the probe exists to prevent.
     const ports = facts.listening.join(', ');
     const only = 1 === facts.listening.length ? facts.listening[0] : undefined;
+    // A refused dial outranks the absence of a local config, for the same reason `previouslyConnected`
+    // does: it is positive evidence about the app, and `initialized` only ever answers "is there a
+    // `.reticle.json` in the ONE directory this daemon stands in". A globally-registered daemon stands
+    // in `/` or `$HOME`, so that answer is no for every project it serves -- and every page it turns
+    // away is proof that the project it turned away is wired.
+    if (!facts.initialized && true === facts.authRefused) {
+        return {
+            action: NoSessionAction.OPEN_APP,
+            ...(only === undefined ? {} : { port: only }),
+            reason: `a page dialled this daemon and was refused on the pairing token, so the app IS running ` +
+                `and instrumented (${ports} listening) — this is a SCOPE problem, not an install problem. ` +
+                'This daemon was started outside the project (an IDE that registers the MCP server ' +
+                'globally starts it in `/` or your home directory), so it has no `.reticle.json` to match ' +
+                'the page against. Do NOT run `reticle init`: the config it would write is already correct ' +
+                'somewhere else. Take a context you own instead with reticle_lease {action:"acquire", url, ' +
+                "projectId}, or restart the daemon from the app's own directory.",
+        };
+    }
     if (!facts.initialized && true !== facts.previouslyConnected) {
         return {
             action: NoSessionAction.RUN_INIT,

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

@@ -10,6 +10,8 @@
  * daemon that outlives the agent by hours has no business scanning ports it does not need.
  */
 import { probeDevServers, probeDevServerStates } from './dev-server-probe.js';
+import { homedir } from 'node:os';
+import { registeredElsewhere } from './registered-projects.js';
 import { explainNoSession } from './no-session-diagnosis.js';
 import { detectDevCommand } from './dev-command.js';
 import { nextActionFor, renderNextAction } from './no-session-next-action.js';
@@ -21,6 +23,7 @@ import { daemonsServingProjectElsewhere, splitBrainNote } from '../daemon/daemon
 import { stallUptime } from './stall-clock.js';
 import { probeDaemon } from '../mcp/mcp-proxy.js';
 import { findOccupiedSiblings } from '../cli/sibling-ports.js';
+import { WS_CLOSE_REASON } from '../bridge/bridge.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. */
@@ -81,15 +84,32 @@ export function startNoSessionWatch(options) {
             return { initialized };
         const discovery = discoverProjectConfigs(directory);
         const elsewhere = discovery.found.filter((config) => config.directory !== directory);
-        return 0 === elsewhere.length
-            ? { initialized, searchedDirectories: discovery.searched }
-            : {
+        if (elsewhere.length > 0) {
+            return {
                 initialized,
                 configsElsewhere: elsewhere.map((config) => ({
                     directory: config.directory,
                     ...(config.projectId === undefined ? {} : { projectId: config.projectId }),
                 })),
             };
+        }
+        // The walk found nothing — which is the honest answer from a daemon standing at `/` or `$HOME`,
+        // where several IDEs start a GLOBALLY registered MCP server. There is nothing above `/` and no
+        // repo root at either, so the walk cannot reach a project it has nonetheless paired with before.
+        // The registry can. See registeredElsewhere: "I am standing in the wrong place" and "you never
+        // installed this" are opposite diagnoses with opposite fixes, and without this we gave the
+        // second one — six times, on projects that were already correctly instrumented.
+        const registered = registeredElsewhere(homedir(), directory);
+        if (registered.length > 0) {
+            return {
+                initialized,
+                configsElsewhere: registered.map((project) => ({
+                    directory: project.directory,
+                    ...(project.projectId === undefined ? {} : { projectId: project.projectId }),
+                })),
+            };
+        }
+        return { initialized, searchedDirectories: discovery.searched };
     };
     // Read at boot: the daemon's own identity does not change under it, and this is the key the
     // durable bit is stored under.
@@ -185,6 +205,19 @@ export function startNoSessionWatch(options) {
     refresh();
     const timer = setInterval(refresh, REFRESH_MS);
     timer.unref();
+    /**
+     * Did the most recent bridge-initiated close refuse a page on its token?
+     *
+     * The bridge records it (`noteClosure(WS_CLOSE_REASON.AUTH_FAILED)`) and nothing read it as a
+     * DIAGNOSIS. It is the one fact that proves an app is running and instrumented: only an SDK dials
+     * the bridge, so a refused hello means the wiring works and this daemon would not serve it.
+     *
+     * Called optionally because this watch is constructed against a structural slice of the manager,
+     * and several callers pass a double that predates `lastClosure`. A manager that cannot answer has
+     * recorded no refusal, which falls through to the behaviour that was there before -- the safe
+     * direction for a fact whose only job is to SUPPRESS an `init` suggestion.
+     */
+    const lastCloseWasAuthFailure = () => options.sessions.lastClosure?.()?.reason === WS_CLOSE_REASON.AUTH_FAILED;
     const nextAction = (scope) => {
         const split = splitBrain();
         return nextActionFor({
@@ -192,6 +225,9 @@ export function startNoSessionWatch(options) {
             initialized: scope.initialized,
             ...(scope.configsElsewhere === undefined ? {} : { configsElsewhere: scope.configsElsewhere }),
             previouslyConnected: connectedBefore(),
+            // 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(),
             ...(split === undefined ? {} : { splitBrain: split }),
             listening,
             // Read when asked, like everything else here: a `package.json` can gain a dev script, and a
@@ -236,6 +272,13 @@ export function startNoSessionWatch(options) {
                 const departed = options.sessions.lastDeparted();
                 return departed === undefined ? false : (options.wasReapedLease?.(departed) ?? false);
             })(),
+            // The URL of the session that went away, when the tombstone still holds it. Optional: a
+            // stub SessionManager in tests has no lastKnown, and a daemon that never saw a session
+            // has none to name.
+            ...(() => {
+                const known = options.sessions.lastKnown?.();
+                return undefined === known ? {} : { lastKnownUrl: known.url };
+            })(),
             // 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/session/registered-projects.d.ts

@@ -0,0 +1,54 @@
+/** One project this machine has paired before, in the shape the no-session facts already carry. */
+export interface RegisteredProject {
+    directory: string;
+    projectId?: string;
+}
+/**
+ * Projects this machine has paired before, read from `~/.reticle/projects.json`.
+ *
+ * The no-session diagnosis learns where projects are by WALKING: up from the daemon's cwd, then
+ * across the declared workspaces of whatever repo root it lands in. That walk is the right first
+ * answer and it has one blind spot, which happens to be the most reported install problem we have.
+ *
+ * Several IDEs register the MCP server GLOBALLY, so the daemon starts with a cwd of `/` or `$HOME`.
+ * From there the walk finds nothing — there is nothing above `/`, and no repo root at either — so
+ * `configsElsewhere` comes back empty and the diagnosis falls through to the branches that reason
+ * from "no config anywhere", whose advice is `reticle init`. Reported six separate times, on a
+ * project that was already correctly instrumented; one reporter burned a turn re-running `init` over
+ * a working config while `doctor`, run from the app directory, said `project ✓ wired here`.
+ *
+ * The registry is the evidence the walk cannot reach: every project that has ever paired with this
+ * machine is in it, with its directory. A daemon that cannot SEE a project can still KNOW of it, and
+ * "I am standing in the wrong place" is a completely different diagnosis from "you never installed
+ * this" — opposite fixes, and we were giving the second one.
+ *
+ * Read fresh rather than cached: a project can pair for the first time while this daemon is up, and
+ * a stale empty read would keep the wrong diagnosis for the life of the process. Fails soft to
+ * empty, because a diagnosis is the last thing that should throw.
+ */
+export declare function registeredProjects(home: string): RegisteredProject[];
+/**
+ * Is this daemon standing somewhere a project could never live?
+ *
+ * THE NARROWING THAT MAKES THIS SAFE, and it is not optional. An empty config walk has two causes:
+ * the daemon is parked outside every project (the global-registration case this fixes), or it is
+ * standing in a real directory that genuinely has not been wired yet (a new project, where
+ * `reticle init` is exactly the right advice). Both look identical from the walk.
+ *
+ * Consulting the registry for BOTH would break the second: any developer machine has registered
+ * projects, so a brand-new unwired project would be told "your config is elsewhere, restart the
+ * daemon there" instead of "run init". That trades the reported false negative for an unreported
+ * one, on the more common path — a bad trade, and caught here by two existing tests going red.
+ *
+ * The filesystem root and the user's home directory are the discriminator. Neither is ever an app
+ * directory, and both are exactly where an IDE's global MCP registration starts a daemon. Anywhere
+ * else, an empty walk still means what it always meant.
+ */
+export declare function isUnscopedRoot(directory: string, home: string): boolean;
+/**
+ * The registered projects that are NOT the directory this daemon is standing in.
+ *
+ * Same rule the config walk applies: a project at the daemon's own cwd is not "elsewhere", and
+ * reporting it as such would tell a correctly-scoped daemon to go and look somewhere else.
+ */
+export declare function registeredElsewhere(home: string, directory: string): RegisteredProject[];

package/dist/session/registered-projects.js

@@ -0,0 +1,73 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, parse, resolve } from 'node:path';
+import { PROJECT_REGISTRY_FILE, ReticleDir, parseProjectRegistry, projectCandidates, } from '@reticlehq/core';
+/**
+ * Projects this machine has paired before, read from `~/.reticle/projects.json`.
+ *
+ * The no-session diagnosis learns where projects are by WALKING: up from the daemon's cwd, then
+ * across the declared workspaces of whatever repo root it lands in. That walk is the right first
+ * answer and it has one blind spot, which happens to be the most reported install problem we have.
+ *
+ * Several IDEs register the MCP server GLOBALLY, so the daemon starts with a cwd of `/` or `$HOME`.
+ * From there the walk finds nothing — there is nothing above `/`, and no repo root at either — so
+ * `configsElsewhere` comes back empty and the diagnosis falls through to the branches that reason
+ * from "no config anywhere", whose advice is `reticle init`. Reported six separate times, on a
+ * project that was already correctly instrumented; one reporter burned a turn re-running `init` over
+ * a working config while `doctor`, run from the app directory, said `project ✓ wired here`.
+ *
+ * The registry is the evidence the walk cannot reach: every project that has ever paired with this
+ * machine is in it, with its directory. A daemon that cannot SEE a project can still KNOW of it, and
+ * "I am standing in the wrong place" is a completely different diagnosis from "you never installed
+ * this" — opposite fixes, and we were giving the second one.
+ *
+ * Read fresh rather than cached: a project can pair for the first time while this daemon is up, and
+ * a stale empty read would keep the wrong diagnosis for the life of the process. Fails soft to
+ * empty, because a diagnosis is the last thing that should throw.
+ */
+export function registeredProjects(home) {
+    try {
+        const path = join(home, ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
+        if (!existsSync(path))
+            return [];
+        const registry = parseProjectRegistry(JSON.parse(readFileSync(path, 'utf8')));
+        return projectCandidates(registry).map((candidate) => ({
+            directory: candidate.directory,
+            projectId: candidate.projectId,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Is this daemon standing somewhere a project could never live?
+ *
+ * THE NARROWING THAT MAKES THIS SAFE, and it is not optional. An empty config walk has two causes:
+ * the daemon is parked outside every project (the global-registration case this fixes), or it is
+ * standing in a real directory that genuinely has not been wired yet (a new project, where
+ * `reticle init` is exactly the right advice). Both look identical from the walk.
+ *
+ * Consulting the registry for BOTH would break the second: any developer machine has registered
+ * projects, so a brand-new unwired project would be told "your config is elsewhere, restart the
+ * daemon there" instead of "run init". That trades the reported false negative for an unreported
+ * one, on the more common path — a bad trade, and caught here by two existing tests going red.
+ *
+ * The filesystem root and the user's home directory are the discriminator. Neither is ever an app
+ * directory, and both are exactly where an IDE's global MCP registration starts a daemon. Anywhere
+ * else, an empty walk still means what it always meant.
+ */
+export function isUnscopedRoot(directory, home) {
+    const at = resolve(directory);
+    return at === resolve(home) || at === parse(at).root;
+}
+/**
+ * The registered projects that are NOT the directory this daemon is standing in.
+ *
+ * Same rule the config walk applies: a project at the daemon's own cwd is not "elsewhere", and
+ * reporting it as such would tell a correctly-scoped daemon to go and look somewhere else.
+ */
+export function registeredElsewhere(home, directory) {
+    if (!isUnscopedRoot(directory, home))
+        return [];
+    return registeredProjects(home).filter((project) => project.directory !== directory);
+}

package/dist/session/review-store.d.ts

@@ -24,7 +24,7 @@ export interface ReviewMark {
 /** Tests only — assertions on `m1` must not depend on which test ran first. */
 export declare function resetMarkIdsForTest(): void;
 /** What `resolve` actually did, including WHICH mark — so a caller can verify it hit the right one. */
-export interface ResolveOutcome {
+interface ResolveOutcome {
     resolved: boolean;
     id: string;
     /** The retired mark's note. Absent when nothing was resolved. */
@@ -56,3 +56,4 @@ export declare class ReviewStore {
      */
     resolveDetail(id: string): ResolveOutcome;
 }
+export {};

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

@@ -1,4 +1,4 @@
-import { BrowserBrand } from '@reticlehq/core';
+import { BrowserBrand, type ReticleEvent } from '@reticlehq/core';
 import type { Session } from './session.js';
 /**
  * The health block spliced onto act/assert results. Defined here rather than in session.ts: this is
@@ -10,7 +10,58 @@ export interface SessionHealth {
     focused: boolean;
     /** present only when hidden/throttled — points at the `reticle drive` escape hatch. */
     recommendation?: string;
+    /**
+     * How long the OLDEST unanswered request has been in flight, when that is long enough to matter.
+     *
+     * Present only past `PENDING_NAVIGATION_NOTICE_MS`, so a healthy session costs nothing. Both
+     * reporters on the hung-server issue said this alone would have been enough for them: one sat on
+     * an RSC fetch stuck pending for 170+ seconds across many calls, the other on a dev server that
+     * accepted connections and never sent a body. Reticle held the evidence both times and the truth
+     * was eventually established with `curl`.
+     */
+    pendingNavigationMs?: number;
+    /**
+     * Present only when the page's SDK version differs from the daemon's — see version-skew.ts.
+     *
+     * On the HEALTH block, not only on `reticle_sessions`, because skew causes SILENT action failures
+     * and the fields it contradicts ride on the act result. Reported from the field: `act_and_wait`
+     * returning `dispatched: true, settled: true, domMutatedWithin: 12-40ms` while React state never
+     * changed, across eight attempts and three interaction strategies. The banner existed the whole
+     * time — on `reticle_sessions` and `reticle_lease`, which is not the surface an agent reads on
+     * every call.
+     */
+    versionSkew?: string;
 }
+/**
+ * How long a request may be in flight before it is worth reporting on session health.
+ *
+ * A drive always has requests in the air, so a low bar puts a scary number on every healthy session
+ * and trains agents to ignore the field — the same way a guard that fires on routine controls trains
+ * them to pass `confirmDangerous` reflexively.
+ *
+ * 10s, and it is a HEURISTIC with no clean separation available: "a slow endpoint" and "a server
+ * that will never answer" are the same observation until one of them finishes. The number is chosen
+ * to sit between the two things actually measured, not derived from anything.
+ *
+ * Below it: this repo's own battery runs its API with `REFLECT_MS=6000` on purpose, and at the 5s
+ * this first shipped with, a healthy app with one slow route was permanently non-nominal and carried
+ * a scary number on every result.
+ *
+ * Above it: both reported wedges — 10.4s on one, 170s+ on the other. 10.4s clears this by 400ms,
+ * which is thin, and an app with an 8-second endpoint will not be warned about a wedge until 10s.
+ * That is the trade: an over-firing field gets ignored, and a field nobody reads catches nothing.
+ */
+export declare const PENDING_NAVIGATION_NOTICE_MS = 10000;
+/**
+ * The age of the oldest request that STARTED and never completed, or undefined when there is none
+ * worth reporting.
+ *
+ * Matched on request id, the way `detectHungRequests` and the route oracle's `unansweredIn` do: a
+ * NET_PENDING with no NET_REQUEST carrying the same id. Three readings of one fact is two too many,
+ * but they read different windows — this one is the whole session, which is the point: a wedge that
+ * began before the current action is exactly the case a per-window reading cannot see.
+ */
+export declare function pendingNavigationMs(events: readonly ReticleEvent[], nowMs: number): number | undefined;
 /** The evidence-completeness block spliced onto observe/network/console results. */
 interface BufferEnvelope {
     buffer?: {
@@ -49,10 +100,20 @@ export declare function refuseIfThrottled(session: Session, refuse: unknown): vo
  * Suffix the starvation note onto a FAILED predicate verdict when the tab is throttled. A pass is
  * returned untouched — starvation is context for a failure, not a reason to doubt a hold. Pure and
  * generic over the verdict shape so assert/wait_for/act_and_wait share one rule.
+ *
+ * The sentence FOLLOWS the field, and does not decide for itself. `annotateThrottledMiss`
+ * (predicate.ts) owns the question of whether this failure was reached by not having seen
+ * something, which is the only reading a starved tab casts doubt on; it stamps
+ * `THROTTLED_STARVED_NOTE` when it was. Deciding again here got two answers to one question:
+ * an `absent: true` assertion that MATCHED 13 elements was graded honestly in the field an agent
+ * gates on, and told in prose that the tab may never have rendered. It also doubled up on a failure
+ * that already carried a more specific reason (an unreadable locator, a superseded window), where
+ * the concrete diagnosis is the one that should lead.
  */
 export declare function annotateStarvedFailure<V extends {
     pass?: boolean;
     failureReason?: string;
+    inconclusive?: string;
 }>(session: Session, verdict: V): V;
 /** The page's own visibility/runtime report, narrowed out of an untrusted PAGE_HEALTH payload. */
 interface HealthReport {