@reticlehq/server 3.5.0 → 3.6.0

package/dist/portal/session/no-session-watch.js

@@ -10,17 +10,19 @@
  * daemon that outlives the agent by hours has no business scanning ports it does not need.
  */
 import { probeRouteStatus } from './dev-server/route-status-probe.js';
-import { probeDevServers, probeDevServerStates } from './dev-server/dev-server-probe.js';
+import { probeDevServerStates } from './dev-server/dev-server-probe.js';
+import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { registeredElsewhere } from '../../memory/recall/registered-projects.js';
 import { explainNoSession } from './no-session-diagnosis.js';
-import { detectDevCommand } from './dev-server/dev-command.js';
+import { detectDevCommandInProject } from './dev-server/dev-command.js';
 import { nextActionFor, renderNextAction } from './no-session-next-action.js';
-import { readProjectFramework, readProjectId, readProjectIsDesktop, readProjectPort, } from '../../command/cli/ports/resolve/cli-port.js';
+import { DEV_SERVER_PORTS, readProjectFramework, readProjectId, readProjectIsDesktop, readProjectPort, } from '../../command/cli/ports/resolve/cli-port.js';
 import { discoverProjectConfigs } from '../../command/cli/config/config-discovery.js';
 import { hasProjectConnectedBefore, rememberConnected, } from '../../memory/recall/prior/connection-memory.js';
 import { isAlive, reticleStateHome } from '../../command/daemon/daemon.js';
-import { daemonsServingProjectElsewhere, splitBrainNote } from '../../command/daemon/daemon-resolve.js';
+import { daemonsServingProjectElsewhere, projectDaemonsElsewhere, projectlessNote, splitBrainNote, } from '../../command/daemon/daemon-resolve.js';
 import { stallUptime } from './stall-clock.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
 import { findOccupiedSiblings } from '../../command/cli/ports/sibling-ports.js';
@@ -47,6 +49,19 @@ function attachFailureClause(port, reason) {
                 'rather than treating this as a problem with the app.'
             : ''));
 }
+/** The port a tombstone URL names, when it names one — anything unparseable names no port. */
+function portOfUrl(url) {
+    try {
+        const raw = new URL(url).port;
+        if ('' === raw)
+            return undefined;
+        const port = Number(raw);
+        return Number.isSafeInteger(port) && port > 0 ? port : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Start the watch. Returns a stop function; the timer is unref'd so it never holds the daemon up.
  *
@@ -54,7 +69,6 @@ function attachFailureClause(port, reason) {
  * through `wireSessionScope`.
  */
 export function startNoSessionWatch(options) {
-    const probe = options.probe ?? (() => probeDevServers());
     let listening = [];
     /**
      * Ports that accepted a connection and then answered nothing in time.
@@ -81,6 +95,7 @@ export function startNoSessionWatch(options) {
     /** Set only when an attempt actually failed, so the diagnosis can say so instead of hiding it. */
     let attachFailure;
     const directory = options.directory ?? process.cwd();
+    const exists = options.exists ?? ((file) => existsSync(join(directory, file)));
     // The boot answer still counts (it is what the daemon scoped its sessions with), but `.reticle.json`
     // is routinely written by `init` AFTER this daemon started, so re-read rather than cache. See the
     // `initialized` comment below, which this shares.
@@ -146,6 +161,9 @@ export function startNoSessionWatch(options) {
      */
     const splitBrain = () => {
         const projectId = readProjectId(directory);
+        if (projectId === undefined) {
+            return projectlessNote(options.port, projectDaemonsElsewhere(options.port, stateDir, isAlive));
+        }
         return splitBrainNote(options.port, daemonsServingProjectElsewhere(projectId, options.port, stateDir, isAlive, (port) => hasProjectConnectedBefore(stateDir, port, projectId)));
     };
     // Every path that registers a session goes through SessionManager.add, so this is the one hook
@@ -172,6 +190,29 @@ export function startNoSessionWatch(options) {
             projectId: readProjectId(directory),
             root: directory,
         }).map((entry) => entry.port));
+    /**
+     * The ports the background scan must cover: the well-known list plus the facts that name THIS
+     * repo's port without guessing it (#1367).
+     *
+     * The scan is machine-wide, so it knows 3000/5173/8080… and nothing about this checkout: with a
+     * Next app already running on :3005 (`next dev -p 3005`) the diagnosis said nothing was listening
+     * and named a command that would have started a duplicate. Three facts name the port instead —
+     * the project's own dev script pins it in its own text, the build plugins announced theirs
+     * (already trusted for auto-attach), and the last session was on one.
+     */
+    const scanPorts = () => {
+        const ports = new Set(DEV_SERVER_PORTS);
+        for (const port of ownDevServerPorts())
+            ports.add(port);
+        const pinned = detectDevCommandInProject(directory)?.port;
+        if (pinned !== undefined)
+            ports.add(pinned);
+        const known = options.sessions.lastKnown?.();
+        const knownPort = known === undefined ? undefined : portOfUrl(known.url);
+        if (knownPort !== undefined)
+            ports.add(knownPort);
+        return [...ports];
+    };
     /**
      * Is `port` demonstrably this project's app? Either its dev server announced it, or this
      * project's own last session was on it. Anything else is a guess, and a guess that opens a
@@ -218,12 +259,13 @@ export function startNoSessionWatch(options) {
         if (running || options.sessions.count() > 0)
             return;
         running = true;
+        const candidates = scanPorts();
         void (options.probe === undefined
-            ? probeDevServerStates().then((states) => {
+            ? probeDevServerStates(candidates).then((states) => {
                 slowListeners = states.slow;
                 return states.serving;
             })
-            : probe())
+            : options.probe(candidates))
             .then(async (ports) => {
             listening = ports;
             siblingListeners =
@@ -294,6 +336,7 @@ export function startNoSessionWatch(options) {
             initialized: scope.initialized,
             ...(scope.configsElsewhere === undefined ? {} : { configsElsewhere: scope.configsElsewhere }),
             previouslyConnected: connectedBefore(),
+            exists,
             // Read when asked, like every other fact here: a page can dial at any moment, and a daemon
             // that cached "nothing has been refused" at boot would keep saying so.
             authRefused: lastCloseWasAuthFailure(),
@@ -307,11 +350,16 @@ export function startNoSessionWatch(options) {
             // command and the sentence beside it name the same page.
             ...(() => {
                 const known = options.sessions.lastKnown?.();
-                return known === undefined ? {} : { lastKnownUrl: known.url };
+                if (known === undefined)
+                    return {};
+                return {
+                    lastKnownUrl: known.url,
+                    ...(known.departedTo === undefined ? {} : { departedTo: known.departedTo }),
+                };
             })(),
             // Read when asked, like everything else here: a `package.json` can gain a dev script, and a
             // daemon that cached "there is none" at boot would keep saying so for the rest of the day.
-            dev: detectDevCommand(directory),
+            dev: detectDevCommandInProject(directory),
         });
     };
     options.sessions.setNoSessionNextAction(() => nextAction(projectScopeFacts()));
@@ -375,7 +423,12 @@ export function startNoSessionWatch(options) {
                 const status = lastKnownStatus !== undefined && lastKnownStatus.url === known.url
                     ? { lastKnownStatus: lastKnownStatus.status }
                     : {};
-                return { lastKnownUrl: known.url, ...status };
+                // Where the tab was seen heading, when the SDK reported it fresh. Kept separate from
+                // lastKnownUrl: the 5xx probe needs the page the tab was ON.
+                const departed = known.departedTo === undefined || '' === known.departedTo
+                    ? {}
+                    : { departedTo: known.departedTo };
+                return { lastKnownUrl: known.url, ...status, ...departed };
             })(),
             // How long this daemon has been waiting with no app. The diagnosis uses it to surface
             // "install never finished" — the same condition telemetry already knows about.

package/dist/portal/session/presence/session-mirror.js

@@ -19,4 +19,7 @@ export function mirroredNarration(sessionId, text) {
 export const MIRRORED_COMMANDS = new Set([
     ReticleCommand.NARRATE,
     ReticleCommand.IMPACT,
+    // A replay usually reloads the page, so its progress has to reach whichever tab is there now.
+    ReticleCommand.FLOW_PROGRESS,
+    ReticleCommand.PLAN,
 ]);

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

@@ -0,0 +1,27 @@
+/**
+ * Which directory the dev server that served a page runs in.
+ *
+ * The tie-breaker for a project several checkouts declare: every git worktree carries the same
+ * committed `.reticle.json`, so the projectId cannot tell them apart, but the process serving the
+ * page runs inside exactly one of them. Lives with the session rather than the artifact resolver
+ * because both observations are about this machine's processes -- daemon state files and `lsof` --
+ * which `memory/project` has no business knowing. The resolver takes the answer as an injected
+ * function; the composition roots pass this one.
+ */
+import { type DevServerEntry } from '@reticlehq/core';
+/** Where `servingDirectoryOf` gets its two observations. Injected so a test needs no processes. */
+export interface ServingDirectoryIo {
+    /** Live dev servers that announced themselves (the Vite plugin writes `devserver-<port>.json`). */
+    devServers: () => readonly DevServerEntry[];
+    /** The working directory of whatever listens on `port`, or null when it cannot be read. */
+    listenerCwd: (port: number) => string | null;
+}
+/**
+ * The directory of the dev server that served `origin`, or undefined when it cannot be observed.
+ *
+ * Two observations, exact one first. A dev server whose plugin announced this port names its own
+ * root and works on every platform. Otherwise the process listening on the port is asked for its
+ * working directory, which covers frameworks with no announcing plugin (Next.js) wherever `lsof`
+ * runs. Loopback only: a remote page's port says nothing about any process on this machine.
+ */
+export declare function servingDirectoryOf(origin: string, io?: ServingDirectoryIo): string | undefined;

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

@@ -0,0 +1,45 @@
+/**
+ * Which directory the dev server that served a page runs in.
+ *
+ * The tie-breaker for a project several checkouts declare: every git worktree carries the same
+ * committed `.reticle.json`, so the projectId cannot tell them apart, but the process serving the
+ * page runs inside exactly one of them. Lives with the session rather than the artifact resolver
+ * because both observations are about this machine's processes -- daemon state files and `lsof` --
+ * which `memory/project` has no business knowing. The resolver takes the answer as an injected
+ * function; the composition roots pass this one.
+ */
+import { isLoopbackHostname } from '@reticlehq/core';
+import { captureLookup, findListenerCwd } from '../../command/cli/ports/port-holder.js';
+import { reticleStateHome } from '../../command/daemon/daemon.js';
+import { readDevServers } from '../../command/daemon/dev-servers.js';
+const DEFAULT_PORT = { 'http:': 80, 'https:': 443 };
+const liveIo = {
+    devServers: () => readDevServers(reticleStateHome()),
+    listenerCwd: (port) => findListenerCwd(port, captureLookup),
+};
+/**
+ * The directory of the dev server that served `origin`, or undefined when it cannot be observed.
+ *
+ * Two observations, exact one first. A dev server whose plugin announced this port names its own
+ * root and works on every platform. Otherwise the process listening on the port is asked for its
+ * working directory, which covers frameworks with no announcing plugin (Next.js) wherever `lsof`
+ * runs. Loopback only: a remote page's port says nothing about any process on this machine.
+ */
+export function servingDirectoryOf(origin, io = liveIo) {
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isLoopbackHostname(url.hostname))
+        return undefined;
+    const port = '' === url.port ? DEFAULT_PORT[url.protocol] : Number(url.port);
+    if (port === undefined)
+        return undefined;
+    const announced = io.devServers().find((entry) => entry.port === port);
+    if (announced !== undefined)
+        return announced.root;
+    return io.listenerCwd(port) ?? undefined;
+}

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

@@ -163,6 +163,13 @@ interface HealthReport {
      * closed list is that an unbounded string can never reach telemetry through it.
      */
     brand: BrowserBrand | undefined;
+    /** Only the keys the page reported, so merging it never erases one an earlier report set. */
+    page: PageIdentity;
+}
+/** Which desktop window a session is, and what its document was served with. */
+export interface PageIdentity {
+    windowLabel?: string;
+    documentStatus?: number;
 }
 /**
  * Narrow a PAGE_HEALTH payload. Every field is optional on the wire — an older SDK does not report

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

@@ -161,6 +161,12 @@ export function readHealthEvent(data) {
         runtime: 'string' === typeof data['runtime'] ? data['runtime'] : undefined,
         engine: 'string' === typeof data['engine'] ? data['engine'] : undefined,
         brand: Object.values(BrowserBrand).find((known) => known === data['brand']),
+        page: {
+            ...('string' === typeof data['windowLabel'] ? { windowLabel: data['windowLabel'] } : {}),
+            ...(Number.isInteger(data['documentStatus'])
+                ? { documentStatus: data['documentStatus'] }
+                : {}),
+        },
     };
 }
 /**

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

@@ -1,4 +1,6 @@
-import type { SessionHealth } from './session-health.js';
+import type { PageIdentity, SessionHealth } from './session-health.js';
+/** A document served as 4xx/5xx — a dev server's 404 page that still mounted the SDK, say. */
+export declare function isErrorDocument(page: PageIdentity | undefined): boolean;
 export interface SessionInfo {
     sessionId: string;
     url: string;
@@ -17,6 +19,10 @@ export interface SessionInfo {
      * not render like it.
      */
     runtime?: string;
+    /** The desktop window's own name (Tauri's label: `main`, `setup`) — absent on a web page. */
+    window?: string;
+    /** Present only when the document was served as an error (4xx/5xx): a 404 page is not the app. */
+    documentStatus?: number;
     /** Present only when the page's SDK version differs from the daemon's — see version-skew.ts. */
     versionSkew?: string;
     /** ms since the SDK last reported anything (silence ⇒ likely throttled). */
@@ -72,6 +78,7 @@ interface SessionView {
     runtime: string | undefined;
     versionSkew: string | undefined;
     hidden: boolean;
+    page?: PageIdentity;
     health: () => SessionHealth;
     staleMs: () => number;
     pendingMarkCount: () => number;

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

@@ -6,6 +6,10 @@
  * it, and separating them keeps the wire-facing shape reviewable on its own.
  */
 import { SESSION_LEASE } from '@reticlehq/core';
+/** A document served as 4xx/5xx — a dev server's 404 page that still mounted the SDK, say. */
+export function isErrorDocument(page) {
+    return (page?.documentStatus ?? 0) >= 400;
+}
 /**
  * Project a live Session into the shape the tools return.
  *
@@ -27,6 +31,8 @@ export function buildSessionInfo(session) {
         hasCapabilities: session.hasCapabilities,
         // Omitted when the page never said, so absence stays readable as "unknown" rather than "web".
         ...(session.runtime === undefined ? {} : { runtime: session.runtime }),
+        ...(session.page?.windowLabel === undefined ? {} : { window: session.page.windowLabel }),
+        ...(isErrorDocument(session.page) ? { documentStatus: session.page?.documentStatus ?? 0 } : {}),
         // On every listing, not buried in a log — skew explains failures that read as app bugs.
         ...(session.versionSkew === undefined ? {} : { versionSkew: session.versionSkew }),
         hidden: session.hidden,

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

@@ -14,6 +14,17 @@ interface ResolveScope {
 }
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export declare function originOf(url: string | undefined): string | undefined;
+/**
+ * Honest, scoped error when sessions exist but none match the agent's project.
+ *
+ * The daemon takes its default scope from the `.reticle.json` of whichever directory started it, so
+ * attaching from a second project — or another worktree of the SAME project — makes every tool
+ * refuse while `reticle_sessions` shows the tab sitting right there. The old message asked "is that
+ * app running with @reticlehq/core enabled?", which is the one thing that is definitely true, so the
+ * reader goes looking at their app instead of at the scope. Name what IS connected and how to
+ * target it: both facts are already in hand here.
+ */
+export declare function scopeMissError(connected: Session[], scope?: ResolveScope): string;
 /** What a refused hello said about itself: the page it was on and the project it claimed. */
 export interface RefusedPage {
     readonly url?: string;
@@ -31,6 +42,16 @@ export declare class SessionManager {
     setDefaultScope(scope: ResolveScope | undefined): void;
     setConnectionRecorder(record: ((projectId: string | undefined) => void) | undefined): void;
     add(session: Session): Session | undefined;
+    /**
+     * Close a window's connection and refuse its id until the daemon restarts.
+     *
+     * Reported from a Tauri app whose hidden windows kept reconnecting: ending the session only ended
+     * the presenter, so the window came straight back. A reload keeps its id (sessionStorage), so the
+     * id is what stays parked; the 1008 close tells the SDK not to retry. Its tombstone goes too, so a
+     * call naming it is refused rather than handed a sibling window.
+     */
+    park(session: Session): void;
+    isParked(sessionId: string): boolean;
     remove(session: Session): boolean;
     get(sessionId: string): Session | undefined;
     /**

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

@@ -4,7 +4,8 @@ import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input
 import { Session } from './session.js';
 import { AttachmentHistory } from './presence/attachment-history.js';
 import { openedBeforeDeparture, pickDocumentSuccessor, } from './session-successor.js';
-import { SESSION_DISCONNECTED_REASON } from './facts/session-replaced.js';
+import { SESSION_DISCONNECTED_REASON, SESSION_PARKED_REASON } from './facts/session-replaced.js';
+import { isErrorDocument } from './session-info.js';
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export function originOf(url) {
     if (url === undefined)
@@ -43,19 +44,31 @@ function scopeSessions(sessions, scope) {
  * reader goes looking at their app instead of at the scope. Name what IS connected and how to
  * target it: both facts are already in hand here.
  */
-function scopeMissError(connected, scope) {
+export function scopeMissError(connected, scope) {
     const who = scope?.projectId !== undefined
         ? `project '${scope.projectId}'`
         : scope?.url !== undefined
             ? `your app at ${scope.url}`
             : 'the active project';
+    const anyUntagged = connected.some((s) => s.projectId === undefined);
+    const anyTagged = connected.some((s) => s.projectId !== undefined);
+    const how = anyUntagged && !anyTagged
+        ? 'with no projectId'
+        : anyUntagged && anyTagged
+            ? 'under a different project or with no projectId'
+            : 'under a different project';
     const listed = connected
-        .map((s) => `'${s.projectId ?? 'untagged'}' (${s.url}, sessionId '${s.id}')`)
+        .map((s) => s.projectId !== undefined
+        ? `'${s.projectId}' (${s.url}, sessionId '${s.id}')`
+        : `(no projectId: the page's connect() carries none) (${s.url}, sessionId '${s.id}')`)
         .join(', ');
-    return (`no browser session for ${who}, but ${String(connected.length)} session(s) ARE connected under a ` +
-        `different project: ${listed}. The daemon scopes to the .reticle.json of the directory it was ` +
-        `started in, so this is a scope mismatch, not a dead app. Pass the sessionId above to target one, ` +
-        `or restart the daemon from that app's directory.`);
+    const advice = anyUntagged
+        ? `Pass the sessionId above to target one, add a projectId to the app's connect() call or ` +
+            `.reticle.json, or restart the daemon from that app's directory.`
+        : `Pass the sessionId above to target one, or restart the daemon from that app's directory.`;
+    return (`no browser session for ${who}, but ${String(connected.length)} session(s) ARE connected ${how}: ` +
+        `${listed}. The daemon scopes to the .reticle.json of the directory it was started in, so ` +
+        `this is a scope mismatch, not a dead app. ${advice}`);
 }
 /**
  * Owns the set of connected browser sessions and the smart auto-selection that resolves which one a
@@ -144,6 +157,24 @@ export class SessionManager {
         const scope = driven.projectId === undefined ? { url: driven.url } : { projectId: driven.projectId };
         return scopeSessions([...this.#sessions.values()], scope).filter((s) => s !== driven);
     }
+    /**
+     * Close a window's connection and refuse its id until the daemon restarts.
+     *
+     * Reported from a Tauri app whose hidden windows kept reconnecting: ending the session only ended
+     * the presenter, so the window came straight back. A reload keeps its id (sessionStorage), so the
+     * id is what stays parked; the 1008 close tells the SDK not to retry. Its tombstone goes too, so a
+     * call naming it is refused rather than handed a sibling window.
+     */
+    park(session) {
+        this.#parked.add(session.id);
+        session.disconnect(SESSION_PARKED_REASON);
+        this.remove(session);
+        this.#tombstones.delete(session.id);
+    }
+    isParked(sessionId) {
+        return this.#parked.has(sessionId);
+    }
+    #parked = new Set();
     remove(session) {
         if (this.#sessions.get(session.id) !== session)
             return false;
@@ -164,10 +195,13 @@ export class SessionManager {
         this.#siblingsAtDeparture.set(session.id, new Set([...this.#sessions.values()]
             .filter((s) => s !== session && openedBeforeDeparture(s, session))
             .map((s) => s.id)));
+        const departedTo = session.departedTo();
         this.#tombstones.set(session.id, {
             id: session.id,
             url: session.url,
             ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
+            // Where the tab was seen heading, kept off `url`: successor matching needs the old origin.
+            ...(departedTo === undefined ? {} : { departedTo }),
         });
         while (this.#tombstones.size > MAX_TOMBSTONES) {
             const oldest = this.#tombstones.keys().next().value;
@@ -495,7 +529,9 @@ export class SessionManager {
         // every call auto-targeted the one tab guaranteed to time out.
         const scored = all.map((s) => ({
             s,
-            score: s.unresponsive() ? 2 : s.throttled() ? 1 : 0,
+            // An error document (a dev server's 404 that still mounted the SDK) ranks below any working
+            // page, hidden or not: it is never the app the agent was asked about.
+            score: s.unresponsive() ? 3 : isErrorDocument(s.page) ? 2 : s.throttled() ? 1 : 0,
             ms: s.lastSeenMs(),
         }));
         const bestScore = Math.min(...scored.map((x) => x.score));

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

@@ -101,7 +101,10 @@ export function endAllSessions(sessions, reason) {
     for (const session of sessions.all()) {
         if (session.isEnded())
             continue;
-        endWithUndelivered(session, reason, PresenterTone.WARN);
+        // WAITING, not WARN: a dropped MCP connection is far more often an agent that finished its turn
+        // than one that crashed, and the daemon cannot tell them apart. Red at the end of every
+        // completed Harness or agent run read as an error the run never had.
+        endWithUndelivered(session, reason, PresenterTone.WAITING);
         ended.push(session.id);
     }
     if (ended.length > 0)

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

@@ -14,6 +14,11 @@ export interface SessionIdentity {
     id: string;
     url: string;
     projectId?: string;
+    /**
+     * Where the tab was seen heading just before it went away (#1256). Separate from `url` — the
+     * old origin — because successor matching must match on where the tab WAS.
+     */
+    departedTo?: string;
 }
 export interface SuccessorClock {
     now: () => number;

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ReticleCommand } from '@reticlehq/core';
+import { HudCorner, HudVisibility, ReticleCommand } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asString } from '@reticlehq/core';
 import { idleMsSchema } from '../../surface/tools/args/numeric-bounds.js';
@@ -12,11 +12,17 @@ import { idleMsSchema } from '../../surface/tools/args/numeric-bounds.js';
 export const SESSION_TOOLS = [
     {
         name: ReticleTool.SESSION_TUNE,
-        description: 'Tune the presenter session for this app. { idleEndMs } sets how long the session stays open after you go quiet before the panel shows the human you are WAITING (your turn). Default 5min — the SLOW backstop; signal handback IMMEDIATELY with reticle_session{action:"yield"} instead of waiting for this. Lower it for snappier auto-handback, raise it for a slow app where long gaps between your tool calls are normal. Enforced SERVER-SIDE (immune to background-tab throttling); it also fires if you (the MCP client) disconnect — so a forgotten or crashed session never leaves the HUD reading "live". Going quiet then acting again revives the session automatically. Returns { applied, idleEndMs }.',
+        description: 'Tune the presenter session for this app. { idleEndMs } sets how long the session stays open after you go quiet before the panel shows the human you are WAITING (your turn). Default 5min — the SLOW backstop; signal handback IMMEDIATELY with reticle_session{action:"yield"} instead of waiting for this. Lower it for snappier auto-handback, raise it for a slow app where long gaps between your tool calls are normal. Enforced SERVER-SIDE (immune to background-tab throttling); it also fires if you (the MCP client) disconnect — so a forgotten or crashed session never leaves the HUD reading "live". Going quiet then acting again revives the session automatically. Also moves the HUD out of your way: { hud: "hidden" | "shown" | "removed" } (removed lasts until the page reloads), or a corner to move it to: { hud: "top-left" }. Use it when the HUD covers a control you must test; say so in your report. Returns { applied, idleEndMs, hud }.',
         inputSchema: {
             idleEndMs: idleMsSchema
                 .optional()
                 .describe('Idle window in milliseconds after which the panel shows WAITING (your turn). Default: 300000 (5 min) — the slow backstop; prefer reticle_session{action:"yield"}. Raise for slow apps.'),
+            hud: z
+                .enum([
+                ...Object.values(HudVisibility),
+                ...Object.values(HudCorner),
+            ])
+                .optional(),
             sessionId: z
                 .string()
                 .optional()
@@ -25,6 +31,7 @@ export const SESSION_TOOLS = [
         outputSchema: {
             applied: z.boolean(),
             idleEndMs: z.number().optional(),
+            hud: z.array(z.string()).optional(),
         },
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
@@ -33,9 +40,25 @@ export const SESSION_TOOLS = [
             // authority), so the agent-set window is honored even when the tab is backgrounded.
             if (idleEndMs !== undefined)
                 session.setIdleEndMs(idleEndMs);
-            const res = await session.command(ReticleCommand.SESSION_CONFIG, idleEndMs !== undefined ? { idleEndMs } : {});
+            // One parameter on the wire to the agent, two to the page: a corner moves it, anything else
+            // shows, hides or removes it.
+            const asked = asString(args['hud']);
+            const isCorner = Object.values(HudCorner).includes(asked);
+            const hud = isCorner ? undefined : asked;
+            const corner = isCorner ? asked : undefined;
+            const res = await session.command(ReticleCommand.SESSION_CONFIG, {
+                ...(idleEndMs === undefined ? {} : { idleEndMs }),
+                ...(hud === undefined ? {} : { hud }),
+                ...(corner === undefined ? {} : { corner }),
+            });
             if (!res.ok)
                 throw new Error(res.error ?? 'session config failed');
+            // Asked to move the HUD and the page says nothing about it: an SDK older than this daemon, or
+            // no HUD mounted. Reported, never `applied: true`: an agent told the HUD moved would test a
+            // control it is still covering.
+            const applied = res.result?.hud;
+            if ((hud !== undefined || corner !== undefined) && !Array.isArray(applied))
+                throw new Error('the page did not apply `hud`: its Reticle SDK predates it, or no HUD is mounted. Update the SDK (npx @reticlehq/server update) or test with the HUD where it is.');
             return res.result ?? { applied: true };
         },
     },

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

@@ -5,9 +5,9 @@ import { LastAct } from './last-act.js';
 import { GapLedger } from '@reticlehq/engine/evidence/gap-ledger.js';
 import { CaptureLedger } from '../../surface/tools/feature-capture.js';
 import { type PageRuntime } from './timing/command-timeout.js';
-import { type SessionHealth } from './session-health.js';
+import { readHealthEvent, type SessionHealth } from './session-health.js';
 export type { SessionHealth };
-import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type JournalAction, type JournalWriteLoss, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
+import { ReticleCommand, PresenterTone, SessionState, type BrowserBrand, type CommandResult, type JournalAction, type JournalWriteLoss, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
 import type { JournalReader, JournalRecorder } from '../../memory/journal/journal-recorder.js';
 import { type EventQueryOptions } from '../../memory/journal/journal-query.js';
 import { type AmbientCounts } from '@reticlehq/engine/window/ambient.js';
@@ -60,9 +60,12 @@ export declare class Session implements HandshakeFacts {
     commands?: readonly string[] | undefined;
     sourceMapping?: boolean | undefined;
     readonly redactKeys: readonly string[];
+    /** The desktop window this is and its document's HTTP status, merged from every PAGE_HEALTH. */
+    readonly page: ReturnType<typeof readHealthEvent>['page'];
     constructor(hello: HelloMessage, socket: WebSocket, clock: Clock);
     /** Milliseconds since this session connected — the authoritative buffer clock. */
     elapsed(): number;
+    departedTo(): string | undefined;
     /** Mark that the SDK was just heard from. Called on every inbound message. */
     touch(): void;
     /** ms since the SDK last reported anything (distinct from elapsed-since-connect). */
@@ -273,6 +276,8 @@ export declare class Session implements HandshakeFacts {
     pushImpact(read: () => ImpactSnapshot | undefined, immediate?: boolean): void;
     pushPresenter(state: SessionState, text?: string, tone?: PresenterTone): void;
     pushNarration(text: string): void;
+    /** A HUD replay's progress, or the Harness's drive plan: pictures the HUD redraws as they change. */
+    pushView(name: typeof ReticleCommand.FLOW_PROGRESS | typeof ReticleCommand.PLAN, args: object): void;
     /** The one-time lease block on the first agent command, then undefined forever after. */
     takeSessionLease(): SessionLease | undefined;
     /**