@reticlehq/server 3.6.0 → 3.7.0

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

@@ -1,11 +1,21 @@
+import { takeCallSecrets, withCallSecrets } from './tool-kit.js';
 import { healthEnvelope } from '../../portal/session/session-health.js';
 import { logToolCall, toolLogPath } from '../../hooks/tool-log.js';
 import { nextStep } from './next-step.js';
 import { currentDrivenBy } from '../../hooks/driven-by.js';
-import { sessionRoot } from '../../memory/project/session-root.js';
-import { takePlatformMoment } from './platform-moment.js';
+import { runAsAgent } from '../../hooks/coding-agents.js';
+import { takeHumanNotes } from './human-notes.js';
+import { takeDriveNotes } from '../../features/harness/drive-runs.js';
+import { harnessDriving, msgHarnessHasTheTab } from './harness-tab-guard.js';
+import { sessionRoot, sessionTarget } from '../../memory/project/session-root.js';
+import { ArtifactRootReason } from '../../memory/project/artifact-root.js';
+import { agentNudge, takePlatformMoment } from './platform-moment.js';
+import { RESULT_FIELD, trackVerdict } from './reticle-result.js';
+import { forTheAgent } from './agent/for-the-agent.js';
+import { feedbackAlreadyAsked, noteFeedbackAsked } from './agent/notices.js';
+import { SKEW_SHORT_WARNING, SKEW_VERDICT_WARNING } from '../../portal/session/session-health.js';
 import { verifyNextBaton, SUPPRESS_VERIFY_NEXT_ENV } from './verify-next-baton.js';
-import { TelemetryActor, TelemetryEventKind, TRANSPORT_LIMITS, fingerprintFinding, } from '@reticlehq/core';
+import { TelemetryActor, TelemetryEventKind, THROTTLED_WARNING, TRANSPORT_LIMITS, fingerprintFinding, } from '@reticlehq/core';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { getTelemetry } from '../../telemetry/telemetry.js';
 import { takeUpdateNudge } from '../../command/update/update-nudge.js';
@@ -18,21 +28,19 @@ import { buildErrorPayload, refusalReasonFor } from './error-recovery.js';
 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 { noteActed, noteFirstVerdict, noteOnboardingFirst } from '../../telemetry/onboarding-firsts.js';
-import { withHarnessDrive } from '../../telemetry/harness-drive.js';
-import { OnboardingPhase, OnboardingStepStatus } from '@reticlehq/core/telemetry';
-import { DiscoveryInvite, asString } from '@reticlehq/core';
+import { noteActed, noteFirstVerdict, noteOnboardingFirst, noteVerdictProduced, } from '../../telemetry/onboarding-firsts.js';
+import { DiscoveryInvite } from '@reticlehq/core';
 import { SESSION_ID_ARG, sessionIdFromArgs, spentRefFromArgs } from './tools-helpers.js';
-import { EnvelopeKey } from './tool-kit.js';
+import { EnvelopeKey, HOST_STUB_NOTE, STEP_SHOT_TOOLS } from './tool-kit.js';
 import { ReticleTool } from '@reticlehq/core';
 import { takeFeedbackPrompt } from './feedback-tools.js';
 import { takeFeedbackUndelivered } from '../../telemetry/feedback-delivery.js';
 import { noteRefsMinted, wrongTabRefusal } from '../../portal/session/facts/ref-provenance.js';
-import { CAPTURED_TOOLS, noteCapturedCall, noteToolDispatched, } from './feature-capture.js';
 import { span } from '../../trace.js';
+import { takeStepShot } from '../../features/visual/step-shots.js';
 import { defectForToolResult, deltaForToolResult, impactSnapshot, initImpact, recordImpact, } from '../../memory/impact/impact-recorder.js';
-import { frictionOf, inviteFor } from './feedback-invite.js';
+import { FrictionKind, frictionOf, inviteFor } from './feedback-invite.js';
+import { VACUOUS_BECAUSE } from '@reticlehq/engine/evidence/verified.js';
 /**
  * The live-session tools whose result MUST carry the
  * session-health envelope. Owned in ONE place — not retrofitted per handler — so a throttled tab
@@ -158,17 +166,6 @@ 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);
 }
@@ -183,7 +180,7 @@ function isPlainObject(value) {
  * The RULE itself lives in verification-of.ts, because getting it wrong fails silently.
  */
 function recordVerification(toolName, result, durationMs, brand, sessionId) {
-    const verification = verificationOf(toolName, result, durationMs, brand);
+    const verification = verificationOf(toolName, result, durationMs, brand, currentDrivenBy() !== undefined);
     if (verification === undefined)
         return;
     getSessionMetrics().recordVerification();
@@ -202,12 +199,8 @@ function recordVerification(toolName, result, durationMs, brand, sessionId) {
     emitVerdictHook(toolName, result, verification.verified, sessionId);
     // The ONBOARD half of the same moment: the first verdict of this run, once.
     noteFirstVerdict();
-    void reportOnboardingStep({
-        phase: OnboardingPhase.FIRST_RUN,
-        step: 'verdict_produced',
-        status: OnboardingStepStatus.COMPLETED,
-        elapsedMs: Math.max(0, Math.round(durationMs)),
-    });
+    // The FIRST_RUN rung: once per machine + project, not once per verdict.
+    noteVerdictProduced(durationMs);
 }
 /**
  * Emit one `bug_found` per defect in a tool result, and count it into the session.
@@ -231,9 +224,15 @@ function reportBugsFound(toolName, result, sessionId) {
             ? { kind: bug.kind, source: bug.source, route }
             : { kind: bug.kind, source: bug.source };
         const fingerprint = fingerprintFinding(identity);
+        const occurrence = metrics.recordBugOccurrence(fingerprint);
         void getTelemetry().emit(TelemetryEventKind.BUG_FOUND, {
             actor: TelemetryActor.AGENT,
-            bug: { ...bug, repeat: !first, fingerprint },
+            bug: {
+                ...bug,
+                repeat: !first,
+                fingerprint,
+                ...(occurrence === undefined ? {} : { occurrence }),
+            },
         });
         // The same defect, said out loud to whoever is building on Reticle. Inside the loop rather than
         // after it because the event is PER DEFECT — one event carrying a list would make a consumer
@@ -278,7 +277,9 @@ function frictionInviteFor(toolName, raw) {
         return undefined;
     const friction = frictionOf({
         unknownTool: false,
-        verifiedUnknown: 'unknown' === raw['verified'],
+        // A vacuous unknown is the caller's: it asserted nothing real (a bare `settled` wait, which the
+        // instructions recommend). Inviting a bug report there told agents Reticle had failed them.
+        verifiedUnknown: 'unknown' === raw['verified'] && VACUOUS_BECAUSE !== raw['because'],
         repeatRun: getSessionMetrics().currentRun,
         errored: resultIsError(raw),
         // A verdict is progress. Without this, three successful act_and_wait calls in a row — the exact
@@ -344,13 +345,52 @@ function pinnedArgs(args, explicitSessionId, session) {
         return args;
     return { ...args, [SESSION_ID_ARG]: session.id };
 }
-export async function runTool(tool, deps, args) {
+export async function runTool(tool, deps, given, call) {
+    // A replay's secrets leave the arguments here, before the tool log, the journal or telemetry can
+    // see them, and are supplied to this call alone.
+    const { secrets, rest: args } = takeCallSecrets(given);
+    // A verdict still being decided is waited for by a session end (`trackVerdict`); the result is
+    // compacted for the agent last, after telemetry and the tool log have read the full result.
+    return trackVerdict(tool.name, withCallSecrets(secrets, async () => {
+        const result = await loggedTool(tool, deps, args, call);
+        const attach = currentDrivenBy() === undefined ? deps.attachId : undefined;
+        const root = attach === undefined
+            ? undefined
+            : safeRoot(() => sessionRoot(deps, sessionIdFromArgs(args)));
+        return forTheAgent({ name: tool.name, args, result, attach, root, fold: NOTICE_FOLD });
+    }));
+}
+/** Advisories that become once-per-session notice lines. See agent/notices.ts. */
+export const NOTICE_FOLD = {
+    advisories: [
+        EnvelopeKey.FEEDBACK_PROMPT,
+        EnvelopeKey.FEEDBACK_INVITE,
+        EnvelopeKey.TALK_TO_US,
+        EnvelopeKey.UPDATE_AVAILABLE,
+        // NOT `version_skew`: it is decisive — it explains every result after it and names the command to
+        // run — so it rides out as its own key, untouched (one-shot at its source already).
+        EnvelopeKey.PLATFORM,
+        EnvelopeKey.SESSION_LEASE,
+        EnvelopeKey.SESSION_AGE_WARNING,
+        EnvelopeKey.FEEDBACK_UNDELIVERED,
+        EnvelopeKey.ZERO_INSTALL,
+    ],
+    notices: EnvelopeKey.NOTICES,
+    next: EnvelopeKey.NEXT,
+    warning: EnvelopeKey.WARNING,
+    onceWarnings: new Map([
+        // `session.throttled` still rides on every result: only the paragraph explaining it goes.
+        [THROTTLED_WARNING, undefined],
+        [SKEW_VERDICT_WARNING, SKEW_SHORT_WARNING],
+    ]),
+};
+async function loggedTool(tool, deps, args, call) {
     const logPath = toolLogPath();
     if (logPath === undefined)
-        return dispatchTool(tool, deps, args);
+        return dispatchTool(tool, deps, args, call);
     const at = deps.now();
     try {
-        const result = await dispatchTool(tool, deps, args);
+        const result = await dispatchTool(tool, deps, args, call);
         logToolCall(logPath, { tool: tool.name, args, at, ms: deps.now() - at, result });
         return result;
     }
@@ -360,7 +400,7 @@ export async function runTool(tool, deps, args) {
         throw error;
     }
 }
-async function dispatchTool(tool, deps, args) {
+async function dispatchTool(tool, deps, args, call) {
     // 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
     // that leaves once, with the session summary. A verification loop is 50–200 calls, and PostHog bills
@@ -399,6 +439,14 @@ async function dispatchTool(tool, deps, args) {
         reportRefusal(tool.name, error);
         return { error };
     }
+    // One driver per tab. The Harness clicking through a page while the agent clicks too is two hands
+    // on one mouse: neither result means anything. The agent's own action waits; its reads still run.
+    const busy = ACTION_TOOLS.has(tool.name) ? harnessDriving(deps, args) : undefined;
+    if (busy !== undefined) {
+        const error = msgHarnessHasTheTab(busy);
+        reportRefusal(tool.name, error);
+        return { error };
+    }
     // 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)) {
@@ -423,6 +471,24 @@ async function dispatchTool(tool, deps, args) {
             session = undefined;
         }
     }
+    // Nothing connected, and the app was never wired: a call that needs a page opens it zero-install
+    // rather than answering with a diagnosis the agent stops at. See zero-install-first-call.ts.
+    const openUnwired = deps.openUnwiredApp;
+    const opened = openUnwired !== undefined &&
+        session === undefined &&
+        bound &&
+        rawSessionId === undefined &&
+        0 === deps.sessions.list().length
+        ? await openUnwired()
+        : undefined;
+    if (opened !== undefined) {
+        try {
+            session = deps.sessions.resolve(rawSessionId);
+        }
+        catch {
+            session = undefined;
+        }
+    }
     // CDP tools against a skewed session: refuse with the sentence reticle_sessions already knows,
     // before Playwright invents a closed page. ready:true leases still hit this path.
     if (session?.versionSkew !== undefined && CDP_TOOLS.has(tool.name)) {
@@ -430,43 +496,6 @@ async function dispatchTool(tool, deps, args) {
         reportRefusal(tool.name, message);
         throw new Error(message);
     }
-    // The read-only calls the journal never keeps, recorded HERE because this is the one dispatch
-    // point every call routes through — a second recording site is a second thing to forget, and this
-    // instrument exists precisely because nothing was recorded before. Recorded before the handler
-    // runs: a read dispatches no action, so the counter reads the same either side.
-    //
-    // `reticle_context` is session-EXEMPT, so `session` above is undefined for it and it needs its own
-    // lenient resolve. Failing that resolve is silent by design: a call made with nothing connected
-    // has no per-session ledger to land in, and an instrument must never be why a tool call fails.
-    //
-    // EVERY tool is counted here, not just the read set: which of the 70-odd names in the table an
-    // agent actually reaches for is the question a decision about cutting or consolidating the surface
-    // turns on, and it had no answer. `reticle_run` is the one exclusion, for the same reason
-    // `reportRefusal` and `bugsInResult` exclude it — its handler calls `runTool` on the real tool, so
-    // the inner call is already counted under the name that RAN, and counting the wrapper too would
-    // both double the total and hide the run-only tier behind a single wrapper name. That tier is
-    // precisely the one the decision hinges on. See surface/tools/tool-hit-rate.ts.
-    if (ReticleTool.RUN !== tool.name) {
-        let target = session;
-        if (target === undefined) {
-            try {
-                target = deps.sessions.resolve(rawSessionId);
-            }
-            catch {
-                target = undefined;
-            }
-        }
-        if (target !== undefined) {
-            noteToolDispatched(target, tool.name);
-            if (CAPTURED_TOOLS.has(tool.name)) {
-                const subject = asString(args['ref']) ?? asString(args['target']);
-                noteCapturedCall(target, {
-                    tool: tool.name,
-                    ...(subject === undefined ? {} : { subject }),
-                });
-            }
-        }
-    }
     // A ref that was handed out by a DIFFERENT tab, on a call that named no session. Refused here, at
     // the one point that knows both the ref and the tab resolution picked — the handler only learns
     // that the ref missed, and answers that with "the DOM re-rendered", which is a confident diagnosis
@@ -500,16 +529,11 @@ async function dispatchTool(tool, 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());
+        const invokeHandler = () => span('tool.handler', { tool: tool.name, session: session?.id }, () => tool.handler(deps, dispatchArgs, call));
+        // The Harness's own inner calls carry their drive in an async context (`runDrivenBy`), which is
+        // what attributes their verdicts; the outer explore call adjudicates nothing of its own.
+        // As the agent on this connection, so a note it reads is marked seen by that agent.
+        raw = await runAsAgent(deps.attachId, invokeHandler);
     }
     catch (error) {
         // The commonest refusal shape by far, and the one nothing could see: the message is built, handed
@@ -547,6 +571,7 @@ async function dispatchTool(tool, deps, args) {
         // concurrency slot and peakConcurrentTools would climb forever on an unhealthy session.
         settleTiming(Date.now() - startedAt);
     }
+    raw = await withStepShot(tool.name, deps, args, raw, session?.id ?? rawSessionId);
     // Milestones describe work that ran. Refusals and paused calls must not consume the firsts.
     // Record action before verdict: act_and_wait can complete both in this same call.
     if (isPlainObject(raw) && !resultIsError(raw) && raw['paused'] !== true && raw['ok'] !== false) {
@@ -600,7 +625,10 @@ async function dispatchTool(tool, deps, args) {
         if (session !== undefined && REF_MINTING_TOOLS.has(tool.name))
             noteRefsMinted(session.id);
     }
-    const prompt = isPlainObject(raw) ? takeFeedbackPrompt(tool.name) : undefined;
+    // The feedback family is asked at most once per agent session (agent/notices.ts): gated here, at
+    // the take, so a suppressed ask is never counted as one that was made.
+    const asked = feedbackAlreadyAsked(currentDrivenBy() === undefined ? deps.attachId : undefined);
+    const prompt = isPlainObject(raw) && !asked ? takeFeedbackPrompt(tool.name) : undefined;
     // Same one-shot channel as the feedback ask: the agent is mid-task, so anything it would have to go
     // and ASK for is something it will never ask for. Spliced on ANY tool result, not just a
     // verification, because an out-of-date install is worth mentioning whatever the agent is doing.
@@ -625,9 +653,12 @@ async function dispatchTool(tool, deps, args) {
     // `refused` friction the line is written for. `errored` could only ever see the handlers that
     // RETURN an error. So the denominator was counting a small, unrepresentative slice of the
     // invitations and reading near-empty, which looks identical to a nudge that never fires.
-    const friction = frictionInviteFor(tool.name, raw);
-    // Once per project, on a proved verdict, when the runs live only on this machine.
-    const platform = isPlainObject(raw)
+    const friction = asked || prompt !== undefined ? undefined : frictionInviteFor(tool.name, raw);
+    if (prompt !== undefined || friction !== undefined)
+        noteFeedbackAsked(currentDrivenBy() === undefined ? deps.attachId : undefined);
+    // Once per project, on a proved verdict, when the runs live only on this machine. Not on a result
+    // whose `reticleResult` already ends with the platform line: once per result, never twice.
+    const platform = isPlainObject(raw) && !(RESULT_FIELD in raw)
         ? await takePlatformMoment(deps, raw, () => sessionRoot(deps, rawSessionId))
         : undefined;
     // What the agent should do next, on every client that reads results. Not for the Harness, whose
@@ -636,18 +667,48 @@ async function dispatchTool(tool, deps, args) {
     const next = isPlainObject(raw) && ReticleTool.RUN !== tool.name && currentDrivenBy() === undefined
         ? nextStep({
             tool: tool.name,
+            unmatched: unmatchedRootOf(deps, rawSessionId),
             verdict: 'verified' in raw,
             root: safeRoot(() => sessionRoot(deps, rawSessionId)),
             // A partial deps (tests, the demo) may carry no clock; the line is advice, never a reason to fail.
             now: 'function' === typeof deps.now ? deps.now() : Date.now(),
         })
         : undefined;
-    const result = prompt === undefined &&
+    // Only an agent's own call (an MCP connection, not the Harness, not the HUD's or the chat's calls
+    // into the same tools) takes what is waiting for the agent: those calls answer nobody who reads.
+    const answer = isPlainObject(raw) ? raw : undefined;
+    const agentCall = answer !== undefined && deps.attachId !== undefined && currentDrivenBy() === undefined;
+    // A Harness drive started or finished, from the HUD, the platform's chat or this agent: one line,
+    // once. Not about the run this very result already reports.
+    // One-time advisories toward the platform and the Harness (`platform-moment.ts`), only on the agent's
+    // own calls, riding the same platform line as the moments above.
+    const nudge = agentCall && answer !== undefined
+        ? await agentNudge({
+            deps,
+            tool: tool.name,
+            raw: answer,
+            isError: resultIsError(answer),
+            tab: session,
+            root: safeRoot(() => sessionRoot(deps, rawSessionId)),
+            harnessOn: () => impactSnapshot(artifactRoot)?.harnessConfig?.harnessEnabled,
+        })
+        : undefined;
+    const platformLine = platform === undefined ? nudge : nudge === undefined ? platform : `${platform}\n${nudge}`;
+    const drives = agentCall
+        ? takeDriveNotes('string' === typeof answer?.['runId'] ? answer['runId'] : undefined)
+        : [];
+    // The person's notes from the HUD, on ANY tool. Act tools splice their own `control` first.
+    const notes = agentCall && answer !== undefined && !(EnvelopeKey.CONTROL in answer)
+        ? await runAsAgent(deps.attachId, () => Promise.resolve(takeHumanNotes(deps.sessions, rawSessionId, session)))
+        : undefined;
+    const result = 0 === drives.length &&
+        notes === undefined &&
+        prompt === undefined &&
         update === undefined &&
         skew === undefined &&
         undelivered === undefined &&
         friction === undefined &&
-        platform === undefined &&
+        platformLine === undefined &&
         next === undefined
         ? raw
         : {
@@ -657,14 +718,20 @@ async function dispatchTool(tool, deps, args) {
             ...(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,
+                    // The founder's calendar only for an agent genuinely STUCK (the same call, again,
+                    // with no progress). An ordinary refusal carried it too, and read as a sales pitch
+                    // stapled to an error message.
+                    ...(FrictionKind.REPEATING === friction
+                        ? { [EnvelopeKey.TALK_TO_US]: DiscoveryInvite.AGENT }
+                        : {}),
                 }
                 : {}),
             ...(prompt !== undefined ? { [EnvelopeKey.FEEDBACK_PROMPT]: prompt } : {}),
             ...(update !== undefined ? { [EnvelopeKey.UPDATE_AVAILABLE]: update } : {}),
             ...(skew !== undefined ? { [EnvelopeKey.VERSION_SKEW]: skew } : {}),
-            ...(platform !== undefined ? { [EnvelopeKey.PLATFORM]: platform } : {}),
+            ...(platformLine !== undefined ? { [EnvelopeKey.PLATFORM]: platformLine } : {}),
+            ...(0 === drives.length ? {} : { [EnvelopeKey.HARNESS]: drives.join('\n') }),
+            ...(notes === undefined ? {} : { [EnvelopeKey.CONTROL]: notes }),
             ...(undelivered !== undefined
                 ? {
                     [EnvelopeKey.FEEDBACK_UNDELIVERED]: `your earlier report did NOT send: ${undelivered}. Tell the human what you found so it is not lost.`,
@@ -675,7 +742,15 @@ async function dispatchTool(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 driven = session ?? deps.sessions.resolve(rawSessionId);
+    // A handler that answered with no tab to resolve (a Harness drive polled by runId after a daemon
+    // restart reads its record from disk) keeps its answer: there is no session health to describe.
+    let driven = session;
+    try {
+        driven ??= deps.sessions.resolve(rawSessionId);
+    }
+    catch {
+        return result;
+    }
     // ...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
@@ -684,6 +759,14 @@ async function dispatchTool(tool, deps, args) {
     const arrivedId = 'string' === typeof result['sessionId'] ? result['sessionId'] : driven.id;
     const resolved = deps.sessions.get?.(arrivedId) ?? driven;
     const envelope = {};
+    // A leased tab opened with `initScript` runs a STUB of the bindings a desktop shell injects. Said
+    // on every session-bound result, not only on verdicts, for the same reason health is: a green from
+    // that tab proves the app's view logic, and nothing else in the result would say so.
+    // Optional-called: a partial pool in a test double has no lookup, and absence must read as "no
+    // stub", never as a crash on the whole tool surface.
+    if (true === deps.pool?.stubInstalled?.(resolved.id)) {
+        envelope[EnvelopeKey.HOST_STUB] = HOST_STUB_NOTE;
+    }
     // The health block is idempotent: add it only when the handler didn't already include a `session`.
     if (!('session' in result))
         Object.assign(envelope, healthEnvelope(resolved));
@@ -692,8 +775,13 @@ async function dispatchTool(tool, deps, args) {
     // does) — so a long-running backgrounded session, the case most likely to leak, never got the
     // one-time pool-lease reminder or the age cleanup nudge. Splice them regardless.
     const lease = resolved.takeSessionLease();
-    if (lease !== undefined)
+    // In CI there is no panel and no human to hand it back to: the reminder was noise in every
+    // pipeline log. Still taken, so the once-per-session cadence is unchanged.
+    if (lease !== undefined && process.env['CI'] === undefined) {
         envelope[EnvelopeKey.SESSION_LEASE] = lease;
+    }
+    if (opened !== undefined)
+        envelope[EnvelopeKey.ZERO_INSTALL] = opened.notice;
     const warning = resolved.ageWarning();
     if (warning !== undefined)
         envelope[EnvelopeKey.SESSION_AGE_WARNING] = warning;
@@ -725,6 +813,23 @@ async function dispatchTool(tool, deps, args) {
         envelope[EnvelopeKey.VERIFY_NEXT] = verifyNextBaton(unverified, resolved.lastAct?.effect() ?? {});
     return Object.keys(envelope).length > 0 ? { ...result, ...envelope } : result;
 }
+/**
+ * A picture of the page the moment this call's outcome was decided, named on the result. Only on
+ * an answer that touched the page: a refusal or a paused call drove nothing worth a picture. A
+ * navigation can land the page under a new id, so the id the result reports wins.
+ */
+async function withStepShot(name, deps, args, raw, sessionId) {
+    if (!STEP_SHOT_TOOLS.has(name) || Array.isArray(args['steps']))
+        return raw;
+    if (!isPlainObject(raw) || resultIsError(raw) || true === raw['paused'])
+        return raw;
+    const tab = 'string' === typeof raw['sessionId'] ? raw['sessionId'] : sessionId;
+    if (tab === undefined)
+        return raw;
+    // Paired with its check when the run is written: the n-th verdict picture is the n-th check.
+    const verdict = 'verified' in raw && (ReticleTool.ACT_AND_WAIT === name || ReticleTool.ASSERT === name);
+    return { ...raw, [EnvelopeKey.SCREENSHOT]: await takeStepShot(deps, tab, name, { verdict }) };
+}
 /** A root, or undefined when none can be resolved: a missing root is never a reason to throw. */
 function safeRoot(get) {
     try {
@@ -734,3 +839,25 @@ function safeRoot(get) {
         return undefined;
     }
 }
+/**
+ * Where this session's evidence goes when no project claims it (`~/.reticle/unmatched/<id>`), with
+ * the folders that compete for its id; undefined when it lands in a project. Never throws.
+ */
+function unmatchedRootOf(deps, sessionId) {
+    try {
+        const target = sessionTarget(deps, sessionId);
+        const resolved = deps.artifactRootFor?.(target.projectId, target.origin);
+        if (resolved === undefined || ArtifactRootReason.MATCHED_PROJECT === resolved.reason)
+            return undefined;
+        if (resolved.root === deps.reticleRoot)
+            return undefined;
+        return {
+            root: resolved.root,
+            contenders: resolved.candidates ?? [],
+            ...(resolved.serving === undefined ? {} : { serving: resolved.serving }),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -17,6 +17,7 @@
  * 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.
  */
+import { isLoopbackHostname } from '@reticlehq/core';
 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`, " +
@@ -36,6 +37,17 @@ const NUXT_FIRST = 'This project is Nuxt: the most likely cause by a distance is
     '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"}.';
+const PRODUCTION_STUB = ' If this is a production build (`vite build`, `next build`, `next start`, or a deployed site), it strips ' +
+    'Reticle or replaces it with an inert stub by design; point the lease at the dev server instead.';
+function isRemoteUrl(url) {
+    try {
+        const hostname = new URL(url).hostname.toLowerCase();
+        return !isLoopbackHostname(hostname);
+    }
+    catch {
+        return false;
+    }
+}
 function markerClause(sdkMarker) {
     if (sdkMarker === undefined)
         return '';
@@ -82,8 +94,8 @@ export function leaseNotConnectedHint(url, port, evidence = {}) {
             `this daemon is on ${String(port)}, so the dial never reached it. Nothing about the app's ` +
             `wiring is in question. Either start the daemon on ${String(dialled)}, or point the app at ` +
             `${String(port)} — the app's port comes from its build config (\`.reticle.json\`, ` +
-            `RETICLE_PORT, or the build plugin's \`port\`), and \`VITE_RETICLE_WS_URL\` overrides it ` +
-            `outright.${marker} ${RELEASE}`);
+            `RETICLE_PORT, or the build plugin's \`port\`), and \`reticle.connect({ 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
@@ -118,18 +130,27 @@ export function leaseNotConnectedHint(url, port, evidence = {}) {
             : ' That may have been a DIFFERENT app, though: this one may carry no Reticle SDK at all, ' +
                 'in which case run `reticle init` in ITS directory first — every cause below assumes the ' +
                 'SDK is already installed.';
+        // Never beside a marker that WAS found: "it ships the SDK" and "the build stripped it" cannot
+        // both be the story.
+        const production = true !== evidence.sdkMarker && (false === evidence.sdkMarker || isRemoteUrl(url))
+            ? PRODUCTION_STUB
+            : '';
         return (`${opening} An app for this project HAS connected on this port before, so the port is ` +
-            `proven.${notThisApp}${nuxt}${marker} ${REAL_CAUSES} ${RELEASE}`);
+            `proven.${notThisApp}${nuxt}${marker}${production} ${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}`;
+        const production = false === evidence.sdkMarker ? PRODUCTION_STUB : '';
+        return `${opening}${nuxt}${marker}${production} ${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.
+    // Nothing says the project was ever wired, so `reticle init` stays the advice whenever the SDK
+    // was not seen; a production build is the other way to serve a page without it.
     const noSdk = true === evidence.sdkMarker
         ? ''
-        : ' If the app carries no Reticle SDK at all, run `reticle init` in it first.';
+        : ' If the app carries no Reticle SDK at all, run `reticle init` in it first.' +
+            (false === evidence.sdkMarker || isRemoteUrl(url) ? PRODUCTION_STUB : '');
     return `${opening}${nuxt}${marker} ${PORT_DIFFERENTIAL}${noSdk} ${REAL_CAUSES} ${RELEASE}`;
 }

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

@@ -0,0 +1,33 @@
+/**
+ * The `permissions` argument of `reticle_lease { action: "acquire" }` (#1370).
+ *
+ * Granted before the first navigation of a fresh lease. On an origin that already has a live lease,
+ * acquire hands back THAT lease rather than opening a second tab, and it may be another agent's tab
+ * mid-flow — nothing at this layer knows whose it is. So its grants never change there: the same list
+ * is a plain reuse, a different one is refused with the way out (release, then acquire again).
+ */
+import { z } from 'zod';
+import type { BrowserPool } from '../../portal/pool/browser-pool.js';
+export declare const LEASE_PERMISSIONS_ARG: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+type PermissionPool = Pick<BrowserPool, 'notificationPermission'>;
+/** The validated list, undefined when the caller passed none, or a refusal naming the right shape. */
+export declare function parseLeasePermissions(raw: unknown): readonly string[] | undefined;
+/** A permission failure, reworded for the agent; undefined for every other error. */
+export declare function permissionRefusal(err: unknown): Error | undefined;
+/**
+ * What to tell the agent when the page cannot see a notifications grant, else undefined.
+ *
+ * Undefined too when the page could not be asked: the grant was made, and a reading nobody took is
+ * not evidence that it failed.
+ */
+export declare function notificationReadBack(pool: PermissionPool, sessionId: string, permissions: readonly string[] | undefined): Promise<string | undefined>;
+/**
+ * Refuse to reuse a held lease under a different set of grants. Nothing to refuse when the caller
+ * named no list, or the same one in any order.
+ */
+export declare function refuseRegrant(pool: Pick<BrowserPool, 'permissionsOf'>, sessionId: string, permissions: readonly string[] | undefined): void;
+/** `{ hint }` joining whichever parts are present, or nothing at all. */
+export declare function hintOf(...parts: (string | undefined)[]): {
+    hint?: string;
+};
+export {};