@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,211 @@
+/**
+ * "No browser session connected", as something an agent can RUN.
+ *
+ * The prose diagnosis next door is good and it is prose: the agent has to read four hedged sentences
+ * and decide which of them is about its situation. This is the same decision, decided here, as one
+ * value plus one literal command — so the branch happens in the daemon, which has the evidence,
+ * rather than in the agent, which does not.
+ *
+ * The rule that outranks helpfulness: never invent a command. If the project has no dev script, this
+ * says there is none. A command that does not exist sends the agent chasing a phantom error in its
+ * own repo.
+ *
+ * Pure. The facts arrive from the watch; nothing here touches the disk or the clock.
+ */
+import { NoSessionAction, ReticleEnv } from '@reticlehq/core';
+/** `reticle init`, the only command here that is Reticle's own and so cannot be wrong. */
+const INIT_COMMAND = 'reticle init';
+const OPEN_COMMAND = 'reticle open';
+const LOCALHOST = 'http://localhost';
+export function nextActionFor(facts) {
+    // FIRST, above every other cause, because it is the only one supported by positive evidence about
+    // a daemon rather than by an absence. This project's own connection record names a live daemon
+    // that is not this one, which means the app is up and instrumented and the agent is simply looking
+    // at the wrong process. Every branch below would send it to fix something that is not broken —
+    // start a dev server that is running, open a page that is open, or re-run `init` over a config
+    // that works — and the agent has no way to suspect the real cause from here.
+    const splitBrain = facts.splitBrain;
+    if (splitBrain !== undefined) {
+        return { action: NoSessionAction.DAEMON_SPLIT, reason: splitBrain };
+    }
+    // `authRefused` is checked here and not only further down, because this branch short-circuits.
+    //
+    // Both refusal branches below were already written and already right, and neither could be
+    // reached once a session had ever connected: `everConnected` is a LIFETIME fact and won. The
+    // payload then disagreed with itself — the message said the daemon had refused a page on its
+    // token while the next action beside it said the tab had been closed and offered to reopen it,
+    // which reopens a page that will be refused again. Measured on a token rotation: `status` said
+    // "reopen the tab" while the daemon's own log said `authentication failed: wrong pairing token`.
+    //
+    // This is only correct because `authRefused` means "refused, and nothing has connected since"
+    // (`connectedSinceLastClosure` in the manager). Read as the weaker "a refusal was recorded at
+    // some point", the flip trades this bug for its mirror image and blames the token for a tab the
+    // human closed. The ordering belongs to the fact; what this branch does with it is then obvious.
+    if (facts.everConnected && true !== facts.authRefused) {
+        const listening = facts.listening;
+        const only = 1 === listening.length ? listening[0] : undefined;
+        const bound = 0 === listening.length
+            ? ''
+            : only === undefined
+                ? ` An app is already listening on ${listening.join(', ')}; just open the URL the human names — do not start a second stack.`
+                : ` An app is already listening on ${String(only)}; just open ${LOCALHOST}:${String(only)} — do not start a second stack.`;
+        return {
+            action: NoSessionAction.REOPEN_APP,
+            ...(only === undefined
+                ? {}
+                : { command: `${OPEN_COMMAND} ${LOCALHOST}:${String(only)}`, port: only }),
+            reason: 'a session was connected to this daemon earlier, so the wiring is correct — the tab was ' +
+                'closed, reloaded, or the lease aged out. Reopen the app, or take one you own with ' +
+                'reticle_lease {action:"acquire", url}.' +
+                bound,
+        };
+    }
+    const configsElsewhere = facts.configsElsewhere ?? [];
+    if (!facts.initialized && configsElsewhere.length > 0) {
+        const named = configsElsewhere
+            .map((config) => config.projectId === undefined
+            ? config.directory
+            : `${config.directory} ('${config.projectId}')`)
+            .join(', ');
+        const projectIds = configsElsewhere.flatMap((config) => config.projectId === undefined ? [] : [config.projectId]);
+        const leaseAlternative = 0 === projectIds.length
+            ? ''
+            : ' Alternatively, acquire the app URL explicitly with reticle_lease ' +
+                '{action:"acquire", url, projectId} using the matching projectId above.';
+        return {
+            action: NoSessionAction.OPEN_APP,
+            reason: `a \`.reticle.json\` was found outside this daemon's directory: ${named}. This is a ` +
+                "scope problem, not an install problem. Restart the daemon from the app's directory (or " +
+                `point it there), then open the app.${leaseAlternative}`,
+        };
+    }
+    if (0 === facts.listening.length) {
+        const dev = facts.dev;
+        if (dev === undefined) {
+            return {
+                action: NoSessionAction.START_DEV_SERVER,
+                reason: 'nothing is listening on the ports Reticle scans, so the app is probably not running — ' +
+                    'but this project declares no dev script (no `dev`, `develop` or `start` in its ' +
+                    'package.json), so there is no command to hand you. Ask the human how their app is ' +
+                    'started, and for the URL it serves on.',
+            };
+        }
+        return {
+            action: NoSessionAction.START_DEV_SERVER,
+            command: dev.command,
+            ...(dev.port === undefined ? {} : { port: dev.port }),
+            // "Probably", to match the branch above it and the paragraph beside it.
+            //
+            // The same fact was stated at two confidence levels by one function: no dev script said the
+            // app was "probably not running", and THIS branch — the one that hands over a command to run
+            // — asserted it flatly. That is the branch where being wrong costs something, because the
+            // agent then starts a SECOND dev server on a second port, which the guard below calls the
+            // exact confusion this probe exists to prevent.
+            //
+            // It also contradicted its own payload: the prose beside it says the scan is narrow, that a
+            // server on any other port is invisible to it, and that a running app should be checked for
+            // rather than assumed away. Measured on a machine with three dev servers up on ports the scan
+            // does not cover, it reported the app was not running.
+            reason: 'nothing is listening on the ports Reticle scans, so the app is probably not running — ' +
+                'though that scan is narrow, so if it IS up on another port, ask for its URL instead of ' +
+                `starting a second one. This is the project's own \`${dev.script}\` script — run it in the ` +
+                'background, tell the human it is running, then call reticle_sessions again.',
+        };
+    }
+    // Something IS up. Whatever else is true, do NOT hand back a start command: a second dev server on
+    // 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.
+    // A refusal against a project that IS initialised here. The daemon has the config, so this is not
+    // a scope problem — the page reached the right daemon and presented a credential it would not
+    // accept. The usual cause is a dev server that shares no filesystem with the daemon (Docker, a
+    // devcontainer, WSL): the build plugin reads-or-mints the pairing token from `$HOME/.reticle`,
+    // which over there is a different file, so it mints its own and every page is refused. The daemon
+    // holds every fact needed to say so, which is why the reason below says it rather than repeating
+    // `authentication failed`.
+    if (true === 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 (${ports} listening), so ` +
+                'the app IS running and instrumented and this project IS wired — the page simply presented ' +
+                'a token this daemon does not own. The usual cause is a dev server that does not share a ' +
+                'filesystem with the daemon (Docker, a devcontainer, WSL): the build plugin reads the token ' +
+                'from `$HOME/.reticle/pairing-token`, which over there is a different file, so it mints its ' +
+                "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 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) {
+        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,
+            command: INIT_COMMAND,
+            ...(only === undefined ? {} : { port: only }),
+            reason: `something is listening (${ports}) but no \`.reticle.json\` was found, so the app may ` +
+                "carry no Reticle SDK. Run this in the APP's own directory — in a monorepo that is not " +
+                'where this daemon stands — then restart the dev server.',
+        };
+    }
+    if (only === undefined) {
+        return {
+            action: NoSessionAction.OPEN_APP,
+            reason: `this project is wired and no page is open. Several ports are listening (${ports}) and ` +
+                'none of them can be attributed to this project, so open the one the human names: ' +
+                `\`${OPEN_COMMAND} <url>\`.`,
+        };
+    }
+    // Two causes sit under this branch and only one of them is fixed by opening a page.
+    //
+    // The prose diagnosis next door already ranks them and puts the stale bundle first: `init` writes
+    // the plugin into a config the RUNNING dev server has already read, so the served bundle carries
+    // no SDK and reloading it cannot ever produce a session. This function — the half an agent
+    // actually executes — used to say only "open the app", which is the answer to the OTHER cause.
+    // An agent that follows it opens a bundle with no Reticle in it, sees no session, and has been
+    // given no reason to suspect the one thing that would have worked.
+    //
+    // Named only while nothing has EVER connected. Once a session has been here the wiring is proven
+    // and sending an agent to restart a working dev server is a wild goose chase.
+    const neverConnected = true !== facts.previouslyConnected;
+    return {
+        action: NoSessionAction.OPEN_APP,
+        command: `${OPEN_COMMAND} ${LOCALHOST}:${String(only)}`,
+        port: only,
+        reason: neverConnected
+            ? 'this project is wired and a dev server is listening, but no app has ever connected to ' +
+                'this daemon — Reticle only ever sees a page a browser has LOADED, and nothing has loaded ' +
+                'one. If opening it does not produce a session, the dev server is older than the Reticle ' +
+                'plugin and its bundle carries no SDK: restart the dev server (do not rely on HMR) and ' +
+                'load the page again.'
+            : 'this project is wired and a dev server is listening — Reticle only ever sees a page a ' +
+                'browser has LOADED, and nothing has loaded one.',
+    };
+}
+/** The same action as one sentence, for the prose message the human reads. */
+export function renderNextAction(next) {
+    const command = next.command;
+    return command === undefined
+        ? `NEXT ACTION: ${next.reason}`
+        : `NEXT ACTION: run \`${command}\` — ${next.reason}`;
+}

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

@@ -0,0 +1,351 @@
+/**
+ * Keeps the "why is nothing connected" diagnosis fresh, without putting a probe on the hot path.
+ *
+ * `SessionManager.resolve` is synchronous and runs on every tool call, so it cannot await a port
+ * scan. This refreshes the answer in the background and hands the manager a closure that reads the
+ * cached result — a hint in an error message is exactly the sort of thing that may be a few seconds
+ * stale.
+ *
+ * It only probes while NOTHING is connected. Once a session is live the question is moot, and a
+ * daemon that outlives the agent by hours has no business scanning ports it does not need.
+ */
+import { probeDevServers, probeDevServerStates } from './dev-server/dev-server-probe.js';
+import { homedir } from 'node:os';
+import { registeredElsewhere } from '../../memory/recall/registered-projects.js';
+import { explainNoSession } from './no-session-diagnosis.js';
+import { detectDevCommand } from './dev-server/dev-command.js';
+import { nextActionFor, renderNextAction } from './no-session-next-action.js';
+import { readProjectFramework, readProjectId, readProjectPort, } from '../../command/cli/ports/resolve/cli-port.js';
+import { discoverProjectConfigs } from '../../command/cli/config/config-discovery.js';
+import { hasProjectConnectedBefore, rememberConnected, } from '../../memory/recall/prior/connection-memory.js';
+import { isAlive, reticleStateHome } from '../../command/daemon/daemon.js';
+import { daemonsServingProjectElsewhere, splitBrainNote } from '../../command/daemon/daemon-resolve.js';
+import { stallUptime } from './stall-clock.js';
+import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
+import { findOccupiedSiblings } from '../../command/cli/ports/sibling-ports.js';
+import { isAuthRefusalReason } from '../bridge/auth-failure-reason.js';
+/** 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. */
+const LOCALHOST = 'http://localhost';
+/**
+ * What the failure path says, always naming the reason rather than swallowing it.
+ *
+ * An auto-attach that fails silently is the same class of defect as the message it replaces: the
+ * agent is told absence and never learns that Reticle tried and could not.
+ */
+function attachFailureClause(port, reason) {
+    const collision = /EADDRINUSE|address already in use/i.test(reason);
+    return (` Reticle also tried to open ${LOCALHOST}:${String(port)} in a browser it owns and could not: ` +
+        `${reason}.` +
+        (collision
+            ? ' That is a port collision — something already holds the port this daemon needs, so the ' +
+                'browser Reticle drives could not be started. Stop the other Reticle process and retry, ' +
+                'rather than treating this as a problem with the app.'
+            : ''));
+}
+/**
+ * Start the watch. Returns a stop function; the timer is unref'd so it never holds the daemon up.
+ *
+ * Exported for the test that pins the after-boot config read below — the daemon itself starts this
+ * through `wireSessionScope`.
+ */
+export function startNoSessionWatch(options) {
+    const probe = options.probe ?? (() => probeDevServers());
+    let listening = [];
+    /**
+     * Ports that accepted a connection and then answered nothing in time.
+     *
+     * Tracked beside `listening` rather than folded into it: they are not dev servers as far as the
+     * probe knows, so they must not be spent as proof the app is up, and they are not absent either,
+     * so the diagnosis must stop telling people to start a server that is already running. A custom
+     * `options.probe` returns only the serving set, so this stays empty for injected probes.
+     */
+    let slowListeners = [];
+    let siblingListeners = [];
+    let running = false;
+    /** Ports auto-attach has already spent its one attempt on. Bounded: never a loop, never a retry. */
+    const attempted = new Set();
+    /** Set only when an attempt actually failed, so the diagnosis can say so instead of hiding it. */
+    let attachFailure;
+    const directory = options.directory ?? process.cwd();
+    // The boot answer still counts (it is what the daemon scoped its sessions with), but `.reticle.json`
+    // is routinely written by `init` AFTER this daemon started, so re-read rather than cache. See the
+    // `initialized` comment below, which this shares.
+    const isWired = () => options.initialized || readProjectId(directory) !== undefined;
+    /**
+     * Resolve the daemon's current project scope once for both halves of a sessions response.
+     *
+     * This remains a live read because `init` commonly writes the config after the daemon starts.
+     */
+    const projectScopeFacts = () => {
+        const initialized = isWired();
+        if (initialized)
+            return { initialized };
+        const discovery = discoverProjectConfigs(directory);
+        const elsewhere = discovery.found.filter((config) => config.directory !== directory);
+        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.
+    const stateDir = options.stateDir ?? reticleStateHome();
+    /**
+     * Only ever asked ABOUT A NAMED PROJECT.
+     *
+     * With no projectId the memory can still answer the weaker "has anything connected on this port",
+     * and that answer must not be spent here: a shared 4400 on a machine with several repos would
+     * then soften a genuinely-unwired directory's diagnosis on the strength of an unrelated app. That
+     * is the same over-confident claim this whole file exists to remove, pointing the other way.
+     */
+    const connectedBefore = () => hasProjectConnectedBefore(stateDir, options.port, readProjectId(directory));
+    /**
+     * The split brain, asked fresh every time like everything else here.
+     *
+     * Cheap — a directory listing of `~/.reticle` and a few small JSON reads — and only ever reached
+     * on a daemon with no session, which is the state this whole file exists for. Reading it once at
+     * boot would miss the ordinary case entirely: the app connects to the other daemon SECONDS after
+     * this one starts, which is precisely the window the agent then spends being told to start a dev
+     * server that is already running.
+     */
+    const splitBrain = () => {
+        const projectId = readProjectId(directory);
+        return splitBrainNote(options.port, daemonsServingProjectElsewhere(projectId, options.port, stateDir, isAlive, (port) => hasProjectConnectedBefore(stateDir, port, projectId)));
+    };
+    // Every path that registers a session goes through SessionManager.add, so this is the one hook
+    // that makes the bit durable. Recorded per port + projectId so a shared 4400 cannot make one
+    // project's success into evidence about another's.
+    options.sessions.setConnectionRecorder((projectId) => {
+        rememberConnected(stateDir, options.port, projectId);
+    });
+    /**
+     * Open the app ourselves when there is exactly one unambiguous candidate.
+     *
+     * AUTOMATIC, not offered — the deliberate call. Offering means a round trip and a decision by an
+     * agent that has strictly less evidence than this daemon does, on the one case where there is
+     * nothing left to decide: the project is wired, so a page WILL connect, and exactly one dev server
+     * is listening, so there is no ambiguity about which. That case is the bulk of the loss. Every
+     * other shape (several listeners, an unwired project, no listener) still returns prose, because
+     * there the daemon would be guessing and a guess that opens a browser is worse than a sentence.
+     *
+     * Bounded by construction: one attempt per port per daemon. A failure is recorded, never retried —
+     * a retry loop against a broken Chromium install would spin for the daemon's whole life.
+     */
+    const autoAttach = async (ports) => {
+        const attach = options.attach;
+        if (attach === undefined)
+            return;
+        if (1 !== ports.length)
+            return;
+        const [only] = ports;
+        if (only === undefined || attempted.has(only))
+            return;
+        if (!isWired())
+            return;
+        attempted.add(only);
+        try {
+            await attach(`${LOCALHOST}:${String(only)}`);
+        }
+        catch (error) {
+            attachFailure = attachFailureClause(only, error instanceof Error ? error.message : String(error));
+        }
+    };
+    const refresh = () => {
+        // Nothing to diagnose while a session is live, and no reason to scan.
+        if (running || options.sessions.count() > 0)
+            return;
+        running = true;
+        void (options.probe === undefined
+            ? probeDevServerStates().then((states) => {
+                slowListeners = states.slow;
+                return states.serving;
+            })
+            : probe())
+            .then(async (ports) => {
+            listening = ports;
+            siblingListeners =
+                options.occupiedSiblings !== undefined
+                    ? await options.occupiedSiblings()
+                    : options.probe === undefined
+                        ? await findOccupiedSiblings(options.port, probeDaemon)
+                        : [];
+            await autoAttach(ports);
+        })
+            .catch(() => {
+            /* a diagnostic hint must never take the daemon down */
+        })
+            .finally(() => {
+            running = false;
+        });
+    };
+    refresh();
+    const timer = setInterval(refresh, REFRESH_MS);
+    timer.unref();
+    /**
+     * Is a refusal on the pairing token the CURRENT state of the bridge?
+     *
+     * 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.
+     *
+     * Two clauses, because `lastClosure` alone answers a slightly different question than the one the
+     * diagnosis asks. It records only the closes the BRIDGE initiated, so an ordinary disconnect never
+     * reaches it: a refusal, then a good session, then a closed tab leaves it still reading
+     * `AUTH_FAILED` hours later. `connectedSinceLastClosure` is the ordering fact that tells a live
+     * refusal from a remembered one, and without it this reports a token problem for a closed tab.
+     *
+     * Called optionally because this watch is constructed against a structural slice of the manager,
+     * and several callers pass a double that predates these methods. 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 job is to SUPPRESS advice rather than to add any.
+     */
+    const lastCloseWasAuthFailure = () => isAuthRefusalReason(options.sessions.lastClosure?.()?.reason) &&
+        true !== options.sessions.connectedSinceLastClosure?.();
+    const nextAction = (scope) => {
+        const split = splitBrain();
+        return nextActionFor({
+            everConnected: options.sessions.everConnected(),
+            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
+            // daemon that cached "there is none" at boot would keep saying so for the rest of the day.
+            dev: detectDevCommand(directory),
+        });
+    };
+    options.sessions.setNoSessionNextAction(() => nextAction(projectScopeFacts()));
+    // ONE call for both registrations below. The prose and the branch code have to come from the
+    // same evaluation or they can describe different branches - the facts are read when asked, so two
+    // calls a moment apart can genuinely disagree (#615).
+    const explain = () => {
+        const scope = projectScopeFacts();
+        return explainNoSession({
+            everConnected: options.sessions.everConnected(),
+            // Read WHEN ASKED, for the same reason `projectPort` below is: `.reticle.json` is routinely
+            // written by `init` after this daemon started — that is the ordinary first-install order — and
+            // the boot-time answer is then permanently stale. Reported from the field as `reticle status`
+            // saying the project had never been through `init` about a project whose config named its
+            // framework and its projectId, and whose real problem was a dev server older than the plugin.
+            // The boot value still counts: it is the one the daemon scoped its sessions with.
+            ...scope,
+            listening,
+            slowListeners,
+            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,
+            // The one fact that outranks every absence below it, and the reason a fresh daemon stopped
+            // claiming that an install which has demonstrably worked has never worked.
+            previouslyConnected: connectedBefore(),
+            // Already read for the NEXT ACTION and, until now, not for the message — so the daemon could
+            // suppress an `init` suggestion because it knew a page had been refused, while the sentence
+            // beside it still said the tab had been closed. One fact, two answers, and only one of them
+            // was right. Read when asked, like the rest: a page can be refused at any moment.
+            authRefused: lastCloseWasAuthFailure(),
+            // Ranks the causes. Read when asked, like the rest: `init` writes this file after the daemon
+            // starts on an ordinary first install.
+            ...(() => {
+                const framework = readProjectFramework(directory);
+                return framework === undefined ? {} : { framework };
+            })(),
+            // Decided from the session that actually went away, not from a lifetime tally: the lease
+            // sentence is only right when the thing that vanished WAS a lease.
+            leaseExpired: (() => {
+                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.
+            ...(() => {
+                const upMs = stallUptime(Date.now());
+                return upMs === undefined ? {} : { daemonUpMs: upMs };
+            })(),
+            // 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(directory);
+                return configured === undefined ? {} : { projectPort: configured };
+            })(),
+            ...(0 === siblingListeners.length ? {} : { siblingListeners }),
+        });
+    };
+    // 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();
+        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);
+    };
+}
+/**
+ * The daemon's whole session-scoping decision in one call: scope auto-selection to the active
+ * project, and keep the no-session diagnosis fresh. Both derive from the same one fact — whether
+ * this directory has been through `reticle init` — so they belong together rather than as two
+ * adjacent blocks in the bootstrap.
+ */
+export function wireSessionScope(sessions, activeProjectId, port, 
+/** Asks the pool whether a session id was a lease it aged out; omitted when there is no pool. */
+wasReapedLease, 
+/** Opens a URL in a Reticle-owned browser (the pool). Omitted ⇒ auto-attach is off. */
+attach) {
+    if (activeProjectId !== undefined)
+        sessions.setDefaultScope({ projectId: activeProjectId });
+    return startNoSessionWatch({
+        sessions,
+        port,
+        initialized: activeProjectId !== undefined,
+        ...(wasReapedLease === undefined ? {} : { wasReapedLease }),
+        ...(attach === undefined ? {} : { attach }),
+    });
+}

package/dist/portal/session/output-budget.d.ts

@@ -0,0 +1,82 @@
+import { type ReticleEvent } from '@reticlehq/core';
+/**
+ * A self-budgeting hint returned on event-bearing tool results so the agent can decide whether to
+ * narrow its next call (large results are a real token tax). `bytes` is the JSON
+ * size of the payload; `droppedOldest` is present only when a cap actually truncated the timeline —
+ * never a silent cap.
+ */
+interface CostHint {
+    events: number;
+    bytes: number;
+    droppedOldest?: number;
+    /** Present when the timeline is large — tells the agent to scope its NEXT call (cut tokens). */
+    recommendation?: string;
+}
+/**
+ * Default cap for reticle_network / reticle_console when the caller passes no `limit`. Those tools
+ * default `since` to 0 (the whole session), so a long-lived or event-flooded session produced an
+ * UNBOUNDED result — a measured 1-hour flood is ~72,000 calls / ~1M tokens in a single tool result.
+ * Capping to the most-recent N (with `total`/`droppedOldest` disclosed, so nothing is hidden and the
+ * agent can page with since/until or a higher explicit limit) bounds the cost without changing the
+ * window. 200 comfortably covers a real flow's traffic while killing the pathological case.
+ */
+export declare const DEFAULT_QUERY_LIMIT = 200;
+/**
+ * Default cap for `reticle_observe`'s timeline when the caller passes no `max_events`.
+ *
+ * Without one, the whole window is returned. That is fine for a quiet page and pathological for a
+ * busy one: a page with count-up animations emits an event per frame, and a single observe result
+ * was measured at ~60KB. The sibling tools (`reticle_network`, `reticle_console`) have had a default
+ * for exactly this reason; observe was simply missed.
+ *
+ * Capping is safe for accuracy — and that is the only reason it is allowed. Contradiction detection
+ * runs over the FILTERED-BUT-UNBUDGETED window (see `observe-tools.ts`), so a finding can never
+ * disappear because the timeline was trimmed for tokens. What the cap changes is how much of the
+ * timeline is printed, never what was examined.
+ *
+ * Nothing is hidden: whenever the cap bites, `cost.droppedOldest` says how many older events fell
+ * outside it, and the caller can pass a larger `max_events` to see them.
+ */
+export declare const DEFAULT_OBSERVE_EVENT_LIMIT = 200;
+/**
+ * Trim a timeline to `maxEvents`, sacrificing noise before evidence.
+ *
+ * The obvious rule -- keep the most recent N -- is wrong here, and a live session showed why. A page
+ * emits a health heartbeat every few seconds forever, so on any idle app the most recent events are
+ * all heartbeats. A real observe call came back with 200 events and 46 KB whose own summary read:
+ * zero network, zero DOM changes, zero route changes, zero console errors, zero signals. The budget
+ * had been spent entirely on heartbeats, and the click the caller was asking about had been dropped
+ * for being older.
+ *
+ * So evidence is kept first, and `CHURN_TYPES` -- which core already defines as the high-volume,
+ * low-signal events that are "the ONLY thing that should be sacrificed when a buffer is full" -- is
+ * used to fill whatever room is left. That rule already governed buffer eviction; it governs this
+ * budget now too, so both agree on what is worth keeping.
+ *
+ * Order is preserved: the result reads oldest-first, like the timeline it came from.
+ */
+export declare function applyEventBudget(events: ReticleEvent[], maxEvents: number | undefined): {
+    events: ReticleEvent[];
+    droppedOldest: number;
+};
+/** Build a cost hint from a payload + the event count it carries. */
+export declare function costHint(payload: unknown, events: number, droppedOldest?: number): CostHint;
+export declare function estimateTokens(text: string): number;
+/**
+ * A size preview for non-event read results (snapshot, query). Same intent as CostHint but for
+ * payloads measured by size rather than event count: the agent can bail and re-scope (mode:status,
+ * a tighter scope, a more specific query) before spending context on a large body. The token
+ * figure is an estimate (see estimateTokens).
+ */
+interface SizeCost {
+    bytes: number;
+    tokens: number;
+}
+export declare function sizeCost(payload: unknown): SizeCost;
+/**
+ * Attach a `cost` size preview to a read result. Pure: the cost is computed over the result BEFORE
+ * the cost field is added (so it measures the body the agent will actually read), then merged in.
+ * Non-object results (e.g. a thrown-error envelope) pass through unchanged.
+ */
+export declare function withSizeCost<T>(result: T): T;
+export {};