@reticlehq/server 2.5.0 → 2.6.0

package/dist/tools/invoke-tool.js

@@ -1,5 +1,5 @@
 import { healthEnvelope } from '../session/session-health.js';
-import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { TelemetryActor, TelemetryEventKind, TRANSPORT_LIMITS, } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { getTelemetry } from '../telemetry/telemetry.js';
 import { takeUpdateNudge } from '../update/update-nudge.js';
@@ -12,6 +12,7 @@ import { ReticleTool } from './tool-names.js';
 import { takeFeedbackPrompt } from './feedback-tools.js';
 import { takeFeedbackUndelivered } from '../telemetry/feedback-delivery.js';
 import { span } from '../trace.js';
+import { frictionOf, inviteFor } from './feedback-invite.js';
 /**
  * The live-session tools whose result MUST carry the
  * session-health envelope. Owned in ONE place — not retrofitted per handler — so a throttled tab
@@ -138,6 +139,27 @@ function reportBugsFound(toolName, result) {
  * object that did not already include `session` — splices the health envelope on. Idempotent
  * (handlers that already add health are left untouched) and never alters non-object results.
  */
+/**
+ * The name of the first argument whose string value exceeds the transport bound, if any.
+ *
+ * One level of nesting is searched because that is where callers put payloads — `reticle_act`'s
+ * `args.value`, and the fuzz's own `huge-string` shape. Deeper recursion would cost more than it
+ * buys: the failure is a single huge string, not a deeply nested structure of small ones.
+ */
+function firstOversizedArg(args) {
+    const tooLong = (value) => 'string' === typeof value && value.length > TRANSPORT_LIMITS.MAX_STRING_LENGTH;
+    for (const [key, value] of Object.entries(args)) {
+        if (tooLong(value))
+            return key;
+        if ('object' === typeof value && null !== value && !Array.isArray(value)) {
+            for (const [inner, nested] of Object.entries(value)) {
+                if (tooLong(nested))
+                    return `${key}.${inner}`;
+            }
+        }
+    }
+    return undefined;
+}
 export async function runTool(tool, deps, args) {
     // Both dispatch paths (MCP + programmatic) pass through here — the one place "which tool is mostly
     // used" can be counted. This used to EMIT an event per call; it now increments an in-process counter
@@ -150,6 +172,28 @@ export async function runTool(tool, deps, args) {
     // closure carries this call's own identity, which is also what makes peak-concurrency measurable.
     // A daemon that has served even one tool call is doing a job for somebody; see daemon-usefulness.
     noteToolCall();
+    // An oversized argument is refused BEFORE the handler deserialises it.
+    //
+    // tool-fuzz failed CI on the invariant that matters most — `every tool answers every hostile call`
+    // — for a ~100KB string. Seen twice with different tools; the earlier one came back
+    // `-32001 sse_aborted` with the tool surface dropping 48→17, which is a RESTARTED daemon. The
+    // shape is: oversized argument → the daemon dies → the proxy answers the in-flight call with
+    // transport loss, and the next assertion is talking to a different daemon.
+    //
+    // `TRANSPORT_LIMITS.MAX_STRING_LENGTH` already bounds what crosses the bridge; a tool argument
+    // arrives over MCP stdio and never met it. Here, because this is the one place every invocation
+    // routes through, so a tool added later inherits the bound instead of having to remember it.
+    //
+    // A refusal is a normal answer. An UNANSWERED call is a hung agent, and that is the failure this
+    // prevents: the agent learns its argument was too big, which is something it can fix.
+    const oversized = firstOversizedArg(args);
+    if (oversized !== undefined) {
+        return {
+            error: `argument '${oversized}' is larger than ${String(TRANSPORT_LIMITS.MAX_STRING_LENGTH)} ` +
+                'characters, which is the most Reticle moves in one call. Nothing ran. Send a smaller ' +
+                'value — a selector or an id rather than a document, or a slice of the text you need.',
+        };
+    }
     // An ACTION is what gets abandoned. Counted here, against verifications, so "the agent drove the
     // page and then wandered off" becomes a number instead of an impression.
     if (ACTION_TOOLS.has(tool.name))
@@ -246,5 +290,29 @@ export async function runTool(tool, deps, args) {
     const warning = resolved.ageWarning();
     if (warning !== undefined)
         envelope['session_age_warning'] = warning;
+    // Ask for a verdict when the agent has driven the page and not asked for one. 137 of the 140
+    // verdict-less sessions measured over 2026-08-10/11 never called a verdict-producing tool ONCE;
+    // the counter behind this already existed and was reported only to us. One-shot per abandoned
+    // run, same discipline as the pool lease — a hint on every call is noise that gets tuned out.
+    const unverified = getSessionMetrics().takeUnverifiedNudge();
+    if (unverified !== undefined)
+        envelope['verify_next'] = unverified;
+    // Invite feedback at the moment of friction, worded for what just happened. Feedback produced
+    // ~11 of this release's fixes from 14 reports; the handshake instruction is what got those 14,
+    // and this closes the gap it leaves — the agent mid-problem, not thinking about feedback tooling.
+    // Counted so `feedback_submitted / feedbackPrompted` can tell us whether it works at all.
+    const friction = frictionOf({
+        unknownTool: false,
+        verifiedUnknown: 'unknown' === result.verified,
+        repeatRun: getSessionMetrics().currentRun,
+        errored: 'error' in result,
+        // A verdict is progress. Without this, three successful act_and_wait calls in a row — the exact
+        // loop this release exists to encourage — get told they are stuck.
+        producedVerdict: 'verified' in result,
+    });
+    if (friction !== undefined) {
+        envelope['feedback_invite'] = inviteFor(friction);
+        getSessionMetrics().recordFeedbackPrompt();
+    }
     return Object.keys(envelope).length > 0 ? { ...result, ...envelope } : result;
 }

package/dist/tools/navigate-arrival.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Wait, briefly, for the SDK to reconnect after a navigation — so `confirmed` can mean something.
+ *
+ * `window.location.assign(url)` destroys the SDK that would report on the new document, so the
+ * navigation itself cannot be confirmed from inside the page. But the SDK reconnects TO THE DAEMON,
+ * which makes the daemon the only party that can see arrival happen. Before this, it did not look,
+ * and told the agent to poll `reticle_sessions` instead — a tool call on every navigation, on the
+ * least reliable tool we ship.
+ *
+ * Bounded and best-effort by construction: a navigation to a page that is not instrumented, or not
+ * there at all, must still return promptly with `confirmed:false` rather than hanging. The clock and
+ * the sleep are injected so this is testable without waiting on a real one.
+ */
+import type { SessionManager } from '../session/session-manager.js';
+import type { NavigateArrival } from './navigate-result.js';
+/** Long enough for a dev server to serve a page and the SDK to dial back; short enough to not hang. */
+export declare const ARRIVAL_TIMEOUT_MS = 5000;
+export interface ArrivalClock {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+/**
+ * Poll until a session is present at `target`, or the budget runs out. Returns `null` on timeout —
+ * never throws, because a failure to confirm is a legitimate answer, not an error.
+ */
+export declare function awaitArrival(sessions: SessionManager, target: string, timeoutMs?: number, clock?: ArrivalClock): Promise<NavigateArrival | null>;

package/dist/tools/navigate-arrival.js

@@ -0,0 +1,60 @@
+/**
+ * Wait, briefly, for the SDK to reconnect after a navigation — so `confirmed` can mean something.
+ *
+ * `window.location.assign(url)` destroys the SDK that would report on the new document, so the
+ * navigation itself cannot be confirmed from inside the page. But the SDK reconnects TO THE DAEMON,
+ * which makes the daemon the only party that can see arrival happen. Before this, it did not look,
+ * and told the agent to poll `reticle_sessions` instead — a tool call on every navigation, on the
+ * least reliable tool we ship.
+ *
+ * Bounded and best-effort by construction: a navigation to a page that is not instrumented, or not
+ * there at all, must still return promptly with `confirmed:false` rather than hanging. The clock and
+ * the sleep are injected so this is testable without waiting on a real one.
+ */
+/** Long enough for a dev server to serve a page and the SDK to dial back; short enough to not hang. */
+export const ARRIVAL_TIMEOUT_MS = 5_000;
+const POLL_MS = 100;
+/**
+ * Compare only origin + pathname.
+ *
+ * The app is entitled to add or rewrite the query and hash on arrival — a redirect to
+ * `?redirect=%2F`, a router normalising a trailing slash, an auth guard appending a reason. Matching
+ * the whole URL string would report `confirmed:false` for a navigation that plainly succeeded, which
+ * is the same lie in the opposite direction.
+ */
+function samePage(a, b) {
+    try {
+        const x = new URL(a);
+        const y = new URL(b);
+        return x.origin === y.origin && x.pathname.replace(/\/$/, '') === y.pathname.replace(/\/$/, '');
+    }
+    catch {
+        return false;
+    }
+}
+function findArrival(sessions, target) {
+    for (const s of sessions.all()) {
+        if (samePage(s.url, target))
+            return { sessionId: s.id };
+    }
+    return null;
+}
+const REAL_CLOCK = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+/**
+ * Poll until a session is present at `target`, or the budget runs out. Returns `null` on timeout —
+ * never throws, because a failure to confirm is a legitimate answer, not an error.
+ */
+export async function awaitArrival(sessions, target, timeoutMs = ARRIVAL_TIMEOUT_MS, clock = REAL_CLOCK) {
+    const deadline = clock.now() + timeoutMs;
+    for (;;) {
+        const found = findArrival(sessions, target);
+        if (found !== null)
+            return found;
+        if (clock.now() >= deadline)
+            return null;
+        await clock.sleep(POLL_MS);
+    }
+}

package/dist/tools/navigate-result.d.ts

@@ -10,8 +10,22 @@
  * `reticle_act` already draws this line — `dispatched` (sent) versus `settled` (a frame flushed).
  * This gives navigate the same honesty without changing what it does.
  */
+/** The session the SDK reconnected as after the page moved, when one was observed in the window. */
+export interface NavigateArrival {
+    sessionId: string;
+}
 export declare function navigateResult(result: {
     ok?: unknown;
     url?: unknown;
     reason?: unknown;
-}): Record<string, unknown>;
+}, 
+/**
+ * Arrival, if the daemon saw the SDK come back. `null` keeps the original honest envelope.
+ *
+ * Measured on three fixtures: `confirmed` was `false` on every navigation on every app, because
+ * nothing ever set it. A boolean that never varies teaches an agent nothing, and an agent that
+ * learns to ignore it will keep ignoring it when it starts meaning something. The daemon is the
+ * one place that CAN answer this — the SDK reconnects to it — so making it answer removes a
+ * `reticle_sessions` poll from every single navigation.
+ */
+arrival?: NavigateArrival | null): Record<string, unknown>;

package/dist/tools/navigate-result.js

@@ -1,16 +1,14 @@
+export function navigateResult(result, 
 /**
- * The honest envelope for a navigation nobody can confirm.
+ * Arrival, if the daemon saw the SDK come back. `null` keeps the original honest envelope.
  *
- * `window.location.assign(url)` returns before the page moves, and the SDK that would report on the
- * new document is destroyed by the navigation itself. So a successful NAVIGATE means the browser
- * accepted the instruction — not that anything arrived. Driven against a dead URL it returned
- * `{"ok":true}` while the session died, which is the worst combination available: the agent believes
- * it navigated, is looking at nothing, and has lost Reticle.
- *
- * `reticle_act` already draws this line — `dispatched` (sent) versus `settled` (a frame flushed).
- * This gives navigate the same honesty without changing what it does.
+ * Measured on three fixtures: `confirmed` was `false` on every navigation on every app, because
+ * nothing ever set it. A boolean that never varies teaches an agent nothing, and an agent that
+ * learns to ignore it will keep ignoring it when it starts meaning something. The daemon is the
+ * one place that CAN answer this — the SDK reconnects to it — so making it answer removes a
+ * `reticle_sessions` poll from every single navigation.
  */
-export function navigateResult(result) {
+arrival = null) {
     const ok = true === result.ok;
     const base = {
         ok,
@@ -20,6 +18,15 @@ export function navigateResult(result) {
     // A refusal is conclusive: the page never moved, so there is nothing unconfirmed to report.
     if (!ok)
         return base;
+    if (arrival !== null) {
+        return {
+            ...base,
+            confirmed: true,
+            // The SDK that reconnects after a navigation is a NEW session with a new id. Returning it here
+            // is the difference between a confirmation and a confirmation the agent can act on.
+            sessionId: arrival.sessionId,
+        };
+    }
     return {
         ...base,
         confirmed: false,

package/dist/tools/observe-tools.js

@@ -10,6 +10,7 @@ import { ReticleTool } from './tool-names.js';
 import { buildReactionReport } from '../events/reaction.js';
 import { findContradictions } from '../events/contradictions.js';
 import { evaluatePredicate, waitForPredicate, PredicateSchema } from '../events/predicate.js';
+import { parsePredicate } from '../events/predicate-parse.js';
 import { matchNet, matchConsole, isConsoleEvent, eventMatchesFilters, netEmptyHint, consoleEmptyHint, reconcileNet, projectNetCall, projectConsoleLog, } from '../events/event-filters.js';
 import { applyEventBudget, costHint, withSizeCost, DEFAULT_QUERY_LIMIT, } from '../session/output-budget.js';
 import { healthEnvelope, bufferEnvelope } from '../session/session-health.js';
@@ -209,6 +210,10 @@ export const OBSERVE_TOOLS = [
             pass: z.boolean(),
             evidence: z.unknown().optional(),
             failureReason: z.string().optional(),
+            observationLost: z
+                .boolean()
+                .optional()
+                .describe('The tab disconnected mid-wait, so this was never observed — the verdict is UNKNOWN, not a failure of the app.'),
             session: z
                 .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })
                 .optional(),
@@ -233,7 +238,7 @@ export const OBSERVE_TOOLS = [
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
             // `until` is act_and_wait's name for this — see alias-args.ts.
-            const predicate = PredicateSchema.parse(aliasParam(args, 'predicate', ['until'])['predicate']);
+            const predicate = parsePredicate(aliasParam(args, 'predicate', ['until'])['predicate']);
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
             const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
             const verdict = await waitForPredicate(session, predicate, asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS, since);
@@ -252,7 +257,16 @@ export const OBSERVE_TOOLS = [
         example: { predicate: { kind: PredicateKind.SIGNAL, name: 'todos:loaded' } },
         description: 'Evaluate a predicate (optionally waiting up to timeout_ms). Returns { pass, evidence, failureReason? }. The end of every verify loop. Prefer a { signal } or { net } consequence over { element }/{ text } presence — a passing presence-only assertion returns `advice` because a wrong/healed element can fake it. By default it only counts events since your last act, so a stale buffered signal can never fake a pass; pass `since` (an observe/act cursor) to set the window explicitly.',
         inputSchema: {
-            predicate: PredicateSchema.optional().describe('Predicate to evaluate: { signal }, { net }, { element } or a combination.'),
+            predicate: PredicateSchema.optional().describe(
+            // Every kind, each with the field that carries its argument. Five of the nine were
+            // undocumented here, including `route` — and "did submitting the login form navigate away"
+            // is the most common thing an agent wants to assert. A field report reached us from an agent
+            // that guessed `urlContains` on route (net's spelling) and got unrecognized_keys.
+            'Predicate to evaluate. Kinds: { signal, name } { net, urlContains|method|status|count } ' +
+                '{ state, path|equals } { route, pathname (exact) | contains (path+query+hash) } ' +
+                '{ element, testid|role|text } { text } { console, level|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)."),
             timeout_ms: z
                 .number()
@@ -268,6 +282,10 @@ export const OBSERVE_TOOLS = [
             pass: z.boolean(),
             evidence: z.unknown().optional(),
             failureReason: z.string().optional(),
+            observationLost: z
+                .boolean()
+                .optional()
+                .describe('The tab disconnected mid-wait, so this was never observed — the verdict is UNKNOWN, not a failure of the app.'),
             advice: z
                 .string()
                 .optional()
@@ -304,7 +322,7 @@ export const OBSERVE_TOOLS = [
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
             // `until` is act_and_wait's name for this — see alias-args.ts.
-            const predicate = PredicateSchema.parse(aliasParam(args, 'predicate', ['until'])['predicate']);
+            const predicate = parsePredicate(aliasParam(args, 'predicate', ['until'])['predicate']);
             const timeout = asNumber(args['timeout_ms']) ?? 0;
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
             const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
@@ -323,7 +341,7 @@ export const OBSERVE_TOOLS = [
                     : assertsDerivedIpcStatus(predicate)
                         ? { advice: DERIVED_IPC_STATUS_ADVICE }
                         : {};
-            const { decision, contradictions, coverage } = await assertVerdict(session, predicate, verdict.pass, since, verdict.inconclusive);
+            const { decision, contradictions, coverage } = await assertVerdict(session, predicate, verdict.pass, since, verdict.inconclusive, verdict.observationLost);
             return withControl(session, {
                 ...decision,
                 ...verdict,

package/dist/tools/real-input-attempt.js

@@ -27,17 +27,22 @@ function synthetic(reason) {
  */
 export async function tryRealInput(deps, session, ref, action, args) {
     const provider = deps.realInput;
-    if (provider === undefined)
-        return synthetic(); // real input not configured — no diagnostic
+    const inner = asRecord(args['args']);
+    const askedForNative = true === inner[NATIVE_INPUT_ARG];
+    if (provider === undefined) {
+        // Silent by default: with no provider EVERY action is synthetic, and a reason on all of them is
+        // noise on the most-used tool in the product. But an agent that passed native:true asked a
+        // question and got the opposite answer — reported from the field as a silent downgrade that cost
+        // real debugging time, because the tool description promises a reason is "never silent".
+        return askedForNative ? synthetic(InputModeReason.NOT_CONFIGURED) : synthetic();
+    }
     if (!isPointerAction(action))
         return synthetic(InputModeReason.NOT_POINTER); // fill/type stay synthetic
-    const inner = asRecord(args['args']);
     // "Don't click, run the code": a click/dblclick runs the occlusion-honest SYNTHETIC path by default
     // even with a provider configured — no coordinate gesture to be intercepted by the HUD or missed
     // off-screen. Opt into a trusted native click with args.native:true (file pickers, clipboard,
     // isTrusted-gated handlers). hover/drag genuinely need native pointer state, so they stay real.
-    if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) &&
-        inner[NATIVE_INPUT_ARG] !== true) {
+    if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) && !askedForNative) {
         return synthetic(InputModeReason.SYNTHETIC_CLICK_PREFERRED);
     }
     if (!(await provider.isAvailableFor(session.url)))

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

@@ -33,6 +33,14 @@ export interface ToolDeps {
     fs: FileSystemPort;
     /** absolute.reticle path (index.ts computes cwd/.reticle). */
     reticleRoot: string;
+    /**
+     * This daemon's OWN project id, derived from the directory it was started in.
+     *
+     * Optional because a daemon above an uninitialised directory has none, and because every existing
+     * test construction of ToolDeps predates it. Absence means "cannot tell", which must never be
+     * treated as a mismatch.
+     */
+    projectId?: string;
     /** injected clock for the contract's generatedAt stamp. */
     now: () => number;
     /**

package/dist/tools/tool-surface.js

@@ -98,6 +98,19 @@ export const CORE_TOOL_NAMES = new Set([
     ReticleTool.QUERY,
     ReticleTool.ACT,
     ReticleTool.ACT_AND_WAIT,
+    // ACT_SEQUENCE is here because its absence was measurably CAUSING the biggest loop in the data.
+    //
+    // Measured 2026-08-10/11 (non-CI): `reticle_act` 319 calls, `reticle_act_sequence` **7**. `act`
+    // also leads the repeat table at 110 consecutive-repeat runs, and inside those sessions the
+    // repeated calls are 98 clicks and 21 fills — a login form driven one round trip at a time, which
+    // is exactly the antipattern SKILL.md warns about and exactly what this tool exists to collapse.
+    //
+    // The repeats are NOT retries: looping sessions have a lower error rate (0.051) than non-looping
+    // ones (0.078). The calls succeed and get repeated, because the batching tool was reachable only
+    // through `reticle_run` — so an agent had to already know it existed to use it, and 7-vs-319 says
+    // essentially nobody did. A tool an agent must already know about is a tool that never gets
+    // called; the same argument that put INSPECT and FEEDBACK here.
+    ReticleTool.ACT_SEQUENCE,
     ReticleTool.OBSERVE,
     ReticleTool.NETWORK,
     ReticleTool.CONSOLE,

package/docs/README.md

@@ -0,0 +1,55 @@
+# Docs index
+
+Two audiences share this directory, which is why it looked like twenty-five unsorted files. Every page states its own audience in the first blockquote; this index is the shortcut.
+
+**User docs are published** to [reticle.sh](https://reticle.sh) via `mint.json`. **Contributor docs are not** — they are for people working _on_ Reticle, and they live here because they belong next to what they describe.
+
+---
+
+## For people using Reticle
+
+**Start:** [getting-started.md](getting-started.md) → [usage.md](usage.md) (the full tool reference).
+
+| Page | What it answers |
+| --- | --- |
+| [getting-started.md](getting-started.md) | install it, connect an agent, verify something |
+| [usage.md](usage.md) | every tool, every argument — the reference |
+| [agent-cheatsheet.md](agent-cheatsheet.md) | the condensed version an agent keeps in context |
+| [architecture.md](architecture.md) | how it works, and why it is built this way |
+| [platform-integration.md](platform-integration.md) | Vite, Next, Remix, Astro, plain HTML |
+| [desktop-apps.md](desktop-apps.md) | Electron and Tauri |
+| [integration-patterns.md](integration-patterns.md) | wiring it into a real codebase |
+| [flows.md](flows.md) | record → save → replay → heal |
+| [testing.md](testing.md) | `@reticlehq/test` — turning a session into a CI suite |
+| [multi-agent-testing.md](multi-agent-testing.md) | more than one agent on one app |
+| [human-control.md](human-control.md) | taking the wheel back from the agent |
+| [deploy-checks.md](deploy-checks.md) | running Reticle against a deployed build |
+| [token-efficiency.md](token-efficiency.md) | why it costs less than a screenshot loop |
+| [benchmarks.md](benchmarks.md) | how the numbers were measured, including where Reticle loses |
+| [telemetry.md](telemetry.md) | what is collected, and how to turn it off |
+| [local-registry.md](local-registry.md) | installing an unpublished build |
+| [enterprise.md](enterprise.md) | the licensed surface |
+
+## For people working on Reticle
+
+**Start:** [`CONTRIBUTING.md`](../CONTRIBUTING.md) → [gates.md](gates.md).
+
+| Page | What it answers |
+| --- | --- |
+| [gates.md](gates.md) | **I changed some files — which gate do I run?** |
+| [gate-plan.md](gate-plan.md) | why the gates are shaped this way, and what is still unbuilt |
+| [system-map.md](system-map.md) | how a tool call reaches the app, and which failures are silent |
+| [telemetry-contract.md](telemetry-contract.md) | required reading before touching anything that emits |
+| [debugging.md](debugging.md) | debugging Reticle itself — the four signals and what each answers |
+| [fixtures.md](fixtures.md) | the sibling `reticle-fixtures` repo: install complexity, not regressions |
+| [matrix/README.md](matrix/README.md) | submitting an MCP-client compatibility record — the best first contribution |
+| [matrix/MATRIX.md](matrix/MATRIX.md) | which clients are known to work (generated; do not hand-edit) |
+| [`../apps/README.md`](../apps/README.md) | what belongs in `apps/`, and what does not |
+| [`../apps/e2e/harness-rules.md`](../apps/e2e/harness-rules.md) | the four rules every gate obeys, and the incident behind each |
+| [`../bench/README.md`](../bench/README.md) | what in `bench/` is live and what is a kept one-off study |
+
+`fixtures-dispatch-receiver.yml` is not a doc — it is the workflow template `reticle-fixtures` needs, kept in this repo so the two ends of the contract cannot drift apart.
+
+---
+
+**Adding a page?** Put it in the right table above. If it is user-facing, add it to `mint.json` too — a page that is published but unlisted is a page nobody finds, and a page listed here but absent from `mint.json` is one users cannot reach at all.

package/docs/agent-cheatsheet.md

@@ -7,7 +7,7 @@ One screen to get fluent. Reticle is the **proof layer for AI agents** — no sc
 | Verb | Tool | One-liner |
 | --- | --- | --- |
 | **look** | `reticle_snapshot` / `reticle_query` | See the page (semantic tree) / find one specific element. |
-| **act** | `reticle_act` / `reticle_act_and_wait` | Click/fill a `ref` / act + wait for a predicate in one hop. |
+| **act** | `reticle_act` / `reticle_act_sequence` / `reticle_act_and_wait` | Click/fill a `ref` / **batch a whole journey in one hop** / act + wait for a predicate in one hop. |
 | **observe** | `reticle_observe` / `reticle_wait_for` | Everything the app did after `since` / block until true. |
 | **assert** | `reticle_assert` | Evaluate a predicate → `{ pass, evidence, failureReason? }`. The end of every loop. |
 
@@ -50,7 +50,7 @@ A claim is real only when the layers agree. Check more than the UI:
 
 The tools advertised DIRECTLY — what you'll use 90% of the time. Everything else is one `reticle_run` away (see Token note below).
 
-`reticle_sessions` · `reticle_navigate` · `reticle_snapshot` · `reticle_query` · `reticle_act` · `reticle_act_and_wait` · `reticle_observe` · `reticle_network` · `reticle_console` · `reticle_wait_for` · `reticle_assert` · `reticle_state` · `reticle_inspect` (DOM node → `src/App.tsx:104`) · `reticle_feedback` (tell the maintainers what is missing) · `reticle_session` (hand back: `{action:"yield"}` the moment you stop driving, `{action:"resume"}` after a human pause).
+`reticle_sessions` · `reticle_navigate` · `reticle_snapshot` · `reticle_query` · `reticle_act` · `reticle_act_sequence` · `reticle_act_and_wait` · `reticle_observe` · `reticle_network` · `reticle_console` · `reticle_wait_for` · `reticle_assert` · `reticle_state` · `reticle_inspect` (DOM node → `src/App.tsx:104`) · `reticle_feedback` (tell the maintainers what is missing) · `reticle_session` (hand back: `{action:"yield"}` the moment you stop driving, `{action:"resume"}` after a human pause).
 
 Frequently useful but NOT core, so reach them through `reticle_run({ tool, args })`: `reticle_domain` (learn the app + gaps), `reticle_capabilities` (the app's declared testable surface), `reticle_baseline {action:"diff"}`, `reticle_project` (run history).
 

package/docs/benchmarks.md

@@ -2,7 +2,7 @@
 
 > This page assumes **zero** testing background. By the end you'll understand what software testing is, why AI coding agents made it urgent, how to tell a good verification tool from a bad one, and exactly how Reticle measures up against the main alternatives — including the places Reticle loses. If a term looks like jargon, it's defined the first time it appears.
 >
-> _The headline charts below are rendered from the measured numbers (`assets/readme/`, rendered from the measured `history.jsonl` via `assets/benchmarks/render.mjs`); supporting diagrams live in `bench/artifacts/`._
+> _Where the pictures come from, stated accurately: the **SVG charts** (`bench/artifacts/`) are generated from measured raws by `bench/harness/charts.mjs`. The **headline PNG cards** (`assets/readme/`) are screenshots of hand-authored HTML in `assets/benchmarks/src/`, rendered by `assets/benchmarks/render.mjs` — their figures are typed in by a human and are **not** read from `history.jsonl`, which this line previously claimed. Treat a card as a design asset that has to be updated by hand when a number moves, and `bench/SCORECARD.md` (plus its freshness banner) as the source of truth._
 
 ---
 

package/docs/fixtures-dispatch-receiver.yml

@@ -0,0 +1,76 @@
+# Copy this into `reticle-fixtures` as `.github/workflows/verify-on-dispatch.yml`.
+#
+# It is kept HERE, in the repo that sends the dispatch, on purpose: the two halves have to agree on
+# an event name and a payload shape, and a contract whose two ends live in different repositories
+# drifts the first time somebody edits one of them. This file is the sending end's statement of what
+# the receiving end must look like.
+#
+# It has never run. Nothing in this repository can verify it — the dispatch needs a token that does
+# not exist yet, and the receiver needs to be committed to another repository. Treat every line as
+# unverified until somebody has watched one green run, and do not let its presence here be mistaken
+# for Tier 2 being live.
+name: Verify a Reticle commit against the fixtures
+
+on:
+  repository_dispatch:
+    types: [reticle-commit]
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: Reticle commit to verify
+        required: true
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    # Nine real apps, each installed and booted. This is why Tier 2 cannot block a merge.
+    timeout-minutes: 90
+    steps:
+      - name: Check out the fixtures (the pristine surface)
+        uses: actions/checkout@v4
+        with:
+          # `clean` is the branch that has NEVER been instrumented. Running init over an already
+          # wired app reports "already wired" for every step and proves nothing, which is exactly how
+          # an install regression ships unnoticed.
+          ref: clean
+
+      - name: Check out the Reticle commit under test
+        uses: actions/checkout@v4
+        with:
+          repository: reticlehq/reticle
+          ref: ${{ github.event.client_payload.sha || inputs.sha }}
+          path: reticle
+
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Build the release candidate
+        working-directory: reticle
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm build
+
+      - run: npx playwright install --with-deps chromium
+
+      - name: Materialise the fixture apps
+        run: node scripts/materialise.mjs
+
+      - name: Install into every fixture and open each one in a browser
+        # `--local` is the whole point: without it the gate can only confirm what already shipped,
+        # which is the wrong half of the question before a release.
+        run: node scripts/verify.mjs --local ./reticle
+        env:
+          # The fixtures gate's own idle shutdown once fired mid-install and scored three fixtures as
+          # install failures. A gate owns its daemon for the whole run — see the reticle repo's
+          # apps/e2e/harness-rules.md, rule 2.
+          RETICLE_IDLE_SHUTDOWN_MS: '0'
+
+      - name: Upload the run
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: fixtures-run
+          path: runs/
+          if-no-files-found: ignore

package/docs/fixtures.md

@@ -26,3 +26,20 @@ The last step is the one that earns its keep. Every install bug found so far has
 `apps/` — bench-app, next-smoke, the Remix and Astro examples, the Electron and Tauri smoke apps, atlas, and the API. These are the CI gates (`pnpm test:e2e`, `pnpm test:e2e:desktop`), and `integration-coverage.test.ts` fails if one of them goes missing while `SKILL.md` still offers its framework.
 
 The split is: **`apps/` proves the tools work. `reticle-fixtures` proves the install works.**
+
+## Wiring Tier 2 (not yet live)
+
+CI can ask this repo to verify a Reticle commit automatically — the [`vite-ecosystem-ci`](https://github.com/vitejs/vite-ecosystem-ci) shape, where a separate repo holds the downstream apps and the main repo asks it to run. The sending half is built (`fixtures-dispatch` in `.github/workflows/ci.yml`); the receiving half is a template at [`docs/fixtures-dispatch-receiver.yml`](./fixtures-dispatch-receiver.yml).
+
+**It is inert until two things happen, and neither can be done from inside this repository:**
+
+1. A fine-grained PAT with **Actions: write** on `reticlehq/reticle-fixtures`, added to `reticlehq/reticle` as the secret `FIXTURES_DISPATCH_TOKEN`. Until it exists the job logs that Tier 2 is unwired and exits 0 — it never reddens CI, because a dispatch failure has nothing to do with the change being pushed.
+2. The template copied into `reticle-fixtures` as `.github/workflows/verify-on-dispatch.yml`.
+
+The template lives in the _sending_ repo deliberately: the two halves must agree on an event name and payload shape, and a contract whose ends live in different repositories drifts the first time somebody edits one of them.
+
+**Nothing here has ever run.** Treat every line as unverified until somebody has watched one green run. Tier 2 being present in the plan is not Tier 2 being live.
+
+### Why Tier 2 exists when Tier 1 already passes
+
+`pnpm gate:install` (Tier 1) scaffolds pristine apps and catches install **regressions**. It cannot catch install **complexity**: `rowy` is 70 dependencies of somebody else's product, `phanpy` has a 130-line vite config holding ten plugins inside a `defineConfig` callback. That is where install bugs actually hide, and a scaffold deliberately has none of it. The two tiers answer different questions and neither substitutes for the other.