@reticlehq/server 3.5.0 → 3.7.0

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
@@ -66,6 +64,11 @@ export interface PooledPage {
      * existed short of restarting the daemon), because nothing in the stack ever answered it.
      */
     onDialog?(handler: (dialog: PooledDialog) => void): void;
+    /**
+     * Make this the visible tab. OPTIONAL, like `onDialog`: a page opened beside others can start
+     * hidden, and a hidden tab throttles timers and rAF so nothing on it verifies (#1351).
+     */
+    bringToFront?(): Promise<void>;
 }
 /** A native dialog the page opened, handed to the pool so it can be dismissed instead of left blocking. */
 export interface PooledDialog {
@@ -105,14 +108,34 @@ export interface PooledContext {
     newPage(): Promise<PooledPage>;
     close(): Promise<void>;
     addCookies?(cookies: PooledCookie[]): Promise<void>;
+    /**
+     * Grant browser permissions on this context. OPTIONAL, like `addCookies`: a context that cannot
+     * grant makes a lease that asked for permissions refuse, rather than open with none granted while
+     * the caller believes otherwise.
+     */
+    grantPermissions?(permissions: string[], opts?: {
+        origin?: string;
+    }): Promise<void>;
+    /** Drop every permission granted on this context. OPTIONAL, for the same reason. */
+    clearPermissions?(): Promise<void>;
 }
 /** The launched browser. Real Playwright `Browser` satisfies this. */
 export interface PooledBrowser {
     isConnected(): boolean;
-    newContext(): Promise<PooledContext>;
+    /** `ignoreHTTPSErrors` accepts a self-signed or local-CA certificate for this context only. */
+    newContext(opts?: {
+        ignoreHTTPSErrors?: boolean;
+    }): Promise<PooledContext>;
     close(): Promise<void>;
     /** Fires when the browser process dies/crashes so the pool can relaunch on the next acquire. */
     onDisconnected(handler: () => void): void;
 }
 /** 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;
+    /** One image pixel per CSS pixel, so a high-density display does not double a step screenshot. */
+    cssScale?: boolean;
+}

package/dist/portal/session/agent-link.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What the HUD shows about the coding agent: who is attached, and this tab's latest notes to it with
+ * whether an agent's tool call has taken each one. Read from the session's own inbox history, so
+ * "Seen" is shown only for a note that was actually handed to an agent.
+ */
+import { type AgentLink } from '@reticlehq/core';
+import type { InboxMessage } from './human/live-control.js';
+export declare function agentLinkOf(history: readonly InboxMessage[]): AgentLink;

package/dist/portal/session/agent-link.js

@@ -0,0 +1,17 @@
+/**
+ * What the HUD shows about the coding agent: who is attached, and this tab's latest notes to it with
+ * whether an agent's tool call has taken each one. Read from the session's own inbox history, so
+ * "Seen" is shown only for a note that was actually handed to an agent.
+ */
+import { AGENT_NOTE_MAX, AGENT_NOTES_SHOWN } from '@reticlehq/core';
+import { connectedAgents } from '../../hooks/coding-agents.js';
+export function agentLinkOf(history) {
+    return {
+        agents: connectedAgents(),
+        notes: history.slice(-AGENT_NOTES_SHOWN).map((message) => ({
+            text: message.text.slice(0, AGENT_NOTE_MAX),
+            seen: true === message.seen,
+            ...(message.by === undefined ? {} : { by: message.by }),
+        })),
+    };
+}

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,24 @@
+import { CommandActor, MessageKind } from '@reticlehq/core';
+import { currentDrivenBy, harnessOutwardAllowed } 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 }),
+        // The page presses no outward control (invite, send, delete, pay…) the journey did not ask for.
+        ...outwardField(harnessOutwardAllowed()),
+    });
+}
+function outwardField(allowed) {
+    return allowed === undefined ? {} : { outward: { allowed } };
+}

package/dist/portal/session/daemon-answers.d.ts

@@ -1,5 +1,4 @@
 import { log } from '../../log.js';
-import { bindSpanContext } from '../../trace.js';
 /**
  * What the daemon answers when the rules that decide a verdict ask it for something.
  *
@@ -15,6 +14,7 @@ import { bindSpanContext } from '../../trace.js';
 export declare const noteToDaemonLog: typeof log;
 /**
  * Keep a callback belonging to the call that created it, so a re-check scheduled for later still
- * traces back to the wait that asked for it instead of looking like work starting from nowhere.
+ * traces back to the wait that asked for it instead of looking like work starting from nowhere, and
+ * is still the Harness's when the Harness made the call: the HUD files it by who drove it.
  */
-export declare const keepCallerContextInDaemon: typeof bindSpanContext;
+export declare const keepCallerContextInDaemon: <A extends unknown[]>(fn: (...args: A) => void) => ((...args: A) => void);

package/dist/portal/session/daemon-answers.js

@@ -1,5 +1,6 @@
 import { log } from '../../log.js';
 import { bindSpanContext } from '../../trace.js';
+import { bindDrivenBy } from '../../hooks/driven-by.js';
 /**
  * What the daemon answers when the rules that decide a verdict ask it for something.
  *
@@ -15,6 +16,7 @@ import { bindSpanContext } from '../../trace.js';
 export const noteToDaemonLog = log;
 /**
  * Keep a callback belonging to the call that created it, so a re-check scheduled for later still
- * traces back to the wait that asked for it instead of looking like work starting from nowhere.
+ * traces back to the wait that asked for it instead of looking like work starting from nowhere, and
+ * is still the Harness's when the Harness made the call: the HUD files it by who drove it.
  */
-export const keepCallerContextInDaemon = bindSpanContext;
+export const keepCallerContextInDaemon = (fn) => bindDrivenBy(bindSpanContext(fn));

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,22 @@ 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;
+/**
+ * The command that wires THIS project for good: `init`, in the app's own folder, through the
+ * one-off runner the project's package manager ships.
+ *
+ * Handed to an agent whose install never ran `init` (an MCP-only route), so it has to be right first
+ * time: `init` run in a folder that is not the app stops on a missing package.json, and a runner the
+ * machine does not have is "command not found". npx whenever there is doubt — it ships with Node.
+ */
+export declare function initCommandIn(directory: string, read?: (path: string) => string | undefined, listDirs?: (path: string) => readonly string[]): string;

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 { RETICLE_NPM_PACKAGE, desktopLaunch, workspacePackageDirs } from '@reticlehq/init';
 /**
  * Script names checked, in order.
  *
@@ -23,11 +23,27 @@ const DEV_SCRIPTS = ['dev', 'develop', 'start'];
 const LOCKFILES = [
     { file: 'pnpm-lock.yaml', manager: 'pnpm' },
     { file: 'yarn.lock', manager: 'yarn' },
+    { file: 'bun.lockb', manager: 'bun' },
+    { file: 'bun.lock', manager: 'bun' },
 ];
+/** The one-off runner each manager ships, for running Reticle's CLI without installing it. */
+const RUNNER = { pnpm: 'pnpm dlx', bun: 'bunx' };
+const NPX = 'npx';
+const YARN = 'yarn';
+/** `yarn dlx` exists only on Yarn 2+, which is the yarn that writes this file; classic yarn has none. */
+const YARN_BERRY_MARKER = '.yarnrc.yml';
+const YARN_DLX = 'yarn dlx';
+const INIT_VERB = 'init';
 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 +57,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 +84,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 +119,64 @@ 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;
+}
+/**
+ * The command that wires THIS project for good: `init`, in the app's own folder, through the
+ * one-off runner the project's package manager ships.
+ *
+ * Handed to an agent whose install never ran `init` (an MCP-only route), so it has to be right first
+ * time: `init` run in a folder that is not the app stops on a missing package.json, and a runner the
+ * machine does not have is "command not found". npx whenever there is doubt — it ships with Node.
+ */
+export function initCommandIn(directory, read = readTextFile, listDirs = readDirNames) {
+    const manager = packageManager(directory, read);
+    const berry = read(join(directory, YARN_BERRY_MARKER)) !== undefined;
+    const runner = YARN === manager ? (berry ? YARN_DLX : NPX) : (RUNNER[manager] ?? NPX);
+    const command = `${runner} ${RETICLE_NPM_PACKAGE} ${INIT_VERB}`;
+    const app = detectDevCommandInProject(directory, read, listDirs)?.directory;
+    return app === undefined ? command : `cd ${app} && ${command}`;
+}

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/observed-state.d.ts

@@ -1,21 +1,5 @@
 import { type ReticleEvent } from '@reticlehq/core';
 import { type AmbientCounts } from '@reticlehq/engine/window/ambient.js';
-/**
- * The two things a session learns by watching its own event stream, as opposed to storing.
- *
- * Both are LEVELS derived from a stream, and both have to outlive the ring buffer — which is what
- * separates them from the buffer's job and earns them their own unit:
- *
- *   ambient    — which regions of the page move on their own (chat, tickers, live counters). Used by
- *                the settle oracle to ignore background motion, so an action isn't held open forever
- *                by churn it did not cause.
- *   blindSpots — how much of the page the SDK cannot observe (cross-origin frames, closed shadow
- *                roots). The SDK reports these only when the count CHANGES, so a page that mounts
- *                two frames at load announces them once and is silent forever after. Anything that
- *                infers coverage from a window of events therefore sees nothing and concludes the
- *                page was fully observed — a positive claim to have seen what we cannot see. Holding
- *                the level here makes coverage something to ask rather than infer.
- */
 export declare class ObservedState {
     #private;
     /** Fold one already-attributed event into the learned state. */
@@ -57,8 +41,22 @@ export declare class ObservedState {
      * dropped before they reached the observer. Recording it here keeps the honesty contract intact —
      * a verdict over a sampled window says `coverage: partial` rather than implying it saw everything.
      */
-    noteRateLimited(dropped: number): void;
-    blindSpots(): Readonly<Record<string, number>>;
+    noteRateLimited(dropped: number, at?: number): void;
+    /**
+     * How many events the bridge sampled away at or after `since` (session-elapsed ms).
+     *
+     * A bucket is counted when any part of its second reaches the window, so a drop in the same
+     * second as the window's start still impeaches it: erring toward unclean is the safe direction.
+     */
+    rateDroppedSince(since: number): number;
+    /**
+     * The blind spots, session-wide; or, given `since`, with bridge sampling counted only from then on.
+     *
+     * Coverage reads the session-wide view: that sampling happened at all is a fact about the session.
+     * A verdict deciding whether ITS capture is clean reads the windowed one. Read session-wide there,
+     * one early burst made every later verdict on the tab `unclean_capture` (#1414).
+     */
+    blindSpots(since?: number): Readonly<Record<string, number>>;
 }
 /**
  * The snapshot-shaped labels an act reply names its control by: the testid, and `role "name"`.

package/dist/portal/session/facts/observed-state.js

@@ -16,12 +16,18 @@ import { ambientKeyOf } from '@reticlehq/engine/window/ambient.js';
  *                page was fully observed — a positive claim to have seen what we cannot see. Holding
  *                the level here makes coverage something to ask rather than infer.
  */
+/** The resolution rate-limit drops are kept at: per second of session time. */
+const RATE_DROP_BUCKET_MS = 1000;
+/** An hour of seconds; older buckets are past any window a verdict reads. */
+const MAX_RATE_DROP_BUCKETS = 3600;
 export class ObservedState {
     /** What THIS session observed. Never contains seeded history — see seedAmbient. */
     #ownAmbient = {};
     /** What previous sessions learned, kept separate so it is never re-persisted as if newly seen. */
     #seededAmbient = {};
     #blindSpots = {};
+    /** Bridge-side sampling, by second of session time. See noteRateLimited. */
+    #rateDrops = [];
     /** Fold one already-attributed event into the learned state. */
     observe(event) {
         // Only UNATTRIBUTED events count as ambient: an event caused by an action is the action's work,
@@ -124,11 +130,48 @@ export class ObservedState {
      * dropped before they reached the observer. Recording it here keeps the honesty contract intact —
      * a verdict over a sampled window says `coverage: partial` rather than implying it saw everything.
      */
-    noteRateLimited(dropped) {
+    noteRateLimited(dropped, at) {
+        const before = this.#blindSpots[BlindSpotKind.RATE_LIMITED] ?? 0;
         this.#blindSpots[BlindSpotKind.RATE_LIMITED] = dropped;
+        // WHEN, beside how many: the running total above is a fact about the session, and read as one
+        // it made every verdict after a single burst `unclean_capture`, however quiet its own window
+        // was (#1414). Bucketed per second so a sustained flood stays a bounded list.
+        if (at === undefined || dropped <= before)
+            return;
+        const second = Math.floor(at / RATE_DROP_BUCKET_MS) * RATE_DROP_BUCKET_MS;
+        const last = this.#rateDrops[this.#rateDrops.length - 1];
+        if (last !== undefined && last.at === second)
+            last.count += dropped - before;
+        else
+            this.#rateDrops.push({ at: second, count: dropped - before });
+        if (this.#rateDrops.length > MAX_RATE_DROP_BUCKETS)
+            this.#rateDrops.shift();
     }
-    blindSpots() {
-        return this.#blindSpots;
+    /**
+     * How many events the bridge sampled away at or after `since` (session-elapsed ms).
+     *
+     * A bucket is counted when any part of its second reaches the window, so a drop in the same
+     * second as the window's start still impeaches it: erring toward unclean is the safe direction.
+     */
+    rateDroppedSince(since) {
+        let total = 0;
+        for (const bucket of this.#rateDrops) {
+            if (bucket.at + RATE_DROP_BUCKET_MS > since)
+                total += bucket.count;
+        }
+        return total;
+    }
+    /**
+     * The blind spots, session-wide; or, given `since`, with bridge sampling counted only from then on.
+     *
+     * Coverage reads the session-wide view: that sampling happened at all is a fact about the session.
+     * A verdict deciding whether ITS capture is clean reads the windowed one. Read session-wide there,
+     * one early burst made every later verdict on the tab `unclean_capture` (#1414).
+     */
+    blindSpots(since) {
+        if (since === undefined)
+            return this.#blindSpots;
+        return { ...this.#blindSpots, [BlindSpotKind.RATE_LIMITED]: this.rateDroppedSince(since) };
     }
 }
 /**

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?
  *

package/dist/portal/session/first-run-wiring.d.ts

@@ -0,0 +1,42 @@
+export interface WiredStep {
+    mark: string;
+    title: string;
+    target: string;
+}
+export interface WireOutcome {
+    ok: boolean;
+    /** Where init ran. */
+    directory: string;
+    /** Every step of init's plan, applied or not, as it printed them. */
+    steps: WiredStep[];
+    /** The app's url, when init got as far as the dev server. */
+    url?: string;
+    /** Why it stopped, in init's words or ours. */
+    error?: string;
+}
+export interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export type RunCli = (args: readonly string[], cwd: string) => Promise<RunResult>;
+export interface FirstRunWiring {
+    /**
+     * The directory init would run in, or undefined when it cannot be told without guessing: a
+     * daemon started in the home directory or at a filesystem root has no project of its own.
+     */
+    projectDirectory(cwd: string): string | undefined;
+    wire(directory: string): Promise<WireOutcome>;
+}
+export declare function projectDirectoryOf(cwd: string, home?: string, wired?: (dir: string) => boolean): string | undefined;
+/** init's plan lines, and the one JSON object it prints last under `--json`. */
+export declare function readInitOutput(stdout: string): {
+    steps: WiredStep[];
+    result: unknown;
+};
+export declare function firstRunWiring(options: {
+    /** This daemon's port, so init wires the app to it rather than choosing another. */
+    port: number;
+    cliPath: string;
+    run?: RunCli;
+}): FirstRunWiring;