@reticlehq/server 3.5.0 → 3.6.0

package/dist/portal/pool/browser-pool.d.ts

@@ -10,7 +10,7 @@
  * the thin Playwright adapter that satisfies these interfaces lives separately.
  */
 import { type SeedStorage } from '@reticlehq/core';
-import type { Launcher, PooledMockRule } from './pool-contract.js';
+import type { Launcher, PooledMockRule, ScreenshotOptions } from './pool-contract.js';
 export type { InitScriptHandle, Launcher, PooledBrowser, PooledContext, PooledCookie, PooledDialog, PooledMockRule, PooledPage, } from './pool-contract.js';
 /** A leased context+page for one flow. `release` frees the slot and closes the context. */
 export interface Lease {
@@ -42,9 +42,17 @@ interface BrowserPoolOptions {
      * the ~450KB build is only read if some page ever needs it; undefined when there is none to give.
      */
     zeroInstallScript?: () => string | undefined;
+    /**
+     * Launches a browser with a window, for a lease somebody wants to watch. Launched only when the
+     * first headed lease is asked for. Absent: a headed lease is refused.
+     */
+    launchHeaded?: Launcher;
 }
+/** What a headed lease is refused with where no window can be opened. */
+export declare const NO_HEADED_BROWSER = "no headed browser can be opened here";
 /**
- * Owns a single browser and leases isolated contexts out of it, capped at `maxContexts`.
+ * Owns a headless browser (and, when asked, a headed one) and leases isolated contexts out of them,
+ * capped at `maxContexts` across both.
  * Not exported as a singleton — the daemon owns one instance.
  */
 export declare class BrowserPool {
@@ -60,15 +68,17 @@ export declare class BrowserPool {
     /** The sessionIds of every currently leased context — used to report/group leased sessions. */
     leasedSessionIds(): string[];
     /**
-     * The public session id of an active lease on this origin, if we already hold one.
+     * The public session id of an active lease on this origin that `owner` took, if there is one.
      *
      * The lease TOOL reuses that id instead of minting a second context: a second acquire on the same
-     * origin used to leave both tabs connected and poison default session resolution (#600). The pool's
-     * own `acquire` still mints — the parallel suite needs isolation on purpose.
+     * origin used to leave both tabs connected and poison default session resolution (#600). Only the
+     * caller that took the lease gets it back: handing it to whoever asked put two agents in one tab,
+     * each one's verdicts resting on the other's actions (#1226). A caller with no owner cannot be told
+     * apart from another, so it always gets its own. The pool's own `acquire` still mints.
      *
      * Prefers the alias the agent was given, when the app registered under its own name.
      */
-    leaseIdOnOrigin(origin: string): string | undefined;
+    leaseIdOnOrigin(origin: string, owner: string | undefined): string | undefined;
     /**
      * Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown.
      *
@@ -106,9 +116,7 @@ export declare class BrowserPool {
      * Touches the lease like any other tool call, so capturing keeps it alive rather than letting the
      * reaper take it out from under a diff.
      */
-    screenshotLease(sessionId: string, opts?: {
-        fullPage?: boolean;
-    }): Promise<Uint8Array | undefined>;
+    screenshotLease(sessionId: string, opts?: ScreenshotOptions): Promise<Uint8Array | undefined>;
     /**
      * Move the real pointer on a leased page, or false when this session is not a lease or cannot
      * hover. Same optional-capability contract as screenshotLease: absence must read as "could not
@@ -167,6 +175,9 @@ export declare class BrowserPool {
         signal?: AbortSignal;
         sessionId?: string;
         seedStorage?: SeedStorage;
+        owner?: string;
+        /** In a browser with a window the person can watch. */
+        headed?: boolean;
     }): Promise<Lease>;
     /**
      * The websocket address this lease's page reported it could not reach, if it reported one.
@@ -181,4 +192,6 @@ export declare class BrowserPool {
     lastDialogMessage(sessionId: string): string | undefined;
     /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
     shutdown(): Promise<void>;
+    /** Whether this lease lives in the headed browser. */
+    isHeaded(sessionId: string): boolean;
 }

package/dist/portal/pool/browser-pool.js

@@ -20,20 +20,22 @@ const DEFAULT_NAV_TIMEOUT_MS = 30_000;
  * this is slack for a burst sweep, not a history.
  */
 const MAX_REMEMBERED_REAPED_LEASES = 64;
+/** What a headed lease is refused with where no window can be opened. */
+export const NO_HEADED_BROWSER = 'no headed browser can be opened here';
 /**
- * Owns a single browser and leases isolated contexts out of it, capped at `maxContexts`.
+ * Owns a headless browser (and, when asked, a headed one) and leases isolated contexts out of them,
+ * capped at `maxContexts` across both.
  * Not exported as a singleton — the daemon owns one instance.
  */
 export class BrowserPool {
-    #launch;
     #max;
     #genId;
     #now;
     #ttl;
     #zeroInstall;
     #navTimeout;
-    #browser;
-    #launching;
+    #headless;
+    #headed;
     #closed = false;
     /** Leases reclaimed for going stale — see reapedLeaseCount(). */
     #reapedLeases = 0;
@@ -65,7 +67,8 @@ export class BrowserPool {
     constructor(launch, opts) {
         if (opts.maxContexts < 1)
             throw new Error('maxContexts must be >= 1');
-        this.#launch = launch;
+        this.#headless = { launch, headed: false };
+        this.#headed = { launch: opts.launchHeaded, headed: true };
         this.#max = opts.maxContexts;
         this.#genId = opts.genSessionId;
         this.#now = opts.now ?? (() => Date.now());
@@ -93,16 +96,22 @@ export class BrowserPool {
         return [...this.#active.keys()];
     }
     /**
-     * The public session id of an active lease on this origin, if we already hold one.
+     * The public session id of an active lease on this origin that `owner` took, if there is one.
      *
      * The lease TOOL reuses that id instead of minting a second context: a second acquire on the same
-     * origin used to leave both tabs connected and poison default session resolution (#600). The pool's
-     * own `acquire` still mints — the parallel suite needs isolation on purpose.
+     * origin used to leave both tabs connected and poison default session resolution (#600). Only the
+     * caller that took the lease gets it back: handing it to whoever asked put two agents in one tab,
+     * each one's verdicts resting on the other's actions (#1226). A caller with no owner cannot be told
+     * apart from another, so it always gets its own. The pool's own `acquire` still mints.
      *
      * Prefers the alias the agent was given, when the app registered under its own name.
      */
-    leaseIdOnOrigin(origin) {
+    leaseIdOnOrigin(origin, owner) {
+        if (owner === undefined)
+            return undefined;
         for (const [leaseId, lease] of this.#active) {
+            if (lease.owner !== owner)
+                continue;
             let leaseOrigin;
             try {
                 leaseOrigin = new URL(lease.url).origin;
@@ -314,6 +323,10 @@ export class BrowserPool {
     async acquire(url, opts = {}) {
         if (this.#closed)
             throw new Error('browser pool is shut down');
+        const slot = true === opts.headed ? this.#headed : this.#headless;
+        // Refused before a slot is claimed, so a refusal never holds one.
+        if (slot.launch === undefined)
+            throw new Error(NO_HEADED_BROWSER);
         // #waitForSlot claims the slot synchronously (bumps #occupied) before returning, so the cap holds
         // even when many acquires race through the gate in the same tick.
         await this.#waitForSlot(opts.signal);
@@ -322,7 +335,7 @@ export class BrowserPool {
         let pending;
         let pendingDialogMessage;
         try {
-            const browser = await this.#ensureBrowser();
+            const browser = await this.#ensureBrowser(slot);
             context = await browser.newContext();
             const page = await context.newPage();
             // Per-page crash isolation: if THIS renderer dies, reclaim only this lease — the shared browser
@@ -375,7 +388,7 @@ export class BrowserPool {
             // #occupied. Registering the lease now would resurrect a dead entry against a crashed browser with
             // the slot count out of sync (drifting below #active.size, eventually exceeding the cap). If we're
             // no longer the live browser, bail — the catch below closes the context and returns the slot.
-            if (this.#browser !== browser)
+            if (slot.browser !== browser)
                 throw new Error('browser crashed during navigation');
             let navStatus;
             if (null !== navRes && 'object' === typeof navRes && 'status' in navRes) {
@@ -395,9 +408,11 @@ export class BrowserPool {
                 }
             }
             this.#active.set(sessionId, {
+                headed: slot.headed,
                 context,
                 page,
                 url,
+                ...(opts.owner === undefined ? {} : { owner: opts.owner }),
                 touchedAt: this.#now(),
                 ...(pending === undefined ? {} : { dialFailureUrl: pending }),
                 ...(pendingDialogMessage === undefined ? {} : { lastDialogMessage: pendingDialogMessage }),
@@ -450,17 +465,19 @@ export class BrowserPool {
         await Promise.all(contexts.map((c) => c.close().catch(() => undefined)));
         // If a launch is in flight, await it so we can close the resulting browser — otherwise it
         // resolves after shutdown returns and the Chromium process is orphaned (hundreds of MB leaked).
-        const inflight = this.#launching;
-        if (inflight !== undefined) {
-            const launched = await inflight.catch(() => undefined);
-            if (launched !== undefined && launched !== this.#browser) {
-                await launched.close().catch(() => undefined);
+        for (const slot of [this.#headless, this.#headed]) {
+            const inflight = slot.launching;
+            if (inflight !== undefined) {
+                const launched = await inflight.catch(() => undefined);
+                if (launched !== undefined && launched !== slot.browser) {
+                    await launched.close().catch(() => undefined);
+                }
             }
+            const browser = slot.browser;
+            slot.browser = undefined;
+            if (browser !== undefined)
+                await browser.close().catch(() => undefined);
         }
-        const browser = this.#browser;
-        this.#browser = undefined;
-        if (browser !== undefined)
-            await browser.close().catch(() => undefined);
         for (const waiter of this.#waiters.splice(0))
             waiter();
     }
@@ -532,38 +549,56 @@ export class BrowserPool {
         if (next !== undefined)
             next();
     }
-    async #ensureBrowser() {
+    async #ensureBrowser(slot) {
         if (this.#closed)
             throw new Error('browser pool is shut down');
-        if (this.#browser !== undefined && this.#browser.isConnected())
-            return this.#browser;
+        if (slot.browser !== undefined && slot.browser.isConnected())
+            return slot.browser;
+        const launch = slot.launch;
+        if (launch === undefined)
+            throw new Error(NO_HEADED_BROWSER);
         // De-dupe concurrent launches: the first acquire to find no browser starts one; the rest await it.
-        if (this.#launching === undefined) {
+        if (slot.launching === undefined) {
             // The in-flight promise MUST be cleared on failure as well as success. It used to be cleared only
             // in the success callback, so the first failed launch — Chromium not downloaded, a transient
             // EAGAIN — left a permanently rejected promise here, and every subsequent acquire for the daemon's
             // lifetime re-returned that same stale rejection. Running `npx playwright install` did not help;
             // only restarting the daemon did. A retry must be allowed to actually retry.
-            this.#launching = this.#launch()
+            slot.launching = launch()
                 .then((b) => {
-                b.onDisconnected(() => this.#onCrash(b));
-                this.#browser = b;
+                b.onDisconnected(() => this.#onCrash(slot, b));
+                slot.browser = b;
                 return b;
             })
                 .finally(() => {
-                this.#launching = undefined;
+                slot.launching = undefined;
             });
         }
-        return this.#launching;
+        return slot.launching;
     }
-    /** The browser process died: drop every lease (they're invalid) and clear so the next acquire relaunches. */
-    #onCrash(crashed) {
-        if (this.#browser !== crashed)
+    /**
+     * A browser process died: drop the leases it held (they're invalid) and clear its slot so the next
+     * acquire of that kind relaunches it. The other browser's leases live on.
+     */
+    #onCrash(slot, crashed) {
+        if (slot.browser !== crashed)
             return; // a stale handler from a prior browser
-        this.#browser = undefined;
-        this.#active.clear();
-        this.#occupied = 0; // every slot is gone with the browser
+        slot.browser = undefined;
+        let freed = 0;
+        for (const [id, lease] of this.#active) {
+            if (lease.headed !== slot.headed)
+                continue;
+            this.#active.delete(id);
+            freed += 1;
+        }
+        // A lease mid-acquire on the dead browser holds a slot too; it frees it in its own catch. When
+        // every lease belonged to this browser, nothing else can be holding one.
+        this.#occupied = 0 === this.#active.size ? 0 : Math.max(0, this.#occupied - freed);
         for (const waiter of this.#waiters.splice(0))
             waiter(); // let them re-claim + relaunch
     }
+    /** Whether this lease lives in the headed browser. */
+    isHeaded(sessionId) {
+        return true === this.#active.get(this.#leaseIdOf(sessionId))?.headed;
+    }
 }

package/dist/portal/pool/playwright-launcher.d.ts

@@ -6,6 +6,19 @@
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
 import type { Launcher } from './browser-pool.js';
+import type { ScreenshotOptions } from './pool-contract.js';
+/** Reticle's own panel, kept out of a picture of the app: it is ours, not what the app shows. */
+export declare const HIDE_RETICLE_CHROME_CSS = "[data-reticle-overlay]{display:none !important}";
+/**
+ * How Playwright captures a leased tab. A live picture (JPEG) leaves Reticle's panel out, as the
+ * visual captures do; a plain PNG capture is unchanged, so no existing baseline moves.
+ */
+export declare function screenshotOptions(opts: ScreenshotOptions): {
+    fullPage: boolean;
+    type?: 'jpeg';
+    quality?: number;
+    style?: string;
+};
 /**
  * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
  * the rest of this file needs a real Chromium.

package/dist/portal/pool/playwright-launcher.js

@@ -11,6 +11,22 @@ import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
 import { chromiumInstallCommand, chromiumInstallDepsCommand, bundledPlaywrightVersion, } from '../../command/cli/doctor/browser/chromium-hint.js';
 import { installNetworkMocks } from '../input/network-mock.js';
+/** Reticle's own panel, kept out of a picture of the app: it is ours, not what the app shows. */
+export const HIDE_RETICLE_CHROME_CSS = '[data-reticle-overlay]{display:none !important}';
+/**
+ * How Playwright captures a leased tab. A live picture (JPEG) leaves Reticle's panel out, as the
+ * visual captures do; a plain PNG capture is unchanged, so no existing baseline moves.
+ */
+export function screenshotOptions(opts) {
+    return opts.jpegQuality === undefined
+        ? { fullPage: true === opts.fullPage }
+        : {
+            fullPage: true === opts.fullPage,
+            type: 'jpeg',
+            quality: opts.jpegQuality,
+            style: HIDE_RETICLE_CHROME_CSS,
+        };
+}
 /**
  * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
  * the rest of this file needs a real Chromium.
@@ -43,7 +59,7 @@ function wrapBrowser(browser) {
                         close: () => page.close(),
                         evaluate: (script) => page.evaluate(script),
                         // Playwright returns a Buffer; Uint8Array is what the visual store and differ take.
-                        screenshot: async (opts) => new Uint8Array(await page.screenshot({ fullPage: true === opts?.fullPage })),
+                        screenshot: async (opts) => new Uint8Array(await page.screenshot(screenshotOptions(opts ?? {}))),
                         // Three moves, same as performGesture: a single move to the center can be a no-op if
                         // the pointer was already there, and CSS :hover needs a native hit-test to apply.
                         hover: async (x, y) => {

package/dist/portal/pool/pool-contract.d.ts

@@ -20,14 +20,12 @@ export interface PooledPage {
      */
     onConsole?(handler: (text: string) => void): void;
     /**
-     * Capture the page as a PNG. OPTIONAL, like `onConsole`: a fake that does not implement it makes
+     * Capture the page as a PNG, or a JPEG at `jpegQuality` (a live picture, where size matters more). OPTIONAL, like `onConsole`: a fake that does not implement it makes
      * the pool report "no provider", which is the correct degradation — an absent screenshotter must
      * read as "this context cannot be captured", never as a blank image that a visual diff would then
      * compare against and pass.
      */
-    screenshot?(opts?: {
-        fullPage?: boolean;
-    }): Promise<Uint8Array>;
+    screenshot?(opts?: ScreenshotOptions): Promise<Uint8Array>;
     /**
      * Move the real pointer to (x, y) so CSS `:hover` applies. OPTIONAL, like `screenshot`: a fake
      * that does not implement it makes hover refuse rather than dispatch a synthetic mouseover that
@@ -116,3 +114,8 @@ export interface PooledBrowser {
 }
 /** Produces a freshly launched browser. Injected so tests can supply a fake. */
 export type Launcher = () => Promise<PooledBrowser>;
+/** How a page is captured: the whole page or the viewport, and JPEG at a quality instead of PNG. */
+export interface ScreenshotOptions {
+    fullPage?: boolean;
+    jpegQuality?: number;
+}

package/dist/portal/session/command-payload.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The command a session sends its page, as wire JSON.
+ *
+ * Marked `by: harness` when the Harness is the one calling, so the HUD can show the person watching
+ * which of the two is driving their app. Absent means the connected agent, which is also what an
+ * older page that does not know the field assumes.
+ */
+export declare function commandPayload(id: string, sessionId: string, name: string, args: Record<string, unknown>): string;

package/dist/portal/session/command-payload.js

@@ -0,0 +1,19 @@
+import { CommandActor, MessageKind } from '@reticlehq/core';
+import { currentDrivenBy } from '../../hooks/driven-by.js';
+/**
+ * The command a session sends its page, as wire JSON.
+ *
+ * Marked `by: harness` when the Harness is the one calling, so the HUD can show the person watching
+ * which of the two is driving their app. Absent means the connected agent, which is also what an
+ * older page that does not know the field assumes.
+ */
+export function commandPayload(id, sessionId, name, args) {
+    return JSON.stringify({
+        kind: MessageKind.COMMAND,
+        id,
+        sessionId,
+        name,
+        args,
+        ...(currentDrivenBy() === undefined ? {} : { by: CommandActor.HARNESS }),
+    });
+}

package/dist/portal/session/dev-server/dev-command.d.ts

@@ -16,6 +16,8 @@ export interface DevCommand {
     script?: string;
     /** The port the script PINS, when it pins one. Absent means the tool picks — never a guess. */
     port?: number;
+    /** The app's directory, when it is not the project root. The caller must run the command there. */
+    directory?: string;
 }
 /**
  * The dev command for the project in `directory`, or undefined when there is not one to be sure of.
@@ -24,3 +26,13 @@ export interface DevCommand {
  * default disk reader.
  */
 export declare function detectDevCommand(directory: string, read?: (path: string) => string | undefined): DevCommand | undefined;
+/**
+ * The dev command for the project, looking one level down when the root has none.
+ *
+ * `reticle init` is run at the repo root, and in a monorepo the app is a directory down — so the
+ * daemon's "this project declares no dev script" was false for a root whose `frontend/package.json`
+ * held `"dev": "vite"`, and the agent asked a human for a command that was on disk (reticle#1368).
+ * init's own workspace listing answers which directories to consider; the root's lockfile picks the
+ * package manager, because a workspace package usually has no lockfile of its own.
+ */
+export declare function detectDevCommandInProject(directory: string, read?: (path: string) => string | undefined, listDirs?: (path: string) => readonly string[]): DevCommand | undefined;

package/dist/portal/session/dev-server/dev-command.js

@@ -8,9 +8,9 @@
  *
  * Pure apart from one injected reader, so every case is a unit test rather than a temp directory.
  */
-import { readFileSync } from 'node:fs';
+import { readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { desktopLaunch } from '@reticlehq/init';
+import { desktopLaunch, workspacePackageDirs } from '@reticlehq/init';
 /**
  * Script names checked, in order.
  *
@@ -28,6 +28,12 @@ const DEFAULT_PACKAGE_MANAGER = 'npm';
 const PACKAGE_JSON = 'package.json';
 /** `--port 4311` / `--port=4311`, the flag every dev server in this list accepts. */
 const PORT_FLAG = /--port[= ]\s*(\d+)/;
+/**
+ * `-p 3005`, the short form Next, Nuxt and Astro accept (reticle#1367).
+ *
+ * Anchored to a start or a whitespace so the `-p` inside a longer flag (`--pretty`) is not a port.
+ */
+const PORT_SHORT_FLAG = /(?:^|\s)-p\s*(\d+)/;
 /** `PORT=8080 remix dev` — the other half of how a project pins its port. */
 const PORT_ENV = /(?:^|\s)PORT=(\d+)/;
 /** Reads a file, or undefined if it is not there / not readable. */
@@ -41,7 +47,7 @@ function readTextFile(path) {
 }
 /** The port the script pins, when it pins one at all. */
 function pinnedPort(script) {
-    const match = PORT_FLAG.exec(script) ?? PORT_ENV.exec(script);
+    const match = PORT_FLAG.exec(script) ?? PORT_SHORT_FLAG.exec(script) ?? PORT_ENV.exec(script);
     const digits = match?.[1];
     if (digits === undefined)
         return undefined;
@@ -68,17 +74,15 @@ function scriptsOf(manifest) {
         return {};
     return scripts;
 }
-/**
- * The dev command for the project in `directory`, or undefined when there is not one to be sure of.
- *
- * `read` is injected so the whole decision is testable without a filesystem; the daemon uses the
- * default disk reader.
- */
-export function detectDevCommand(directory, read = readTextFile) {
+/** The package manager the lockfiles under `directory` identify. Anything else is npm. */
+function packageManager(directory, read) {
+    return (LOCKFILES.find(({ file }) => read(join(directory, file)) !== undefined)?.manager ??
+        DEFAULT_PACKAGE_MANAGER);
+}
+/** The dev command for the package in `directory`, with the manager chosen by the caller. */
+function devCommandFor(directory, manager, read) {
     const manifest = readManifest(read(join(directory, PACKAGE_JSON)));
     const scripts = scriptsOf(manifest);
-    const manager = LOCKFILES.find(({ file }) => read(join(directory, file)) !== undefined)?.manager ??
-        DEFAULT_PACKAGE_MANAGER;
     // A desktop shell's `dev` is its renderer's dev server, which no window ever opens onto. init's
     // rule decides which launcher it is, so the command the daemon hands an agent and the one init
     // spawns are the same.
@@ -105,3 +109,48 @@ export function detectDevCommand(directory, read = readTextFile) {
     }
     return undefined;
 }
+/** Directory names under `path`, or none when it cannot be read. */
+function readDirNames(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The dev command for the project in `directory`, or undefined when there is not one to be sure of.
+ *
+ * `read` is injected so the whole decision is testable without a filesystem; the daemon uses the
+ * default disk reader.
+ */
+export function detectDevCommand(directory, read = readTextFile) {
+    return devCommandFor(directory, packageManager(directory, read), read);
+}
+/**
+ * The dev command for the project, looking one level down when the root has none.
+ *
+ * `reticle init` is run at the repo root, and in a monorepo the app is a directory down — so the
+ * daemon's "this project declares no dev script" was false for a root whose `frontend/package.json`
+ * held `"dev": "vite"`, and the agent asked a human for a command that was on disk (reticle#1368).
+ * init's own workspace listing answers which directories to consider; the root's lockfile picks the
+ * package manager, because a workspace package usually has no lockfile of its own.
+ */
+export function detectDevCommandInProject(directory, read = readTextFile, listDirs = readDirNames) {
+    const manager = packageManager(directory, read);
+    const here = devCommandFor(directory, manager, read);
+    if (here !== undefined)
+        return here;
+    const packages = workspacePackageDirs({
+        readFile: (path) => read(join(directory, path)) ?? null,
+        listDirs: (path) => listDirs(join(directory, path)),
+    });
+    for (const sub of packages) {
+        const found = devCommandFor(join(directory, sub), manager, read);
+        if (found !== undefined)
+            return { ...found, directory: sub };
+    }
+    return undefined;
+}

package/dist/portal/session/facts/departure-note.d.ts

@@ -0,0 +1,22 @@
+import { type ReticleEvent } from '@reticlehq/core';
+/**
+ * Where the SDK last saw the page heading.
+ *
+ * The SDK emits a navigation-initiated NET_PENDING while the old document is still alive — the
+ * one fact that can outrun the socket close (#1256). This keeps it off `Session.url` deliberately:
+ * successor matching and the 5xx probe need the page the tab was ON; this is where it was GOING.
+ * Timestamps are session-relative milliseconds, read from the session's injected clock.
+ */
+export declare class DepartureNote {
+    #private;
+    /** Fold one inbound event into the note. */
+    observe(event: ReticleEvent, elapsedMs: number): void;
+    /**
+     * The navigation target, if it is fresh enough to be this departure's story.
+     *
+     * A navigation intent from long ago is not this departure: the document survived it — it kept
+     * talking — so attributing a later disconnect to it would invent a story. Read at tombstone
+     * time, when `elapsedMs` is the disconnect time.
+     */
+    read(elapsedMs: number): string | undefined;
+}

package/dist/portal/session/facts/departure-note.js

@@ -0,0 +1,47 @@
+import { EventType, NetInitiator } from '@reticlehq/core';
+/**
+ * How long a navigation-departure note stays attributable to the disconnect that follows it.
+ *
+ * The socket close follows a real departure within seconds; a note older than this belongs to a
+ * navigation the document survived, and blaming a later disconnect on it would invent a story.
+ */
+const DEPARTED_TO_FRESHNESS_MS = 30_000;
+/**
+ * Where the SDK last saw the page heading.
+ *
+ * The SDK emits a navigation-initiated NET_PENDING while the old document is still alive — the
+ * one fact that can outrun the socket close (#1256). This keeps it off `Session.url` deliberately:
+ * successor matching and the 5xx probe need the page the tab was ON; this is where it was GOING.
+ * Timestamps are session-relative milliseconds, read from the session's injected clock.
+ */
+export class DepartureNote {
+    #note;
+    /** Fold one inbound event into the note. */
+    observe(event, elapsedMs) {
+        if (event.type !== EventType.NET_PENDING)
+            return;
+        // Only navigation-initiated pendings count: a fetch that never settled is in-flight work,
+        // not a departure.
+        if (event.data['initiator'] !== NetInitiator.NAVIGATION)
+            return;
+        // A download never takes the document away, so it must not explain a later disconnect.
+        if (true === event.data['download'])
+            return;
+        const url = event.data['url'];
+        if ('string' !== typeof url || 0 === url.length)
+            return;
+        this.#note = { url, at: elapsedMs };
+    }
+    /**
+     * The navigation target, if it is fresh enough to be this departure's story.
+     *
+     * A navigation intent from long ago is not this departure: the document survived it — it kept
+     * talking — so attributing a later disconnect to it would invent a story. Read at tombstone
+     * time, when `elapsedMs` is the disconnect time.
+     */
+    read(elapsedMs) {
+        if (this.#note === undefined)
+            return undefined;
+        return elapsedMs - this.#note.at <= DEPARTED_TO_FRESHNESS_MS ? this.#note.url : undefined;
+    }
+}

package/dist/portal/session/facts/session-replaced.d.ts

@@ -33,6 +33,11 @@ export declare function isSessionReplacedError(error: unknown): boolean;
  * `PendingCommands.rejectAll` documents, and a caller that CAN wait decides what it means.
  */
 export declare const SESSION_DISCONNECTED_REASON = "session disconnected";
+/**
+ * The close an agent's `reticle_session { action: "end", disconnect: true }` sends. The page's SDK
+ * prints it and stops retrying, so it says how to undo it. A close reason is capped at 123 bytes.
+ */
+export declare const SESSION_PARKED_REASON = "detached by the agent (session end, disconnect) \u2014 restart the daemon to attach this window again";
 /**
  * Is this failure the page's transport going away, rather than an answer from the page?
  *

package/dist/portal/session/facts/session-replaced.js

@@ -38,6 +38,11 @@ export function isSessionReplacedError(error) {
  * `PendingCommands.rejectAll` documents, and a caller that CAN wait decides what it means.
  */
 export const SESSION_DISCONNECTED_REASON = 'session disconnected';
+/**
+ * The close an agent's `reticle_session { action: "end", disconnect: true }` sends. The page's SDK
+ * prints it and stops retrying, so it says how to undo it. A close reason is capped at 123 bytes.
+ */
+export const SESSION_PARKED_REASON = 'detached by the agent (session end, disconnect) — restart the daemon to attach this window again';
 /**
  * Is this failure the page's transport going away, rather than an answer from the page?
  *