@reticlehq/server 2.6.0 → 2.8.0

package/dist/pool/playwright-launcher.js

@@ -8,6 +8,7 @@
 import { BrowserLaunchKind } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../telemetry/connect-failure.js';
+import { chromiumInstallCommand, bundledPlaywrightVersion } from '../cli/chromium-hint.js';
 /**
  * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
  * the rest of this file needs a real Chromium.
@@ -48,8 +49,15 @@ function wrapBrowser(browser) {
         onDisconnected: (handler) => browser.on('disconnected', handler),
     };
 }
-/** The fix for the most common first-run failure: Chromium isn't installed for Playwright. */
-const CHROMIUM_MISSING_HINT = 'Chromium is not installed for Playwright. Run: npx playwright install chromium';
+/**
+ * The fix for the most common first-run failure: Chromium isn't installed for Playwright.
+ *
+ * Pinned to the playwright this process bundles. Unpinned, `npx` fetches the latest playwright and
+ * installs ITS browser revision — a build this launcher will never look at — so the user follows the
+ * advice, it succeeds, and the next launch fails identically. Shares one builder with `doctor` so the
+ * two cannot suggest different commands for the same missing browser.
+ */
+const CHROMIUM_MISSING_HINT = `Chromium is not installed for Playwright. Run: ${chromiumInstallCommand(bundledPlaywrightVersion())}`;
 /** A Launcher that boots a real headless Chromium and adapts it to the pool's interface. */
 export function playwrightLauncher(opts = {}) {
     const headless = opts.headless ?? true;

package/dist/project/learned-routes.d.ts

@@ -0,0 +1,24 @@
+import { type ReticleEvent } from '@reticlehq/core';
+interface RouteLearningSession {
+    url: string;
+    onEvent(handler: (event: ReticleEvent) => void): () => void;
+}
+interface RouteLearningBridge {
+    sessions: {
+        all(): RouteLearningSession[];
+    };
+    attachSessionReady(handler: (session: RouteLearningSession) => void): void;
+}
+interface RouteLearningStore {
+    recordRoutes(routes: readonly string[]): Promise<void>;
+}
+/** Coalesce navigation bursts so one crawl does not lock and rewrite project.json per event. */
+export declare const ROUTE_PERSIST_DEBOUNCE_MS = 50;
+/** Convert a validated route-change payload into a bounded route identity. */
+export declare function routeFromEvent(event: ReticleEvent): string | undefined;
+/** Read the same route shape from a session's absolute URL. */
+export declare function routeFromUrl(value: string): string | undefined;
+export declare function routesFromEvents(events: readonly ReticleEvent[]): string[];
+/** Persist initial and subsequent routes for existing and future browser sessions. */
+export declare function attachRouteLearning(bridge: RouteLearningBridge, project: RouteLearningStore): void;
+export {};

package/dist/project/learned-routes.js

@@ -0,0 +1,63 @@
+import { EventType } from '@reticlehq/core';
+/** Coalesce navigation bursts so one crawl does not lock and rewrite project.json per event. */
+export const ROUTE_PERSIST_DEBOUNCE_MS = 50;
+/** Convert a validated route-change payload into a bounded route identity. */
+export function routeFromEvent(event) {
+    if (event.type !== EventType.ROUTE_CHANGE)
+        return undefined;
+    const pathname = event.data['pathname'];
+    if ('string' !== typeof pathname || 0 === pathname.length)
+        return undefined;
+    return pathname;
+}
+/** Read the same route shape from a session's absolute URL. */
+export function routeFromUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.pathname;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function routesFromEvents(events) {
+    return events.flatMap((event) => {
+        const route = routeFromEvent(event);
+        return route === undefined ? [] : [route];
+    });
+}
+/** Persist initial and subsequent routes for existing and future browser sessions. */
+export function attachRouteLearning(bridge, project) {
+    const attached = new WeakSet();
+    const pending = new Set();
+    let flushTimer;
+    const flush = () => {
+        flushTimer = undefined;
+        const routes = [...pending];
+        pending.clear();
+        if (routes.length > 0)
+            void project.recordRoutes(routes).catch(() => undefined);
+    };
+    const queue = (route) => {
+        pending.add(route);
+        if (flushTimer !== undefined)
+            clearTimeout(flushTimer);
+        flushTimer = setTimeout(flush, ROUTE_PERSIST_DEBOUNCE_MS);
+    };
+    const attach = (session) => {
+        if (attached.has(session))
+            return;
+        attached.add(session);
+        const initial = routeFromUrl(session.url);
+        if (initial !== undefined)
+            queue(initial);
+        session.onEvent((event) => {
+            const route = routeFromEvent(event);
+            if (route !== undefined)
+                queue(route);
+        });
+    };
+    for (const session of bridge.sessions.all())
+        attach(session);
+    bridge.attachSessionReady(attach);
+}

package/dist/project/project-store.d.ts

@@ -26,6 +26,12 @@ export declare class ProjectStore {
      * (last PER_NAME of any one name, then cap to TOTAL overall) and writes byte-stably.
      */
     recordRun(record: Omit<RunRecord, 'at'>): Promise<void>;
+    /**
+     * Add discovered routes to the learned app map. Empty input is a no-op so "nothing observed"
+     * does not materialize as `learned.routes: []`; non-empty updates are serialized per file so
+     * concurrent browser sessions accumulate rather than overwriting one another.
+     */
+    recordRoutes(routes: readonly string[]): Promise<void>;
     /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
     lastRun(name: string): Promise<RunRecord | undefined>;
 }

package/dist/project/project-store.js

@@ -1,4 +1,4 @@
-import { PROJECT_FILE_VERSION, PROJECT_RUN_CAP, ProjectFileSchema, ProjectReadError, } from '@reticlehq/core';
+import { PROJECT_FILE_VERSION, PROJECT_ROUTE_CAP, PROJECT_RUN_CAP, ProjectFileSchema, ProjectReadError, } from '@reticlehq/core';
 import { reticleDirPaths } from './reticle-dir.js';
 import { withFileLock } from './file-lock.js';
 const JSON_INDENT = 2;
@@ -77,6 +77,30 @@ export class ProjectStore {
             await this.#fs.writeFile(path, this.#serialize(next));
         });
     }
+    /**
+     * Add discovered routes to the learned app map. Empty input is a no-op so "nothing observed"
+     * does not materialize as `learned.routes: []`; non-empty updates are serialized per file so
+     * concurrent browser sessions accumulate rather than overwriting one another.
+     */
+    async recordRoutes(routes) {
+        const additions = routes.filter((route) => route.length > 0);
+        if (0 === additions.length)
+            return;
+        const path = reticleDirPaths(this.#root).project;
+        await withFileLock(path, async () => {
+            const existing = await this.read();
+            const base = existing.ok ? existing.file : EMPTY_PROJECT;
+            const current = base.learned?.routes ?? [];
+            const merged = [...new Set([...current, ...additions])].slice(0, PROJECT_ROUTE_CAP);
+            if (merged.length === current.length &&
+                merged.every((route, index) => route === current[index]))
+                return;
+            const learned = { ...base.learned, routes: merged };
+            const next = { ...base, learned };
+            await this.#fs.mkdir(reticleDirPaths(this.#root).root);
+            await this.#fs.writeFile(path, this.#serialize(next));
+        });
+    }
     /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
     async lastRun(name) {
         const read = await this.read();

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

@@ -93,12 +93,37 @@ export const LIVE_CONTROL_TOOLS = [
         description: 'Drain and return any messages the human queued from the panel since the last poll. Use to ' +
             'explicitly check for human guidance without acting.',
         inputSchema: { ...sessionIdShape },
-        outputSchema: { messages: z.array(z.unknown()) },
+        outputSchema: {
+            messages: z.array(z.unknown()),
+            delivered: z
+                .array(z.unknown())
+                .optional()
+                .describe('Present ONLY when this poll found nothing new but the human HAS spoken this session: everything they said, including what was already handed to you inline on an earlier tool result. An empty `messages` never means silence.'),
+        },
         handler: (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
+            const messages = session.drainInbox();
+            if (messages.length > 0)
+                return Promise.resolve({ messages });
+            // Nothing NEW is not the same as nothing said. The inbox has two consumers — this poll and the
+            // control envelope spliced onto every tool result — and delivery is destructive, so a message
+            // handed over inline moments ago left this call reporting an empty queue with a note that read
+            // as "the human has said nothing". Reported from the field, from both ends: the agent believed
+            // it, and the person who typed the message got silence with no sign it had been seen.
+            const history = session.inboxHistory();
+            if (history.length > 0) {
+                return Promise.resolve({
+                    messages,
+                    delivered: [...history],
+                    note: `nothing NEW since your last poll — but the human has sent ` +
+                        `${String(history.length)} message(s) this session, listed in \`delivered\`. They were ` +
+                        `handed to you inline on an earlier tool result, which is why this queue is empty. An ` +
+                        `empty \`messages\` never means the human has said nothing.`,
+                });
+            }
             // An empty inbox and a panel that is not wired both return `[]`. The first means the human has
             // said nothing; the second means an agent is waiting on a channel that does not exist.
-            return Promise.resolve(noteEmptyRead({ messages: session.drainInbox() }, 'messages', {
+            return Promise.resolve(noteEmptyRead({ messages }, 'messages', {
                 noun: 'messages from the human since the last poll',
             }));
         },
@@ -126,16 +151,26 @@ export const LIVE_CONTROL_TOOLS = [
             marks: z.array(z.unknown()),
             pendingCount: z.number(),
             resolved: z.boolean().optional(),
+            resolvedNote: z
+                .string()
+                .optional()
+                .describe('The note on the mark that was actually retired. CHECK IT against the mark you meant to resolve: a bare `resolved:true` cannot tell you it closed the right one, and ids are only meaningful while the session that issued them lives.'),
         },
         handler: (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
             const resolveId = asString(args['resolve']);
             let resolved;
+            let resolvedNote;
             if (resolveId !== undefined) {
                 // Grab the note BEFORE retiring it so we can close the loop visually for the human.
                 const mark = session.allMarks().find((m) => m.id === resolveId);
                 resolved = session.resolveMark(resolveId);
                 if (resolved && mark !== undefined) {
+                    // Echoed back to the CALLER too, not only to the panel. A bare `resolved:true` is equally
+                    // consistent with "I retired the bug you fixed" and "I retired somebody else's", and an
+                    // agent hit exactly that — it closed a mark the human had recorded minutes later while
+                    // the two it had actually fixed vanished with no record.
+                    resolvedNote = mark.note;
                     // The human watching the panel sees their flagged bug get marked fixed (fire-and-forget).
                     session.pushNarration(`✓ fixed: ${mark.note}`);
                 }
@@ -148,6 +183,8 @@ export const LIVE_CONTROL_TOOLS = [
             };
             if (resolved !== undefined)
                 out.resolved = resolved;
+            if (resolvedNote !== undefined)
+                out.resolvedNote = resolvedNote;
             return Promise.resolve(out);
         },
     },

package/dist/session/live-control.d.ts

@@ -4,15 +4,6 @@ export interface InboxMessage {
     text: string;
     t: number;
 }
-/**
- * The human-in-the-loop half of a session: its lifecycle state, and the one-way inbox a person uses
- * to talk to the agent driving their browser.
- *
- * Server-owned on purpose — a paused session has to stay paused even if the page reloads, so this
- * cannot live in the tab. Split out of Session because it shares nothing with the transport, the
- * ring buffer, or the journal: it is state a HUMAN changes, on a human's timescale, while everything
- * else in Session is driven by the event stream.
- */
 export declare class LiveControl {
     #private;
     state(): SessionState;
@@ -22,6 +13,13 @@ export declare class LiveControl {
     setState(next: SessionState): void;
     /** Queue a human note. Empty/whitespace-only text is ignored so a stray enter cannot spam the agent. */
     push(text: string, t: number): void;
+    /**
+     * Everything the human has said this session, including what has already been delivered.
+     *
+     * Read-only and non-destructive by design — this is the answer to "did the human say anything
+     * while I was away", which a destructive drain can never give twice.
+     */
+    history(): readonly InboxMessage[];
     /** Return the queued notes AND clear them — delivered once, so a hint never repeats. */
     drain(): InboxMessage[];
     /** Diagnostic read of the inbox depth (does not clear). */

package/dist/session/live-control.js

@@ -8,9 +8,29 @@ import { HumanControlKind, SessionState } from '@reticlehq/core';
  * ring buffer, or the journal: it is state a HUMAN changes, on a human's timescale, while everything
  * else in Session is driven by the event stream.
  */
+/**
+ * How many delivered messages a session remembers.
+ *
+ * Enough that an agent picking up a long session can see what was said; bounded because a session
+ * can run for hours and this is a convenience, not a record.
+ */
+const HISTORY_CAP = 200;
 export class LiveControl {
     #state = SessionState.ACTIVE;
     #inbox = [];
+    /**
+     * Everything the human has said this session, delivered or not.
+     *
+     * The inbox has TWO consumers — the control envelope on every tool result, and the explicit
+     * message poll — and `drain` is destructive, so whichever ran first took the message and the other
+     * reported an empty queue. That produced a confident "no messages from the human since the last
+     * poll" about a message the human had definitely sent, with no way for the agent to tell the
+     * difference and no acknowledgement for the person who typed it.
+     *
+     * Delivered-once stays: a guidance hint that repeats every turn is noise. This only stops the
+     * delivery from being the same event as the forgetting.
+     */
+    #history = [];
     state() {
         return this.#state;
     }
@@ -29,7 +49,20 @@ export class LiveControl {
         const trimmed = text.trim();
         if (0 === trimmed.length)
             return;
-        this.#inbox.push({ text: trimmed, t });
+        const message = { text: trimmed, t };
+        this.#inbox.push(message);
+        this.#history.push(message);
+        if (this.#history.length > HISTORY_CAP)
+            this.#history.splice(0, this.#history.length - HISTORY_CAP);
+    }
+    /**
+     * Everything the human has said this session, including what has already been delivered.
+     *
+     * Read-only and non-destructive by design — this is the answer to "did the human say anything
+     * while I was away", which a destructive drain can never give twice.
+     */
+    history() {
+        return this.#history;
     }
     /** Return the queued notes AND clear them — delivered once, so a hint never repeats. */
     drain() {

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

@@ -1,10 +1,10 @@
 /**
  * Turning "no browser session connected" from a dead end into a next action.
  *
- * This is the most consequential sentence in the product. Measured over a day of telemetry: 74% of
- * sessions never call a Reticle tool, and of the ones that do, half make exactly ONE call — usually
- * `reticle_sessions` — and stop. Ten of those thirteen never touched a browser, and every recorded
- * session error is this one. The agent asks whether anything is connected, is told no, and leaves.
+ * This is the most consequential sentence in the product. Most sessions never call a Reticle tool at
+ * all, and of the ones that do, a large share make exactly ONE call — usually `reticle_sessions` —
+ * and stop. Almost none of those ever touched a browser, and this is the session error they hit. The
+ * agent asks whether anything is connected, is told no, and leaves.
  *
  * The old message asked the agent to check two things it cannot see from where it stands ("is your
  * app running with the SDK enabled?", "does it point at this port?"). The daemon can actually tell
@@ -27,6 +27,14 @@ interface NoSessionFacts {
     listening: readonly number[];
     /** The port this daemon is on — half of the mismatch the old message asked about. */
     port: number;
+    /**
+     * The directory `initialized` was decided in, named in the message when it is known.
+     *
+     * "There is no `.reticle.json`" is only ever true OF A DIRECTORY, and a reader who cannot see
+     * which one has to guess whether the claim is about their app at all — reported by someone whose
+     * app lives in `src/admin` while the daemon stands at the repo root.
+     */
+    directory?: string;
     /**
      * This daemon has reaped at least one EXPIRED pooled lease.
      *
@@ -34,6 +42,17 @@ interface NoSessionFacts {
      * evidence, not proof, and the message below is worded accordingly.
      */
     leaseExpired?: boolean;
+    /**
+     * The port `.reticle.json` configures for this project, when there is one.
+     *
+     * Half of a mismatch the daemon can settle rather than hint at: it knows the port it bound, and
+     * this is the number the app's SDK was built to dial. `doctor` already compares them and prints a
+     * precise line; the agent reading `why` was getting "check that the port matches" instead.
+     *
+     * Absent means no config, or one without a port, which is NOT a mismatch: a plugin-wired app has
+     * no `.reticle.json` at all and is working perfectly.
+     */
+    projectPort?: number;
 }
 /**
  * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session

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

@@ -1,10 +1,10 @@
 /**
  * Turning "no browser session connected" from a dead end into a next action.
  *
- * This is the most consequential sentence in the product. Measured over a day of telemetry: 74% of
- * sessions never call a Reticle tool, and of the ones that do, half make exactly ONE call — usually
- * `reticle_sessions` — and stop. Ten of those thirteen never touched a browser, and every recorded
- * session error is this one. The agent asks whether anything is connected, is told no, and leaves.
+ * This is the most consequential sentence in the product. Most sessions never call a Reticle tool at
+ * all, and of the ones that do, a large share make exactly ONE call — usually `reticle_sessions` —
+ * and stop. Almost none of those ever touched a browser, and this is the session error they hit. The
+ * agent asks whether anything is connected, is told no, and leaves.
  *
  * The old message asked the agent to check two things it cannot see from where it stands ("is your
  * app running with the SDK enabled?", "does it point at this port?"). The daemon can actually tell
@@ -30,12 +30,12 @@ const RETRY = SELF_RECOVERING_MARKER;
  * The way out that needs no human at all.
  *
  * `reticle_lease` opens a browser Reticle drives itself, instead of waiting for somebody's tab to
- * dial in. Measured over a day of telemetry it is the single strongest predictor of a session that
- * works: the 5 sessions that used it had a MEDIAN of 30 tool calls and produced 46% of every bug
- * found, against a median of 1 call for the 20 active sessions that did not — and not one
- * single-call bounce used one. It is also advertised on no profile except `full`, so an agent only
- * ever finds it if it already knew it existed. Naming it HERE puts it in front of the agent at the
- * one moment it is the answer, and costs nothing on the turns when it is not.
+ * dial in. In the field it is the single strongest predictor of a session that works: sessions that
+ * use it drive an order of magnitude more tool calls than those that do not, they account for a
+ * disproportionate share of every bug found, and no single-call bounce has ever used one. It is also
+ * advertised on no profile except `full`, so an agent only ever finds it if it already knew it
+ * existed. Naming it HERE puts it in front of the agent at the one moment it is the answer, and
+ * costs nothing on the turns when it is not.
  *
  * Only offered when the app is known to carry the SDK: leasing an uninstrumented app just burns a
  * browser and comes back `ready:false`.
@@ -51,19 +51,75 @@ const SELF_SERVE = 'You do not have to wait for the human: reticle_lease {action
  * evidence that was never gathered.
  */
 /**
- * The second half of the answer for a project that never went through `init`.
+ * The one cause that produces a PERFECTLY healthy everything and still never connects.
  *
- * Held separately because it must appear ONLY when the project is uninstrumented — telling a wired
- * project to re-run `init` sends the reader back to a step that already succeeded, which is its own
- * kind of wrong answer.
+ * The SDK refuses to dial from a page that is not on localhost unless `allowNonLocalhost` is set.
+ * That is deliberate — Reticle must not be reachable from a page it does not trust — but the refusal
+ * happens page-side, so the daemon sees only silence, `doctor` sees only a healthy daemon, and every
+ * checklist item passes. Reported from the field by an agent on a hosts-file alias (the normal setup
+ * for white-label and multi-tenant apps): the whole setup was lost to a flag named in no checklist,
+ * and `init`'s own fallback snippet guards on `hostname === 'localhost'`, so on such a host the
+ * connect never runs and there is not even a console line to find.
+ *
+ * Only offered on the wired-and-listening branch: that is where a correctly installed app that
+ * cannot connect actually lands.
  */
-const UNINSTRUMENTED = 'Separately: this project has not been through `reticle init`, which is what installs the SDK ' +
-    'and wires it into the build — so even once the dev server is up, the app will carry no SDK and ' +
-    "no session will appear. Run `reticle init` in the app's directory too.";
+const NON_LOCALHOST_GATE = 'One more cause that leaves every other check healthy: if the app is served on anything other ' +
+    'than localhost (a hosts-file alias, a LAN IP, a tunnel), the SDK refuses to connect unless it ' +
+    'is given `allowNonLocalhost: true` — the refusal is page-side, so nothing here can see it. ' +
+    "Check the browser console for that message and pass the flag in the app's reticle.connect().";
 const SCANNED_PORTS = [...DEV_SERVER_PORTS].join(', ');
+/**
+ * The commonest first-run state there is, and until #320 the message named it nowhere.
+ *
+ * Reticle sees a page only once a browser has LOADED it. A wired app that nobody has opened produces
+ * exactly the same empty list as a broken install, and the reporter who hit it spent an afternoon
+ * re-verifying their init output, diffing their Vite config and curling their own page before
+ * discovering that one `reticle open` fixed it instantly.
+ */
+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 `reticle open <url>` with the app's own URL (or ask the " +
+    'human to open it).';
+/**
+ * What a machine-wide port scan can and cannot say.
+ *
+ * It finds listeners anywhere on localhost and knows nothing about who owns them. The old wording
+ * spent that as evidence — "something IS listening on port 5173, 8000, 8080, SO a server is up and
+ * has never dialled this daemon" — about three ports that belonged to three other repositories on
+ * the reporter's machine, while their own app sat on a port the scan does not cover. On any machine
+ * running more than one instrumented repo, which is the normal case here, that inference is unsound.
+ */
+function unattributedListeners(listening) {
+    if (0 === listening.length) {
+        return (`No listener found that I can attribute to this project: the scan covers ${SCANNED_PORTS} ` +
+            'across the whole machine, so an app on any other port is invisible to it.');
+    }
+    return (`Something is listening on port ${listening.join(', ')}, but I cannot attribute any of it to ` +
+        `this project: that is a machine-wide scan of ${SCANNED_PORTS}, so on a machine running more ` +
+        "than one repo those are as likely to be somebody else's dev server, and the app's own port " +
+        'may not be in the set at all. Treat them as unattributed rather than as evidence.');
+}
+/**
+ * The mismatch, stated with both numbers, when we can actually see one. Empty otherwise.
+ *
+ * Leading space so the caller can concatenate it unconditionally without producing a double space
+ * in the common case where there is nothing to say.
+ */
+function portMismatchClause(facts) {
+    const configured = facts.projectPort;
+    if (configured === undefined || configured === facts.port)
+        return '';
+    return (` They already disagree: \`.reticle.json\` says port ${String(configured)} and this daemon is` +
+        ` on ${String(facts.port)}, so the SDK is dialling ${String(configured)} and nothing is there.` +
+        ` Either restart the daemon on ${String(configured)}, or update \`.reticle.json\` to` +
+        ` ${String(facts.port)} and restart the dev server so the app picks it up.`);
+}
 export function diagnoseNoSession(facts) {
     const { everConnected, initialized, listening, port } = facts;
-    const ports = listening.join(', ');
+    // Named when known: a claim about a missing file is a claim about ONE directory.
+    const where = facts.directory === undefined
+        ? 'the directory this daemon is running in'
+        : `the directory this daemon is running in (${facts.directory})`;
     if (everConnected) {
         // A reaped lease first, because it is the one cause we have POSITIVE evidence for. Reported
         // from the field (#157): an aged-out lease produced "the tab was closed … ask the human to
@@ -72,49 +128,77 @@ export function diagnoseNoSession(facts) {
         // went looking for a port mismatch. Hedged rather than swapped: a human tab may ALSO have
         // closed, and this does not know which session went.
         if (true === facts.leaseExpired) {
-            return ('no browser session connected — but one WAS connected to this daemon earlier, so the wiring ' +
+            return ('no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
                 'is correct. This daemon has expired at least one pooled lease, so the likeliest cause is ' +
                 'that a lease you were using aged out; a lease is a headless context, not a human tab, and ' +
                 'it takes its cookies with it (so an authenticated app needs signing in again). Re-acquire ' +
                 'with reticle_lease {action:"acquire", url} and carry on. If you were driving a human tab ' +
                 `instead, it went away — reopen it or run \`reticle open\`. ${RETRY}`);
         }
-        return ('no browser session connected — but one WAS connected to this daemon earlier, so the wiring ' +
+        return ('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 ' +
             `the app (or run \`reticle open\`), or reload the tab. ${SELF_SERVE} ${RETRY}`);
     }
     if (0 === listening.length) {
-        return ('no browser session connected, and nothing is listening on the ports Reticle scans ' +
-            `(${SCANNED_PORTS}). The likeliest cause by far is that the dev server is not running: ask ` +
-            'the human to start it (`npm run dev`), then open the app in a browser. ' +
+        // Lead with the stronger EVIDENCE, and do not overstate what it is.
+        //
+        // `initialized` is one thing only: whether a `.reticle.json` sits in the directory this daemon
+        // is running in. It is NOT "this project has never been through `reticle init`", and the two
+        // come apart constantly — a monorepo whose daemon runs at the root while the app lives in
+        // `apps/web`, or any app wired by the babel/vite plugin rather than by `init`. An earlier
+        // version of this branch asserted the strong claim and led with it, on the reasoning that it was
+        // a certainty while the port scan was a guess. It is not a certainty. Caught driving Reticle's
+        // OWN repo, where the message told an agent the project had never been through `init` about a
+        // fixture that is instrumented and working — "the one sentence I was most likely to act on was
+        // wrong", which is the exact failure this whole file exists to prevent.
+        //
+        // So: report what was actually checked, name the directory, and name the case where the absence
+        // is expected rather than diagnostic.
+        if (!initialized) {
+            return ('no browser session connected. Two things to weigh, and neither of them is proof. ' +
+                `(1) Nothing is listening on the ports Reticle scans (${SCANNED_PORTS}), so the dev server ` +
+                'may not be running — ask the human to start it (`npm run dev`). That scan is narrow ' +
+                'though: a server on any other port is invisible to it, so if the app IS running, ask for ' +
+                'its URL rather than assuming it is down, and open it with `reticle open <url>`. ' +
+                `(2) There is no \`.reticle.json\` in ${where}. That is the ` +
+                "file `reticle init` writes, so the app may carry no Reticle SDK — but check the app's " +
+                'OWN directory before re-running `init`: in a monorepo the daemon often runs at the root ' +
+                'while the app lives in a subdirectory, and an app wired by the Vite or Babel plugin ' +
+                `carries the SDK without that file at all. ${RETRY}`);
+        }
+        return (`no browser session connected, and this daemon has never seen one. ${OPEN_THE_APP} ` +
+            'Nothing is listening on the ports Reticle scans ' +
+            `(${SCANNED_PORTS}) either, and the most common reason for that is a dev server that is not ` +
+            'running: ask the human to start it (`npm run dev`), then open the app in a browser. ' +
             // The caveat is here rather than omitted because the scan is NARROW, and the old sentence
-            // spent its confidence as though an empty result from eleven ports were proof of absence.
-            // Reported from a scripted drive of 2.5.0: this branch asserted the app was not running while
-            // it served 200 on :7699. A dev server on any other port — 4173 from `vite preview`, 1420
-            // from Tauri, 5175 from a second Vite, anything passed to --port — is invisible to it.
+            // spent its confidence as though an empty result were proof of absence. Reported twice: a
+            // scripted drive of 2.5.0 asserted the app was not running while it served 200 on :7699, and
+            // an agent was told nothing was listening while a dev server answered on :5000 under a custom
+            // hostname. The common defaults have since been added to the scanned set, which narrows the
+            // gap and cannot close it — anything passed to `--port` is still invisible.
             'That scan is narrow, so it is not proof: a server on any other port is invisible to it. If ' +
             // Deliberately NOT offering reticle_lease here, and a test pins that: a lease opens a URL, and
             // if nothing is listening there is nothing at any URL to open. Asking for the real one is the
             // only move that can recover the :7699 case.
             'the app IS running, ask the human for its URL rather than assuming it is down. ' +
-            // BOTH facts at once when the project was never wired. This branch fires before the
-            // `!initialized` one, so an uninstrumented project used to be told only "start your dev
-            // server" — the reader starts it, calls again, and is told ONLY THEN that no app carries the
-            // SDK. Two round trips to learn two things the daemon knew on the first call, and this is the
-            // largest cohort in the funnel (#171): 77 users attached an agent and never instrumented an
-            // app. They have a daemon (they registered the MCP server) and no SDK anywhere.
-            `${initialized ? '' : UNINSTRUMENTED} ${RETRY}`);
+            // Reachable only for a project that HAS been through `init` — the uninstrumented case is
+            // answered above, leading with that certainty instead of behind this scan's guess.
+            `${RETRY}`);
     }
     if (!initialized) {
-        return (`no browser session connected, but something IS listening on port ${ports} — so a server is ` +
-            'up and has never dialled this daemon. This project has not been through `reticle init`, ' +
-            'which is what installs the SDK and wires it into the build, so the likeliest cause is that ' +
-            "the app carries no Reticle SDK. Ask the human to run `reticle init` in the app's directory " +
-            `and restart the dev server. ${RETRY}`);
+        return ('no browser session connected, and this daemon has never seen one. ' +
+            `What was actually checked: there is no \`.reticle.json\` in ${where}. That is the file ` +
+            '`reticle init` writes, so the app may carry no Reticle SDK — but it is not proof, and the ' +
+            'same absence is expected in a monorepo whose daemon runs at the root while the app lives in ' +
+            "a subdirectory, or in an app wired by the Vite or Babel plugin. Check the app's OWN " +
+            'directory: if it has no config, run `reticle init` there and restart the dev server; if it ' +
+            'has one, the app is wired and simply has no page open — `reticle open <url>`. ' +
+            `${unattributedListeners(listening)} ${RETRY}`);
     }
-    return (`no browser session connected, but something IS listening on port ${ports} and this project is ` +
-        `wired for Reticle — so the app is either serving a build made before the wiring landed, or ` +
-        `dialling a different daemon than this one (this daemon is on ${String(port)}). Ask the human ` +
-        'to restart the dev server and hard-reload the page; if it still does not appear, check that ' +
-        `the app's reticle port matches ${String(port)}. ${SELF_SERVE} ${RETRY}`);
+    return ('no browser session connected, and this daemon has never seen one for this project, which is ' +
+        `wired for Reticle. ${OPEN_THE_APP} ${unattributedListeners(listening)} ` +
+        'If the page IS open and still does not appear, the app is either serving a build made before ' +
+        `the wiring landed or dialling a different daemon than this one (on ${String(port)}): restart ` +
+        "the dev server, hard-reload the page, and check that the app's reticle port matches " +
+        `${String(port)}.${portMismatchClause(facts)} ${NON_LOCALHOST_GATE} ${SELF_SERVE} ${RETRY}`);
 }

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

@@ -11,6 +11,7 @@
  */
 import { probeDevServers } from './dev-server-probe.js';
 import { diagnoseNoSession } from './no-session-diagnosis.js';
+import { readProjectPort } from '../cli/cli-port.js';
 /** Slow enough to be free, fast enough that a dev server started 15s ago is already reflected. */
 const REFRESH_MS = 15_000;
 /** Start the watch. Returns a stop function; the timer is unref'd so it never holds the daemon up. */
@@ -42,7 +43,18 @@ function startNoSessionWatch(options) {
         initialized: options.initialized,
         listening,
         port: options.port,
+        // The directory `initialized` was decided in. Named in the message because "there is no
+        // `.reticle.json`" is a claim about ONE directory, and a reader standing somewhere else
+        // cannot tell whether it is a claim about their app at all.
+        directory: options.directory ?? process.cwd(),
         leaseExpired: (options.reapedLeases?.() ?? 0) > 0,
+        // Read here rather than at boot: `.reticle.json` can be written by `init` after this daemon
+        // started, which is the ordinary first-install order, and a port cached from before it existed
+        // would make the daemon confidently report no mismatch on the one run where there is one.
+        ...(() => {
+            const configured = readProjectPort(options.directory ?? process.cwd());
+            return configured === undefined ? {} : { projectPort: configured };
+        })(),
     }));
     return () => {
         clearInterval(timer);