@reticlehq/server 3.1.0 → 3.2.0

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

@@ -129,8 +129,10 @@ const NUXT_STALE_BUNDLE = 'This project is Nuxt: the most likely cause by a dist
 const RESTARTED_LEAD = 'no browser session connected. This daemon has served none since it started, but it is a NEW ' +
     'process — an app for this project HAS connected on this port before, which is recorded ' +
     'durably. So the wiring is correct and the port is correct: what is failing now is the SDK ' +
-    'reaching initialise on the page. Re-running the install is the wrong move here: it cannot help ' +
-    'on a project that has demonstrably connected, and it can overwrite a working config.';
+    'reaching initialise on the page.';
+/** Why the obvious move is the wrong one here. Reasoning, so it rides in the detail. */
+const DO_NOT_REINSTALL = 'Re-running the install is the wrong move here: it cannot help on a project that has ' +
+    'demonstrably connected, and it can overwrite a working config.';
 /**
  * The ports the scan actually covers, rendered for the message.
  *
@@ -259,10 +261,8 @@ function configsElsewhereClause(facts) {
         .map((c) => (c.projectId === undefined ? c.directory : `${c.directory} ('${c.projectId}')`))
         .join(', ');
     return (`A \`.reticle.json\` WAS found outside this daemon's directory: ${named}. So the app is wired ` +
-        'and this is a SCOPE problem, not an install problem — this daemon was started somewhere that ' +
-        'is not the project, which is the normal outcome when an editor launches it from your home ' +
-        "directory. Restart the daemon from the app's directory (or point it there) rather than " +
-        'installing anything.');
+        'and this is a SCOPE problem, not an install problem. Restart the daemon from the ' +
+        "app's directory (or point it there) rather than installing anything.");
 }
 /** Where we looked, when we found nothing. An absence nobody can check is not evidence. */
 function searchedClause(facts) {
@@ -327,13 +327,12 @@ export function explainNoSession(facts) {
     if (true === facts.authRefused) {
         return reason(NoSessionReason.AUTH_REFUSED, 'no browser session connected, and the reason is not the app: this daemon REFUSED the last ' +
             'page that dialled it, because the pairing token it presented is not the one this daemon ' +
-            'holds. Only an SDK dials the bridge, so the wiring is correct and the app is running. The ' +
-            'token is read by the build plugin when the dev server STARTS, so the usual cause is a ' +
-            'daemon restarted (or a `~/.reticle` cleared) after the dev server was already up, and the ' +
-            'fix is to restart the dev server so it picks up the current token. If the two were started ' +
-            'from different environments — an editor spawning the MCP server globally while the dev ' +
-            'server runs from a shell — they can be reading different `~/.reticle` directories instead. ' +
-            'The page says the same thing in the browser console.');
+            'holds. Only an SDK dials the bridge, so the wiring is correct and the app is running. ' +
+            'Restart the dev server so it picks up the current token.', 'The token is read by the build plugin when the dev server STARTS, so the usual cause is a ' +
+            'daemon restarted (or a `~/.reticle` cleared) after the dev server was already up. If the ' +
+            'two were started from different environments — an editor spawning the MCP server globally ' +
+            'while the dev server runs from a shell — they can be reading different `~/.reticle` ' +
+            'directories instead. The page says the same thing in the browser console.');
     }
     if (everConnected) {
         // A reaped lease first, because it is the one cause with POSITIVE evidence behind it. Calling
@@ -344,15 +343,13 @@ export function explainNoSession(facts) {
         // (#611), so this branch is only reached when the thing that vanished WAS the lease.
         if (true === facts.leaseExpired) {
             return reason(NoSessionReason.LEASE_EXPIRED, 'no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
-                'is correct. The session that went away was a pooled lease and it aged out; a lease is a ' +
-                'headless context, not a human tab, and it takes its cookies with it (so an authenticated ' +
-                'app needs signing in again). Re-acquire with reticle_lease {action:"acquire", url} and ' +
-                `carry on.${alreadyListeningClause(listening)} ${RETRY}`);
+                'is correct. The session that went away was a pooled lease and it aged out. Re-acquire ' +
+                `with reticle_lease {action:"acquire", url} and carry on. ${RETRY}`, 'A lease is a headless context, not a human tab, and it takes its cookies with it, so an ' +
+                `authenticated app needs signing in again.${alreadyListeningClause(listening)}`);
         }
         return reason(NoSessionReason.TAB_GONE, 'no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
             `is correct. ${tabGoneWhat(facts.lastKnownUrl)} Ask the human to reopen ` +
-            `the app (or run ${OPEN_CMD_BARE}), or reload the tab.${alreadyListeningClause(listening)} ` +
-            `${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
+            `the app (or run ${OPEN_CMD_BARE}), or reload the tab. ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, alreadyListeningClause(listening).trim());
     }
     // Ranked ahead of every "we have never seen one" branch below, because it is the one fact that
     // OUTRANKS them: those branches all reason from an absence, and this reasons from a recorded
@@ -363,15 +360,16 @@ export function explainNoSession(facts) {
             ? `${unattributedListeners(listening)} If the dev server is not running, start it first ` +
                 '(the command is in `next_action`).'
             : unattributedListeners(listening);
-        return reason(NoSessionReason.APP_NOT_REOPENED, `${RESTARTED_LEAD} ${OPEN_THE_APP} ${listeners} ${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
+        return reason(NoSessionReason.APP_NOT_REOPENED, `${RESTARTED_LEAD} ${OPEN_THE_APP} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, `${DO_NOT_REINSTALL} ${listeners} ${rankedCauses(facts)}`);
     }
     // A config found elsewhere outranks every "you may have no SDK" branch below: those reason from
     // an absence in ONE directory, and this is a file we read in another. Ranked here so the reader is
     // never sent through an install on a project that has demonstrably been installed.
     if (!initialized && (facts.configsElsewhere ?? []).length > 0) {
         return reason(NoSessionReason.CONFIG_ELSEWHERE, 'no browser session connected, and this daemon has never seen one. ' +
-            `${configsElsewhereClause(facts)} ${unattributedListeners(listening)} ${OPEN_THE_APP} ` +
-            `${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
+            `${configsElsewhereClause(facts)} ${OPEN_THE_APP} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, 'This daemon was started somewhere that is not the project, which is the normal outcome when ' +
+            `an editor launches it from your home directory. ${unattributedListeners(listening)} ` +
+            `${rankedCauses(facts)}`);
     }
     if (0 === listening.length) {
         // Lead with the stronger EVIDENCE, and do not overstate what it is.
@@ -390,54 +388,62 @@ export function explainNoSession(facts) {
         // is expected rather than diagnostic.
         if (!initialized) {
             return reason(NoSessionReason.NO_LISTENER_NO_CONFIG, 'no browser session connected. Two things to weigh, and neither of them is proof. ' +
-                `(1) ${slowListenerClause(facts)}Nothing is listening on the ports Reticle scans (${SCANNED_PORTS}), so the dev server ` +
-                'may not be running — START IT YOURSELF, in the background, using the command in ' +
-                "`next_action` (it is read from this project's own scripts; if there is none, that field " +
-                'says so and you should ask rather than guess). Tell the human in one line that it is ' +
-                'running. That scan is narrow ' +
-                'though: a server on any other port is invisible to it, so if the app IS running, ask for ' +
-                `its URL rather than assuming it is down, and open it with ${OPEN_CMD}. ` +
-                `(2) There is no \`.reticle.json\` in ${where}. That is the ` +
-                `file ${INIT_CMD} writes, so the app may carry no Reticle SDK — but check the app's ` +
-                'OWN directory before re-running `init`: in a monorepo the daemon often runs at the root ' +
-                'while the app lives in a subdirectory, and an app wired by the Vite or Babel plugin ' +
-                `carries the SDK without that file at all.${searchedClause(facts)}${siblingListenerClause(facts)} ${leaseAdvice(URL_THEN_LEASE, facts)} ${RETRY}`);
+                `(1) ${slowListenerClause(facts)}Nothing is listening on the ports Reticle scans, so the ` +
+                'dev server may not be running: START IT YOURSELF, in the background, using the command ' +
+                'in `next_action`, and tell the human in one line that it is running. ' +
+                `(2) There is no \`.reticle.json\` in ${where}, which is the file ${INIT_CMD} writes, so ` +
+                `the app may carry no Reticle SDK. Check the app's OWN directory before re-running it. ${RETRY}`, `The scan covers ${SCANNED_PORTS} and nothing else, so a server on any other port is ` +
+                'invisible to it: if the app IS running, ask for its URL rather than assuming it is down, ' +
+                `and open it with ${OPEN_CMD}. The missing config is not proof either — in a monorepo the ` +
+                'daemon often runs at the root while the app lives in a subdirectory, and an app wired by ' +
+                'the Vite or Babel plugin carries the SDK without that file at all.' +
+                `${searchedClause(facts)}${siblingListenerClause(facts)} ${leaseAdvice(URL_THEN_LEASE, facts)}`);
         }
         return reason(NoSessionReason.NO_LISTENER, `${stallClause(facts)}no browser session connected, and this daemon has never seen one. ${OPEN_THE_APP} ` +
-            'Nothing is listening on the ports Reticle scans ' +
-            `(${SCANNED_PORTS}) either, and the most common reason for that is a dev server that is not ` +
-            'running: start it yourself in the background with the command in `next_action` — it is read ' +
-            "from this project's own scripts, and says so rather than guessing when there is none — tell " +
-            'the human in one line that it is running, then open the app in a browser. ' +
-            // The caveat is here rather than omitted because the scan is NARROW: an empty result is not
-            // proof of absence. Reported twice, once against a server answering 200 on :7699 and once
-            // against one on :5000 under a custom hostname. The common defaults are in the scanned set,
-            // which narrows the gap and cannot close it — anything passed to `--port` is invisible.
-            'That scan is narrow, so it is not proof: a server on any other port is invisible to it. If ' +
+            'Nothing is listening on the ports Reticle scans either, and the usual reason is a dev ' +
+            'server that is not running: start it yourself in the background with the command in ' +
+            '`next_action`, tell the human in one line that it is running, then open the app in a ' +
+            `browser. ${RETRY}`, 
+        // The caveat is in the detail rather than omitted because the scan is NARROW: an empty result
+        // is not proof of absence. Reported twice, once against a server answering 200 on :7699 and
+        // once against one on :5000 under a custom hostname. The common defaults are in the scanned
+        // set, which narrows the gap and cannot close it — anything passed to `--port` is invisible.
+        `The scan covers ${SCANNED_PORTS} and nothing else, so it is not proof: a server on any other ` +
+            'port is invisible to it. If the app IS running, ask the human for its URL rather than ' +
             // Deliberately NOT offering reticle_lease here, and a test pins that: a lease opens a URL, and
             // if nothing is listening there is nothing at any URL to open. Asking for the real one is the
             // only move that can recover the :7699 case.
-            `the app IS running, ask the human for its URL rather than assuming it is down. ${leaseAdvice(URL_THEN_LEASE, facts)}` +
-            `${siblingListenerClause(facts)} ${RETRY}`);
+            `assuming it is down. The \`next_action\` command is read from this project's own scripts, ` +
+            'and says so rather than guessing when there is none. ' +
+            `${leaseAdvice(URL_THEN_LEASE, facts)}${siblingListenerClause(facts)}`);
     }
     if (!initialized) {
         return reason(NoSessionReason.NO_CONFIG, 'no browser session connected, and this daemon has never seen one. ' +
-            `What was actually checked: there is no \`.reticle.json\` in ${where}. That is the file ` +
-            `${INIT_CMD} writes, so the app may carry no Reticle SDK — but it is not proof, and the ` +
-            'same absence is expected in a monorepo whose daemon runs at the root while the app lives in ' +
-            "a subdirectory, or in an app wired by the Vite or Babel plugin. Check the app's OWN " +
-            `directory: if it has no config, run ${INIT_CMD} there and restart the dev server; if it ` +
-            `has one, the app is wired and simply has no page open — ${OPEN_CMD}. ` +
-            `${unattributedListeners(listening)}${searchedClause(facts)}${siblingListenerClause(facts)} ${RETRY}`);
+            `What was actually checked: there is no \`.reticle.json\` in ${where}, which is the file ` +
+            `${INIT_CMD} writes, so the app may carry no Reticle SDK. Check the app's OWN directory: ` +
+            `if it has no config, run ${INIT_CMD} ` +
+            'there and restart the dev server; if it has one, the app is wired and simply has no page ' +
+            `open — ${OPEN_CMD}. ${RETRY}`, 'That absence is not proof: the same one is expected in a monorepo whose daemon runs at the ' +
+            'root while the app lives in a subdirectory, or in an app wired by the Vite or Babel ' +
+            `plugin. ${unattributedListeners(listening)}${searchedClause(facts)}${siblingListenerClause(facts)}`);
     }
     return reason(NoSessionReason.SDK_NOT_REACHING_DAEMON, `${stallClause(facts)}no browser session connected, and this daemon has never seen one for this project, which is ` +
-        `wired for Reticle. ${OPEN_THE_APP} ${unattributedListeners(listening)} ` +
-        'If the page IS open and still does not appear, the app is wired and the SDK is not reaching ' +
-        `this daemon (on ${String(port)}). ${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
+        `wired for Reticle. ${OPEN_THE_APP} If the page IS open and still does not appear, the SDK ` +
+        `is not reaching this daemon (on ${String(port)}). ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, `${unattributedListeners(listening)} ${rankedCauses(facts)}`);
 }
-/** Pair a branch's verdict with its prose, so neither can be produced without the other. */
-function reason(code, message) {
-    return { reason: code, message };
+/**
+ * Pair a branch's verdict with its prose, so neither can be produced without the other.
+ *
+ * TWO pieces of prose now. `message` is the lead: what is true and what to do about it, in about
+ * four sentences. `detail` is the differential behind it -- the port-scan caveat, the ranked causes,
+ * the lease offer -- which is the part that was making this five hundred words in one paragraph.
+ *
+ * Split rather than deleted. Almost every clause in `detail` exists because somebody was sent the
+ * wrong way without it, and the reader who needs it is the agent about to spend a drive on a guess.
+ * The reader who does not is the person watching `reticle init`, who gets the lead.
+ */
+function reason(code, message, detail) {
+    return { reason: code, message, ...(undefined === detail ? {} : { detail }) };
 }
 /**
  * The message alone, for the callers that render it.
@@ -446,5 +452,6 @@ function reason(code, message) {
  * pair would spread a telemetry concern across every error path that shows a user this text.
  */
 export function diagnoseNoSession(facts) {
-    return explainNoSession(facts).message;
+    const { message, detail } = explainNoSession(facts);
+    return undefined === detail ? message : `${message} ${detail}`;
 }

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

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

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

@@ -23,7 +23,7 @@ import { daemonsServingProjectElsewhere, splitBrainNote } from '../../command/da
 import { stallUptime } from './stall-clock.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
 import { findOccupiedSiblings } from '../../command/cli/ports/sibling-ports.js';
-import { WS_CLOSE_REASON } from '../bridge/bridge.js';
+import { isAuthRefusalReason } from '../bridge/auth-failure-reason.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. */
@@ -208,7 +208,7 @@ export function startNoSessionWatch(options) {
     /**
      * Is a refusal on the pairing token the CURRENT state of the bridge?
      *
-     * The bridge records the refusal (`noteClosure(WS_CLOSE_REASON.AUTH_FAILED)`) and nothing read it
+     * The bridge records the refusal (the sentence it closed the socket with) 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.
      *
@@ -223,7 +223,7 @@ export function startNoSessionWatch(options) {
      * recorded no refusal, which falls through to the behaviour that was there before -- the safe
      * direction for a fact whose job is to SUPPRESS advice rather than to add any.
      */
-    const lastCloseWasAuthFailure = () => options.sessions.lastClosure?.()?.reason === WS_CLOSE_REASON.AUTH_FAILED &&
+    const lastCloseWasAuthFailure = () => isAuthRefusalReason(options.sessions.lastClosure?.()?.reason) &&
         true !== options.sessions.connectedSinceLastClosure?.();
     const nextAction = (scope) => {
         const split = splitBrain();
@@ -307,19 +307,23 @@ export function startNoSessionWatch(options) {
             ...(0 === siblingListeners.length ? {} : { siblingListeners }),
         });
     };
-    options.sessions.setNoSessionHint(() => {
+    // The lead, then the literal command, then the differential. Both renderings consume the same
+    // scope facts so a discovered workspace config cannot become an `init` recommendation below it,
+    // and both come from ONE `explain()` call so they cannot describe different branches.
+    const rendered = () => {
         const scope = projectScopeFacts();
-        return (explain().message +
-            // Prose for the human, then the literal command for the agent. Both consume the same scope
-            // facts so a discovered workspace config cannot become an `init` recommendation below it.
-            ` ${renderNextAction(nextAction(scope))}` +
-            (attachFailure ?? ''));
-    });
+        const { message, detail } = explain();
+        const lead = `${message} ${renderNextAction(nextAction(scope))}${attachFailure ?? ''}`;
+        return { lead, full: undefined === detail ? lead : `${lead} ${detail}` };
+    };
+    options.sessions.setNoSessionHint(() => rendered().full);
+    options.sessions.setNoSessionLead(() => rendered().lead);
     options.sessions.setNoSessionReason(() => explain().reason);
     return () => {
         clearInterval(timer);
         options.sessions.setConnectionRecorder(undefined);
         options.sessions.setNoSessionHint(undefined);
+        options.sessions.setNoSessionLead(undefined);
         options.sessions.setNoSessionReason(undefined);
         options.sessions.setNoSessionNextAction(undefined);
     };

package/dist/portal/session/rebind.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Commands that may be re-issued against the connection that replaced this session.
+ *
+ * Reads only, and the boundary is the point. Re-reading a page costs nothing and answers the same
+ * question the caller asked. An act cannot be replayed: it may already have been dispatched in the
+ * page that went away, and performing it a second time behind the caller's back is a double submit
+ * nobody asked for. A replaced act still errors, and the caller's own retry — with the same id,
+ * which is still the right one — is the safe path.
+ */
+export declare const REBINDABLE_COMMANDS: ReadonlySet<string>;
+/**
+ * How far to walk a chain of replacements before giving up.
+ *
+ * Generous for the real case (a page reloading a handful of times while a call is in flight) and
+ * small enough that a cycle costs nothing. The number is a backstop, not a policy: a chain longer
+ * than this means something is re-dialling in a loop, and that is a different problem.
+ */
+export declare const MAX_SUCCESSOR_HOPS = 32;

package/dist/portal/session/rebind.js

@@ -0,0 +1,38 @@
+/**
+ * Whether a command in flight may be re-issued against the connection that REPLACED this session,
+ * and how far a chain of replacements is worth walking.
+ *
+ * One question, so one file. It left `session.ts` when that file crossed the thousand-line cap on a
+ * merge: two branches had each grown it by a few lines and the sum went over, which is the moment
+ * the rule says to split rather than to raise the number. These two constants and the reasoning
+ * behind them are the most self-contained thing in there — `session.ts` reads them twice and owns
+ * nothing else about rebinding.
+ */
+import { ReticleCommand } from '@reticlehq/core';
+/**
+ * Commands that may be re-issued against the connection that replaced this session.
+ *
+ * Reads only, and the boundary is the point. Re-reading a page costs nothing and answers the same
+ * question the caller asked. An act cannot be replayed: it may already have been dispatched in the
+ * page that went away, and performing it a second time behind the caller's back is a double submit
+ * nobody asked for. A replaced act still errors, and the caller's own retry — with the same id,
+ * which is still the right one — is the safe path.
+ */
+export const REBINDABLE_COMMANDS = new Set([
+    ReticleCommand.SNAPSHOT,
+    ReticleCommand.QUERY,
+    ReticleCommand.MATCH,
+    ReticleCommand.INSPECT,
+    ReticleCommand.STATE_READ,
+    ReticleCommand.STORAGE_READ,
+    ReticleCommand.CAPABILITIES,
+    ReticleCommand.ANIMATIONS,
+]);
+/**
+ * How far to walk a chain of replacements before giving up.
+ *
+ * Generous for the real case (a page reloading a handful of times while a call is in flight) and
+ * small enough that a cycle costs nothing. The number is a backstop, not a policy: a chain longer
+ * than this means something is re-dialling in a loop, and that is a different problem.
+ */
+export const MAX_SUCCESSOR_HOPS = 32;

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

@@ -30,6 +30,10 @@ export declare class SessionManager {
     count(): number;
     /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
     setNoSessionHint(hint: (() => string | undefined) | undefined): void;
+    /** Wire the short rendering. Registered from the same `explainNoSession` call as the hint. */
+    setNoSessionLead(lead: (() => string | undefined) | undefined): void;
+    /** The lead and the next action, for a surface a person reads. */
+    noSessionLead(): string | undefined;
     /**
      * The same diagnosis, for a caller that is ASKING about sessions rather than failing to get one.
      *

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

@@ -4,6 +4,7 @@ import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input
 import { Session } from './session.js';
 import { AttachmentHistory } from './presence/attachment-history.js';
 import { pickDocumentSuccessor } from './session-successor.js';
+import { SESSION_DISCONNECTED_REASON } from './facts/session-replaced.js';
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export function originOf(url) {
     if (url === undefined)
@@ -143,7 +144,7 @@ export class SessionManager {
     remove(session) {
         if (this.#sessions.get(session.id) !== session)
             return false;
-        session.rejectAll('session disconnected');
+        session.rejectAll(SESSION_DISCONNECTED_REASON);
         forgetDrivenRedactionKeys(session.id);
         // Recorded, not forgotten: a session that comes back needs its gap measured, and a listing after
         // the reconnect is exactly where that matters.
@@ -246,10 +247,27 @@ export class SessionManager {
      * different branches. See no-session-watch.ts.
      */
     #noSessionReason;
+    /**
+     * The same diagnosis with the differential left off: the lead and the next action, nothing else.
+     *
+     * Two renderings because there are two readers, and only one of them can spend the words. An
+     * agent about to burn a drive on a guess wants the ranked causes, the port-scan caveat and the
+     * lease offer. The person watching `reticle init` fail wants to know what is wrong and what to
+     * type, and was instead handed roughly five hundred words in one paragraph.
+     */
+    #noSessionLead;
     /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
     setNoSessionHint(hint) {
         this.#noSessionHint = hint;
     }
+    /** Wire the short rendering. Registered from the same `explainNoSession` call as the hint. */
+    setNoSessionLead(lead) {
+        this.#noSessionLead = lead;
+    }
+    /** The lead and the next action, for a surface a person reads. */
+    noSessionLead() {
+        return this.#noSessionLead?.();
+    }
     /**
      * The same diagnosis, for a caller that is ASKING about sessions rather than failing to get one.
      *

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

@@ -1,5 +1,5 @@
 import type { WebSocket } from 'ws';
-import type { ChannelId, ImpactSnapshot } from '@reticlehq/core';
+import { type ChannelId, type ImpactSnapshot, type ProjectId } from '@reticlehq/core';
 import type { HandshakeFacts } from './facts/handshake-facts.js';
 import { LastAct } from './last-act.js';
 import { GapLedger } from '@reticlehq/engine/evidence/gap-ledger.js';
@@ -7,7 +7,7 @@ import { CaptureLedger } from '../../surface/tools/feature-capture.js';
 import { type PageRuntime } from './timing/command-timeout.js';
 import { type SessionHealth } from './session-health.js';
 export type { SessionHealth };
-import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type JournalAction, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
+import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type JournalAction, type JournalWriteLoss, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
 import type { JournalReader, JournalRecorder } from '../../memory/journal/journal-recorder.js';
 import { type EventQueryOptions } from '../../memory/journal/journal-query.js';
 import { type AmbientCounts } from '@reticlehq/engine/window/ambient.js';
@@ -25,8 +25,14 @@ type Clock = () => number;
 export declare class Session implements HandshakeFacts {
     #private;
     readonly id: string;
-    /** Stable build-stamped project identity; undefined for v1.0 SDKs that omit it. */
-    readonly projectId: string | undefined;
+    /**
+     * Stable build-stamped project identity; undefined for SDKs old enough to omit it.
+     *
+     * MINTED HERE. This is one of the two places a projectId enters the daemon with its provenance
+     * intact: the field is `projectId` on a zod-parsed HELLO, so the page said what it is. Every
+     * downstream reader takes the brand from this property rather than re-blessing a string.
+     */
+    readonly projectId: ProjectId | undefined;
     /**
      * The `.reticle` directory this session's evidence belongs in — impact counters AND capsules.
      *
@@ -118,12 +124,13 @@ export declare class Session implements HandshakeFacts {
      */
     setJournal(recorder: JournalRecorder, reader?: JournalReader): void;
     /**
-     * Journal-backed event query: the ring buffer's events, merged with the durable journal **only when
-     * the buffer has evicted** (so a healthy session pays no disk cost), then filtered by since/until/
-     * actionId. This is how "what did action N cause" is answered after the buffer has dropped the
-     * evidence — the substrate's whole point. The sync `eventsSince`/`window` stay for the hot path.
+     * Journal-backed event query — the rule itself lives in `readQueryEvents`, beside the merge and
+     * filter it is made of. This is how "what did action N cause" is answered after the buffer has
+     * dropped the evidence. The sync `eventsSince`/`window` stay for the hot path.
      */
     queryEvents(options: EventQueryOptions): Promise<ReticleEvent[]>;
+    /** What the durable ledger could not WRITE — see `readJournalWriteLoss` for the rule and why. */
+    journalWriteLoss(): Promise<JournalWriteLoss | undefined>;
     /**
      * Open an action-attribution window: events observed until finishAction attribute to the returned
      * action id. Ids are minted independently of command correlation ids so the journal is self-contained.
@@ -200,9 +207,13 @@ export declare class Session implements HandshakeFacts {
         dropped: number;
     };
     /**
-     * Did the buffer lose scarce evidence from a window opened at `cursor`? The input to whether a
+     * Did the EVENT STORE lose scarce evidence from a window opened at `cursor`? The input to whether a
      * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
-     * moves for the age and churn evictions that every live page produces continuously.
+     * moves for the age and churn evictions that every live page produces continuously. The journal is
+     * the other half of that store, so a durable read that could not reach back to `cursor` lost
+     * exactly what an eviction would have. Both boundaries are INCLUSIVE (`t` is a millisecond many
+     * records share) and an absent `lostThroughT` impeaches every window rather than none — the
+     * conservative direction, both times.
      */
     lostSince(cursor: number): boolean;
     onEvent(listener: (event: ReticleEvent) => void): () => void;

package/dist/portal/session/session.js

@@ -1,3 +1,4 @@
+import { asProjectId } from '@reticlehq/core';
 import { refusedResult } from './page-commands/undeclared-command.js';
 import { recordImpact } from '../../memory/impact/impact-recorder.js';
 import { LastAct } from './last-act.js';
@@ -13,7 +14,7 @@ import { span } from '../../trace.js';
 import { keepCallerContextInDaemon, noteToDaemonLog } from './daemon-answers.js';
 import { isKnownRealm, EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
 import { RingBuffer } from '@reticlehq/engine/window/ring-buffer.js';
-import { filterEvents, mergeEventsBySeq, } from '../../memory/journal/journal-query.js';
+import { readJournalWriteLoss, readQueryEvents, } from '../../memory/journal/journal-query.js';
 import {} from '@reticlehq/engine/window/ambient.js';
 import { ObservedState } from './facts/observed-state.js';
 import { recordBrowserLatency, recordSdkFailure } from '../../telemetry/session-metrics.js';
@@ -23,36 +24,10 @@ import { buildSessionRecommendation } from './presence/session-recommendation.js
 import { buildPresenterArgs } from './human/presenter-args.js';
 import { buildSessionLease } from './presence/session-lease.js';
 import { buildSessionInfo } from './session-info.js';
+import { MAX_SUCCESSOR_HOPS, REBINDABLE_COMMANDS } from './rebind.js';
 const DEFAULT_COMMAND_TIMEOUT_MS = 8000;
 /** Prefix on correlated command ids (c1, c2, …) — distinguishes them from mark ids. */
 const COMMAND_ID_PREFIX = 'c';
-/**
- * Commands that may be re-issued against the connection that replaced this session.
- *
- * Reads only, and the boundary is the point. Re-reading a page costs nothing and answers the same
- * question the caller asked. An act cannot be replayed: it may already have been dispatched in the
- * page that went away, and performing it a second time behind the caller's back is a double submit
- * nobody asked for. A replaced act still errors, and the caller's own retry — with the same id,
- * which is still the right one — is the safe path.
- */
-/**
- * How far to walk a chain of replacements before giving up.
- *
- * Generous for the real case (a page reloading a handful of times while a call is in flight) and
- * small enough that a cycle costs nothing. The number is a backstop, not a policy: a chain longer
- * than this means something is re-dialling in a loop, and that is a different problem.
- */
-const MAX_SUCCESSOR_HOPS = 32;
-const REBINDABLE_COMMANDS = new Set([
-    ReticleCommand.SNAPSHOT,
-    ReticleCommand.QUERY,
-    ReticleCommand.MATCH,
-    ReticleCommand.INSPECT,
-    ReticleCommand.STATE_READ,
-    ReticleCommand.STORAGE_READ,
-    ReticleCommand.CAPABILITIES,
-    ReticleCommand.ANIMATIONS,
-]);
 /** Prefix on minted action ids (a1, a2, …) — the journal's action identity, independent of commands. */
 const ACTION_ID_PREFIX = 'a';
 /**
@@ -69,7 +44,13 @@ const WS_OPEN = 1;
  */
 export class Session {
     id;
-    /** Stable build-stamped project identity; undefined for v1.0 SDKs that omit it. */
+    /**
+     * Stable build-stamped project identity; undefined for SDKs old enough to omit it.
+     *
+     * MINTED HERE. This is one of the two places a projectId enters the daemon with its provenance
+     * intact: the field is `projectId` on a zod-parsed HELLO, so the page said what it is. Every
+     * downstream reader takes the brand from this property rather than re-blessing a string.
+     */
     projectId;
     /**
      * The `.reticle` directory this session's evidence belongs in — impact counters AND capsules.
@@ -145,7 +126,7 @@ export class Session {
     #editEpoch;
     constructor(hello, socket, clock) {
         this.id = hello.sessionId;
-        this.projectId = hello.projectId;
+        this.projectId = hello.projectId === undefined ? undefined : asProjectId(hello.projectId);
         this.url = hello.url;
         this.title = hello.title;
         this.adapters = hello.adapters;
@@ -408,17 +389,16 @@ export class Session {
         this.#journalReader = reader;
     }
     /**
-     * Journal-backed event query: the ring buffer's events, merged with the durable journal **only when
-     * the buffer has evicted** (so a healthy session pays no disk cost), then filtered by since/until/
-     * actionId. This is how "what did action N cause" is answered after the buffer has dropped the
-     * evidence — the substrate's whole point. The sync `eventsSince`/`window` stay for the hot path.
+     * Journal-backed event query — the rule itself lives in `readQueryEvents`, beside the merge and
+     * filter it is made of. This is how "what did action N cause" is answered after the buffer has
+     * dropped the evidence. The sync `eventsSince`/`window` stay for the hot path.
      */
     async queryEvents(options) {
-        if (this.#journalReader !== undefined && this.#buffer.bufferHealth().dropped > 0) {
-            const durable = await this.#journalReader.readEvents();
-            return filterEvents(mergeEventsBySeq(durable, this.#buffer.since(0)), options);
-        }
-        return filterEvents(this.#buffer.since(options.since ?? 0), options);
+        return readQueryEvents(this.#journalReader, this.#buffer, options);
+    }
+    /** What the durable ledger could not WRITE — see `readJournalWriteLoss` for the rule and why. */
+    async journalWriteLoss() {
+        return readJournalWriteLoss(this.#journalReader, this.#buffer);
     }
     /**
      * Open an action-attribution window: events observed until finishAction attribute to the returned
@@ -541,12 +521,19 @@ export class Session {
         return this.#buffer.bufferHealth();
     }
     /**
-     * Did the buffer lose scarce evidence from a window opened at `cursor`? The input to whether a
+     * Did the EVENT STORE lose scarce evidence from a window opened at `cursor`? The input to whether a
      * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
-     * moves for the age and churn evictions that every live page produces continuously.
+     * moves for the age and churn evictions that every live page produces continuously. The journal is
+     * the other half of that store, so a durable read that could not reach back to `cursor` lost
+     * exactly what an eviction would have. Both boundaries are INCLUSIVE (`t` is a millisecond many
+     * records share) and an absent `lostThroughT` impeaches every window rather than none — the
+     * conservative direction, both times.
      */
     lostSince(cursor) {
-        return this.#buffer.lostSince(cursor);
+        if (this.#buffer.lostSince(cursor))
+            return true;
+        const lost = this.#journalReader?.readLoss?.();
+        return lost !== undefined && (lost.lostThroughT === undefined || lost.lostThroughT >= cursor);
     }
     onEvent(listener) {
         this.#listeners.add(listener);

package/dist/status-payload.d.ts

@@ -19,12 +19,23 @@ interface StatusPayload {
      * beside a live session.
      */
     why?: string;
+    /**
+     * The same diagnosis with the differential left off: the lead and the next action.
+     *
+     * Two fields because there are two readers. `why` is for an agent about to spend a drive on a
+     * guess, and carries the ranked causes, the port-scan caveat and the lease offer. `whyLead` is
+     * for a surface a PERSON reads: `reticle init` prints the daemon's account of a failed connect,
+     * and was printing roughly five hundred words of it in one paragraph.
+     */
+    whyLead?: string;
     /** Port of the verify HTTP endpoint this daemon serves — present only when started with `--http`. */
     verifyPort?: number;
 }
 export declare function statusPayload(sessionCount: number, sessions: SessionInfo[], 
 /** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
-why?: string, verifyPort?: number): StatusPayload;
+why?: string, verifyPort?: number, 
+/** The short rendering of the same diagnosis. Absent on a daemon that has no provider wired. */
+whyLead?: string): StatusPayload;
 /**
  * Why `serve --http` cannot claim success against an already-running daemon — or undefined when
  * that daemon already serves the verify HTTP endpoint on the wanted port.