@reticlehq/server 3.8.0 → 3.8.2

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

@@ -19,7 +19,7 @@
  * the base64 4/3 inflation factor applied, so the encoded payload always fits in one WebSocket
  * frame.
  */
-import { ActionType, DriveErrorCode, ElementState, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, InputMode, InputModeReason, ReticleCommand, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { ActionType, clickInputProblem, DriveErrorCode, ElementState, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, InputMode, 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 { assertNativeAllowed } from '../../portal/production/production-drive.js';
@@ -101,10 +101,12 @@ const UPLOAD_MAX_BYTES = Math.floor((TRANSPORT_LIMITS.MAX_MESSAGE_BYTES / (4 / 3
  * through unchanged. `home` is injected so unit tests do not depend on the machine's real home.
  */
 function expandUserPath(rawPath, home) {
-    if ('~' === rawPath)
+    if ('~' === rawPath) {
         return home;
-    if (rawPath.startsWith('~/') || rawPath.startsWith('~\\'))
+    }
+    if (rawPath.startsWith('~/') || rawPath.startsWith('~\\')) {
         return join(home, rawPath.slice(2));
+    }
     return rawPath;
 }
 /** True when `real` is inside `root` after both have been realpath'd / resolved. */
@@ -132,15 +134,18 @@ async function readUploadRoots(projectRoot, fs, home) {
     catch {
         return [];
     }
-    if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
+    if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed)) {
         return [];
+    }
     const listed = parsed['uploadRoots'];
-    if (!Array.isArray(listed))
+    if (!Array.isArray(listed)) {
         return [];
+    }
     const roots = [];
     for (const entry of listed) {
-        if ('string' !== typeof entry || 0 === entry.trim().length)
+        if ('string' !== typeof entry || 0 === entry.trim().length) {
             continue;
+        }
         roots.push(resolve(expandUserPath(entry.trim(), home)));
     }
     return roots;
@@ -191,11 +196,13 @@ async function resolveUploadPath(rawPath, projectRoot, fs, uploadRoots, home) {
 export async function rewriteUploadArgs(deps, action, innerArgs, 
 /** Injected for tests; production uses the process home directory. */
 home = homedir()) {
-    if (action !== ActionType.UPLOAD)
+    if (action !== ActionType.UPLOAD) {
         return innerArgs;
+    }
     const rawPath = asString(innerArgs['path']);
-    if (rawPath === undefined)
-        return innerArgs; // no path → browser handles as inline upload
+    if (rawPath === undefined) {
+        return innerArgs;
+    } // no path → browser handles as inline upload
     // Project root is one level above .reticle/
     const projectRoot = resolve(join(deps.reticleRoot, '..'));
     const uploadRoots = await readUploadRoots(projectRoot, deps.fs, home);
@@ -236,14 +243,17 @@ function synthetic(reason) {
 function performArgsOf(inner) {
     const performArgs = {};
     const value = asString(inner['value']);
-    if (value !== undefined)
+    if (value !== undefined) {
         performArgs.value = value;
+    }
     const text = asString(inner['text']);
-    if (text !== undefined)
+    if (text !== undefined) {
         performArgs.text = text;
+    }
     const key = asString(inner['key']);
-    if (key !== undefined)
+    if (key !== undefined) {
         performArgs.key = key;
+    }
     const modifiers = inner['modifiers'];
     if (Array.isArray(modifiers)) {
         performArgs.modifiers = modifiers.filter((m) => 'string' === typeof m);
@@ -251,9 +261,14 @@ function performArgsOf(inner) {
     // 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 button = asString(inner['button']);
+    if (button !== undefined) {
+        performArgs.button = button;
+    }
     const holdMs = asNumber(inner['holdMs']);
-    if (holdMs !== undefined)
+    if (holdMs !== undefined) {
         performArgs.holdMs = holdMs;
+    }
     // `keys` and `code` are read but not forwarded: both are routed away by the caller — 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.
@@ -285,11 +300,13 @@ const ANCHOR_FIELDS = [
  */
 async function pressOnLease(deps, session, ref, inner) {
     const pool = deps.pool;
-    if (pool === undefined || !pool.hasKeyboard(session.id))
+    if (pool === undefined || !pool.hasKeyboard(session.id)) {
         return undefined;
+    }
     const unspellable = unspellablePressReason('', inner);
-    if (unspellable !== undefined)
+    if (unspellable !== undefined) {
         return synthetic(unspellable);
+    }
     // What the focused element is called, from the focus act's own report, so the saved step can
     // find it again: the real keyboard reports no element of its own.
     let anchor = {};
@@ -307,8 +324,9 @@ async function pressOnLease(deps, session, ref, inner) {
         }
     }
     const performed = await pool.pressLease(session.id, performArgsOf(inner));
-    if (performed?.performed !== true)
+    if (performed?.performed !== true) {
         return undefined;
+    }
     return {
         result: {
             ...anchor,
@@ -382,15 +400,17 @@ async function hoverForReal(deps, session, ref, inner, provider) {
     if (box === undefined) {
         throw new Error(HOVER_NEEDS_POINTER_MSG);
     }
-    if (!inView)
+    if (!inView) {
         throw new Error(HOVER_OFF_VIEWPORT_MSG);
+    }
     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)
+            if (performed.performed) {
                 return hoverSucceeded(performed.center ?? boxCenter(box), scrolled);
+            }
         }
         catch {
             // A provider error used to fall back to synthetic dispatch. For hover that is a lie.
@@ -428,8 +448,9 @@ export async function tryRealInput(deps, session, ref, action, args) {
     if (provider === undefined) {
         if (action === ActionType.PRESS) {
             const leased = await pressOnLease(deps, session, ref, inner);
-            if (leased !== undefined)
+            if (leased !== undefined) {
                 return leased;
+            }
         }
         // Silent by default: with no provider EVERY action is synthetic, and a reason on all of them is
         // noise on the most-used tool in the product. But an agent that passed native:true asked a
@@ -441,11 +462,13 @@ export async function tryRealInput(deps, session, ref, action, args) {
     // 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)
+        if (unspellable !== undefined) {
             return synthetic(unspellable);
+        }
     }
-    if (!isRealInputAction(action))
-        return synthetic(InputModeReason.NOT_POINTER); // fill/type stay synthetic
+    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
     // off-screen. Opt into a trusted native click with args.native:true (file pickers, clipboard,
@@ -453,6 +476,13 @@ export async function tryRealInput(deps, session, ref, action, args) {
     if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) && !askedForNative) {
         return synthetic(InputModeReason.SYNTHETIC_CLICK_PREFERRED);
     }
+    // The page refuses the same arguments on the synthetic path. A native click must not drop one.
+    if (action === ActionType.CLICK || action === ActionType.DBLCLICK) {
+        const problem = clickInputProblem(action, inner);
+        if (problem !== undefined) {
+            throw new Error(`cannot ${action}: ${problem}`);
+        }
+    }
     // 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.
@@ -466,15 +496,17 @@ export async function tryRealInput(deps, session, ref, action, args) {
     if (action !== ActionType.PRESS && session.versionSkew !== undefined) {
         throw new Error(session.versionSkew);
     }
-    if (!(await provider.isAvailableFor(session.url)))
+    if (!(await provider.isAvailableFor(session.url))) {
         return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
+    }
     const performArgs = performArgsOf(inner);
     // 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)
+            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
@@ -521,13 +553,15 @@ export async function tryRealInput(deps, session, ref, action, args) {
     let box = asBox(inspected);
     // A box outside the viewport after the reveal is a gesture that would land on nothing. The
     // synthetic path scrolls and hit-tests on its own, so it is the honest answer.
-    if (box === undefined || !source.inView)
+    if (box === undefined || !source.inView) {
         return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
+    }
     let toBox;
     if (action === ActionType.DRAG) {
         const toRef = asString(inner['toRef']);
-        if (toRef === undefined)
+        if (toRef === undefined) {
             return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
+        }
         const target = await inspectRevealed(deps, session, toRef);
         const targetInspected = target.inspected;
         // A drag is judged on BOTH ends: dropping onto "Trash" is destructive however innocent the
@@ -549,12 +583,14 @@ export async function tryRealInput(deps, session, ref, action, args) {
             }
         }
     }
-    if (toBox !== undefined)
+    if (toBox !== undefined) {
         performArgs.toBox = toBox;
+    }
     try {
         const performed = await provider.perform(session.url, action, box, performArgs);
-        if (!performed.performed)
+        if (!performed.performed) {
             return synthetic(InputModeReason.PROVIDER_DECLINED);
+        }
         return {
             result: {
                 performed: true,
@@ -566,8 +602,9 @@ export async function tryRealInput(deps, session, ref, action, args) {
         };
     }
     catch {
-        if (session.versionSkew !== undefined)
+        if (session.versionSkew !== undefined) {
             throw new Error(session.versionSkew);
+        }
         return {
             result: undefined,
             settled: false,
@@ -585,8 +622,9 @@ export async function tryRealInput(deps, session, ref, action, args) {
  * A Proxy, not a copy: the session keeps private state its own methods read.
  */
 export function withLeaseKeyboard(deps, session) {
-    if (deps.realInput !== undefined || deps.pool?.hasKeyboard(session.id) !== true)
+    if (deps.realInput !== undefined || deps.pool?.hasKeyboard(session.id) !== true) {
         return session;
+    }
     const command = async (name, args = {}, timeoutMs) => {
         if (ReticleCommand.ACT === name && ActionType.PRESS === args['action']) {
             const ref = asString(args['ref']) ?? '';
@@ -600,8 +638,9 @@ export function withLeaseKeyboard(deps, session) {
     };
     return new Proxy(session, {
         get(target, key) {
-            if ('command' === key)
+            if ('command' === key) {
                 return command;
+            }
             const value = Reflect.get(target, key, target);
             return 'function' === typeof value
                 ? value.bind(target)

package/dist/surface/tools/session-ports.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Provider capabilities handed to features as ports: a suite fixture to seed from, save/restore,
+ * slowing the page and breaking it. Each is `undefined` when the provider cannot do it. They sit on
+ * the tool side because a feature reaching into the input layer directly would depend on a driver.
+ */
+import type { RealInputProvider } from '../../portal/input/real-input.js';
+import { type StorageFixturePort } from '../../portal/input/storage-fixture.js';
+import { type NetworkMutationPort } from '../../portal/input/network-mutation.js';
+import type { Perturbation, SeedStorage } from '@reticlehq/core';
+/**
+ * The state a suite should boot its flows from: whatever the agent is already sitting in.
+ *
+ * This is the join the fixture work was building toward. A suite's flows each start from cold, so
+ * fifty of them prove the login works fifty times — and the flow that LOGS OUT leaves every flow
+ * after it signed out, which no navigation repairs, because the problem is not where the subject is
+ * but what it holds. A seed is applied to an isolated context BEFORE the first navigation, which is
+ * exactly and only when a fixture can work.
+ *
+ * Best-effort, deliberately. A fixture is an OPTIMISATION over running from cold, and running from
+ * cold is correct: a suite that refused to start because a cookie jar could not be read would have
+ * traded a slow answer for no answer. Every "no" here — no provider, no storage support, nothing
+ * driven, a browser that threw, nothing worth seeding — produces the same honest `undefined`, and
+ * the suite runs exactly as it did before any of this existed.
+ */
+export declare function suiteFixtureSeed(realInput: RealInputProvider | undefined, appUrl: string): Promise<SeedStorage | undefined>;
+/**
+ * A way to make this session's page SLOW on purpose, or nothing.
+ *
+ * The third of these seams, for the same reason as the other two: a feature reaching into the input
+ * layer directly is a feature depending on a driver, and the boundary guard asks about it.
+ *
+ * Installs delays and NOTHING else. A rule that carried a status or a body would substitute a
+ * response the server never sent, and an app raced against invented data produces invented races —
+ * a fabricated defect handed to somebody at 3am, which is worse than finding nothing.
+ */
+export declare function sessionPerturbationPort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<{
+    slow(rules: readonly Perturbation[]): Promise<void>;
+    clear(): Promise<void>;
+} | undefined>;
+/**
+ * Save/restore for this session's page, or nothing.
+ *
+ * The same job as `suiteFixtureSeed` next door, stopping one step earlier: that one captures and
+ * converts, this hands back the PORT so a caller can re-apply what it captured later. It lives here
+ * for the reason written above — a feature reaching into the input layer directly is a feature
+ * depending on a driver, and the boundary guard asks about it. It asked.
+ */
+export declare function suiteFixturePort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<StorageFixturePort | undefined>;
+/**
+ * A way to break this session's page, or nothing.
+ *
+ * Sits beside `suiteFixtureSeed` because it is the same shape of job: turning a provider capability
+ * into something a feature can use, on the one side of the graph that is allowed to know about both.
+ * A flow tool reaching into the input layer directly would be a feature depending on a driver, which
+ * is the reach the boundary guard exists to ask about.
+ */
+export declare function sessionMutationPort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<NetworkMutationPort | undefined>;

package/dist/surface/tools/session-ports.js

@@ -0,0 +1,102 @@
+import { fixturePortFor, seedFromStorageState, } from '../../portal/input/storage-fixture.js';
+import { mutationPortFor } from '../../portal/input/network-mutation.js';
+/**
+ * The state a suite should boot its flows from: whatever the agent is already sitting in.
+ *
+ * This is the join the fixture work was building toward. A suite's flows each start from cold, so
+ * fifty of them prove the login works fifty times — and the flow that LOGS OUT leaves every flow
+ * after it signed out, which no navigation repairs, because the problem is not where the subject is
+ * but what it holds. A seed is applied to an isolated context BEFORE the first navigation, which is
+ * exactly and only when a fixture can work.
+ *
+ * Best-effort, deliberately. A fixture is an OPTIMISATION over running from cold, and running from
+ * cold is correct: a suite that refused to start because a cookie jar could not be read would have
+ * traded a slow answer for no answer. Every "no" here — no provider, no storage support, nothing
+ * driven, a browser that threw, nothing worth seeding — produces the same honest `undefined`, and
+ * the suite runs exactly as it did before any of this existed.
+ */
+export async function suiteFixtureSeed(realInput, appUrl) {
+    if (realInput === undefined) {
+        return undefined;
+    }
+    try {
+        const port = await fixturePortFor(realInput, appUrl);
+        if (port === undefined) {
+            return undefined;
+        }
+        return seedFromStorageState(await port.capture(), appUrl);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A way to make this session's page SLOW on purpose, or nothing.
+ *
+ * The third of these seams, for the same reason as the other two: a feature reaching into the input
+ * layer directly is a feature depending on a driver, and the boundary guard asks about it.
+ *
+ * Installs delays and NOTHING else. A rule that carried a status or a body would substitute a
+ * response the server never sent, and an app raced against invented data produces invented races —
+ * a fabricated defect handed to somebody at 3am, which is worse than finding nothing.
+ */
+export async function sessionPerturbationPort(realInput, appUrl) {
+    if (realInput === undefined || appUrl === undefined) {
+        return undefined;
+    }
+    const setMocks = realInput.setMocks?.bind(realInput);
+    if (setMocks === undefined) {
+        return undefined;
+    }
+    if (!(await realInput.isAvailableFor(appUrl))) {
+        return undefined;
+    }
+    return {
+        slow: async (rules) => {
+            await setMocks(appUrl, [...rules]);
+        },
+        /** Clearing is the undo. A page left slowed is damage the next run inherits. */
+        clear: async () => {
+            await setMocks(appUrl, []);
+        },
+    };
+}
+/**
+ * Save/restore for this session's page, or nothing.
+ *
+ * The same job as `suiteFixtureSeed` next door, stopping one step earlier: that one captures and
+ * converts, this hands back the PORT so a caller can re-apply what it captured later. It lives here
+ * for the reason written above — a feature reaching into the input layer directly is a feature
+ * depending on a driver, and the boundary guard asks about it. It asked.
+ */
+export async function suiteFixturePort(realInput, appUrl) {
+    if (realInput === undefined || appUrl === undefined) {
+        return undefined;
+    }
+    try {
+        return await fixturePortFor(realInput, appUrl);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A way to break this session's page, or nothing.
+ *
+ * Sits beside `suiteFixtureSeed` because it is the same shape of job: turning a provider capability
+ * into something a feature can use, on the one side of the graph that is allowed to know about both.
+ * A flow tool reaching into the input layer directly would be a feature depending on a driver, which
+ * is the reach the boundary guard exists to ask about.
+ */
+export async function sessionMutationPort(realInput, appUrl) {
+    if (realInput === undefined || appUrl === undefined) {
+        return undefined;
+    }
+    try {
+        return await mutationPortFor(realInput, appUrl);
+    }
+    catch {
+        // A provider that cannot answer is the same answer as a provider that cannot break anything.
+        return undefined;
+    }
+}

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

@@ -94,6 +94,8 @@ export interface ToolDeps<Ext = unknown> {
         url: string;
         notice: string;
     } | undefined>;
+    /** The one dev server running in the caller's project folder, for a lease that names no url. */
+    projectAppUrl?: () => Promise<string | undefined>;
     /** cross-run outcome memory (.reticle/project.json). */
     project: ProjectStore;
     /** optional native-input provider. undefined ⇒ everything stays synthetic. */
@@ -170,13 +172,13 @@ export interface ToolDeps<Ext = unknown> {
 export interface ToolDef<Ext = unknown> {
     name: string;
     description: string;
-    inputSchema: z.ZodRawShape;
+    inputSchema: Record<string, z.ZodType>;
     /**
      * JSON Schema-compatible output schema for this tool. When present, the MCP server advertises it
      * in the tools/list response so schema-aware clients (like @reticlehq/cli) can validate outputs and
      * compose tool calls safely. Also drives TOON encoding for snapshot/query results.
      */
-    outputSchema?: z.ZodRawShape;
+    outputSchema?: Record<string, z.ZodType>;
     /**
      * One concrete, valid call — the shape, not the prose.
      *
@@ -369,7 +371,7 @@ export declare const SCREENSHOT_DOC = " `screenshot.path` is a picture of the pa
  * Derived from `EnvelopeKey` rather than re-listed: this shape and the splice sites disagreed for a
  * whole release, and every key that went missing was a channel nobody could see was missing.
  */
-export declare const sessionEnvelopeShape: z.ZodRawShape;
+export declare const sessionEnvelopeShape: Record<string, z.ZodType>;
 /** Unwrap a browser command result or throw its error so the agent sees a clean failure. */
 export declare function commandOrThrow(deps: ToolDeps, sessionId: string | undefined, name: ReticleCommand, args: Record<string, unknown>): Promise<unknown>;
 /** Full DOM snapshot → normalized tree lines + route, for tools that diff or scan the page. */

package/dist/surface/tools/tools.js

@@ -324,7 +324,7 @@ export const RAW_TOOLS = withCompactEnvelope([
                 states: z.array(z.string()),
                 visible: z.boolean(),
                 attrs: z
-                    .record(z.string())
+                    .record(z.string(), z.string())
                     .optional()
                     .describe('Present only for attributes requested via `attrs` and found on the element.'),
                 source: z

package/dist/telemetry/daemon-telemetry.d.ts

@@ -5,7 +5,7 @@
  * It lives apart from `cli.ts` because it has its own timers and its own failure rule — nothing here
  * may ever be able to fail a daemon start — and because `cli.ts` is a dispatcher.
  */
-import { type SessionSummary } from '@reticlehq/core/telemetry';
+import { DaemonSpawnMethod, type SessionSummary } from '@reticlehq/core/telemetry';
 /**
  * How often a running daemon rolls up its window.
  *
@@ -29,6 +29,8 @@ export declare const SESSION_FLUSH_MS: number;
  * costs nothing on a daemon that never serves a tool, because only a NON-EMPTY window emits.
  */
 export declare const FIRST_FLUSH_MS: number;
+/** How the parent started this daemon, from the env it set. Anything else reads as absent. */
+export declare function daemonSpawnMethod(env?: Readonly<Record<string, string | undefined>>): DaemonSpawnMethod | undefined;
 /** Stops the timers this installed. Called from the daemon's shutdown path. */
 interface DaemonTelemetry {
     /**

package/dist/telemetry/daemon-telemetry.js

@@ -5,7 +5,8 @@
  * It lives apart from `cli.ts` because it has its own timers and its own failure rule — nothing here
  * may ever be able to fail a daemon start — and because `cli.ts` is a dispatcher.
  */
-import { TelemetryEventKind } from '@reticlehq/core/telemetry';
+import { DaemonSpawnMethod, TelemetryEventKind, } from '@reticlehq/core/telemetry';
+import { ReticleEnv } from '@reticlehq/core';
 import { getTelemetry } from './telemetry.js';
 import { getSessionMetrics } from './session-metrics.js';
 import { profileProject } from './project-profile.js';
@@ -78,6 +79,11 @@ function withNudgeState(summary) {
         ...(nudge.offered === undefined ? {} : { updateOffered: nudge.offered }),
     };
 }
+/** How the parent started this daemon, from the env it set. Anything else reads as absent. */
+export function daemonSpawnMethod(env = process.env) {
+    const value = env[ReticleEnv.SPAWN_METHOD];
+    return Object.values(DaemonSpawnMethod).find((method) => method === value);
+}
 /**
  * Report the daemon as started, profile the project once, and keep the session counters flushing.
  * Every timer is `unref`'d so telemetry can never be the reason a daemon refuses to exit.
@@ -91,7 +97,8 @@ export function installDaemonTelemetry(cwd, now = () => Date.now(),
  */
 port) {
     const metrics = getSessionMetrics(now);
-    void getTelemetry().emit(TelemetryEventKind.DAEMON_STARTED);
+    const spawnMethod = daemonSpawnMethod();
+    void getTelemetry().emit(TelemetryEventKind.DAEMON_STARTED, spawnMethod === undefined ? undefined : { spawnMethod });
     // Reports a past send could not deliver. Off the boot path, and never able to throw into it.
     void drainFeedbackOutbox().catch(() => undefined);
     // Ask npm whether a newer Reticle exists, so the agent can tell the human. Nothing checked before

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,4 @@
-import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type OnboardingStep, type InstallSource, type McpConnection, type McpOutage, type DaemonDeath, type ProxyExit, type WakeRefusal, type ToolRefusal, type AppInstrumentation, type HarnessRun, type HudEvent, type PlatformLink, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
+import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type OnboardingStep, type InstallSource, type McpConnection, type McpOutage, type DaemonDeath, type ProxyExit, type WakeRefusal, type DaemonSpawnMethod, type ToolRefusal, type AppInstrumentation, type HarnessRun, type HudEvent, type PlatformLink, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
 /**
  * Presence of this file marks the MACHINE as the Reticle team's own: every event carries
  * `internal: true`. The persistent twin of `RETICLE_INTERNAL=1`, for a dev machine where setting a
@@ -113,6 +113,8 @@ export interface TelemetryExtra {
     daemonDeath?: DaemonDeath;
     /** `wake_refused`: what held the port. */
     wakeRefusal?: WakeRefusal;
+    /** `daemon_started`: how the parent started the daemon. */
+    spawnMethod?: DaemonSpawnMethod;
     /**
      * `platform_linked`: the workspace just linked. Overrides the envelope's own reading, which looks
      * at the daemon's working directory and not at the project the HUD linked.

package/dist/telemetry/telemetry.js

@@ -470,6 +470,8 @@ export const createTelemetry = (opts) => {
             ...(extra?.proxyExit !== undefined ? { proxyExit: extra.proxyExit } : {}),
             ...(extra?.daemonDeath !== undefined ? { daemonDeath: extra.daemonDeath } : {}),
             ...(extra?.wakeRefusal !== undefined ? { wakeRefusal: extra.wakeRefusal } : {}),
+            // A SCALAR: the event build and the wire schema, no `blocks` entry.
+            ...(extra?.spawnMethod !== undefined ? { spawnMethod: extra.spawnMethod } : {}),
         };
         // The wire schema's caps are only real if something applies them. An event that fails is
         // DROPPED, never sent and never repaired: the payload is exactly what the caps exist to stop.

package/docs/agent-cheatsheet.md

@@ -48,6 +48,7 @@ Two consequences worth knowing:
 
 - **You can assert what a field contains.** Do not read the value with `reticle_look { action: "find" }` and compare it in prose: that produces no verdict and does not count as verification.
 - **`{ role, text }` checks the text,** so it does not match every button with that role.
+- **A `text` predicate reads rendered text, not a field's value.** Text typed into an `<input>` or a `<textarea>` is not on the page as text, so `{ kind: "text", contains }` does not see it. Assert it with `value` on an `element` predicate, as above.
 
 Fields that nothing can check are refused rather than ignored: `by` without a `value`, and `label`, `placeholder`, `testid` or `component` when a higher-precedence field already selected the element. `alt` is the one that can still be checked beside another locator: on an image it is compared with the image's `alt` attribute (so `alt: ""` passes on a decorative image but not on one missing its alt), and on anything that is not an image it is refused, with a hint to use `name`. An element query is a first-match dispatch, not a conjunction.
 
@@ -164,6 +165,17 @@ Recent additions, each of which answers a question agents were previously asking
 2. `reticle_run({ tool: "reticle_domain", args: {} })` learns the app BEFORE testing: the saved flows, what each asserts, and the **gaps** (declared signals/testids that no flow verifies, i.e. untested intent). Tells you what to test and where the real risk is without crawling the whole app. Falls back to `reticle_run({ tool: "reticle_capabilities", args: {} })` for the raw testable surface (`testids`, `signals`, `stores`, `flows`).
 3. Run the loop: **look → act → observe → assert**, cross-checking the 4 layers on anything that matters.
 
+## No MCP tools in this host
+
+A cloud agent or a worker can have a shell and no MCP tools. Use the CLI. `verify --expect` asks a running daemon and never starts one, so start it first:
+
+```bash
+npx @reticlehq/server serve --headless
+npx @reticlehq/server verify http://localhost:5173/ --expect '{"kind":"text","contains":"Welcome"}'
+```
+
+It exits `0` only on `verified: "yes"`. `--expect-file <path>` reads the predicate from a file, and `--timeout N` sets how long it waits (default `4000` ms). To move a connected tab to another page first, run `npx @reticlehq/server open <url> --navigate`. For an action that `--expect` cannot do, use the [HTTP MCP transport](/http-transport).
+
 ## Token note
 
 - **Keep observation cheap.** Prefer `reticle_look { action: "find" }` / scoped or `interactive` `reticle_look { action: "page" }` / `reticle_assert` over dumping the full tree. A full verify loop is ~100 tokens; see [Token efficiency](/token-efficiency) (~73× leaner than full-tree snapshots).

package/docs/cli/gate.mdx

@@ -49,7 +49,7 @@ One `reticle_gate` line. Real capture from this repository, with the flow lists
 }
 ```
 
-`downgraded`, `deletedCoverage`, `unflowed`, `coverageRegressed`, `unexecuted`, `coverageStale` and `coverageAccepted` appear only when they are non-empty, and none was present in that run. The coverage categories need a coverage ledger, which a project gets from `reticle_verify { action: "crawl", exhaustive: true }` or `reticle_verify { action: "coverage", app: true }`; without one they never fire. The CLI prints this as a single line of JSON; it is pretty-printed here to be readable.
+`downgraded`, `deletedCoverage`, `unflowed`, `coverageRegressed`, `unexecuted`, `coverageStale` and `coverageAccepted` appear only when they are non-empty, `flowsWithoutSources` only when it is `true`, and none was present in that run. The coverage categories need a coverage ledger, which a project gets from `reticle_verify { action: "crawl", exhaustive: true }` or `reticle_verify { action: "coverage", app: true }`; without one they never fire. The CLI prints this as a single line of JSON; it is pretty-printed here to be readable.
 
 ## Exit codes
 

package/docs/cli/verify.mdx

@@ -7,7 +7,7 @@ icon: circle-check
 `reticle verify` is the CI command: no model in the loop, no MCP. On a free port it boots the engine in drive mode, waits for the in-page SDK to dial back, replays every saved flow, renders the verdict, and exits. When a Reticle daemon already owns the port, it asks that daemon to replay the flows instead.
 
 ```bash
-npx @reticlehq/server verify <url> [--headed] [--timeout N] [--storage-state <file>]
+npx @reticlehq/server verify <url> [--headed] [--timeout N] [--storage-state <file>] [--expect <json> | --expect-file <path>]
 ```
 
 It uses the same runner and the same verdict as the MCP and HTTP paths, so a platform agent that can only run a shell command gets a byte-identical artifact.
@@ -28,6 +28,13 @@ It uses the same runner and the same verdict as the MCP and HTTP paths, so a pla
 | `--explore` / `--persona "<who does what>"` | boolean / string | off | No saved flows yet? The Harness drives the app and records them. `--persona` implies `--explore`. Needs a linked project (`reticle connect`, or `RETICLE_API_KEY` in CI). It runs at any instrumentation score |
 | `--confirm-dangerous` | boolean | off | Let this run press the controls the replay guard holds as destructive, such as a "Place order" or "Delete" button in a saved flow. Without it such a step is refused, so a checkout flow cannot pass. It covers this run only and is never saved into a flow. |
 
+On Windows PowerShell, write the predicate to a file and pass `--expect-file` so the JSON never goes through shell quoting:
+
+```powershell
+'{"kind":"text","contains":"Saved"}' | Set-Content expect.json
+npx @reticlehq/server verify http://localhost:3000 --expect-file expect.json
+```
+
 ## What it prints
 
 The rendered run report on stdout. On failure it names the cause on stderr instead, and there are two refusals worth knowing:

package/docs/first-drive.md

@@ -72,6 +72,13 @@ node server/dist/command/cli.js verify http://localhost:4310/ --port 4400 \
   --expect '{"kind":"text","contains":"definitely not on this page"}'
 ```
 
+On Windows PowerShell, `npx.cmd` re-parses `--expect '{...}'` and strips the inner quotes. Prefer `--expect-file`:
+
+```powershell
+'{"kind":"text","contains":"Saved"}' | Set-Content expect.json
+npx @reticlehq/server verify http://localhost:3000 --expect-file expect.json
+```
+
 ## 3. Drive it properly, with the tools
 
 If your editor has the Reticle MCP server, the same app is now drivable. The four calls worth knowing, in the order you actually use them:

package/docs/multi-agent-testing.md

@@ -36,6 +36,8 @@ reticle_run { tool: "reticle_lease", args: { action: "release", sessionId } }
 
 `reticle_run { tool: "reticle_lease", args: { action: "acquire" } }` opens a fresh isolated headless context against your **already-running** app, stamps the lease identity into the URL so the app's own SDK registers under a sessionId you can target, and waits until that tab has connected (`ready: true`) before returning, so the sessionId is usable immediately. Release when the flow finishes.
 
+**Lease the exact host that the dev server binds.** `http://localhost:3000` and `http://127.0.0.1:3000` are two origins, and they are not the same address. A dev server that binds only `::1` (Vite can do this for `localhost`) refuses a lease on `127.0.0.1`, and a server that binds only `127.0.0.1` does not answer on `::1`. The two origins also have their own cookies and storage, and a lease is reused for each origin. Copy the url that the dev server prints, host and port included.
+
 ## Permissions
 
 A lease starts with every permission undecided. Pass `permissions` to grant some on the app's origin before the first navigation, so the first render already sees them: