@reticlehq/server 2.10.0 → 2.12.0

package/dist/init/slash-command.d.ts

@@ -24,4 +24,4 @@ export declare const CURSOR_COMMAND_PATH = ".cursor/commands/reticle.md";
  * are told apart.
  */
 export declare const SLASH_COMMAND_SIGNATURE = "description: Verify this app in the browser with Reticle";
-export declare const SLASH_COMMAND_BODY = "---\ndescription: Verify this app in the browser with Reticle \u2014 drive one real flow and report what happened.\n---\n\nVerify this running app with Reticle. Drive it; do not read the code and guess.\n\n## Step 0 \u2014 is anything connected?\n\nCall `reticle_sessions` first.\n\n**A session is listed?** Go to \"Pick ONE flow\".\n\n**No session?** Setup is not finished, and stopping to ask the user to run something is not an\nanswer. Work these in order, and say which one you are on:\n\n0. **Is anything serving the app at all?** If a dev server is already listening, use it and go to\n   step 1 \u2014 the cause is then almost always that the SDK never loaded in the page, not a missing\n   server, so do not tell the user to start one they are already running. If nothing is listening:\n\n**If no dev server is listening, start one yourself.** Read the project's own dev script out of `package.json` (`dev`, `start`, whatever this project calls it), run it in the BACKGROUND, tell the user in one line that it is running and how to stop it, then carry on. Stopping to ask is how a verification turn ends with nothing verified.\n\nFive guards, none optional:\n\n1. **Never start a second one.** If something is already listening on the app's port, use it.\n2. **Never guess the command.** It comes from `package.json` scripts. If there is no recognisable dev script, say so and stop rather than inventing one.\n3. **Never kill anything.** Not a dev server, not a daemon, not a port holder \u2014 including one you started.\n4. **Background it, and say so.** The user must know a server is running and how to stop it. A dev server the human does not know about is the same failure one step later.\n5. **The permission prompt belongs to your host.** Never try to bypass, suppress or auto-approve it, and take a refusal as the answer.\n\nThen, once something is serving the app:\n\n1. **Is the SDK actually in the app?** Read the app's entry file (`src/main.tsx`, `app/layout.tsx`,\n   `src/app.vue`, whatever this project uses). You are looking for an `import` from\n   `@reticlehq/react` or `@reticlehq/browser` and a `connect()` call, or the Reticle plugin in\n   `vite.config.*`, or `withReticle` in `next.config.*`. **If it is not there, that is the bug.**\n   Wire it in \u2014 see the framework snippets at https://docs.reticle.sh/instrumentation \u2014 then restart\n   the dev server and re-check.\n2. **Is the connect guarded on `hostname === 'localhost'`?** If so, remove that guard. It is false on\n   any non-localhost dev host, and `window` does not exist during SSR, so the guard silently prevents\n   the connect and logs nothing. Use the framework's dev flag instead (`import.meta.env.DEV`,\n   `process.env.NODE_ENV !== 'production'`, `import.meta.dev`).\n3. **Is the dev server serving that entry?** Ask the user to open the app in a browser and check its\n   console for a line starting `[Reticle]`. That line, or its absence, tells you which side is at\n   fault. Reticle itself never starts a dev server \u2014 starting it is your job, under the guards above.\n4. **Do both sides agree on the port?** Run `npx @reticlehq/server doctor` and compare the daemon\n   port against the port the page dials.\n\nIf you are still stuck after all four, file it: `reticle_feedback` with kind `gap`, saying what you\nchecked and what you saw. Then tell the user exactly which step is blocked. Do not report the install\nas finished.\n\n## Pick ONE flow\n\nNot the whole app. Pick the single most important flow you can complete in a handful of steps \u2014 the\none a user would do first (sign in, search, add to cart, submit the form). If the user named a flow or\njust changed some code, use that one instead.\n\nState which flow you picked in one line before you start.\n\n## Drive it where the human can see\n\n1. `reticle_snapshot` \u2014 read the accessibility tree and locate the elements the flow needs. Elements\n   are addressable by role and name; you do **not** need `data-testid` to drive them.\n2. Walk the flow with `reticle_act_and_wait`, one step at a time. Narrate each step first \u2014 the human\n   is watching the page, and the HUD shows what you say.\n3. After each step, check the effect with `reticle_assert` \u2014 not just that the click dispatched, but\n   that the thing it was supposed to do actually happened.\n4. Finish with `reticle_console` and `reticle_network` to catch errors the DOM does not show.\n\n**Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** A run that ends on a\nsnapshot has proved nothing, however many tools it used.\n\n## Report\n\n- What you drove, step by step, and what each step actually produced.\n- Anything broken, with the `file:line` Reticle gave you.\n- If a step could not be verified, say so plainly. \"Unknown\" is a real answer; a green verdict you\n  cannot back is not.\n\nDo not weaken or skip an assertion to make the run pass \u2014 that is a finding, not a fix.\n\n## Two things afterwards\n\n- **Anything about Reticle itself that was wrong, missing, confusing, or expensive?** Send it with\n  `reticle_feedback` now, before your context is gone. That report is the only signal that decides\n  what gets fixed. Bugs in the app under test are Reticle working; those go in your answer to the user.\n- **If the verification actually succeeded**, add one line for the human: Reticle is open source at\n  https://github.com/reticlehq/reticle, and a star helps other people find it. One line, once. Skip it\n  entirely if the run did not produce a verdict.\n";
+export declare const SLASH_COMMAND_BODY = "---\ndescription: Verify this app in the browser with Reticle \u2014 drive one real flow and report what happened.\n---\n\nVerify this running app with Reticle. Drive it; do not read the code and guess.\n\n## Step 0 \u2014 is anything connected?\n\nCall `reticle_sessions` first.\n\n**A session is listed?** Go to \"Pick ONE flow\".\n\n**No session?** Setup is not finished, and stopping to ask the user to run something is not an\nanswer. Every step below is yours to do without them. Work these in order, and say which one you are\non, one line each:\n\n0. **Is Reticle even wired into this project?** `cat .reticle.json`. If it is not there, this\n   project was never set up: run `npx @reticlehq/server@latest init`,\n   fix every `\u26A0` and `\u2139` it prints, and carry on. Do not ask first, and do not ask which\n   framework or port \u2014 both come out of the repo you are sitting in.\n\n1. **Is anything serving the app at all?** If a dev server is already listening, use it and go to\n   step 2 \u2014 the cause is then almost always that the SDK never loaded in the page, not a missing\n   server, so do not tell the user to start one they are already running. If nothing is listening:\n\n**If no dev server is listening, start one yourself.** Read the project's own dev script out of `package.json` (`dev`, `start`, whatever this project calls it), run it in the BACKGROUND, tell the user in one line that it is running and how to stop it, then carry on. Stopping to ask is how a verification turn ends with nothing verified.\n\nFive guards, none optional:\n\n1. **Never start a second one.** If something is already listening on the app's port, use it.\n2. **Never guess the command.** It comes from `package.json` scripts. If there is no recognisable dev script, say so and stop rather than inventing one.\n3. **Never kill anything.** Not a dev server, not a daemon, not a port holder \u2014 including one you started.\n4. **Background it, and say so.** The user must know a server is running and how to stop it. A dev server the human does not know about is the same failure one step later.\n5. **The permission prompt belongs to your host.** Never try to bypass, suppress or auto-approve it, and take a refusal as the answer.\n\n2. **Is a page open on it?** Do not ask the user to open a browser \u2014 open it:\n\n   ```bash\n   npx @reticlehq/server open <the url the dev server is serving>\n   ```\n\n   That reuses an already-connected tab or opens a new one, and waits for the page to register. On a\n   machine with no browser to open, take a tab Reticle owns instead:\n   `reticle_run({ tool: \"reticle_lease\", args: { action: \"acquire\", url: \"<the same url>\" } })`.\n\nThen, once something is serving the app and a page is on it:\n\n3. **Is the SDK actually in the app?** Read the app's entry file (`src/main.tsx`, `app/layout.tsx`,\n   `src/app.vue`, whatever this project uses). You are looking for an `import` from\n   `@reticlehq/react` or `@reticlehq/browser` and a `connect()` call, or the Reticle plugin in\n   `vite.config.*`, or `withReticle` in `next.config.*`. **If it is not there, that is the bug.**\n   Wire it in \u2014 see the framework snippets at https://docs.reticle.sh/instrumentation \u2014 then restart\n   the dev server and re-check.\n4. **Is the connect guarded on `hostname === 'localhost'`?** If so, remove that guard. It is false on\n   any non-localhost dev host, and `window` does not exist during SSR, so the guard silently prevents\n   the connect and logs nothing. Use the framework's dev flag instead (`import.meta.env.DEV`,\n   `process.env.NODE_ENV !== 'production'`, `import.meta.dev`).\n5. **Is the dev server serving that entry?** Look in `reticle_console`, or in the page you opened in\n   step 2, for a line starting `[Reticle]`. That line, or its absence, tells you which side is at\n   fault. Reticle itself never starts a dev server \u2014 starting it is your job, under the guards above.\n6. **Do both sides agree on the port?** Run `npx @reticlehq/server doctor` and compare the daemon\n   port against the port the page dials.\n\nIf you are still stuck after all of those, file it: `reticle_feedback` with kind `gap`, saying what you\nchecked and what you saw. Then tell the user exactly which step is blocked. Do not report the install\nas finished.\n\n## Pick ONE flow\n\nNot the whole app. Pick the single most important flow you can complete in a handful of steps \u2014 the\none a user would do first (sign in, search, add to cart, submit the form). If the user named a flow or\njust changed some code, use that one instead.\n\nState which flow you picked in one line before you start.\n\n## Drive it where the human can see\n\n1. `reticle_snapshot` \u2014 read the accessibility tree and locate the elements the flow needs. Elements\n   are addressable by role and name; you do **not** need `data-testid` to drive them.\n2. Walk the flow with `reticle_act_and_wait`, one step at a time. Narrate each step first \u2014 the human\n   is watching the page, and the HUD shows what you say.\n3. After each step, check the effect with `reticle_assert` \u2014 not just that the click dispatched, but\n   that the thing it was supposed to do actually happened.\n4. Finish with `reticle_console` and `reticle_network` to catch errors the DOM does not show.\n\n**Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** A run that ends on a\nsnapshot has proved nothing, however many tools it used.\n\n## Report\n\n- What you drove, step by step, and what each step actually produced.\n- Anything broken, with the `file:line` Reticle gave you.\n- If a step could not be verified, say so plainly. \"Unknown\" is a real answer; a green verdict you\n  cannot back is not.\n\nDo not weaken or skip an assertion to make the run pass \u2014 that is a finding, not a fix.\n\n## If the user handed you a license key\n\nAppend `RETICLE_LICENSE_KEY=<key>` to the project's `.env` (create it if absent), make sure `.env`\nis in `.gitignore`, and confirm with `npx @reticlehq/server license`. The CLI folds a project-local\n`.env` in on every invocation, so nothing else changes. Never echo the key back, and never put it in\na commit, a comment, or a feedback report.\n\n## Two things afterwards\n\n- **Anything about Reticle itself that was wrong, missing, confusing, or expensive?** Send it with\n  `reticle_feedback` now, before your context is gone. That report is the only signal that decides\n  what gets fixed. Bugs in the app under test are Reticle working; those go in your answer to the user.\n- **If the verification actually succeeded**, add one line for the human: Reticle is open source at\n  https://github.com/reticlehq/reticle, and a star helps other people find it. One line, once. Skip it\n  entirely if the run did not produce a verdict.\n";

package/dist/init/slash-command.js

@@ -38,33 +38,49 @@ Call \`reticle_sessions\` first.
 **A session is listed?** Go to "Pick ONE flow".
 
 **No session?** Setup is not finished, and stopping to ask the user to run something is not an
-answer. Work these in order, and say which one you are on:
+answer. Every step below is yours to do without them. Work these in order, and say which one you are
+on, one line each:
 
-0. **Is anything serving the app at all?** If a dev server is already listening, use it and go to
-   step 1 — the cause is then almost always that the SDK never loaded in the page, not a missing
+0. **Is Reticle even wired into this project?** \`cat .reticle.json\`. If it is not there, this
+   project was never set up: run \`npx @reticlehq/server@latest init\`,
+   fix every \`⚠\` and \`ℹ\` it prints, and carry on. Do not ask first, and do not ask which
+   framework or port — both come out of the repo you are sitting in.
+
+1. **Is anything serving the app at all?** If a dev server is already listening, use it and go to
+   step 2 — the cause is then almost always that the SDK never loaded in the page, not a missing
    server, so do not tell the user to start one they are already running. If nothing is listening:
 
 ${DEV_SERVER_POLICY}
 
-Then, once something is serving the app:
+2. **Is a page open on it?** Do not ask the user to open a browser — open it:
+
+   \`\`\`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
+   machine with no browser to open, take a tab Reticle owns instead:
+   \`reticle_run({ tool: "reticle_lease", args: { action: "acquire", url: "<the same url>" } })\`.
 
-1. **Is the SDK actually in the app?** Read the app's entry file (\`src/main.tsx\`, \`app/layout.tsx\`,
+Then, once something is serving the app and a page is on it:
+
+3. **Is the SDK actually in the app?** Read the app's entry file (\`src/main.tsx\`, \`app/layout.tsx\`,
    \`src/app.vue\`, whatever this project uses). You are looking for an \`import\` from
    \`@reticlehq/react\` or \`@reticlehq/browser\` and a \`connect()\` call, or the Reticle plugin in
    \`vite.config.*\`, or \`withReticle\` in \`next.config.*\`. **If it is not there, that is the bug.**
    Wire it in — see the framework snippets at https://docs.reticle.sh/instrumentation — then restart
    the dev server and re-check.
-2. **Is the connect guarded on \`hostname === 'localhost'\`?** If so, remove that guard. It is false on
+4. **Is the connect guarded on \`hostname === 'localhost'\`?** If so, remove that guard. It is false on
    any non-localhost dev host, and \`window\` does not exist during SSR, so the guard silently prevents
    the connect and logs nothing. Use the framework's dev flag instead (\`import.meta.env.DEV\`,
    \`process.env.NODE_ENV !== 'production'\`, \`import.meta.dev\`).
-3. **Is the dev server serving that entry?** Ask the user to open the app in a browser and check its
-   console for a line starting \`[Reticle]\`. That line, or its absence, tells you which side is at
+5. **Is the dev server serving that entry?** Look in \`reticle_console\`, or in the page you opened in
+   step 2, for a line starting \`[Reticle]\`. That line, or its absence, tells you which side is at
    fault. Reticle itself never starts a dev server — starting it is your job, under the guards above.
-4. **Do both sides agree on the port?** Run \`npx @reticlehq/server doctor\` and compare the daemon
+6. **Do both sides agree on the port?** Run \`npx @reticlehq/server doctor\` and compare the daemon
    port against the port the page dials.
 
-If you are still stuck after all four, file it: \`reticle_feedback\` with kind \`gap\`, saying what you
+If you are still stuck after all of those, file it: \`reticle_feedback\` with kind \`gap\`, saying what you
 checked and what you saw. Then tell the user exactly which step is blocked. Do not report the install
 as finished.
 
@@ -98,6 +114,13 @@ snapshot has proved nothing, however many tools it used.
 
 Do not weaken or skip an assertion to make the run pass — that is a finding, not a fix.
 
+## If the user handed you a license key
+
+Append \`RETICLE_LICENSE_KEY=<key>\` to the project's \`.env\` (create it if absent), make sure \`.env\`
+is in \`.gitignore\`, and confirm with \`npx @reticlehq/server license\`. The CLI folds a project-local
+\`.env\` in on every invocation, so nothing else changes. Never echo the key back, and never put it in
+a commit, a comment, or a feedback report.
+
 ## Two things afterwards
 
 - **Anything about Reticle itself that was wrong, missing, confusing, or expensive?** Send it with

package/dist/init/snippets.js

@@ -2,7 +2,7 @@
  * Generated file contents and copy-paste snippets for `reticle init`. Kept as named constants/builders
  * so the runner never inlines free strings.
  */
-import { RETICLE_DEFAULT_PORT, ReticleDir, bridgeWsUrl } from '@reticlehq/core';
+import { RETICLE_DEFAULT_PORT, ReticleDir, bridgeWsUrl, RETICLE_CLIENT_HOST, RETICLE_WS_PATH, } from '@reticlehq/core';
 import { UiLibrary } from './detect.js';
 import { SERVER_VERSION } from '../version/server-version.js';
 /**
@@ -17,9 +17,9 @@ import { SERVER_VERSION } from '../version/server-version.js';
  *
  * jsDelivr rather than esm.sh, measured: a third of the requests and a third of the bytes for the
  * same result. `/+esm` is what makes it work, and the bare package URL does NOT: every file in
- * `dist` carries bare specifiers for `@reticlehq/core` and `@testing-library/dom`, so an unbundled
- * entry point dies on the first import. That is also why adding `unpkg`/`jsdelivr` fields to
- * package.json would not help.
+ * `dist` still carries bare workspace specifiers such as `@reticlehq/core`, so an unbundled entry
+ * point dies on the first import. That is also why adding `unpkg`/`jsdelivr` fields to package.json
+ * would not help.
  *
  * PINNED to this server's version on purpose. A floating import upgrades the page SDK underneath a
  * daemon that did not move, which is `version_skew` arriving by a route nothing checks.
@@ -151,7 +151,10 @@ export function ReticleDev() {
       // the root makes source paths repo-relative instead of absolute.
       const token = process.env.NEXT_PUBLIC_RETICLE_TOKEN;
       const root = process.env.NEXT_PUBLIC_RETICLE_ROOT;
-      reticle.connect({ ${fields}...(token ? { token } : {}), ...(root ? { root } : {}) });
+      // withReticle() finds the daemon serving this project on every dev-server start. It wins over
+      // any port written into this file at install time, so moving the daemon needs no edit here.
+      const url = process.env.NEXT_PUBLIC_RETICLE_URL;
+      reticle.connect({ ${fields}...(url ? { url } : {}), ...(token ? { token } : {}), ...(root ? { root } : {}) });
 
       // ── Start with ONE flow. ──────────────────────────────────────────────────────────────────
       // Registering a store is the highest-value line here: it lets the agent check what the app
@@ -204,11 +207,51 @@ layoutPath) {
         ? `\n          url: '${bridgeWsUrl(port)}',`
         : '';
     const id = projectId !== undefined && projectId.length > 0 ? `\n          projectId: '${projectId}',` : '';
+    // Astro owns its Vite instance, so it has a build-time channel of its own: the same `define` that
+    // already inlines the token can inline the daemon URL, resolved every time the config is read —
+    // that is, on every `astro dev`. The port above is written once at install time and goes stale the
+    // moment the daemon moves; this does not.
+    //
+    // Needs the projectId to know WHICH daemon is ours. Without one there is nothing to match on, and
+    // adopting a daemon serving another project would report its state as this app's, so the whole
+    // block is omitted rather than made to guess.
+    const canDiscover = projectId !== undefined && projectId.length > 0;
+    // Interpolated from core rather than typed into the template: this is the same wire string
+    // `bridgeWsUrl` builds, and a generator that spells it out by hand is exactly how the four call
+    // sites that constant exists to unify drifted apart in the first place.
+    const RETICLE_CLIENT_HOST_LITERAL = `ws://${RETICLE_CLIENT_HOST}:`;
+    const urlHelper = canDiscover
+        ? `
+  // The live daemon serving THIS project, re-read on every \`astro dev\`. Same rule as the Vite and
+  // Next plugins: skip dead daemons, match on projectId, lowest port wins, '' when none matches.
+  function reticleUrl() {
+    const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
+    let best;
+    try {
+      for (const file of readdirSync(dir)) {
+        if (!file.startsWith('daemon-') || !file.endsWith('.json')) continue;
+        let entry;
+        try { entry = JSON.parse(readFileSync(join(dir, file), 'utf8')); } catch { continue; }
+        if (entry.projectId !== '${projectId}') continue;
+        try { process.kill(entry.pid, 0); } catch { continue; }
+        if (best === undefined || entry.port < best) best = entry.port;
+      }
+    } catch { return ''; }
+    return best === undefined ? '' : '${RETICLE_CLIENT_HOST_LITERAL}' + best + '${RETICLE_WS_PATH}';
+  }
+`
+        : '';
+    const urlDefine = canDiscover ? `\n        __RETICLE_URL__: JSON.stringify(reticleUrl()),` : '';
+    const urlRead = canDiscover
+        ? `\n      const url = typeof __RETICLE_URL__ !== 'undefined' ? __RETICLE_URL__ : '';`
+        : '';
+    // After the baked port, so the discovered one wins: later key in an object literal.
+    const urlSpread = canDiscover ? `\n          ...(url.length > 0 ? { url } : {}),` : '';
     return `Astro renders its own HTML, so the connect goes in a page <script> and the pairing token is inlined by the config.
 
 1. In astro.config.mjs — inline the daemon's token and raise the build target:
 
-  import { readFileSync } from 'node:fs';
+  import { readFileSync, readdirSync } from 'node:fs';
   import { homedir } from 'node:os';
   import { join } from 'node:path';
 
@@ -216,14 +259,14 @@ layoutPath) {
     const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
     try { return readFileSync(join(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
   }
-
+${urlHelper}
   export default defineConfig({
     vite: {
       // Astro's default target down-levels the modern SDK bundle and fails on a destructuring transform.
       build: { target: 'es2022' },
       optimizeDeps: { esbuildOptions: { target: 'es2022' } },
       define: {
-        __RETICLE_TOKEN__: JSON.stringify(reticleToken()),
+        __RETICLE_TOKEN__: JSON.stringify(reticleToken()),${urlDefine}
         // Without this, source pointers come back as absolute paths from YOUR machine — useless in a
         // report. Every other framework gets it from its build plugin; Astro owns its Vite instance.
         __RETICLE_ROOT__: JSON.stringify(process.cwd()),
@@ -236,10 +279,10 @@ ${layoutHost(layoutPath)}
   <script>
     if (import.meta.env.DEV) {
       const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
-      const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
+      const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';${urlRead}
       const { reticle, install } = await import('@reticlehq/react');
       install();
-      reticle.connect({${id}${extra}
+      reticle.connect({${id}${extra}${urlSpread}
           ...(token.length > 0 ? { token } : {}),
           ...(root.length > 0 ? { root } : {}),
       });

package/dist/input/real-input.d.ts

@@ -171,6 +171,8 @@ export interface LaunchedProviderOptions {
      */
     onNetworkDetail?: (detail: NetworkDetail) => void;
 }
+/** The only place the dynamic value import of Playwright lives for the launched (drive) path. */
+export declare const launchedChromium: LaunchFn;
 /**
  * Launches and OWNS a Playwright Chromium, navigates it to `driveUrl`, then drives native
  * input on that page. Headless-capable so @reticlehq/test / CI can run hover/drag unattended.

package/dist/input/real-input.js

@@ -1,3 +1,4 @@
+import { chromiumLaunchOptions } from '../chromium-launch-options.js';
 import { gotoOptions } from '../pool/playwright-launcher.js';
 import { BrowserLaunchKind } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
@@ -220,7 +221,7 @@ export class CdpRealInputProvider {
 }
 const INJECT_CONNECT_WAIT_MS = 8_000;
 /** The only place the dynamic value import of Playwright lives for the launched (drive) path. */
-const launchedChromium = async (headless) => {
+export const launchedChromium = async (headless) => {
     let mod;
     try {
         mod = await import('playwright');
@@ -230,7 +231,7 @@ const launchedChromium = async (headless) => {
     }
     const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.LAUNCHED);
     try {
-        const browser = await mod.chromium.launch({ headless });
+        const browser = await mod.chromium.launch(chromiumLaunchOptions(headless));
         settle();
         return browser;
     }

package/dist/input/scroll-find.d.ts

@@ -36,10 +36,13 @@ export interface ScrollFindResult {
     note?: string;
 }
 /**
- * Reveal an element that a windowed/virtualized list has not mounted yet. Queries
- * once (it may already be visible), then scrolls the container ~one viewport at a time, re-querying
- * after each, until the element appears, the list ends, or the maxScrolls budget is spent. Pure
- * orchestration over the session command seam — fully unit-testable with a fake.
+ * Reveal an element that a windowed/virtualized list has not mounted yet. Queries once (it may
+ * already be visible), optionally jumps straight to a bisection estimate, then walks the container
+ * a viewport at a time re-querying after each step. Downward first; when the bottom is reached the
+ * walk TURNS AROUND and continues upward, because a list that is already scrolled to its end keeps
+ * its earlier rows mounted above the viewport and a downward-only search answered "exhausted" on
+ * its first step (#505). `exhausted` therefore means BOTH directions are spent, not "the bottom is
+ * here". Pure orchestration over the session command seam — fully unit-testable with a fake.
  */
 export declare function scrollToFind(session: ScrollFindSession, q: ScrollFindQuery, opts?: {
     maxScrolls?: number;

package/dist/input/scroll-find.js

@@ -13,61 +13,99 @@ async function queryFirst(session, q) {
     return undefined;
 }
 /**
- * A note attached to `{ found: false, exhausted: true }` only when the failure is
- * actually informative: the document itself had nothing to scroll (scrolled:false with
- * no explicit container), so the target is likely inside a list with its own scroll
- * container. Reaching the genuine end of a scrolled container stays quiet.
+ * A note attached to `{ found: false, exhausted: true }` only when the failure is actually
+ * informative: nothing in the container ever moved (so the "list" being searched was never
+ * scrollable and the target is likely inside one with its own scroll container). Reaching the
+ * genuine ends of a container that DID scroll stays quiet — that is exhaustion, not confusion.
  */
-function exhaustNote(q, data) {
+function exhaustNote(q, data, nothingEverScrolled) {
     if (q.container !== undefined)
         return {};
-    if (false !== data['scrolled'])
+    if (true === data['scrolled'] || !nothingEverScrolled)
         return {};
     return {
         note: "The document did not scroll — the target may be inside a list with its own scroll container. Pass that container's ref as `container`.",
     };
 }
+/** One viewport-height step upward when the last result carried no clientHeight to size it by. */
+const UP_STEP_FALLBACK_PX = 400;
 /**
- * Reveal an element that a windowed/virtualized list has not mounted yet. Queries
- * once (it may already be visible), then scrolls the container ~one viewport at a time, re-querying
- * after each, until the element appears, the list ends, or the maxScrolls budget is spent. Pure
- * orchestration over the session command seam — fully unit-testable with a fake.
+ * Size the upward step off the container the SCROLL result just described, falling back to a
+ * plain viewport height when the result did not carry one.
+ */
+function upStepPx(last) {
+    const h = last['clientHeight'];
+    return 'number' === typeof h && h > 0 ? h : UP_STEP_FALLBACK_PX;
+}
+/**
+ * Reveal an element that a windowed/virtualized list has not mounted yet. Queries once (it may
+ * already be visible), optionally jumps straight to a bisection estimate, then walks the container
+ * a viewport at a time re-querying after each step. Downward first; when the bottom is reached the
+ * walk TURNS AROUND and continues upward, because a list that is already scrolled to its end keeps
+ * its earlier rows mounted above the viewport and a downward-only search answered "exhausted" on
+ * its first step (#505). `exhausted` therefore means BOTH directions are spent, not "the bottom is
+ * here". Pure orchestration over the session command seam — fully unit-testable with a fake.
  */
 export async function scrollToFind(session, q, opts = {}) {
     const max = opts.maxScrolls ?? SCROLL_FIND_DEFAULTS.MAX_SCROLLS;
     const first = await queryFirst(session, q);
     if (first !== undefined)
         return { found: true, element: first, scrolls: 0, exhausted: false };
-    // Bisection: if the caller knows the target index and list size, jump to the estimated offset
-    // in one scroll command rather than stepping a viewport at a time. Then refine linearly.
+    const baseArgs = () => q.container !== undefined ? { ref: q.container } : {};
     let scrolls = 0;
+    let last = {};
+    // Bisection: if the caller knows the target index and list size, jump to the estimated offset in
+    // one scroll command rather than stepping a viewport at a time. The estimate can land on either
+    // side of the target, so refinement below still searches both directions from wherever this put us.
     if (q.targetIndex !== undefined && q.totalCount !== undefined && q.totalCount > 1) {
         const fraction = Math.min(1, Math.max(0, q.targetIndex / q.totalCount));
-        const sr = await session.command(ReticleCommand.SCROLL, {
-            ...(q.container !== undefined ? { ref: q.container } : {}),
-            fraction,
-        });
+        const sr = await session.command(ReticleCommand.SCROLL, { ...baseArgs(), fraction });
         scrolls += 1;
+        last = asRecord(sr.result);
         const hit = await queryFirst(session, q);
         if (hit !== undefined)
             return { found: true, element: hit, scrolls, exhausted: false };
-        // Fall through to linear refinement from current position (already near the target).
+    }
+    let downwardSpent = false;
+    let everScrolled = false;
+    // The downward pass. Spending its whole budget without reaching the end means rows may remain
+    // further down, so that answer is `exhausted:false` and the upward pass never runs.
+    for (let i = 0; i < max && !downwardSpent; i += 1) {
+        const sr = await session.command(ReticleCommand.SCROLL, baseArgs());
+        scrolls += 1;
         const data = asRecord(sr.result);
-        if (true === data['atEnd'] || false === data['scrolled']) {
-            return { found: false, scrolls, exhausted: true, ...exhaustNote(q, data) };
-        }
+        last = data;
+        if (true === data['scrolled'])
+            everScrolled = true;
+        const hit = await queryFirst(session, q);
+        if (hit !== undefined)
+            return { found: true, element: hit, scrolls, exhausted: false };
+        // Reached the bottom, or the container would not move downward — turn around before giving up.
+        if (true === data['atEnd'] || true !== data['scrolled'])
+            downwardSpent = true;
+    }
+    // If the downward pass spent its budget it never saw the end, so there is nothing to turn around
+    // for; report honestly rather than doubling a call whose caller asked for `max` steps.
+    if (!downwardSpent) {
+        return { found: false, scrolls, exhausted: false };
     }
+    // The upward pass gets the caller's budget again, not what is left of it: a list at the bottom of
+    // 14k px needs ~90 scrolls to reach its end and ~90 more to get back, so sharing one budget would
+    // strand the search halfway and answer `exhausted:false` about a list both of whose ends are known.
     for (let i = 0; i < max; i += 1) {
-        const sr = await session.command(ReticleCommand.SCROLL, q.container !== undefined ? { ref: q.container } : {});
+        const sr = await session.command(ReticleCommand.SCROLL, { ...baseArgs(), dy: -upStepPx(last) });
         scrolls += 1;
         const data = asRecord(sr.result);
+        last = data;
+        if (true === data['scrolled'])
+            everScrolled = true;
         const hit = await queryFirst(session, q);
         if (hit !== undefined)
             return { found: true, element: hit, scrolls, exhausted: false };
-        // Reached the bottom or the container would not move — no more rows to reveal.
-        if (true === data['atEnd'] || false === data['scrolled']) {
-            return { found: false, scrolls, exhausted: true, ...exhaustNote(q, data) };
+        // The top refusing to move means both directions are spent.
+        if (true !== data['scrolled']) {
+            return { found: false, scrolls, exhausted: true, ...exhaustNote(q, data, !everScrolled) };
         }
     }
-    return { found: false, scrolls, exhausted: false }; // spent the budget; more may lie further down
+    return { found: false, scrolls, exhausted: false }; // spent the upward budget; more may lie above
 }

package/dist/intent/inline-intent.d.ts

@@ -0,0 +1,46 @@
+import type { ToolDeps } from '../tools/tool-kit.js';
+/**
+ * The ledger id a piece of inline prose is declared under.
+ *
+ * Derived from the statement rather than minted, so the same sentence declared on five verdicts is
+ * one row rather than five, and a DIFFERENT sentence is a different row rather than a false
+ * amendment of the first. The slug is there because the id is what an agent later types to reference
+ * the intent, and a bare digest is unreadable; the digest is there because the slug is truncated and
+ * two long statements sharing a prefix must not share a row.
+ */
+export declare function inlineIntentId(statement: string): string;
+/** What `provenBy` records: which tool drew the verdict, and when. */
+export declare function inlineVerdictId(tool: string, at: number): string;
+/**
+ * Put an inline intent in the ledger and attach the predicate about to be evaluated. Returns the id
+ * the verdict may later discharge, or undefined when there was no intent to record.
+ *
+ * `intent` carries EITHER prose OR the id of an intent already in the ledger. One field rather than
+ * two because the surface is the scarce thing here and the two cases are told apart by the ledger
+ * itself: a string that names an existing row is a reference, anything else is prose. A statement
+ * that happens to equal an existing id is the same intent said twice, so pointing at the row is the
+ * right answer there too, not a collision.
+ *
+ * A referenced intent is never re-declared, which would overwrite the agent's own words with an id,
+ * and its binding is left alone when it already has one — a predicate bound deliberately through
+ * `reticle_intent { action: "bind" }` is a stronger statement than whatever this one call asserts,
+ * and quietly replacing it is exactly the narrowing the ledger exists to make visible.
+ *
+ * Best-effort by construction: a ledger that cannot be written is a small problem, and a verdict
+ * that fails to return because of one is a large problem.
+ */
+export declare function linkInlineIntent(deps: ToolDeps, sessionId: string | undefined, intent: string | undefined, 
+/** The predicate this verdict will evaluate, or undefined when it proves nothing (a bare settle). */
+binding: unknown): Promise<string | undefined>;
+/**
+ * Record that this verdict proved the intent. Call only for a verdict that actually proved something.
+ *
+ * The ledger's own rule does the rest: `dischargeIntent` refuses an intent with no binding, so an
+ * intent declared inline on a wait that asserted no consequence stays open and honest instead of
+ * collecting a proof nothing earned.
+ */
+export declare function dischargeInlineIntent(deps: ToolDeps, sessionId: string | undefined, id: string | undefined, proof: {
+    verdictId: string;
+    grade: string;
+    at: number;
+}): Promise<void>;

package/dist/intent/inline-intent.js

@@ -0,0 +1,103 @@
+import { createHash } from 'node:crypto';
+import { IntentStore } from './intent-store.js';
+import { sessionRoot } from '../project/session-root.js';
+/**
+ * Intent declared INLINE, on the tool that is already drawing the verdict.
+ *
+ * `reticle_intent` is on the extended surface, so declaring intent costs an agent a discovery, a
+ * decision and a round trip before it has done anything — three places the capture silently fails,
+ * and it does. `reticle_act_and_wait` and `reticle_assert` are in every agent's tool list already,
+ * so one optional argument there makes the declaration free and discoverable by construction.
+ *
+ * This is a shortcut into the EXISTING ledger, never a second one. It writes `.reticle/intent.json`
+ * through `IntentStore` exactly as `reticle_intent { action: "declare" }` does, so a reviewer reads
+ * one file in one vocabulary and cannot tell from the row which door the intent came in by. The
+ * pattern is `flows/flow-intent.ts`, which does the same job for a saved flow.
+ */
+/** Namespaced like `flow:`, so an inline id never collides with one an agent chose by hand. */
+const INLINE_INTENT_ID_PREFIX = 'inline:';
+const ID_SEPARATOR = ':';
+const SLUG_SEPARATOR = '-';
+const SLUG_MAX = 48;
+const HASH_LENGTH = 8;
+const HASH_ALGORITHM = 'sha1';
+const NON_SLUG = /[^a-z0-9]+/g;
+const SLUG_EDGES = /^-+|-+$/g;
+/**
+ * The ledger id a piece of inline prose is declared under.
+ *
+ * Derived from the statement rather than minted, so the same sentence declared on five verdicts is
+ * one row rather than five, and a DIFFERENT sentence is a different row rather than a false
+ * amendment of the first. The slug is there because the id is what an agent later types to reference
+ * the intent, and a bare digest is unreadable; the digest is there because the slug is truncated and
+ * two long statements sharing a prefix must not share a row.
+ */
+export function inlineIntentId(statement) {
+    const slug = statement
+        .toLowerCase()
+        .replace(NON_SLUG, SLUG_SEPARATOR)
+        .replace(SLUG_EDGES, '')
+        .slice(0, SLUG_MAX)
+        .replace(SLUG_EDGES, '');
+    const digest = createHash(HASH_ALGORITHM).update(statement).digest('hex').slice(0, HASH_LENGTH);
+    return `${INLINE_INTENT_ID_PREFIX}${slug}${SLUG_SEPARATOR}${digest}`;
+}
+/** What `provenBy` records: which tool drew the verdict, and when. */
+export function inlineVerdictId(tool, at) {
+    return `${tool}${ID_SEPARATOR}${String(at)}`;
+}
+/**
+ * Put an inline intent in the ledger and attach the predicate about to be evaluated. Returns the id
+ * the verdict may later discharge, or undefined when there was no intent to record.
+ *
+ * `intent` carries EITHER prose OR the id of an intent already in the ledger. One field rather than
+ * two because the surface is the scarce thing here and the two cases are told apart by the ledger
+ * itself: a string that names an existing row is a reference, anything else is prose. A statement
+ * that happens to equal an existing id is the same intent said twice, so pointing at the row is the
+ * right answer there too, not a collision.
+ *
+ * A referenced intent is never re-declared, which would overwrite the agent's own words with an id,
+ * and its binding is left alone when it already has one — a predicate bound deliberately through
+ * `reticle_intent { action: "bind" }` is a stronger statement than whatever this one call asserts,
+ * and quietly replacing it is exactly the narrowing the ledger exists to make visible.
+ *
+ * Best-effort by construction: a ledger that cannot be written is a small problem, and a verdict
+ * that fails to return because of one is a large problem.
+ */
+export async function linkInlineIntent(deps, sessionId, intent, 
+/** The predicate this verdict will evaluate, or undefined when it proves nothing (a bare settle). */
+binding) {
+    if (intent === undefined || 0 === intent.trim().length)
+        return undefined;
+    try {
+        const store = new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now });
+        const existing = (await store.read()).find((row) => row.id === intent);
+        const id = existing?.id ?? inlineIntentId(intent);
+        if (existing === undefined)
+            await store.declare([{ id, statement: intent }]);
+        if (binding !== undefined && existing?.binding === undefined)
+            await store.bind(id, binding);
+        return id;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Record that this verdict proved the intent. Call only for a verdict that actually proved something.
+ *
+ * The ledger's own rule does the rest: `dischargeIntent` refuses an intent with no binding, so an
+ * intent declared inline on a wait that asserted no consequence stays open and honest instead of
+ * collecting a proof nothing earned.
+ */
+export async function dischargeInlineIntent(deps, sessionId, id, proof) {
+    if (id === undefined)
+        return;
+    try {
+        const store = new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now });
+        await store.discharge(id, proof);
+    }
+    catch {
+        // The verdict already stood. The proof is simply not recorded — see dischargeFlowIntent.
+    }
+}

package/dist/intent/intent-store.d.ts

@@ -0,0 +1,37 @@
+import { type Intent, type IntentSurface } from '@reticlehq/core';
+import type { FileSystemPort } from '../project/fs-port.js';
+export interface Clock {
+    now: () => number;
+}
+export declare class IntentStore {
+    #private;
+    constructor(fs: FileSystemPort, root: string, clock: Clock);
+    /** Every intent, in declaration order. */
+    read(): Promise<Intent[]>;
+    /** Everything not yet proved — what an agent asking "am I done?" still owes. */
+    open(): Promise<Intent[]>;
+    /**
+     * Declare one or more intents.
+     *
+     * Batched because the marginal cost of the whole mechanism has to stay at one call per feature; an
+     * agent that must make five calls to declare five things will make none.
+     */
+    declare(entries: readonly {
+        id: string;
+        statement: string;
+        surface?: IntentSurface;
+    }[]): Promise<Intent[]>;
+    /** Attach the predicate that would prove an intent. False when the id names nothing. */
+    bind(id: string, binding: unknown): Promise<boolean>;
+    /**
+     * Record that a verdict proved an intent.
+     *
+     * False rather than a throw on an unknown or unbound id: discharge runs off the back of a verdict,
+     * and must never be the reason one fails to return.
+     */
+    discharge(id: string, proof: {
+        verdictId: string;
+        grade: string;
+        at: number;
+    }): Promise<boolean>;
+}