@reticlehq/server 2.10.0 → 2.11.0

package/dist/telemetry/daemon-telemetry.js

@@ -13,8 +13,7 @@ import { profileProject } from './project-profile.js';
 import { startUpdateCheck } from '../update/update-nudge.js';
 import { markDaemonStart } from './mcp-connection.js';
 import { markInstrumentationClock } from './app-instrumented.js';
-import { markStallClock, reportInstrumentationStall, STALL_AFTER_MS, } from './instrumentation-stall.js';
-import { readProjectId } from '../cli/cli-port.js';
+import { markStallClock, STALL_AFTER_MS, stallUptime } from '../session/stall-clock.js';
 /** Let the daemon finish coming up before walking the source tree for a profile. */
 const PROJECT_PROFILE_DELAY_MS = 5_000;
 /**
@@ -74,19 +73,18 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
             /* a profile is a nice-to-have; it must never touch the daemon */
         }
     }, PROJECT_PROFILE_DELAY_MS).unref();
+    // Once per daemon run: a warning repeated every ten minutes at somebody already stuck is noise.
+    let stallWarned = false;
     const flushWindow = () => {
-        // BEFORE the idle return, and that ordering is the whole point: a stalled install produces an
-        // empty window by definition — no app, so no tool calls, so nothing to roll up. Checking it
-        // after the early return would make the one case this event exists for the one case it never
-        // sees. It is self-limiting (once per run, never after an app connects), so running it on every
-        // tick costs a comparison.
-        const stalled = reportInstrumentationStall({
-            // Same test `app_instrumented` uses for the same field, so the success and failure events
-            // stay directly comparable: a stamped projectId means `init` has run here.
-            initialized: readProjectId(cwd) !== undefined,
-            agentAttached: metrics.agentEverAttached,
-        }, now);
-        if (stalled) {
+        // BEFORE the idle return, and that ordering still matters for the reason the removed event
+        // documented: a stalled install produces an empty window by definition — no app, so no tool
+        // calls, so nothing to roll up — so checking after the early return would never fire on the one
+        // case worth warning about. What is left here is the WARNING, for a human watching the log; the
+        // metric that used to ride alongside it was removed as a second, less complete way to compute
+        // `daemon_started` minus `app_instrumented`.
+        const waited = stallUptime(now());
+        if (!stallWarned && waited !== undefined && waited >= STALL_AFTER_MS) {
+            stallWarned = true;
             const minutes = Math.round(STALL_AFTER_MS / 60_000);
             process.stderr.write(`[reticle] no app has connected after ${String(minutes)} minutes — ` +
                 'the install may be incomplete. Restart the dev server if you added the Reticle plugin.\n');
@@ -113,15 +111,6 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
             stopped ??= (async () => {
                 clearInterval(flush);
                 clearTimeout(firstFlush);
-                // Last chance to say that no app ever arrived. The periodic path cannot report an
-                // UNATTENDED stall at all — that daemon idle-exits at five minutes and the periodic
-                // threshold is ten — so without this the event only ever describes daemons with an agent
-                // attached, which is not the population it was built to measure. Self-limiting: if the
-                // interval already reported, this returns false and emits nothing.
-                reportInstrumentationStall({
-                    initialized: readProjectId(cwd) !== undefined,
-                    agentAttached: metrics.agentEverAttached,
-                }, now, { atShutdown: true });
                 // The rich one: the whole session in a single event — duration, the tool histogram, error
                 // shapes, verifications, browser launches. This is what replaced the per-tool-call event.
                 await getTelemetry().emit(TelemetryEventKind.DAEMON_STOPPED, {

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

@@ -133,7 +133,7 @@ export declare class SessionMetrics {
     /**
      * Has an agent ever attached to this daemon?
      *
-     * Read by the instrumentation-stall check, which needs to tell two very different silences apart:
+     * Read by the stall clock, which needs to tell two very different silences apart:
      * a daemon nobody is using, and a daemon with an agent sitting on it that has no app to drive.
      * The second is the funnel's failure case and the first is not a problem at all.
      */

package/dist/telemetry/session-metrics.js

@@ -575,7 +575,7 @@ export class SessionMetrics {
     /**
      * Has an agent ever attached to this daemon?
      *
-     * Read by the instrumentation-stall check, which needs to tell two very different silences apart:
+     * Read by the stall clock, which needs to tell two very different silences apart:
      * a daemon nobody is using, and a daemon with an agent sitting on it that has no app to drive.
      * The second is the funnel's failure case and the first is not a problem at all.
      */

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,15 @@
-import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type InstallSource, type McpConnection, type McpOutage, type ToolRefusal, type AppInstrumentation, type InstrumentationStall, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
+import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type InstallSource, type McpConnection, type McpOutage, type ToolRefusal, type AppInstrumentation, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
+/**
+ * PostHog's group type for a licensed customer. Sent as `$groups` so PostHog can aggregate a whole
+ * organisation natively: per-company retention, "which orgs went quiet", one row per customer rather
+ * than one per machine.
+ *
+ * The KEY is the licence id and nothing else. The organisation's NAME is never sent from a customer's
+ * machine, here or anywhere; the name reaches PostHog only if we push it ourselves from the issuance
+ * ledger, which is the one place that mapping lives. So an event still carries no identity, and the
+ * analytics side learns a customer list only when we deliberately upload one.
+ */
+export declare const POSTHOG_GROUP_ORGANIZATION = "organization";
 /**
  * Feedback gets its own, much larger budget — and a retry.
  *
@@ -78,8 +89,6 @@ export interface TelemetryExtra {
     outage?: McpOutage;
     /** `app_instrumented`: an app carrying the SDK reached this daemon for the first time. */
     instrumentation?: AppInstrumentation;
-    /** `instrumentation_stalled`: the daemon waited and no app ever arrived. */
-    stall?: InstrumentationStall;
     /** `reticle_installed` / `init_completed`: which published route brought this install in. */
     installSource?: InstallSource;
 }

package/dist/telemetry/telemetry.js

@@ -42,6 +42,17 @@ const POSTHOG_KEY = 'phc_q4yCxKMXHfWQ43VAz4HxJXZFLqFi4nBbg5v3avemggYo';
  * still key on distinct_id.
  */
 const POSTHOG_PERSONLESS = { $process_person_profile: false };
+/**
+ * PostHog's group type for a licensed customer. Sent as `$groups` so PostHog can aggregate a whole
+ * organisation natively: per-company retention, "which orgs went quiet", one row per customer rather
+ * than one per machine.
+ *
+ * The KEY is the licence id and nothing else. The organisation's NAME is never sent from a customer's
+ * machine, here or anywhere; the name reaches PostHog only if we push it ourselves from the issuance
+ * ledger, which is the one place that mapping lives. So an event still carries no identity, and the
+ * analytics side learns a customer list only when we deliberately upload one.
+ */
+export const POSTHOG_GROUP_ORGANIZATION = 'organization';
 const SEND_TIMEOUT_MS = 2000;
 /**
  * Feedback gets its own, much larger budget — and a retry.
@@ -337,7 +348,6 @@ export const createTelemetry = (opts) => {
             ...(extra?.refusal !== undefined ? { refusal: extra.refusal } : {}),
             ...(extra?.outage !== undefined ? { outage: extra.outage } : {}),
             ...(extra?.instrumentation !== undefined ? { instrumentation: extra.instrumentation } : {}),
-            ...(extra?.stall !== undefined ? { stall: extra.stall } : {}),
             // A SCALAR, so it needs the event build and the wire schema but no entry in `blocks` below —
             // there is nothing to flatten. It still needs both of those, which is the trap `outage` fell
             // into: a field declared on TelemetryExtra and missing from either one is dropped in silence.
@@ -348,14 +358,17 @@ export const createTelemetry = (opts) => {
             // `blocks` entry. Resolved per event off the event's own clock rather than once at startup — an
             // eleven-hour session must not report the status it booted with. All three are absent unless a
             // release has an issuer key baked, so an OSS payload is byte-identical to before.
-            ...licenseFacts(eventTs),
+            // The RESOLVED env, not process.env: createTelemetry takes an env for injection, and reading
+            // the ambient one here would silently ignore it. Identical in production, wrong everywhere the
+            // seam is actually used.
+            ...licenseFacts(eventTs, env),
         };
         // Map the core contract onto PostHog's capture shape: id/name/time move up, the rest are properties.
         // The feedback body is FLATTENED into `feedback_*` properties rather than sent as a nested object:
         // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
         // would be invisible to the exact "which stacks report the most bugs" question this exists to
         // answer. One prefix keeps them grouped in the UI without a nested path.
-        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, refusal, outage, instrumentation, stall, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, refusal, outage, instrumentation, ...rest } = event;
         // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
         // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
         // `sessionId` rides only on events that happened inside a daemon run. A one-shot CLI command
@@ -386,7 +399,6 @@ export const createTelemetry = (opts) => {
             refusal,
             outage,
             instrumentation,
-            stall,
         };
         for (const [prefix, block] of Object.entries(blocks)) {
             for (const [key, value] of Object.entries(block ?? {})) {
@@ -397,7 +409,15 @@ export const createTelemetry = (opts) => {
             event: name,
             distinct_id: distinctId,
             timestamp: new Date(ts).toISOString(),
-            properties: { ...properties, ...POSTHOG_PERSONLESS },
+            properties: {
+                ...properties,
+                ...POSTHOG_PERSONLESS,
+                // Only on a licensed build. An unlicensed event has no organisation to belong to, and an
+                // empty group key would mint a phantom "no org" bucket that every OSS install falls into.
+                ...(event.licenseId !== undefined
+                    ? { $groups: { [POSTHOG_GROUP_ORGANIZATION]: event.licenseId } }
+                    : {}),
+            },
         };
         const body = JSON.stringify({ api_key: apiKey, batch: [capture] });
         const filePath = env[Env.FILE];

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/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,6 +11,7 @@ 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';
@@ -39,8 +40,22 @@ export interface ToolDeps<Ext = unknown> {
     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.
      *

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/docs.json

@@ -32,7 +32,7 @@
   "navigation": {
     "versions": [
       {
-        "version": "2.10.0",
+        "version": "2.11.0",
         "default": true,
         "tabs": [
           {
@@ -183,7 +183,7 @@
               },
               {
                 "group": "Trust & licensing",
-                "pages": ["telemetry", "enterprise"]
+                "pages": ["telemetry", "license-activation", "enterprise"]
               }
             ]
           },

package/docs/enterprise.md

@@ -8,6 +8,8 @@ Enterprise features ship inside the open package and are unlocked by a signed li
 
 > Premium access (how you get + activate it), what's gated, the security/data-handling posture, and the licensing model. Integration mechanics live in [`platform-integration.md`](./platform-integration.md).
 
+> **Already have a key and just need to switch it on?** [Activating a license key](./license-activation) is the step-by-step version: where to set it on each platform, the editor and CI cases, how to read every status, and what to do when it does not work.
+
 ## How premium access works (offline, no phone-home)
 
 Enterprise (`ee/`) features ship **inside the open package**; they're source-available (free for development, testing, and evaluation). A **license key activates them in production**. Activation is verified locally with Ed25519; nothing about your usage ever leaves your machine.
@@ -29,7 +31,7 @@ Enterprise (`ee/`) features ship **inside the open package**; they're source-ava
    expired   license expired. Renew with hey@reticle.sh to keep using enterprise features
    ```
 
-   Every status also reports `gated` (what a licence unlocks in the build you are running) and `contact`, so the command answers "what would this buy me, and how do I get one" without anybody having to find this page first. `gated` is derived from the features the gate actually enforces, so it lists what your build will really refuse rather than a roadmap.
+   Every status reports `contact`, so a reader who is stuck always has somebody to write to. An unlicensed status also reports `gated`, what a licence unlocks in the build you are running, so the command answers "what would this buy me, and how do I get one" without anybody having to find this page first. It is derived from the features the gate actually enforces, so it names what your build will really refuse rather than a roadmap. An `active` licence does not report it: that reader has already bought, and listing feature names at them answers nothing they asked.
 
 4. **Unlock.** Enterprise features now run in production; without a valid key they refuse to run there (a clear error, never a silent half-feature). In eval/dev they always run free.
 5. **Renew.** Keys carry an expiry; `reticle license` warns before it lapses.