@reticlehq/server 3.2.0 → 3.3.0

package/dist/memory/project/fs/fs-port.js

@@ -1,11 +1,46 @@
 import { access, appendFile, mkdir, open, readdir, readFile, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
 /** The JSONL record terminator, as a byte — the only boundary a capped tail read can align to. */
 const NEWLINE_BYTE = 0x0a;
+/**
+ * The largest single `read(2)` this port will ask for: 2^31 - 1, the int32 ceiling.
+ *
+ * Past it `fs.read` does not throw — it ABORTS the process on a V8 assertion
+ * (`node::fs::Read ... Assertion failed: args[3]->IsInt32()`, where args[3] is the length). That is
+ * not catchable, so one oversized journal takes the daemon down and with it every session on the
+ * machine, including unrelated ones. Reported from the field exactly that way.
+ *
+ * Reachable in practice because `Buffer.allocUnsafe` happily allocates well past this, so a
+ * `size - start` over 2 GiB allocates fine and then kills node at the syscall. A `.reticle/sessions`
+ * has been observed in the multi-gigabyte range, so "no journal is ever that big" is not a bound
+ * anybody is enforcing.
+ *
+ * Clamping rather than throwing is deliberate: a caller reading a tail wants the newest records, and
+ * returning the last 2 GiB of them is a better answer than an error. The boundary realignment below
+ * already handles a window that opens mid-record, which is exactly what a clamp produces.
+ */
+const MAX_SINGLE_READ_BYTES = 2_147_483_647;
+/**
+ * Refuse an offset that cannot survive the arithmetic below.
+ *
+ * `length = size - start`, so a non-integer or negative offset produces a non-integer or negative
+ * length, and those fail in two different ways one layer apart: `Buffer.allocUnsafe` throws a
+ * RangeError for a fractional length, while an oversized one reaches `fs.read` and aborts the
+ * process. Checking here means the caller gets one predictable rejection instead of either.
+ */
+function requireByteCount(label, value) {
+    if (value === undefined)
+        return;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${label} must be a non-negative safe integer, got ${String(value)} — a fractional or negative byte count cannot reach a read syscall safely`);
+    }
+}
 /** Production adapter — the single import site of node:fs/promises in the server. */
 export function createNodeFileSystem() {
     return {
         readFile: (path) => readFile(path, 'utf8'),
         readFileFrom: async (path, byteOffset, maxBytes) => {
+            requireByteCount('byteOffset', byteOffset);
+            requireByteCount('maxBytes', maxBytes);
             const fh = await open(path, 'r');
             try {
                 const { size } = await fh.stat();
@@ -18,14 +53,18 @@ export function createNodeFileSystem() {
                 // One byte BEFORE that cut, so a cut landing exactly on a record boundary is recognised as
                 // one instead of sacrificing the record after it.
                 const start = capped ? cut - 1 : byteOffset;
-                const length = size - start;
+                // Clamped to the int32 ceiling: past it `fs.read` aborts the process rather than throwing.
+                // Keep the NEWEST bytes, matching what every caller of a tail read is asking for.
+                const want = size - start;
+                const length = Math.min(want, MAX_SINGLE_READ_BYTES);
+                const readFrom = start + (want - length);
                 const buf = Buffer.allocUnsafe(length);
-                const { bytesRead } = await fh.read(buf, 0, length, start);
+                const { bytesRead } = await fh.read(buf, 0, length, readFrom);
                 // ONLY what the read returned. `allocUnsafe` hands back whatever was last in that heap
                 // block, and `fstat` runs one syscall ahead of `read` — so a file truncated in between, or
                 // any short read, would otherwise decode that memory and hand it back as journal text.
                 const got = buf.subarray(0, bytesRead);
-                if (!capped)
+                if (!capped && readFrom === start)
                     return { text: got.toString('utf8'), size, from: start };
                 // The ceiling moved the start, so the window may open inside a record whose head was never
                 // read. Drop up to the first boundary in BYTES, before decoding: `\n` is one byte and
@@ -35,11 +74,11 @@ export function createNodeFileSystem() {
                 // No boundary in the whole window: there is no record here that can be read, and half of
                 // one is worse than none. `from` still says how far the read reached.
                 if (-1 === newline)
-                    return { text: '', size, from: start + bytesRead };
+                    return { text: '', size, from: readFrom + bytesRead };
                 return {
                     text: got.subarray(newline + 1).toString('utf8'),
                     size,
-                    from: start + newline + 1,
+                    from: readFrom + newline + 1,
                 };
             }
             finally {

package/dist/memory/project/fs/write-atomic.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Write a file so a reader never sees a half-written one, and two writers never see each other's.
+ *
+ * Write to a temporary sibling, then rename. The rename is what makes it atomic: on a POSIX
+ * filesystem it either replaces the destination entirely or does not happen, so a reader gets the
+ * old file or the new one and never a truncated middle.
+ *
+ * TWO properties, and the second is the one that was missing. Five stores in this package built
+ * this by hand and named the temp file after the DESTINATION — `${path}.tmp` — which is shared by
+ * every process writing that path. Two daemons on one repository then write the same temp file:
+ * one truncates the other mid-write and renames the remains into place, and the survivor is a file
+ * neither of them produced. Two other stores already pid-suffixed theirs, so the fix was known and
+ * had simply never been carried to the rest.
+ *
+ * Running parallel agent sessions against one checkout is the ordinary way to reach this, not an
+ * exotic one.
+ *
+ * The temp file stays BESIDE its destination rather than in the system temp directory, because a
+ * rename across devices is not atomic and `/tmp` is routinely a different device.
+ *
+ * One helper rather than five corrected copies: the sixth store gets this for free and cannot get
+ * it wrong, which is the only version of this fix that stays fixed.
+ */
+import type { FileSystemPort } from './fs-port.js';
+export declare function tempNameFor(path: string, pid?: number, seq?: number): string;
+export declare function writeFileAtomic(fs: FileSystemPort, path: string, contents: string): Promise<void>;

package/dist/memory/project/fs/write-atomic.js

@@ -0,0 +1,48 @@
+/**
+ * Unique per WRITE, not per process.
+ *
+ * The pid separates two daemons. It does not separate two concurrent writes inside ONE daemon —
+ * `Promise.all` over two store saves, or two scheduled flushes of the same ledger — and those share
+ * a pid, so a pid-only name puts them straight back on the same temp file. The first version of
+ * this helper had exactly that hole and its own concurrency test found it.
+ *
+ * A counter rather than `Math.random()`: rule 7 keeps the clock and the random source out of pure
+ * logic, and a monotonic counter is deterministic, collision-free within a process, and needs
+ * neither.
+ */
+let writeSeq = 0;
+export function tempNameFor(path, pid = process.pid, seq) {
+    writeSeq += 1;
+    return `${path}.${String(pid)}.${String(seq ?? writeSeq)}.tmp`;
+}
+/**
+ * What Windows answers, for a moment, when another writer is still replacing the destination.
+ * POSIX never refuses such a rename; Windows does, and the save has to wait it out rather than
+ * fail. Seen on Windows CI with two writers on one path.
+ */
+const TRANSIENT_RENAME = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const RENAME_ATTEMPTS = 6;
+const RENAME_BACKOFF_MS = 15;
+function isTransientRename(error) {
+    const code = error?.code;
+    return 'string' === typeof code && TRANSIENT_RENAME.has(code);
+}
+export async function writeFileAtomic(fs, path, contents) {
+    const tmp = tempNameFor(path);
+    await fs.writeFile(tmp, contents);
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            await fs.rename(tmp, path);
+            return;
+        }
+        catch (error) {
+            if (attempt < RENAME_ATTEMPTS && isTransientRename(error)) {
+                await new Promise((resolve) => setTimeout(resolve, RENAME_BACKOFF_MS * attempt));
+                continue;
+            }
+            // The write failed; its temp file must not outlive it.
+            await fs.rm(tmp).catch(() => undefined);
+            throw error;
+        }
+    }
+}

package/dist/memory/recall/prior/connection-memory.d.ts

@@ -63,3 +63,9 @@ export declare function hasAnyAppConnectedBefore(stateDir: string, port: number,
  * diagnosis, which is why it now shares this function instead of keeping a second copy of the rule.
  */
 export declare function hasProjectConnectedBefore(stateDir: string, port: number, projectId: string | undefined): boolean;
+/**
+ * Has any of these projects connected before: the first-move question for a directory that speaks
+ * for more than one app (a monorepo root), or for none by name (an app wired by the plugin alone).
+ * The ids come from `projectIdsAt`; each is still asked the narrow question.
+ */
+export declare function hasAnyProjectConnectedBefore(stateDir: string, port: number, projectIds: readonly string[]): boolean;

package/dist/memory/recall/prior/connection-memory.js

@@ -112,3 +112,11 @@ export function hasProjectConnectedBefore(stateDir, port, projectId) {
         return false;
     return hasAnyAppConnectedBefore(stateDir, port, projectId);
 }
+/**
+ * Has any of these projects connected before: the first-move question for a directory that speaks
+ * for more than one app (a monorepo root), or for none by name (an app wired by the plugin alone).
+ * The ids come from `projectIdsAt`; each is still asked the narrow question.
+ */
+export function hasAnyProjectConnectedBefore(stateDir, port, projectIds) {
+    return projectIds.some((id) => hasProjectConnectedBefore(stateDir, port, id));
+}

package/dist/memory/recall/registered-projects.d.ts

@@ -1,5 +1,5 @@
 /** One project this machine has paired before, in the shape the no-session facts already carry. */
-export interface RegisteredProject {
+interface RegisteredProject {
     directory: string;
     projectId?: string;
 }
@@ -52,3 +52,4 @@ export declare function isUnscopedRoot(directory: string, home: string): boolean
  * reporting it as such would tell a correctly-scoped daemon to go and look somewhere else.
  */
 export declare function registeredElsewhere(home: string, directory: string): RegisteredProject[];
+export {};

package/dist/portal/bridge/auth-failure-reason.js

@@ -28,8 +28,11 @@ const PLAIN = 'authentication failed';
  * before `~/.reticle` was replaced. Both need the same first move: ask `status`, which can say which.
  */
 const WRONG_TOKEN = 'authentication failed: wrong pairing token — run `reticle status` for the cause';
-/** A paste-in snippet or a Next config that never saw a token. Reload cannot mint one. */
-const NO_TOKEN = 'authentication failed: no pairing token on the page';
+/**
+ * A paste-in snippet or a Next config that never saw a token. Reload cannot mint one; restarting the
+ * dev server re-runs the substitution that should have put it there (#1047).
+ */
+const NO_TOKEN = 'authentication failed: no pairing token on the page; the build did not substitute it, so restart the dev server';
 /** WebSocket close reasons are capped at 123 bytes; a longer one throws and closes with nothing. */
 const MAX_REASON_BYTES = 123;
 const DIFFERENT_PROJECT_PREFIX = 'this daemon serves a different project';

package/dist/portal/input/real-input.js

@@ -7,6 +7,7 @@ import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
 import { ActionType, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG } from '@reticlehq/core';
 import { installNetworkMocks } from './network-mock.js';
 import { attachNetworkDetail } from './network-detail.js';
+import { injectedConnectArgs } from '../pool/zero-install.js';
 /** Structured, code-tagged failure so callers branch on cause, not message text. */
 export class DriveError extends Error {
     code;
@@ -338,7 +339,7 @@ export class LaunchedRealInputProvider {
             await page.waitForFunction('!!globalThis.__reticleInstance', {
                 timeout: INJECT_CONNECT_WAIT_MS,
             });
-            const arg = JSON.stringify({ allowNonLocalhost: true, token: opts.token, url: opts.url });
+            const arg = JSON.stringify(injectedConnectArgs(opts));
             await page.evaluate(`globalThis.__reticleInstance.connect(${arg})`);
         }
         catch {

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

@@ -18,6 +18,11 @@ export interface Lease {
     readonly url: string;
     readonly navStatus?: number;
     release(): Promise<void>;
+    /**
+     * Hand the page the zero-install reader: evaluated in the live document, and added ahead of every
+     * document this lease loads next. False when there is no reader, or the page cannot run one.
+     */
+    injectReader?(): Promise<boolean>;
 }
 /** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
 export declare const DEFAULT_LEASE_TTL_MS: number;
@@ -32,6 +37,11 @@ interface BrowserPoolOptions {
     leaseTtlMs?: number;
     /** Per-lease navigation timeout — a page that won't load fails its own lease, never blocks a slot. */
     navTimeoutMs?: number;
+    /**
+     * The zero-install reader, built where the daemon knows its own port and pairing token. A thunk so
+     * the ~450KB build is only read if some page ever needs it; undefined when there is none to give.
+     */
+    zeroInstallScript?: () => string | undefined;
 }
 /**
  * Owns a single browser and leases isolated contexts out of it, capped at `maxContexts`.

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

@@ -30,6 +30,7 @@ export class BrowserPool {
     #genId;
     #now;
     #ttl;
+    #zeroInstall;
     #navTimeout;
     #browser;
     #launching;
@@ -70,6 +71,7 @@ export class BrowserPool {
         this.#now = opts.now ?? (() => Date.now());
         this.#ttl = opts.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
         this.#navTimeout = opts.navTimeoutMs ?? DEFAULT_NAV_TIMEOUT_MS;
+        this.#zeroInstall = opts.zeroInstallScript;
     }
     /** The TTL configured for leases — how long an untouched lease lives before the reaper reclaims it. */
     leaseTtlMs() {
@@ -405,6 +407,14 @@ export class BrowserPool {
                 url,
                 ...(navStatus !== undefined ? { navStatus } : {}),
                 release: () => this.#release(sessionId),
+                injectReader: async () => {
+                    const script = this.#zeroInstall?.();
+                    if (script === undefined || page.evaluate === undefined)
+                        return false;
+                    await page.addInitScript?.(script);
+                    await page.evaluate(script);
+                    return true;
+                },
             };
         }
         catch (err) {

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

@@ -41,6 +41,7 @@ function wrapBrowser(browser) {
                     return {
                         goto: (url, opts) => page.goto(url, gotoOptions(opts?.timeoutMs)),
                         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 })),
                         // Three moves, same as performGesture: a single move to the center can be a no-op if

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

@@ -34,6 +34,8 @@ export interface PooledPage {
      * reports dispatched/settled while the styles never ran.
      */
     hover?(x: number, y: number): Promise<void>;
+    /** Evaluate a script in the page's current document. OPTIONAL: without it no reader is injected. */
+    evaluate?(script: string): Promise<unknown>;
     /** Add an init script to run after document creation but before any page scripts run. */
     addInitScript?<Arg>(script: ((arg: Arg) => void) | string, arg?: Arg): Promise<InitScriptHandle | void>;
     /**

package/dist/portal/pool/storage-seed.d.ts

@@ -2,7 +2,7 @@ import { type SeedStorage } from '@reticlehq/core';
 import type { InitScriptHandle, PooledContext, PooledCookie, PooledPage } from './pool-contract.js';
 export declare function targetOriginOf(navUrl: string): string | undefined;
 export declare function normalizeCookies(cookies: SeedStorage['cookies'], navUrl: string): PooledCookie[];
-export interface StorageSeedResult {
+interface StorageSeedResult {
     handle?: InitScriptHandle;
     checkError?: () => void;
 }
@@ -21,3 +21,4 @@ export interface StorageSeedResult {
  * has resolved, ensuring one-time semantics (reloads or future navigations do not reapply the seed).
  */
 export declare function seedStorageInto(context: PooledContext, page: PooledPage, targetUrl: string, seed: SeedStorage): Promise<StorageSeedResult | void>;
+export {};

package/dist/portal/pool/zero-install.d.ts

@@ -0,0 +1,27 @@
+export interface InjectedConnect {
+    url: string;
+    /** Absent when this daemon runs without a pairing token; the bridge then asks for none. */
+    token?: string;
+}
+/**
+ * The connect options a page is given when WE supply the connection rather than the app.
+ *
+ * One builder for both injection paths — this one, and re-pointing an SDK a hosted preview already
+ * ships (`real-input.ts`) — so the two cannot come to disagree about what a daemon-driven page needs.
+ */
+export declare function injectedConnectArgs(opts: InjectedConnect): Record<string, unknown>;
+/**
+ * The script for a page: install the SDK if the page has none, then connect it to this daemon.
+ *
+ * The guard is on the SINGLETON, not on a timer: a page that loaded its own SDK already holds
+ * `__reticleInstance`, and evaluating a second copy would register a second session for one tab.
+ * `connect` is a no-op once connected, so calling it on the page's own instance is safe.
+ */
+export declare function zeroInstallScript(bundle: string, opts: InjectedConnect): string;
+/**
+ * The single-file build, or undefined when this install has none.
+ *
+ * Read once and kept: it is ~450KB and identical for every lease. Absent means an older browser
+ * package or a broken install, and the caller then behaves exactly as it did before this existed.
+ */
+export declare function readReaderBundle(): string | undefined;

package/dist/portal/pool/zero-install.js

@@ -0,0 +1,54 @@
+/**
+ * The zero-install reader: how a page whose app never ran `init` still reaches a verdict.
+ *
+ * `@reticlehq/browser` builds itself into one file (`dist/reticle-inject.js`). The daemon reads that
+ * file as TEXT and evaluates it in a leased page that never connected, so the server never imports DOM
+ * code and the page needs no build step. What comes back is an ordinary session that reports no
+ * framework adapter and no source mapping, which is the honest description of what it can see.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+/** The subpath `@reticlehq/browser` exports its single-file build under. */
+const READER_SPECIFIER = '@reticlehq/browser/inject';
+/**
+ * The connect options a page is given when WE supply the connection rather than the app.
+ *
+ * One builder for both injection paths — this one, and re-pointing an SDK a hosted preview already
+ * ships (`real-input.ts`) — so the two cannot come to disagree about what a daemon-driven page needs.
+ */
+export function injectedConnectArgs(opts) {
+    return {
+        allowNonLocalhost: true,
+        ...(opts.token === undefined ? {} : { token: opts.token }),
+        url: opts.url,
+    };
+}
+/**
+ * The script for a page: install the SDK if the page has none, then connect it to this daemon.
+ *
+ * The guard is on the SINGLETON, not on a timer: a page that loaded its own SDK already holds
+ * `__reticleInstance`, and evaluating a second copy would register a second session for one tab.
+ * `connect` is a no-op once connected, so calling it on the page's own instance is safe.
+ */
+export function zeroInstallScript(bundle, opts) {
+    const args = JSON.stringify(injectedConnectArgs(opts));
+    return `(() => {\nif (!globalThis.__reticleInstance) {\n${bundle}\n}\nglobalThis.__reticleInstance.connect(${args});\n})();`;
+}
+let cached;
+/**
+ * The single-file build, or undefined when this install has none.
+ *
+ * Read once and kept: it is ~450KB and identical for every lease. Absent means an older browser
+ * package or a broken install, and the caller then behaves exactly as it did before this existed.
+ */
+export function readReaderBundle() {
+    if (cached === undefined) {
+        try {
+            cached = readFileSync(createRequire(import.meta.url).resolve(READER_SPECIFIER), 'utf8');
+        }
+        catch {
+            cached = null;
+        }
+    }
+    return cached ?? undefined;
+}

package/dist/portal/realm/web-realm.js

@@ -93,6 +93,11 @@ export const CHANNEL_OF_PREFIX = {
     // channel at all.
     anim: ProtocolChannel.UI,
     dialog: ProtocolChannel.UI,
+    // A form field's value is on the subject's surface in exactly the sense `ui` means: it is what
+    // the person is looking at and typing into. The protocol has no `input` channel and does not
+    // want one — a field is a rendered thing, and the observation carries the field's NAME and
+    // length, never its contents for a password or a card.
+    field: ProtocolChannel.UI,
     focus: ProtocolChannel.UI,
     render: ProtocolChannel.UI,
     reveal: ProtocolChannel.UI,
@@ -124,6 +129,7 @@ export const NOT_EVIDENCE = {
     context: "Reticle's own context tool opening, not something the application did",
     flow: 'a flow being recorded by the tool',
     human: 'a person driving the HUD: pause, resume, a mark. The operator, not the subject',
+    hud: "usage telemetry about Reticle's own panel, taken off before the buffer. The tool, not the subject",
     page: "the SDK's own health report about the page it is inside",
     sdk: 'the SDK itself failing, which is a fact about the observer',
     transport: "the tool's own buffer overflowing",

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

@@ -25,7 +25,7 @@ export declare const PortState: {
     /** Answered with a document: a dev server serving an app. */
     readonly SERVES_DOCUMENT: "serves-document";
 };
-export type PortState = (typeof PortState)[keyof typeof PortState];
+type PortState = (typeof PortState)[keyof typeof PortState];
 /** The probe's answer for one port, however it was obtained. */
 export declare function classifyPort(port: number, probe: (port: number) => Promise<PortState>): Promise<PortState>;
 /**
@@ -71,3 +71,4 @@ export declare function probeDevServerStates(ports?: readonly number[], probe?:
 }>;
 /** Every candidate port serving a document, in ascending order. Never rejects. */
 export declare function probeDevServers(ports?: readonly number[], probe?: (port: number) => Promise<boolean>): Promise<number[]>;
+export {};

package/dist/portal/session/dev-server/served-document.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The document a local dev server actually serves: its CSP header and HTML, read once and failing
+ * soft. Shared by `doctor` (is a policy blocking the bridge?) and a lease that never dialled (was
+ * it the page's own policy?), which is why it lives beside the dev-server probe and not in either.
+ */
+/** What a served page said about its policy. The same shape `diagnoseObservedWebCsp` reads. */
+export interface ObservedWebDocument {
+    url: string;
+    headers: string[];
+    html: string;
+}
+export type PageRequest = (url: string, init: RequestInit) => Promise<Response>;
+interface ConnectedDocument {
+    url: string;
+    projectId?: string;
+}
+/** A connected tab for this project, or on its observed origin, disproves a CSP diagnosis. */
+export declare function hasConnectedDocument(sessions: readonly ConnectedDocument[], documentUrls: readonly string[], projectId?: string): boolean;
+/** Read the document a live local dev server actually sends, failing soft like the rest of doctor. */
+export declare function observeWebDocument(rawUrl: string, request?: PageRequest): Promise<ObservedWebDocument | undefined>;
+export {};

package/dist/portal/session/dev-server/served-document.js

@@ -0,0 +1,57 @@
+const CSP_HEADER = 'content-security-policy';
+const DOCUMENT_TIMEOUT_MS = 1_000;
+const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
+const requestPage = (url, init) => fetch(url, init);
+function loopbackDocumentUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (!['http:', 'https:'].includes(url.protocol))
+            return undefined;
+        return LOOPBACK_HOSTS.includes(url.hostname) ? url : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function originOf(raw) {
+    try {
+        return new URL(raw).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A connected tab for this project, or on its observed origin, disproves a CSP diagnosis. */
+export function hasConnectedDocument(sessions, documentUrls, projectId) {
+    if (projectId !== undefined && sessions.some((session) => session.projectId === projectId)) {
+        return true;
+    }
+    const origins = new Set(documentUrls.map(originOf).filter((value) => value !== undefined));
+    return sessions.some((session) => {
+        const origin = originOf(session.url);
+        return undefined !== origin && origins.has(origin);
+    });
+}
+/** Read the document a live local dev server actually sends, failing soft like the rest of doctor. */
+export async function observeWebDocument(rawUrl, request = requestPage) {
+    const url = loopbackDocumentUrl(rawUrl);
+    if (url === undefined)
+        return undefined;
+    try {
+        const response = await request(url.href, {
+            redirect: 'error',
+            signal: AbortSignal.timeout(DOCUMENT_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return undefined;
+        const policy = response.headers.get(CSP_HEADER);
+        return {
+            url: url.href,
+            headers: null === policy ? [] : [policy],
+            html: await response.text(),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/portal/session/facts/background-traffic.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Read `background` out of an already-parsed `.reticle.json`: the same-origin endpoints the app calls
+ * on its own (telemetry, heartbeats), which must not hold a settle window open or contradict a claim.
+ *
+ * Takes the record rather than a path, like `readRetainPolicy`, because the config search belongs to
+ * the startup code that already does it once. Never throws, and drops a bad entry rather than the
+ * whole list.
+ */
+export declare function readBackgroundTraffic(config: Record<string, unknown> | undefined): string[];

package/dist/portal/session/facts/background-traffic.js

@@ -0,0 +1,25 @@
+/** The key a project writes in `.reticle.json`. */
+const BACKGROUND_KEY = 'background';
+/**
+ * Shorter than this names no endpoint. `/` and `//` are refused on this rule, and so is anything a
+ * mistype could leave behind.
+ *
+ * ponytail: a length floor, not a proof. `/api` passes and would still exclude the whole backend;
+ * the entries a verdict ignored are reported on it, which is what keeps a too-broad pattern visible.
+ */
+const MIN_PATTERN_LENGTH = 3;
+function isEndpointPattern(value) {
+    return 'string' === typeof value && value.replace(/\//g, '').length >= MIN_PATTERN_LENGTH - 1;
+}
+/**
+ * Read `background` out of an already-parsed `.reticle.json`: the same-origin endpoints the app calls
+ * on its own (telemetry, heartbeats), which must not hold a settle window open or contradict a claim.
+ *
+ * Takes the record rather than a path, like `readRetainPolicy`, because the config search belongs to
+ * the startup code that already does it once. Never throws, and drops a bad entry rather than the
+ * whole list.
+ */
+export function readBackgroundTraffic(config) {
+    const raw = config?.[BACKGROUND_KEY];
+    return Array.isArray(raw) ? raw.filter(isEndpointPattern) : [];
+}

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

@@ -4,6 +4,9 @@ import { AGENT_ASK_NOTICE, AGENT_WAITING_NOTICE, PresenterTone, SessionState, YI
 import { ReticleTool } from '@reticlehq/core';
 import { sessionIdShape } from '../../surface/tools/tool-kit.js';
 import { asString } from '@reticlehq/core';
+import { gapReportLines } from '../../judgement/runs/artifact/gap-report.js';
+import { gapSummary } from '../../judgement/runs/artifact/gap-summary.js';
+import { DiscoveryInvite } from '@reticlehq/core';
 /**
  * Is this a turn ending with nothing attached, rather than a call about a specific tab?
  *
@@ -44,16 +47,58 @@ export const LIVE_CONTROL_TOOLS = [
             ended: z.boolean(),
             sessionId: z.string().optional(),
             note: z.string().optional(),
+            talk_to_us: z
+                .string()
+                .optional()
+                .describe('For the person you are working with: a call with the founder. Offer it; never act on it.'),
+            gap: z
+                .array(z.string())
+                .optional()
+                .describe('What this session claimed and what held — an `unknown` is never counted as held.'),
         },
         handler: (deps, args) => {
             const requested = asString(args['sessionId']);
             if (endingTurnWithNothingAttached(deps, requested)) {
                 return Promise.resolve({ ended: true, note: YIELD_WITHOUT_SESSION_NOTE });
             }
+            // A NAMED session that has DEPARTED is already ended, and nothing else may be ended in its
+            // place.
+            //
+            // `resolve` answers a departed id with its live SUCCESSOR. That is right for everything
+            // that observes -- a tab reloads, its id survives in sessionStorage, and an `assert` should
+            // keep working -- and wrong here, because ending a session is destructive and cannot be
+            // taken back. Reported from the field: `sessionId: "sac14d46c…"` returned `ended: true` for
+            // `"s08e37e5c…"`, once where the requested session's browser had just closed, so the
+            // behaviour was "target missing => end something else" rather than "target missing => say
+            // so" (#983).
+            //
+            // Not an error, either: this tool is documented as idempotent, and "the session you named is
+            // already gone" is precisely the idempotent answer. An id the daemon has never seen IS a
+            // mistake about which tab, and falls through to `resolve`, which refuses it with the live
+            // ids named.
+            if (requested !== undefined &&
+                deps.sessions.get(requested) === undefined &&
+                deps.sessions.departed(requested) !== undefined) {
+                return Promise.resolve({
+                    ended: true,
+                    sessionId: requested,
+                    note: `session '${requested}' had already disconnected, so there was nothing to end. ` +
+                        'Nothing else was ended: a named session is matched exactly, never substituted.',
+                });
+            }
+            // Resolved synchronously, as before: a named session that does not exist still throws here
+            // rather than becoming a rejected promise the caller did not expect.
             const session = deps.sessions.resolve(requested);
-            // One PRESENTER push for the transition; the optional summary rides the same push.
-            session.setState(SessionState.ENDED, asString(args['summary']));
-            return Promise.resolve({ ended: true, sessionId: session.id });
+            const summary = asString(args['summary']);
+            return session.readJournalActions().then((actions) => {
+                // The moment the agent calls the task complete is when "and what did not hold" is worth a
+                // line: the same fold `reticle_context` and `reticle report` serve, so they cannot disagree.
+                const gap = gapReportLines(gapSummary(actions));
+                const panel = [summary, gap[0]].filter((line) => line !== undefined);
+                // One PRESENTER push for the transition; the summary and the gap headline ride together.
+                session.setState(SessionState.ENDED, 0 === panel.length ? undefined : panel.join('\n'));
+                return { ended: true, sessionId: session.id, gap, talk_to_us: DiscoveryInvite.AGENT };
+            });
         },
     },
     {