@reticlehq/server 3.6.0 → 3.7.0

package/dist/portal/session/recorded-gaps.d.ts

@@ -0,0 +1,97 @@
+import type { InboxMessage } from './human/live-control.js';
+import { type Coverage, CoverageCapability, type ImpactSnapshot } from '@reticlehq/core';
+export interface RecordedGap {
+    kind: string;
+    missing: string;
+    fix: string;
+    seenAt: number;
+    cost?: string;
+    ref?: string;
+    source?: string;
+}
+/** Remember gaps a verdict on this session just reported. Malformed entries are skipped. */
+export declare function recordGaps(sessionId: string, gaps: readonly object[], now: number): void;
+/** A tab as the notes below key it: its session, and the app it shows. */
+export interface NotedTab {
+    readonly id: string;
+    readonly projectId?: string | undefined;
+    readonly url?: string | undefined;
+}
+/** A verdict on this tab named a file:line: source mapping is seen, whatever else lacks one. */
+export declare function noteSourceSeen(tab: NotedTab, source: string | undefined): void;
+/** An acted element carried a test id: the app uses them, whatever one control lacks. */
+export declare function noteTestidSeen(tab: NotedTab, testid: string | undefined): void;
+/** What an act result says about the element it reached: its test id and its source stamp. */
+export declare function noteActedElement(tab: NotedTab, result: unknown): void;
+/**
+ * An act's result, passed through after noting what it says about the element it reached. Every act
+ * dispatches through one function, so coverage sees test ids and source stamps from the first
+ * control acted on rather than only from a verdict.
+ */
+export declare function notedAct<T extends {
+    ok: boolean;
+    result?: unknown;
+}>(tab: NotedTab, done: T): T;
+/** A tab the daemon can ask. Absent `command`: a test double or a tab with no page to ask. */
+export interface ProbedTab extends NotedTab {
+    command?(name: string, args?: Record<string, unknown>, timeoutMs?: number): Promise<{
+        ok: boolean;
+        result?: unknown;
+    }>;
+}
+/**
+ * Ask each page whose app has not shown both markers yet what it carries. What an act happens to
+ * reach decides nothing then: an app with test ids is seen to have them before anything acted, and a
+ * hidden tab of it says the same. A page that cannot answer (an older SDK, a closed tab) is skipped.
+ * True when a page showed something not known before.
+ */
+export declare function probeMarkers(tabs: readonly ProbedTab[]): Promise<boolean>;
+/** What this session's verdicts recorded, newest first. */
+export declare function recordedGaps(sessionId: string): readonly RecordedGap[];
+/** Forget a session that ended. What its app has shown is kept: it is still that app's. */
+export declare function forgetRecordedGaps(sessionId: string): void;
+/** Forget everything, apps included. For tests. */
+export declare function forgetAllRecordedGaps(): void;
+/** What instrumentation coverage reads off a connected tab. */
+export interface InstrumentedTab extends NotedTab {
+    readonly channels?: readonly string[] | undefined;
+    readonly sourceMapping?: boolean | undefined;
+    /** What the person said to the agent from this tab. Absent on a test double. */
+    inboxHistory?(): readonly InboxMessage[];
+}
+/**
+ * The tab's HELLO channels, plus the `source` marker when an act or verdict mapped a control to
+ * its file:line (seen anywhere is seen) or its page said it carries source mapping, and the
+ * `testid` marker once an acted element carried one — the list the platform report sends and
+ * coverage reads. A build that turned the stamp off has no source marker, whatever was seen.
+ */
+export declare function announcedChannels(tab: InstrumentedTab): string[];
+/**
+ * The coverage capabilities that do not apply to this tab's app, excluded from both sides of the
+ * score: file:line on a page that said it cannot apply there (plain HTML), until a stamp shows up.
+ * The platform reads the same list from the local-apps report, so both sides move together.
+ */
+export declare function notApplicableOf(tab: NotedTab): CoverageCapability[];
+/** Whether the Harness may drive this tab's app (see core's `instrumentation-coverage.ts`), as pushed. */
+export interface TabHarnessGate {
+    percent: number;
+    unlocked: boolean;
+    reason?: string;
+}
+/**
+ * This tab's coverage and its Harness gate, with the coding-agent prompt when its verdicts recorded
+ * any gap or the gate is shut: below the gate the prompt names every unseen capability, so there is
+ * always something to hand the agent.
+ */
+export declare function instrumentationOf(tab: InstrumentedTab, 
+/** The app's other tabs: what any of them has seen or recorded counts, as on the platform. */
+siblings?: readonly InstrumentedTab[]): Coverage & {
+    prompt?: string;
+    harnessGate: TabHarnessGate;
+};
+/**
+ * The impact snapshot a tab is pushed, carrying that tab's own coverage, running drive and agent
+ * link (who is attached, and this tab's notes to them). Every
+ * push needs the drive: one without it reads as "no drive", and the drive's own tool calls push.
+ */
+export declare function withInstrumentation(tab: InstrumentedTab, snapshot: ImpactSnapshot): ImpactSnapshot;

package/dist/portal/session/recorded-gaps.js

@@ -0,0 +1,251 @@
+/**
+ * The instrumentation gaps each session's verdicts actually recorded, kept for the surfaces that
+ * describe an app rather than one verdict: the platform's app report, the HUD's coverage line and
+ * `doctor`. Fed from the one function every verdict's gaps already pass through (`withGapNovelty`),
+ * so nothing here surveys a page: a gap is listed only because a verdict paid for it.
+ *
+ * Deduped by kind + missing, newest first, bounded per session.
+ */
+import { withRunningDrive } from '../../features/harness/drive-runs.js';
+import { agentLinkOf } from './agent-link.js';
+import { CoverageMarker, InstrumentationGapKind, LINK_APP_GAPS_MAX, ReticleCommand, agentPromptFor, coverageOf, harnessGateOf, harnessUnlockPrompt, CoverageCapability, } from '@reticlehq/core';
+const bySession = new Map();
+const text = (value) => 'string' === typeof value && 0 < value.length ? value : undefined;
+/** Remember gaps a verdict on this session just reported. Malformed entries are skipped. */
+export function recordGaps(sessionId, gaps, now) {
+    let list = bySession.get(sessionId) ?? [];
+    for (const raw of gaps) {
+        const gap = raw;
+        const kind = text(gap['kind']);
+        const missing = text(gap['missing']);
+        const fix = text(gap['fix']);
+        if (kind === undefined || missing === undefined || fix === undefined)
+            continue;
+        const cost = text(gap['cost']);
+        const ref = text(gap['ref']);
+        const source = text(gap['source']);
+        list = [
+            {
+                kind,
+                missing,
+                fix,
+                seenAt: now,
+                ...(cost === undefined ? {} : { cost }),
+                ...(ref === undefined ? {} : { ref }),
+                ...(source === undefined ? {} : { source }),
+            },
+            ...list.filter((g) => g.kind !== kind || g.missing !== missing),
+        ].slice(0, LINK_APP_GAPS_MAX);
+    }
+    if (0 < list.length)
+        bySession.set(sessionId, list);
+}
+/**
+ * The app a tab shows, as a key: its project, else its origin. What one tab of an app has shown
+ * (a file:line, a test id) is a fact about the app, and a fresh tab of it has not acted yet: keyed
+ * by session alone, every new lease reported the app at 75% and the platform locked a Harness run
+ * mid-drive that it had let start at 87.5%.
+ */
+function appKeyOf(tab) {
+    if (tab.projectId !== undefined && 0 < tab.projectId.length)
+        return `project:${tab.projectId}`;
+    if (tab.url === undefined)
+        return undefined;
+    try {
+        return `origin:${new URL(tab.url).origin}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Sessions, and apps, where at least one verdict mapped a control to its file:line. */
+const sourceSeen = new Set();
+/** Mark a tab, and the app it shows, in a seen-set. */
+function markSeen(seen, tab) {
+    seen.add(tab.id);
+    const app = appKeyOf(tab);
+    if (app !== undefined)
+        seen.add(app);
+}
+/** Whether this tab, or any tab of its app, was marked. */
+function wasSeen(seen, tab) {
+    const app = appKeyOf(tab);
+    return seen.has(tab.id) || (app !== undefined && seen.has(app));
+}
+/** A verdict on this tab named a file:line: source mapping is seen, whatever else lacks one. */
+export function noteSourceSeen(tab, source) {
+    if (source !== undefined)
+        markSeen(sourceSeen, tab);
+}
+/** Sessions, and apps, where an acted element carried a `data-testid`. */
+const testidSeen = new Set();
+/** An acted element carried a test id: the app uses them, whatever one control lacks. */
+export function noteTestidSeen(tab, testid) {
+    if (testid !== undefined && 0 < testid.length)
+        markSeen(testidSeen, tab);
+}
+/** What an act result says about the element it reached: its test id and its source stamp. */
+export function noteActedElement(tab, result) {
+    if ('object' !== typeof result || null === result)
+        return;
+    const acted = result;
+    noteTestidSeen(tab, text(acted['testid']));
+    const source = acted['source'];
+    if ('object' === typeof source && null !== source) {
+        const file = text(source['file']);
+        if (file !== undefined)
+            markSeen(sourceSeen, tab);
+    }
+}
+/**
+ * An act's result, passed through after noting what it says about the element it reached. Every act
+ * dispatches through one function, so coverage sees test ids and source stamps from the first
+ * control acted on rather than only from a verdict.
+ */
+export function notedAct(tab, done) {
+    if (done.ok)
+        noteActedElement(tab, done.result);
+    return done;
+}
+/** The markers a page said it carries (`ReticleCommand.MARKERS`), marked for its tab and its app. */
+function noteMarkers(tab, result) {
+    if ('object' !== typeof result || null === result)
+        return;
+    const markers = result['markers'];
+    if (!Array.isArray(markers))
+        return;
+    if (markers.includes(CoverageMarker.SOURCE))
+        markSeen(sourceSeen, tab);
+    if (markers.includes(CoverageMarker.TESTID))
+        markSeen(testidSeen, tab);
+    const notApplicable = result['notApplicable'];
+    if (Array.isArray(notApplicable) && notApplicable.includes(CoverageCapability.SOURCE_MAPPING))
+        markSeen(sourceNotApplicable, tab);
+}
+/** Apps whose page said file:line cannot apply (plain HTML: no plugin, no framework, no stamp). */
+const sourceNotApplicable = new Set();
+/** How long a page gets to say what it carries. Silent and cheap, so a page that cannot is skipped. */
+const MARKERS_PROBE_MS = 2_000;
+/**
+ * Ask each page whose app has not shown both markers yet what it carries. What an act happens to
+ * reach decides nothing then: an app with test ids is seen to have them before anything acted, and a
+ * hidden tab of it says the same. A page that cannot answer (an older SDK, a closed tab) is skipped.
+ * True when a page showed something not known before.
+ */
+export async function probeMarkers(tabs) {
+    const before = sourceSeen.size + testidSeen.size;
+    await Promise.all(tabs
+        .filter((tab) => !(wasSeen(sourceSeen, tab) || wasSeen(sourceNotApplicable, tab)) ||
+        !wasSeen(testidSeen, tab))
+        .map(async (tab) => {
+        const done = await tab
+            .command?.(ReticleCommand.MARKERS, {}, MARKERS_PROBE_MS)
+            .catch(() => undefined);
+        if (true === done?.ok)
+            noteMarkers(tab, done.result);
+    }));
+    return before < sourceSeen.size + testidSeen.size;
+}
+/** What this session's verdicts recorded, newest first. */
+export function recordedGaps(sessionId) {
+    return bySession.get(sessionId) ?? [];
+}
+/** Forget a session that ended. What its app has shown is kept: it is still that app's. */
+export function forgetRecordedGaps(sessionId) {
+    bySession.delete(sessionId);
+    sourceSeen.delete(sessionId);
+    testidSeen.delete(sessionId);
+}
+/** Forget everything, apps included. For tests. */
+export function forgetAllRecordedGaps() {
+    bySession.clear();
+    sourceSeen.clear();
+    testidSeen.clear();
+    sourceNotApplicable.clear();
+}
+/**
+ * The tab's HELLO channels, plus the `source` marker when an act or verdict mapped a control to
+ * its file:line (seen anywhere is seen) or its page said it carries source mapping, and the
+ * `testid` marker once an acted element carried one — the list the platform report sends and
+ * coverage reads. A build that turned the stamp off has no source marker, whatever was seen.
+ */
+export function announcedChannels(tab) {
+    const channels = [...(tab.channels ?? [])];
+    const gaps = recordedGaps(tab.id);
+    // Only the build turning the stamp off overrules the page: one unmapped control does not mean
+    // the app has no source mapping (core's per-control rule).
+    const off = gaps.some((gap) => InstrumentationGapKind.SOURCE_MAPPING_OFF === gap.kind);
+    if (!off && (wasSeen(sourceSeen, tab) || true === tab.sourceMapping))
+        channels.push(CoverageMarker.SOURCE);
+    // Nothing announces test ids, so they are seen on an acted element — and a control the agent
+    // could only reach without one keeps the capability missing.
+    const noTestid = gaps.some((gap) => InstrumentationGapKind.MISSING_TESTID === gap.kind);
+    if (!noTestid && wasSeen(testidSeen, tab))
+        channels.push(CoverageMarker.TESTID);
+    return channels;
+}
+/** The app a tab shows, named for a prompt: its host, else its url. */
+const appNameOf = (url) => {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+};
+/**
+ * The coverage capabilities that do not apply to this tab's app, excluded from both sides of the
+ * score: file:line on a page that said it cannot apply there (plain HTML), until a stamp shows up.
+ * The platform reads the same list from the local-apps report, so both sides move together.
+ */
+export function notApplicableOf(tab) {
+    return wasSeen(sourceNotApplicable, tab) && !wasSeen(sourceSeen, tab)
+        ? [CoverageCapability.SOURCE_MAPPING]
+        : [];
+}
+/**
+ * This tab's coverage and its Harness gate, with the coding-agent prompt when its verdicts recorded
+ * any gap or the gate is shut: below the gate the prompt names every unseen capability, so there is
+ * always something to hand the agent.
+ */
+export function instrumentationOf(tab, 
+/** The app's other tabs: what any of them has seen or recorded counts, as on the platform. */
+siblings = []) {
+    const tabs = [tab, ...siblings];
+    const gaps = [
+        ...new Map(tabs.flatMap((each) => recordedGaps(each.id)).map((g) => [`${g.kind}\u0000${g.missing}`, g])).values(),
+    ];
+    const channels = [...new Set(tabs.flatMap((each) => announcedChannels(each)))];
+    const coverage = coverageOf({ channels, gaps });
+    const url = tab.url ?? '';
+    const appName = appNameOf(url);
+    const notApplicable = notApplicableOf(tab);
+    const gate = harnessGateOf(coverage, notApplicable);
+    const harnessGate = {
+        percent: gate.percent,
+        unlocked: gate.unlocked,
+        ...(gate.reason === undefined ? {} : { reason: gate.reason }),
+    };
+    if (!gate.unlocked)
+        return {
+            ...coverage,
+            harnessGate,
+            prompt: harnessUnlockPrompt({ coverage, gaps, appName, url, notApplicable }),
+        };
+    return 0 === gaps.length
+        ? { ...coverage, harnessGate }
+        : { ...coverage, harnessGate, prompt: agentPromptFor({ gaps, appName, url }) };
+}
+/**
+ * The impact snapshot a tab is pushed, carrying that tab's own coverage, running drive and agent
+ * link (who is attached, and this tab's notes to them). Every
+ * push needs the drive: one without it reads as "no drive", and the drive's own tool calls push.
+ */
+export function withInstrumentation(tab, snapshot) {
+    const pushed = {
+        ...snapshot,
+        instrumentation: { ...instrumentationOf(tab) },
+        agent: agentLinkOf(tab.inboxHistory?.() ?? []),
+    };
+    return withRunningDrive(pushed, tab.id) ?? pushed;
+}

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

@@ -75,6 +75,17 @@ export interface SessionHealth {
  * That is the trade: an over-firing field gets ignored, and a field nobody reads catches nothing.
  */
 export declare const PENDING_NAVIGATION_NOTICE_MS = 10000;
+/**
+ * Said beside `dispatched` / `settled` on a skewed session, because those fields read as success.
+ *
+ * The reporter's own account of the cost: "the false-positive dispatch confirmation is what cost the
+ * most time — I trusted `dispatched: true, domMutatedWithin: Nms` as real signal for a long time
+ * before suspecting the skew banner." Stating the contradiction is the whole job here; the existing
+ * banner was accurate and simply never appeared where it was needed.
+ */
+/** The skew warning after an agent has read the paragraph once this session. */
+export declare const SKEW_SHORT_WARNING = "version skew: `dispatched`/`settled` here do not prove the app acted \u2014 see session.versionSkew.";
+export declare const SKEW_VERDICT_WARNING: string;
 /**
  * The age of the oldest request that STARTED and never completed, or undefined when there is none
  * worth reporting.

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

@@ -27,7 +27,9 @@ export const PENDING_NAVIGATION_NOTICE_MS = 10_000;
  * before suspecting the skew banner." Stating the contradiction is the whole job here; the existing
  * banner was accurate and simply never appeared where it was needed.
  */
-const SKEW_VERDICT_WARNING = 'version skew: `dispatched` and `settled` on this session mean the event was sent, NOT that the ' +
+/** The skew warning after an agent has read the paragraph once this session. */
+export const SKEW_SHORT_WARNING = 'version skew: `dispatched`/`settled` here do not prove the app acted — see session.versionSkew.';
+export const SKEW_VERDICT_WARNING = 'version skew: `dispatched` and `settled` on this session mean the event was sent, NOT that the ' +
     'app acted on it — a skewed pair drops actions silently. Re-read the control (aria-checked, ' +
     'data-state, its text) before trusting any verdict from this session, and converge the versions ' +
     '(see session.versionSkew).';

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

@@ -49,7 +49,8 @@ export function buildSessionInfo(session) {
         base.unresponsive = true;
         base.unresponsive_suggestion =
             'This tab is connected but has stopped answering commands, so every call against it will time ' +
-                'out. Ending the session does not revive the page. Reload the tab, or run `reticle open <url>` ' +
+                'out. Ending the session does not revive the page. Reload the tab, or run ' +
+                '`npx @reticlehq/server open <url>` ' +
                 'to get a fresh one — it will no longer hand this tab back.';
     }
     // Surface human bug reports in reticle_sessions (only when > 0, so a clean session adds nothing).

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

@@ -68,6 +68,13 @@ export declare class SessionManager {
     attachmentOf(sessionId: string): ReturnType<AttachmentHistory['of']>;
     /** Every connected session — used by the liveness reaper to sweep for idle/disconnected ones. */
     all(): Session[];
+    /**
+     * The connected sessions an id-less call may consider: the active project's, when one is set.
+     *
+     * The same set `resolve()` chooses from, so a caller that falls back from a refused resolution
+     * (an id-less yield) never reaches a tab the project scope would never have handed it.
+     */
+    inScope(): Session[];
     count(): number;
     /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
     setNoSessionHint(hint: (() => string | undefined) | undefined): void;
@@ -89,6 +96,8 @@ export declare class SessionManager {
     setNoSessionNextAction(next: (() => NoSessionNextAction | undefined) | undefined): void;
     noSessionNextAction(): NoSessionNextAction | undefined;
     everConnected(): boolean;
+    /** Whether a session for this project has registered since boot. An unknown id has not. */
+    everConnectedTo(projectId: string): boolean;
     /**
      * Record a bridge-initiated close so `resolve` can explain a session that vanished.
      *
@@ -120,6 +129,15 @@ export declare class SessionManager {
      * a connected tab is in `list()`, not here.
      */
     lastKnown(): SessionIdentity | undefined;
+    /**
+     * The most recent departed session for one project.
+     *
+     * `lastKnown` is the newest tombstone of any project. A shared daemon that quoted it to every
+     * caller told the second project to reopen the first project's tab.
+     */
+    lastKnownFor(projectId: string): SessionIdentity | undefined;
+    /** 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;
 }
 export {};

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

@@ -3,7 +3,7 @@ import { notePendingNoSessionReason } from '../../telemetry/tool-refused.js';
 import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input/driven-redaction.js';
 import { Session } from './session.js';
 import { AttachmentHistory } from './presence/attachment-history.js';
-import { openedBeforeDeparture, pickDocumentSuccessor, } from './session-successor.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';
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
@@ -85,6 +85,8 @@ const MAX_REMEMBERED_CLOSURES = 5;
  * Bounded so a long-lived daemon cannot accumulate one record per tab forever.
  */
 const MAX_TOMBSTONES = 32;
+/** How a leased tab's id begins (`lease-tools.ts` mints them). */
+const LEASE_ID_PREFIX = 'lease-';
 export class SessionManager {
     #sessions = new Map();
     /**
@@ -125,6 +127,8 @@ export class SessionManager {
     }
     add(session) {
         this.#everConnected = true;
+        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.
@@ -256,6 +260,15 @@ export class SessionManager {
     all() {
         return [...this.#sessions.values()];
     }
+    /**
+     * The connected sessions an id-less call may consider: the active project's, when one is set.
+     *
+     * The same set `resolve()` chooses from, so a caller that falls back from a refused resolution
+     * (an id-less yield) never reaches a tab the project scope would never have handed it.
+     */
+    inScope() {
+        return scopeSessions(this.all(), this.#defaultScope);
+    }
     count() {
         return this.#sessions.size;
     }
@@ -356,9 +369,20 @@ export class SessionManager {
     }
     /** Whether any session has connected since this daemon booted — half the diagnosis. */
     #everConnected = false;
+    /**
+     * Which projects have registered a session in this process.
+     *
+     * `#everConnected` is one bit for the whole daemon. A second project asking "has anything
+     * connected" was answered about the first. The set is the same fact, per project.
+     */
+    #connectedProjects = new Set();
     everConnected() {
         return this.#everConnected;
     }
+    /** Whether a session for this project has registered since boot. An unknown id has not. */
+    everConnectedTo(projectId) {
+        return this.#connectedProjects.has(projectId);
+    }
     /**
      * Record a bridge-initiated close so `resolve` can explain a session that vanished.
      *
@@ -419,6 +443,24 @@ export class SessionManager {
             last = record;
         return last;
     }
+    /**
+     * The most recent departed session for one project.
+     *
+     * `lastKnown` is the newest tombstone of any project. A shared daemon that quoted it to every
+     * caller told the second project to reopen the first project's tab.
+     */
+    lastKnownFor(projectId) {
+        let last;
+        for (const record of this.#tombstones.values()) {
+            if (record.projectId === projectId)
+                last = record;
+        }
+        return last;
+    }
+    /** Every departed session's URL, oldest first. The port scan has to see all of them, not only the newest. */
+    tombstoneUrls() {
+        return [...this.#tombstones.values()].map((record) => record.url);
+    }
     /**
      * A dead `sessionId`, answered with what the caller needs to recover — not with an errand.
      *
@@ -444,8 +486,17 @@ export class SessionManager {
                 ' The app is not dialling this daemon; call ' +
                 'reticle_sessions for the diagnosis rather than retrying this call.');
         }
-        const named = live.map((s) => `'${s.id}' (${s.url})`).join(', ');
-        return (`no connected session with id '${sessionId}'. Connected right now: ${named}. ` +
+        // A leased tab belongs to whoever holds the lease: naming it, and the page it is on, told one
+        // agent what every other agent on this daemon was doing. Only the app's own tabs are offered.
+        const own = live.filter((s) => claimedSessionOf(s.url) === undefined);
+        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)
+            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) {

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

@@ -24,6 +24,14 @@ export interface SuccessorClock {
     now: () => number;
     sleep: (ms: number) => Promise<void>;
 }
+/**
+ * The session a URL explicitly CLAIMS to be, via `__reticle_session`.
+ *
+ * A leased tab carries this marker so the pool can find the context it opened, and an app can set it
+ * deliberately so a battery addresses a known id. Either way it is a claim of identity, not a
+ * coincidence of origin — which is what makes it the right thing to gate succession on.
+ */
+export declare function claimedSessionOf(url: string): string | undefined;
 /**
  * The one live session that can honestly take over from `departed`, or undefined when none or more
  * than one could.

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

@@ -30,7 +30,7 @@ function originOf(url) {
  * deliberately so a battery addresses a known id. Either way it is a claim of identity, not a
  * coincidence of origin — which is what makes it the right thing to gate succession on.
  */
-function claimedSessionOf(url) {
+export function claimedSessionOf(url) {
     try {
         return new URL(url).searchParams.get(RETICLE_URL_PARAM.SESSION) ?? undefined;
     }