@reticlehq/server 3.1.0 → 3.3.0

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

@@ -0,0 +1,156 @@
+/**
+ * What a drive is FOR, decided before it starts and read out of `.reticle` rather than the app.
+ *
+ * The driver used to open its eyes on a page and pick whatever looked interesting. That makes every
+ * run start from zero: it re-drives journeys that are already saved, and it has no idea which
+ * declared intent nobody has ever tested. Both are the same missing input — the project's own
+ * record of what it claims to do and what has been proved about it.
+ *
+ * `.reticle` already holds that. `buildDomainModel` reads `.reticle/flows/` and
+ * `.reticle/contract.json` and answers with every saved flow, the consequence that MUST hold for
+ * each one, and the GAPS: signals and testids the app DECLARED that no flow asserts. So the plan is
+ * derivable with no browser, no model and no source code — which is the order this product argues
+ * for everywhere else and did not follow here.
+ *
+ * Two kinds of step, and the split is the whole economics:
+ *
+ *   REPLAY  a journey that is already recorded. Deterministic, no model in the loop, a few hundred
+ *           tokens. Anything already covered belongs here and must never be re-driven.
+ *   DRIVE   a gap. A model is worth paying for exactly where nothing is proved yet.
+ *
+ * Nothing here calls a model. The plan is the deterministic half, and the model's only job is to
+ * choose among steps somebody already decided were worth taking.
+ */
+export const PlanStepKind = {
+    /** Already recorded: replay it deterministically instead of paying a model to rediscover it. */
+    REPLAY: 'replay',
+    /** Declared but never proved: this is what a drive is actually for. */
+    DRIVE: 'drive',
+};
+/**
+ * How many untested declarations become drive steps.
+ *
+ * A contract can declare hundreds of testids, and a plan longer than the step budget is not a plan,
+ * it is a list. Capped so the drive spends its budget on the front of a ranked queue rather than
+ * spreading itself across everything and finishing none of it.
+ */
+const MAX_DRIVE_STEPS = 12;
+/**
+ * How many recorded journeys become replay steps.
+ *
+ * A project with seventy-four flows produced a seventy-four-step plan, which went into the tool
+ * result AND the standing instruction — thousands of tokens spent, every turn, listing work the
+ * drive had no budget to do. The whole argument for reading `.reticle` first is spending less, and
+ * an uncapped plan spends more.
+ *
+ * `reticle_domain` caps its own per-flow detail at 25 for the same measured reason. Ranked before
+ * cutting, so what survives is what is worth replaying first rather than whatever was listed first.
+ */
+const MAX_REPLAY_STEPS = 15;
+/** Signals first: a declared signal is a stronger statement of intent than a testid. */
+function driveSteps(domain) {
+    const steps = [];
+    for (const signal of domain.gaps.declaredUntestedSignals) {
+        steps.push({
+            kind: PlanStepKind.DRIVE,
+            target: signal,
+            why: `the app declares the signal "${signal}" and no saved flow asserts it`,
+        });
+    }
+    for (const testid of domain.gaps.declaredUntestedTestids) {
+        steps.push({
+            kind: PlanStepKind.DRIVE,
+            target: testid,
+            why: `the app declares the control "${testid}" and no saved flow exercises it`,
+        });
+    }
+    return steps.slice(0, MAX_DRIVE_STEPS);
+}
+/**
+ * Replay steps, worst-risk first when there is run history to rank by.
+ *
+ * A flow that asserts nothing is listed too, and says so: replaying it proves very little, and the
+ * honest plan admits that rather than counting it as coverage.
+ */
+function replaySteps(domain) {
+    const byName = new Map(domain.flows.map((flow) => [flow.name, flow]));
+    const ordered = 0 === domain.riskRanked.length
+        ? domain.flows.map((flow) => flow.name)
+        : [
+            ...domain.riskRanked,
+            ...domain.flows.map((f) => f.name).filter((name) => !domain.riskRanked.includes(name)),
+        ];
+    /*
+     * Flows that assert a real consequence come first, whatever the run history says.
+     *
+     * A flow with no `mustHold` passes as long as its steps still run, so replaying one proves close
+     * to nothing — and when the plan has to be cut, proving nothing is the first thing to give up.
+     */
+    const ranked = [
+        ...ordered.filter((name) => byName.get(name)?.mustHold !== undefined),
+        ...ordered.filter((name) => byName.get(name)?.mustHold === undefined),
+    ];
+    const steps = [];
+    for (const name of ranked) {
+        const flow = byName.get(name);
+        if (flow === undefined)
+            continue;
+        steps.push({
+            kind: PlanStepKind.REPLAY,
+            target: name,
+            why: flow.mustHold === undefined
+                ? `already recorded, but it asserts no consequence — replaying it proves only that the steps still run`
+                : `already recorded; it must still hold: ${flow.mustHold}`,
+        });
+    }
+    return steps.slice(0, MAX_REPLAY_STEPS);
+}
+/**
+ * Build the plan.
+ *
+ * Replays come first, always. They are the cheap half and they establish what is still true before
+ * any model is paid to explore what is not yet known — and a regression found by a replay is found
+ * for a few hundred tokens rather than a few hundred thousand.
+ */
+export function buildHarnessPlan(domain) {
+    const replays = replaySteps(domain);
+    const drives = driveSteps(domain);
+    const steps = [...replays, ...drives];
+    // Counted over EVERYTHING, then listed up to the cap — the same split `reticle_domain` uses, so a
+    // capped listing never quietly becomes a smaller analysis.
+    const totalRecorded = domain.flows.length;
+    const totalGaps = domain.gaps.declaredUntestedSignals.length + domain.gaps.declaredUntestedTestids.length;
+    const omitted = totalRecorded - replays.length + (totalGaps - drives.length);
+    /*
+     * Untested declarations first: a signal no flow asserts is exactly the one a drive should be
+     * claiming, and it is the same ranking the drive steps above already use.
+     *
+     * Then the signals saved flows ALREADY assert, which is not redundant and not a nicety. Most apps
+     * declare no capabilities at all -- the production dashboard this was measured on has no
+     * `contract.json` -- so a vocabulary built only from declarations is empty for exactly the
+     * projects that most need one. A signal a saved flow asserts is better evidence than a
+     * declaration anyway: it is a name the app has actually been observed to fire.
+     */
+    const vocabulary = [
+        ...domain.gaps.declaredUntestedSignals,
+        ...domain.declared.signals,
+        ...domain.flows.flatMap((flow) => flow.signals),
+    ].filter((name, index, all) => 0 < name.length && all.indexOf(name) === index);
+    const summary = 0 === steps.length
+        ? 'Nothing is recorded and nothing is declared: there is no plan to follow, so drive the app to find out what it does.'
+        : `${String(totalRecorded)} recorded journey(s) and ${String(totalGaps)} untested declaration(s); the plan lists the ${String(steps.length)} worth doing first${0 === omitted ? '' : `, omitting ${String(omitted)}`}.`;
+    return { steps, summary, vocabulary };
+}
+/**
+ * The plan as the model reads it.
+ *
+ * Intent first and names second, because a model ranking "what next" against a list of identifiers
+ * is guessing, and ranking against what the project says each one is FOR is not. The kind is stated
+ * so it can prefer finishing the cheap deterministic half before spending itself on the rest.
+ */
+export function planAsText(plan) {
+    if (0 === plan.steps.length)
+        return 'PLAN: none — nothing recorded, nothing declared.';
+    const lines = plan.steps.map((step, index) => ` ${String(index + 1)}. [${step.kind}] ${step.target} — ${step.why}`);
+    return `PLAN (from .reticle, not from the source):\n${lines.join('\n')}`;
+}

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

@@ -23,7 +23,18 @@ import { withTimeout } from '../../features/harness/with-timeout.js';
  * only through a discovery hop — and a hop the model has to take on every journey is a hop it will
  * sometimes skip, which silently turns the cheap path off.
  */
-const HARNESS_EXTRA_TOOLS = [ReticleTool.RECORD, ReticleTool.FLOW_SAVE];
+/**
+ * Beyond the default surface, the three tools a drive cannot do its job without.
+ *
+ * RECORD and FLOW_SAVE are how a drive keeps what it drove. FLOW_REPLAY is how it avoids driving
+ * the same thing twice — it was absent, so a driver handed a plan full of already-recorded journeys
+ * had no way to run one, and every run paid a model to rediscover what was on disk.
+ */
+const HARNESS_EXTRA_TOOLS = [
+    ReticleTool.RECORD,
+    ReticleTool.FLOW_SAVE,
+    ReticleTool.FLOW_REPLAY,
+];
 /**
  * The one deliberate subtraction.
  *

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

@@ -14,10 +14,11 @@ import { resultIsError } from '../mcp/faults/mcp-is-error.js';
 import { verificationOf } from '../../telemetry/verification-of.js';
 import { emitBugFoundHook, emitVerdictHook } from '../../hooks/hook-emit.js';
 import { reportOnboardingStep } from '../../telemetry/onboarding-funnel.js';
-import { noteFirstVerdict, noteOnboardingFirst } from '../../telemetry/onboarding-firsts.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 { sessionIdFromArgs, spentRefFromArgs } from './tools-helpers.js';
+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';
 import { takeFeedbackPrompt } from './feedback-tools.js';
@@ -133,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
@@ -152,6 +153,17 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     // when NO session exists — "nothing ever connected" is feedback we especially want.
     ReticleTool.FEEDBACK,
 ]);
+/**
+ * The merged action that hands the drive to a model inside the daemon.
+ *
+ * Derived from the member tool's own name rather than spelled again: the merge dispatches on
+ * `action`, and `reticle_verify` plus `explore` IS `reticle_verify_explore`. A literal here would be
+ * a third spelling of one name, and the one that silently stops matching when the action is renamed.
+ */
+const HARNESS_DRIVE_ACTION = ReticleTool.VERIFY_EXPLORE.slice(`${ReticleTool.VERIFY}_`.length);
+function isHarnessDrive(toolName, args) {
+    return ReticleTool.VERIFY === toolName && HARNESS_DRIVE_ACTION === args['action'];
+}
 function isPlainObject(value) {
     return 'object' === typeof value && value !== null && !Array.isArray(value);
 }
@@ -299,6 +311,34 @@ function firstOversizedArg(args) {
     }
     return undefined;
 }
+/**
+ * The args the handler is dispatched with, pinned to the session THIS call resolved.
+ *
+ * `runTool` resolves the session once and then attributes the whole call to it: the pool lease it
+ * refreshes, the health envelope it splices, the tab a ref is recorded as minted in, the project
+ * ledger the call lands in, the session a verdict is reported under. The handler was then handed
+ * the caller's args untouched, so a call that named no `sessionId` resolved a SECOND time — and a
+ * tab that connects in between can win auto-selection on its fresher heartbeat. The action goes to
+ * one tab and the answer describes another, which is a verdict about a page that was never driven
+ * and reads exactly like a correct one (#983).
+ *
+ * The wrong-tab ref guard is the sharpest case: it is asked whether the ref belongs to the tab
+ * resolution picked, so its permission is only sound if that is also the tab the handler drives.
+ *
+ * A COPY, never a write into the caller's object. `reticle_run`, the merged families and the
+ * programmatic invoker all pass the same record on, and a dispatch decision leaking back into it
+ * would outlive this call.
+ *
+ * Only a GUESSED session is pinned. An explicit id — including one lifted off a sequence step — is
+ * passed through exactly as written, so whether a stale id refuses or rebinds stays the resolver's
+ * decision; and a tool no session was resolved for (disk-only tools, or nothing connected) is left
+ * unscoped, so it answers as it always did.
+ */
+function pinnedArgs(args, explicitSessionId, session) {
+    if (explicitSessionId !== undefined || session === undefined)
+        return args;
+    return { ...args, [SESSION_ID_ARG]: session.id };
+}
 export async function runTool(tool, deps, args) {
     // Both dispatch paths (MCP + programmatic) pass through here — the one place "which tool is mostly
     // used" can be counted. This used to EMIT an event per call; it now increments an in-process counter
@@ -313,7 +353,7 @@ export async function runTool(tool, deps, args) {
     noteToolCall();
     // The ONBOARD firsts, at the chokepoint every call already passes through — so a second dispatch
     // path cannot quietly stop reporting them the way an extra listener would.
-    noteOnboardingFirst(tool.name, args);
+    noteOnboardingFirst(tool.name);
     // The impact record needs the project's own `.reticle` root, and this is the first place every
     // call knows it. Idempotent: the first root wins for the daemon's lifetime.
     initImpact({ reticleRoot: deps.reticleRoot });
@@ -343,8 +383,13 @@ export async function runTool(tool, deps, args) {
     }
     // An ACTION is what gets abandoned. Counted here, against verifications, so "the agent drove the
     // page and then wandered off" becomes a number instead of an impression.
-    if (ACTION_TOOLS.has(tool.name))
+    if (ACTION_TOOLS.has(tool.name)) {
         getSessionMetrics().recordAction();
+        // The two funnel rungs this branch is the authority on: the first action of the run, and the
+        // fact that this install has been driven at all. Reported from the set that already decides
+        // what "drove the page" means, so a fourth driving tool inherits both.
+        noteActed(args);
+    }
     const settleTiming = getSessionMetrics().startToolCall(tool.name, args);
     const startedAt = Date.now();
     const rawSessionId = sessionIdFromArgs(args);
@@ -430,12 +475,27 @@ export async function runTool(tool, deps, args) {
     const leaseId = session?.id ?? rawSessionId;
     if (leaseId !== undefined)
         deps.pool?.touch(leaseId);
+    // One identity for the whole call: the handler drives the session everything above is attributed
+    // to, rather than resolving again against a registry that can have changed underneath it.
+    const dispatchArgs = pinnedArgs(args, rawSessionId, session);
     let raw;
     try {
         // The one dispatch point every tool call passes through, so it is where the trace's root span
         // belongs: with RETICLE_TRACE on, every stage that runs underneath inherits this call's id and
         // nests under it. Free when off — see trace.ts.
-        raw = await span('tool.handler', { tool: tool.name, session: session?.id }, () => tool.handler(deps, args));
+        // `dispatchArgs`, not `args`: an inferred session is pinned into the arguments before the
+        // handler sees them, so a tool that resolves the session a second time cannot land on a
+        // different one than the dispatcher chose.
+        const call = () => span('tool.handler', { tool: tool.name, session: session?.id }, () => tool.handler(deps, dispatchArgs));
+        // A drive we run on the user's behalf, marked for its whole span so the verdicts it produces
+        // underneath are distinguishable from the ones the user's own agent earned.
+        //
+        // The outer call emits no verdict of its own, and that is the honest answer rather than a gap:
+        // it drives and records, it adjudicates nothing, and its result carries no verified/pass field
+        // to read. Deriving one from how far the drive got would be inventing a verdict nobody reached.
+        // What was missing was never an event here — it was that a session driven BY US read exactly
+        // like one the agent earned, which is what the span fixes.
+        raw = await (isHarnessDrive(tool.name, args) ? withHarnessDrive(call) : call());
     }
     catch (error) {
         // The commonest refusal shape by far, and the one nothing could see: the message is built, handed
@@ -549,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 } : {}),
@@ -563,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,6 +14,8 @@ 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';
@@ -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;
     }
@@ -298,7 +324,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 +364,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 +390,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 +424,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 +441,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()
@@ -538,7 +585,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 +616,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(),

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.d.ts

@@ -15,5 +15,11 @@ export declare function liveCallText(text: string, advertised: ReadonlySet<strin
  * was corrected and the result became unreadable, which is a worse trade than the advice was worth.
  *
  * Values, not keys: a key is a contract with the caller and nothing in a key is advice.
+ *
+ * And not every value is advice either. A field that carries a tool's IDENTITY is an answer to
+ * "which one", not a suggestion about what to call — rewriting it destroys the thing the caller
+ * asked for. `reticle_tools { names: ["reticle_act_sequence"] }` sets `name` to the name it was
+ * asked about, and this rewrote it to `reticle_act`, so a batch query came back with entries the
+ * caller could no longer match to their questions. See `IDENTITY_KEYS`.
  */
 export declare function liveCallValues(value: unknown, advertised: ReadonlySet<string>): unknown;