pi-chrome-search 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sh2nk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# pi-chrome-search
+Free, keyless web search for [pi](https://pi.dev) through **your own, visible Chrome** — same profile,
+same cookies, same IP — returning compact Markdown from Google, DuckDuckGo and Yandex with each engine's
+native AI summary (AI Overview, Search Assist, "Быстрый ответ Алисы AI"), plus page reading and image
+search. The window staying visible is intentional: you can watch the search and solve a captcha yourself.
+It is not an automation browser: raw CDP, one owned window, one work tab per engine, ≤2500 chars of
+output, every failure carrying a code, a stage and a hint. No paid search APIs, no keys, no captcha
+solving, no fingerprint spoofing, no headless mode.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Install
+Node ≥ 26 (native TypeScript, no build step), Chrome 136+ (tested on 157, Wayland), pi, a headed desktop
+session. Then `/web-doctor` inside pi must report a live CDP endpoint and `navigator.webdriver === false`.
+
+```bash
+npm install            # ws + typescript (dev); no build step
+pi install .           # register this checkout as a pi package
+pi -e ./src/index.ts   # …or load it for one throwaway session
+```
+
+## Enable CDP (once per Chrome session)
+Chrome 136+ ignores `--remote-debugging-port` for the default profile; debugging is enabled from inside
+the browser and needs an explicit **Allow** click.
+
+1. Open `chrome://inspect/#remote-debugging` in the Chrome window the agent should use.
+2. Tick **Discover network targets**, then click **Allow** on the prompt.
+3. Check the endpoint file (line 1 = port, line 2 = `/devtools/browser/<uuid>`):
+   `cat ~/.config/google-chrome/DevToolsActivePort`
+
+`curl 127.0.0.1:9222/json/version` may return nothing in this mode — expected; the file is authoritative.
+Discovery order: `PI_CHROME_CDP_WS` → `PI_CHROME_CDP_PORTS` → `DevToolsActivePort` → `cdp.ports`. The
+extension never launches, restarts or kills Chrome, never edits your profile, never closes foreign tabs.
+
+## Tools
+`web_search` is `direct`; everything else is `deferred` (tool search + `codemode`, not paid per prompt).
+All descriptions together stay under 900 characters.
+
+| Tool | Exposure | Arguments |
+|---|---|---|
+| `web_search` | direct | `q`; `n` 1–10 (5); `engines` `auto`\|id\|list; `summary` (true); `freshness` `d\|w\|m\|y`; `page`; `format` `md\|json` |
+| `web_read` | deferred | `url` (http/https); `offset`; `maxChars` (6000, ceiling 20000); `format` `md\|text` |
+| `image_search` | deferred | `q`; `n` ≤12 (4); `engine` `google\|yandex`; `attach` (≤4 thumbnails) |
+| `web_research` | deferred | `q`; `budget` `quick` (1 search + 2 reads) \| `normal` (2+4) \| `deep` (4+8) |
+| `web_doctor` | deferred | `probe` (true), `fix` (false: reconnect, close owned tabs, prune artifacts) |
+
+Output is capped at 2500 chars (summary ≤1200, snippets ≤140). The AI block has three states: `ai:yes`
+only for ≥200 chars of prose, `ai:lead` (block present, no answer — never rendered as one), `ai:no`.
+
+## Configuration
+`~/.pi/agent/web-search.json` (or `$PI_CODING_AGENT_DIR/web-search.json`), optional and strict: an
+unknown key is `E_CONFIG`. All keys: [`docs/config.md`](docs/config.md). The six that matter most:
+`engines.google.enabled` (`true`, per-engine switch) · `search.n` (`5`, ≤`search.nMax` 10) ·
+`search.aiWaitMs` (`6000`, bounded AI-block wait) · `read.maxCharsCeiling` (`20000`) ·
+`window.follow` (`"work"`, which tab is raised during a stage) · `reflex.pageGate` (`true`,
+source-quality gate in `web_research`, rules floor in `web_read`).
+
+Env overrides: `PI_CHROME_CDP_WS`, `PI_CHROME_CDP_PORTS`, `PI_CHROME_SEARCH_PROFILE`,
+`PI_CHROME_SEARCH_DEBUG`, `PI_CODING_AGENT_DIR`. System 1 triage stays off (`reflex.enabled: false`):
+the benchmark showed no honest token win.
+
+## When it fails
+| Code | Action |
+|---|---|
+| `E_CDP_UNAVAILABLE` | Open `chrome://inspect/#remote-debugging`, tick **Discover network targets**, click **Allow**; or set `PI_CHROME_CDP_WS` |
+| `E_CDP_AWAITING_ALLOW` | The prompt is waiting; click it — the call resumes by itself (`cdp.attachWaitMs`, 60 s) |
+| `E_WALL` | A captcha/consent page: solve it in the visible window, then retry. Never automated |
+| `E_BUSY` | Another pi session holds `~/.pi/agent/web-search.lock`: close it or wait for the heartbeat |
+| `E_PARSE` | A selector canary failed: open the artifact dir, compare `page.txt` with `docs/engines.md` |
+
+All 18 codes with hints: [`docs/errors.md`](docs/errors.md). `/web-doctor` (or
+`node src/cli/doctor.ts --json`) is the first stop; `--fix` reconnects, closes only owned tabs and prunes
+artifacts under `~/.pi/agent/web-search/`.
+
+## Security and ToS
+Your session, your cookies: searches and reads happen in your browser as you. `web_read` can open pages
+you are logged into but never exfiltrates content, and it refuses loopback/private/`file:`/`data:` URLs
+(re-checked on redirect). No telemetry; artifacts are sanitized and git-ignored. CDP is powerful — any
+local process that reaches the debugging port can drive the browser; it binds loopback only and you
+enable it explicitly. The optional page gate sends only URL/title/snippet of ≤10 sources (never page
+text) to your configured classifier; `reflex.localOnly: true` keeps it local.
+
+Google and Yandex prohibit automated access in their terms: this project does not claim compliance and
+must not be run as a service. If an engine shows a captcha, solve it in the window or stop.
+
+## Development
+`npm run lint` (typecheck + audit) · `npm test` (offline contract suite) · `npm run test:live` (opt-in,
+one query per engine, no retries, `PI_CHROME_LIVE=1`). Decisions: [`docs/architecture.md`](docs/architecture.md)
+· selectors: [`docs/engines.md`](docs/engines.md). Never launch a browser from tests; never loop probes.
+
+## License
+MIT — see [`LICENSE`](LICENSE).

package/assets/anchor.html

@@ -0,0 +1,165 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'">
+<title>pi-chrome-search — anchor</title>
+<!--
+  P10-A: the anchor control panel.
+
+  A static `file://` asset. The connector paints it with `Runtime.evaluate`, so
+  this document has no network of its own: the CSP above forbids every fetch,
+  there is no cookie access and no history. `render(state)` uses textContent
+  only, never innerHTML, so a query cannot inject markup.
+
+  Keep this file dependency-free: it must render in a browser that has no
+  internet access and no extension context.
+-->
+<style>
+  :root {
+    color-scheme: light dark;
+    --bg: #0f1115; --panel: #171a21; --line: #262b36; --fg: #e6e9ef;
+    --dim: #8b93a3; --accent: #6ea8fe; --ok: #4ade80; --warn: #fbbf24; --bad: #f87171;
+  }
+  @media (prefers-color-scheme: light) {
+    :root { --bg: #f5f6f8; --panel: #ffffff; --line: #e3e6ec; --fg: #111418;
+      --dim: #5b6472; --accent: #1d4ed8; --ok: #15803d; --warn: #b45309; --bad: #b91c1c; }
+  }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; }
+  body {
+    margin: 0; padding: 40px 32px; background: var(--bg); color: var(--fg);
+    font: 14px/1.45 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  }
+  main { max-width: 760px; margin: 0 auto; }
+  header { display: flex; align-items: baseline; justify-content: space-between; gap: 16px; }
+  h1 { font-size: 15px; letter-spacing: .08em; text-transform: uppercase; margin: 0; color: var(--dim); font-weight: 600; }
+  #session { font: 12px ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--dim); }
+  .card {
+    margin-top: 18px; padding: 18px 20px; background: var(--panel);
+    border: 1px solid var(--line); border-radius: 14px;
+  }
+  .row { display: flex; gap: 12px; align-items: baseline; flex-wrap: wrap; }
+  .label { font-size: 11px; letter-spacing: .09em; text-transform: uppercase; color: var(--dim); }
+  #stage {
+    display: inline-block; padding: 3px 10px; border-radius: 999px; font-size: 12px;
+    border: 1px solid var(--line); color: var(--accent);
+  }
+  #stage[data-state="error"] { color: var(--bad); }
+  #stage[data-state="done"] { color: var(--ok); }
+  #stage[data-state="pace"] { color: var(--warn); }
+  #engine { font-weight: 600; }
+  #query { margin: 10px 0 0; font-size: 20px; line-height: 1.3; word-break: break-word; }
+  #query.empty { color: var(--dim); font-size: 16px; }
+  #meta { margin-top: 14px; display: flex; gap: 22px; flex-wrap: wrap; color: var(--dim); font-size: 13px; }
+  #error { margin-top: 14px; padding: 10px 12px; border-radius: 10px; border: 1px solid var(--line); color: var(--bad); display: none; }
+  #error.show { display: block; }
+  #error .code { font: 12px ui-monospace, SFMono-Regular, Menlo, monospace; }
+  h2 { margin: 0 0 10px; font-size: 11px; letter-spacing: .09em; text-transform: uppercase; color: var(--dim); font-weight: 600; }
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  td { padding: 6px 0; border-top: 1px solid var(--line); }
+  tr:first-child td { border-top: 0; }
+  td.num { text-align: right; font-variant-numeric: tabular-nums; }
+  footer { margin-top: 18px; color: var(--dim); font-size: 12px; }
+</style>
+</head>
+<body>
+<main>
+  <header>
+    <h1>pi · chrome · search</h1>
+    <span id="session">session —</span>
+  </header>
+
+  <section class="card">
+    <div class="row">
+      <span id="stage" data-state="connect">connect</span>
+      <span id="engine">no engine</span>
+      <span id="pace"></span>
+    </div>
+    <p id="query" class="empty">waiting for the first search…</p>
+    <div id="error"><span class="code"></span> <span class="hint"></span></div>
+    <div id="meta"><span id="updated">—</span></div>
+  </section>
+
+  <section class="card">
+    <h2>Daily counters</h2>
+    <table>
+      <tbody>
+        <tr><td>google</td><td class="num" id="count-google">—</td></tr>
+        <tr><td>duckduckgo</td><td class="num" id="count-duckduckgo">—</td></tr>
+        <tr><td>yandex</td><td class="num" id="count-yandex">—</td></tr>
+      </tbody>
+    </table>
+  </section>
+
+  <footer>local page · no network · no cookies · this window is owned by the extension</footer>
+</main>
+<script>
+(function () {
+  "use strict";
+  var $ = function (id) { return document.getElementById(id); };
+  var counters = { google: $("count-google"), duckduckgo: $("count-duckduckgo"), yandex: $("count-yandex") };
+
+  function text(id, value) {
+    var node = $(id);
+    if (node) node.textContent = value;
+  }
+
+  function render(state) {
+    if (!state || typeof state !== "object") return;
+    var stage = typeof state.stage === "string" ? state.stage : "connect";
+    var badge = $("stage");
+    if (badge) {
+      badge.textContent = stage;
+      badge.setAttribute("data-state", stage);
+    }
+    text("engine", typeof state.engine === "string" ? state.engine : "no engine");
+    var query = typeof state.query === "string" ? state.query : "";
+    var q = $("query");
+    if (q) {
+      q.textContent = query || "waiting for the first search…";
+      q.className = query ? "" : "empty";
+    }
+    text("session", "session " + (typeof state.sessionId === "string" ? state.sessionId.slice(0, 8) : "—"));
+    var pace = Array.isArray(state.pace) && state.pace.length === 2
+      ? "pace " + (state.pace[0] / 1000).toFixed(1) + "–" + (state.pace[1] / 1000).toFixed(1) + " s"
+      : "";
+    text("pace", pace);
+
+    var list = Array.isArray(state.counters) ? state.counters : [];
+    var seen = {};
+    for (var i = 0; i < list.length; i += 1) {
+      var entry = list[i];
+      if (!entry || typeof entry.engine !== "string") continue;
+      var cell = counters[entry.engine];
+      if (!cell) continue;
+      seen[entry.engine] = true;
+      cell.textContent = String(entry.today) + " / " + String(entry.cap);
+    }
+    for (var name in counters) {
+      if (!seen[name] && counters[name]) counters[name].textContent = "—";
+    }
+
+    var box = $("error");
+    if (box) {
+      var error = state.error;
+      if (error && typeof error.code === "string") {
+        box.className = "show";
+        box.querySelector(".code").textContent = error.code;
+        box.querySelector(".hint").textContent = typeof error.hint === "string" ? error.hint : "";
+      } else {
+        box.className = "";
+        box.querySelector(".code").textContent = "";
+        box.querySelector(".hint").textContent = "";
+      }
+    }
+    text("updated", typeof state.updatedAt === "string" ? "updated " + state.updatedAt.replace("T", " ").replace("Z", " UTC") : "—");
+  }
+
+  window.__wcsPanel = { render: render };
+  window.__wcsPanelReady = true;
+})();
+</script>
+</body>
+</html>

package/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Package entry point.
+ *
+ * pi names a locally installed extension by the path of its entry file, not by `package.json#name`:
+ * an entry at `src/index.ts` loses the trailing `index.ts` and the Extensions panel shows `src`.
+ * Declaring the entry here keeps the implementation in `src/` and makes the label the package
+ * directory (`pi-chrome-search`). `src/index.ts` stays the real module and remains loadable with
+ * `pi -e ./src/index.ts`.
+ */
+
+export { default } from "./src/index.ts";
+export * from "./src/index.ts";

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "pi-chrome-search",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Free, keyless web search through the user's own visible Chrome (Google, DuckDuckGo, Yandex) for pi",
+  "type": "module",
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit && node scripts/audit.mjs",
+    "test": "node --test --test-timeout=15000 \"tests/unit/**/*.test.ts\"",
+    "test:live": "PI_CHROME_LIVE=1 node --test \"tests/live/**/*.test.ts\"",
+    "audit": "node scripts/audit.mjs",
+    "release": "node scripts/release.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.5.0",
+    "@types/node": "^24.0.0",
+    "@types/ws": "^8.5.12",
+    "linkedom": "^0.18.15",
+    "typebox": "^1.3.0",
+    "typescript": "^5.9.0"
+  },
+  "keywords": [
+    "pi-package",
+    "chrome",
+    "cdp",
+    "web-search",
+    "google",
+    "duckduckgo",
+    "yandex"
+  ],
+  "files": [
+    "index.ts",
+    "src",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sh2nk/pi-chrome-search.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sh2nk/pi-chrome-search/issues"
+  },
+  "homepage": "https://github.com/sh2nk/pi-chrome-search#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/cdp/ai-wait.ts

@@ -0,0 +1,148 @@
+/**
+ * Streaming-summary wait (PLAN-v2 P8-A, gates V8.1–V8.5).
+ *
+ * The bug this module exists for: the engine's SERP shell settles while the AI
+ * block is still streaming (or not rendered yet), extraction runs, and a
+ * labelled-but-empty block was shipped as `ai:yes`. The fix is to *wait for
+ * prose*, bounded, and to report what was actually seen:
+ *
+ *  - the wait ends the moment the probe reports `state: "answer"` with at least
+ *    `minChars` characters, so a page that already has the answer pays one probe;
+ *  - a block that is present but not an answer keeps the wait alive until the
+ *    deadline (it may still turn into prose);
+ *  - a page with no AI block at all stops after `noneGraceMs` (default 1.4 s)
+ *    instead of burning the whole deadline. Without that grace a slow Overview
+ *    would never be waited for; without the grace *limit* every ordinary
+ *    summary-less search would pay six seconds (V8.4 caps the added latency at
+ *    1.5 s).
+ *
+ * Nothing here sleeps for a fixed amount, nothing retries a navigation, and the
+ * clock/rng/deadline seams are the same ones `waitForMarker` uses
+ * (`cdp/humanize.ts`), so tests advance virtual time.
+ */
+
+import type { CdpPage } from "./types.ts";
+import type { AiProbe, AiState, EngineAi, EngineId } from "../engines/types.ts";
+import { AI_ANSWER_MIN_CHARS } from "../engines/types.ts";
+import type { Clock } from "../runtime/types.ts";
+import { systemClock } from "../runtime/clock.ts";
+import { asFailure, jitteredPollMs, normalizeDeadline, normalizePoll, throwIfAborted } from "./humanize.ts";
+
+/** Long enough for a streaming Overview, short enough to stay under V8.4. */
+export const DEFAULT_AI_WAIT_MS = 6_000;
+/**
+ * How long a page with *no* AI block is watched before giving up. Kept below the
+ * V8.4 ceiling (1.5 s) on purpose: probe round-trips and the jittered poll land
+ * on top of the grace, and a budget that can only be met by measuring the clock
+ * is not a budget.
+ */
+export const DEFAULT_NONE_GRACE_MS = 1_400;
+const DEFAULT_POLL_MS = 150;
+
+/** Readiness answer of the wait. `timedOut` means "the deadline/grace ran out first". */
+export interface AiWaitResult {
+  /** Best state observed; never downgraded by a later empty poll. */
+  state: AiState;
+  /** Characters of answer prose in the best observation. */
+  chars: number;
+  /** Clock time spent in the wait (0 when the first probe was already an answer). */
+  waitMs: number;
+  /** True when the wait ended without an answer. */
+  timedOut: boolean;
+  /** Number of probes executed (evidence for the P8 latency table). */
+  polls: number;
+}
+
+export interface WaitForAiOptions {
+  /** Answer width required to stop early; default `AI_ANSWER_MIN_CHARS` (200). */
+  minChars?: number;
+  /** Overall budget; default 6000 ms, `0` means "probe once and do not wait". */
+  deadlineMs?: number;
+  /** How long `none` is tolerated before the wait gives up; default 1500 ms. */
+  noneGraceMs?: number;
+  pollMs?: number;
+  rng?: () => number;
+  clock?: Clock;
+  signal?: AbortSignal;
+  engine?: EngineId;
+}
+
+/**
+ * A probe result crosses a boundary we do not own (it is produced by an
+ * adapter). Anything malformed is treated as "nothing seen yet" rather than as
+ * an answer: guessing an answer is the failure mode this phase forbids.
+ */
+function normalizeProbe(value: unknown): AiProbe {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { state: "none", chars: 0 };
+  }
+  const record = value as { state?: unknown; chars?: unknown };
+  const chars =
+    typeof record.chars === "number" && Number.isFinite(record.chars) && record.chars > 0
+      ? Math.floor(record.chars)
+      : 0;
+  const state = record.state === "answer" || record.state === "lead" ? record.state : "none";
+  // An "answer" with no measured prose is a contradiction; keep the state but
+  // report zero chars, and the length gate below will refuse to stop on it.
+  return { state, chars };
+}
+
+/**
+ * Poll the adapter's AI probe until it reports a full answer or the budget runs
+ * out. A probe failure is *not* swallowed: a torn socket during the wait is the
+ * same failure it would be one millisecond later in `extract`, and pretending
+ * the page is simply summary-less would hide a disconnect behind `ai:no`.
+ */
+export async function waitForAi(
+  page: CdpPage,
+  ai: EngineAi,
+  options: WaitForAiOptions = {},
+): Promise<AiWaitResult> {
+  const clock = options.clock ?? systemClock;
+  const rng = options.rng ?? Math.random;
+  const deadlineMs = normalizeDeadline(options.deadlineMs ?? DEFAULT_AI_WAIT_MS);
+  const noneGraceMs = Math.max(
+    0,
+    Math.min(deadlineMs, Math.floor(options.noneGraceMs ?? DEFAULT_NONE_GRACE_MS)),
+  );
+  const pollMs = normalizePoll(options.pollMs ?? DEFAULT_POLL_MS);
+  const minChars = Math.max(
+    1,
+    Math.floor(options.minChars ?? AI_ANSWER_MIN_CHARS),
+  );
+  const start = clock.now();
+
+  let best: AiProbe = { state: "none", chars: 0 };
+  let polls = 0;
+  const rank = (state: AiState): number => (state === "answer" ? 2 : state === "lead" ? 1 : 0);
+
+  try {
+    for (;;) {
+      throwIfAborted(options.signal, "settle", options.engine);
+      const observed = normalizeProbe(await ai.probe(page));
+      polls += 1;
+      // A later empty poll must not erase a block that was already seen: the AI
+      // block can be re-rendered mid-stream. Keep the strongest observation.
+      if (rank(observed.state) >= rank(best.state)) best = observed;
+
+      const elapsed = Math.max(0, clock.now() - start);
+      if (observed.state === "answer" && observed.chars >= minChars) {
+        return { state: "answer", chars: observed.chars, waitMs: elapsed, timedOut: false, polls };
+      }
+      if (elapsed >= deadlineMs) {
+        return { state: best.state, chars: best.chars, waitMs: elapsed, timedOut: true, polls };
+      }
+      if (best.state === "none" && elapsed >= noneGraceMs) {
+        return { state: "none", chars: 0, waitMs: elapsed, timedOut: true, polls };
+      }
+      // While nothing has been seen, never sleep past the grace: that budget is a
+      // hard ceiling on the latency a summary-less page may cost (V8.4), and an
+      // unclamped jittered poll would overshoot it by up to 25%.
+      const remainingGrace = best.state === "none" ? noneGraceMs - elapsed : Number.POSITIVE_INFINITY;
+      const delay = Math.min(jitteredPollMs(pollMs, rng), remainingGrace);
+      await clock.sleep(delay, options.signal);
+    }
+  } catch (error) {
+    throw asFailure(error, "settle", options.engine);
+  }
+}