@reticlehq/server 3.8.2 → 3.10.0

package/dist/portal/session/serving-directory.d.ts

@@ -37,6 +37,16 @@ export interface DevProxy {
  * only: a remote page's port says nothing about any process on this machine.
  */
 export declare function servingDirectoryOf(origin: string, io?: ServingDirectoryIo): string | undefined;
+/** How many ports one scan asks about. Each lookup blocks the daemon for two `lsof` runs. */
+export declare const MAX_FOLDER_LOOKUPS = 16;
+/**
+ * The folder of each port in `ports`, or undefined when it cannot be read.
+ *
+ * `known` is the last scan's answer. A port that stays open keeps it, so a machine with many
+ * listeners pays once. A port past the bound waits for the next scan. A closed port leaves the map,
+ * so the next process on it is asked about.
+ */
+export declare function listenerFolders(ports: readonly number[], known: ReadonlyMap<number, string | undefined>, directoryOf: (port: number) => string | undefined): Map<number, string | undefined>;
 /**
  * The live answers for a worktree-scoped resolve: the calling agent's checkout (from the directory
  * its MCP proxy runs in) and each tab's checkout (from the dev server that served it).

package/dist/portal/session/serving-directory.js

@@ -40,13 +40,15 @@ function readOrUndefined(path) {
 function readPortless() {
     const dir = process.env[PORTLESS_STATE_DIR_ENV] ?? join(homedir(), PORTLESS_STATE_DIR);
     const port = Number(readOrUndefined(join(dir, PORTLESS_PORT_FILE))?.trim());
-    if (!Number.isInteger(port))
+    if (!Number.isInteger(port)) {
         return undefined;
+    }
     let routes = [];
     try {
         const parsed = PortlessRoutesSchema.safeParse(JSON.parse(readOrUndefined(join(dir, PORTLESS_ROUTES_FILE)) ?? '[]'));
-        if (parsed.success)
+        if (parsed.success) {
             routes = parsed.data;
+        }
     }
     catch {
         // A table being rewritten reads as empty: the page stays unplaced, never placed wrong.
@@ -75,27 +77,55 @@ export function servingDirectoryOf(origin, io = liveIo) {
     catch {
         return undefined;
     }
-    if (!isLoopbackHostname(url.hostname) && !isLocalhostSubdomain(url.hostname))
+    if (!isLoopbackHostname(url.hostname) && !isLocalhostSubdomain(url.hostname)) {
         return undefined;
+    }
     // Exact first: a dev proxy serves every worktree on one port, under the name it announced.
     const byUrl = io.devServers().find((entry) => originOf(entry.url) === url.origin);
-    if (byUrl !== undefined)
+    if (byUrl !== undefined) {
         return byUrl.root;
+    }
     const pagePort = '' === url.port ? DEFAULT_PORT[url.protocol] : Number(url.port);
-    if (pagePort === undefined)
+    if (pagePort === undefined) {
         return undefined;
+    }
     // Behind a dev proxy the page's port is the proxy's, and `lsof` on it names the proxy's folder.
     // The proxy's route table names the dev server's own port.
     const proxy = isLocalhostSubdomain(url.hostname) ? io.devProxy?.() : undefined;
     const route = proxy?.routes.find((r) => r.hostname === url.hostname.toLowerCase());
-    if (route === undefined && true === proxy?.ports.includes(pagePort))
+    if (route === undefined && true === proxy?.ports.includes(pagePort)) {
         return undefined;
+    }
     const port = route?.port ?? pagePort;
     const announced = io.devServers().find((entry) => entry.port === port);
-    if (announced !== undefined)
+    if (announced !== undefined) {
         return announced.root;
+    }
     return io.listenerCwd(port) ?? undefined;
 }
+/** How many ports one scan asks about. Each lookup blocks the daemon for two `lsof` runs. */
+export const MAX_FOLDER_LOOKUPS = 16;
+/**
+ * The folder of each port in `ports`, or undefined when it cannot be read.
+ *
+ * `known` is the last scan's answer. A port that stays open keeps it, so a machine with many
+ * listeners pays once. A port past the bound waits for the next scan. A closed port leaves the map,
+ * so the next process on it is asked about.
+ */
+export function listenerFolders(ports, known, directoryOf) {
+    const folders = new Map();
+    let lookups = 0;
+    for (const port of ports) {
+        if (known.has(port)) {
+            folders.set(port, known.get(port));
+        }
+        else if (lookups < MAX_FOLDER_LOOKUPS) {
+            lookups += 1;
+            folders.set(port, directoryOf(port));
+        }
+    }
+    return folders;
+}
 /** The checkout whose dev server serves `origin` right now, or undefined. */
 function checkoutServing(origin) {
     const serving = servingDirectoryOf(origin);
@@ -122,8 +152,9 @@ export function liveCheckoutSource(placeOrigin = checkoutServing) {
                 : undefined;
         },
         ofTab: (tab) => {
-            if (placed.has(tab))
+            if (placed.has(tab)) {
                 return placed.get(tab);
+            }
             const origin = originOf(tab.url);
             const checkout = origin === undefined ? undefined : placeOrigin(origin);
             placed.set(tab, checkout);

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

@@ -64,6 +64,8 @@ export declare class SessionManager {
     isParked(sessionId: string): boolean;
     remove(session: Session): boolean;
     get(sessionId: string): Session | undefined;
+    /** The id the same tab connected as after this session's page went away, if one has. */
+    successorId(sessionId: string): string | undefined;
     /**
      * Did this id belong to a session that has since disconnected?
      *
@@ -149,6 +151,14 @@ export declare class SessionManager {
     /** Every departed session's URL, oldest first. The port scan has to see all of them, not only the newest. */
     tombstoneUrls(): readonly string[];
     resolve(sessionId?: string, scope?: ResolveScope): Session;
+    /**
+     * Resolve the session for a call that only some sessions can serve.
+     *
+     * With no sessionId, resolve() chooses by health and recency alone. A lease that could resize the
+     * page lost to a focused tab that could not, and the call was refused (#1959). Here, when exactly
+     * one candidate can serve the call, that candidate is chosen.
+     */
+    resolveServing(sessionId: string | undefined, canServe: (session: Session) => boolean | Promise<boolean>): Promise<Session>;
 }
 export interface Tab {
     id: string;

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

@@ -1,4 +1,4 @@
-import { NO_SESSION_CONNECTED_ERROR, originOf, samePath } from '@reticlehq/core';
+import { NO_SESSION_CONNECTED_ERROR, NO_SESSION_NAVIGATE_FIX, originOf, samePath, } from '@reticlehq/core';
 import { notePendingNoSessionReason } from '../../telemetry/tool-refused.js';
 import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input/driven-redaction.js';
 import { Session } from './session.js';
@@ -6,6 +6,7 @@ import { AttachmentHistory } from './presence/attachment-history.js';
 import { claimedSessionOf, openedBeforeDeparture, pickDocumentSuccessor, } from './session-successor.js';
 import { SESSION_DISCONNECTED_REASON, SESSION_PARKED_REASON } from './facts/session-replaced.js';
 import { isErrorDocument } from './session-info.js';
+import { carryOnNewDocument, departedNetworkOf, } from './facts/departed-network.js';
 /** Core's `originOf`, re-exported for this module's existing importers. */
 export { originOf };
 /**
@@ -14,8 +15,9 @@ export { originOf };
  * no scope, return the list unchanged (legacy single-/multi-session behavior).
  */
 function scopeSessions(sessions, scope) {
-    if (scope === undefined)
+    if (scope === undefined) {
         return sessions;
+    }
     if (scope.projectId !== undefined) {
         return sessions.filter((s) => s.projectId === scope.projectId);
     }
@@ -36,18 +38,10 @@ function scopeSessions(sessions, scope) {
  * target it: both facts are already in hand here.
  */
 export function scopeMissError(connected, scope) {
-    const who = scope?.projectId !== undefined
-        ? `project '${scope.projectId}'`
-        : scope?.url !== undefined
-            ? `your app at ${scope.url}`
-            : 'the active project';
+    const who = scopeName(scope);
     const anyUntagged = connected.some((s) => s.projectId === undefined);
     const anyTagged = connected.some((s) => s.projectId !== undefined);
-    const how = anyUntagged && !anyTagged
-        ? 'with no projectId'
-        : anyUntagged && anyTagged
-            ? 'under a different project or with no projectId'
-            : 'under a different project';
+    const how = whereConnected(anyUntagged, anyTagged);
     const listed = connected
         .map((s) => s.projectId !== undefined
         ? `'${s.projectId}' (${s.url}, sessionId '${s.id}')`
@@ -61,6 +55,48 @@ export function scopeMissError(connected, scope) {
         `${listed}. The daemon scopes to the .reticle.json of the directory it was started in, so ` +
         `this is a scope mismatch, not a dead app. ${advice}`);
 }
+/** What the scope names, in the words of the refusal. */
+function scopeName(scope) {
+    if (scope?.projectId !== undefined) {
+        return `project '${scope.projectId}'`;
+    }
+    if (scope?.url !== undefined) {
+        return `your app at ${scope.url}`;
+    }
+    return 'the active project';
+}
+/** Where the connected sessions are, given which of them carry a projectId. */
+function whereConnected(anyUntagged, anyTagged) {
+    if (!anyUntagged) {
+        return 'under a different project';
+    }
+    if (!anyTagged) {
+        return 'with no projectId';
+    }
+    return 'under a different project or with no projectId';
+}
+/**
+ * A session's rank for auto-selection: lower is better.
+ *
+ * 0 = non-throttled (visible + recently-heard), 1 = throttled (hidden or stale heartbeat),
+ * 2 = an error document, 3 = attached but not answering commands. A wedged tab keeps streaming
+ * events, so recency RATES IT HIGHEST — it was beating a healthy sibling on the one signal scoring
+ * looked at, and every call auto-targeted the one tab guaranteed to time out. An error document (a
+ * dev server's 404 that still mounted the SDK) ranks below any working page, hidden or not: it is
+ * never the app the agent was asked about.
+ */
+function rankOf(session) {
+    if (session.unresponsive()) {
+        return 3;
+    }
+    if (isErrorDocument(session.page)) {
+        return 2;
+    }
+    if (session.throttled()) {
+        return 1;
+    }
+    return 0;
+}
 /**
  * Owns the set of connected browser sessions and the smart auto-selection that resolves which one a
  * tool targets when the agent omits an explicit sessionId. Extracted from session.ts so each file
@@ -95,6 +131,11 @@ export class SessionManager {
     #tombstones = new Map();
     /** The tabs already open when each tombstoned session departed: siblings, never its successor. */
     #siblingsAtDeparture = new Map();
+    /**
+     * The network record each departed document made after the agent's last act, kept until the same
+     * tab's next document connects (#1944). Bounded with the tombstones. See departed-network.ts.
+     */
+    #departedNetwork = 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
@@ -124,8 +165,9 @@ export class SessionManager {
     }
     add(session) {
         this.#everConnected = true;
-        if (session.projectId !== undefined)
+        if (session.projectId !== undefined) {
             this.#connectedProjects.add(session.projectId);
+        }
         // Ordering, not lifetime: this is what makes a remembered refusal distinguishable from a live
         // one. Here for the same reason `#everConnected` is — `add` is the one method every path that
         // registers a session goes through.
@@ -143,10 +185,24 @@ 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.#carryDepartedNetwork(session, previous);
         this.#tombstones.delete(session.id);
         this.#siblingsAtDeparture.delete(session.id);
         return previous;
     }
+    /**
+     * Give a new document the requests its tab's previous document made after the last act (#1944).
+     * `previous` is that document when its socket has not closed yet; else the record kept at removal.
+     */
+    #carryDepartedNetwork(session, previous) {
+        const departed = previous !== undefined && previous !== session
+            ? departedNetworkOf(previous)
+            : this.#departedNetwork.get(session.id);
+        this.#departedNetwork.delete(session.id);
+        if (departed !== undefined) {
+            carryOnNewDocument(session, departed);
+        }
+    }
     /**
      * The other tabs of the same app as `driven`.
      *
@@ -171,28 +227,39 @@ export class SessionManager {
         session.disconnect(SESSION_PARKED_REASON);
         this.remove(session);
         this.#tombstones.delete(session.id);
+        this.#departedNetwork.delete(session.id);
     }
     isParked(sessionId) {
         return this.#parked.has(sessionId);
     }
     #parked = new Set();
     remove(session) {
-        if (this.#sessions.get(session.id) !== session)
+        if (this.#sessions.get(session.id) !== session) {
             return false;
+        }
         session.rejectAll(SESSION_DISCONNECTED_REASON);
         forgetDrivenRedactionKeys(session.id);
         // Recorded, not forgotten: a session that comes back needs its gap measured, and a listing after
         // the reconnect is exactly where that matters.
         this.#attachment.detached(session.id);
         this.#rememberTombstone(session);
+        // Kept only beside a tombstone, so the tombstone cap bounds it too.
+        const departedNetwork = this.#tombstones.has(session.id)
+            ? departedNetworkOf(session)
+            : undefined;
+        if (departedNetwork !== undefined) {
+            this.#departedNetwork.set(session.id, departedNetwork);
+        }
         return this.#sessions.delete(session.id);
     }
     #rememberTombstone(session) {
         const origin = originOf(session.url);
-        if (origin === undefined)
+        if (origin === undefined) {
             return;
-        if (this.#tombstones.has(session.id))
+        }
+        if (this.#tombstones.has(session.id)) {
             this.#tombstones.delete(session.id);
+        }
         this.#siblingsAtDeparture.set(session.id, new Set([...this.#sessions.values()]
             .filter((s) => s !== session && openedBeforeDeparture(s, session))
             .map((s) => s.id)));
@@ -206,16 +273,19 @@ export class SessionManager {
         });
         while (this.#tombstones.size > MAX_TOMBSTONES) {
             const oldest = this.#tombstones.keys().next().value;
-            if (oldest === undefined)
+            if (oldest === undefined) {
                 break;
+            }
             this.#tombstones.delete(oldest);
             this.#siblingsAtDeparture.delete(oldest);
+            this.#departedNetwork.delete(oldest);
         }
     }
     #successorOf(sessionId) {
         const departed = this.#tombstones.get(sessionId);
-        if (departed === undefined)
+        if (departed === undefined) {
             return undefined;
+        }
         const siblings = this.#siblingsAtDeparture.get(sessionId);
         const picked = pickDocumentSuccessor(this.all()
             .filter((s) => true !== siblings?.has(s.id))
@@ -224,13 +294,18 @@ export class SessionManager {
             url: s.url,
             ...(s.projectId === undefined ? {} : { projectId: s.projectId }),
         })), departed);
-        if (picked === undefined)
+        if (picked === undefined) {
             return undefined;
+        }
         return this.#sessions.get(picked.id);
     }
     get(sessionId) {
         return this.#sessions.get(sessionId);
     }
+    /** The id the same tab connected as after this session's page went away, if one has. */
+    successorId(sessionId) {
+        return this.#successorOf(sessionId)?.id;
+    }
     /**
      * Did this id belong to a session that has since disconnected?
      *
@@ -396,8 +471,9 @@ export class SessionManager {
      */
     noteClosure(reason, at, page) {
         this.#recentClosures.push({ at, reason, ...(page === undefined ? {} : { page }) });
-        if (this.#recentClosures.length > MAX_REMEMBERED_CLOSURES)
+        if (this.#recentClosures.length > MAX_REMEMBERED_CLOSURES) {
             this.#recentClosures.shift();
+        }
         this.#connectedSinceLastClosure = false;
     }
     /** The most recent bridge-initiated close, if any. */
@@ -443,8 +519,9 @@ export class SessionManager {
      */
     lastKnown() {
         let last;
-        for (const record of this.#tombstones.values())
+        for (const record of this.#tombstones.values()) {
             last = record;
+        }
         return last;
     }
     /**
@@ -456,8 +533,9 @@ export class SessionManager {
     lastKnownFor(projectId) {
         let last;
         for (const record of this.#tombstones.values()) {
-            if (record.projectId === projectId)
+            if (record.projectId === projectId) {
                 last = record;
+            }
         }
         return last;
     }
@@ -496,40 +574,19 @@ export class SessionManager {
         const ended = sessionId.startsWith(LEASE_ID_PREFIX)
             ? ` Lease '${sessionId}' has ended (it expired or was released); lease a new tab to go on.`
             : '';
-        if (0 === own.length)
+        if (0 === own.length) {
             return (`no connected session with id '${sessionId}'.${ended} ` +
                 'Omit sessionId to let Reticle scope to your project, or lease a tab of your own.');
+        }
         const named = own.map((s) => `'${s.id}' (${s.url})`).join(', ');
         return (`no connected session with id '${sessionId}'.${ended} Your app's tabs: ${named}. ` +
             'Retry with one of those, or omit sessionId entirely and let Reticle scope to your project.');
     }
-    resolve(sessionId, scope) {
-        if (sessionId !== undefined) {
-            const found = this.#sessions.get(sessionId) ?? this.#successorOf(sessionId);
-            if (found === undefined) {
-                throw new Error(this.#unknownSessionError(sessionId));
-            }
-            found.markAgentActivity(); // liveness — a targeted tool keeps the session alive / revives it
-            return found;
-        }
-        if (0 === this.#sessions.size) {
-            const closure = this.lastClosure();
-            // A diagnosis beats a checklist: it names which of the three causes this actually is.
-            const hint = this.#noSessionHint?.();
-            // BOTH, when there are both — the two answer different questions and the pair is strictly
-            // more than either. This used to be an either/or, and a recorded refusal DISCARDED the whole
-            // diagnosis: the one case where the daemon has hard evidence about why nothing is connected
-            // was also the one case where it threw away everything else it had learned, including the
-            // port scan and the next action. The refusal leads, because it is the fact.
-            const refusal = closure === undefined
-                ? ''
-                : ` NOTE: the bridge REFUSED or closed a connection recently — "${closure.reason}". The app is probably still running and trying to connect: it was turned away, and the SDK does not retry after a policy close. The reason above names the fix — do not go looking for a stopped dev server.`;
-            // Hand the branch code to the refusal that is about to be reported for this throw. The
-            // diagnosis is computed HERE and the refusal is classified from the message downstream, so
-            // without this every no-session refusal lands in one undifferentiated bucket (#615).
-            notePendingNoSessionReason(this.#noSessionReason?.());
-            throw new Error(`${hint ?? NO_SESSION_CONNECTED_ERROR}${refusal}`);
-        }
+    /**
+     * The sessions an id-less call may choose from: in the project scope, then in the caller's own
+     * checkout. Throws when those scopes leave nothing, or leave tabs of more than one project.
+     */
+    #candidates(scope) {
         // Scope to the agent's active project FIRST, so a stray tab from another app/origin (e.g. a
         // leftover dashboard on a different port) is structurally unselectable — it never enters the
         // candidate set, no matter how recently it was heard from. This is the anti-cross-talk guard.
@@ -541,8 +598,9 @@ export class SessionManager {
         const byCheckout = this.#checkoutScope === undefined
             ? { sessions: inProject }
             : scopeToCallerCheckout(inProject, this.#checkoutScope.caller(), this.#checkoutScope.ofTab);
-        if (byCheckout.refusal !== undefined)
+        if (byCheckout.refusal !== undefined) {
             throw new Error(byCheckout.refusal);
+        }
         const all = byCheckout.sessions;
         if (0 === all.length) {
             // Sessions exist, but none belong to the scoped project — never fall back to a foreign tab.
@@ -551,27 +609,20 @@ export class SessionManager {
             // exists to be. Naming the tab and its sessionId costs the agent one extra argument.
             throw new Error(scopeMissError(connected, effectiveScope));
         }
-        if (1 === all.length) {
-            const [only] = all;
-            if (only === undefined)
-                throw new Error('session lookup failed');
-            only.markAgentActivity();
-            return only;
-        }
         // Two projects and nothing to choose between them: refuse, BEFORE any scoring.
         //
         // Reported from the field: a call from `apps/next-app-router` was answered by a `rowy-*`
         // session, and `act_and_wait` spent 16.9s returning `verified:'no'` about an app never under
         // test — a confident false verdict, with a source pointer, about code the agent never touched.
         //
-        // The recency rule below cannot prevent it. It asks "is one of these clearly fresher", which is
-        // the right question for two tabs of ONE app and the wrong question for two apps: the fresher
-        // tab of the wrong project is still the wrong project. The reported case had a clear winner,
-        // so the ambiguity check passed and the wrong app was selected.
+        // The recency rule in resolve() cannot prevent it. It asks "is one of these clearly fresher",
+        // which is the right question for two tabs of ONE app and the wrong question for two apps: the
+        // fresher tab of the wrong project is still the wrong project. The reported case had a clear
+        // winner, so the ambiguity check passed and the wrong app was selected.
         //
         // This sits ahead of scoring so freshness cannot rescue it. It only fires when nothing scoped
-        // the call — an explicit `sessionId` returns far above, and an explicit or default scope has
-        // already narrowed `all` to one project by here.
+        // the call — an explicit `sessionId` never reaches here, and an explicit or default scope has
+        // already narrowed `all` to one project by here. One session is one project, so it never fires.
         const projects = new Set(all.map((s) => s.projectId).filter((p) => p !== undefined));
         if (projects.size > 1) {
             const listed = all
@@ -584,25 +635,54 @@ export class SessionManager {
                 'never touched — the daemon scopes to the directory it was started in, so running it above ' +
                 'several apps leaves it unable to tell them apart.');
         }
-        // Multiple sessions: score each (lower = better candidate for auto-selection).
-        // 0 = non-throttled (visible + recently-heard), 1 = throttled (hidden or stale heartbeat),
-        // 2 = attached but not answering commands. A wedged tab keeps streaming events, so recency
-        // RATES IT HIGHEST — it was beating a healthy sibling on the one signal scoring looked at, and
-        // every call auto-targeted the one tab guaranteed to time out.
-        const scored = all.map((s) => ({
-            s,
-            // An error document (a dev server's 404 that still mounted the SDK) ranks below any working
-            // page, hidden or not: it is never the app the agent was asked about.
-            score: s.unresponsive() ? 3 : isErrorDocument(s.page) ? 2 : s.throttled() ? 1 : 0,
-            ms: s.lastSeenMs(),
-        }));
+        return all;
+    }
+    resolve(sessionId, scope) {
+        if (sessionId !== undefined) {
+            const found = this.#sessions.get(sessionId) ?? this.#successorOf(sessionId);
+            if (found === undefined) {
+                throw new Error(this.#unknownSessionError(sessionId));
+            }
+            found.markAgentActivity(); // liveness — a targeted tool keeps the session alive / revives it
+            return found;
+        }
+        if (0 === this.#sessions.size) {
+            const closure = this.lastClosure();
+            // A diagnosis beats a checklist: it names which of the three causes this actually is.
+            const hint = this.#noSessionHint?.();
+            // BOTH, when there are both — the two answer different questions and the pair is strictly
+            // more than either. This used to be an either/or, and a recorded refusal DISCARDED the whole
+            // diagnosis: the one case where the daemon has hard evidence about why nothing is connected
+            // was also the one case where it threw away everything else it had learned, including the
+            // port scan and the next action. The refusal leads, because it is the fact.
+            const refusal = closure === undefined
+                ? ''
+                : ` NOTE: the bridge REFUSED or closed a connection recently — "${closure.reason}". The app is probably still running and trying to connect: it was turned away, and the SDK does not retry after a policy close. The reason above names the fix — do not go looking for a stopped dev server.`;
+            // Hand the branch code to the refusal that is about to be reported for this throw. The
+            // diagnosis is computed HERE and the refusal is classified from the message downstream, so
+            // without this every no-session refusal lands in one undifferentiated bucket (#615).
+            notePendingNoSessionReason(this.#noSessionReason?.());
+            throw new Error(`${hint ?? NO_SESSION_CONNECTED_ERROR}${refusal}${NO_SESSION_NAVIGATE_FIX}`);
+        }
+        const all = this.#candidates(scope);
+        if (1 === all.length) {
+            const [only] = all;
+            if (only === undefined) {
+                throw new Error('session lookup failed');
+            }
+            only.markAgentActivity();
+            return only;
+        }
+        // Multiple sessions: score each (lower = better candidate for auto-selection). See rankOf().
+        const scored = all.map((s) => ({ s, score: rankOf(s), ms: s.lastSeenMs() }));
         const bestScore = Math.min(...scored.map((x) => x.score));
         const candidates = scored.filter((x) => x.score === bestScore);
         // Sort candidates by recency (ascending lastSeenMs = most recently active first).
         candidates.sort((a, b) => a.ms - b.ms);
         const [best, runnerUp] = candidates;
-        if (best === undefined)
+        if (best === undefined) {
             throw new Error('session lookup failed');
+        }
         // Only auto-select if there is a clear winner.
         //
         // When at least one non-throttled (focused/visible) session exists, require a >1 s recency
@@ -636,6 +716,44 @@ export class SessionManager {
         best.s.markAgentActivity();
         return best.s;
     }
+    /**
+     * Resolve the session for a call that only some sessions can serve.
+     *
+     * With no sessionId, resolve() chooses by health and recency alone. A lease that could resize the
+     * page lost to a focused tab that could not, and the call was refused (#1959). Here, when exactly
+     * one candidate can serve the call, that candidate is chosen.
+     */
+    async resolveServing(sessionId, canServe) {
+        // A named session, or none connected: resolve() already gives the answer and its refusals.
+        if (sessionId !== undefined || 0 === this.#sessions.size) {
+            return this.resolve(sessionId);
+        }
+        // The same candidates resolve() chooses from, so the project and checkout scopes still apply.
+        // canServe can ask a browser, so each answer is awaited in turn.
+        const serving = [];
+        for (const candidate of this.#candidates()) {
+            if (await canServe(candidate)) {
+                serving.push(candidate);
+            }
+        }
+        // Exactly one can serve the call: there is nothing to guess.
+        const [onlyServing, secondServing] = serving;
+        if (onlyServing !== undefined && secondServing === undefined) {
+            onlyServing.markAgentActivity();
+            return onlyServing;
+        }
+        // None can serve: return the usual choice, so the tool gives its own refusal and its advice.
+        // Several can serve, and the usual choice cannot: choosing among them is a guess, so refuse
+        // and name them. canServe admits only the caller's own sessions, so no other agent's lease is
+        // named here.
+        const chosen = this.resolve();
+        if (0 < serving.length && !serving.includes(chosen)) {
+            const ids = serving.map((s) => `'${s.id}'`).join(', ');
+            throw new Error(`no sessionId was given, and ${String(serving.length)} sessions can serve this call: ` +
+                `${ids}. Pass sessionId to choose one.`);
+        }
+        return chosen;
+    }
 }
 /**
  * Which of a project's tabs belong to the agent's own git checkout.
@@ -649,18 +767,29 @@ export class SessionManager {
  * dropped. A tab whose checkout cannot be read stays, because it can be the agent's own.
  */
 export function scopeToCallerCheckout(sessions, caller, checkoutOfTab) {
-    if (caller === undefined)
+    if (caller === undefined) {
         return { sessions: [...sessions] };
+    }
     const placed = sessions.map((session) => ({ session, checkout: checkoutOfTab(session) }));
     const mine = placed.filter((p) => isSame(p.checkout?.root, caller.root)).map((p) => p.session);
-    if (mine.length > 0)
+    if (mine.length > 0) {
         return { sessions: mine };
+    }
     const siblings = placed.filter((p) => isSame(p.checkout?.commonDir, caller.commonDir));
     if (siblings.length !== placed.length) {
         return { sessions: placed.filter((p) => !siblings.includes(p)).map((p) => p.session) };
     }
-    if (0 === siblings.length)
+    if (0 === siblings.length) {
         return { sessions: [] };
+    }
+    // The caller is the folder the MCP proxy started in, not always where the agent works. Claude Code
+    // starts the proxy in the main checkout and then moves the agent into a linked worktree (#1916).
+    // So from the main checkout, one linked worktree that serves every tab is the agent's own: drive it.
+    // The tab names its `worktree`. Tabs of two worktrees, or a proxy in a linked worktree, stay refused.
+    const roots = new Set(siblings.map((p) => p.checkout?.root));
+    if (!caller.linked && 1 === roots.size && true === siblings[0]?.checkout?.linked) {
+        return { sessions: siblings.map((p) => p.session) };
+    }
     const listed = siblings
         .map((p) => `${describeCheckout(p.checkout)} (sessionId '${p.session.id}', ${p.session.url})`)
         .join(', ');
@@ -675,8 +804,9 @@ export function scopeToCallerCheckout(sessions, caller, checkoutOfTab) {
 const isSame = (a, b) => a !== undefined && samePath(a, b);
 /** `/wt/a (branch feat/a)`, or the folder alone on a detached HEAD. */
 export function describeCheckout(checkout) {
-    if (checkout === undefined)
+    if (checkout === undefined) {
         return 'an unknown folder';
+    }
     return checkout.branch === undefined
         ? checkout.root
         : `${checkout.root} (branch ${checkout.branch})`;

package/dist/portal/session/session.js

@@ -1,6 +1,7 @@
 import { noteOwnReload, notePageLoaded } from '../../features/harness/drive-runs.js';
 import { asProjectId } from '@reticlehq/core';
 import { narrationArgs } from './narration-args.js';
+import { sdkBehindNote } from '../../command/version/version-skew.js';
 import { refusedResult } from './page-commands/undeclared-command.js';
 import { impactSnapshot, recordImpact } from '../../memory/impact/impact-recorder.js';
 import { callingAgent } from '../../hooks/coding-agents.js';
@@ -580,9 +581,9 @@ export class Session {
             this.recordActedRef(ref);
         if (name === ReticleCommand.REFRESH)
             noteOwnReload(this.id, this.#clock());
-        // Refused before it is sent, when the page said it does not serve this. The rule, and why
-        // an absent declaration is not an empty list, live in `undeclared-command.ts`.
-        const refused = refusedResult(name, this.commands, `${COMMAND_ID_PREFIX}refused`);
+        // Refused before it is sent when the page did not declare it. See `undeclared-command.ts`.
+        const behind = sdkBehindNote(this.sdkVersion);
+        const refused = refusedResult(name, this.commands, `${COMMAND_ID_PREFIX}refused`, behind);
         if (refused !== undefined)
             return Promise.resolve(refused);
         // The page already re-dialled under this same id. Nothing has been sent yet, so handing the