@reticlehq/server 3.2.0 → 3.4.0

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

@@ -25,6 +25,8 @@ function paramInfo(shape) {
 function unknownParamsError(toolName, unknown) {
     return `unknown ${1 === unknown.length ? 'parameter' : 'parameters'} for ${toolName}: ${unknown.join(', ')} — NOT applied, so any result would be an answer to a different question`;
 }
+/** The one `action` reticle_tools takes: every other tool on the surface is action-dispatched. */
+const TOOLS_LIST_ACTION = 'list';
 /** What to write instead — the one parameter reticle_tools declares, and the no-argument form. */
 const TOOLS_ARG_HINT = 'name the tools you want in `names`: reticle_tools { names: ["reticle_act_and_wait"] } — or call it with no arguments for the full catalog';
 /** The keys not declared by `shape`, in call order. */
@@ -92,6 +94,10 @@ callable) {
             },
         };
     const toolsShape = {
+        action: z
+            .literal(TOOLS_LIST_ACTION)
+            .optional()
+            .describe('"list": the catalogue, same as no arguments.'),
         names: z
             .array(z.string())
             .optional()

package/dist/surface/tools/error-recovery.js

@@ -67,7 +67,7 @@ export const RECOVERY = {
     UNKNOWN_SESSION: 'That sessionId is not connected. Call reticle_sessions for the current ids and retry with a valid one.',
     THROTTLED: 'The target tab is backgrounded/throttled, so actions may silently no-op. Ask the human to bring ' +
         'the tab to the front, or acquire a guaranteed scriptable context yourself with ' +
-        '`reticle_run { tool: "reticle_lease", action: "acquire", url }` (a human can equivalently run ' +
+        '`reticle_run { tool: "reticle_lease", args: { action: "acquire", url } }` (a human can equivalently run ' +
         '`reticle drive <url>`).',
     MISSING_BASELINE: 'That baseline does not exist yet. Call reticle_baseline { action: "list" } to see saved names, or ' +
         'reticle_baseline { action: "save", name } to capture one before diffing against it.',
@@ -159,7 +159,7 @@ export const RECOVERY = {
         'assert on the result instead of typing it. Known gap, already reported: no need to file it.',
     HOVER_NEEDS_POINTER: 'Hover needs a real pointer: a synthetic mouseover does not apply CSS :hover, and Reticle ' +
         'refuses rather than reporting the styles as applied. Acquire a tab with ' +
-        'reticle_run { tool: "reticle_lease", action: "acquire", url } — reticle_lease is not ' +
+        'reticle_run { tool: "reticle_lease", args: { action: "acquire", url } } — reticle_lease is not ' +
         'advertised under the default profile, so it is reached through reticle_run, not called ' +
         'directly — or ask the human to drive with `reticle drive` / RETICLE_CDP_URL. This is a ' +
         'deliberate refusal, not a defect: there is nothing to report.',
@@ -182,7 +182,7 @@ export const RECOVERY = {
     COMMAND_TIMEOUT: 'The page did not answer within the command window. That is a fact about the page, not a Reticle ' +
         'failure: check reticle_sessions for `throttled`/`stale` on this session — a backgrounded tab is ' +
         'throttled and may never answer, so ask the human to bring it to the front or drive your own ' +
-        'browser with reticle_run { tool: "reticle_lease", action: "acquire", url } — reticle_lease is ' +
+        'browser with reticle_run { tool: "reticle_lease", args: { action: "acquire", url } } — reticle_lease is ' +
         'not advertised under the default profile, so it is reached through reticle_run, not called ' +
         'directly. If the tab is in front, the page is busy or blocked (a long ' +
         'synchronous task, an alert/confirm dialog); reticle_console usually shows what it hit. Retry ' +
@@ -495,7 +495,7 @@ const INVALID_NAME_REJECTION = /^invalid (?:[a-z]+ )*name: /i;
  * us nothing new.
  */
 export const FEEDBACK_ASK = 'This error is not one Reticle recognizes, which means it may be a defect in Reticle rather than in ' +
-    'the app. If you believe Reticle misbehaved, call reticle_feedback with a root-cause analysis and ' +
+    'the app. If you believe Reticle misbehaved, call reticle_session { action: "feedback" } with a root-cause analysis and ' +
     'the call trace before moving on — that report is the only way this gets fixed.';
 /**
  * Build the tool-error payload spliced at the MCP boundary. `recovery` is added when the error is

package/dist/surface/tools/feedback-invite.js

@@ -36,12 +36,14 @@ export const FrictionKind = {
  * a run of three is where a deliberate retry becomes a loop.
  */
 const REPEAT_INVITE_AT = 3;
+/** The call that files feedback. The old `reticle_feedback` name only answers with a redirect. */
+const FEEDBACK_CALL = 'reticle_session { action: "feedback" }';
 const LINES = {
-    [FrictionKind.UNKNOWN_TOOL]: 'no such tool — reticle_feedback tells us what you expected it to do, which is how it gets built',
-    [FrictionKind.UNKNOWN_VERDICT]: 'Reticle could not tell what happened here. If you expected otherwise, reticle_feedback. An ' +
+    [FrictionKind.UNKNOWN_TOOL]: `no such tool — ${FEEDBACK_CALL} tells us what you expected it to do, which is how it gets built`,
+    [FrictionKind.UNKNOWN_VERDICT]: `Reticle could not tell what happened here. If you expected otherwise, ${FEEDBACK_CALL}. An ` +
         'unknown verdict is our defect, not yours',
-    [FrictionKind.REPEATING]: 'stuck on the same call? reticle_feedback — say what you were trying to do and it gets fixed',
-    [FrictionKind.REFUSED]: 'if that diagnosis was wrong or unhelpful, reticle_feedback — error messages are a product ' +
+    [FrictionKind.REPEATING]: `stuck on the same call? ${FEEDBACK_CALL} — say what you were trying to do and it gets fixed`,
+    [FrictionKind.REFUSED]: `if that diagnosis was wrong or unhelpful, ${FEEDBACK_CALL} — error messages are a product ` +
         'surface and we fix the ones that fail',
 };
 /**

package/dist/surface/tools/feedback-tools.d.ts

@@ -8,7 +8,7 @@ export declare const FEEDBACK_TOOLS: ToolDef[];
  * Delivered ONCE per server process. A prompt on every verification would be nagging, and a nagged
  * user opts out of telemetry entirely, which costs us the counters too.
  */
-export declare const FEEDBACK_PROMPT: {
+declare const FEEDBACK_PROMPT: {
     readonly ask: "Ask the human, in your own words and only once: how did this verification go, and what would have made Reticle more useful? If they answer, file it with `reticle feedback` (they run it) or relay it yourself.";
     readonly command: "reticle feedback";
 };
@@ -33,3 +33,4 @@ export declare const VERDICT_TOOLS: ReadonlySet<string>;
  */
 export declare function takeFeedbackPrompt(toolName: string): typeof FEEDBACK_PROMPT | undefined;
 export declare function resetFeedbackPrompt(): void;
+export {};

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

@@ -196,7 +196,7 @@ export const FEEDBACK_TOOLS = [
  * Delivered ONCE per server process. A prompt on every verification would be nagging, and a nagged
  * user opts out of telemetry entirely, which costs us the counters too.
  */
-export const FEEDBACK_PROMPT = {
+const FEEDBACK_PROMPT = {
     ask: 'Ask the human, in your own words and only once: how did this verification go, and what would have made Reticle more useful? If they answer, file it with `reticle feedback` (they run it) or relay it yourself.',
     command: 'reticle feedback',
 };

package/dist/surface/tools/harness-explore.d.ts

@@ -98,8 +98,9 @@ export declare const MSG_NO_OPENAI_KEY: string;
  *
  * Resolved into the env rather than threaded through four call sites: the drivers and the
  * preference lookup all read an env record, and giving them a completed one leaves each of them
- * exactly as simple as it was. An EXPLICIT variable still wins — someone who exported a key meant
- * that key, and CI has no linked project to read.
+ * exactly as simple as it was. The key precedence is the resolver's, the same as sync's and the
+ * CLI's: the stored key for the link's host, else the exported one (which is how CI, with no
+ * keystore, gets here). An explicitly exported HOST still wins, so a proxy is not overridden.
  *
  * The credential arrives through `deps.linkedCloud`, a port, because resolving it here would make
  * the tool surface reach into `memory/cloud` — a reach the directory guard refused, correctly.

package/dist/surface/tools/harness-explore.js

@@ -7,7 +7,7 @@
  * nothing grades) but the flows that now exist on disk, because every future run replays those
  * deterministically with no model in the loop at all.
  */
-import { ReticleEnv, ReticleTool, apiKeyFrom, asRecord } from '@reticlehq/core';
+import { ReticleEnv, ReticleTool, cloudUrlFrom, asRecord } from '@reticlehq/core';
 import { projectForRoot } from '../../memory/project/project-for-root.js';
 import { harnessDriver, harnessOptionsFromEnv, } from '../../features/harness/driver.js';
 import { fillValues } from '../../features/harness/fill-values.js';
@@ -22,6 +22,7 @@ import { openAiDriver, openAiOptionsFromEnv } from '../../features/harness/opena
 import { fetchPlatformConfig } from '../../features/harness/platform-config.js';
 import { DEFAULT_MAX_STEPS, runHarness, } from '../../features/harness/harness.js';
 import { reticleToolset } from './harness-toolset.js';
+import { secretEnvKey } from '../../language/flows/flows.js';
 /**
  * Why the harness is unavailable, phrased as the way to make it available.
  *
@@ -53,15 +54,14 @@ const msgUnknownDriver = (asked) => `Unknown harness driver \`${asked}\`. Known
  *
  * Resolved into the env rather than threaded through four call sites: the drivers and the
  * preference lookup all read an env record, and giving them a completed one leaves each of them
- * exactly as simple as it was. An EXPLICIT variable still wins — someone who exported a key meant
- * that key, and CI has no linked project to read.
+ * exactly as simple as it was. The key precedence is the resolver's, the same as sync's and the
+ * CLI's: the stored key for the link's host, else the exported one (which is how CI, with no
+ * keystore, gets here). An explicitly exported HOST still wins, so a proxy is not overridden.
  *
  * The credential arrives through `deps.linkedCloud`, a port, because resolving it here would make
  * the tool surface reach into `memory/cloud` — a reach the directory guard refused, correctly.
  */
 export async function withLinkedCredential(deps, env) {
-    if (apiKeyFrom(env) !== undefined)
-        return env;
     try {
         const linked = await deps.linkedCloud?.();
         if (linked === undefined || null === linked)
@@ -69,7 +69,7 @@ export async function withLinkedCredential(deps, env) {
         return {
             ...env,
             [ReticleEnv.API_KEY]: linked.apiKey,
-            [ReticleEnv.CLOUD_URL]: env[ReticleEnv.CLOUD_URL] ?? linked.url,
+            [ReticleEnv.CLOUD_URL]: cloudUrlFrom(env) ?? linked.url,
         };
     }
     catch {
@@ -412,6 +412,7 @@ function buildDriver(env, maxSteps, plan, requested, fills) {
          * With no such key the label heuristic answers, exactly as it did before this existed.
          */
         fillValue: fillValues({
+            secret: (label) => env[secretEnvKey(label)],
             ...(fills === undefined ? {} : { cache: fills }),
             ...(harnessOptionsFromEnv(env) === undefined
                 ? {}

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

@@ -17,7 +17,7 @@ import { reportOnboardingStep } from '../../telemetry/onboarding-funnel.js';
 import { noteActed, noteFirstVerdict, noteOnboardingFirst } from '../../telemetry/onboarding-firsts.js';
 import { withHarnessDrive } from '../../telemetry/harness-drive.js';
 import { OnboardingPhase, OnboardingStepStatus } from '@reticlehq/core/telemetry';
-import { asString } from '@reticlehq/core';
+import { DiscoveryInvite, asString } from '@reticlehq/core';
 import { SESSION_ID_ARG, sessionIdFromArgs, spentRefFromArgs } from './tools-helpers.js';
 import { EnvelopeKey } from './tool-kit.js';
 import { ReticleTool } from '@reticlehq/core';
@@ -134,7 +134,7 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     // FLOW_HEAL is no longer a name runTool ever sees: it became `reticle_verify {action:"heal"}`,
     // and VERIFY is already listed here, so the exemption is inherited from the parent. Left as a
     // dangling name it would be a lie this file's own test 6 is written to catch.
-    ReticleTool.INTENT, // reads/writes .reticle/intent.json; sessionId only picks the project
+    ReticleTool.INTENT, // reads/writes .reticle/intent/; sessionId only picks the project
     ReticleTool.CONTEXT, // folds the journal + intent ledger; must still answer when nothing is connected
     ReticleTool.PROJECT, // reads .reticle/project.json
     // Reads the team's shared memory over HTTP; sessionId only resolves WHICH project's link file to
@@ -609,7 +609,13 @@ export async function runTool(tool, deps, args) {
         ? raw
         : {
             ...raw,
-            ...(friction !== undefined ? { [EnvelopeKey.FEEDBACK_INVITE]: inviteFor(friction) } : {}),
+            ...(friction !== undefined
+                ? {
+                    [EnvelopeKey.FEEDBACK_INVITE]: inviteFor(friction),
+                    // The moment Reticle got in somebody's way is the moment to offer them the founder.
+                    [EnvelopeKey.TALK_TO_US]: DiscoveryInvite.AGENT,
+                }
+                : {}),
             ...(prompt !== undefined ? { [EnvelopeKey.FEEDBACK_PROMPT]: prompt } : {}),
             ...(update !== undefined ? { [EnvelopeKey.UPDATE_AVAILABLE]: update } : {}),
             ...(skew !== undefined ? { [EnvelopeKey.VERSION_SKEW]: skew } : {}),
@@ -623,7 +629,14 @@ export async function runTool(tool, deps, args) {
         return result;
     // Reuse the session resolved above so the health envelope describes the SAME session the handler
     // drove; only re-resolve if the up-front attempt failed but the handler somehow succeeded.
-    const resolved = session ?? deps.sessions.resolve(rawSessionId);
+    const driven = session ?? deps.sessions.resolve(rawSessionId);
+    // ...unless the call replaced that document. A full navigation or reload registers a NEW Session
+    // under the same id (or under the id the result reports it arrived at), and the object resolved
+    // before the call is the page that unloaded: it reported itself hidden on the way out, so every
+    // response after a navigation said "throttled" about a tab that was fine. Describe what is there
+    // now. Optional-called because a test double is a partial SessionManager.
+    const arrivedId = 'string' === typeof result['sessionId'] ? result['sessionId'] : driven.id;
+    const resolved = deps.sessions.get?.(arrivedId) ?? driven;
     const envelope = {};
     // The health block is idempotent: add it only when the handler didn't already include a `session`.
     if (!('session' in result))

package/dist/surface/tools/lease-hint.d.ts

@@ -36,6 +36,14 @@ export interface LeaseEvidence {
      * reported as a marker that was not found.
      */
     sdkMarker?: boolean;
+    /**
+     * The page's own Content-Security-Policy, read off the served document, when it refuses the
+     * bridge. Proof rather than a guess: the connection cannot happen until the policy allows it.
+     */
+    cspBlock?: {
+        problem: string;
+        fix: string;
+    };
     /**
      * The websocket URL the leased page actually tried, read from its own console.
      *

package/dist/surface/tools/lease-hint.js

@@ -85,6 +85,16 @@ export function leaseNotConnectedHint(url, port, evidence = {}) {
             `RETICLE_PORT, or the build plugin's \`port\`), and \`VITE_RETICLE_WS_URL\` overrides it ` +
             `outright.${marker} ${RELEASE}`);
     }
+    // 0b. The page's own policy forbids the connection. Read off the document it served, so it is
+    //     proof about the page in hand, and it holds whether or not the app ships an SDK: neither
+    //     `init` nor the zero-install reader can dial out of a page that forbids it. Every cause
+    //     below presupposes a page that is allowed to connect, which is why this comes first.
+    if (evidence.cspBlock !== undefined) {
+        return (`${opening} This page's Content-Security-Policy blocks the connection: ` +
+            `${evidence.cspBlock.problem}. That is true whether or not the app has Reticle installed, ` +
+            `so installing it will not help until the policy allows the bridge. For development, ` +
+            `${evidence.cspBlock.fix}. ${RELEASE}`);
+    }
     // 1. A recorded refusal. The only cause with proof behind it, so nothing outranks it.
     if (evidence.refusal !== undefined) {
         return `${opening} A dial DID arrive and was refused: ${evidence.refusal}${marker} ${RELEASE}`;

package/dist/surface/tools/lease-tools.d.ts

@@ -15,8 +15,6 @@ import { type NetworkMutationPort } from '../../portal/input/network-mutation.js
 import type { Perturbation } from '@reticlehq/core';
 import { type SeedStorage } from '@reticlehq/core';
 import type { ToolDef } from './tool-kit.js';
-/** The origin of a URL, or undefined when it does not parse. */
-export declare function originOf(url: string): string | undefined;
 /**
  * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
  * adopts them on connect. Pure; falls back to plain concatenation if the URL can't be parsed.
@@ -78,31 +76,6 @@ export declare function resolveLeasedSessionId(sessions: {
  * a human's own URL.
  */
 export declare function carryReticleIdentity(fromUrl: string | undefined, toUrl: string): string;
-/** The narrow slice of a session the probe needs. Anything that quacks like this works. */
-interface ProbeableSession {
-    command?: (name: string, args: Record<string, unknown>, timeoutMs: number) => Promise<unknown>;
-}
-/**
- * Does this tab still answer?
- *
- * PRESENCE IS NOT LIVENESS. The sessions map still holds a tab that is attached, streaming events,
- * and answering nothing, so `ready` read off a row in that map hands back a lease that `snapshot`,
- * `state` and `console` then reject (#692). It has to mean the tab replied.
- *
- * ANY reply counts, including one that reports the command failed. The question is whether the SDK
- * answers at all, not what it says — so an SDK too old to know the command replies
- * `unknown command '…'`, and that is proof. Only the absence of a reply is evidence of absence:
- * `PendingCommands.track` REJECTS on timeout and on a dropped socket, and resolves on every real
- * answer, so the two cases are already separated for us.
- *
- * `CAPABILITIES` is the probe because it takes no arguments and returns a small fixed list. No new
- * wire command is introduced: this rides an existing round trip.
- *
- * Fails OPEN. A registry entry with no `command` is a shape this code did not put there, and
- * turning a lease that works into a refusal over a probe that could not run would be a worse
- * failure than the one being fixed.
- */
-export declare function probeLeaseAlive(session: ProbeableSession | undefined, timeoutMs?: number): Promise<boolean>;
 /**
  * Poll until the leased tab's SDK has actually registered on the bridge, so the sessionId we return
  * is immediately usable (the page navigates first, then connects a moment later — without this wait
@@ -122,6 +95,7 @@ export declare function acquireLeasedSession(pool: {
         sessionId: string;
         release: () => Promise<void>;
         navStatus?: number;
+        injectReader?: () => Promise<boolean>;
     }>;
     /**
      * The address this lease's page said it could not reach. Optional so a test double need not
@@ -141,6 +115,21 @@ export declare function acquireLeasedSession(pool: {
     release: () => Promise<void>;
 }>;
 export declare function waitForLeasedSession(isConnected: () => boolean, sleeper?: (ms: number) => Promise<void>, attempts?: number, pollMs?: number): Promise<boolean>;
+/**
+ * Wait for the leased tab to connect; if its app never does, hand it the zero-install reader.
+ *
+ * The decision is taken HERE, by the daemon, on the one fact that settles it: no HELLO arrived. A
+ * timer inside the page cannot know that — an app can connect from a dynamic import that resolves
+ * after `load` — and a reader injected into a page whose app was about to connect would take its
+ * place and drop the app's own options. So an app that connected itself is never touched, and a page
+ * that stayed silent through the whole readiness wait is the one that gets a reader.
+ */
+export declare function connectOrInject(lease: {
+    injectReader?: () => Promise<boolean>;
+}, isConnected: () => boolean, wait?: (isConnected: () => boolean) => Promise<boolean>): Promise<{
+    ready: boolean;
+    zeroInstall: boolean;
+}>;
 export declare function hasOriginLock(origin: string): boolean;
 export declare const LEASE_ACQUIRE_TOOL: ToolDef;
 export declare const LEASE_TOOLS: ToolDef[];
@@ -192,4 +181,3 @@ export declare function suiteFixturePort(realInput: RealInputProvider | undefine
  * is the reach the boundary guard exists to ask about.
  */
 export declare function sessionMutationPort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<NetworkMutationPort | undefined>;
-export {};

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

@@ -14,12 +14,14 @@ import { mutationPortFor } from '../../portal/input/network-mutation.js';
 import { z } from 'zod';
 import { leaseNotConnectedHint } from './lease-hint.js';
 import { probeSdkMarker } from './gaps/sdk-marker-probe.js';
+import { observeWebDocument } from '../../portal/session/dev-server/served-document.js';
+import { diagnoseObservedWebCsp } from '@reticlehq/init';
 import { readProjectFramework, readProjectId } from '../../command/cli/ports/resolve/cli-port.js';
 import { hasAnyAppConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
 import { AGENT_DRIVING_ELSEWHERE, AGENT_DRIVING_HERE_AGAIN, watchersToNotify, } from '../../portal/session/lease-visibility.js';
 import { reticleStateHome } from '../../command/daemon/daemon.js';
 import { LeaseNotReadyReason, REDACTED_VALUE, RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT, ReticleCommand, SeedStorageSchema, scrubKnownSecrets, } from '@reticlehq/core';
-import { ReticleTool } from '@reticlehq/core';
+import { ReticleTool, SESSION_HEALTH } from '@reticlehq/core';
 import { asString } from '@reticlehq/core';
 import { chromiumHint } from '../../command/cli/doctor/browser/chromium-hint.js';
 /**
@@ -36,14 +38,38 @@ import { chromiumHint } from '../../command/cli/doctor/browser/chromium-hint.js'
  * to print a paragraph, and it can only ever add a sentence: the probe returns `undefined` on any
  * doubt and the hint then says nothing about markers.
  */
+/**
+ * Whether the served page's own CSP refuses the bridge's SOCKET, read by the same code `doctor` uses.
+ *
+ * Only `connect-src` counts here. A lease injects the SDK itself, so the inline-snippet problem a
+ * `script-src` finding describes does not apply; what stops a leased page is the socket. Said in the
+ * lease's own words, because doctor's advice is about wiring a project, not about a tab.
+ */
+async function observedCspBlock(url, port) {
+    const document = await observeWebDocument(url);
+    if (document === undefined)
+        return undefined;
+    const refusesSocket = diagnoseObservedWebCsp(document, port).some((finding) => `${finding.problem} ${finding.fix}`.includes(CONNECT_SRC));
+    if (!refusesSocket)
+        return undefined;
+    const allow = `ws://localhost:${String(port)} ws://127.0.0.1:${String(port)}`;
+    return {
+        problem: `its ${CONNECT_SRC} does not allow ws://localhost:${String(port)}`,
+        fix: `add ${allow} to ${CONNECT_SRC}, behind a development-only check`,
+    };
+}
+/** The CSP directive that governs the socket the SDK dials. */
+const CONNECT_SRC = 'connect-src';
 async function leaseEvidence(deps, port, url) {
     const cwd = process.cwd();
     const projectId = readProjectId(cwd);
     const refusal = deps.sessions.lastClosure()?.reason;
     const framework = readProjectFramework(cwd);
     const sdkMarker = await probeSdkMarker(url);
+    const cspBlock = await observedCspBlock(url, port);
     return {
         ...(refusal === undefined ? {} : { refusal }),
+        ...(cspBlock === undefined ? {} : { cspBlock }),
         ...(framework === undefined ? {} : { framework }),
         ...(sdkMarker === undefined ? {} : { sdkMarker }),
         previouslyConnected: hasAnyAppConnectedBefore(reticleStateHome(), port, projectId),
@@ -52,7 +78,7 @@ async function leaseEvidence(deps, port, url) {
 }
 const POOL_UNAVAILABLE = 'browser pool unavailable — the lease tools need the daemon-managed pool (start Reticle via `reticle mcp`).';
 /** The origin of a URL, or undefined when it does not parse. */
-export function originOf(url) {
+function originOf(url) {
     try {
         return new URL(url).origin;
     }
@@ -139,6 +165,10 @@ export function scrubSeedFromError(text, seed) {
     }
     return out;
 }
+/** True for a Playwright `storageState()` export (`{ origins: [...] }`), not our seed shape. */
+function looksLikeStorageStateExport(seed) {
+    return Array.isArray(seed?.origins);
+}
 /**
  * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
  * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
@@ -298,7 +328,7 @@ const LEASE_PROBE_TIMEOUT_MS = 1_500;
  * turning a lease that works into a refusal over a probe that could not run would be a worse
  * failure than the one being fixed.
  */
-export async function probeLeaseAlive(session, timeoutMs = LEASE_PROBE_TIMEOUT_MS) {
+async function probeLeaseAlive(session, timeoutMs = LEASE_PROBE_TIMEOUT_MS) {
     const send = session?.command;
     if (send === undefined)
         return true;
@@ -338,7 +368,7 @@ export async function acquireLeasedSession(pool, sessions, url, projectId, seedS
     // id comes back, so handing it the lease id for an app that named its own session sent every flow
     // in the run at a session that does not exist.
     let registeredId;
-    await waitForLeasedSession(() => {
+    await connectOrInject(lease, () => {
         registeredId = resolveLeasedSessionId(sessions, lease.sessionId);
         return registeredId !== undefined;
     });
@@ -364,6 +394,23 @@ export async function waitForLeasedSession(isConnected, sleeper = sleep, attempt
     }
     return isConnected();
 }
+/**
+ * Wait for the leased tab to connect; if its app never does, hand it the zero-install reader.
+ *
+ * The decision is taken HERE, by the daemon, on the one fact that settles it: no HELLO arrived. A
+ * timer inside the page cannot know that — an app can connect from a dynamic import that resolves
+ * after `load` — and a reader injected into a page whose app was about to connect would take its
+ * place and drop the app's own options. So an app that connected itself is never touched, and a page
+ * that stayed silent through the whole readiness wait is the one that gets a reader.
+ */
+export async function connectOrInject(lease, isConnected, wait = waitForLeasedSession) {
+    if (await wait(isConnected))
+        return { ready: true, zeroInstall: false };
+    if (true !== (await lease.injectReader?.()))
+        return { ready: false, zeroInstall: false };
+    const ready = await wait(isConnected);
+    return { ready, zeroInstall: ready };
+}
 /**
  * Named on its own because `reticle drive <url>` runs it too.
  *
@@ -381,7 +428,7 @@ export function hasOriginLock(origin) {
 }
 export const LEASE_ACQUIRE_TOOL = {
     name: ReticleTool.LEASE_ACQUIRE,
-    description: 'Lease a fresh isolated headless browser context from the shared pool and navigate it to the app URL (the app must already be running and embed @reticlehq/core). If this origin is already leased and still connected, this returns THAT session rather than minting a second tab — a second acquire on the same origin poisons default session resolution. Returns the sessionId the leased tab registers — pass it to other tools. The pool keeps all leases in ONE browser and caps concurrency; if at capacity this waits for a free slot. Release with reticle_lease{action:"release"} when the flow is done. PREFER AN ALREADY-OPEN TAB: if reticle_sessions lists a non-leased session for this app, drive THAT instead — a lease is invisible to the person watching the app, whose HUD lives in their own tab, and a tab flagged hidden/throttled is often still driveable. Lease for isolation you actually need (a second identity, a clean context, parallel flows) or when driving the open tab has failed — this call answers with `preferExisting` when a live tab was available.',
+    description: 'Lease a fresh isolated headless browser context from the shared pool and navigate it to the app URL (the app must already be running; one with no Reticle SDK gets one supplied, reported as zeroInstall). If this origin is already leased and still connected, this returns THAT session rather than minting a second tab — a second acquire on the same origin poisons default session resolution. Returns the sessionId the leased tab registers — pass it to other tools. The pool keeps all leases in ONE browser and caps concurrency; if at capacity this waits for a free slot. Release with reticle_lease{action:"release"} when the flow is done. PREFER AN ALREADY-OPEN TAB: if reticle_sessions lists a non-leased session for this app, drive THAT instead — a lease is invisible to the person watching the app, whose HUD lives in their own tab, and a tab flagged hidden/throttled is often still driveable. Lease for isolation you actually need (a second identity, a clean context, parallel flows) or when driving the open tab has failed — this call answers with `preferExisting` when a live tab was available.',
     inputSchema: {
         url: z
             .string()
@@ -398,6 +445,10 @@ export const LEASE_ACQUIRE_TOOL = {
         ready: z
             .boolean()
             .describe('Whether the leased tab is connected AND answering. On a reused lease this is probed, not assumed — a row in the session map is presence, not liveness. False ⇒ read notReadyReason.'),
+        zeroInstall: z
+            .boolean()
+            .optional()
+            .describe('Present when this app ships no Reticle SDK and the lease supplied one. Verdicts work on the DOM, network, console and routes; there is no framework adapter, so no component state and no source file:line. Install with `npx @reticlehq/server init` for those.'),
         notReadyReason: z
             .enum([LeaseNotReadyReason.SDK_NEVER_DIALLED, LeaseNotReadyReason.SDK_STOPPED_ANSWERING])
             .optional()
@@ -447,8 +498,13 @@ export const LEASE_ACQUIRE_TOOL = {
         if (seedStorageArg !== undefined) {
             const parsed = SeedStorageSchema.safeParse(seedStorageArg);
             if (!parsed.success) {
-                const issuesMsg = scrubSeedFromError(parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join(', '), seedStorageArg);
-                throw new Error(`reticle_lease{action:"acquire"} seedStorage is invalid: ${issuesMsg}`);
+                const msg = scrubSeedFromError(parsed.error.issues
+                    .map((i) => (i.path.length > 0 ? `${i.path.join('.')}: ${i.message}` : i.message))
+                    .join(', '), seedStorageArg);
+                const hint = looksLikeStorageStateExport(seedStorageArg)
+                    ? 'This looks like a Playwright storageState() export ({ origins, cookies }); seedStorage takes { local?, session?, cookies? } (map origins[].localStorage into `local`).'
+                    : 'Expected { local?, session?, cookies? }.';
+                throw new Error(`reticle_lease{action:"acquire"} seedStorage is invalid: ${msg}. ${hint}`);
             }
             validatedSeed = parsed.data;
         }
@@ -538,7 +594,7 @@ export const LEASE_ACQUIRE_TOOL = {
             // Resolved rather than assumed: an app that names its own session registers under that name,
             // and the id we hand back has to be the one the agent can actually drive.
             let registeredId;
-            const ready = await waitForLeasedSession(() => {
+            const { ready, zeroInstall } = await connectOrInject(lease, () => {
                 registeredId = resolveLeasedSessionId(deps.sessions, lease.sessionId);
                 return registeredId !== undefined;
             });
@@ -569,6 +625,7 @@ export const LEASE_ACQUIRE_TOOL = {
                 // word: no SDK ever dialled in (look at the install) versus one dialled in and stopped
                 // answering (recover the tab). They want different next actions, so they get names.
                 ...(ready ? {} : { notReadyReason: LeaseNotReadyReason.SDK_NEVER_DIALLED }),
+                ...(zeroInstall ? { zeroInstall: true } : {}),
                 expiresInMs: pool.leaseTtlMs(),
                 leased: pool.activeCount(),
                 queued: pool.queuedCount(),
@@ -651,9 +708,7 @@ const PREFER_EXISTING_NOTE = 'a non-leased tab for this app was already connecte
  * is the right trade for a broadcast and the wrong one here, where a single `[0]` is handed back as
  * "drive this instead". With `projectId` undefined — and it is an OPTIONAL argument that an
  * acquiring agent has no reason to pass — every non-leased session qualified and the answer was
- * whichever the map yielded first. Measured against a real daemon: leasing `localhost:4312`
- * recommended a Phanpy tab on `:5173`, so an agent that complied would have driven a different
- * application and reported a verdict about it.
+ * whichever the map yielded first: leasing `localhost:4312` recommended a tab on `:5173`, another app.
  *
  * So this narrows by the one thing a lease always knows: the ORIGIN it is being taken against.
  * `projectId` still narrows further when given. Nothing is recommended when nothing matches, which
@@ -670,6 +725,8 @@ function liveTabFor(deps, projectId, url) {
         const candidates = deps.sessions
             .all()
             .filter((session) => session.url !== undefined && originOf(session.url) === wanted)
+            // Nor a tab gone silent: one last heard from 105s earlier was named here and answered nothing.
+            .filter((session) => (session.lastSeenMs?.() ?? 0) <= SESSION_HEALTH.STALE_THRESHOLD_MS)
             .map((session) => ({ id: session.id, projectId: session.projectId }));
         return watchersToNotify(candidates, pool.leasedSessionIds(), projectId)[0];
     }

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

@@ -19,7 +19,7 @@ export const LINEAGE_TOOLS = [
     {
         name: ReticleTool.LINEAGE,
         example: { path: 'user.profile.name' },
-        description: 'Trace BACKWARDS from a runtime value: which state change set it, which signal preceded that, and which request preceded the signal. Read-only — it draws no verdict and changes nothing. The state change is OBSERVED; every link above it is an INFERENCE from timing and says so in its own text. Where several candidates could explain a link it names ALL of them rather than choosing, because timing alone cannot justify the choice — so a chain here is a place to look, never a proven cause. Use it after a `no` verdict or a contradiction, instead of correlating reticle_state, reticle_network and reticle_observe by hand.',
+        description: 'Trace BACKWARDS from a runtime value: which state change set it, which driven action it was observed under, which signal preceded it, and which request preceded that. Read-only — it draws no verdict and changes nothing. The state change is OBSERVED; every link above it is an INFERENCE and says so in its own text — a driven action is the window-tier stamp the SDK put on the event, a signal or request is a timing look-back. A candidate stamped with a DIFFERENT action is excluded; an unstamped one is kept. Where several candidates could still explain a link it names ALL of them rather than choosing, because timing alone cannot justify the choice — so a chain here is a place to look, never a proven cause. Use it after a `no` verdict or a contradiction, instead of correlating reticle_look { action: "state" }, reticle_observe { action: "network" } and reticle_observe by hand.',
         inputSchema: {
             path: z
                 .string()

package/dist/surface/tools/live-call-text.js

@@ -38,7 +38,10 @@ const NO_TOOL_EQUIVALENT = [
         // \u2014 so the optional group could not match, the clause survived, and the replacement landed
         // inside the original quoting. What an agent read was the human-equivalent clause twice over,
         // with backticks nested three deep.
-        pattern: /`?reticle_run\s*\{\s*tool:\s*\\?"reticle_lease\\?"[^}]*\}`?(\s*\([^)]*\))?(\s*[-\u2014]+\s*reticle_lease is[^.]*\.)?/g,
+        // The body allows ONE nested object, because the call is `{ tool, args: { action, url } }`: the
+        // hint used to put `action` and `url` beside `tool`, which reticle_run refuses, and a `[^}]*\}`
+        // body stopped at the inner brace and left ` }` behind once the hint was corrected.
+        pattern: /`?reticle_run\s*\{\s*tool:\s*\\?"reticle_lease\\?"(?:[^{}]|\{[^{}]*\})*\}`?(\s*\([^)]*\))?(\s*[-\u2014]+\s*reticle_lease is[^.]*\.)?/g,
         instead: 'the CLI: `reticle open <url>` (a human can equivalently run `reticle drive <url>`)',
     },
     {