@reticlehq/server 2.11.0 → 2.12.0

package/dist/session/last-act.d.ts

@@ -16,6 +16,12 @@
  */
 interface ActEffect {
     action?: string | undefined;
+    /**
+     * The ref the action dispatched against. Recorded so the verdict nudge can suggest a call about
+     * the element the agent actually touched, rather than a worked example from a document. Written
+     * on the SAME success path as `action`, so a refused act leaves neither.
+     */
+    ref?: string | undefined;
     /** DOM mutations inside the acted element's own subtree. Undefined means nobody measured. */
     mutatedWithin?: number | undefined;
 }
@@ -35,7 +41,7 @@ export declare class LastAct {
      * Marking only on the success path is what makes that unrepeatable: a failure mode added later
      * cannot forget to clean up state that was never written.
      */
-    markActed(cursor: number, action: string | undefined, mutatedWithin: number | undefined): void;
+    markActed(cursor: number, action: string | undefined, mutatedWithin: number | undefined, ref?: string): void;
     /**
      * A navigation — by URL or by reload — moves the floor without being an act.
      *

package/dist/session/last-act.js

@@ -18,9 +18,9 @@ export class LastAct {
      * Marking only on the success path is what makes that unrepeatable: a failure mode added later
      * cannot forget to clean up state that was never written.
      */
-    markActed(cursor, action, mutatedWithin) {
+    markActed(cursor, action, mutatedWithin, ref) {
         this.#cursor = cursor;
-        this.#effect = { action, mutatedWithin };
+        this.#effect = { action, mutatedWithin, ...(ref === undefined ? {} : { ref }) };
     }
     /**
      * A navigation — by URL or by reload — moves the floor without being an act.

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

@@ -3,12 +3,7 @@ import { noteEmptyRead } from '../tools/observed-nothing.js';
 import { AGENT_ASK_NOTICE, AGENT_WAITING_NOTICE, PresenterTone, SessionState, YIELD_WITHOUT_SESSION_NOTE, } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
-import { asNumber, asString } from '../tools/tools-helpers.js';
-import { waitForReady, RETICLE_LOOP_GUIDE } from './session-readiness.js';
-import { recoveryFor } from '../tools/error-recovery.js';
-/** Default + ceiling for the readiness wait — keep it short so a truly-missing app fails fast. */
-const WAIT_READY_DEFAULT_MS = 5000;
-const WAIT_READY_MAX_MS = 30000;
+import { asString } from '../tools/tools-helpers.js';
 /**
  * Is this a turn ending with nothing attached, rather than a call about a specific tab?
  *
@@ -225,42 +220,6 @@ export const LIVE_CONTROL_TOOLS = [
             return Promise.resolve(out);
         },
     },
-    {
-        name: ReticleTool.WAIT_READY,
-        description: 'Block until the app is connected, then continue — call this once right after init so your ' +
-            'first real tool call does not lose the race with the SDK connecting its WebSocket. Returns as ' +
-            'soon as a session exists (no latency if one already does), or after `timeoutMs` with a ' +
-            'recovery hint if none appears.',
-        inputSchema: {
-            timeoutMs: z
-                .number()
-                .optional()
-                .describe('How long to wait for a session (ms). Default 5000, max 30000.'),
-        },
-        outputSchema: {
-            ready: z.boolean(),
-            sessionCount: z.number(),
-            loop: z.string().optional(),
-            recovery: z.string().optional(),
-        },
-        handler: async (deps, args) => {
-            const requested = asNumber(args['timeoutMs']) ?? WAIT_READY_DEFAULT_MS;
-            const timeoutMs = Math.max(0, Math.min(requested, WAIT_READY_MAX_MS));
-            const ready = await waitForReady({
-                count: () => deps.sessions.count(),
-                timeoutMs,
-                now: deps.now,
-                sleep: (ms) => new Promise((res) => setTimeout(res, ms)),
-            });
-            // The first response a fresh agent gets — carry the loop guide so it learns how to drive Reticle.
-            if (ready)
-                return { ready: true, sessionCount: deps.sessions.count(), loop: RETICLE_LOOP_GUIDE };
-            const recovery = recoveryFor('no browser session connected');
-            return recovery !== undefined
-                ? { ready: false, sessionCount: 0, recovery }
-                : { ready: false, sessionCount: 0 };
-        },
-    },
 ];
 /**
  * The single actionable next-move for a pending mark: point the agent at the source (or the element

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

@@ -117,6 +117,16 @@ export interface NoSessionFacts {
      * install never finished" to the user-facing diagnosis rather than only to telemetry.
      */
     daemonUpMs?: number;
+    /**
+     * Well-known Reticle ports other than `port` that currently accept a connection.
+     *
+     * Remaining half of #261. We cannot see an SDK dialling a port we are not on, but we can see that
+     * a well-known Reticle port has a listener. That is an observation: somebody else's daemon, another
+     * project, and an unrelated process all look the same from here. The sentence that reports it
+     * names the ports and refuses the conclusion. Absent or empty means nothing else was listening,
+     * which is the common case and must not gain a paragraph.
+     */
+    siblingListeners?: readonly number[];
 }
 /**
  * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session

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

@@ -20,6 +20,7 @@
  */
 import { leaseCaveat } from './lease-availability.js';
 import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
+import { siblingListenerNote } from '../cli/sibling-ports.js';
 import { STALL_AFTER_MS } from './stall-clock.js';
 /** The one framework whose most likely cause differs from every other framework's. */
 const NUXT = 'nuxt';
@@ -217,6 +218,24 @@ function portMismatchClause(facts) {
         ` Either restart the daemon on ${String(configured)}, or update \`.reticle.json\` to` +
         ` ${String(facts.port)} and restart the dev server so the app picks it up.`);
 }
+/**
+ * A listener on a well-known Reticle port we did not bind. Observation, not a cause.
+ *
+ * Leading space so the caller can concatenate it unconditionally. Empty when there is nothing to
+ * say, including when the occupied sibling is already the configured-port mismatch — that sentence
+ * already named both numbers, and repeating 4460 as a second "cause" would overclaim.
+ */
+function siblingListenerClause(facts) {
+    const occupied = facts.siblingListeners ?? [];
+    if (0 === occupied.length)
+        return '';
+    const mismatch = facts.projectPort;
+    const extra = mismatch !== undefined && mismatch !== facts.port
+        ? occupied.filter((port) => port !== mismatch)
+        : occupied;
+    const note = siblingListenerNote(facts.port, extra);
+    return note === undefined ? '' : ` ${note}`;
+}
 /**
  * The tail every "the app is wired and silent" branch ends with, ranked.
  *
@@ -228,7 +247,7 @@ function rankedCauses(facts) {
     const nuxt = facts.framework?.toLowerCase() === NUXT ? `${NUXT_STALE_BUNDLE} ` : '';
     return (`${nuxt}${REAL_CAUSES} If none of those, the app may be dialling a different daemon than this ` +
         `one (on ${String(facts.port)}): check the app's reticle port matches ` +
-        `${String(facts.port)}.${portMismatchClause(facts)} ${NON_LOCALHOST_GATE}`);
+        `${String(facts.port)}.${portMismatchClause(facts)}${siblingListenerClause(facts)} ${NON_LOCALHOST_GATE}`);
 }
 /**
  * The scope answer, when the config was somewhere else all along.
@@ -353,7 +372,7 @@ export function diagnoseNoSession(facts) {
                 `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)} ${leaseAdvice(URL_THEN_LEASE, facts)} ${RETRY}`);
+                `carries the SDK without that file at all.${searchedClause(facts)}${siblingListenerClause(facts)} ${leaseAdvice(URL_THEN_LEASE, facts)} ${RETRY}`);
         }
         return (`${stallClause(facts)}no browser session connected, and this daemon has never seen one. ${OPEN_THE_APP} ` +
             'Nothing is listening on the ports Reticle scans ' +
@@ -371,10 +390,8 @@ export function diagnoseNoSession(facts) {
             // 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)} ` +
-            // Reachable only for a project that HAS been through `init` — the uninstrumented case is
-            // answered above, leading with that certainty instead of behind this scan's guess.
-            `${RETRY}`);
+            `the app IS running, ask the human for its URL rather than assuming it is down. ${leaseAdvice(URL_THEN_LEASE, facts)}` +
+            `${siblingListenerClause(facts)} ${RETRY}`);
     }
     if (!initialized) {
         return ('no browser session connected, and this daemon has never seen one. ' +
@@ -384,7 +401,7 @@ export function diagnoseNoSession(facts) {
             "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)} ${RETRY}`);
+            `${unattributedListeners(listening)}${searchedClause(facts)}${siblingListenerClause(facts)} ${RETRY}`);
     }
     return (`${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)} ` +

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

@@ -29,6 +29,11 @@ interface NextActionFacts {
     initialized: boolean;
     listening: readonly number[];
     dev: DevCommand | undefined;
+    /** Configs found in other workspace directories: positive evidence of a scope mismatch. */
+    configsElsewhere?: readonly {
+        directory: string;
+        projectId?: string;
+    }[];
     /**
      * An app for this project has connected on this port before, from durable state.
      *

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

@@ -26,6 +26,25 @@ export function nextActionFor(facts) {
                 'reticle_lease {action:"acquire", url}.',
         };
     }
+    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) {
@@ -41,9 +60,22 @@ export function nextActionFor(facts) {
             action: NoSessionAction.START_DEV_SERVER,
             command: dev.command,
             ...(dev.port === undefined ? {} : { port: dev.port }),
-            reason: 'nothing is listening on the ports Reticle scans, so the app is not running. 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.',
+            // "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

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

@@ -18,6 +18,14 @@ interface NoSessionWatchOptions {
     /** Where that was decided — this daemon's working directory unless a caller says otherwise. */
     directory?: string;
     probe?: () => Promise<number[]>;
+    /**
+     * Well-known Reticle ports other than ours that currently accept a connection.
+     *
+     * Remaining half of #261. Injected so tests can pin the observation without opening a socket.
+     * Production (no `probe` override) probes those ports itself. A test that injects `probe` and
+     * omits this is opting out: it owns the scan.
+     */
+    occupiedSiblings?: () => Promise<readonly number[]>;
     /**
      * How many pooled leases have aged out, if a pool exists. Injected as a reader rather than the
      * pool itself: the diagnosis needs one number, and taking the whole pool would tie the session

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

@@ -18,6 +18,8 @@ import { discoverProjectConfigs } from '../cli/config-discovery.js';
 import { hasProjectConnectedBefore, rememberConnected } from './connection-memory.js';
 import { reticleStateHome } from '../daemon/daemon.js';
 import { stallUptime } from './stall-clock.js';
+import { probeDaemon } from '../mcp/mcp-proxy.js';
+import { findOccupiedSiblings } from '../cli/sibling-ports.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. */
@@ -56,6 +58,7 @@ export function startNoSessionWatch(options) {
      * `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();
@@ -66,6 +69,27 @@ export function startNoSessionWatch(options) {
     // 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);
+        return 0 === elsewhere.length
+            ? { initialized, searchedDirectories: discovery.searched }
+            : {
+                initialized,
+                configsElsewhere: elsewhere.map((config) => ({
+                    directory: config.directory,
+                    ...(config.projectId === undefined ? {} : { projectId: config.projectId }),
+                })),
+            };
+    };
     // 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();
@@ -129,6 +153,12 @@ export function startNoSessionWatch(options) {
             : 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(() => {
@@ -141,77 +171,65 @@ export function startNoSessionWatch(options) {
     refresh();
     const timer = setInterval(refresh, REFRESH_MS);
     timer.unref();
-    const nextAction = () => nextActionFor({
+    const nextAction = (scope) => nextActionFor({
         everConnected: options.sessions.everConnected(),
-        initialized: isWired(),
+        initialized: scope.initialized,
+        ...(scope.configsElsewhere === undefined ? {} : { configsElsewhere: scope.configsElsewhere }),
         previouslyConnected: connectedBefore(),
         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);
-    options.sessions.setNoSessionHint(() => diagnoseNoSession({
-        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.
-        initialized: isWired(),
-        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,
-        // Where the config actually is, when it is not here — and where we looked, when it is
-        // nowhere. Computed only on the branch that needs it: a wired daemon has its answer already,
-        // and a workspace scan on every hint would be a directory walk per tool refusal.
-        ...(isWired()
-            ? {}
-            : (() => {
-                const discovery = discoverProjectConfigs(directory);
-                const elsewhere = discovery.found.filter((c) => c.directory !== directory);
-                return 0 === elsewhere.length
-                    ? { searchedDirectories: discovery.searched }
-                    : {
-                        configsElsewhere: elsewhere.map((c) => ({
-                            directory: c.directory,
-                            ...(c.projectId === undefined ? {} : { projectId: c.projectId }),
-                        })),
-                    };
-            })()),
-        // 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 };
-        })(),
-        leaseExpired: (options.reapedLeases?.() ?? 0) > 0,
-        // 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 };
-        })(),
-    }) +
-        // Prose for the human, then the literal command for the agent. Appended rather than folded
-        // into the diagnosis so that file stays pure and its cases stay independently pinned.
-        ` ${renderNextAction(nextAction())}` +
-        (attachFailure ?? ''));
+    options.sessions.setNoSessionNextAction(() => nextAction(projectScopeFacts()));
+    options.sessions.setNoSessionHint(() => {
+        const scope = projectScopeFacts();
+        return (diagnoseNoSession({
+            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 };
+            })(),
+            leaseExpired: (options.reapedLeases?.() ?? 0) > 0,
+            // 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 }),
+        }) +
+            // 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 ?? ''));
+    });
     return () => {
         clearInterval(timer);
         options.sessions.setConnectionRecorder(undefined);

package/dist/session/output-budget.js

@@ -50,7 +50,10 @@ export function estimateTokens(text) {
 }
 export function sizeCost(payload) {
     const json = JSON.stringify(payload) ?? '';
-    return { bytes: json.length, tokens: estimateTokens(json) };
+    // Actual UTF-8 wire bytes, not json.length (UTF-16 code units) — the field is labeled `bytes`
+    // and drives the large-snapshot recommendation, so a multibyte-heavy payload was under-counted.
+    const bytes = Buffer.byteLength(json, 'utf8');
+    return { bytes, tokens: estimateTokens(json) };
 }
 /**
  * Attach a `cost` size preview to a read result. Pure: the cost is computed over the result BEFORE

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

@@ -45,6 +45,15 @@ export declare function healthEnvelope(session: Session): HealthEnvelope;
  * warn-only so background testing never breaks.
  */
 export declare function refuseIfThrottled(session: Session, refuse: unknown): void;
+/**
+ * Suffix the starvation note onto a FAILED predicate verdict when the tab is throttled. A pass is
+ * returned untouched — starvation is context for a failure, not a reason to doubt a hold. Pure and
+ * generic over the verdict shape so assert/wait_for/act_and_wait share one rule.
+ */
+export declare function annotateStarvedFailure<V extends {
+    pass?: boolean;
+    failureReason?: string;
+}>(session: Session, verdict: V): V;
 /** The page's own visibility/runtime report, narrowed out of an untrusted PAGE_HEALTH payload. */
 interface HealthReport {
     hidden: boolean | undefined;

package/dist/session/session-health.js

@@ -35,6 +35,29 @@ export function refuseIfThrottled(session, refuse) {
         throw new Error(`refusing to act: ${THROTTLED_WARNING}`);
     }
 }
+/**
+ * The sentence appended to a FAILED predicate verdict waited out on a throttled tab.
+ *
+ * A starved tab and a missing element read identically as a bare near-miss: after a hard reload a
+ * backgrounded tab can sit on its loading state forever (hydration starved, nothing painted), and
+ * `wait_for { text }` timing out there looks exactly like "the code did not render" (#521). The
+ * health envelope already rode alongside saying `throttled:true`, but nothing connected it to the
+ * verdict an agent actually gates on. Appended, not replacing: the original diagnosis still leads,
+ * and on a healthy tab the failure says exactly what it always said.
+ */
+const STARVED_WAIT_NOTE = ' (the tab was throttled during this wait, so starvation can look exactly like absence: bring it to the front and re-check before concluding this is genuinely missing)';
+/**
+ * Suffix the starvation note onto a FAILED predicate verdict when the tab is throttled. A pass is
+ * returned untouched — starvation is context for a failure, not a reason to doubt a hold. Pure and
+ * generic over the verdict shape so assert/wait_for/act_and_wait share one rule.
+ */
+export function annotateStarvedFailure(session, verdict) {
+    if (true === verdict.pass || verdict.failureReason === undefined)
+        return verdict;
+    if (true !== session.throttled())
+        return verdict;
+    return { ...verdict, failureReason: `${verdict.failureReason}${STARVED_WAIT_NOTE}` };
+}
 /**
  * Narrow a PAGE_HEALTH payload. Every field is optional on the wire — an older SDK does not report
  * `runtime` at all — so each is returned as undefined rather than defaulted here, letting the caller

package/dist/session/session-manager.js

@@ -2,6 +2,7 @@ import { NO_SESSION_CONNECTED_ERROR } from '@reticlehq/core';
 import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input/driven-redaction.js';
 import { Session } from './session.js';
 import { AttachmentHistory } from './attachment-history.js';
+import { pickDocumentSuccessor } from './session-successor.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)
@@ -61,6 +62,14 @@ function scopeMissError(connected, scope) {
  */
 /** How many bridge-initiated closes to remember for diagnosis. */
 const MAX_REMEMBERED_CLOSURES = 5;
+/**
+ * How many recently-departed session ids to remember for successor rebind.
+ *
+ * A full-document navigation HELLO's back under a new id while the agent still holds the old one.
+ * The tombstone is how `resolve(oldId)` finds the unique same-origin successor instead of refusing.
+ * Bounded so a long-lived daemon cannot accumulate one record per tab forever.
+ */
+const MAX_TOMBSTONES = 32;
 export class SessionManager {
     #sessions = new Map();
     /**
@@ -69,6 +78,13 @@ export class SessionManager {
      * Owned here because this is the one place that sees both halves — every add and every remove.
      */
     #attachment = new AttachmentHistory();
+    /**
+     * Recently departed sessions, keyed by the id the agent still holds.
+     *
+     * Insertion order is LRU: the oldest is dropped when the cap is hit. A reconnect under the same
+     * id forgets its tombstone — the live session is the answer then.
+     */
+    #tombstones = new Map();
     /**
      * The active project's scope, set once from the daemon's .reticle.json. When a tool resolves a session
      * without passing its own scope, this is applied — so auto-selection is project-scoped by default
@@ -100,6 +116,7 @@ export class SessionManager {
         // that silently fails to register is a leak nothing would report.
         declareDrivenRedactionKeys(session.id, session.redactKeys);
         this.#attachment.attached(session.id);
+        this.#tombstones.delete(session.id);
         return previous;
     }
     remove(session) {
@@ -110,8 +127,40 @@ export class SessionManager {
         // Recorded, not forgotten: a session that comes back needs its gap measured, and a listing after
         // the reconnect is exactly where that matters.
         this.#attachment.detached(session.id);
+        this.#rememberTombstone(session);
         return this.#sessions.delete(session.id);
     }
+    #rememberTombstone(session) {
+        const origin = originOf(session.url);
+        if (origin === undefined)
+            return;
+        if (this.#tombstones.has(session.id))
+            this.#tombstones.delete(session.id);
+        this.#tombstones.set(session.id, {
+            id: session.id,
+            url: session.url,
+            ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
+        });
+        while (this.#tombstones.size > MAX_TOMBSTONES) {
+            const oldest = this.#tombstones.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#tombstones.delete(oldest);
+        }
+    }
+    #successorOf(sessionId) {
+        const departed = this.#tombstones.get(sessionId);
+        if (departed === undefined)
+            return undefined;
+        const picked = pickDocumentSuccessor(this.all().map((s) => ({
+            id: s.id,
+            url: s.url,
+            ...(s.projectId === undefined ? {} : { projectId: s.projectId }),
+        })), departed);
+        if (picked === undefined)
+            return undefined;
+        return this.#sessions.get(picked.id);
+    }
     get(sessionId) {
         return this.#sessions.get(sessionId);
     }
@@ -239,7 +288,7 @@ export class SessionManager {
     }
     resolve(sessionId, scope) {
         if (sessionId !== undefined) {
-            const found = this.#sessions.get(sessionId);
+            const found = this.#sessions.get(sessionId) ?? this.#successorOf(sessionId);
             if (found === undefined) {
                 throw new Error(this.#unknownSessionError(sessionId));
             }