@reticlehq/server 2.9.0 → 2.11.0

package/dist/tools/act-tools.js

@@ -8,7 +8,7 @@ import { resolveTargetRef } from './resolve-target.js';
 import { z } from 'zod';
 import { aliasParam } from './alias-args.js';
 import { captureAct, compileSequenceStep } from '../flows/replay.js';
-import { ActionType, ActionWarning, CaptureLoss, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, ReticleCommand, Verified, PredicateKind, } from '@reticlehq/core';
+import { ActionType, ActionWarning, CaptureLoss, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, ReticleCommand, Verified, VerifiedReason, PredicateKind, } from '@reticlehq/core';
 import { assertNativeInputSupported } from './act-danger.js';
 import { leanActResult, mutatedWithin } from './act-view.js';
 import { ReticleTool } from './tool-names.js';
@@ -16,6 +16,10 @@ import { buildReactionReport, summarizeReaction } from '../events/reaction.js';
 import { parsePredicate } from '../events/predicate-parse.js';
 import { causalSummary } from '../capsule/causal-summary.js';
 import { findContradictions } from '../events/contradictions.js';
+import { gapsForAction } from '../honesty/instrumentation-gaps.js';
+import { noteSessionGaps } from '../honesty/gap-ledger.js';
+import { declaresState } from '../events/predicate-asks.js';
+import { isStateUnwatched } from '../honesty/blind-spots.js';
 import { inFlightRequestLabels, repeatedRequestLabels, waitForInFlight, } from './settle-in-flight.js';
 import { waitForReaction } from './react-grace.js';
 import { decideVerified } from '../honesty/verified.js';
@@ -26,7 +30,7 @@ import { saveFailedAssertCapsule } from './act-capsule.js';
 import { buildDivergenceCapsule } from '../capsule/capsule.js';
 import { predicateToExpectedLinks } from '../capsule/predicate-to-links.js';
 import { buildHonestyBlock } from '../honesty/honesty.js';
-import { BlindSpotKind, buildCoverageStatement, blindSpotsFromState, transportGapNote, Coverage, impeachesCapture, } from '../honesty/blind-spots.js';
+import { buildCoverageStatement, blindSpotsFromState, transportGapNote, Coverage, impeachesCapture, } from '../honesty/blind-spots.js';
 import { hasAcceptedWrite } from '../honesty/accepted-write.js';
 import { unreadWriteLabels } from '../honesty/unread-outcome.js';
 import { evaluatePredicate, waitForPredicate, provenExpectedLinks, PredicateSchema, } from '../events/predicate.js';
@@ -432,6 +436,10 @@ export const ACT_TOOLS = [
                 .array(z.unknown())
                 .optional()
                 .describe('Channels that DISAGREE about this action — the UI advanced while its write failed, a success signal fired over a failed request, a response changed nothing, a duplicate fired, a request never settled. OMITTED when clean. Treat any entry as a finding even when the verdict is green: a passing assertion and a contradicted channel is exactly the false green this exists to catch.'),
+            instrumentationGaps: z
+                .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 red that cannot name a file:line, a state assertion with no registered store, a DOM change no signal announced, a route change nothing signalled); never a survey of the page, so an entry is always work worth doing now. OMITTED when the app told Reticle everything it needed. Applying `fix` makes every later verdict on this app stronger, not just this one.'),
             honesty: z
                 .unknown()
                 .describe('The verdict trust block { grade, attribution, coverage, integrity, envelope? } — a green never looks stronger than this. Gate on grade ≥ net AND integrity.clean. Fields that were not measured are OMITTED rather than reported as zero, so treat an absent `envelope` as "not sampled", never as a failure.'),
@@ -561,7 +569,7 @@ export const ACT_TOOLS = [
                 const coverage = buildCoverageStatement(spots);
                 // Nothing subscribed ⇒ the state channel is dark, and the summary must say so rather than
                 // report an empty diff list that reads like a fact about the app. See CausalSummary.
-                const stateUnwatched = spots.some((s) => s.kind === BlindSpotKind.UNWATCHED_STATE && s.count > 0);
+                const stateUnwatched = isStateUnwatched(spots);
                 // Only a spot that IMPEACHES the capture belongs in integrity — see impeachesCapture. A
                 // structural boundary (virtualized rows, a cross-origin frame) is reported as coverage and
                 // must not downgrade a verdict about what WAS observed.
@@ -672,6 +680,25 @@ export const ACT_TOOLS = [
                         repeated: repeatedRequestLabels(windowEvents),
                     },
                 });
+                // Computed once: the verdict block reports it, and the instrumentation gaps are a second
+                // reading of the same evidence rather than a new observation.
+                const actionSummary = causalSummary(windowEvents, { stateUnwatched });
+                const gaps = gapsForAction({
+                    pass: verdict.pass,
+                    proved: decision.verifiedReason === VerifiedReason.PROVED,
+                    sourceKnown: actedSource !== undefined,
+                    ref: asString(args['ref']),
+                    stateAsked: declaresState(until),
+                    stateUnwatched,
+                    domMutated: (session.lastAct.effect().mutatedWithin ?? 0) > 0,
+                    signalsFired: actionSummary.signals.length,
+                    routeChanged: actionSummary.route !== undefined,
+                    routeSignalFired: actionSummary.signals.some((name) => name.startsWith('route')),
+                });
+                // Recorded on the session, so a later "am I done?" can answer with what is STILL missing
+                // rather than with everything that was ever missing. An empty list closes a gap, which is
+                // why it is noted rather than skipped.
+                noteSessionGaps(session, gaps);
                 return withControl(session, {
                     ...decision,
                     effect: leanActResult(actResult.result),
@@ -686,7 +713,10 @@ export const ACT_TOOLS = [
                     ...(capsuleSaved === undefined ? {} : { capsuleSaved }),
                     // The window cannot say whether anything was WATCHING state — that is a level fact the
                     // session holds. Without it an empty `stateDiffs` reads as "the app changed nothing".
-                    summary: causalSummary(windowEvents, { stateUnwatched }),
+                    summary: actionSummary,
+                    // What the APP did not tell Reticle, and the one change that would fix it. Reported only
+                    // where an absence made this very verdict weaker — never as a survey of the page.
+                    ...(gaps.length > 0 ? { instrumentationGaps: gaps } : {}),
                     // Cross-channel disagreement, reported WITH the action that caused it.
                     //
                     // This is the one finding here a human structurally cannot make — they watch one channel,

package/dist/tools/assert-verdict.d.ts

@@ -1,3 +1,4 @@
+import type { InstrumentationGap } from '@reticlehq/core';
 import type { Predicate } from '../events/predicate.js';
 import type { Session } from '../session/session.js';
 import { type Contradiction } from '../events/contradictions.js';
@@ -26,4 +27,5 @@ observationLost?: boolean): Promise<{
     decision: Record<string, unknown>;
     contradictions: Contradiction[];
     coverage: Record<string, unknown>;
+    gaps: InstrumentationGap[];
 }>;

package/dist/tools/assert-verdict.js

@@ -1,4 +1,8 @@
 import { BlindSpotKind, CaptureLoss, PredicateKind } from '@reticlehq/core';
+import { gapsForAction } from '../honesty/instrumentation-gaps.js';
+import { noteSessionGaps } from '../honesty/gap-ledger.js';
+import { declaresState } from '../events/predicate-asks.js';
+import { isStateUnwatched } from '../honesty/blind-spots.js';
 import { findContradictions } from '../events/contradictions.js';
 import { declaredExpectations } from '../events/declared.js';
 import { blindSpotsFromState, buildCoverageStatement, Coverage, impeachesCapture, transportGapNote, } from '../honesty/blind-spots.js';
@@ -122,5 +126,24 @@ observationLost) {
             repeated: repeatedRequestLabels(windowEvents),
         },
     });
-    return { decision: decision, contradictions, coverage };
+    // The same rule the act path uses, fed by what THIS path knows. An assertion drives nothing, so
+    // only two of the four gates can fire here: a red with no remembered source to point at, and a
+    // state assertion against an app that registers no store.
+    const gaps = gapsForAction({
+        pass,
+        sourceKnown: session.lastAct.source() !== undefined,
+        stateAsked: declaresState(predicate),
+        stateUnwatched: isStateUnwatched(spots),
+        domMutated: false,
+        signalsFired: 0,
+        routeChanged: false,
+        routeSignalFired: false,
+    });
+    noteSessionGaps(session, gaps);
+    return {
+        decision: decision,
+        contradictions,
+        coverage,
+        gaps,
+    };
 }

package/dist/tools/contract-tools.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { sessionRoot } from '../project/session-root.js';
 import { CapabilitiesSchema, ContractReadError, FROM_DISK_ARG, ReticleCommand, } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { asString } from './tools-helpers.js';
@@ -59,7 +60,7 @@ export const CONTRACT_TOOLS = [
         },
         handler: async (deps, args) => {
             if (true === args[FROM_DISK_ARG]) {
-                const r = await readContract(deps.fs, deps.reticleRoot);
+                const r = await readContract(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
                 if (!r.ok)
                     throw new Error(r.reason === ContractReadError.MISSING
                         ? 'no .reticle/contract.json on disk — run reticle_contract_save first (or omit fromDisk to read the live session)'
@@ -84,10 +85,11 @@ export const CONTRACT_TOOLS = [
             const res = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CAPABILITIES, {});
             const caps = CapabilitiesSchema.parse(res);
             assertSameProject(deps, asString(args['sessionId']));
-            await writeContract(deps.fs, deps.reticleRoot, caps, deps.now);
+            const root = sessionRoot(deps, asString(args['sessionId']));
+            await writeContract(deps.fs, root, caps, deps.now);
             return {
                 saved: true,
-                path: reticleDirPaths(deps.reticleRoot).contract,
+                path: reticleDirPaths(root).contract,
                 testidCount: caps.testids.length,
                 signalCount: caps.signals.length,
             };

package/dist/tools/coverage-tools.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coverageRegressed, observabilityOf } from '../honesty/observability.js';
 import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { asString } from './tools-helpers.js';
@@ -62,6 +63,22 @@ export const COVERAGE_TOOLS = [
                 .number()
                 .optional()
                 .describe('Controls you drove that are no longer on the page — usually because the action SUCCEEDED and removed them (archive/delete/submit/navigate). Counted separately so `exercised: 0` never appears immediately after real work.'),
+            instrumentationGaps: z
+                .array(z.unknown())
+                .optional()
+                .describe('What this app still cannot tell Reticle, as of your most recent verdict — each entry is { kind, missing, cost, fix, source?, ref? }. These are not controls you skipped; they are checks this app CANNOT answer until it is instrumented, so driving the untouched list will not close them. Apply each `fix` and re-verify: the gap disappears from this list when the app can answer, and every later verdict on this app gets stronger. OMITTED when nothing is missing.'),
+            unproven: z
+                .boolean()
+                .optional()
+                .describe('True when verification is NOT finished for a reason driving more controls cannot fix — instrumentationGaps is non-empty. Present only when true, so its absence is not a claim.'),
+            observability: z
+                .object({ driven: z.number(), observable: z.number(), percent: z.number().optional() })
+                .optional()
+                .describe('Of the controls you DROVE, how many Reticle could fully observe. `untouched` above is work left for you; this is work left in the APP, and driving more controls does not move it. `percent` is OMITTED when nothing was driven, because 0/0 is not 100%.'),
+            observabilityRegressed: z
+                .object({ was: z.number(), now: z.number() })
+                .optional()
+                .describe('This project has previously reached a HIGHER observability than this run did. Usually means an assertion or an instrumented path was removed — the cheapest way to stop a gap firing is to stop asserting the thing that revealed it. Present only when a drop is real and the run was large enough to compare.'),
         },
         handler: async (deps, args) => {
             const sessionId = asString(args['sessionId']);
@@ -77,11 +94,27 @@ export const COVERAGE_TOOLS = [
             // `droveGone` keeps the other honesty: archive/delete/submit remove their own control, so a
             // drive that WORKED must not read as no coverage at all.
             const { exercised, droveGone, untouched } = exercisedCount(parseControls(tree), session.actedRefs(), session.actedLabels());
+            // The other half of "am I done?". `untouched` answers what you did not DRIVE; this answers
+            // what this app cannot ANSWER, which no amount of further driving will change. Reporting the
+            // first without the second is how an agent finishes a pass believing it verified something the
+            // app was never able to confirm.
+            const gaps = session.gaps?.open() ?? [];
+            // The number, and the floor under it, together. A coverage figure that can only ever be
+            // reported and never contradicted is one an agent learns to satisfy rather than to earn.
+            const observability = observabilityOf(session.actedRefs(), gaps);
+            const best = await deps.project.bestObservability();
+            const regressed = coverageRegressed(best, observability);
+            if (observability.percent !== undefined) {
+                await deps.project.raiseObservability(observability.percent);
+            }
             return {
                 total: parseControls(tree).length,
                 exercised,
                 untouched,
                 ...(droveGone > 0 ? { alsoDroveGone: droveGone } : {}),
+                ...(gaps.length > 0 ? { instrumentationGaps: gaps, unproven: true } : {}),
+                observability,
+                ...(regressed === undefined ? {} : { observabilityRegressed: regressed }),
             };
         },
     },

package/dist/tools/dynamic-tools.js

@@ -75,7 +75,7 @@ export function buildDynamicTools(allTools, profile) {
         };
     const reticleTools = {
         name: ReticleTool.TOOLS,
-        description: 'Discover Reticle tools on demand. Call with no arguments to list every tool (name + one-line summary); call with names:["reticle_network", …] to load full descriptions and parameters for specific tools. Then invoke them with reticle_run. This avoids paying for every tool definition on every turn. To make a verification REUSABLE (record once, replay free forever), the flow workflow lives here: reticle_record{action:"start"} → act → reticle_flow_save → reticle_flow_verify (and reticle_flow_heal on drift). Load those names when you want to save or re-run a flow.',
+        description: 'Discover Reticle tools on demand. Call with no arguments to list every tool (name + one-line summary); call with names:["reticle_network", …] to load full descriptions and parameters for specific tools. Then invoke them with reticle_run. This avoids paying for every tool definition on every turn. To make a verification REUSABLE (record once, replay free forever), the flow workflow lives here: reticle_record{action:"start"} → act → reticle_flow_save → reticle_verify{action:"flows"} (and reticle_flow_heal on drift). Load those names when you want to save or re-run a flow.',
         inputSchema: {
             names: z
                 .array(z.string())

package/dist/tools/error-recovery.js

@@ -129,7 +129,7 @@ export const RECOVERY = {
         'synchronous task, an alert/confirm dialog); reticle_console usually shows what it hit. Retry ' +
         'once the cause is addressed.',
     FLOW_STEP_MISSING: 'A recorded step points at an element that is not on the page now. Either the app changed under ' +
-        'the flow — run reticle_flow_heal to re-anchor it, then reticle_flow_verify — or an earlier step ' +
+        'the flow — run reticle_flow_heal to re-anchor it, then reticle_verify{action:"flows"} — or an earlier step ' +
         'did not do what it used to, leaving the run on the wrong page: check reticle_snapshot to see ' +
         'where it actually is. This is app/flow drift, which is exactly what the flow exists to catch.',
     NO_POOL: 'Reticle cannot launch its own browser here: the daemon-managed pool is absent, or Playwright ' +

package/dist/tools/feedback-tools.js

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

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

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

package/dist/tools/invoke-tool.js

@@ -47,14 +47,21 @@ const REF_MINTING_TOOLS = new Set([
     ReticleTool.QUERY,
     ReticleTool.INSPECT,
     ReticleTool.EXPLORE,
-    ReticleTool.CRAWL,
+    // `crawl` mints refs for the controls it drives and `coverage` for the ones it reports untouched.
+    // Both are actions on the merged verify tool now.
+    ReticleTool.VERIFY,
 ]);
 export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.SNAPSHOT,
     ReticleTool.QUERY,
     ReticleTool.INSPECT,
-    ReticleTool.COVERAGE,
-    ReticleTool.VERIFY_CHANGE,
+    // Merged change/flows/affected/coverage/crawl. Its members were SPLIT across bound and exempt —
+    // coverage/change/crawl bound, flow_verify exempt because it returns its own suite contract — and
+    // a merged tool has to be one or the other. Bound is the right side: `crawl` drives the app
+    // itself, so a throttled or event-dropping tab is exactly the condition its verdict depends on,
+    // and dropping the health disclosure there to protect a sibling's output shape would trade an
+    // honesty signal for a formatting preference.
+    ReticleTool.VERIFY,
     ReticleTool.ACT,
     ReticleTool.ACT_SEQUENCE,
     ReticleTool.ACT_AND_WAIT,
@@ -74,7 +81,6 @@ export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.STATE,
     ReticleTool.STORAGE,
     ReticleTool.EXPLORE,
-    ReticleTool.CRAWL,
     ReticleTool.SCROLL_TO,
     ReticleTool.NAVIGATE,
 ]);
@@ -90,7 +96,6 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     ReticleTool.FLOW_SAVE, // sessionId only scopes the write to the app's flow subdir; disk-side
     ReticleTool.FLOW, // merged list/load/delete — sessionId only scopes the project; all disk-side
     ReticleTool.FLOW_REPLAY, // returns its own FlowReplayResult contract (+ auto-records a run)
-    ReticleTool.FLOW_VERIFY, // returns its own SuiteVerdict contract (replays the whole suite)
     ReticleTool.FLOW_SAVE_RECORDED, // reads the recording buffer, writes disk
     ReticleTool.FLOW_HEAL, // returns its own FlowHealResult contract
     ReticleTool.PROJECT, // reads .reticle/project.json

package/dist/tools/observe-tools.js

@@ -264,7 +264,7 @@ export const OBSERVE_TOOLS = [
             // that guessed `urlContains` on route (net's spelling) and got unrecognized_keys.
             'Predicate to evaluate. Kinds: { signal, name } { net, urlContains|method|status|count|bodyContains } ' +
                 '{ state, path|equals } { route, pathname (exact) | contains (path+query+hash) } ' +
-                '{ element, testid|role|text } { text } { console, level|absent } { animation, name } ' +
+                '{ element, testid|role|text } { text } { console, level|contains|absent } { animation, name } ' +
                 '{ settled } — combine with { allOf | anyOf | not }. Prefer a signal/net/state consequence ' +
                 'over element/text presence.'),
             until: PredicateSchema.optional().describe("Alias for `predicate` (act_and_wait's name)."),
@@ -318,6 +318,10 @@ export const OBSERVE_TOOLS = [
                 .array(z.object({ kind: z.string(), count: z.number() }))
                 .optional()
                 .describe('Which regions were unobservable, when coverage is partial.'),
+            instrumentationGaps: z
+                .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.'),
         },
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
@@ -341,11 +345,13 @@ export const OBSERVE_TOOLS = [
                     : assertsDerivedIpcStatus(predicate)
                         ? { advice: DERIVED_IPC_STATUS_ADVICE }
                         : {};
-            const { decision, contradictions, coverage } = await assertVerdict(session, predicate, verdict.pass, since, verdict.inconclusive, verdict.observationLost);
+            const { decision, contradictions, coverage, gaps } = await assertVerdict(session, predicate, verdict.pass, since, verdict.inconclusive, verdict.observationLost);
             return withControl(session, {
                 ...decision,
                 ...verdict,
                 ...(contradictions.length > 0 ? { contradictions } : {}),
+                // What the app did not tell Reticle, on the same rule the act path uses.
+                ...(gaps.length > 0 ? { instrumentationGaps: gaps } : {}),
                 ...advice,
                 ...coverage,
                 ...lastActSourceOnFailure(session, verdict.pass),

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

@@ -11,12 +11,13 @@ import type { RealInputProvider } from '../input/real-input.js';
 import type { BaselineStore } from '../project/baselines.js';
 import type { RecordingStore } from '../flows/recordings.js';
 import type { FileSystemPort } from '../project/fs-port.js';
+import type { ArtifactRoot } from '../project/artifact-root.js';
 import type { FlowStore } from '../flows/flows.js';
 import type { ProjectStore } from '../project/project-store.js';
 import type { AnnotationStore } from '../flows/annotation-store.js';
 import type { BrowserPool } from '../pool/browser-pool.js';
 import type { ChromiumProbe } from '../cli/chromium-hint.js';
-export interface ToolDeps {
+export interface ToolDeps<Ext = unknown> {
     sessions: SessionManager;
     /** shared one-browser/N-context pool for headless leases. undefined ⇒ lease tools report unavailable. */
     pool?: BrowserPool;
@@ -39,8 +40,22 @@ export interface ToolDeps {
     realInput?: RealInputProvider;
     /** injected filesystem seam (tests pass a fake/temp-dir adapter). */
     fs: FileSystemPort;
-    /** absolute.reticle path (index.ts computes cwd/.reticle). */
+    /** absolute.reticle path (index.ts computes cwd/.reticle). The FALLBACK, not the answer. */
     reticleRoot: string;
+    /**
+     * Which `.reticle` a SESSION's artifacts belong in, resolved per call.
+     *
+     * `reticleRoot` above is fixed at construction from the daemon's own `process.cwd()`, which is a
+     * statement about where the daemon was launched and was being read as a statement about which
+     * project is being verified. Those are usually not the same tree: an editor starts a user-scoped
+     * MCP server wherever it likes, so flows landed outside the repo they verify, or died on
+     * `mkdir '/.reticle'`.
+     *
+     * Optional because every existing construction of ToolDeps predates it and because a consumer
+     * embedding this engine may not have a filesystem to search. Absent ⇒ `reticleRoot`, which is
+     * exactly today's behaviour.
+     */
+    artifactRootFor?: (projectId: string | undefined) => ArtifactRoot;
     /**
      * This daemon's OWN project id, derived from the directory it was started in.
      *
@@ -59,8 +74,23 @@ export interface ToolDeps {
      * ToolDeps keeps working; absent falls back to the default port.
      */
     bridgePort?: number;
+    /**
+     * A consumer's OWN dependencies, carried through untouched.
+     *
+     * Nothing in this package reads it. It exists so a consumer embedding the engine can add tools of
+     * its own — answering out of a store this package has never heard of — without either widening the
+     * fields above with a stranger's vocabulary or forking to get a handle through.
+     *
+     * The type parameter, rather than `unknown`, is what keeps the seam typed: a consumer writes
+     * `ToolDef<TheirExt>` once and their handlers see their own type. Casting out of `unknown` in every
+     * handler is how a typed seam quietly becomes an untyped one.
+     *
+     * Optional, and defaulted to `unknown`, so every existing construction of this bag — and every test
+     * that builds one — is unchanged.
+     */
+    ext?: Ext;
 }
-export interface ToolDef {
+export interface ToolDef<Ext = unknown> {
     name: string;
     description: string;
     inputSchema: z.ZodRawShape;
@@ -86,7 +116,19 @@ export interface ToolDef {
      * example that does not validate is worse than none at all.
      */
     example?: Record<string, unknown>;
-    handler: (deps: ToolDeps, args: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Declared method-style, not as a property, and that is load-bearing rather than stylistic.
+     *
+     * Under `strictFunctionTypes` a property holding a function has CONTRAVARIANT parameters, so
+     * `ToolDef<TheirExt>` and `ToolDef<unknown>` become mutually unassignable and a consumer composing
+     * `[...TOOLS, ...theirTools]` needs a cast — as does every internal helper that then touches the
+     * array. Method-style parameters are checked bivariantly, which collapses all of that.
+     *
+     * The unsoundness bivariance admits is that a handler written against `ToolDeps<TheirExt>` could be
+     * handed a bag carrying no `ext` at all. That costs nothing here, because `ext` is optional by
+     * design: any handler reading it already has to survive `undefined`.
+     */
+    handler(deps: ToolDeps<Ext>, args: Record<string, unknown>): Promise<unknown>;
 }
 export declare const sessionIdShape: {
     sessionId: z.ZodOptional<z.ZodString>;

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

@@ -46,6 +46,8 @@ export declare const ReticleTool: {
     readonly AFFECTED: "reticle_affected";
     readonly COVERAGE: "reticle_coverage";
     readonly VERIFY_CHANGE: "reticle_verify_change";
+    /** Merged: change/flows/affected/coverage/crawl — "what is proved, and what is not". */
+    readonly VERIFY: "reticle_verify";
     /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
     readonly PROJECT: "reticle_project";
     /** explicitly record a run outcome (the manual companion to auto-recording). */

package/dist/tools/tool-names.js

@@ -47,6 +47,8 @@ export const ReticleTool = {
     AFFECTED: 'reticle_affected',
     COVERAGE: 'reticle_coverage',
     VERIFY_CHANGE: 'reticle_verify_change',
+    /** Merged: change/flows/affected/coverage/crawl — "what is proved, and what is not". */
+    VERIFY: 'reticle_verify',
     /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
     PROJECT: 'reticle_project',
     /** explicitly record a run outcome (the manual companion to auto-recording). */

package/dist/tools/tool-surface.js

@@ -206,15 +206,14 @@ export const EXTENDED_TOOL_NAMES = new Set([
     ReticleTool.CAPABILITIES,
     ReticleTool.FLOW_SAVE,
     ReticleTool.FLOW_REPLAY,
-    ReticleTool.FLOW_VERIFY,
     ReticleTool.RECORD,
     ReticleTool.SCREENSHOT,
     ReticleTool.VISUAL_DIFF,
     ReticleTool.CLOCK,
     ReticleTool.NETWORK_MOCK,
     ReticleTool.STORAGE,
-    ReticleTool.VERIFY_CHANGE,
-    ReticleTool.CRAWL,
+    // Merged change/flows/affected/coverage/crawl — one name where three of these used to sit.
+    ReticleTool.VERIFY,
 ]);
 /**
  * The verify surface: one acting tool that returns a verdict, plus the two meta-tools that reach

package/dist/tools/tools.js

@@ -508,7 +508,7 @@ export const MERGE_PLANS = [
     },
     {
         name: ReticleTool.FLOW,
-        description: 'Saved-flow management: { action: "list" } names every saved flow, "load" reads+validates one by flowName, "delete" removes one. The hot verbs (flow_save, flow_replay, flow_verify, flow_heal) stay separate.',
+        description: 'Saved-flow management: { action: "list" } names every saved flow, "load" reads+validates one by flowName, "delete" removes one. The hot verbs (flow_save, flow_replay, flow_heal) stay separate; whole-suite replay is reticle_verify { action: "flows" }.',
         members: {
             list: ReticleTool.FLOW_LIST,
             load: ReticleTool.FLOW_LOAD,
@@ -531,6 +531,21 @@ export const MERGE_PLANS = [
         // is the one that must not need a schema lookup first.
         example: { action: 'yield', mode: 'waiting' },
     },
+    {
+        name: ReticleTool.VERIFY,
+        description: 'What is proved, and what is not — by action. Start from a change: { action: "affected" } names which saved flows must re-verify for the files you edited (pass `files`, and/or `since` for a git ref), and "change" goes further and actually replays them, answering with one `verified` plus `because`. `unknown` there is the honest answer when NO saved flow covers the change: nothing ran, so nothing was proved, and it is never reported as green. Without a change to start from: "flows" replays every saved flow for one consolidated suite verdict (deterministic, no LLM per flow), and "coverage" lists the interactive controls you have and have NOT driven this session — an untouched list still holding the controls your change affects means you are not done. "crawl" is the no-script option: it drives every reachable control itself and reports single-channel faults (console errors, failed requests, dead controls) and CONTRADICTIONS, two channels disagreeing about the same click — the false greens a human cannot see, because a human watches the screen and the screen looks correct. DESTRUCTIVE: crawl really clicks, and may navigate or mutate state.',
+        members: {
+            change: ReticleTool.VERIFY_CHANGE,
+            flows: ReticleTool.FLOW_VERIFY,
+            affected: ReticleTool.AFFECTED,
+            coverage: ReticleTool.COVERAGE,
+            crawl: ReticleTool.CRAWL,
+        },
+        // No default action ON PURPOSE. The name implies no single member, and one of them really
+        // clicks: a fallthrough that guessed wrong would drive the app rather than read it. Every action
+        // is explicit, which for `crawl` is the whole safety story.
+        example: { action: 'change', files: ['src/App.tsx'] },
+    },
     {
         name: ReticleTool.LEASE,
         description: 'Isolated headless contexts from the shared pool: { action: "acquire" } leases one and navigates it to the app URL, "release" closes it and frees the slot.',

package/docs/README.md

@@ -69,6 +69,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [vs-screenshots.mdx](vs-screenshots.mdx) | why a better vision model does not fix a non-visual bug |
 | [telemetry.md](telemetry.md) | what is collected, and how to turn it off |
 | [local-registry.md](local-registry.md) | installing an unpublished build |
+| [license-activation.mdx](license-activation.mdx) | you have a key: where to set it, how to confirm it, what to do when it fails |
 | [enterprise.md](enterprise.md) | the licensed surface |
 
 ## For people working on Reticle

package/docs/agent-cheatsheet.md

@@ -115,7 +115,7 @@ The tools advertised DIRECTLY, i.e. what you'll use 90% of the time. Everything
 
 Frequently useful but NOT core, so reach them through `reticle_run({ tool, args })`: `reticle_capabilities` (the app's whole testable surface in one call; `{fromDisk:true}` needs no browser), `reticle_domain` (learn the app + gaps), `reticle_baseline {action:"diff"}`, `reticle_project` (run history).
 
-**Reach past core when…** you need to record/replay a journey (`reticle_record {action:"start"}/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_flow_heal`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_crawl` clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_query` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven mode), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session {action:"end"}` / `reticle_session {action:"resume"}` / `reticle_session {action:"messages"}`, and **`reticle_session {action:"review"}`** to drain + fix the bugs the human flagged from the panel).
+**Reach past core when…** you need to record/replay a journey (`reticle_record {action:"start"}/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_flow_heal`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_verify {action:"crawl"}` clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_query` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven mode), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session {action:"end"}` / `reticle_session {action:"resume"}` / `reticle_session {action:"messages"}`, and **`reticle_session {action:"review"}`** to drain + fix the bugs the human flagged from the panel).
 
 ## flows vs baselines vs project.json (the persistence layers)
 
@@ -160,4 +160,4 @@ Recent additions, each of which answers a question agents were previously asking
 - **Cap broad reads.** `reticle_query` takes `limit` (caps descriptors; reports `total`/`truncated`) and `count_only` (just the match count). `reticle_network` / `reticle_console` take `limit` (most-recent-N, reports `droppedOldest`) and carry the same `cost` hint, so a busy page or wide window never floods your context unnoticed.
 - **A saved flow tells you if it's a real test.** `reticle_flow_save` returns `assertions.grade` (`asserted` / `presence-only` / `assertion-free`); if it's not `asserted`, add a consequence (`reticle_annotate` assert-signal/assert-net or a success-state) so it can't pass while broken. On replay, an ambiguous heal (two testids tie) is surfaced, never auto-applied. And an `apply` heal re-replays the rebound flow and **refuses to write** if the success consequence no longer fires (`status:consequence_broken`): it heals the locator, never the intent.
 - **Predicate schema is not bloated.** The recursive predicate DSL used by `reticle_assert` / `reticle_wait_for` / `reticle_act_and_wait` is **factored, not inlined**: when converted to the JSON Schema MCP sends, the predicate body is emitted **once** (~2.7k chars ≈ **~685 tokens** per tool) and recursion is handled by self-`$ref` (`#/properties/predicate`), with no per-recursion duplication. No action needed.
-- **One tool surface.** Reticle advertises the core set directly (sessions/navigate/snapshot/query/act/act_and_wait/observe/network/console/wait_for/assert/state/inspect/feedback/session: the whole detect loop, plus the file-pointer, the feedback channel and the handback) PLUS two meta-tools that keep every other tool one call away: `reticle_tools` (discover; no args lists every tool name + summary, `names:[…]` loads full params on demand) and `reticle_run({ tool, args })` (invoke any tool by name; a top-level `sessionId` is forwarded to the target, so you need not nest it in `args`). So to record/replay/verify a flow, call `reticle_run({ tool:"reticle_flow_verify", sessionId })` (or `reticle_tools` first to see params). There is nothing to pick. `RETICLE_ADVERTISE_ALL_TOOLS=1` (read by the daemon at startup, so restart it) advertises everything with output schemas: a verification switch for suites, not a way to run agents. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.
+- **One tool surface.** Reticle advertises the core set directly (sessions/navigate/snapshot/query/act/act_and_wait/observe/network/console/wait_for/assert/state/inspect/feedback/session: the whole detect loop, plus the file-pointer, the feedback channel and the handback) PLUS two meta-tools that keep every other tool one call away: `reticle_tools` (discover; no args lists every tool name + summary, `names:[…]` loads full params on demand) and `reticle_run({ tool, args })` (invoke any tool by name; a top-level `sessionId` is forwarded to the target, so you need not nest it in `args`). So to record/replay/verify a flow, call `reticle_run({ tool:"reticle_verify", args:{ action:"flows" }, sessionId })` (or `reticle_tools` first to see params). There is nothing to pick. `RETICLE_ADVERTISE_ALL_TOOLS=1` (read by the daemon at startup, so restart it) advertises everything with output schemas: a verification switch for suites, not a way to run agents. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.