@reticlehq/server 3.7.0 → 3.8.1

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

@@ -0,0 +1,145 @@
+/**
+ * `reticle_map`: the app as the App Graph sees it, folded from what this project's sessions already
+ * journaled. Which screens there are, which controls each has and which of them were pressed and
+ * proven, the frontier (the important screens least proven), and the way to a screen as the anchors
+ * to press. An agent told "test the whole app" starts where the map says, not at the front door.
+ *
+ * PULLED and folded on demand from the journals on disk, never a second store: the act path pays
+ * nothing, and the answer cannot disagree with the ledger it was read from. The same fold
+ * (`@reticlehq/core`'s `mapOfRun` and `mergeMap`) builds the cloud's map, so the two never disagree.
+ */
+import { z } from 'zod';
+import { EventType, JournalActionSchema, MapEdgeKind, MapNodeKind, ReticleTool, asString, frontierLine, mapLine, mapOfRun, mergeMap, pathTo, } from '@reticlehq/core';
+import { isValidSessionId, journalActionsPath, journalEventsPath, reticleDirPaths, } from '../../memory/project/dir/reticle-dir.js';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { sessionIdShape } from './tool-kit.js';
+import { journalSteps } from '../../judgement/app-graph/journal-steps.js';
+/** Sessions folded: this project's recent past, as `harness-hunt` reads it, not its whole history. */
+const MAX_SESSIONS = 20;
+/** Screens listed, the most important first: a dashboard's screens, never its rows. */
+const MAX_SCREENS = 40;
+/** The project's sessions folded into one graph; undefined when none pressed anything. */
+export function graphOfSessions(sessions) {
+    let map;
+    for (const s of sessions) {
+        const start = s.events.find((e) => EventType.ROUTE_CHANGE === e.type);
+        const path = asString(start?.data['pathname']);
+        map = mergeMap(map, mapOfRun(journalSteps(s.actions, s.events), s.events, path), s.id);
+    }
+    return map;
+}
+/** Each screen with its actions counted: what is there, what was pressed, what held. */
+export function screensOf(map) {
+    const byId = new Map(map.nodes.map((n) => [n.id, n]));
+    return map.nodes
+        .filter((n) => MapNodeKind.SCREEN === n.kind)
+        .map((screen) => {
+        const actions = map.edges
+            .filter((e) => e.from === screen.id && MapEdgeKind.HAS === e.kind)
+            .map((e) => byId.get(e.to))
+            .filter((n) => n !== undefined);
+        return {
+            screen: screen.label,
+            actions: actions.length,
+            pressed: actions.filter((a) => 0 < (a.pressed ?? 0)).length,
+            proven: actions.filter((a) => 0 < (a.proven ?? 0)).length,
+        };
+    })
+        .sort((a, b) => b.actions - a.actions)
+        .slice(0, MAX_SCREENS);
+}
+const linesOf = (text, parse) => text.split('\n').flatMap((line) => {
+    if (0 === line.trim().length)
+        return [];
+    try {
+        const value = parse(JSON.parse(line));
+        return value === undefined ? [] : [value];
+    }
+    catch {
+        return [];
+    }
+});
+const asEvent = (raw) => {
+    const e = raw;
+    return 'number' === typeof e?.t && 'string' === typeof e.type && 'object' === typeof e.data
+        ? raw
+        : undefined;
+};
+/** This project's sessions: its live tabs, then the journals on disk of tabs that have closed. */
+async function sessionsFor(deps, sessionId) {
+    let projectId;
+    try {
+        projectId = deps.sessions.resolve(sessionId).projectId;
+    }
+    catch {
+        projectId = undefined;
+    }
+    const tabs = deps.sessions
+        .all()
+        .filter((s) => projectId === undefined || s.projectId === projectId);
+    const live = await Promise.all(tabs.map(async (s) => ({
+        id: s.id,
+        actions: await s.readJournalActions().catch(() => []),
+        events: await s.queryEvents({}).catch(() => []),
+    })));
+    let onDisk = [];
+    try {
+        const root = sessionRoot(deps, sessionId);
+        const liveIds = new Set(tabs.map((s) => s.id));
+        const ids = (await deps.fs.readdir(reticleDirPaths(root).sessions))
+            .filter((id) => !liveIds.has(id) && isValidSessionId(id))
+            .slice(-MAX_SESSIONS);
+        onDisk = await Promise.all(ids.map(async (id) => ({
+            id,
+            actions: linesOf(await deps.fs.readFile(journalActionsPath(root, id)).catch(() => ''), (raw) => {
+                const parsed = JournalActionSchema.safeParse(raw);
+                return parsed.success ? parsed.data : undefined;
+            }),
+            events: linesOf(await deps.fs.readFile(journalEventsPath(root, id)).catch(() => ''), asEvent),
+        })));
+    }
+    catch {
+        onDisk = [];
+    }
+    return [...onDisk, ...live].slice(-MAX_SESSIONS);
+}
+export const MAP_TOOLS = [
+    {
+        name: ReticleTool.MAP,
+        description: "The app as Reticle has seen it, folded from this project's journaled sessions: `screens` (each route with how many controls it has, how many were pressed and how many proven), `frontier` (the most important screens least proven, where testing should go next) and `summary`. Pass `to` (a route) for `path`: the controls to press from `from` (default `/`) to reach it. Call it before testing a whole app or a feature, instead of starting from the front door again. It never drives the page; an empty answer means nothing has been pressed yet.",
+        example: {},
+        inputSchema: {
+            to: z.string().optional().describe('A route to find the way to, e.g. `/settings/members`.'),
+            from: z.string().optional().describe('Where the way starts; `/` when not given.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            summary: z
+                .string()
+                .optional()
+                .describe('The map in one line: screens, actions, requests, things made.'),
+            frontier: z.string().optional().describe('The most important screens least proven.'),
+            screens: z
+                .array(z.unknown())
+                .optional()
+                .describe('`{ screen, actions, pressed, proven }`, most actions first.'),
+            path: z
+                .array(z.unknown())
+                .optional()
+                .describe('With `to`: the anchors to press, in order. Absent when no pressed way is known.'),
+        },
+        handler: async (deps, args) => {
+            const map = graphOfSessions(await sessionsFor(deps, asString(args['sessionId'])));
+            if (map === undefined)
+                return { screens: [] };
+            const to = asString(args['to']);
+            const path = to === undefined ? undefined : pathTo(map, asString(args['from']) ?? '/', to);
+            return {
+                summary: mapLine(map),
+                frontier: frontierLine(map),
+                screens: screensOf(map),
+                ...(path === undefined ? {} : { path }),
+            };
+        },
+    },
+];

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

@@ -18,16 +18,20 @@ const SHARED_KEYS = new Set(['sessionId']);
  * does take each key, which is the correction the caller needs.
  */
 function strayKeysRefusal(tool, action, stray, actions) {
-    const owners = stray.map((key) => {
-        const takes = Object.entries(actions)
-            .filter(([, member]) => key in member.inputSchema)
-            .map(([name]) => `"${name}"`);
-        return `\`${key}\` is a parameter of action ${takes.join(' or ')}`;
-    });
+    const takers = stray.map((key) => Object.entries(actions)
+        .filter(([, member]) => key in member.inputSchema)
+        .map(([name]) => name));
+    const owners = stray.map((key, i) => `\`${key}\` is a parameter of action ${(takers[i] ?? []).map((n) => `"${n}"`).join(' or ')}`);
     const declared = Object.keys(actions[action]?.inputSchema ?? {}).join(', ');
+    // One action that takes every stray key is the correction to name. Otherwise there is none.
+    const [only] = takers[0] ?? [];
+    const oneOwner = only !== undefined && takers.every((names) => 1 === names.length && only === names[0]);
+    const next = oneOwner
+        ? ` Call ${tool} { action: "${only}" } to use them, or call action "${action}" again without them.`
+        : '';
     return (`${tool} { action: "${action}" } does not take ${stray.map((k) => `\`${k}\``).join(', ')}, ` +
         'so it was NOT applied — a result computed without it would look like an answer. ' +
-        `${owners.join('; ')}. Action "${action}" takes: ${declared}.`);
+        `${owners.join('; ')}. Action "${action}" takes: ${declared}.${next}`);
 }
 /** The union of member input shapes, every field optional so one schema serves every action. */
 function unionShape(actions) {

package/dist/surface/tools/next-step.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { ReticleDir, ReticleEnv } from '@reticlehq/core';
 import { DRIVE_RECORD_SUFFIX } from '../../memory/project/dir/reticle-dir.js';
 import { callingAttachId } from '../../hooks/coding-agents.js';
+import { INIT_COMMAND, wiringConsent } from '../../portal/session/no-session-next-action.js';
 /**
  * The one thing the agent should do next, on the result of the call it just made.
  *
@@ -41,11 +42,13 @@ export const NextText = {
         const app = serving === undefined ? "This app's" : `The app served from ${serving}: its`;
         const lead = `${app} runs and flows are going to ${root}, not your project, so they will not reach the dashboard: `;
         if (0 === contenders.length) {
-            return `${lead}no folder on this machine declares its project. Run \`reticle init\` in the app's folder.`;
+            return `${lead}no folder on this machine declares its project. ${wiringConsent()}`;
         }
+        // `reticle init` alone keeps the id already on disk, so it cannot separate a copy from its original.
+        const copy = serving ?? 'the copy';
         return (`${lead}${String(contenders.length)} folders claim its project id (${contenders.join(', ')}). ` +
-            'Serve the app from the checkout that owns the id, or give this one its own id with ' +
-            "`reticle init` in it — that rewrites its committed .reticle.json, so keep the change on this checkout's branch.");
+            'Serve the app from the checkout that owns the id, or give the copy its own id: ' +
+            `\`cd ${copy} && ${INIT_COMMAND} --new-id\`. That rewrites only the copy's .reticle.json, so keep the change on the copy's branch.`);
     },
     REPLAY: (flows) => `This app has ${String(flows)} saved flow(s). Replay them before driving anything by hand: reticle_verify { action: "flows" } re-verifies them with no model.`,
 };

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

@@ -6,7 +6,7 @@ import { checkWords, runIdOfCall } from '../../judgement/runs/drive-run.js';
 import { noteEmptyRead } from './gaps/observed-nothing.js';
 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 { CONSOLE_ATTACH_NOTE, CONSOLE_LEVELS, ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS, PredicateKind, Verified, checkIntent, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 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';
@@ -16,22 +16,23 @@ import { resolveSessionWithin } from '../../portal/session/timing/resolve-within
 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 { applyEventBudget, costHint, withSizeCost, DEFAULT_OBSERVE_EVENT_LIMIT, DEFAULT_QUERY_LIMIT, withoutConstantSessionId, } from '../../portal/session/output-budget.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';
-import { withGapNovelty } from './gap-novelty.js';
+import { engineBlindSpotsOutput, withGapNovelty } from './gap-novelty.js';
+import { engineBlindSpotsField } from '../../portal/session/recorded-gaps.js';
 import { assertionSource } from './assert/assert-source.js';
 import { isChangeUndeclared } from '@reticlehq/engine/evidence/undeclared-change.js';
 import { openSessionIntents } from '../../memory/intent/open-intents.js';
 import { dischargeInlineIntent, inlineVerdictId, linkInlineIntent, } from '../../memory/intent/inline-intent.js';
-import { bodiesNotCaptured } from '@reticlehq/engine/evidence/uncaptured-bodies.js';
+import { bodiesNotCaptured, captureProvedOn, } from '@reticlehq/engine/evidence/uncaptured-bodies.js';
 import { bodyIsEvidence } from '@reticlehq/engine/window/body-relevance.js';
 import { foldAssetNoise } from '@reticlehq/engine/window/asset-noise.js';
 import { bodyClauseRefusal } from '@reticlehq/engine/evidence/body-capture-remedy.js';
 import { withControl } from '../../portal/session/control-envelope.js';
-import { asNumber, asRecord, asString } from '@reticlehq/core';
+import { asNumber, asRecord, asString, isPlainRecord } from '@reticlehq/core';
 import { intentArg, sessionIdShape, commandOrThrow } from './tool-kit.js';
 import { gradeOfPredicate } from './assert/assert-grade.js';
 import { captureAssertion } from '../../language/flows/replay.js';
@@ -45,21 +46,6 @@ const bufferOutputShape = {
         .optional()
         .describe('Present only when the event buffer evicted events — a negative result may then be a false negative.'),
 };
-/**
- * Drop `sessionId` from an event in a response the caller scoped to ONE session.
- *
- * The caller passed that id in the request, so echoing it on every event is the request quoted back
- * once per row. Measured on a live app it was 25% of a four-event `reticle_observe` payload, and it
- * grows linearly with the timeline — a fifty-event window spends ~2.5KB restating a fact the caller
- * supplied. The id stays on the wire between SDK and bridge, where events from different sessions
- * really do interleave; it is only redundant at this boundary.
- */
-function withoutConstantSessionId(event) {
-    if (typeof event !== 'object' || null === event)
-        return event;
-    const { sessionId: _sessionId, ...rest } = event;
-    return rest;
-}
 /**
  * The console levels, derived from core's console EventTypes — see CONSOLE_LEVELS.
  *
@@ -201,17 +187,18 @@ export const OBSERVE_TOOLS = [
             until: PredicateSchema.optional().describe("Alias for `predicate` (act_and_wait's name)."),
             timeout_ms: waitForTimeoutMsSchema
                 .optional()
-                .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.`),
+                .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, the same predicate, the same since, and the same intent to keep waiting.`),
             since: cursorSchema
                 .optional()
                 .describe('Cursor from a prior reticle_act — scopes the wait to events after that act.'),
+            intent: intentArg,
             ...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.'),
+                .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, the same since, and the same intent to keep waiting.'),
             verified: z
                 .string()
                 .optional()
@@ -265,10 +252,12 @@ export const OBSERVE_TOOLS = [
             // Refused up front rather than waited out: a body clause this session cannot answer would
             // burn the whole timeout to report something knowable now. See #801(C).
             const bodyRefusal = bodyClauseRefusal(predicate, session);
-            if (bodyRefusal !== undefined)
+            if (bodyRefusal !== undefined) {
                 throw new Error(bodyRefusal);
+            }
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
             const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
+            const intentId = await linkInlineIntent(deps, asString(args['sessionId']), asString(args['intent']), PredicateKind.SETTLED === predicate.kind ? undefined : predicate);
             // See the note on the assert handler below: a wait cut off by a full-document navigation is
             // followed to the document that took over, rather than graded as a lost observation there.
             const predicateStarted = session.elapsed();
@@ -296,8 +285,22 @@ export const OBSERVE_TOOLS = [
             }
             // The verdict, graded as `reticle_assert` grades it. This is `reticle_assert { action: "wait" }`,
             // and it answered `pass` with no `verified` — the one field an agent is told to gate on — while
-            // `action: "now"` carried it. Not journaled: a wait settles the page; the proof is the assert.
-            const { decision } = await assertVerdict(session, predicate, verdict.pass, verdict.evidence, followed.followed ? 0 : since, verdict.inconclusive, verdict.observationLost);
+            // `action: "now"` carried it.
+            const { decision, verdictEffect } = await assertVerdict(session, predicate, verdict.pass, verdict.evidence, followed.followed ? 0 : since, verdict.inconclusive, verdict.observationLost);
+            if (intentId !== undefined && Verified.YES === decision['verified']) {
+                await dischargeInlineIntent(deps, asString(args['sessionId']), intentId, {
+                    verdictId: inlineVerdictId(ReticleTool.WAIT_FOR, deps.now()),
+                    grade: gradeOfPredicate(predicate),
+                    at: deps.now(),
+                    runId: runIdOfCall(session.id),
+                }, session.lastAct.source());
+            }
+            // A graded wait is proof, but it observes rather than drives, so it has no attribution window.
+            session.recordAction(ReticleTool.WAIT_FOR, asRecord(args), {
+                ...verdictEffect,
+                ...checkWords(verdict),
+                ...checkIntent(predicate, verdict, asString(args['intent'])),
+            });
             // match reticle_assert — wrap with control + session health (throttle matters most while blocking)
             // and the buffer envelope, so a verdict reached over an evicted window says so.
             return withControl(session, {
@@ -331,7 +334,7 @@ export const OBSERVE_TOOLS = [
                 '{ state, path|equals } { route, pathname (exact) | contains (path+query+hash) } ' +
                 '{ element, testid|role|text } { text } { console, level|contains|absent } { animation, name } ' +
                 '{ settled } { compare, left, right } — combine with { allOf | anyOf | not }. Prefer a signal/net/state consequence ' +
-                'over element/text presence.'),
+                'over element/text presence. For net and signal, count is exact; omit it for at least one; 0 means never.'),
             until: PredicateSchema.optional().describe("Alias for `predicate` (act_and_wait's name)."),
             timeout_ms: timeoutMsSchema
                 .optional()
@@ -398,6 +401,7 @@ export const OBSERVE_TOOLS = [
                 .array(z.unknown())
                 .optional()
                 .describe('What the APP did not tell Reticle, and the one change that would fix it — each entry is { kind, missing, cost, fix, source?, ref? }. Reported ONLY where an absence made THIS verdict weaker: a failing assertion with no source to point at, or a state assertion against an app that registers no store. Never a survey of the page, so an entry is always work worth doing now. OMITTED when the app told Reticle everything it needed.'),
+            engineBlindSpots: engineBlindSpotsOutput,
         },
         handler: async (deps, args) => {
             const timeout = asNumber(args['timeout_ms']) ?? 0;
@@ -408,8 +412,9 @@ export const OBSERVE_TOOLS = [
             // Refused up front rather than waited out: a body clause this session cannot answer would
             // burn the whole timeout to report something knowable now. See #801(C).
             const bodyRefusal = bodyClauseRefusal(predicate, session);
-            if (bodyRefusal !== undefined)
+            if (bodyRefusal !== undefined) {
                 throw new Error(bodyRefusal);
+            }
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
             let since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
             // Declared BEFORE the verdict, so the undeclared-change read below finds it open and stays
@@ -435,8 +440,9 @@ export const OBSERVE_TOOLS = [
                 reevaluate: (next, budget) => waitForPredicate(next, predicate, budget, 0),
             });
             // The successor's buffer is its own: the departed session's cursor means nothing there.
-            if (followed.followed)
+            if (followed.followed) {
                 since = 0;
+            }
             session = followed.session;
             const verdict = followed.verdict;
             // A GREEN presence-only assertion is the dangerous case (a wrong element can fake it) — nudge
@@ -453,7 +459,9 @@ export const OBSERVE_TOOLS = [
                         : {};
             // Asked of every verdict drawn after an observed edit, not once per edit — see
             // isChangeUndeclared for why repeating it is disclosure rather than nagging.
-            const changeUndeclared = await isChangeUndeclared(session.currentEditEpoch, () => openSessionIntents(deps, asString(args['sessionId'])));
+            // Read once: the undeclared-change check and the engine's claim reading share it.
+            const declared = await openSessionIntents(deps, asString(args['sessionId']));
+            const changeUndeclared = await isChangeUndeclared(session.currentEditEpoch, () => Promise.resolve(declared));
             const { decision, contradictions, coverage, gaps, verdictEffect } = await assertVerdict(session, predicate, verdict.pass, verdict.evidence, since, verdict.inconclusive, verdict.observationLost, changeUndeclared);
             // The assertion IS the proof attempt, so a green one discharges the intent it was drawn for. A
             // red proved nothing, and an unbound intent refuses discharge anyway — see inline-intent.ts.
@@ -482,6 +490,8 @@ export const OBSERVE_TOOLS = [
             session.recordAction(ReticleTool.ASSERT, asRecord(args), {
                 ...verdictEffect,
                 ...checkWords(verdict),
+                // A person's sentence for the check, and the part of an allOf that failed.
+                ...checkIntent(predicate, verdict, asString(args['intent'])),
             });
             // A passing check over the default window (since the last act) is proof of that act, so it
             // joins that step in the recording — otherwise "act, then assert" saves a bare click. An
@@ -502,6 +512,7 @@ export const OBSERVE_TOOLS = [
                 // The filter belongs where the response is assembled anyway — telemetry above keeps the
                 // full text. See gap-novelty.ts.
                 ...(gaps.length > 0 ? { instrumentationGaps: withGapNovelty(session.id, gaps) } : {}),
+                ...engineBlindSpotsField(session.id, predicate, args['intent'], declared),
                 ...advice,
                 ...coverage,
                 // The SAME pointer the journal keeps, not a second lookup — one verdict, one file:line.
@@ -643,7 +654,9 @@ export const OBSERVE_TOOLS = [
             return withSizeCost(noteEmptyRead({
                 calls: listed,
                 ...(droppedOldest > 0 ? { total: matched.length, droppedOldest } : {}),
-                ...('none' !== bodyMode ? bodiesNotCaptured(calls, session.sdkVersion) : {}),
+                ...('none' !== bodyMode
+                    ? bodiesNotCaptured(calls, session.sdkVersion, captureProvedOn(matched))
+                    : {}),
                 /*
                  * Never silent. The agent has to be able to tell "this call had no body" from "the body
                  * is here and you were not shown it", and to know the exact way to get it — otherwise
@@ -692,7 +705,9 @@ export const OBSERVE_TOOLS = [
                 .optional()
                 .describe('Total matches before `limit` — present only when capped.'),
             droppedOldest: z.number().optional().describe('How many older matches `limit` dropped.'),
-            hint: z.object({ totalInWindow: z.number(), byLevel: z.record(z.number()) }).optional(),
+            hint: z
+                .object({ totalInWindow: z.number(), byLevel: z.record(z.string(), z.number()) })
+                .optional(),
             cost: z.object({ bytes: z.number(), tokens: z.number() }).optional(),
             ...bufferOutputShape,
         },
@@ -746,7 +761,3 @@ export const OBSERVE_TOOLS = [
         },
     },
 ];
-/** Narrow a command result to something noteEmptyRead can annotate. */
-function isPlainRecord(value) {
-    return 'object' === typeof value && value !== null && !Array.isArray(value);
-}

package/dist/surface/tools/platform-moment.d.ts

@@ -1,11 +1,10 @@
 import { AgentNudgeKind } from '@reticlehq/core';
-import { type InstrumentedTab } from '../../portal/session/recorded-gaps.js';
 import type { ToolDeps } from './tool-kit.js';
 /** Verified runs kept only on this machine before the platform is worth a sentence. */
 export declare const LOCAL_RUNS_MOMENT = 5;
 /** A `.reticle` this large is history worth keeping somewhere other than one laptop. */
 export declare const LARGE_RETICLE_BYTES: number;
-export declare const CONNECT = "`npx @reticlehq/server connect`";
+export declare const CONNECT = "`reticle connect`";
 export declare function takePlatformMoment(deps: Pick<ToolDeps, 'fs' | 'linkedCloud'> & {
     now?: () => number;
 }, raw: Record<string, unknown>, 
@@ -21,8 +20,7 @@ export declare function resetPlatformMoments(): void;
 export declare const LONG_JOURNEY_ACTS = 1;
 export declare const NudgeText: {
     readonly CONNECT: string;
-    readonly closeGaps: (reason: string) => string;
-    readonly switchOn: (percent: number) => string;
+    readonly SWITCH_ON: string;
     readonly explore: () => string;
 };
 export interface NudgeInput {
@@ -37,12 +35,6 @@ export interface NudgeInput {
     failed: boolean;
     /** Whether the project is linked to the platform. Read only when a kind needs it. */
     linked: () => Promise<boolean>;
-    /** The driven tab's Harness gate, when one is resolved. */
-    gate: {
-        percent: number;
-        unlocked: boolean;
-        reason?: string;
-    } | undefined;
     /** Whether the Harness is switched on, when the platform has said. Read only when needed. */
     harnessOn: () => boolean | undefined;
     /** Whether this call drives the page by hand. */
@@ -58,7 +50,7 @@ export declare function takeNudge(input: NudgeInput): Promise<{
 /** A result that failed: thrown or returned as an error, refused, or a verdict that said no. */
 export declare function resultFailed(raw: Record<string, unknown>, isError: boolean): boolean;
 /**
- * The advisory for one agent call, wired to this daemon: the tab's gate, the project's link and the
+ * The advisory for one agent call, wired to this daemon: the project's link and the
  * Harness switch as the platform last said it. Counted when shown. Never throws.
  */
 export declare function agentNudge(input: {
@@ -66,7 +58,6 @@ export declare function agentNudge(input: {
     tool: string;
     raw: Record<string, unknown>;
     isError: boolean;
-    tab: InstrumentedTab | undefined;
     root: string | undefined;
     harnessOn: () => boolean | undefined;
 }): Promise<string | undefined>;

package/dist/surface/tools/platform-moment.js

@@ -16,8 +16,7 @@
  */
 import { readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { AgentNudgeKind, HARNESS_UNLOCK_COVERAGE, ReticleDir, ReticleTool, Verified, } from '@reticlehq/core';
-import { instrumentationOf } from '../../portal/session/recorded-gaps.js';
+import { AgentNudgeKind, CONNECT_COMMAND, ReticleDir, ReticleTool, Verified, } from '@reticlehq/core';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { DRIVE_RECORD_SUFFIX, reticleDirPaths } from '../../memory/project/dir/reticle-dir.js';
 import { FlakeFileSchema } from '../../language/flows/recording/flake.js';
@@ -33,7 +32,7 @@ const STATUS_EVERY_MS = 10_000;
 /** How many verdicts between size checks: walking `.reticle` is not free either. */
 const SIZE_EVERY = 20;
 const MOMENTS_FILE = ReticleDir.PLATFORM_MOMENTS_FILE;
-export const CONNECT = '`npx @reticlehq/server connect`';
+export const CONNECT = `\`${CONNECT_COMMAND}\``;
 const RUN_FILE = /\.json$/;
 const Moment = {
     LOCAL_RUNS: 'local-runs',
@@ -173,13 +172,12 @@ export function resetPlatformMoments() {
  * One-time advisories, on the agent's own tool results, that point at the platform and the Harness.
  *
  * Reticle has two drivers: the user's coding agent, through these tools (local, free), and Reticle
- * Harness on the platform (opt-in, credits, unlocks at 80% instrumentation). The agent is the one
+ * Harness on the platform (opt-in, credits, no setup score needed). The agent is the one
  * reader who can tell the user the second exists at the moment it would help, so each kind is said:
  *
  *   connect     unlinked, after a verdict: results stay here; `reticle connect` keeps them and lets
- *               the Harness test the whole app, 10 free credits
- *   close_gaps  linked, below the gate: closing the named gaps unlocks the Harness
- *   switch_on   linked, at the gate, Harness off: the user can switch it on
+ *               the Harness test the whole app, with free credits to start
+ *   switch_on   linked, Harness off: the user can switch it on
  *   explore     Harness on, the agent driving a long journey by hand: hand it to explore
  *
  * Guardrails: each kind at most once per agent session per project; never on a result that failed
@@ -193,16 +191,12 @@ export function resetPlatformMoments() {
  * its first hand-driven step rather than after eight.
  */
 export const LONG_JOURNEY_ACTS = 1;
-const UNLOCK_PERCENT = Math.round(HARNESS_UNLOCK_COVERAGE * 100);
 export const NudgeText = {
     CONNECT: 'Tell the user, once, in one line after your answer: this result is only on this machine; ' +
         '`reticle connect` saves it to the Reticle dashboard and lets Reticle Harness test the whole ' +
-        'app — a new account gets 10 free credits.',
-    closeGaps: (reason) => `Tell the user, once, in one line: ${reason} Closing those gaps unlocks Reticle Harness; offer ` +
-        'to close them (`reticle doctor` prints the prompt with each fix).',
-    switchOn: (percent) => `Tell the user, once, in one line: this app is at ${String(percent)}% instrumentation ` +
-        `(${String(UNLOCK_PERCENT)}% unlocks it), so Reticle Harness can be switched on in the HUD's ` +
-        'Settings or the dashboard; it drives whole journeys on the platform and saves them as flows.',
+        'app — a new account gets free credits to start.',
+    SWITCH_ON: "Tell the user, once, in one line: Reticle Harness can be switched on in the HUD's Settings " +
+        'or the dashboard; it drives whole journeys on the platform and saves them as flows.',
     // No count: it was kept per agent connection, which a client may open per call, so "you have
     // driven 1 step by hand" was said after twenty.
     explore: () => 'Reticle Harness is on for this project and you are driving it step by step by hand, so ' +
@@ -247,13 +241,8 @@ export async function takeNudge(input) {
             return fresh(AgentNudgeKind.CONNECT)
                 ? say(AgentNudgeKind.CONNECT, NudgeText.CONNECT)
                 : undefined;
-        const gate = input.gate;
-        if (gate === undefined)
-            return undefined;
-        if (!gate.unlocked && gate.reason !== undefined && fresh(AgentNudgeKind.CLOSE_GAPS))
-            return say(AgentNudgeKind.CLOSE_GAPS, NudgeText.closeGaps(gate.reason));
-        if (gate.unlocked && false === harnessOn && fresh(AgentNudgeKind.SWITCH_ON))
-            return say(AgentNudgeKind.SWITCH_ON, NudgeText.switchOn(gate.percent));
+        if (false === harnessOn && fresh(AgentNudgeKind.SWITCH_ON))
+            return say(AgentNudgeKind.SWITCH_ON, NudgeText.SWITCH_ON);
         return undefined;
     }
     catch {
@@ -271,11 +260,11 @@ const HAND_TOOLS = new Set([
     ReticleTool.ACT_AND_WAIT,
 ]);
 /**
- * The advisory for one agent call, wired to this daemon: the tab's gate, the project's link and the
+ * The advisory for one agent call, wired to this daemon: the project's link and the
  * Harness switch as the platform last said it. Counted when shown. Never throws.
  */
 export async function agentNudge(input) {
-    const { deps, raw, tab } = input;
+    const { deps, raw } = input;
     const linkedCloud = deps.linkedCloud;
     const nudge = await takeNudge({
         session: deps.attachId,
@@ -285,7 +274,6 @@ export async function agentNudge(input) {
         failed: resultFailed(raw, input.isError),
         // No link port (an embedder, a test double): nothing to say about linking.
         linked: async () => linkedCloud === undefined || null !== (await linkedCloud()),
-        gate: tab === undefined ? undefined : instrumentationOf(tab).harnessGate,
         harnessOn: input.harnessOn,
         acted: HAND_TOOLS.has(input.tool),
     });

package/dist/surface/tools/read/complete-snapshot.d.ts

@@ -45,5 +45,11 @@ interface CompletedRead {
     /** Why completion stopped short, for the caller to quote. Present ONLY when `complete` is false. */
     incompleteBecause?: string;
 }
-export declare function readCompleteTree(read: SnapshotReader): Promise<CompletedRead>;
+/**
+ * Read the whole tree under `root` (the whole page when it is undefined), finishing every cut branch.
+ *
+ * `root` is a ref or a CSS selector (reticle#1545). A page that cuts past the read budget elsewhere,
+ * such as a card of 500-option selects, can still be read completely in the part the caller needs.
+ */
+export declare function readCompleteTree(read: SnapshotReader, root?: string): Promise<CompletedRead>;
 export {};

package/dist/surface/tools/read/complete-snapshot.js

@@ -40,10 +40,18 @@ const SnapshotShape = z.object({
     truncated: z.boolean().optional(),
     unread: z.array(z.string()).optional(),
     unreadOverflow: z.literal(true).optional(),
+    /** The scope named no element. The walk then read NOTHING, which is not an empty finished branch. */
+    scopeMissing: z.literal(true).optional(),
 });
-export async function readCompleteTree(read) {
+/**
+ * Read the whole tree under `root` (the whole page when it is undefined), finishing every cut branch.
+ *
+ * `root` is a ref or a CSS selector (reticle#1545). A page that cuts past the read budget elsewhere,
+ * such as a card of 500-option selects, can still be read completely in the part the caller needs.
+ */
+export async function readCompleteTree(read, root) {
     const parts = [];
-    let frontier = [undefined];
+    let frontier = [root];
     let reads = 0;
     const stop = (because) => ({
         tree: parts.join('\n'),
@@ -61,6 +69,9 @@ export async function readCompleteTree(read) {
             reads += 1;
             if (!parsed.success)
                 return stop('a snapshot came back in a shape this read cannot trust');
+            if (true === parsed.data.scopeMissing) {
+                return stop(`\`${scope ?? ''}\` matched no element when it was read, so nothing under it was seen`);
+            }
             parts.push(parsed.data.tree ?? '');
             if (true === parsed.data.unreadOverflow) {
                 return stop('the cut named more branches than one snapshot can carry, so the frontier itself is incomplete and no sequence of re-reads can finish this page');

package/dist/surface/tools/read/query-paginate.js

@@ -30,6 +30,12 @@ export function paginateQueryResult(result, limit, countOnly) {
     // report nothing, but never prefer the array when the browser told us the real number.
     const total = 'number' === typeof counted ? counted : elements.length;
     const truncatedOnWire = total > elements.length;
+    // When the scope did not resolve, 0 is not a count — no subtree was searched. Omit count so
+    // a caller reading only that field does not conclude the element is absent from the page.
+    if (true === record['scopeMissing']) {
+        const { count: _dropped, elements: _els, ...rest } = record;
+        return countOnly ? rest : { ...rest, elements };
+    }
     if (countOnly) {
         const { elements: _dropped, ...rest } = record;
         // `truncated` here means "the sample was capped in transit", not "the count is approximate" —

package/dist/surface/tools/read/query-shape.d.ts

@@ -16,3 +16,12 @@
  * being replaced by a confident wrong query.
  */
 export declare function normalizeQueryArgs(args: Record<string, unknown>): Record<string, unknown>;
+/** How the refusal of an empty find opens: the error table recognizes it by these words. */
+export declare const EMPTY_FIND_OPENING = "Nothing was searched: this find names nothing to find.";
+/**
+ * The error for a query that names nothing to find, or `undefined` when it names something.
+ *
+ * Sent to the page, an empty query answered `count: 0`, which reads as "nothing here matches" about
+ * a question nobody asked. A container asked for itself (`self`) needs no other field.
+ */
+export declare function emptyQueryRefusal(args: Record<string, unknown>): Error | undefined;