@ultimat3/scraping 23.0.0 → 24.0.0

package/src/driver-cdp.ts

@@ -23,6 +23,7 @@ import { isScrapeError } from './errors';
 import type { ScrapeEventFields } from './events';
 import { errorCode } from './failures';
 import { httpOverFetch } from './http';
+import { launchArgs } from './launch-args';
 import { pageOverTarget } from './page-over-target';
 import type { ScrapeTarget } from './target';
 import { endpointLabel, hasCredentials, splitCredentials, urlSecretValues } from './url-secrets';
@@ -38,7 +39,10 @@ export interface BrowserOptions {
    * `egress(input)` — `SessionInit.proxy` — wins over it, per session.
    */
   readonly proxy?: string | undefined;
-  /** Extra launch/connect arguments, passed through untouched. */
+  /**
+   * Extra launch/connect options, passed through — except `args`, which `localBrowser()` puts
+   * BEFORE the exit's `--proxy-server` and screens for a second route (`launch-args.ts`).
+   */
   readonly options?: Record<string, unknown> | undefined;
   /** How long a graceful `close()` may take before the process is killed. */
   readonly graceMs?: number | undefined;
@@ -267,6 +271,11 @@ export function localBrowser(options: LocalBrowserOptions): ScrapeDriver {
       // The userinfo never reaches the argument list: Chrome ignores it there, and an argument is
       // readable by every process on the box. `opened()` answers the challenge instead.
       const proxyArg = proxy !== undefined && authenticate ? splitCredentials(proxy).bare : proxy;
+      // The caller's args FIRST and the exit appended after them, never a spread that lets one
+      // replace the other: `{ args: ['--no-sandbox'] }` — every container deploy's — used to
+      // overwrite the proxy flag, and the browser dialled direct while the session reported the exit.
+      const { args: callerArgs, ...passthrough } = options.options ?? {};
+      const args = launchArgs(callerArgs, proxyArg);
       let browser: CdpBrowserLike;
       try {
         browser = await launch.call(options.launcher, {
@@ -275,8 +284,8 @@ export function localBrowser(options: LocalBrowserOptions): ScrapeDriver {
             ? {}
             : { executablePath: options.executablePath }),
           ...(options.profileDir === undefined ? {} : { userDataDir: options.profileDir }),
-          ...(proxyArg === undefined ? {} : { args: [`--proxy-server=${proxyArg}`] }),
-          ...options.options,
+          ...passthrough,
+          ...(args === undefined ? {} : { args }),
         });
       } catch (thrown) {
         throw browserUnreachable(CDP_DRIVER, thrown);

package/src/driver.ts

@@ -102,7 +102,7 @@ export interface ScrapeDriver {
 
 let ambient: ScrapeDriver | undefined;
 
-/** Set once at boot from `app.config.ts`. A scrape's own `driver:` overrides it per definition. */
+/** Set once by the app at boot — no config key names it. A scrape's own `driver:` overrides it. */
 export function setScrapeDriver(driver: ScrapeDriver): void {
   ambient = driver;
 }

package/src/error-throws-session.ts

@@ -72,3 +72,40 @@ export const promptAnswerInvalid = (input: {
     fix: 'publish the answer with answerPrompt({ runId, index, answer }) and never publishEvent() by hand — the answer is sealed for this one prompt, so a plain payload is refused rather than typed into the site',
     meta: { scrape: input.scrape, label: input.label, event: input.event },
   });
+
+/** Lists every `localBrowser(` call site and every proxy switch in the app — where the edit goes. */
+export const LAUNCH_ARGS_FIX =
+  "grep -rnE --include='*.ts' -e 'localBrowser\\(' -e '--(no-)?proxy-' .";
+
+/**
+ * The caller's launch args set the exit themselves, or are not a list a launcher can take. The
+ * switch NAME only, never its value: `--proxy-server=http://user:pass@…` is a credential a caller
+ * may well have written, and this cause is written to the dead-letter row.
+ */
+
+export const launchArgsInvalid = (reason: string, route: boolean): ScrapeError =>
+  new ScrapeError({
+    code: 'X_SCRAPE_LAUNCH_ARGS_INVALID',
+    cause: `localBrowser({ options: { args } }) ${reason} — ${
+      route
+        ? 'delete the switch from args and pass the exit as localBrowser({ proxy }) or scrape({ egress })'
+        : "pass args as a list of strings, e.g. options: { args: ['--no-sandbox'] }"
+    }`,
+    // One command, the same for both shapes: it lists every call site and every proxy switch.
+    fix: LAUNCH_ARGS_FIX,
+    meta: { reason },
+  });
+
+/**
+ * A name a WILDCARD admitted, resolved to an address inside the network. The address CLASS and
+ * never the address: the cause reaches the dead-letter row, and the hostname is enough to act on.
+ */
+export const hostResolvesInward = (url: string, hostname: string, kind: string): ScrapeError =>
+  new ScrapeError({
+    code: 'X_SCRAPE_HOST_BLOCKED',
+    cause: `${url} is admitted by a wildcard in allowHosts, and ${hostname} resolves to ${
+      kind === 'unresolvable' ? 'no address' : `a ${kind} address`
+    } — a wildcard admits public addresses only`,
+    fix: `name the host exactly on the scrape() definition — allowHosts: [${JSON.stringify(hostname)}] — if it is meant to be reached inside your network`,
+    meta: { url, host: hostname, addressClass: kind },
+  });

package/src/error-throws.ts

@@ -8,7 +8,6 @@ import {
   isRetryableStatus,
   renderFixShellArg,
   renderThrowable,
-  UltimateError,
 } from '@ultimat3/core';
 import type { CaptureClip } from './capture-clip';
 import { ScrapeError } from './errors';
@@ -303,7 +302,11 @@ export const fixtureMissing = (url: string, dir: string): ScrapeError =>
 export const fixtureStale = (url: string, ageMs: number, maxAgeMs: number): ScrapeError =>
   new ScrapeError({
     code: 'X_SCRAPE_FIXTURE_STALE',
-    cause: `the recording of ${url} is ${String(Math.round(ageMs / 86_400_000))} days old and fixtureBrowser declares maxAge ${String(Math.round(maxAgeMs / 86_400_000))} days`,
+    cause: `the recording of ${url} ${
+      Number.isFinite(ageMs)
+        ? `is ${String(Math.round(ageMs / 86_400_000))} days old`
+        : 'has a recordedAt that is not a date'
+    } and fixtureBrowser declares maxAge ${String(Math.round(maxAgeMs / 86_400_000))} days`,
     fix: 're-record the fixture directory, or raise maxAge on fixtureBrowser({ maxAge }) with the reason an old recording still proves something',
     meta: { url, ageMs, maxAgeMs },
   });
@@ -426,19 +429,6 @@ export const blocked = (scrape: string, url: string, detail: string): ScrapeErro
     meta: { scrape, url },
   });
 
-/**
- * The honest stub, in the shape `packages/jobs/src/driver-redis.ts` uses: correct types so an app
- * can be written against the seam, and one labelled throw so nobody discovers the gap from a
- * silently-skipped recovery.
- */
-export const scrapeNotImplemented = (feature: string, fix: string): UltimateError =>
-  new UltimateError({
-    code: 'X_NOT_IMPLEMENTED',
-    cause: `${feature} is declared and not implemented in @ultimat3/scraping`,
-    fix,
-    meta: { feature },
-  });
-
 /**
  * The crop rectangle's three refusals, one code. Each is a caller's DECLARATION being impossible
  * rather than a site behaving badly, so each names the edit that fixes it — and the alternative in

package/src/errors.ts

@@ -41,11 +41,12 @@ export const SCRAPE_OWNED_ERROR_CODES = [
   'X_SCRAPE_KEY_INVALID',
   'X_SCRAPE_EGRESS_UNSUPPORTED',
   'X_SCRAPE_EGRESS_IN_PAYLOAD',
+  'X_SCRAPE_LAUNCH_ARGS_INVALID',
 ] as const;
 
 /**
- * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s and `recover.ts` throws it for the agent seam, the
- * way `packages/jobs/src/driver-redis.ts` does for its stub. `X_ENV_MISSING` is core's too: a
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s: `recover.ts`, `cdp-target.ts` and `html-target.ts`
+ * throw it as core's own `NotImplementedError`, never a constructor of this package's. `X_ENV_MISSING` is core's too: a
  * declared secret with no value in the environment is a missing environment variable, not a
  * scraping concept needing its own code. No title is kept here for either — one code, one owner,
  * or the two copies drift.
@@ -95,6 +96,8 @@ export const SCRAPE_ERROR_TITLES: Readonly<Record<ScrapeOwnedErrorCode, string>>
   X_SCRAPE_KEY_INVALID: 'the key chord names no key a browser can press',
   X_SCRAPE_EGRESS_UNSUPPORTED: 'this driver cannot give the session the exit the run asked for',
   X_SCRAPE_EGRESS_IN_PAYLOAD: 'the run exit carries a credential that is also in the job payload',
+  X_SCRAPE_LAUNCH_ARGS_INVALID:
+    'the launch options carry arguments this driver cannot hand the browser',
 };
 
 // One unconditional call, so a second package claiming one of these codes throws
@@ -202,6 +205,9 @@ export const SCRAPE_ERROR_RETRY = {
   X_SCRAPE_EGRESS_UNSUPPORTED: 'terminal',
   // The payload is the row: every remaining attempt reads the same credential out of it.
   X_SCRAPE_EGRESS_IN_PAYLOAD: 'terminal',
+  // The args are the deploy's own literal: attempt 2 launches with the same list and is refused
+  // the same way. Launching anyway is the retry that "works" from the worker's own address.
+  X_SCRAPE_LAUNCH_ARGS_INVALID: 'terminal',
 } as const satisfies Readonly<Record<ScrapeOwnedErrorCode, 'retryable' | 'terminal'>>;
 
 registerErrorRetry(SCRAPE_ERROR_RETRY);

package/src/expect.ts

@@ -3,7 +3,7 @@
 // where the data went. `expect` turns that into a red run: a yield under `minRows`, or under
 // `maxDrop` of what this scrape normally returns, throws.
 
-import { finiteCount, finiteOption } from '@ultimat3/core';
+import { assert, finiteCount, finiteOption } from '@ultimat3/core';
 import { yieldCollapsed } from './error-throws';
 import type { ScrapeError } from './errors';
 
@@ -57,6 +57,23 @@ export interface YieldCheck {
   readonly history: readonly number[];
 }
 
+/**
+ * `maxDrop`, screened: finite, then a FRACTION in `[0, 1)`. `1` and anything above it — `50`, the
+ * percent habit — make `baseline * (1 - maxDrop)` zero or negative, so no yield is ever under it
+ * and the alarm is silent forever; a negative one fires on a run that matched its baseline. Asked
+ * by the rule and by `scrape()`, where the number is written.
+ */
+export function maxDropFraction(scrape: string, value: number): number {
+  const fraction = finiteOption('the scrape expect', 'maxDrop', value);
+  assert(
+    fraction >= 0 && fraction < 1,
+    `scrape "${scrape}" declares expect.maxDrop: ${String(fraction)}, and maxDrop is a fraction of the trailing median from 0 up to but not including 1 — at 1 or above no yield is ever under the line and the alarm can never fire; write it as a fraction, expect: { maxDrop: 0.5 } allows half`,
+    // Lists every declaration outside [0, 1) — static, so no declared value reaches a shell.
+    "grep -rnE --include='*.ts' 'maxDrop: *(-|[1-9]|1\\.)' .",
+  );
+  return fraction;
+}
+
 /**
  * The whole rule, pure: the error this yield earns, or `undefined`. Pure so a test can hand it
  * fifty histories without a queue, a browser or a clock.
@@ -69,8 +86,8 @@ export function yieldProblem(check: YieldCheck): ScrapeError | undefined {
   // instead, and an alarm that always fires is an alarm somebody turns off.
   //
   // `minRows: 0` is legal and stays legal: this file asks an author whose answer is legitimately
-  // sometimes zero to declare exactly that. `maxDrop` is a FRACTION of a median, so `finiteOption`
-  // and not `finiteCount` — `0.5` is the documented value.
+  // sometimes zero to declare exactly that. `maxDrop` is a FRACTION of a median, so not
+  // `finiteCount` — `0.5` is the documented value (`maxDropFraction`).
   const minRows =
     check.expect.minRows === undefined
       ? undefined
@@ -78,7 +95,7 @@ export function yieldProblem(check: YieldCheck): ScrapeError | undefined {
   const maxDrop =
     check.expect.maxDrop === undefined
       ? undefined
-      : finiteOption('the scrape expect', 'maxDrop', check.expect.maxDrop);
+      : maxDropFraction(check.scrape, check.expect.maxDrop);
   if (minRows !== undefined && check.rows < minRows) {
     return yieldCollapsed({ scrape: check.scrape, rows: check.rows, reason: 'min-rows', minRows });
   }

package/src/html-target.ts

@@ -5,16 +5,11 @@
 // through to the network would make a green offline suite that is secretly hitting production —
 // the exact failure an offline driver exists to prevent.
 
+import { NotImplementedError } from '@ultimat3/core';
 import type { CaptureClip } from './capture-clip';
 import type { ScrapeClock } from './clock';
 import type { ColorScheme } from './color-scheme';
-import {
-  browserUnreachable,
-  downloadTimeout,
-  fixtureMissing,
-  fixtureStale,
-  scrapeNotImplemented,
-} from './error-throws';
+import { browserUnreachable, downloadTimeout, fixtureMissing, fixtureStale } from './error-throws';
 import { queryHtml } from './html-query';
 import { markupRequests } from './html-requests';
 import type { InterceptRules } from './intercept';
@@ -358,10 +353,10 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
      * attribute would pass every test against the element a screen reader cannot reach.
      */
     async accessibility(_selector: string, _max: number): Promise<readonly AxNode[]> {
-      throw scrapeNotImplemented(
-        `accessibility() on the ${init.driver} driver`,
-        'run this assertion on localBrowser()/remoteBrowser(), whose accessibility() reads the tree the browser computed — an offline driver parses markup and computes no role',
-      );
+      throw new NotImplementedError({
+        cause: `accessibility() on the ${init.driver} driver is not implemented by this driver`,
+        fix: 'run this assertion on localBrowser()/remoteBrowser(), whose accessibility() reads the tree the browser computed — an offline driver parses markup and computes no role',
+      });
     },
     evaluate(expression: string): Promise<unknown> {
       live();
@@ -381,10 +376,10 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
     // `async`, so the refusal REJECTS: the method is typed `Promise<void>` and a synchronous
     // `throw` from one jumps straight over `page.offline(true).catch(…)` at every caller.
     async setOfflineMode(_enabled: boolean): Promise<void> {
-      throw scrapeNotImplemented(
-        `setOfflineMode() on the ${init.driver} driver`,
-        'run this assertion on localBrowser()/remoteBrowser(), whose setOfflineMode() reaches a real browser — an offline driver has no network to cut, so it cannot prove an offline behaviour',
-      );
+      throw new NotImplementedError({
+        cause: `setOfflineMode() on the ${init.driver} driver is not implemented by this driver`,
+        fix: 'run this assertion on localBrowser()/remoteBrowser(), whose setOfflineMode() reaches a real browser — an offline driver has no network to cut, so it cannot prove an offline behaviour',
+      });
     },
     /**
      * ACCEPTED and recorded, where `setOfflineMode` refuses — and the line between them is which

package/src/http-recorded.ts

@@ -64,7 +64,9 @@ export function recordedHttp(init: RecordedHttpInit): ScrapeHttp {
       if (found === undefined) throw fixtureMissing(`${method} ${url}`, init.source);
       if (init.maxAgeMs !== undefined && found.recordedAt !== undefined) {
         const age = init.clock.now().getTime() - new Date(found.recordedAt).getTime();
-        if (age > init.maxAgeMs) throw fixtureStale(`${method} ${url}`, age, init.maxAgeMs);
+        // `!(age <= limit)`, never `age > limit`: an unparseable `recordedAt` makes `age` NaN, and
+        // `NaN > limit` is false — a recording of unknown age replayed as fresh. `auth.ts` the same.
+        if (!(age <= init.maxAgeMs)) throw fixtureStale(`${method} ${url}`, age, init.maxAgeMs);
       }
       init.network.push({
         method,

package/src/http.ts

@@ -20,6 +20,8 @@ import type { RedirectHop } from './http-redirect';
 import { MAX_REDIRECT_HOPS, redirectHop } from './http-redirect';
 import type { InterceptRules } from './intercept';
 import { interceptVerdict } from './intercept';
+import type { DialTarget, HostResolve } from './pinned-host';
+import { dialTarget, resolveHost } from './pinned-host';
 import type { NetworkRing } from './rings';
 import type { RobotsGate } from './robots';
 import type { ScrapeSecrets } from './secrets';
@@ -43,6 +45,11 @@ export type ScrapeFetch = (input: string, init: ScrapeFetchInit) => Promise<Resp
 export interface ScrapeFetchInit extends RequestInit {
   /** The session's exit. A different exit IP mid-session is a different client to an anti-bot. */
   readonly proxy?: string | undefined;
+  /**
+   * The NAME a pinned connection proves (`pinned-host.ts`): the url names the approved address,
+   * and Bun's `fetch` verifies the certificate against this instead.
+   */
+  readonly tls?: { readonly serverName?: string | undefined } | undefined;
 }
 
 export interface HttpRequestInit {
@@ -114,6 +121,8 @@ export interface HttpTransportInit {
   /** The run's meter: one `httpRequest` per hop on the wire, with the body bytes read for it. */
   readonly usage?: UsageMeter | undefined;
   readonly fetch?: ScrapeFetch | undefined;
+  /** The resolver a wildcard-admitted name is checked and pinned with. Defaults to `Bun.dns`. */
+  readonly resolve?: HostResolve | undefined;
 }
 
 /**
@@ -196,6 +205,22 @@ const withoutCredentials = (headers: Readonly<Record<string, string>>): Record<s
     Object.entries(headers).filter(([name]) => !CROSS_ORIGIN_STRIPPED.has(name.toLowerCase())),
   );
 
+/**
+ * The request's headers from every source, LATER sources winning, keyed by the lower-cased name.
+ * HTTP names are case-insensitive and `Headers` APPENDS two spellings of one name: a caller's
+ * `User-Agent: Mine` beside the session's `user-agent` went out as `BrowserUA, Mine`, and a
+ * declared `Cookie` was joined to the jar's instead of replacing it.
+ */
+const composeHeaders = (
+  ...sources: readonly Readonly<Record<string, string>>[]
+): Record<string, string> => {
+  const out = new Map<string, string>();
+  for (const source of sources) {
+    for (const [name, value] of Object.entries(source)) out.set(name.toLowerCase(), value);
+  }
+  return Object.fromEntries(out);
+};
+
 /** Unparseable is not same-origin: a URL this package cannot read is one it cannot vouch for. */
 const sameOrigin = (left: string, right: string): boolean => {
   try {
@@ -251,12 +276,21 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
    * The three gates, in one place, so the initial URL and hop seven are screened by the same code
    * in the same order. A second copy for redirects is how the two drift.
    */
-  const screen = async (target: string): Promise<void> => {
+  const resolve = init.resolve ?? resolveHost;
+  const screen = async (target: string): Promise<DialTarget> => {
     if (interceptVerdict(target, 'fetch', init.rules) !== 'allow') {
       throw hostBlocked(target, init.rules.allowHosts);
     }
+    // Through a proxy the PROXY resolves the name, from its own network, so an answer from this
+    // box's resolver says nothing about where the request lands — and pinning would hand the
+    // proxy an address where it expects the name.
+    const dial =
+      init.proxy === undefined
+        ? await dialTarget(target, init.rules.allowHosts, resolve)
+        : { url: target };
     await init.robots?.assertAllowed(target);
     await init.pace?.(init.signal);
+    return dial;
   };
   return {
     async request(url: string, request: HttpRequestInit = {}): Promise<ScrapeResponse> {
@@ -284,7 +318,7 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
         1,
       );
       init.onActivity?.();
-      await screen(url);
+      let dial = await screen(url);
       const session = await init.session();
       // `AbortSignal.timeout` and NOT `clock.sleep`: this is a deadline handed to the platform's
       // own fetch, not a wait this package performs — and under a test clock a slept deadline
@@ -319,14 +353,17 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
           const declared = credentialsInScope
             ? request.headers
             : withoutCredentials(request.headers ?? {});
-          const response = await call(hop.url, {
+          const response = await call(dial.url, {
             method: hop.method,
-            headers: {
-              ...carried,
-              ...(session.userAgent === '' ? {} : { 'user-agent': session.userAgent }),
-              ...(cookies === undefined ? {} : { cookie: cookies }),
-              ...declared,
-            },
+            headers: composeHeaders(
+              carried,
+              session.userAgent === '' ? {} : { 'user-agent': session.userAgent },
+              cookies === undefined ? {} : { cookie: cookies },
+              declared ?? {},
+              // Last: a pinned request is reached AS the name that was screened, whatever was declared.
+              dial.host === undefined ? {} : { host: dial.host },
+            ),
+            ...(dial.serverName === undefined ? {} : { tls: { serverName: dial.serverName } }),
             ...(hop.body === undefined ? {} : { body: hop.body }),
             signal: AbortSignal.any(signals),
             // The whole point: the platform's own `follow` is what made the four lines above
@@ -360,7 +397,7 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
           await discardHopBody(response);
           if (followed >= MAX_REDIRECT_HOPS) throw redirectLoop(url, next.url, followed + 1);
           init.onActivity?.();
-          await screen(next.url);
+          dial = await screen(next.url);
           if (!sameOrigin(hop.url, next.url)) credentialsInScope = false;
           hop = next;
         }

package/src/index.ts

@@ -22,6 +22,8 @@ export type { CaptureClip, CaptureFraming } from './capture-clip';
 export { assertCaptureFraming } from './capture-clip';
 export type {
   CdpBrowserLike,
+  CdpBrowserSessionLike,
+  CdpBrowserTargetLike,
   CdpFrameLike,
   CdpKeyboardLike,
   CdpLauncherLike,
@@ -79,7 +81,6 @@ export {
   redirectLoop,
   remoteRequired,
   robotsDisallowed,
-  scrapeNotImplemented,
   scrapeTimeout,
   secretExposed,
   selectorMissing,
@@ -213,6 +214,7 @@ export type {
 export {
   memorySessionStore,
   parseSessionState,
+  recordVersion,
   SESSION_SEAL_PURPOSE,
   sessionDigest,
   sessionKeyFor,

package/src/launch-args.ts

@@ -0,0 +1,51 @@
+// The argument list a launched browser gets: the caller's own, then the exit. The exit is the
+// session's — the driver's `proxy` or the run's `egress` — so it is appended LAST and a caller
+// switch that would decide the route instead is refused rather than ranked.
+
+import { launchArgsInvalid } from './error-throws-session';
+
+/**
+ * Every switch Chrome reads a proxy decision from. Matched on the switch NAME, case-folded and
+ * with either prefix POSIX Chrome accepts (`--` and `-`), so a value that merely mentions a proxy
+ * (`--user-agent=proxy-server-test`) is not refused.
+ */
+const ROUTE_SWITCHES = new Set([
+  'proxy-server',
+  'proxy-bypass-list',
+  'proxy-pac-url',
+  'proxy-auto-detect',
+  'no-proxy-server',
+]);
+
+const switchName = (arg: string): string | undefined => {
+  const match = /^--?([^=]+)/.exec(arg);
+  return match?.[1]?.toLowerCase();
+};
+
+/**
+ * `undefined` when the launch carries no args at all — the launcher's own defaults stay untouched
+ * then. Refused with `X_SCRAPE_LAUNCH_ARGS_INVALID` before anything starts: a browser launched on a
+ * second route is a session that reports one exit and leaves the worker by another.
+ */
+export function launchArgs(
+  callerArgs: unknown,
+  proxyArg: string | undefined,
+): string[] | undefined {
+  if (callerArgs !== undefined) {
+    if (!Array.isArray(callerArgs) || !callerArgs.every((arg) => typeof arg === 'string')) {
+      throw launchArgsInvalid('is not an array of strings', false);
+    }
+    for (const arg of callerArgs as readonly string[]) {
+      const name = switchName(arg);
+      if (name !== undefined && ROUTE_SWITCHES.has(name)) {
+        throw launchArgsInvalid(
+          `sets --${name}, which decides the route this session leaves by`,
+          true,
+        );
+      }
+    }
+  }
+  const args = [...((callerArgs as readonly string[] | undefined) ?? [])];
+  if (proxyArg !== undefined) args.push(`--proxy-server=${proxyArg}`);
+  return args.length === 0 ? undefined : args;
+}

package/src/pinned-host.ts

@@ -0,0 +1,65 @@
+// The DNS half of `allowHosts`, for the two legs this package dials itself — the HTTP leg and the
+// robots read. Core's `hostDecision` is synchronous and judges NAMES: a wildcard never admits an
+// address literal inside the network, but `allowHosts: ['*']` still admits a hostname that
+// resolves inward. So a name admitted by a wildcard alone is resolved here, every address
+// classified by core's one classifier, and the connection PINNED to the approved address — the
+// shape `@ultimat3/jobs`' `webhook-target.ts` takes for a webhook.
+
+import type { HostRule } from '@ultimat3/core';
+import { classifyAddress, hostMatches } from '@ultimat3/core';
+import { hostResolvesInward } from './error-throws-session';
+
+/** Every address a hostname answers. Injected in tests: the network is sealed in this repo. */
+export type HostResolve = (hostname: string) => Promise<readonly string[]>;
+
+/** `Bun.dns.lookup` — the runtime's own resolver, every family, every address. */
+export const resolveHost: HostResolve = async (hostname) =>
+  (await Bun.dns.lookup(hostname)).map((entry) => entry.address);
+
+/** What the transport connects to: the URL to dial, and the name it proves when pinned. */
+export interface DialTarget {
+  readonly url: string;
+  /** The original `host[:port]`, sent as the `Host` header of a pinned request. */
+  readonly host?: string | undefined;
+  /** For `https:` — the certificate is verified against the NAME, not the address. */
+  readonly serverName?: string | undefined;
+}
+
+const isWildcard = (rule: HostRule): boolean => {
+  const cleaned = rule.trim();
+  return cleaned === '*' || cleaned.startsWith('*.');
+};
+
+/**
+ * The connection for `url`, which `interceptVerdict` has ALREADY allowed. Unchanged when an exact
+ * rule names the host — the app said that host, internal or not, in a line a reviewer can see —
+ * or when the host is an address literal, which core's floor already judged. Otherwise resolved:
+ * one address that is not public refuses the request (`X_SCRAPE_HOST_BLOCKED`), and the dial is
+ * pinned to the first approved address, so a name that answers public here and private to the
+ * socket (DNS rebinding) is never reached. A resolver failure propagates: nothing unscreened is
+ * dialled, and the same name would not have resolved for `fetch` either.
+ */
+export async function dialTarget(
+  url: string,
+  allowHosts: readonly HostRule[],
+  resolve: HostResolve,
+): Promise<DialTarget> {
+  const parsed = new URL(url);
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return { url };
+  const hostname = parsed.hostname.replace(/^\[|\]$/g, '');
+  if (classifyAddress(hostname) !== undefined) return { url };
+  if (allowHosts.some((rule) => !isWildcard(rule) && hostMatches(hostname, rule))) return { url };
+  const addresses = await resolve(hostname);
+  const inward = addresses.map((address) => classifyAddress(address) ?? 'unclassifiable');
+  const refused =
+    addresses.length === 0 ? 'unresolvable' : inward.find((kind) => kind !== 'public');
+  if (refused !== undefined) throw hostResolvesInward(url, hostname, refused);
+  const pinned = addresses[0] ?? hostname;
+  const target = new URL(parsed.href);
+  target.hostname = pinned.includes(':') ? `[${pinned}]` : pinned;
+  return {
+    url: target.href,
+    host: parsed.host,
+    ...(parsed.protocol === 'https:' ? { serverName: hostname } : {}),
+  };
+}

package/src/recover.ts

@@ -6,7 +6,8 @@
 // `X_NOT_IMPLEMENTED` today, in the shape `packages/jobs/src/driver-redis.ts` uses: correct types
 // so an app can be written against it, one labelled throw, no silent no-op.
 
-import { recoverRefused, scrapeNotImplemented } from './error-throws';
+import { NotImplementedError } from '@ultimat3/core';
+import { recoverRefused } from './error-throws';
 import type { ScrapePage } from './page';
 
 export interface RecoveryAttempt {
@@ -41,7 +42,7 @@ export async function runRecovery(recovery: Recovery, attempt: RecoveryAttempt):
     // The agent path lands with `@ultimat3/ai`'s `llm()` behind it: page HTML in, a selector out,
     // re-run once. Until it does, this throws rather than answering `false` — a recovery that
     // silently declines is indistinguishable from one that was never configured.
-    throw scrapeNotImplemented("recover: 'agent'", AGENT_FIX);
+    throw new NotImplementedError({ cause: "recover: 'agent' is not implemented", fix: AGENT_FIX });
   }
   const verdict: unknown = await recovery(attempt);
   if (typeof verdict !== 'boolean') {