@reticlehq/server 2.10.0 → 2.11.0

package/SKILL.md

@@ -14,6 +14,18 @@ This file is the whole critical path and nothing else. Everything it leaves out
 
 **Do not tell the user Reticle is set up until step 5 has produced a verdict.** The most common failure in the field is an agent that finishes step 1, reports success, and leaves a user with config files and no instrumented page.
 
+## Setup runs to the end without you
+
+**Do not stop, and do not ask the user anything, until their app is running with Reticle inside it and a session is connected.** Everything between here and that point is yours to do: run `init`, fix the wiring it could not, start the dev server, open the browser. Not one of those needs a human, and every one of them has been the place an onboarding turn died with nothing to show.
+
+Questions you must not ask, because the repo you are sitting in already answers them: which framework, which package manager, which port, which editor or MCP client, whether to start the dev server, whether to open the browser, whether to carry on. Decide, act, and say what you did in one line.
+
+There are exactly three places you may stop, and none is a question about a preference:
+
+1. **No recognisable dev script in `package.json`.** Say so; do not invent one.
+2. **Your host asks the human to approve a command.** That prompt belongs to the host. Never bypass or suppress it, and take a refusal as the answer.
+3. **On a first install only, the client restart that loads the MCP tools** (step 2). Even then, keep going until the app is running and connected, and stop for the restart last, with only the drive left.
+
 Setup requires a client restart, which ends your turn. This file was fetched into the context that just ended, so nothing carries it across unless you make it. **Before you trigger the restart, write the remaining steps into `RETICLE-SETUP.md` at the repo root**, one line each, with the step you stopped at marked. That file is what you re-read afterwards. Delete it once step 5 has produced a verdict.
 
 Better still, install the on-disk copy first. It survives the restart on its own, and it is the same content:
@@ -80,25 +92,29 @@ RETICLE_INSTALL_SOURCE=skill_file npx @reticlehq/server@latest init
 
 It detects the framework, package manager and UI library, registers the MCP server with the agents on the machine, installs the SDK, writes `.reticle.json` and the `/reticle` command, wires the build config, and scaffolds a capabilities file from the `data-testid` values it found.
 
-**Ask nothing:** not the framework, package manager, port, editor, or MCP client. Every one is answerable from the repo you are sitting in. In a monorepo run it at the root anyway; it finds the app under `apps/*` or `packages/*`.
+**Ask nothing:** not the framework, package manager, port, editor, or MCP client. Every one is answerable from the repo you are sitting in. In a monorepo run it at the root anyway. With one app under `apps/*` or `packages/*` it wires that app silently. With several it wires nothing, lists them, and names the flag: re-run with `--app <dir>` for the one the user is working in, the one their request named, or the one whose `package.json` has the dev script. **Pick it yourself and re-run.** Asking which app they meant is the most likely place this whole install stops, and the answer is almost always in the request you were already given.
 
 **Never ask about the port.** There are two, and conflating them is a top setup failure. The dev-server port (3000, 5173) belongs to the project's own dev script and the daemon never binds it. The bridge port (**4400**) is the daemon-to-SDK channel and defaults correctly.
 
 Read the report: `✓` applied, `·` already wired, `–` skipped, `ℹ` done but incomplete in a way that matters, `⚠` needs your edit. **`⚠` and `ℹ` both need you.** `ℹ` is the one people skim past: the step ran, and something about the result still stops a session appearing. Each line carries the exact snippet. A non-zero exit is a to-do list, not a failed install. Fix every `⚠` before moving on. Per-framework wiring is at `https://docs.reticle.sh/install-manual.md`.
 
-## 2. Register the MCP server, then restart the client.
+**If the user gave you a license key**, along with the install request or at any later point, see [License key](#license-key) below and do it before moving on.
 
-Call `reticle_sessions`. If the tool exists, skip to step 3.
+## 2. Check for the tools. Do not stop for them.
 
-If it does not: your client read its server list at startup and has not re-read it. No retry loads it. `init` registers globally once per machine, so this bites on the first install only.
+Call `reticle_sessions`. If the tool exists, go to step 3 and never mention a restart.
 
-Say this once and then stop:
+If it does not: your client read its server list at startup and has not re-read it. No retry, config edit or slash command loads it into the process you are already in. `init` registers globally once per machine, so this bites on the first install only.
 
-> "Reticle is installed. Restart your client so it picks up the new MCP server, then say **'continue Reticle setup'**. Three steps are left, and your app is not instrumented until they are done."
+**This is not a reason to stop.** Steps 3 and 4 need no MCP tools at all: they are a build config, a dev server and a browser tab, and every one of them is yours to do from the shell. An install that halts here leaves the user with config files, an uninstrumented page, and a question to answer; that is the single most common failure in the field, and it is this paragraph's fault when it happens.
+
+So carry straight on through steps 3 and 4. Ask for the restart **once, at the end**, when a session is connected and the only thing left is the drive:
+
+> "Reticle is installed and your app is connected. Restart your client so it picks up the MCP server, then say **'continue Reticle setup'**. One step is left: driving a flow."
 
 Claude Code: restart (`/mcp` does not re-read the config). VS Code: press Start in `.vscode/mcp.json`. Cursor, Windsurf, Zed: reload the window.
 
-**Do not report setup as finished here.** When the tools return, resume at step 3.
+**Do not report setup as finished at that point either.** When the tools return, resume at step 5.
 
 ## 3. Wire the SDK into the app, and start the dev server.
 
@@ -132,7 +148,17 @@ Five guards, none optional:
 4. **Background it, and say so.** A dev server the human does not know about is the same failure one step later.
 5. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.
 
-Then ask the user to open the app in their browser.
+Then open the app yourself. Do not ask the user to do it. A setup turn that ends on "now open your browser" ends with nothing verified:
+
+```bash
+npx @reticlehq/server open <the url the dev server is serving>
+```
+
+That reuses an already-connected tab or opens a new one, and waits for the page to register. On a headless machine with no browser to open, take a tab Reticle owns instead, once the tools are reachable:
+
+```
+reticle_run({ tool: "reticle_lease", args: { action: "acquire", url: "<the same url>" } })
+```
 
 ## 4. Prove a page is connected. This is a gate.
 
@@ -159,7 +185,7 @@ Drive it in as few calls as you can. Every call is a full model turn, and in a c
 3. `reticle_act_and_wait({ ref, action, until })` for the final step only. This is the call that produces the verdict, and `until` names the expected consequence before the action fires.
 4. `reticle_state()` once at the end.
 
-Four calls for a login, not fourteen. If `reticle_state` comes back empty or `hasCapabilities` is false, the generated capabilities file registered no store. Say so in one line and offer to finish it. Never report a clean install over an empty state read.
+Four calls for a login, not fourteen. If `reticle_state` comes back empty or `hasCapabilities` is false, the capabilities file `init` generated registered nothing, which is what its `ℹ AGENT: finish the capabilities file` line was telling you. **Finish it yourself, before you drive**: open `src/reticle-dev.*`, register the app's store if it has one, and list the `testids` the flow you picked actually touches. Do not offer, and do not ask; it is a few lines in a file `init` already wrote for you. Never report a clean install over an empty state read.
 
 **Then save what you just drove.** Two calls, and they are what make every future check a single call instead of a repeat of this one. Wrap the drive above in a recording:
 
@@ -190,6 +216,18 @@ Stop here. Do not continue into VERIFY.
 
 ---
 
+# License key
+
+Enterprise features are unlocked by a signed key, verified locally with Ed25519 and **no network call**. If the user hands you one, during setup or at any later point:
+
+1. Append `RETICLE_LICENSE_KEY=<key>` to the project's `.env`, creating the file if it is not there. The CLI folds a project-local `.env` into the environment on every invocation, so nothing else has to change.
+2. Make sure `.env` is in `.gitignore`. A license key in git is a leaked credential, so check before you write and add the line if it is missing.
+3. Confirm with `npx @reticlehq/server license`, which prints `active`, `eval`, `missing` or `expired`.
+
+Never echo the key back in your reply, and never put it in a commit, a code comment, or a feedback report. The rest: `curl https://docs.reticle.sh/enterprise.md`.
+
+---
+
 # VERIFY
 
 **Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** Everything else (`act`, `snapshot`, `query`, `navigate`, `observe`, `network`, `console`) moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.

package/dist/dev/stale-issue-guard.d.ts

@@ -0,0 +1,43 @@
+/**
+ * An issue we have already fixed must not still read as available work.
+ *
+ * Three contributor PRs died on arrival in one week for this. #373 was filed at 09:52 and fixed by
+ * us at 12:33 the same day, then left open for three more days — somebody started on it on day two.
+ * #398 shipped and stayed open; a second contributor rebuilt it from scratch. `GITHUB.md` already
+ * documents the same failure costing three contributors before either of those, which makes this the
+ * third recurrence of a defect we have written down and asked ourselves to remember.
+ *
+ * Remembering is not a mechanism, and this is the smallest one that works: a commit saying it closes
+ * an issue is a claim that the issue is done. If that issue is still open and unlabelled afterwards,
+ * the tracker is lying to whoever reads it next — and the person it lies to is by definition someone
+ * looking for something to work on.
+ *
+ * ## Why `fixed-pending-release` is an accepted answer
+ *
+ * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
+ * ships. The label is what tells a contributor not to start, so the label — not the closure — is
+ * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
+ * when they close things, only to say so.
+ *
+ * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
+ * below testable without a network or a repo.
+ */
+export interface IssueState {
+    number: number;
+    state: 'open' | 'closed';
+    labels: readonly string[];
+}
+/** The label that means "fixed, waiting for a release" — an honest reason to still be open. */
+export declare const PENDING_RELEASE_LABEL = "fixed-pending-release";
+export declare function closedRefsIn(commitMessage: string): number[];
+/**
+ * Of the issues these commits claimed to close, the ones still reading as available work.
+ *
+ * An issue that could not be looked up is deliberately silent rather than failing. A rate limit, a
+ * transferred issue or a deleted one would otherwise turn this red for a reason unrelated to what it
+ * guards, and a guard that goes red for unrelated reasons gets disabled — which costs more than the
+ * defect it was catching.
+ */
+export declare function staleIssues(claimed: readonly number[], issues: readonly IssueState[]): number[];
+/** The message the guard prints. Held here so the check and its tests cannot describe it differently. */
+export declare function staleIssueReport(stale: readonly number[]): string;

package/dist/dev/stale-issue-guard.js

@@ -0,0 +1,75 @@
+/**
+ * An issue we have already fixed must not still read as available work.
+ *
+ * Three contributor PRs died on arrival in one week for this. #373 was filed at 09:52 and fixed by
+ * us at 12:33 the same day, then left open for three more days — somebody started on it on day two.
+ * #398 shipped and stayed open; a second contributor rebuilt it from scratch. `GITHUB.md` already
+ * documents the same failure costing three contributors before either of those, which makes this the
+ * third recurrence of a defect we have written down and asked ourselves to remember.
+ *
+ * Remembering is not a mechanism, and this is the smallest one that works: a commit saying it closes
+ * an issue is a claim that the issue is done. If that issue is still open and unlabelled afterwards,
+ * the tracker is lying to whoever reads it next — and the person it lies to is by definition someone
+ * looking for something to work on.
+ *
+ * ## Why `fixed-pending-release` is an accepted answer
+ *
+ * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
+ * ships. The label is what tells a contributor not to start, so the label — not the closure — is
+ * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
+ * when they close things, only to say so.
+ *
+ * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
+ * below testable without a network or a repo.
+ */
+/** The label that means "fixed, waiting for a release" — an honest reason to still be open. */
+export const PENDING_RELEASE_LABEL = 'fixed-pending-release';
+/**
+ * Issue numbers a commit message CLAIMS to have closed.
+ *
+ * Only the closing verbs GitHub itself acts on. A bare `#447`, a `Refs #447` or a `see #447` is how
+ * a change points at context it did not close — the exact habit we want to encourage — so counting
+ * those would make the guard cry wolf on good behaviour, and a check that cries wolf is one people
+ * learn to skip.
+ */
+const CLOSING_REF = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/gi;
+export function closedRefsIn(commitMessage) {
+    const seen = new Set();
+    for (const match of commitMessage.matchAll(CLOSING_REF)) {
+        const raw = match[1];
+        if (raw === undefined)
+            continue;
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed))
+            seen.add(parsed);
+    }
+    return [...seen];
+}
+/**
+ * Of the issues these commits claimed to close, the ones still reading as available work.
+ *
+ * An issue that could not be looked up is deliberately silent rather than failing. A rate limit, a
+ * transferred issue or a deleted one would otherwise turn this red for a reason unrelated to what it
+ * guards, and a guard that goes red for unrelated reasons gets disabled — which costs more than the
+ * defect it was catching.
+ */
+export function staleIssues(claimed, issues) {
+    const byNumber = new Map(issues.map((issue) => [issue.number, issue]));
+    return claimed.filter((number) => {
+        const issue = byNumber.get(number);
+        if (issue === undefined)
+            return false;
+        if ('closed' === issue.state)
+            return false;
+        return !issue.labels.includes(PENDING_RELEASE_LABEL);
+    });
+}
+/** The message the guard prints. Held here so the check and its tests cannot describe it differently. */
+export function staleIssueReport(stale) {
+    const list = stale.map((n) => `#${String(n)}`).join(', ');
+    return (`${list} ${1 === stale.length ? 'is' : 'are'} still OPEN, and a commit on this branch says it ` +
+        `closes ${1 === stale.length ? 'it' : 'them'}. Anyone browsing the tracker reads that as work ` +
+        `nobody has started. Close ${1 === stale.length ? 'it' : 'them'}, or label ` +
+        `${1 === stale.length ? 'it' : 'them'} \`${PENDING_RELEASE_LABEL}\` if the fix is waiting on a ` +
+        `release. This has cost three contributors an evening each; it is not bookkeeping.`);
+}

package/dist/domain/domain-tools.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { asNumber } from '../tools/tools-helpers.js';
+import { sessionRoot } from '../project/session-root.js';
+import { asNumber, asString } from '../tools/tools-helpers.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { readContract } from '../project/reticle-dir.js';
 import { buildDomainModel } from './domain-model.js';
@@ -74,7 +75,7 @@ export const DOMAIN_TOOLS = [
                 if (loaded.ok)
                     flows.push(loaded.value);
             }
-            const contract = await readContract(deps.fs, deps.reticleRoot);
+            const contract = await readContract(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
             const project = await deps.project.read();
             const runs = project.ok ? project.file.runs : [];
             const model = buildDomainModel(flows, contract.ok ? contract.capabilities : null, runs);

package/dist/events/predicate-asks.d.ts

@@ -0,0 +1,17 @@
+import type { Predicate } from './predicate-schema.js';
+/**
+ * Did the caller's predicate ask about registered state?
+ *
+ * Walks composites, because `allOf[{net}, {state}]` asks about state exactly as much as a bare
+ * `{state}` does — and the gap that reveals is the same one either way.
+ *
+ * Lives here rather than at a call site because both the act path and the assert path need it, and
+ * two walkers over one predicate tree is two chances to disagree about what counts as asking.
+ *
+ * NOT in `predicate-schema.ts` next to `predicateFieldsFor`, where it would otherwise belong: five
+ * open contributor PRs are queued on that file and on `predicate-eval.ts`, and a one-function import
+ * is not worth handing five people a conflict. Named `predicate-asks` rather than `predicate-shape`
+ * because `predicate-shape.test.ts` already exists and is about something else entirely — a file
+ * that reads as the subject of an unrelated test is a half-hour somebody loses later.
+ */
+export declare function declaresState(predicate: Predicate): boolean;

package/dist/events/predicate-asks.js

@@ -0,0 +1,26 @@
+import { PredicateKind } from '@reticlehq/core';
+/**
+ * Did the caller's predicate ask about registered state?
+ *
+ * Walks composites, because `allOf[{net}, {state}]` asks about state exactly as much as a bare
+ * `{state}` does — and the gap that reveals is the same one either way.
+ *
+ * Lives here rather than at a call site because both the act path and the assert path need it, and
+ * two walkers over one predicate tree is two chances to disagree about what counts as asking.
+ *
+ * NOT in `predicate-schema.ts` next to `predicateFieldsFor`, where it would otherwise belong: five
+ * open contributor PRs are queued on that file and on `predicate-eval.ts`, and a one-function import
+ * is not worth handing five people a conflict. Named `predicate-asks` rather than `predicate-shape`
+ * because `predicate-shape.test.ts` already exists and is about something else entirely — a file
+ * that reads as the subject of an unrelated test is a half-hour somebody loses later.
+ */
+export function declaresState(predicate) {
+    if (predicate.kind === PredicateKind.STATE)
+        return true;
+    if (predicate.kind === PredicateKind.ALL_OF || predicate.kind === PredicateKind.ANY_OF) {
+        return predicate.predicates.some(declaresState);
+    }
+    if (predicate.kind === PredicateKind.NOT)
+        return declaresState(predicate.predicate);
+    return false;
+}

package/dist/events/predicate-eval.js

@@ -160,8 +160,111 @@ function describeNetFilter(p) {
     const { kind: _kind, count: _count, since: _since, ...filter } = p;
     return JSON.stringify(filter);
 }
+/**
+ * URL suffixes only the DOCUMENT fetches, which the network observer therefore never records.
+ *
+ * `network.ts` patches `fetch` and `XMLHttpRequest` and nothing else, so `<link rel=icon>`,
+ * `<link rel=manifest>`, stylesheets, fonts and `<img src>` are invisible to it. "No matching call"
+ * and "that class of call is not observed" are then indistinguishable, and the miss graded
+ * `assertion_failed` — a false RED. Reported from the field: an assert over `/favicon.ico`,
+ * `/site.webmanifest` and `/apple-touch-icon.png` returned `verified:"no"` while curl showed all
+ * three answering 200. A false negative here is worse than an unknown, because an agent that trusts
+ * it goes and "fixes" working code.
+ *
+ * Deliberately NOT here: `.js` and `.json`. Both are routinely fetched via `fetch`/XHR — a module
+ * preload and an API call can share a suffix — so downgrading them would hide real misses. This list
+ * is only the suffixes for which the document is the sole plausible initiator.
+ *
+ * This began as the smaller half of #447: it did not make these requests observable, it stopped
+ * Reticle claiming they did not happen. The other half, observing them via resource timing, has
+ * since landed in the browser SDK, so the two halves are no longer independent and this downgrade is
+ * now GATED: when the event stream carries at least one document-initiated record, the observer is
+ * demonstrably live and a miss over these suffixes is real evidence, graded a plain failure. Only a
+ * page whose stream holds no resource entry at all keeps the honest "cannot tell apart" answer,
+ * because there the observer may simply not exist.
+ */
+const DOCUMENT_ONLY_SUFFIXES = [
+    '.ico',
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.svg',
+    '.webp',
+    '.avif',
+    '.bmp',
+    '.css',
+    '.woff',
+    '.woff2',
+    '.ttf',
+    '.otf',
+    '.eot',
+    '.webmanifest',
+];
+/**
+ * Does this filter target a class of request the observer cannot see?
+ *
+ * Read off `urlContains` only, and only when the pattern ENDS in one of the suffixes — a filter of
+ * `/api/` that happens to contain `.css` somewhere in a query string is still an ordinary XHR
+ * target. Query strings and fragments are stripped first, since `favicon.ico?v=2` is the same asset.
+ */
+function targetsUnobservedChannel(p) {
+    if (p.urlContains === undefined)
+        return false;
+    const path = (p.urlContains.split('#')[0] ?? '').split('?')[0]?.toLowerCase() ?? '';
+    return DOCUMENT_ONLY_SUFFIXES.some((suffix) => path.endsWith(suffix));
+}
+/**
+ * Initiator types the browser SDK's resource-timing observer stamps onto document-initiated records
+ * (packages/browser/src/observers/network.ts). The patched transports sign themselves `fetch`,
+ * `xhr` or `beacon`, so any NET_REQUEST carrying one of these came from a `resource` entry, and its
+ * mere presence is proof the PerformanceObserver is alive on this page. Mirrors the wire; keep in
+ * sync with the browser package.
+ */
+const DOCUMENT_INITIATORS = new Set([
+    'link',
+    'css',
+    'img',
+    'script',
+    'manifest',
+    'other',
+]);
+/**
+ * Did the observer actually report a document-initiated load?
+ *
+ * This is the gate on the unobserved-channel downgrade above. Once subresource observation landed,
+ * a miss over `.ico`/`.css`/`.woff2` is no longer inherently unknowable: if the observer is live it
+ * would have seen the favicon load, so seeing none is evidence it never fired. But the observer is
+ * opt-in-by-engine, not guaranteed: on a renderer without `PerformanceObserver` (or before any
+ * resource entry exists) nothing distinguishes "not requested" from "not visible", and the honest
+ * answer stays inconclusive. Liveness is inferred from the same events being judged: one
+ * document-initiated record anywhere in the window proves the channel works.
+ */
+function observerSawSubresources(events) {
+    return events.some((e) => {
+        if (e.type !== EventType.NET_REQUEST)
+            return false;
+        const initiator = str(e.data['initiator']);
+        return initiator !== undefined && DOCUMENT_INITIATORS.has(initiator);
+    });
+}
+/** The sentence both zero-match branches hand to `inconclusive`. */
+function unobservedChannelReason(p) {
+    return (`no call matched ${describeNetFilter(p)}, and no document-initiated load was recorded either, ` +
+        `so this page exposed no resource timing to read: Reticle observes fetch and XMLHttpRequest ` +
+        `directly, while a request the document initiates (<link rel=icon|manifest|preload>, a ` +
+        `stylesheet, a font, <img src>) leaves no record, and that state cannot be told apart from the ` +
+        `request having been made. ` +
+        `Nothing here says the app is wrong. Check it outside the browser, or assert something the ` +
+        `document does not fetch on its own`);
+}
 export function evalNet(events, p) {
     const since = p.since ?? 0;
+    /**
+     * Computed once: the gate every zero-match downgrade below reads. True means the resource-timing
+     * observer is demonstrably live in this window, so a miss is evidence rather than blindness.
+     */
+    const sawSubresources = observerSawSubresources(events);
     /**
      * Did any call match everything EXCEPT the body assertion, while carrying no recorded body?
      *
@@ -171,6 +274,8 @@ export function evalNet(events, p) {
      * because it is the same pass over the same events.
      */
     let matchedButUnrecorded = false;
+    /** A call matched url/method but carried NO readable status (document-initiated subresource). */
+    let unobservableStatus = false;
     /**
      * The response body of a call that matched everything EXCEPT the body assertion, and HAD one.
      *
@@ -190,8 +295,19 @@ export function evalNet(events, p) {
         if (p.urlContains !== undefined && !(str(d['url']) ?? '').includes(p.urlContains)) {
             return false;
         }
-        if (p.status !== undefined && num(d['status']) !== p.status)
-            return false;
+        if (p.status !== undefined) {
+            const status = num(d['status']);
+            if (status === undefined) {
+                // Document-initiated subresources (link/css/img/manifest via resource timing) carry no
+                // readable status on engines without responseStatus. A failed assertion here would read
+                // "your change is broken" and send the caller to fix working code — the exact false
+                // negative the oracle exists to prevent. Downgrade to unknown instead.
+                unobservableStatus = true;
+                return false;
+            }
+            if (status !== p.status)
+                return false;
+        }
         if (p.ok !== undefined && callSucceeded(d) !== p.ok)
             return false;
         if (p.bodyContains !== undefined) {
@@ -211,6 +327,18 @@ export function evalNet(events, p) {
         }
         return true;
     });
+    if (unobservableStatus && 0 === matches.length) {
+        // The url/method matched a document-initiated subresource whose engine could not read a status.
+        // "No matching call" would be a lie in both directions: it may have succeeded, it may have 404'd
+        // on exactly the path mistake the caller is hunting. Say the truth — not observable here.
+        return {
+            pass: false,
+            inconclusive: `a document-initiated request matching ${describeNetFilter(p)} was observed, but this engine does not expose its status code (resource timing without responseStatus) — assert on the element or route instead, or check the network tab`,
+            observed: 'a matching request with no readable status',
+            expected: `a status of ${String(p.status)} on ${JSON.stringify(p.urlContains ?? '*')}`,
+            assertion: 'net.unobservable-status',
+        };
+    }
     if (matchedButUnrecorded && 0 === matches.length) {
         return {
             pass: false,
@@ -237,19 +365,37 @@ export function evalNet(events, p) {
     if (p.count !== undefined) {
         return matches.length === p.count
             ? { pass: true, evidence: { matched: matches.length } }
-            : {
-                pass: false,
-                // Monotonic: more matches than asked for can never become exactly the number asked for.
-                // This is the double-submit — two writes 59ms apart — so the finding that matters most was
-                // also the one that took the caller's whole budget to report.
-                ...(matches.length > p.count ? { decided: true } : {}),
-                failureReason: `expected ${String(p.count)} network call(s) matching ${describeNetFilter(p)}, saw ${String(matches.length)}`,
-                observed: `${String(matches.length)} matching network call(s)`,
-                expected: `exactly ${String(p.count)} matching ${describeNetFilter(p)}`,
-                assertion: 'net.count',
-            };
+            : 0 === matches.length && targetsUnobservedChannel(p) && !sawSubresources
+                ? {
+                    pass: false,
+                    failureReason: unobservedChannelReason(p),
+                    inconclusive: unobservedChannelReason(p),
+                    assertion: 'net.count',
+                }
+                : {
+                    pass: false,
+                    // Monotonic: more matches than asked for can never become exactly the number asked for.
+                    // This is the double-submit — two writes 59ms apart — so the finding that matters most was
+                    // also the one that took the caller's whole budget to report.
+                    ...(matches.length > p.count ? { decided: true } : {}),
+                    failureReason: `expected ${String(p.count)} network call(s) matching ${describeNetFilter(p)}, saw ${String(matches.length)}`,
+                    observed: `${String(matches.length)} matching network call(s)`,
+                    expected: `exactly ${String(p.count)} matching ${describeNetFilter(p)}`,
+                    assertion: 'net.count',
+                };
     }
     const hit = matches[0];
+    if (hit === undefined && targetsUnobservedChannel(p) && !sawSubresources) {
+        const reason = unobservedChannelReason(p);
+        return {
+            pass: false,
+            failureReason: reason,
+            inconclusive: reason,
+            observed: describeObserved('calls', events.filter((e) => e.type === EventType.NET_REQUEST).map(describeCall)),
+            expected: `at least one call matching ${describeNetFilter(p)}`,
+            assertion: 'net.unobserved-channel',
+        };
+    }
     return hit !== undefined
         ? { pass: true, evidence: hit.data }
         : {
@@ -296,25 +442,66 @@ export function evalConsole(events, p) {
             return isErr;
         return e.type === CONSOLE_LEVEL_TYPE[p.level];
     });
+    // A text match narrows the population to entries whose captured message contains the substring.
+    // With `absent: true` this is the whole point: "THIS message did not appear", not "no messages
+    // appeared" — the difference between a regression check and a fragile one that any unrelated
+    // warning anywhere in the app breaks.
+    const wanted = 'contains' in p ? p.contains : undefined;
+    // Captured messages are strings (stringifyArgs in the browser observer), but a malformed or
+    // foreign event must not crash the evaluator: non-strings stringify defensively, and objects
+    // go through JSON.stringify rather than a default toString that would print '[object Object]'.
+    const asText = (v) => {
+        if ('string' === typeof v)
+            return v;
+        try {
+            return JSON.stringify(v) ?? '';
+        }
+        catch {
+            return '';
+        }
+    };
+    const matching = wanted !== undefined
+        ? matches.filter((e) => asText(e.data['message']).includes(wanted))
+        : matches;
     if (true === p.absent) {
-        return 0 === matches.length
+        if (wanted !== undefined && 0 === matching.length && matches.length > 0) {
+            // Other entries exist but none carries the substring: exactly the pass an absence-with-match
+            // asserts. Name both counts so the caller can tell this from a silent window.
+            return {
+                pass: true,
+                evidence: { absent: true, contains: wanted },
+            };
+        }
+        return 0 === matching.length
             ? { pass: true, evidence: { absent: true } }
             : {
                 pass: false,
-                failureReason: `expected no ${p.level ?? 'console'} entries but found ${String(matches.length)}`,
-                observed: `${String(matches.length)} ${p.level ?? 'console'} entr${1 === matches.length ? 'y' : 'ies'}`,
-                expected: `no ${p.level ?? 'console'} entries`,
-                assertion: 'console.absent',
-                evidence: matches.map((e) => e.data),
+                failureReason: wanted !== undefined
+                    ? `expected no ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)} but found ${String(matching.length)}`
+                    : `expected no ${p.level ?? 'console'} entries but found ${String(matches.length)}`,
+                observed: wanted !== undefined
+                    ? `${String(matching.length)} ${p.level ?? 'console'} entr${1 === matching.length ? 'y' : 'ies'} containing ${JSON.stringify(wanted)}`
+                    : `${String(matches.length)} ${p.level ?? 'console'} entr${1 === matches.length ? 'y' : 'ies'}`,
+                expected: wanted !== undefined
+                    ? `no ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)}`
+                    : `no ${p.level ?? 'console'} entries`,
+                assertion: wanted !== undefined ? 'console.absent-contains' : 'console.absent',
+                evidence: matching.map((e) => e.data),
             };
     }
-    return matches.length > 0
-        ? { pass: true, evidence: matches.map((e) => e.data) }
+    return matching.length > 0
+        ? { pass: true, evidence: matching.map((e) => e.data) }
         : {
             pass: false,
-            failureReason: `no ${p.level ?? 'console'} entries found`,
-            observed: `no ${p.level ?? 'console'} entries in the window`,
-            expected: `at least one ${p.level ?? 'console'} entry`,
+            failureReason: wanted !== undefined
+                ? `no ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)} found`
+                : `no ${p.level ?? 'console'} entries found`,
+            observed: wanted !== undefined
+                ? `no ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)} in the window`
+                : `no ${p.level ?? 'console'} entries in the window`,
+            expected: wanted !== undefined
+                ? `at least one ${p.level ?? 'console'} entry containing ${JSON.stringify(wanted)}`
+                : `at least one ${p.level ?? 'console'} entry`,
             assertion: 'console.present',
         };
 }

package/dist/events/predicate-parse.js

@@ -14,7 +14,7 @@
  */
 import { z } from 'zod';
 import { PredicateKind } from '@reticlehq/core';
-import { PredicateSchema, predicateFieldsFor } from './predicate-eval.js';
+import { PredicateSchema, predicateFieldsFor, predicateNestedFieldsFor } from './predicate-eval.js';
 /**
  * One valid call PER KIND, because an example of another kind answers a question nobody asked.
  *
@@ -90,7 +90,13 @@ export function parsePredicate(input) {
  */
 function accepted(kind) {
     const fields = predicateFieldsFor(kind);
-    if (0 < fields.length)
-        return `${kind} accepts: ${fields.join(', ')}.`;
+    if (0 < fields.length) {
+        // A field whose value is an object is the one an agent cannot guess from its name alone, so
+        // expand it in the same breath rather than making the shape a second round trip.
+        const nested = Object.entries(predicateNestedFieldsFor(kind))
+            .map(([field, keys]) => ` ${field} accepts: ${keys.join(', ')}.`)
+            .join('');
+        return `${kind} accepts: ${fields.join(', ')}.${nested}`;
+    }
     return `"${kind}" is not a predicate kind — use one of: ${Object.values(PredicateKind).join(', ')}.`;
 }

package/dist/events/predicate-schema.d.ts

@@ -38,6 +38,12 @@ export type Predicate = {
 } | {
     kind: typeof PredicateKind.CONSOLE;
     level?: string;
+    /**
+     * A substring the captured message must contain. With `absent: true` this flips the meaning
+     * from "no console entries at all" to "THIS message did not appear" — the assertion people
+     * actually write regression checks for (deprecation warnings, no-op handler notices).
+     */
+    contains?: string;
     absent?: boolean;
     since?: number;
 } | {
@@ -97,3 +103,15 @@ export declare const PredicateSchema: z.ZodType<Predicate>;
  * wall. Empty for a kind that is not in the union.
  */
 export declare function predicateFieldsFor(kind: string): readonly string[];
+/**
+ * One level into the fields that are themselves objects — `{ query: ['by', 'value', ...] }`.
+ *
+ * Naming the top-level fields alone leaves `element` unguessable: `query` is an object with its own
+ * required shape, and a plain CSS string works in `reticle_snapshot.scope` and `reticle_query.scope`,
+ * so assuming it works here is the natural guess. The rejection is the only place that inconsistency
+ * can be explained.
+ *
+ * One level only. Derived from the schema for the same reason `predicateFieldsFor` is: a stale field
+ * list is worse than none, because the agent trusts it and retries into the same wall.
+ */
+export declare function predicateNestedFieldsFor(kind: string): Readonly<Record<string, readonly string[]>>;