@reticlehq/server 3.2.0 → 3.3.0

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/observe-tools.js

@@ -7,7 +7,7 @@ import { z } from 'zod';
 import { aliasParam } from './args/alias-args.js';
 import { CONSOLE_ATTACH_NOTE, CONSOLE_LEVELS, ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS, PredicateKind, Verified, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
-import { countSchema, cursorSchema, httpStatusSchema, timeoutMsSchema, windowMsSchema, } from './args/numeric-bounds.js';
+import { countSchema, cursorSchema, httpStatusSchema, timeoutMsSchema, waitForTimeoutMsSchema, resumeAfter, MAX_BLOCKING_WAIT_MS, windowMsSchema, } from './args/numeric-bounds.js';
 import { buildReactionReport } from '@reticlehq/engine/question/reaction.js';
 import { findContradictions } from '@reticlehq/engine/disagreement/contradictions.js';
 import { evaluatePredicate, waitForPredicate, PredicateSchema, } from '@reticlehq/engine/question/predicate/predicate.js';
@@ -16,7 +16,7 @@ import { WALL_CLOCK } from '../../portal/session/timing/wall-clock.js';
 import { parsePredicate } from '@reticlehq/engine/question/predicate/predicate-parse.js';
 import { matchNet, matchConsole, isConsoleEvent, eventMatchesFilters, netEmptyHint, consoleEmptyHint, reconcileNet, projectNetCall, projectConsoleLog, withoutUrlRaw, } from '@reticlehq/engine/window/event-filters.js';
 import { applyEventBudget, costHint, withSizeCost, DEFAULT_OBSERVE_EVENT_LIMIT, DEFAULT_QUERY_LIMIT, } from '../../portal/session/output-budget.js';
-import { annotateStarvedFailure, healthEnvelope, bufferEnvelope, } from '../../portal/session/session-health.js';
+import { annotateStarvedFailure, currentOf, healthEnvelope, bufferEnvelope, } from '../../portal/session/session-health.js';
 import { assertsDerivedIpcStatus, DERIVED_IPC_STATUS_ADVICE, isPresenceOnlyAssertion, PRESENCE_ONLY_ADVICE, } from './assert/assert-grade.js';
 import { assertVerdict } from './assert/assert-verdict.js';
 import { followLostObservation } from './act/act-observation.js';
@@ -172,6 +172,7 @@ export const OBSERVE_TOOLS = [
                 currentDocumentId: session.currentDocumentId,
                 currentEditEpoch: session.currentEditEpoch,
                 appOrigin: session.url,
+                background: session.background,
                 ...(judgingTheAct ? { ...session.lastAct.effect(), actionSince: actCursor } : {}),
             });
             // carry session health — a throttled tab means the observed timeline may be incomplete.
@@ -193,15 +194,19 @@ export const OBSERVE_TOOLS = [
             predicate: PredicateSchema.optional().describe('Predicate to wait for: { signal }, { net }, { element }, { kind: "net", ok: false } (assert on the OUTCOME — the honest field for IPC, which has no status code), { kind: "state", store, path, equals } (assert a registered store\'s value directly — the source of truth no DOM read can reach; equals takes a literal or { $gte | $contains | $length } pattern), { kind: "settled", quietMs } (deterministic network + DOM idle — prefer this over a fixed sleep), or a combination via allOf/anyOf.'),
             // Same concept, the neighbouring tool's name. See alias-args.ts.
             until: PredicateSchema.optional().describe("Alias for `predicate` (act_and_wait's name)."),
-            timeout_ms: timeoutMsSchema
+            timeout_ms: waitForTimeoutMsSchema
                 .optional()
-                .describe('Maximum wait in milliseconds. Default: 4000. Capped at 55000: your MCP client aborts the request before a longer wait can return, so a bound above this would be advertised and not deliverable. To outlast it, poll — several short waits, each of which returns a verdict.'),
+                .describe(`Maximum wait in milliseconds. Default: 4000, up to 600000. One call waits at most ${String(MAX_BLOCKING_WAIT_MS)} ms, because your MCP client aborts a longer request; past that it returns resume_ms, and you call again with timeout_ms: resume_ms and the same since to keep waiting.`),
             since: cursorSchema
                 .optional()
                 .describe('Cursor from a prior reticle_act — scopes the wait to events after that act.'),
             ...sessionIdShape,
         },
         outputSchema: {
+            resume_ms: z
+                .number()
+                .optional()
+                .describe('Present when this call stopped at the per-call limit before the predicate was seen. Call again with timeout_ms set to this, the same predicate and the same since, to keep waiting.'),
             pass: z.boolean(),
             evidence: z.unknown().optional(),
             failureReason: z.string().optional(),
@@ -239,7 +244,9 @@ export const OBSERVE_TOOLS = [
                 .describe('Where the code behind this verdict lives, as `file:line`. For an element/text assertion it is the matched element itself; for a FAILING signal/net/state assertion — which has no element to point at — it is the control last acted on, where the handler that should have fired lives. OMITTED when neither is known: this tool never borrows an unrelated location.'),
         },
         handler: async (deps, args) => {
-            const waitBudget = asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS;
+            const requestedMs = asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS;
+            // One call never blocks past what the client allows; the rest comes back as resume_ms.
+            const waitBudget = Math.min(requestedMs, MAX_BLOCKING_WAIT_MS);
             // Spend the budget waiting for the APP as well as for the predicate. See resolve-within.
             let session = await resolveSessionWithin(deps.sessions, asString(args['sessionId']), waitBudget, WALL_CLOCK);
             // `until` is act_and_wait's name for this — see alias-args.ts.
@@ -275,6 +282,7 @@ export const OBSERVE_TOOLS = [
                 ...annotateStarvedFailure(session, verdict),
                 ...assertionSource(session, predicate, verdict),
                 ...(followed.followed ? { sessionId: session.id } : {}),
+                ...((resume) => (resume === undefined ? {} : { resume_ms: resume }))(resumeAfter(requestedMs, waitBudget, verdict)),
                 ...healthEnvelope(session),
                 ...bufferEnvelope(session),
             });
@@ -454,7 +462,7 @@ export const OBSERVE_TOOLS = [
                 ...coverage,
                 // The SAME pointer the journal keeps, not a second lookup — one verdict, one file:line.
                 ...(verdictEffect.source === undefined ? {} : { source: verdictEffect.source }),
-                ...healthEnvelope(session),
+                ...healthEnvelope(currentOf(deps.sessions, session)),
                 ...bufferEnvelope(session),
             });
         },

package/dist/surface/tools/real-input-attempt.d.ts

@@ -22,11 +22,6 @@
 import { ActionType, InputModeReason } from '@reticlehq/core';
 import type { Session } from '../../portal/session/session.js';
 import { type ToolDeps } from './tool-kit.js';
-/**
- * Expand a leading `~` against the caller's home directory. Absolute and relative paths pass
- * through unchanged. `home` is injected so unit tests do not depend on the machine's real home.
- */
-export declare function expandUserPath(rawPath: string, home: string): string;
 /**
  * If the action is `upload` AND the inner args carry `path`, read the file from disk and rewrite
  * the args to `{ content, name, type, __base64: true }` before the ACT command reaches the browser.

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

@@ -99,7 +99,7 @@ const UPLOAD_MAX_BYTES = Math.floor((TRANSPORT_LIMITS.MAX_MESSAGE_BYTES / (4 / 3
  * Expand a leading `~` against the caller's home directory. Absolute and relative paths pass
  * through unchanged. `home` is injected so unit tests do not depend on the machine's real home.
  */
-export function expandUserPath(rawPath, home) {
+function expandUserPath(rawPath, home) {
     if ('~' === rawPath)
         return home;
     if (rawPath.startsWith('~/') || rawPath.startsWith('~\\'))

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

@@ -222,6 +222,11 @@ export declare const EnvelopeKey: {
     readonly VERIFY_NEXT: "verify_next";
     /** The contextual "tell us what just went wrong" invitation. Same story, same release. */
     readonly FEEDBACK_INVITE: "feedback_invite";
+    /**
+     * The same moment, for the HUMAN: a call with the founder, or an email through `identify`. The
+     * agent is told to offer it and never to book or submit anything itself.
+     */
+    readonly TALK_TO_US: "talk_to_us";
     /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
     readonly VERSION_SKEW: "version_skew";
     /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */

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

@@ -28,7 +28,7 @@ export const intentArg = z
     'BAD: "P1 step 5", "drive 2 of 2", "same as before the fix", "the board renders cleanly" — these name a session, ' +
     'a step number or nothing checkable, and the person reading them later has none of that context. ' +
     'This is shared memory: it is pooled per project and later agents read it back to avoid re-deriving what you just established. ' +
-    'Recorded in .reticle/intent.json, the same ledger reticle_intent writes, and marked proved by this verdict if it passes.');
+    'Recorded in .reticle/intent/, the same ledger reticle_intent writes, and marked proved by this verdict if it passes.');
 export const sessionIdShape = {
     sessionId: z
         .string()
@@ -75,6 +75,11 @@ export const EnvelopeKey = {
     VERIFY_NEXT: 'verify_next',
     /** The contextual "tell us what just went wrong" invitation. Same story, same release. */
     FEEDBACK_INVITE: 'feedback_invite',
+    /**
+     * The same moment, for the HUMAN: a call with the founder, or an email through `identify`. The
+     * agent is told to offer it and never to book or submit anything itself.
+     */
+    TALK_TO_US: 'talk_to_us',
     /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
     VERSION_SKEW: 'version_skew',
     /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */

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

@@ -395,11 +395,23 @@ export function describeToolSurface(active, requested) {
 export function defaultAdvertisedNames() {
     const surface = resolveToolSurface();
     const names = [...filterToolNames(surface)];
-    // `reticle_run` is real only where the surface keeps a dispatch hatch. The merged surface ships
-    // the catalogue without one, and naming a hatch that is not there is the same defect one level in.
-    return TOOL_SURFACE.MERGED === surface
-        ? [...names, ReticleTool.TOOLS]
-        : [...names, ReticleTool.TOOLS, ReticleTool.RUN];
+    /*
+     * Both meta tools, on every surface, because that is what the MCP actually advertises.
+     *
+     * This used to withhold `reticle_run` from the merged surface, reasoning that "naming a hatch
+     * that is not there is the same defect one level in". The reasoning is sound and the premise was
+     * false: `buildDynamicTools` returns `[reticle_tools, reticle_run]` unconditionally and
+     * `advertisedTools` appends both to every surface, so the hatch has always been there. Measured
+     * against a live daemon on the default surface: `reticle_run` is advertised, and
+     * `reticle_run { tool: "reticle_lease" }` reaches `reticle_lease`.
+     *
+     * Two functions answering one question, and this was the one the MCP never called. It is read by
+     * `server-instructions`, which gates "Everything else is one hop: reticle_tools lists it,
+     * reticle_run calls it" on this list - so agents were told the hatch was absent from a surface
+     * carrying it, and six recovery messages were later rewritten to match the lie.
+     * `advertised-names-are-real.test.ts` now pins this to `advertisedTools` itself.
+     */
+    return [...names, ReticleTool.TOOLS, ReticleTool.RUN];
 }
 /** The advertised NAME set for a surface, without needing the tool table. */
 function filterToolNames(surface) {

package/dist/surface/tools/tools.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { NoSessionAction, QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { DiscoveryInvite, AttrNamesSchema, EventType, NoSessionAction, QueryBy, ReticleCommand, SnapshotMode, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { withSizeCost } from '../../portal/session/output-budget.js';
 import { applySnapshotDelta, SnapshotCache } from './read/snapshot-delta.js';
@@ -109,7 +109,7 @@ export const RAW_TOOLS = [
                     lastOutage: z.object({ startedMs: z.number(), durationMs: z.number() }).optional(),
                 })
                     .optional()
-                    .describe('Present only when this tab has dropped and reconnected at least once: how long it has been attached in total, how many outages occurred, and when the last one started and how long it lasted. A verdict over this window spans a gap where nothing was observed.'),
+                    .describe('Continuity of the SDK-to-daemon LINK for this tab, present for any tab the daemon has a record of: how long this attachment has lasted, how many times it dropped and came back, and when the last gap started and how long it lasted. `outages > 0` means a verdict over this window spans a gap where nothing was observed. These are link counters, NOT app health: they say nothing about whether the page origin is still serving, so a tab whose dev server has died reports `outages: 0` with a growing `connectedSinceMs` and is not evidence the app is up.'),
             }))
                 .describe('Connected browser sessions with health state. `projectId` groups sessions by app (stable across port changes); `leased` marks a pool-managed headless context vs a human tab.'),
             why: z
@@ -125,6 +125,10 @@ export const RAW_TOOLS = [
             })
                 .optional()
                 .describe("Present ONLY when `sessions` is empty: the same answer as `why`, executable. `command` is the LITERAL command to run, sourced from this project's own package.json scripts and lockfile — it is absent, never guessed, when the project declares no dev script. `action` is one of daemon_split | start_dev_server | run_init | open_app | reopen_app. `daemon_split` outranks the rest and means the app IS running and instrumented, on a DIFFERENT daemon than the one you are attached to — do not start or re-init anything, read `reason`."),
+            talk_to_us: z
+                .string()
+                .optional()
+                .describe('Present ONLY when `sessions` is empty: a call with the founder for the person you are working with. Offer it; never act on it.'),
             lastKnown: z
                 .object({
                 sessionId: z.string(),
@@ -158,6 +162,8 @@ export const RAW_TOOLS = [
                     ...(why === undefined ? {} : { why }),
                     ...(next === undefined ? {} : { next_action: next }),
                     ...(undefined === lastKnown ? {} : { lastKnown }),
+                    // Setup that never connects is where most people give up; it is the talk worth having.
+                    talk_to_us: DiscoveryInvite.AGENT,
                 };
             }
             return { sessions };
@@ -261,7 +267,7 @@ export const RAW_TOOLS = [
                 scope: asString(args['scope']) ?? '',
                 mode,
                 diff: true === args['diff'],
-            }, deps.snapshots ?? SNAPSHOT_CACHE), mode), mode), mode)));
+            }, deps.snapshots ?? SNAPSHOT_CACHE), mode), mode), mode, resolved)));
         },
     },
     {
@@ -290,10 +296,7 @@ export const RAW_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('Return the `scope` element ITSELF instead of searching inside it. Use when the target is a plain layout container with no role, name, testid or text of its own — which is routinely the element that carries the handler, and is otherwise unreachable because every query excludes its own scope root. Requires `scope`.'),
-            attrs: z
-                .array(z.string())
-                .optional()
-                .describe("Attribute names to return per match, e.g. ['href'] to inventory links or ['src'] for images. Absent attributes are omitted; credential-bearing names are redacted."),
+            attrs: AttrNamesSchema.optional().describe("Attribute NAMES to return per match, e.g. ['href'] for links, ['src'] for images. Projects, never filters: 'name=value' is refused. Absent omitted; credentials redacted."),
             limit: countSchema
                 .optional()
                 .describe('Cap the returned descriptors to the first N (cuts tokens on broad queries). If more matched, the result carries total + truncated:true so the trim is never silent — narrow with name/scope.'),
@@ -371,6 +374,12 @@ export const RAW_TOOLS = [
                     .optional()
                     .describe('Structural clusters on the page — what IS here, to diagnose the miss.'),
                 presentTestids: z.array(z.string()).optional(),
+                // Declared for the same reason presentRegions had to be: undeclared here, it is stripped
+                // from structuredContent without a word — and this field exists precisely to say a word.
+                presentTestidsTotal: z
+                    .number()
+                    .optional()
+                    .describe('Present only when presentTestids was cut at its cap: how many there were. The list is document order, so a region low on the page is what got dropped — absence from the list proves nothing.'),
                 knownEmptyState: z.boolean(),
                 splitText: z
                     .object({
@@ -614,24 +623,31 @@ function noteEmptyLeanTree(result, mode) {
  * wrapper or two is ordinary, so this is deliberately not `=== 0`.
  */
 const UNMOUNTED_ROOT_MAX_ELEMENTS = 3;
-/**
- * The third cause of an empty tree, and the one the walk cannot see: the app is not mounted.
- *
- * Reported from the field with the react-three-fiber crash. The source-mapping stamp threw inside
- * R3F's commit phase, React unmounted the entire tree, and the page went white — and the snapshot
- * answered `{ tree: "", nodes: 0 }`, which is also what a page that has not rendered yet answers.
- * The reporter spent a diagnosis pass separating the two, and said that detecting a dead root would
- * have pointed straight at the cause.
- *
- * The other two notes here explain an empty tree by what the WALK passed over. This one cannot: a
- * walk that visited nothing has nothing to have skipped. It reads the DOM count instead, which is
- * why the browser now reports it, and it fires only when the skip counts are silent — a page whose
- * elements were all hidden has plenty of DOM and belongs to `noteHiddenPage`.
- *
- * Like both of its neighbours it names a fact and hands over the next read, and does not diagnose:
- * "not mounted" is certain from the count, WHY is not, and the console is where the answer is.
- */
-function noteUnmountedRoot(result, mode) {
+function crashEvidence(session) {
+    const since = asRecord(session)['eventsSince'];
+    if ('function' !== typeof since)
+        return undefined;
+    let events;
+    try {
+        events = since.call(session, 0);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(events))
+        return undefined;
+    const errors = events.filter((e) => {
+        const type = asString(asRecord(e)['type']);
+        return EventType.CONSOLE_ERROR === type || EventType.ERROR_UNCAUGHT === type;
+    });
+    if (0 === errors.length)
+        return undefined;
+    const first = errors
+        .map((e) => asString(asRecord(asRecord(e)['data'])['message']))
+        .find((m) => undefined !== m && '' !== m);
+    return { count: errors.length, first: first ?? '' };
+}
+function noteUnmountedRoot(result, mode, session) {
     if (SnapshotMode.STATUS === mode)
         return result;
     const row = asRecord(result);
@@ -642,12 +658,31 @@ function noteUnmountedRoot(result, mode) {
     const elements = asNumber(row['domElements']);
     if (elements === undefined || elements > UNMOUNTED_ROOT_MAX_ELEMENTS)
         return result;
+    const mount = `the tree is empty because there is almost nothing in the DOM: ${String(elements)} ` +
+        `element(s) under this scope. That is a mount container with nothing rendered into it, not a ` +
+        `page whose contents were skipped — so the app is UNMOUNTED rather than slow, and waiting ` +
+        `will not change it. `;
+    // An uncaught error beside an empty mount container is the difference between "has not started"
+    // and "started and died", which are the two readings of this count and want opposite next moves.
+    // Nothing here is framework-specific, and deliberately so: the condition is a known mount
+    // container that holds nothing with an uncaught error beside it, which is as true of a Vue or
+    // Svelte root as a React one.
+    const crash = crashEvidence(session);
+    if (crash !== undefined) {
+        return {
+            ...row,
+            note: mount +
+                `The app did not merely fail to start — it CRASHED: ${String(crash.count)} uncaught ` +
+                `error(s) were logged in this session` +
+                ('' === crash.first ? '' : `, the first: "${crash.first}"`) +
+                `. Read reticle_console for the rest, and check anything that runs inside a framework ` +
+                `commit phase. Loading the app again will reproduce it rather than fix it.`,
+        };
+    }
     return {
         ...row,
-        note: `the tree is empty because there is almost nothing in the DOM: ${String(elements)} ` +
-            `element(s) under this scope. That is a mount container with nothing rendered into it, not a ` +
-            `page whose contents were skipped — so the app is UNMOUNTED rather than slow, and waiting ` +
-            `will not change it. An app that was rendering and then stopped has usually thrown: read ` +
+        note: mount +
+            `An app that was rendering and then stopped has usually thrown: read ` +
             `reticle_console for an uncaught error, and check anything that runs inside a framework ` +
             `commit phase. If the app has genuinely not started yet, load it and snapshot again.`,
     };

package/dist/telemetry/feedback-local.d.ts

@@ -1,4 +1,5 @@
 import type { Feedback } from '@reticlehq/core/telemetry';
+/** Reports live beside the rest of the workspace, not in a temp dir somebody has to be told about. */
 interface SavedFeedback {
     path: string;
     /** A ready-to-run command that turns the file into an issue. */

package/dist/telemetry/feedback-local.js

@@ -13,8 +13,6 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ReticleDir } from '@reticlehq/core';
-/** Reports live beside the rest of the workspace, not in a temp dir somebody has to be told about. */
-const FEEDBACK_SUBDIR = 'feedback';
 /** Filesystem-safe, sortable, and unique enough for one report per second per kind. */
 const stamp = (now) => new Date(now).toISOString().replace(/[:.]/g, '-').replace('Z', '');
 const asMarkdown = (input, text, context) => {
@@ -39,7 +37,7 @@ const asMarkdown = (input, text, context) => {
  */
 export function saveFeedbackLocally(cwd, input, text, context, now = Date.now()) {
     try {
-        const dir = join(cwd, ReticleDir.ROOT, FEEDBACK_SUBDIR);
+        const dir = join(cwd, ReticleDir.ROOT, ReticleDir.FEEDBACK_SUBDIR);
         mkdirSync(dir, { recursive: true });
         const path = join(dir, `${stamp(now)}-${input.kind ?? 'note'}.md`);
         writeFileSync(path, asMarkdown(input, text, context), 'utf8');

package/dist/telemetry/feedback.d.ts

@@ -27,7 +27,7 @@ import { type SessionFacts } from './feedback-context.js';
 export declare const FEEDBACK_ENV = "RETICLE_FEEDBACK";
 /** What replaces a redacted match. Visible on purpose: a reader must see that something was removed. */
 export declare const REDACTED = "[redacted]";
-export interface Redaction {
+interface Redaction {
     text: string;
     /** Which rules fired, deduped. Surfaced back to the author so a redaction is never silent. */
     removed: string[];

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

@@ -0,0 +1,32 @@
+import { HudPanel, HudView, type HudUseData } from '@reticlehq/core';
+/**
+ * How people use the in-page HUD, rolled into the session summary.
+ *
+ * Windowed like the tool histograms beside it: a periodic flush reports what happened since the
+ * last one, so a dashboard sums across a session's events. Names only — every key is a control id
+ * the wire schema already checked against core's closed list.
+ */
+/** How many steps of the journey one window keeps. A journey longer than this is cut, and says so. */
+export declare const HUD_JOURNEY_MAX = 60;
+export interface HudSummary {
+    /** Presses per control; a toggle counts under `id:on` / `id:off` so a switch reads both ways. */
+    hudControls?: Record<string, number>;
+    /** Milliseconds the HUD spent in each view during the window. */
+    hudViewMs?: Partial<Record<HudView, number>>;
+    /** Milliseconds each panel was showing during the window. */
+    hudPanelMs?: Partial<Record<HudPanel, number>>;
+    /** The window's presses and view changes, in order, cut at HUD_JOURNEY_MAX. */
+    hudJourney?: string[];
+    /** Present, and true, only when the journey was cut. */
+    hudJourneyCut?: true;
+}
+export declare class HudMetrics {
+    #private;
+    constructor(now: () => number);
+    record(use: HudUseData): void;
+    get empty(): boolean;
+    /** The window so far. Open view and panel are counted up to now, and keep running after. */
+    summarize(): HudSummary;
+    /** Start the next window. The current view and panel carry over, timed from now. */
+    reset(): void;
+}