@reticlehq/server 3.4.0 → 3.6.0

package/dist/surface/tools/platform-moment.js

@@ -0,0 +1,168 @@
+/**
+ * What the agent is told about the Reticle platform, and when. One channel, two audiences.
+ *
+ * A machine that is NOT linked hears about the platform at real moments only, each once per project
+ * and never as an ad: verified runs that exist only here, a flow whose failure history nobody else
+ * can see, and a `.reticle` that has grown large. Each is a fact about the user's own work, with the
+ * one command that changes it.
+ *
+ * A machine that IS linked hears where its work stands: once when the platform first confirms it,
+ * then only when that changes (the platform refused a run, a push failed, or it recovered). Silence
+ * means it is going up. The daemon pushes after every run; an agent can force one with
+ * `reticle_project { push }`.
+ *
+ * Remembered in `.reticle`, so a restarted daemon does not repeat itself. Never throws, never blocks
+ * a verdict, and an embedder with no link port hears nothing.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleDir, Verified } from '@reticlehq/core';
+import { reticleDirPaths } from '../../memory/project/dir/reticle-dir.js';
+import { FlakeFileSchema } from '../../language/flows/recording/flake.js';
+import { SyncStatus, describeSync, overallStatus, readSyncSummary, } from '../../memory/project/sync-status.js';
+/** Verified runs kept only on this machine before the platform is worth a sentence. */
+export const LOCAL_RUNS_MOMENT = 5;
+/** A `.reticle` this large is history worth keeping somewhere other than one laptop. */
+export const LARGE_RETICLE_BYTES = 50 * 1024 * 1024;
+/** A flow that has failed this often has a history worth sharing. */
+const FLAKY_MIN_RUNS = 3;
+/** How often the linked status is re-read: it reads every run, so not on every verdict. */
+const STATUS_EVERY_MS = 10_000;
+/** How many verdicts between size checks: walking `.reticle` is not free either. */
+const SIZE_EVERY = 20;
+const MOMENTS_FILE = ReticleDir.PLATFORM_MOMENTS_FILE;
+const CONNECT = '`npx @reticlehq/server connect`';
+const RUN_FILE = /\.json$/;
+const Moment = {
+    LOCAL_RUNS: 'local-runs',
+    FLAKE: 'flake-history',
+    LARGE: 'large-reticle',
+};
+/** Per root, in this process: what is known, so the file is read once and checks are throttled. */
+const seen = new Map();
+export async function takePlatformMoment(deps, raw, 
+/** The `.reticle` of the project the verdict was about — the session's, not the daemon's. */
+rootOf) {
+    if (!('verified' in raw) || deps.linkedCloud === undefined)
+        return undefined;
+    try {
+        const root = rootOf();
+        const now = (deps.now ?? Date.now)();
+        const entry = seen.get(root) ?? { told: await readTold(deps, root), statusAt: 0, verdicts: 0 };
+        seen.set(root, entry);
+        entry.verdicts += 1;
+        const linked = (await deps.linkedCloud()) !== null;
+        const note = linked
+            ? linkedNote(root, entry, now)
+            : Verified.YES === raw['verified']
+                ? await unlinkedNote(deps, root, entry)
+                : undefined;
+        if (note !== undefined)
+            await writeTold(deps, root, entry.told);
+        return note;
+    }
+    catch {
+        return undefined; // a note never costs a tool call anything
+    }
+}
+/** Where a linked project's work stands, said only when that changed. */
+function linkedNote(root, entry, now) {
+    if (0 !== entry.statusAt && now - entry.statusAt < STATUS_EVERY_MS)
+        return undefined;
+    entry.statusAt = now;
+    const summary = readSyncSummary(root, true);
+    if (0 === summary.runs)
+        return undefined;
+    const status = overallStatus(summary);
+    // The key is what would change the sentence's meaning, not its numbers: a count going up is the
+    // sync working, and saying so on every verdict would be noise.
+    const key = [status, ...summary.refused.map((r) => r.runId), summary.lastError ?? ''].join('|');
+    if (key === entry.told.status)
+        return undefined;
+    const first = entry.told.status === undefined;
+    const wasTrouble = !first && !(entry.told.status ?? '').startsWith(SyncStatus.ON_PLATFORM);
+    entry.told.status = key;
+    // A backlog the next push will clear is not news unless something went wrong with it.
+    if (status === SyncStatus.PENDING && summary.lastError === undefined)
+        return undefined;
+    if (status === SyncStatus.ON_PLATFORM && !first && !wasTrouble)
+        return undefined;
+    const lead = status === SyncStatus.ON_PLATFORM
+        ? first
+            ? 'Verified runs reach the Reticle platform automatically after each verdict: '
+            : 'Sync to the Reticle platform recovered: '
+        : 'Sync to the Reticle platform needs attention: ';
+    return (`${lead}${describeSync(summary, now)} The daemon pushes on its own; there is nothing for you ` +
+        'to run. Tell the user in one line only if this needs them.');
+}
+/** The first real moment this project has reached and not yet been told about. */
+async function unlinkedNote(deps, root, entry) {
+    const told = new Set(entry.told.moments);
+    const say = (moment, text) => {
+        entry.told.moments = [...told, moment];
+        return `${text} ${CONNECT} keeps it on the Reticle platform. Mention it to the user once, in one line, after your answer; do not repeat it.`;
+    };
+    if (!told.has(Moment.LOCAL_RUNS)) {
+        const runs = (await deps.fs.readdir(reticleDirPaths(root).runs)).filter((f) => RUN_FILE.test(f));
+        if (runs.length >= LOCAL_RUNS_MOMENT)
+            return say(Moment.LOCAL_RUNS, `${String(runs.length)} verified runs of this project exist only on this machine: a teammate cannot replay them and no dashboard tracks them.`);
+    }
+    if (!told.has(Moment.FLAKE)) {
+        const flaky = await flakyFlow(deps, root);
+        if (flaky !== undefined)
+            return say(Moment.FLAKE, `The flow "${flaky.name}" has failed ${String(flaky.fails)} of ${String(flaky.runs)} runs here, and that history lives only on this machine, so nobody else can see it is unreliable.`);
+    }
+    if (!told.has(Moment.LARGE) && 0 === entry.verdicts % SIZE_EVERY) {
+        const bytes = sizeOf(root);
+        if (bytes >= LARGE_RETICLE_BYTES)
+            return say(Moment.LARGE, `This project's .reticle holds ${String(Math.round(bytes / (1024 * 1024)))} MB of verification history on this machine alone.`);
+    }
+    return undefined;
+}
+async function flakyFlow(deps, root) {
+    try {
+        const parsed = FlakeFileSchema.safeParse(JSON.parse(await deps.fs.readFile(reticleDirPaths(root).flake)));
+        if (!parsed.success)
+            return undefined;
+        const found = Object.entries(parsed.data.flows).find(([, f]) => f.runs >= FLAKY_MIN_RUNS && 0 < f.fails && f.fails < f.runs);
+        return found === undefined
+            ? undefined
+            : { name: found[0], runs: found[1].runs, fails: found[1].fails };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Bytes under a directory. ponytail: a full walk, sampled every SIZE_EVERY verdicts. */
+function sizeOf(dir) {
+    let total = 0;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        total += entry.isDirectory() ? sizeOf(path) : statSync(path).size;
+    }
+    return total;
+}
+async function readTold(deps, root) {
+    try {
+        const raw = JSON.parse(await deps.fs.readFile(join(root, MOMENTS_FILE)));
+        const strings = (v) => Array.isArray(v) ? v.filter((m) => 'string' === typeof m) : [];
+        // The first version of this file was a bare list of moments.
+        if (Array.isArray(raw))
+            return { moments: strings(raw) };
+        const r = raw;
+        return {
+            moments: strings(r.moments),
+            ...('string' === typeof r.status ? { status: r.status } : {}),
+        };
+    }
+    catch {
+        return { moments: [] };
+    }
+}
+async function writeTold(deps, root, told) {
+    await deps.fs.writeFile(join(root, MOMENTS_FILE), JSON.stringify(told));
+}
+/** Tests only. */
+export function resetPlatformMoments() {
+    seen.clear();
+}

package/dist/surface/tools/query-hint-schema.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+/**
+ * `hint.testidFoundUnder` on a zero-match reticle_query. Declared here, not inline, because tools.ts
+ * is at its line cap; it must still be declared at all, since an undeclared field is stripped from
+ * structuredContent without a word.
+ */
+export declare const TESTID_FOUND_UNDER_SCHEMA: z.ZodOptional<z.ZodString>;

package/dist/surface/tools/query-hint-schema.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+/**
+ * `hint.testidFoundUnder` on a zero-match reticle_query. Declared here, not inline, because tools.ts
+ * is at its line cap; it must still be declared at all, since an undeclared field is stripped from
+ * structuredContent without a word.
+ */
+export const TESTID_FOUND_UNDER_SCHEMA = z
+    .string()
+    .optional()
+    .describe('A TESTID miss whose value IS on the page under another attribute, e.g. data-test-subj: set testIdAttribute in .reticle.json (Vite plugin) or pass it to connect().');

package/dist/surface/tools/read-tools.js

@@ -2,6 +2,7 @@
  * Read / record / replay tools — baselines + diff, recordings + replay, narrate, clock, state,
  * explore. Split out of tools.ts; assembled back via...READ_TOOLS.
  */
+import { UNKEPT_EXPECT } from '../../language/flows/replay.js';
 import { resolveAnnotateTarget } from '../../language/flows/annotate-notes/annotate-target.js';
 import { z } from 'zod';
 import { EventType, ReticleCommand, REPLAY_PROGRAM_VERSION, SnapshotMode, StorageArea, } from '@reticlehq/core';
@@ -161,7 +162,7 @@ export const READ_TOOLS = [
             // Where the journey begins, so a saved flow can navigate here before step 1 instead of
             // replaying from wherever the page happens to be. Pathname only: a host or port belongs to
             // the machine that recorded it, not to the journey.
-            deps.recordings.start(name, cursor, pathnameOf(session.url));
+            deps.recordings.start(name, cursor, pathnameOf(session.url), session.id);
             return Promise.resolve({ recordingName: name, since: cursor });
         },
     },
@@ -223,8 +224,13 @@ export const READ_TOOLS = [
                 }
                 : {};
             const unanchored = 0 < unstable ? unanchoredWarning(unstable) : undefined;
+            // A check that held and could not be saved, said rather than lost (#988).
+            const unkept = rec.steps.filter((st) => st.unkeptExpect !== undefined).length;
+            const lostChecks = 0 < unkept
+                ? `${String(unkept)} step(s) proved a consequence this flow does not keep: ${UNKEPT_EXPECT}.`
+                : undefined;
             const backtrack = recordingBacktrackWarning(routes);
-            const warning = [unanchored, backtrack].filter((part) => part !== undefined);
+            const warning = [unanchored, backtrack, lostChecks].filter((part) => part !== undefined);
             const body = {
                 recordingName: name,
                 program,

package/dist/surface/tools/real-input-attempt.js

@@ -19,11 +19,11 @@
  * the base64 4/3 inflation factor applied, so the encoded payload always fits in one WebSocket
  * frame.
  */
-import { ActionType, InputModeReason, ReticleCommand, TRANSPORT_LIMITS } from '@reticlehq/core';
-import { boxCenter, isPointerAction } from '../../portal/input/real-input.js';
+import { ActionType, DriveErrorCode, InputModeReason, ReticleCommand, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { boxCenter, DriveError, isRealInputAction, unspellablePressReason, } from '../../portal/input/real-input.js';
 import { assertDragNotDestructive, assertNotDestructive } from './act/act-danger.js';
 import { NATIVE_INPUT_ARG } from '@reticlehq/core';
-import { asRecord, asString } from '@reticlehq/core';
+import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { commandOrThrow } from './tool-kit.js';
 import { asBox } from './act/act-helpers.js';
 import { isAbsolute, join, relative, extname, basename, resolve } from 'node:path';
@@ -228,6 +228,13 @@ function synthetic(reason) {
         ? { result: undefined, settled: false }
         : { result: undefined, settled: false, reason };
 }
+/**
+ * Filler for the provider signature, which demands a box on every action.
+ *
+ * No coordinate is derived from it and none is reported back: `performGesture` returns before it
+ * reads the box on a press, because a key addresses focus rather than a point.
+ */
+const PRESS_HAS_NO_BOX = { x: 0, y: 0, width: 0, height: 0 };
 /**
  * Hover without a native pointer is a false success: synthetic mouseover reports dispatched and
  * settled while CSS `:hover` never applies. Same refusal shape as contenteditable — name the gap
@@ -258,8 +265,10 @@ async function hoverForReal(deps, session, ref, inner, provider) {
     if (providerReady && provider !== undefined) {
         try {
             const performed = await provider.perform(session.url, ActionType.HOVER, box, {});
+            // Hover always has a resolved box, so there is always a center to report: the provider's own
+            // reading, or the box's if it reported none. Both are the same point, not a fabricated one.
             if (performed.performed)
-                return hoverSucceeded(performed.center);
+                return hoverSucceeded(performed.center ?? boxCenter(box));
         }
         catch {
             // A provider error used to fall back to synthetic dispatch. For hover that is a lie.
@@ -295,7 +304,14 @@ export async function tryRealInput(deps, session, ref, action, args) {
         // real debugging time, because the tool description promises a reason is "never silent".
         return askedForNative ? synthetic(InputModeReason.NOT_CONFIGURED) : synthetic();
     }
-    if (!isPointerAction(action))
+    // Two `press`es this module will NOT drive, and neither is a fallback — the reason says which
+    // one was asked for, instead of a different gesture being sent. See `unspellablePressReason`.
+    if (action === ActionType.PRESS) {
+        const unspellable = unspellablePressReason(ref, inner);
+        if (unspellable !== undefined)
+            return synthetic(unspellable);
+    }
+    if (!isRealInputAction(action))
         return synthetic(InputModeReason.NOT_POINTER); // fill/type stay synthetic
     // "Don't click, run the code": a click/dblclick runs the occlusion-honest SYNTHETIC path by default
     // even with a provider configured — no coordinate gesture to be intercepted by the HUD or missed
@@ -307,11 +323,85 @@ export async function tryRealInput(deps, session, ref, action, args) {
     // Under version skew CDP is unusable while DOM tools still work (#688). Surface the skew sentence
     // rather than "page not correlated" / a silent provider-error fallback — those send the agent
     // hunting a dead context that is not dead.
-    if (session.versionSkew !== undefined) {
+    //
+    // `press` is exempt, and it is the one action where throwing would take something away: a
+    // document key is dispatched entirely in the page, so it does not need CDP at all and has always
+    // worked under skew. Routing it into real input made it reach this line for the first time, and
+    // throwing here would turn a working synthetic press into a hard failure. It falls through to
+    // `isAvailableFor` instead, and a driver that really is dead answers PROVIDER_ERROR with the
+    // usual `fellBack` — still a signal, just not a refusal.
+    if (action !== ActionType.PRESS && session.versionSkew !== undefined) {
         throw new Error(session.versionSkew);
     }
     if (!(await provider.isAvailableFor(session.url)))
         return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
+    const performArgs = {};
+    const value = asString(inner['value']);
+    if (value !== undefined)
+        performArgs.value = value;
+    const text = asString(inner['text']);
+    if (text !== undefined)
+        performArgs.text = text;
+    const key = asString(inner['key']);
+    if (key !== undefined)
+        performArgs.key = key;
+    const modifiers = inner['modifiers'];
+    if (Array.isArray(modifiers)) {
+        performArgs.modifiers = modifiers.filter((m) => 'string' === typeof m);
+    }
+    // A held key is the whole point of a hold-to-confirm control, and the synthetic path has honoured
+    // `holdMs` all along. Not forwarding it made the real keyboard the WEAKER of the two paths: it
+    // drove the key instantly and reported a hold that never held.
+    const holdMs = asNumber(inner['holdMs']);
+    if (holdMs !== undefined)
+        performArgs.holdMs = holdMs;
+    // `keys` and `code` are read but not forwarded: both are routed away above — a multi-key sequence
+    // and an explicit physical code have no driver spelling — so carrying them into the provider would
+    // only invite it to guess at a gesture the caller did not ask for.
+    // A document key has no element of its own: skip INSPECT and the box entirely.
+    if (action === ActionType.PRESS) {
+        try {
+            const performed = await provider.perform(session.url, action, PRESS_HAS_NO_BOX, performArgs);
+            if (!performed.performed)
+                return synthetic(InputModeReason.PROVIDER_DECLINED);
+            // No `center`: a key addresses focus, not a point. The placeholder's zero happened nowhere.
+            //
+            // `heldMs` IS forwarded, and it is the whole reason this object is not just the three fields
+            // above: `reticle_act`'s description promises `effect.heldMs` reports the hold actually
+            // achieved, and on the real path the act result IS the `effect` block. Dropping it here made
+            // that promise true on the synthetic path and silently false on the one this release added
+            // `holdMs` to — an agent checking for an armed hold-to-confirm control read `undefined`.
+            return {
+                result: {
+                    performed: true,
+                    action,
+                    inputMode: performed.inputMode,
+                    ...(performed.heldMs !== undefined ? { heldMs: performed.heldMs } : {}),
+                },
+                settled: true,
+            };
+        }
+        catch (error) {
+            // The ONE failure that must not fall back. Every other throw means the gesture did not
+            // happen, and the synthetic path is the honest answer. A release that failed means the
+            // gesture DID happen and the key may still be down — replaying it synthetically presses the
+            // same key a second time on top of a keyboard that is already holding something, which is
+            // the corruption the release exists to prevent. Refusing is the only answer that cannot
+            // make it worse.
+            if (error instanceof DriveError && error.code === DriveErrorCode.RELEASE_FAILED) {
+                throw error;
+            }
+            // No skew re-throw here, unlike the pointer path below: this action has a working synthetic
+            // route (see the skew check above), so the honest answer to a driver that threw is the
+            // fallback, not a refusal.
+            return {
+                result: undefined,
+                settled: false,
+                fellBack: true,
+                reason: InputModeReason.PROVIDER_ERROR,
+            };
+        }
+    }
     const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
     assertNotDestructive(action, inner, inspected);
     const box = asBox(inspected);
@@ -332,13 +422,6 @@ export async function tryRealInput(deps, session, ref, action, args) {
         if (toBox === undefined)
             return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
     }
-    const performArgs = {};
-    const value = asString(inner['value']);
-    if (value !== undefined)
-        performArgs.value = value;
-    const text = asString(inner['text']);
-    if (text !== undefined)
-        performArgs.text = text;
     if (toBox !== undefined)
         performArgs.toBox = toBox;
     try {

package/dist/surface/tools/tool-kit.d.ts

@@ -4,6 +4,7 @@
  * in its own leaf module (no dependency on any tool array) so the per-group tool files can import it
  * without a circular import — `tools.ts` assembles the groups and re-exports `ToolDef`/`ToolDeps`.
  */
+import type { FirstRunWiring } from '../../portal/session/first-run-wiring.js';
 import { z } from 'zod';
 import { type ProjectId, ReticleCommand } from '@reticlehq/core';
 import type { SessionManager } from '../../portal/session/session-manager.js';
@@ -59,6 +60,25 @@ export interface ToolDeps<Ext = unknown> {
      * `tools.ts`, which keeps every existing `ToolDeps` construction working unchanged.
      */
     snapshots?: SnapshotCache;
+    /**
+     * The skew between THIS client's MCP server and the daemon, told once to this connection only.
+     *
+     * Per attach for the same reason as `snapshots`: one daemon serves every agent on the machine, and
+     * a daemon-wide queue handed one agent's "restart your MCP server" to whichever agent called next,
+     * whose server matched (#1136). Absent ⇒ this connection's server matched, or it did not announce.
+     */
+    peerSkew?: {
+        take(): string | undefined;
+    };
+    /**
+     * Who is asking: one id per MCP attach. A browser lease is handed back only to the attach that took
+     * it, so two agents on one origin never share a tab (#1226). Absent ⇒ every acquire gets its own.
+     */
+    attachId?: string;
+    /** Run one sync cycle with the platform now, for `reticle_project { push }`. Absent: not linked here. */
+    syncNow?: () => Promise<unknown>;
+    /** Wires the app on the agent's first use, instead of at installation. Absent: tell, do not wire. */
+    firstRun?: FirstRunWiring;
     /** cross-run outcome memory (.reticle/project.json). */
     project: ProjectStore;
     /** optional native-input provider. undefined ⇒ everything stays synthetic. */
@@ -80,7 +100,7 @@ export interface ToolDeps<Ext = unknown> {
      * embedding this engine may not have a filesystem to search. Absent ⇒ `reticleRoot`, which is
      * exactly today's behaviour.
      */
-    artifactRootFor?: (projectId: ProjectId | undefined) => ArtifactRoot;
+    artifactRootFor?: (projectId: ProjectId | undefined, origin?: string) => ArtifactRoot;
     /**
      * A verification run just landed — wake cloud sync instead of waiting for its next tick.
      *
@@ -231,6 +251,10 @@ export declare const EnvelopeKey: {
     readonly VERSION_SKEW: "version_skew";
     /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */
     readonly FEEDBACK_UNDELIVERED: "feedback_undelivered";
+    /** Once per project: verified runs exist only on this machine. See platform-moment.ts. */
+    readonly PLATFORM: "platform";
+    /** The one thing to do next: declare the request, yield, fix sync, connect. See next-step.ts. */
+    readonly NEXT: "next";
 };
 export type EnvelopeKey = (typeof EnvelopeKey)[keyof typeof EnvelopeKey];
 /**

package/dist/surface/tools/tool-kit.js

@@ -1,9 +1,3 @@
-/**
- * Shared kit for the MCP tool modules — the tool shape, the dependency bag, the common
- * session-id arg, and the two helpers (commandOrThrow, snapshotTree) every tool group needs. Lives
- * in its own leaf module (no dependency on any tool array) so the per-group tool files can import it
- * without a circular import — `tools.ts` assembles the groups and re-exports `ToolDef`/`ToolDeps`.
- */
 import { z } from 'zod';
 import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
 import { normalizeLines } from '../../memory/project/baselines.js';
@@ -84,6 +78,10 @@ export const EnvelopeKey = {
     VERSION_SKEW: 'version_skew',
     /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */
     FEEDBACK_UNDELIVERED: 'feedback_undelivered',
+    /** Once per project: verified runs exist only on this machine. See platform-moment.ts. */
+    PLATFORM: 'platform',
+    /** The one thing to do next: declare the request, yield, fix sync, connect. See next-step.ts. */
+    NEXT: 'next',
 };
 /**
  * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime.

package/dist/surface/tools/tools.js

@@ -1,5 +1,7 @@
+import { TESTID_FOUND_UNDER_SCHEMA } from './query-hint-schema.js';
 import { z } from 'zod';
-import { DiscoveryInvite, AttrNamesSchema, EventType, NoSessionAction, QueryBy, ReticleCommand, SnapshotMode, } from '@reticlehq/core';
+import { EMPTY_SESSION_LIST_OUTPUT, emptySessionList } from './empty-session-list.js';
+import { AttrNamesSchema, EventType, QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { withSizeCost } from '../../portal/session/output-budget.js';
 import { applySnapshotDelta, SnapshotCache } from './read/snapshot-delta.js';
@@ -82,6 +84,11 @@ export const RAW_TOOLS = [
                     .string()
                     .optional()
                     .describe("Present only when this page's SDK version differs from the daemon's. A skewed pair connects and then disagrees about tool behaviour — usually surfacing as a bare -32000. Fix it before trusting any verdict from this session."),
+                window: z.string().optional().describe('Desktop window label (Tauri: main, setup…).'),
+                documentStatus: z
+                    .number()
+                    .optional()
+                    .describe('Set only for an error page (4xx/5xx): not the app, never auto-selected first.'),
                 lastSeenMs: z.number(),
                 throttled: z.boolean(),
                 focused: z.boolean(),
@@ -112,30 +119,7 @@ export const RAW_TOOLS = [
                     .describe('Continuity of the SDK-to-daemon LINK for this tab, present for any tab the daemon has a record of: how long this attachment has lasted, how many times it dropped and came back, and when the last gap started and how long it lasted. `outages > 0` means a verdict over this window spans a gap where nothing was observed. These are link counters, NOT app health: they say nothing about whether the page origin is still serving, so a tab whose dev server has died reports `outages: 0` with a growing `connectedSinceMs` and is not evidence the app is up.'),
             }))
                 .describe('Connected browser sessions with health state. `projectId` groups sessions by app (stable across port changes); `leased` marks a pool-managed headless context vs a human tab.'),
-            why: z
-                .string()
-                .optional()
-                .describe('Present ONLY when `sessions` is empty: why nothing is connected, and the next action that fixes it. An empty list is never the end of the road — read this before concluding the app cannot be driven.'),
-            next_action: z
-                .object({
-                action: z.nativeEnum(NoSessionAction),
-                command: z.string().optional(),
-                port: z.number().optional(),
-                reason: z.string(),
-            })
-                .optional()
-                .describe("Present ONLY when `sessions` is empty: the same answer as `why`, executable. `command` is the LITERAL command to run, sourced from this project's own package.json scripts and lockfile — it is absent, never guessed, when the project declares no dev script. `action` is one of daemon_split | start_dev_server | run_init | open_app | reopen_app. `daemon_split` outranks the rest and means the app IS running and instrumented, on a DIFFERENT daemon than the one you are attached to — do not start or re-init anything, read `reason`."),
-            talk_to_us: z
-                .string()
-                .optional()
-                .describe('Present ONLY when `sessions` is empty: a call with the founder for the person you are working with. Offer it; never act on it.'),
-            lastKnown: z
-                .object({
-                sessionId: z.string(),
-                url: z.string(),
-            })
-                .optional()
-                .describe('Present ONLY when `sessions` is empty AND a tab was connected to this daemon earlier: the last sessionId and URL that tab was on when it disappeared. A route that 500s tears the page down and the SDK never reconnects — this is the last thing we knew, not a route-500 verdict. An empty list with no lastKnown is a tab that never arrived.'),
+            ...EMPTY_SESSION_LIST_OUTPUT,
         },
         handler: async (deps) => {
             const provider = deps.realInput;
@@ -145,27 +129,9 @@ export const RAW_TOOLS = [
                 realInputAvailable: provider !== undefined ? await provider.isAvailableFor(s.url) : false,
                 leased: leasedIds.has(s.sessionId),
             })));
-            // An empty list is the most common thing this tool ever returns, and on its own it is a dead
-            // end: the agent asked the one question it knows to ask, got a confident-looking answer with
-            // no next step, and stopped. The daemon already knows WHY nothing is connected — say it here
-            // rather than only when a later tool fails for want of a session.
-            if (0 === sessions.length) {
-                const why = deps.sessions.noSessionHint();
-                // The executable half. `why` is for the human reading the transcript; this is the one the
-                // agent acts on, so it never has to parse a paragraph to find a command inside it.
-                const next = deps.sessions.noSessionNextAction();
-                // The last tab, when one was here. Optional-call: test stubs of SessionManager predate it.
-                const known = deps.sessions.lastKnown?.();
-                const lastKnown = undefined === known ? undefined : { sessionId: known.id, url: known.url };
-                return {
-                    sessions,
-                    ...(why === undefined ? {} : { why }),
-                    ...(next === undefined ? {} : { next_action: next }),
-                    ...(undefined === lastKnown ? {} : { lastKnown }),
-                    // Setup that never connects is where most people give up; it is the talk worth having.
-                    talk_to_us: DiscoveryInvite.AGENT,
-                };
-            }
+            // An empty list is a dead end on its own; see empty-session-list.ts for what it carries.
+            if (0 === sessions.length)
+                return emptySessionList(deps, sessions);
             return { sessions };
         },
     },
@@ -400,6 +366,7 @@ export const RAW_TOOLS = [
                     .array(z.string())
                     .optional()
                     .describe('Present when a ROLE+NAME search missed and that role DOES carry a nearly-matching name — role+name is exact, so "Mesh" does not find "2 Mesh". Retry with one of these spellings; no snapshot needed.'),
+                testidFoundUnder: TESTID_FOUND_UNDER_SCHEMA,
             })
                 .optional()
                 .describe('Present only on zero matches — tells you what IS on the page so you can diagnose the miss.'),
@@ -522,7 +489,10 @@ export const MERGE_PLANS = [
         // whatever comes first is what an agent discovers; when this sentence opened with `tune` the
         // MANDATORY handback sat past the cut and no agent reading the catalogue ever learned it
         // existed. The rule is: if a tool has an obligation, the obligation goes first.
-        'Session lifecycle and the human channel, by action: "yield" hands control back to the human and is MANDATORY before you stop driving (mode: waiting|ask, between turns); "tune" adjusts the presenter session (e.g. idle-end window); "end" terminates the session for good; "resume" clears a human pause; "messages" drains the human→agent inbox; "review" lists/resolves the mistakes a human pinned to elements; "narrate" states your intent on the presenter HUD.',
+        // The first sentence is all a lean surface shows (160 characters), so it carries the
+        // obligation and the HUD control; the rest is the detail for a full one.
+        'By action: "yield" is MANDATORY before you stop driving; "tune" hides or moves the HUD, or sets the idle window. ' +
+            'In full: "yield" hands control back to the human (mode: waiting|ask, between turns); "tune" takes `hud` (hidden, shown, removed until reload, or a corner) for when the HUD covers a control you must test, and `idleEndMs`; "end" terminates the session for good; "resume" clears a human pause; "messages" drains the human→agent inbox; "review" lists/resolves the mistakes a human pinned to elements; "narrate" states your intent on the presenter HUD.',
         members: {
             tune: ReticleTool.SESSION_TUNE,
             yield: ReticleTool.YIELD,
@@ -538,7 +508,7 @@ export const MERGE_PLANS = [
     },
     {
         name: ReticleTool.VERIFY,
-        description: 'What is proved, and what is not — by action. Start from a change: { action: "affected" } names which saved flows must re-verify for the files you edited (pass `files`, and/or `since` for a git ref), and "change" goes further and actually replays them, answering with one `verified` plus `because`. `unknown` there is the honest answer when NO saved flow covers the change: nothing ran, so nothing was proved, and it is never reported as green. Without a change to start from: "flows" replays every saved flow for one consolidated suite verdict (deterministic, no LLM per flow), and "coverage" lists the interactive controls you have and have NOT driven this session — an untouched list still holding the controls your change affects means you are not done. "crawl" is the no-script option: it drives every reachable control itself and reports single-channel faults (console errors, failed requests, dead controls) and CONTRADICTIONS, two channels disagreeing about the same click — the false greens a human cannot see, because a human watches the screen and the screen looks correct. "explore" is the one to reach for on a project with NO saved flows: a model inside the daemon drives the app for you — pass a `persona` and it completes that whole journey — and RECORDS what it drove, so the next run replays it with no model in the loop and none of the driving costs your context. "mutate" grades the FLOW rather than the app: it breaks the endpoint a saved flow declared it depends on and replays it, and a flow that stays GREEN through a broken subject is a click sequence, not a test. "heal" repairs a flow whose LOCATOR drifted (a renamed testid), re-asserting the saved consequence before it writes and refusing when that stops firing — it heals a locator, never an intent. DESTRUCTIVE: crawl and explore really click, and may navigate or mutate state; "mutate" really fails a request on a driven page, and always puts it back.',
+        description: 'What is proved, and what is not — by action. Start from a change: { action: "affected" } names which saved flows must re-verify for the files you edited (pass `files`, and/or `since` for a git ref), and "change" goes further and actually replays them, answering with one `verified` plus `because`. `unknown` there is the honest answer when NO saved flow covers the change: nothing ran, so nothing was proved, and it is never reported as green. Without a change to start from: "flows" replays every saved flow for one consolidated suite verdict (deterministic, no LLM per flow), and "coverage" lists the interactive controls you have and have NOT driven this session — an untouched list still holding the controls your change affects means you are not done. "crawl" is the no-script option: it drives every reachable control itself and reports single-channel faults (console errors, failed requests, dead controls) and CONTRADICTIONS, two channels disagreeing about the same click — the false greens a human cannot see, because a human watches the screen and the screen looks correct. "explore" is the one to reach for on a project with NO saved flows: the Reticle Harness drives the app for you on the platform — pass a `persona` and it completes that whole journey — and RECORDS what it drove, so the next run replays it with no model in the loop and none of the driving costs your context. "mutate" grades the FLOW rather than the app: it breaks the endpoint a saved flow declared it depends on and replays it, and a flow that stays GREEN through a broken subject is a click sequence, not a test. "heal" repairs a flow whose LOCATOR drifted (a renamed testid), re-asserting the saved consequence before it writes and refusing when that stops firing — it heals a locator, never an intent. DESTRUCTIVE: crawl and explore really click, and may navigate or mutate state; "mutate" really fails a request on a driven page, and always puts it back.',
         members: {
             change: ReticleTool.VERIFY_CHANGE,
             flows: ReticleTool.FLOW_VERIFY,
@@ -804,6 +774,8 @@ export const MERGED_SURFACE_PLANS = [
             // surface: on the default one `reticle_sessions` still exists and this tool is purely
             // lifecycle, where no member is the obvious bare meaning.
             defaultAction: 'list',
+            description: 'By action: "list" (the default) shows connected tabs; "yield" is MANDATORY before you stop; "tune" hides or moves the HUD; "feedback" reports a problem. ' +
+                'In full: "list" is the first call to make, and on a project that has never connected it wires the app and names the files it changed under `wired`; "yield" hands control back to the human (mode: waiting|ask); "tune" takes `hud` (hidden, shown, removed until reload, or a corner) for when the HUD covers a control you must test, and `idleEndMs`; "feedback" files a report; "end", "resume", "messages", "review" and "narrate" manage the session and the human channel.',
         }
         : plan),
     ...SURFACE_MERGE_PLANS,

package/dist/telemetry/argument-shape.js

@@ -27,7 +27,7 @@ import { ActionType, FeedbackKind, QueryBy, SnapshotMode } from '@reticlehq/core
 const SAFE_ENUM_PARAMS = new Map([
     // Every entry DERIVED from the enum core already owns, never hand-listed. The first version listed
     // them literally and was wrong on the day it shipped, not merely at risk: `action` was missing
-    // `fill`, `dblclick`, `submit`, `scrollIntoView`, `drag` and `webmcp` — so `fill`, one of the most
+    // `fill`, `dblclick`, `submit`, `scrollIntoView` and `drag` — so `fill`, one of the most
     // common actions there is, silently reported as `other` — while carrying a `scroll` that
     // `ActionType` does not define. `mode` mixed SnapshotMode with unrelated session-lifecycle values.
     // Deriving is not tidiness here; it is the difference between the data being right and being wrong.

package/dist/telemetry/hud-metrics.d.ts

@@ -19,6 +19,8 @@ export interface HudSummary {
     hudJourney?: string[];
     /** Present, and true, only when the journey was cut. */
     hudJourneyCut?: true;
+    /** Times each rail slide became the visible one. Slide ids are Reticle's own, never page text. */
+    hudSlides?: Record<string, number>;
 }
 export declare class HudMetrics {
     #private;