@reticlehq/server 2.14.0 → 3.2.0

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

@@ -1,174 +0,0 @@
-/**
- * "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 } 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 };
-    }
-    if (facts.everConnected) {
-        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.
-    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/session/no-session-watch.js

@@ -1,335 +0,0 @@
-/**
- * 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-probe.js';
-import { homedir } from 'node:os';
-import { registeredElsewhere } from './registered-projects.js';
-import { explainNoSession } from './no-session-diagnosis.js';
-import { detectDevCommand } from './dev-command.js';
-import { nextActionFor, renderNextAction } from './no-session-next-action.js';
-import { readProjectFramework, readProjectId, readProjectPort } from '../cli/cli-port.js';
-import { discoverProjectConfigs } from '../cli/config-discovery.js';
-import { hasProjectConnectedBefore, rememberConnected } from './connection-memory.js';
-import { isAlive, reticleStateHome } from '../daemon/daemon.js';
-import { daemonsServingProjectElsewhere, splitBrainNote } from '../daemon/daemon-resolve.js';
-import { stallUptime } from './stall-clock.js';
-import { probeDaemon } from '../mcp/mcp-proxy.js';
-import { findOccupiedSiblings } from '../cli/sibling-ports.js';
-import { WS_CLOSE_REASON } from '../bridge/bridge.js';
-/** Slow enough to be free, fast enough that a dev server started 15s ago is already reflected. */
-const REFRESH_MS = 15_000;
-/** The URL an auto-attach opens. `localhost` for the same reason the probe uses it: both stacks. */
-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();
-    /**
-     * Did the most recent bridge-initiated close refuse a page on its token?
-     *
-     * The bridge records it (`noteClosure(WS_CLOSE_REASON.AUTH_FAILED)`) and nothing read it as a
-     * DIAGNOSIS. It is the one fact that proves an app is running and instrumented: only an SDK dials
-     * the bridge, so a refused hello means the wiring works and this daemon would not serve it.
-     *
-     * Called optionally because this watch is constructed against a structural slice of the manager,
-     * and several callers pass a double that predates `lastClosure`. A manager that cannot answer has
-     * recorded no refusal, which falls through to the behaviour that was there before -- the safe
-     * direction for a fact whose only job is to SUPPRESS an `init` suggestion.
-     */
-    const lastCloseWasAuthFailure = () => options.sessions.lastClosure?.()?.reason === WS_CLOSE_REASON.AUTH_FAILED;
-    const nextAction = (scope) => {
-        const split = splitBrain();
-        return nextActionFor({
-            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(),
-            // 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 }),
-        });
-    };
-    options.sessions.setNoSessionHint(() => {
-        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 ?? ''));
-    });
-    options.sessions.setNoSessionReason(() => explain().reason);
-    return () => {
-        clearInterval(timer);
-        options.sessions.setConnectionRecorder(undefined);
-        options.sessions.setNoSessionHint(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/session/observed-state.d.ts

@@ -1,60 +0,0 @@
-import { type ReticleEvent } from '@reticlehq/core';
-import { type AmbientCounts } from '../journal/ambient.js';
-/**
- * The two things a session learns by watching its own event stream, as opposed to storing.
- *
- * Both are LEVELS derived from a stream, and both have to outlive the ring buffer — which is what
- * separates them from the buffer's job and earns them their own unit:
- *
- *   ambient    — which regions of the page move on their own (chat, tickers, live counters). Used by
- *                the settle oracle to ignore background motion, so an action isn't held open forever
- *                by churn it did not cause.
- *   blindSpots — how much of the page the SDK cannot observe (cross-origin frames, closed shadow
- *                roots). The SDK reports these only when the count CHANGES, so a page that mounts
- *                two frames at load announces them once and is silent forever after. Anything that
- *                infers coverage from a window of events therefore sees nothing and concludes the
- *                page was fully observed — a positive claim to have seen what we cannot see. Holding
- *                the level here makes coverage something to ask rather than infer.
- */
-export declare class ObservedState {
-    #private;
-    /** Fold one already-attributed event into the learned state. */
-    observe(event: ReticleEvent): void;
-    /**
-     * Learned ambient-churn counts — seeded history PLUS this session — for the settle oracle, which
-     * wants the sharpest available picture of what moves on its own.
-     */
-    ambientCounts(): AmbientCounts;
-    /**
-     * ONLY what this session observed — the correct input to persistence.
-     *
-     * Teardown accumulates by adding the session's counts onto the file it loaded. When the session's
-     * counts still contained the seeded ones, that addition wrote `2 x persisted + own` every run, so
-     * the map doubled per session: the file committed in this repo had reached ~9.1e23 (about 2^80,
-     * i.e. ~80 sessions of doubling). Keeping the seed separate makes the accumulation what it always
-     * claimed to be — history plus what is new.
-     */
-    ownAmbientCounts(): AmbientCounts;
-    /**
-     * Seed from the persisted per-app map so the picture sharpens across sessions.
-     * In-session counts win: they describe this page as it is now.
-     */
-    seedAmbient(counts: AmbientCounts): void;
-    /** Record a driven ref. Idempotent. */
-    recordActedRef(ref: string): void;
-    /** Record a driven control's re-render-surviving label. Idempotent; empty labels are not identities. */
-    recordActedLabel(label: string): void;
-    /** Every ref driven so far this session. */
-    actedRefs(): ReadonlySet<string>;
-    /** Every driven control's label, for matching across re-renders. */
-    actedLabels(): ReadonlySet<string>;
-    /**
-     * Record bridge-side sampling as a blind spot.
-     *
-     * Every other blind spot is reported BY the SDK, which cannot report this one: the events were
-     * dropped before they reached the observer. Recording it here keeps the honesty contract intact —
-     * a verdict over a sampled window says `coverage: partial` rather than implying it saw everything.
-     */
-    noteRateLimited(dropped: number): void;
-    blindSpots(): Readonly<Record<string, number>>;
-}