@reticlehq/server 2.8.0 → 2.10.0

package/dist/tools/feedback-tools.js

@@ -12,9 +12,9 @@
  * tokens on that and not on politeness.
  */
 import { z } from 'zod';
-import { FeedbackKind, FeedbackSource } from '@reticlehq/core';
+import { FeedbackKind, FeedbackSource, FEEDBACK_RATING_MAX, FEEDBACK_RATING_MIN, } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
-import { asString } from './tools-helpers.js';
+import { asNumber, asString } from './tools-helpers.js';
 import { submitFeedback, feedbackDisabled } from '../telemetry/feedback.js';
 import { getTelemetry } from '../telemetry/telemetry.js';
 /** One optional string arg, present only when the agent actually supplied it. */
@@ -22,6 +22,19 @@ function optionalText(args, key) {
     const value = asString(args[key]);
     return value !== undefined && value !== '' ? { [key]: value } : {};
 }
+/**
+ * The star rating, present only when the agent actually supplied one, and only when it is on the
+ * scale core defines. Bounds-checked HERE as well as in the schema because a number that survives
+ * to the wire off-scale is worse than an absent one: it still averages.
+ */
+function optionalRating(args) {
+    const value = asNumber(args['rating']);
+    if (value === undefined || !Number.isInteger(value))
+        return {};
+    if (value < FEEDBACK_RATING_MIN || value > FEEDBACK_RATING_MAX)
+        return {};
+    return { rating: value };
+}
 /** Read the connected session's self-reported facts, or nothing when no app is attached. */
 function sessionFacts(deps, sessionId) {
     const driven = deps.realInput !== undefined;
@@ -45,7 +58,7 @@ function sessionFacts(deps, sessionId) {
 export const FEEDBACK_TOOLS = [
     {
         name: ReticleTool.FEEDBACK,
-        description: "Tell the Reticle maintainers something — a failure, OR a feature you wish existed. Reticle is built FOR agents, so your experience is the one that decides what gets built, and this is the only channel that reaches us. File a `bug` when a tool returned something wrong, a `gap` when Reticle could not observe what you needed, an `ambiguity` when a verdict was not decidable, a `feature_request` when you thought 'I wish Reticle could do X', or an `improvement` when something works but is awkward (too many calls, a confusing shape, a slow path). Do not save these up or judge them as too minor — file it the moment you notice, then carry on with your task. For a failure, write `text` as a root-cause analysis (what you called, expected, got). For a request, write what you want and use `need` for the GOAL behind it, `impact` for what gets better, and `currentApproach` for how you are working around it today — that workaround is usually the most useful thing in the report. Set `model` to the model you are running. Never include app source, secrets, user data, or customer records. Do NOT use this for bugs you found in the app under test — that is a successful verification, which is Reticle working.",
+        description: "Tell the Reticle maintainers something — a failure, OR a feature you wish existed. Reticle is built FOR agents, so your experience is the one that decides what gets built, and this is the only channel that reaches us. File a `bug` when a tool returned something wrong, a `gap` when Reticle could not observe what you needed, an `ambiguity` when a verdict was not decidable, a `feature_request` when you thought 'I wish Reticle could do X', an `improvement` when something works but is awkward (too many calls, a confusing shape, a slow path), or an `experience` when something worked notably WELL (carry `rating` 1-5). File that one unprompted, when you actually notice it, and say which call and what it saved you — every other kind here is a complaint, so it is the only evidence for what is worth protecting when we change things. Do not save these up or judge them as too minor — file it the moment you notice, then carry on with your task. For a failure, write `text` as a root-cause analysis (what you called, expected, got). For a request, write what you want and use `need` for the GOAL behind it, `impact` for what gets better, and `currentApproach` for how you are working around it today — that workaround is usually the most useful thing in the report. Set `model` to the model you are running. Never include app source, secrets, user data, or customer records. Do NOT use this for bugs you found in the app under test — that is a successful verification, which is Reticle working.",
         inputSchema: {
             kind: z
                 .enum([
@@ -54,8 +67,9 @@ export const FEEDBACK_TOOLS = [
                 FeedbackKind.AMBIGUITY,
                 FeedbackKind.FEATURE_REQUEST,
                 FeedbackKind.IMPROVEMENT,
+                FeedbackKind.EXPERIENCE,
             ])
-                .describe('bug = a Reticle tool returned a wrong or broken result; gap = Reticle could not observe something you needed at all; ambiguity = the verification ran but you could not tell pass from fail; feature_request = something that does not exist and would have helped; improvement = something that exists but is awkward or inefficient.'),
+                .describe('bug = a Reticle tool returned a wrong or broken result; gap = Reticle could not observe something you needed at all; ambiguity = the verification ran but you could not tell pass from fail; feature_request = something that does not exist and would have helped; improvement = something that exists but is awkward or inefficient; experience = something worked notably well and is worth keeping (pair it with `rating`).'),
             text: z
                 .string()
                 .min(1)
@@ -72,6 +86,13 @@ export const FEEDBACK_TOOLS = [
                 .string()
                 .optional()
                 .describe('How you work around it TODAY. Usually the most useful field in the report: it proves the need is real, and often shows a cheaper fix than the feature being asked for.'),
+            rating: z
+                .number()
+                .int()
+                .min(FEEDBACK_RATING_MIN)
+                .max(FEEDBACK_RATING_MAX)
+                .optional()
+                .describe(`How well it worked, ${FEEDBACK_RATING_MIN}-${FEEDBACK_RATING_MAX}, with an \`experience\`. Only when you formed the judgement while working, never because you were asked: an agreeable number and an earned one are indistinguishable once both sit in the same column. The \`text\` is the part we can act on.`),
             model: z
                 .string()
                 .optional()
@@ -112,6 +133,7 @@ export const FEEDBACK_TOOLS = [
                 ...optionalText(args, 'impact'),
                 ...optionalText(args, 'currentApproach'),
                 ...optionalText(args, 'model'),
+                ...optionalRating(args),
             }, {
                 session: sessionFacts(deps, asString(args['sessionId'])),
                 // The AGENT does not wait for the network. `reticle feedback` (a human, at a terminal,
@@ -154,8 +176,11 @@ export const FEEDBACK_PROMPT = {
 export const VERIFICATION_TOOLS = new Set([
     ReticleTool.ACT_AND_WAIT,
     ReticleTool.ASSERT,
-    ReticleTool.FLOW_VERIFY,
-    ReticleTool.VERIFY_CHANGE,
+    // Merged: `flow_verify` and `verify_change` are actions on this tool now. Naming the merged tool
+    // does NOT make every action a verification — `verificationOf` still requires the result to carry
+    // a `verified` or a pass/fail `status`, so `coverage` and `crawl` contribute nothing and cannot
+    // inflate the count.
+    ReticleTool.VERIFY,
     ReticleTool.RECONCILE,
 ]);
 /**

package/dist/tools/invoke-tool.d.ts

@@ -7,4 +7,4 @@ export declare const SESSION_BOUND_TOOLS: ReadonlySet<string>;
  * `sessionId`-bearing tool to be classified into exactly one set (bound XOR exempt).
  */
 export declare const SESSION_EXEMPT_TOOLS: ReadonlySet<string>;
-export declare function runTool(tool: ToolDef, deps: ToolDeps, args: Record<string, unknown>): Promise<unknown>;
+export declare function runTool<Ext>(tool: ToolDef<Ext>, deps: ToolDeps<Ext>, args: Record<string, unknown>): Promise<unknown>;

package/dist/tools/invoke-tool.js

@@ -1,11 +1,11 @@
 import { healthEnvelope } from '../session/session-health.js';
-import { TelemetryActor, TelemetryEventKind, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { TelemetryActor, TelemetryEventKind, TRANSPORT_LIMITS, fingerprintFinding, } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { getTelemetry } from '../telemetry/telemetry.js';
 import { takeUpdateNudge } from '../update/update-nudge.js';
 import { takeVersionSkew } from '../version/version-nudge.js';
 import { noteToolCall } from '../daemon/daemon-usefulness.js';
-import { bugsInResult } from '../telemetry/bug-found.js';
+import { bugsInResult, routeOf } from '../telemetry/bug-found.js';
 import { noteToolServed, reportToolRefused } from '../telemetry/tool-refused.js';
 import { buildErrorPayload, refusalReasonFor } from './error-recovery.js';
 import { resultIsError } from '../mcp/mcp-is-error.js';
@@ -17,6 +17,7 @@ import { takeFeedbackPrompt } from './feedback-tools.js';
 import { takeFeedbackUndelivered } from '../telemetry/feedback-delivery.js';
 import { noteRefsMinted, wrongTabRefusal } from '../session/ref-provenance.js';
 import { span } from '../trace.js';
+import { deltaForToolResult, impactSnapshot, initImpact, recordImpact, } from '../impact/impact-recorder.js';
 import { frictionOf, inviteFor } from './feedback-invite.js';
 /**
  * The live-session tools whose result MUST carry the
@@ -46,14 +47,21 @@ const REF_MINTING_TOOLS = new Set([
     ReticleTool.QUERY,
     ReticleTool.INSPECT,
     ReticleTool.EXPLORE,
-    ReticleTool.CRAWL,
+    // `crawl` mints refs for the controls it drives and `coverage` for the ones it reports untouched.
+    // Both are actions on the merged verify tool now.
+    ReticleTool.VERIFY,
 ]);
 export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.SNAPSHOT,
     ReticleTool.QUERY,
     ReticleTool.INSPECT,
-    ReticleTool.COVERAGE,
-    ReticleTool.VERIFY_CHANGE,
+    // Merged change/flows/affected/coverage/crawl. Its members were SPLIT across bound and exempt —
+    // coverage/change/crawl bound, flow_verify exempt because it returns its own suite contract — and
+    // a merged tool has to be one or the other. Bound is the right side: `crawl` drives the app
+    // itself, so a throttled or event-dropping tab is exactly the condition its verdict depends on,
+    // and dropping the health disclosure there to protect a sibling's output shape would trade an
+    // honesty signal for a formatting preference.
+    ReticleTool.VERIFY,
     ReticleTool.ACT,
     ReticleTool.ACT_SEQUENCE,
     ReticleTool.ACT_AND_WAIT,
@@ -73,7 +81,6 @@ export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.STATE,
     ReticleTool.STORAGE,
     ReticleTool.EXPLORE,
-    ReticleTool.CRAWL,
     ReticleTool.SCROLL_TO,
     ReticleTool.NAVIGATE,
 ]);
@@ -89,7 +96,6 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     ReticleTool.FLOW_SAVE, // sessionId only scopes the write to the app's flow subdir; disk-side
     ReticleTool.FLOW, // merged list/load/delete — sessionId only scopes the project; all disk-side
     ReticleTool.FLOW_REPLAY, // returns its own FlowReplayResult contract (+ auto-records a run)
-    ReticleTool.FLOW_VERIFY, // returns its own SuiteVerdict contract (replays the whole suite)
     ReticleTool.FLOW_SAVE_RECORDED, // reads the recording buffer, writes disk
     ReticleTool.FLOW_HEAL, // returns its own FlowHealResult contract
     ReticleTool.PROJECT, // reads .reticle/project.json
@@ -141,14 +147,19 @@ function reportBugsFound(toolName, result) {
     if (0 === bugs.length)
         return;
     const metrics = getSessionMetrics();
+    const route = routeOf(result);
     for (const bug of bugs) {
         // `recordBug` answers whether this kind is new to the session, which is the only thing that
         // separates "another defect" from "the same defect again". Counting instances as defects is how
         // a published number inflates itself.
         const first = metrics.recordBug(bug.kind);
+        const identity = route !== undefined
+            ? { kind: bug.kind, source: bug.source, route }
+            : { kind: bug.kind, source: bug.source };
+        const fingerprint = fingerprintFinding(identity);
         void getTelemetry().emit(TelemetryEventKind.BUG_FOUND, {
             actor: TelemetryActor.AGENT,
-            bug: { ...bug, repeat: !first },
+            bug: { ...bug, repeat: !first, fingerprint },
         });
     }
 }
@@ -239,6 +250,9 @@ export async function runTool(tool, deps, args) {
     // closure carries this call's own identity, which is also what makes peak-concurrency measurable.
     // A daemon that has served even one tool call is doing a job for somebody; see daemon-usefulness.
     noteToolCall();
+    // 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 });
     // An oversized argument is refused BEFORE the handler deserialises it.
     //
     // tool-fuzz failed CI on the invariant that matters most — `every tool answers every hostile call`
@@ -352,6 +366,14 @@ export async function runTool(tool, deps, args) {
     // throw path would have measured half the wall and called it the whole of it, the same way `isError`
     // once did. A call that was served clears the retry chain, so the next refusal after it is a first
     // refusal rather than a retry of something unrelated.
+    // The user's own record of what Reticle did for them. Same chokepoint as everything else that
+    // counts, for the same reason: a second recording site is a second thing to forget. Separate
+    // store from telemetry - this one never leaves the machine.
+    recordImpact(deltaForToolResult(raw, Date.now() - startedAt, resultIsError(raw)));
+    // ...and the tab being driven is told, so the report is live rather than a thing you reload.
+    // Optional-call, not optional-chain-on-the-object: a test double is a partial Session, and a
+    // courtesy push must never be the reason a tool call throws.
+    session?.pushImpact?.(impactSnapshot);
     if (resultIsError(raw))
         reportRefusal(tool.name, raw.error);
     else {

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

@@ -5,13 +5,35 @@
  * — it does not wait for the human's tab. Measured over a day: lease sessions had a median of 30
  * tool calls and produced 46% of all bugs found, against a median of 1 call for everything else.
  *
- * When it fails it is almost always a PORT MISMATCH: the tab loads, and the app's SDK dials the port
- * it was BUILT with, which need not be the daemon that issued the lease. Verified by driving it —
- * against a matching daemon `acquire` returns ready:true and the session is driveable immediately;
- * against a different one the tab connects to the OTHER daemon instead.
- *
  * The old hint asked "is <url> running with @reticlehq/core enabled?", which is the one thing that
- * cannot be in doubt: the pool just navigated a real browser to it. Naming the true cause first is
- * the difference between a two-minute fix and abandoning the best path Reticle has.
+ * cannot be in doubt: the pool just navigated a real browser to it. Its replacement then swung to
+ * the other confident-but-unevidenced claim — "the usual cause is a PORT MISMATCH" — and the daemon
+ * ended up contradicting ITSELF inside one response, saying in `reticle_sessions` that a session had
+ * connected earlier "so the wiring is correct" and here that the port was probably wrong. Across a
+ * batch of field reports on four apps the port was correct every single time, and `reticle init`
+ * would have been the wrong action every single time.
+ *
+ * So: rank by what the daemon actually knows, and fall back to the differential only when it knows
+ * nothing. A cause we hold positive evidence against is not printed at all.
  */
-export declare function leaseNotConnectedHint(url: string, port: number): string;
+/** What the daemon can say for certain at the moment a lease comes back unconnected. */
+export interface LeaseEvidence {
+    /** A dial WAS made and turned away, with the reason. The only certain cause there is. */
+    refusal?: string;
+    /** An app for this project has connected on this port before (durable, survives a restart). */
+    previouslyConnected?: boolean;
+    /** The project has been through `init` — so recommending it again cannot help. */
+    initialized?: boolean;
+    /** The framework `.reticle.json` declares, used to rank rather than to decorate. */
+    framework?: string;
+    /**
+     * Whether any Reticle marker was found in the page the lease loaded.
+     *
+     * The single bit that separates the two commonest cases — "this app ships no SDK" and "the SDK
+     * loaded but could not reach the daemon" — which today produce identical messages. Absent means
+     * NOT CHECKED, and an absent bit prints nothing: a marker check that could not run must not be
+     * reported as a marker that was not found.
+     */
+    sdkMarker?: boolean;
+}
+export declare function leaseNotConnectedHint(url: string, port: number, evidence?: LeaseEvidence): string;

package/dist/tools/lease-hint.js

@@ -5,20 +5,71 @@
  * — it does not wait for the human's tab. Measured over a day: lease sessions had a median of 30
  * tool calls and produced 46% of all bugs found, against a median of 1 call for everything else.
  *
- * When it fails it is almost always a PORT MISMATCH: the tab loads, and the app's SDK dials the port
- * it was BUILT with, which need not be the daemon that issued the lease. Verified by driving it —
- * against a matching daemon `acquire` returns ready:true and the session is driveable immediately;
- * against a different one the tab connects to the OTHER daemon instead.
- *
  * The old hint asked "is <url> running with @reticlehq/core enabled?", which is the one thing that
- * cannot be in doubt: the pool just navigated a real browser to it. Naming the true cause first is
- * the difference between a two-minute fix and abandoning the best path Reticle has.
+ * cannot be in doubt: the pool just navigated a real browser to it. Its replacement then swung to
+ * the other confident-but-unevidenced claim — "the usual cause is a PORT MISMATCH" — and the daemon
+ * ended up contradicting ITSELF inside one response, saying in `reticle_sessions` that a session had
+ * connected earlier "so the wiring is correct" and here that the port was probably wrong. Across a
+ * batch of field reports on four apps the port was correct every single time, and `reticle init`
+ * would have been the wrong action every single time.
+ *
+ * So: rank by what the daemon actually knows, and fall back to the differential only when it knows
+ * nothing. A cause we hold positive evidence against is not printed at all.
  */
-export function leaseNotConnectedHint(url, port) {
-    return (`the leased tab loaded ${url} but never dialled this daemon (port ${String(port)}). The usual ` +
-        `cause is a PORT MISMATCH: the app's SDK connects to the port it was BUILT with, so a daemon on ` +
-        `a different port never hears from it — check the app's reticle port (\`.reticle.json\`, ` +
-        `RETICLE_PORT, or the build plugin's \`port\`) matches ${String(port)}, or start the daemon on ` +
-        `the port the app expects. If the app carries no Reticle SDK at all, run \`reticle init\` in it ` +
-        `first. The tab stays leased either way — release it with reticle_lease{action:"release"}.`);
+const NUXT = 'nuxt';
+const PORT_DIFFERENTIAL = "The usual cause is a PORT MISMATCH: the app's SDK connects to the port it was BUILT with, so a " +
+    "daemon on a different port never hears from it — check the app's reticle port (`.reticle.json`, " +
+    "RETICLE_PORT, or the build plugin's `port`), or start the daemon on the port the app expects.";
+/**
+ * The causes that actually occur on a wired app, in the order they occur. Mirrors the no-session
+ * diagnosis deliberately: two surfaces answering the same question must not rank it differently.
+ */
+const REAL_CAUSES = 'Causes that produce exactly this and are NOT a port problem: (a) the SDK is in the bundle but ' +
+    '`connect()` is never reached — a dev-mode guard or a missing runtime-config value returning ' +
+    'early, which emits nothing at all; (b) the dev server was started BEFORE the Reticle plugin was ' +
+    'added, so it is not in the bundle — restart it, HMR is not enough; (c) a peer dependency is ' +
+    'missing (typically `@reticlehq/react` in a non-React app) so the dynamic import fails silently; ' +
+    '(d) the page is not on localhost, where the SDK needs BOTH `allowNonLocalhost: true` and a ' +
+    'pairing token — the flag alone is not sufficient.';
+const NUXT_FIRST = 'This project is Nuxt: the most likely cause by a distance is a dev server that predates the ' +
+    'Reticle plugin, because Nuxt does NOT register a newly added plugin on HMR. Restart `nuxt dev` ' +
+    'and re-acquire before investigating anything else.';
+const RELEASE = 'The tab stays leased either way — release it with reticle_lease{action:"release"}.';
+function markerClause(sdkMarker) {
+    if (sdkMarker === undefined)
+        return '';
+    return sdkMarker
+        ? ' A Reticle SDK marker WAS found in the page that loaded, so the app does ship the SDK — the ' +
+            'question is only why it did not reach this daemon.'
+        : ' No Reticle SDK marker was found in the page that loaded. That is a check of the SERVED ' +
+            'document, so a lazily-imported SDK can still be missed — but combined with the rest it ' +
+            'points at a bundle that carries no Reticle at all, i.e. wiring that never took effect.';
+}
+export function leaseNotConnectedHint(url, port, evidence = {}) {
+    const opening = `the leased tab loaded ${url} but never dialled this daemon (port ${String(port)}).`;
+    const marker = markerClause(evidence.sdkMarker);
+    // 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}`;
+    }
+    // 2. Nuxt, whose most likely cause differs from every other framework's and which `init` warns
+    //    about at install time — while this hint never mentioned it.
+    const nuxt = evidence.framework?.toLowerCase() === NUXT ? ` ${NUXT_FIRST}` : '';
+    // 3. Proven wiring. Blaming the port here is the self-contradiction this rewrite exists to end.
+    if (true === evidence.previouslyConnected) {
+        return (`${opening} An app for this project HAS connected on this port before, so the port and the ` +
+            `wiring are both correct — what is failing is the SDK reaching initialise on the page.${nuxt}` +
+            `${marker} ${REAL_CAUSES} ${RELEASE}`);
+    }
+    // 4. Wired, but never seen connect. Rank the real causes; keep the port differential last, where
+    //    the evidence for it actually sits.
+    if (true === evidence.initialized) {
+        return `${opening}${nuxt}${marker} ${REAL_CAUSES} If none of those, it may be dialling a different daemon than this one: check the app's reticle port matches ${String(port)}. ${RELEASE}`;
+    }
+    // 5. Nothing known. The differential, plus the possibility this app carries no SDK at all —
+    //    except when the marker check already ruled that out, which is the whole reason for the bit.
+    const noSdk = true === evidence.sdkMarker
+        ? ''
+        : ' If the app carries no Reticle SDK at all, run `reticle init` in it first.';
+    return `${opening}${nuxt}${marker} ${PORT_DIFFERENTIAL}${noSdk} ${REAL_CAUSES} ${RELEASE}`;
 }

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

@@ -71,4 +71,15 @@ 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>;
+/**
+ * Named on its own because `reticle drive <url>` runs it too.
+ *
+ * When a daemon already owns the bridge port, `drive` asks that daemon for a browser instead of
+ * competing for the port (see cli/drive-attach.ts), and the browser it should get is exactly the one
+ * an agent gets: same pool, same isolation, same reporting. Sharing the ToolDef rather than the
+ * handler keeps that literal — the drive route dispatches through `runTool`, so it is counted like
+ * any other call instead of being a second, invisible dispatch path.
+ */
+export declare const LEASE_ACQUIRE_TOOL: ToolDef;
+export declare const LEASE_RELEASE_TOOL: ToolDef;
 export declare const LEASE_TOOLS: ToolDef[];

package/dist/tools/lease-tools.js

@@ -10,9 +10,32 @@
  */
 import { z } from 'zod';
 import { leaseNotConnectedHint } from './lease-hint.js';
+import { readProjectFramework, readProjectId } from '../cli/cli-port.js';
+import { hasConnectedBefore } from '../session/connection-memory.js';
+import { reticleStateHome } from '../daemon/daemon.js';
 import { RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { asString } from './tools-helpers.js';
+import { chromiumHint } from '../cli/chromium-hint.js';
+/**
+ * Everything the daemon already knows about why a leased tab might not have dialled in.
+ *
+ * Gathered here rather than guessed in the hint, because the daemon HAD this evidence all along and
+ * printed a static differential over the top of it — telling one agent in `reticle_sessions` that
+ * the wiring was proven correct and telling it seconds later that the port was probably wrong.
+ */
+function leaseEvidence(deps, port) {
+    const cwd = process.cwd();
+    const projectId = readProjectId(cwd);
+    const refusal = deps.sessions.lastClosure()?.reason;
+    const framework = readProjectFramework(cwd);
+    return {
+        ...(refusal === undefined ? {} : { refusal }),
+        ...(framework === undefined ? {} : { framework }),
+        previouslyConnected: hasConnectedBefore(reticleStateHome(), port, projectId),
+        initialized: projectId !== undefined,
+    };
+}
 const POOL_UNAVAILABLE = 'browser pool unavailable — the lease tools need the daemon-managed pool (start Reticle via `reticle mcp`).';
 /**
  * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
@@ -129,102 +152,124 @@ export async function waitForLeasedSession(isConnected, sleeper = sleep, attempt
     }
     return isConnected();
 }
-export const LEASE_TOOLS = [
-    {
-        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). 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.',
-        inputSchema: {
-            url: z
-                .string()
-                .describe('URL of the already-running app to drive (e.g. http://localhost:3000/dashboard).'),
-            projectId: z
-                .string()
-                .optional()
-                .describe('Stable project id to stamp on the leased tab so the agent can scope to it.'),
-        },
-        outputSchema: {
-            sessionId: z.string(),
-            url: z.string(),
-            ready: z
-                .boolean()
-                .describe('Whether the leased tab connected — false ⇒ the app may not embed @reticlehq/core.'),
-            expiresInMs: z
-                .number()
-                .describe('Milliseconds until this lease expires if untouched. Each tool call that targets this session resets the clock. Plan your work to finish or re-acquire before this runs out.'),
-            leased: z.number().describe('How many contexts are currently leased from the pool.'),
-            queued: z.number().describe('How many acquires are waiting for a free slot.'),
-            hint: z.string().optional(),
-        },
-        handler: async (deps, args) => {
-            const pool = deps.pool;
-            if (pool === undefined)
-                throw new Error(POOL_UNAVAILABLE);
-            const url = asString(args['url']);
-            if (url === undefined || 0 === url.length)
-                throw new Error('reticle_lease{action:"acquire"} requires a url');
-            const projectId = asString(args['projectId']);
-            const sessionId = newLeaseId();
-            const navUrl = appendReticleParams(url, sessionId, projectId);
-            let lease;
-            try {
-                lease = await pool.acquire(navUrl, { sessionId });
-            }
-            catch (err) {
-                // A raw page.goto failure is noisy and leaks the internal URL params — surface a clean,
-                // actionable message instead.
-                throw new Error(`could not open ${url} — is the app running there? (${cleanNavError(err)})`);
-            }
-            // Wait for the leased tab's SDK to connect so the returned sessionId is usable right away.
-            // 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(() => {
-                registeredId = resolveLeasedSessionId(deps.sessions, lease.sessionId);
-                return registeredId !== undefined;
-            });
-            // Tell the pool the other name this lease answers to. Every later touch and release arrives
-            // under the id we are about to hand back, and the pool is keyed by the id it navigated with;
-            // without this the touches miss, the lease ages out despite continuous activity, and the
-            // reaper closes the context mid-flow. See BrowserPool.alias and #157.
-            if (registeredId !== undefined)
-                pool.alias(registeredId, lease.sessionId);
-            return {
-                sessionId: registeredId ?? lease.sessionId,
-                url,
-                ready,
-                expiresInMs: pool.leaseTtlMs(),
-                leased: pool.activeCount(),
-                queued: pool.queuedCount(),
-                ...(ready
-                    ? {}
-                    : {
-                        hint: leaseNotConnectedHint(url, deps.bridgePort ?? RETICLE_DEFAULT_PORT),
-                    }),
-            };
-        },
+/**
+ * Named on its own because `reticle drive <url>` runs it too.
+ *
+ * When a daemon already owns the bridge port, `drive` asks that daemon for a browser instead of
+ * competing for the port (see cli/drive-attach.ts), and the browser it should get is exactly the one
+ * an agent gets: same pool, same isolation, same reporting. Sharing the ToolDef rather than the
+ * handler keeps that literal — the drive route dispatches through `runTool`, so it is counted like
+ * any other call instead of being a second, invisible dispatch path.
+ */
+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). 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.',
+    inputSchema: {
+        url: z
+            .string()
+            .describe('URL of the already-running app to drive (e.g. http://localhost:3000/dashboard).'),
+        projectId: z
+            .string()
+            .optional()
+            .describe('Stable project id to stamp on the leased tab so the agent can scope to it.'),
     },
-    {
-        name: ReticleTool.LEASE_RELEASE,
-        description: 'Release a leased browser context by sessionId, closing it and freeing the pool slot for a queued acquire. Call this when a flow finishes so the pool stays within its concurrency cap.',
-        inputSchema: {
-            sessionId: z
-                .string()
-                .describe('The leased sessionId returned by reticle_lease{action:"acquire"}.'),
-        },
-        outputSchema: {
-            released: z.boolean(),
-            leased: z.number(),
-        },
-        handler: async (deps, args) => {
-            const pool = deps.pool;
-            if (pool === undefined)
-                throw new Error(POOL_UNAVAILABLE);
-            const sessionId = asString(args['sessionId']);
-            if (sessionId === undefined || 0 === sessionId.length) {
-                throw new Error('reticle_lease{action:"release"} requires a sessionId');
+    outputSchema: {
+        sessionId: z.string(),
+        url: z.string(),
+        ready: z
+            .boolean()
+            .describe('Whether the leased tab connected — false ⇒ the app may not embed @reticlehq/core.'),
+        expiresInMs: z
+            .number()
+            .describe('Milliseconds until this lease expires if untouched. Each tool call that targets this session resets the clock. Plan your work to finish or re-acquire before this runs out.'),
+        leased: z.number().describe('How many contexts are currently leased from the pool.'),
+        queued: z.number().describe('How many acquires are waiting for a free slot.'),
+        hint: z.string().optional(),
+    },
+    handler: async (deps, args) => {
+        const pool = deps.pool;
+        if (pool === undefined)
+            throw new Error(POOL_UNAVAILABLE);
+        const url = asString(args['url']);
+        if (url === undefined || 0 === url.length)
+            throw new Error('reticle_lease{action:"acquire"} requires a url');
+        // Preflight the browser before spending the round trip. Without it a missing Playwright Chromium
+        // only surfaces inside pool.acquire, where the launch failure is caught and reported as
+        // "could not open <url> — is the app running?" — sending the caller to debug an app that is
+        // fine. Say the real thing at the first refusal instead. The phrasing carries "Chromium is not
+        // installed" so error-recovery routes it to the NO_POOL fix (install + drive a human tab).
+        if (deps.browserProbe !== undefined) {
+            const probe = await deps.browserProbe();
+            if (!probe.exists) {
+                throw new Error(`Chromium is not installed for Playwright — ${chromiumHint(probe)}`);
             }
-            await pool.release(sessionId);
-            return { released: true, leased: pool.activeCount() };
-        },
+        }
+        const projectId = asString(args['projectId']);
+        const sessionId = newLeaseId();
+        const navUrl = appendReticleParams(url, sessionId, projectId);
+        let lease;
+        try {
+            lease = await pool.acquire(navUrl, { sessionId });
+        }
+        catch (err) {
+            // A raw page.goto failure is noisy and leaks the internal URL params — surface a clean,
+            // actionable message instead.
+            throw new Error(`could not open ${url} — is the app running there? (${cleanNavError(err)})`);
+        }
+        // Wait for the leased tab's SDK to connect so the returned sessionId is usable right away.
+        // 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(() => {
+            registeredId = resolveLeasedSessionId(deps.sessions, lease.sessionId);
+            return registeredId !== undefined;
+        });
+        // Tell the pool the other name this lease answers to. Every later touch and release arrives
+        // under the id we are about to hand back, and the pool is keyed by the id it navigated with;
+        // without this the touches miss, the lease ages out despite continuous activity, and the
+        // reaper closes the context mid-flow. See BrowserPool.alias and #157.
+        if (registeredId !== undefined)
+            pool.alias(registeredId, lease.sessionId);
+        return {
+            sessionId: registeredId ?? lease.sessionId,
+            url,
+            ready,
+            expiresInMs: pool.leaseTtlMs(),
+            leased: pool.activeCount(),
+            queued: pool.queuedCount(),
+            ...(ready
+                ? {}
+                : (() => {
+                    const bridgePort = deps.bridgePort ?? RETICLE_DEFAULT_PORT;
+                    return {
+                        hint: leaseNotConnectedHint(url, bridgePort, leaseEvidence(deps, bridgePort)),
+                    };
+                })()),
+        };
+    },
+};
+export const LEASE_RELEASE_TOOL = {
+    name: ReticleTool.LEASE_RELEASE,
+    description: 'Release a leased browser context by sessionId, closing it and freeing the pool slot for a queued acquire. Call this when a flow finishes so the pool stays within its concurrency cap.',
+    inputSchema: {
+        sessionId: z
+            .string()
+            .describe('The leased sessionId returned by reticle_lease{action:"acquire"}.'),
+    },
+    outputSchema: {
+        released: z.boolean(),
+        leased: z.number(),
+    },
+    handler: async (deps, args) => {
+        const pool = deps.pool;
+        if (pool === undefined)
+            throw new Error(POOL_UNAVAILABLE);
+        const sessionId = asString(args['sessionId']);
+        if (sessionId === undefined || 0 === sessionId.length) {
+            throw new Error('reticle_lease{action:"release"} requires a sessionId');
+        }
+        await pool.release(sessionId);
+        return { released: true, leased: pool.activeCount() };
     },
-];
+};
+export const LEASE_TOOLS = [LEASE_ACQUIRE_TOOL, LEASE_RELEASE_TOOL];