@reticlehq/server 2.11.0 → 2.12.0

package/dist/init/refresh-rules.js

@@ -0,0 +1,51 @@
+/**
+ * Bring an already-installed project's agent rules up to the version that is running.
+ *
+ * `mergeMarkedInstruction` has always been able to do this: the managed block is marker-delimited,
+ * idempotence is decided by comparing CONTENT rather than by seeing a marker, and everything
+ * outside the markers is left exactly as the human wrote it. What was missing is anything that
+ * CALLS it after the first install.
+ *
+ * It is reachable only from `buildPlan`, so the rules refresh when somebody re-runs `init` and
+ * never otherwise. A project set up on an older release keeps that release's instructions forever,
+ * which means every improvement to them — what to do when a capabilities file registers nothing,
+ * that an install is not finished until a verdict exists, that intent is captured while building —
+ * reaches new projects only.
+ *
+ * That is the wrong way round. The people who most need better instructions are the ones already
+ * installed and not getting value, and `reticle update` is the moment they are already touching the
+ * install.
+ */
+import { join } from 'node:path';
+import { mergeMarkedInstruction, AgentRuleStatus, hasManagedBlock } from './agent-rules.js';
+/** The instruction files the managed block lives in. Cursor's rule file is regenerated whole. */
+export const RULE_FILES = ['CLAUDE.md', 'AGENTS.md'];
+/**
+ * Refresh every instruction file that already carries a Reticle block.
+ *
+ * Deliberately does NOT create one where none exists. A project with no Reticle block in its
+ * CLAUDE.md either never ran `init` here or had the block removed on purpose, and `update` is not
+ * the place to make that decision for somebody — it is a version command, and quietly writing
+ * instructions into a file a user curates would be a surprise.
+ */
+export function refreshAgentRules(cwd, io) {
+    const updated = [];
+    const unchanged = [];
+    for (const name of RULE_FILES) {
+        const path = join(cwd, name);
+        const existing = io.read(path);
+        if (null === existing || !hasManagedBlock(existing)) {
+            unchanged.push(name);
+            continue;
+        }
+        const result = mergeMarkedInstruction(existing);
+        if (AgentRuleStatus.APPLY === result.status && result.content !== existing) {
+            io.write(path, result.content);
+            updated.push(name);
+        }
+        else {
+            unchanged.push(name);
+        }
+    }
+    return { updated, unchanged };
+}

package/dist/init/run.d.ts

@@ -3,8 +3,6 @@
  * plan (pure), optionally write the apply-steps, and print a human-readable report. All filesystem
  * access goes through `InitIo` so the orchestration is unit-testable with an in-memory IO.
  */
-import { Framework } from './detect.js';
-import { StepStatus } from './plan.js';
 import type { InitOutcome } from '@reticlehq/core';
 /**
  * Resolve the lockfiles set used to pick the package manager. A lockfile in the project root wins;
@@ -93,28 +91,4 @@ export interface InitResult {
  * it knows it is in a workspace; this is the matching walk DOWN.
  */
 export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
-/**
- * The standing ask, printed at the end of every `init`.
- *
- * Addressed to the agent as much as the human: whichever of them just ran this command is the one
- * holding the experience, and neither has a Reticle tool surface to file through at this point.
- *
- * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
- * the workspace redirect is kept from asking twice.
- */
-export declare const FEEDBACK_HINT: string;
-/**
- * The last two lines a user reads, and the order matters.
- *
- * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
- * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
- * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
- * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
- * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
- * failed.
- *
- * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
- * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
- */
-export declare function restartHint(framework: Framework, mcpStatus: StepStatus | undefined): string;
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;

package/dist/init/run.js

@@ -5,6 +5,8 @@
  */
 import { dirname, join } from 'node:path';
 import { noPackageJsonMessage } from './non-js-project.js';
+import { devCommandFrom } from './dev-script.js';
+import { restartHint, FEEDBACK_HINT } from './closing-hint.js';
 import { spanSync } from '../trace.js';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -15,7 +17,7 @@ import { pickAstroHost } from './astro-host.js';
 import { workspaceParents } from './workspace-apps.js';
 import { chooseWorkspaceApp } from './app-choice.js';
 import { isConnectStep } from './connect-steps.js';
-import { CLI, CURSOR_RULE_PATH, RETICLE_MD_PATH } from './agent-rules.js';
+import { CURSOR_RULE_PATH, RETICLE_MD_PATH } from './agent-rules.js';
 import { CRA_ENV_PATH } from './cra.js';
 /** CRA's bundled entry, in the order create-react-app itself generates them. */
 const CRA_ENTRY_CANDIDATES = ['src/index.tsx', 'src/index.jsx', 'src/index.ts', 'src/index.js'];
@@ -352,6 +354,7 @@ function gatherPlanInput(options, io, pkgRaw) {
         claudeCli,
         mcpExists,
         cursorPresent,
+        platform: process.platform,
         detectedClients,
         cursorProjectPresent: io.exists(CURSOR_DIR_RELPATH),
         cursorConfig,
@@ -375,6 +378,7 @@ function gatherPlanInput(options, io, pkgRaw) {
         nextReticleDevPath: devLocation.path,
         nextReticleDevImport: devLocation.importSpecifier,
         nextReticleDevExists: io.exists(devLocation.path),
+        nextReticleDevSource: io.readFile(devLocation.path),
         svelteKitHooksExists: io.exists(SVELTEKIT_HOOKS),
         craEntry: craEntryOf(io),
         craEnv: io.readFile(CRA_ENV_PATH),
@@ -468,91 +472,11 @@ export function findWorkspaceApps(io) {
     }
     return [...new Set(found)];
 }
-/**
- * The standing ask, printed at the end of every `init`.
- *
- * Addressed to the agent as much as the human: whichever of them just ran this command is the one
- * holding the experience, and neither has a Reticle tool surface to file through at this point.
- *
- * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
- * the workspace redirect is kept from asking twice.
- */
-export const FEEDBACK_HINT = 'Anything wrong, missing, or awkward — in this setup or in Reticle itself? Tell us; it is the ' +
-    'one thing that decides what gets fixed:\n' +
-    `  ${CLI} feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"   (agents)\n` +
-    `  ${CLI} feedback "what worked, what didn't"   (humans)`;
-function devServerRestart(framework) {
-    if (framework === Framework.NEXT)
-        return 'Restart `next dev`';
-    if (framework === Framework.VITE)
-        return 'Restart `vite`';
-    if (framework === Framework.ASTRO)
-        return 'Restart `astro dev`';
-    if (framework === Framework.SVELTEKIT)
-        return 'Restart your dev server (`npm run dev`)';
-    return 'Reload your app on localhost';
-}
-/**
- * The last two lines a user reads, and the order matters.
- *
- * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
- * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
- * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
- * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
- * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
- * failed.
- *
- * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
- * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
- */
-export function restartHint(framework, mcpStatus) {
-    const dev = `${devServerRestart(framework)}.`;
-    // NAME THE COMMAND THAT PROVES IT, not one that merely asks.
-    //
-    // `init` writes files and stops; the install is not finished until an app carrying the SDK has
-    // actually dialled the daemon, and nothing here confirmed that. The field shape is unambiguous:
-    // people complete the agent half, never complete the app half, and keep a daemon running for
-    // weeks with nothing to drive — so this is the last instruction most of them read.
-    //
-    // "Ask your agent: List Reticle sessions" asks a question whose failure is a dead end. `reticle
-    // status` ANSWERS it: as of 2.7.0 it reports the session, or says why there is none — no app
-    // running, an app running that never dialled us, a tab that closed — with the fix for each.
-    const prove = 'Then run `npx @reticlehq/server status` — it confirms the app connected, or says exactly why ' +
-        'it has not.';
-    // Nothing registered this run (`--no-mcp`, or a client that needs a manual edit): a restart picks
-    // up nothing, so advice about one would be advice about something we did not do.
-    if (!wasMcpRegistered(mcpStatus))
-        return `${dev} ${prove}`;
-    // ALREADY: the tools are reachable RIGHT NOW, and this is the branch that used to lie.
-    //
-    // `wasMcpRegistered` is true for both APPLY and ALREADY, which is correct for the funnel field it
-    // was written for and wrong here, because the two cases have opposite answers to "must anybody
-    // restart". Every second project on a machine, and every Claude Code plugin install, took the
-    // APPLY text: "restart your agent — the tools only appear after that". An agent reads this AFTER
-    // whatever its skill file said, and it describes the output in front of it, so it wins. The agent
-    // stops with the project wired and nothing driven, which is the exact failure the install path
-    // exists to prevent, caused by the install path itself.
-    if (mcpStatus === StepStatus.ALREADY) {
-        return (`${dev}\n` +
-            'The Reticle MCP server was already registered on this machine, so there is no restart to do ' +
-            'and the tools are available now.\n' +
-            `${prove}\n` +
-            'Once it shows a session, drive a flow — that is the install finished. Carry straight on; ' +
-            'nothing here is waiting on a human.');
-    }
-    return (`${dev}\n` +
-        'Then restart your agent so it picks up the new MCP server — restart Claude Code, reload the ' +
-        'window in Cursor, or hit Start in `.vscode/mcp.json` in VS Code.\n' +
-        'The tools only appear after that: your agent read its server list before Reticle existed, ' +
-        'and no slash command re-reads it (`/mcp` manages servers already loaded, so it cannot pick ' +
-        'up a new one). This is once per machine — Reticle is registered globally, so every later ' +
-        'project starts with the tools already there.\n' +
-        `${prove}\n` +
-        'Once it shows a session, ask your agent to drive a flow — that is the install finished.');
-}
 const SKIPPED_DETAIL = 'skipped — the dependency install above failed, and wiring the app to a package that is not ' +
     'installed stops it booting. Run that install, then re-run `reticle init`.';
-function report(plan, dryRun, failed, skipped, degraded, io, projectDir, agentRoot) {
+function report(plan, dryRun, failed, skipped, degraded, io, projectDir, agentRoot, 
+/** The project's own dev command, so the closing line names what a human would type. */
+devCommand) {
     io.print(dryRun ? 'reticle init (dry run, no files written)' : 'reticle init');
     // Every path below is printed RELATIVE, and until now nothing said what to. Reported from the
     // field as "[✓] Reticle config → .reticle.json" followed by the file not being there: the app was
@@ -612,7 +536,7 @@ function report(plan, dryRun, failed, skipped, degraded, io, projectDir, agentRo
             '"no browser session connected" until then. Everything else is already in place.');
         io.print('');
     }
-    io.print(restartHint(plan.framework, resolvedStatus(plan, MCP_TARGET, failed, skipped)));
+    io.print(restartHint(plan.framework, resolvedStatus(plan, MCP_TARGET, failed, skipped), devCommand));
     return { ok: !connectPending, applied, manual };
 }
 /**
@@ -834,12 +758,15 @@ function runInitSteps(options, io) {
     // Init is the flow a user experiences the wait of personally, and the fixture gate measures it at
     // 1–6s per app with no explanation of the spread. These three spans split that number into detect
     // (filesystem probing), plan (pure), and apply (writes + package-manager and CLI subprocesses).
-    const plan = spanSync('init.plan', {}, () => buildPlan(gatherPlanInput(options, io, pkgRaw)));
+    const planInput = gatherPlanInput(options, io, pkgRaw);
+    const plan = spanSync('init.plan', {}, () => buildPlan(planInput));
     const effects = options.dryRun
         ? { failed: new Set(), skipped: new Set(), degraded: new Map() }
         : spanSync('init.apply', { steps: plan.steps.length }, () => applyEffects(plan, io));
     const { failed, skipped, degraded } = effects;
-    const result = report(plan, options.dryRun, failed, skipped, degraded, io, options.cwd, agentRootOf(options));
+    // The project's own dev command, so the closing line names what a human would actually type.
+    const devCommand = devCommandFrom(pkgRaw, planInput.detection.packageManager);
+    const result = report(plan, options.dryRun, failed, skipped, degraded, io, options.cwd, agentRootOf(options), devCommand);
     // A dry run is a preview, not an outcome — reporting it would inflate both success and failure.
     if (options.dryRun)
         return result;

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>;