@ait-co/devtools 0.1.136 → 0.1.138

package/dist/mcp/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { i as generateTotp, n as assertRelayAuthConfigured, r as buildRelayVerifyAuth } from "../totp-WY6l0ysP.js";
-import { t as loadRelaySecretReadOnly } from "../relay-secret-store-DhzAnnj-.js";
+import { t as loadRelaySecretReadOnly } from "../relay-secret-store-CQenfcSL.js";
 import { createRequire } from "node:module";
 import { accessSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { argv } from "node:process";
@@ -25,33 +25,44 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 //#endregion
 //#region src/in-app/gate.ts
 /**
-* The host suffix the Toss app uses to serve dogfood / private mini-apps.
-*
-* A `intoss-private://` (dogfood) entry maps to a host such as
-* `aitc-sdk-example.private-apps.tossmini.com`. A production `intoss://`
-* entry is served from `*.apps.tossmini.com` — the `.private-apps.` segment
-* is absent. Confirmed live over CDP for mini-app 31146; the exact production
-* host is to be re-confirmed once 31146 passes review (spec open question 2).
-*/
-const PRIVATE_APPS_HOST_SUFFIX = ".private-apps.tossmini.com";
-/**
 * The host suffix Cloudflare quick-tunnels serve from — the env 2 (PWA) entry.
 * See {@link isTrycloudflareHost} for why this host kind bypasses Layer B1.
 */
 const TRYCLOUDFLARE_HOST_SUFFIX = ".trycloudflare.com";
 /**
-* Returns whether `hostname` is a `*.private-apps.tossmini.com` subdomain —
-* the host the Toss app reserves for dogfood / private mini-app entries.
+* The parent host suffix for the whole Toss mini-app serving family.
 *
-* The match is an exact suffix check, not a substring `.includes()`: a
-* substring test would also accept an attacker-controlled host like
-* `private-apps.tossmini.com.evil.example`, which ends in `.example`, not in
-* `.tossmini.com`. Requiring the string to END with the suffix closes that.
-* The leading `.` in the suffix also forces a real subdomain label, so a
-* bare `private-apps.tossmini.com` (no mini-app subdomain) does not match.
+* The 3.0 runtime loader serves mini-app pages from tossmini.com hosts that
+* are NOT `*.private-apps.tossmini.com` (observed live 2026-07-08 on mini-app
+* 31146 with a 3.0-beta bundle: a 4-label host ending in `.tossmini.com`
+* whose middle label is not `private-apps`, with `_deploymentId` consumed by
+* the native loader and not propagated to the page URL — devtools#760).
+*
+* Under 3.0 the hostname therefore no longer distinguishes a dogfood
+* candidate from a production entry, so for these hosts Layer B is demoted
+* from a stage discriminator (#665) to a "Toss-owned host family" filter,
+* and the effective boundary moves to Layer C: explicit `debug=1`, a valid
+* `wss:` relay, and a MANDATORY `at=` TOTP code (see Layer C3 in
+* {@link evaluateDebugGate}). A production user's entry URL carries none of
+* those params, so an accidentally-shipped debug build stays dormant exactly
+* as #665 intended; what changes is that a deliberate operator holding the
+* TOTP secret can now attach on a 3.0-family host.
+*
+* The match is the same exact-suffix `endsWith` check as
+* {@link isPrivateAppsHost} — never a substring `.includes()`, which would
+* accept an attacker-controlled `x.tossmini.com.evil.example`. The leading
+* `.` forces at least one subdomain label, so a bare `tossmini.com` does not
+* match.
+*/
+const TOSSMINI_HOST_SUFFIX = ".tossmini.com";
+/**
+* Returns whether `hostname` is any `*.tossmini.com` subdomain — the host
+* family the Toss app serves mini-app pages from. Includes the 2.x
+* `*.private-apps.tossmini.com` dogfood hosts and the 3.0 unified serving
+* hosts (devtools#760).
 */
-function isPrivateAppsHost(hostname) {
-	return hostname.endsWith(PRIVATE_APPS_HOST_SUFFIX);
+function isTossminiHost(hostname) {
+	return hostname.endsWith(TOSSMINI_HOST_SUFFIX);
 }
 /**
 * The host suffix Cloudflare quick-tunnels use — the env 2 (PWA) entry.
@@ -98,18 +109,27 @@ function isLocalhostHost(hostname) {
 * known debug-allowed host. The debug surface is ONLY active on:
 *   - localhost / loopback (env 1 desktop dev)
 *   - *.trycloudflare.com (env 2 PWA tunnel)
-*   - *.private-apps.tossmini.com (env 3 dog-food)
-*
-* Any other host (including apps.tossmini.com — the former env 4 LIVE host)
-* is silently blocked. This is a positive allowlist — unlisted hosts never
-* had debug surface regardless, but this function makes it explicit and
-* auditable in a single place.
+*   - *.tossmini.com (env 3 dog-food — 2.x private-apps hosts AND the 3.0
+*     unified serving family, devtools#760)
+*
+* Any other host is silently blocked. This is a positive allowlist —
+* unlisted hosts never had debug surface regardless, but this function makes
+* it explicit and auditable in a single place.
+*
+* #760 note on the #665 boundary: the former env 4 LIVE host family
+* (`*.apps.tossmini.com`) now passes this coarse filter because the 3.0
+* loader serves dogfood candidates and production entries from the same
+* host family — the hostname alone can no longer separate them. The #665
+* invariant ("no naked attach on a production-family host") is preserved
+* one layer down: on tossmini hosts that are not `*.private-apps.*`, Layer
+* C3 makes the TOTP `at=` code MANDATORY, and production entry URLs carry
+* no debug/relay/at params at all.
 *
 * SECRET-HANDLING: the hostname value MUST NOT be logged or included in any
 * error reason string — only benign labels ('host not in allowlist') are safe.
 */
 function isDebugAllowedHost(hostname) {
-	return isLocalhostHost(hostname) || isTrycloudflareHost(hostname) || isPrivateAppsHost(hostname);
+	return isLocalhostHost(hostname) || isTrycloudflareHost(hostname) || isTossminiHost(hostname);
 }
 //#endregion
 //#region src/shared/parent-watcher.ts
@@ -211,6 +231,39 @@ function startMaxAgeWatchdog(onExpired, opts = {}) {
 	} };
 }
 //#endregion
+//#region src/test-runner/throttle.ts
+/**
+* Shared `APP_BRIDGE_THROTTLED` detection (devtools#767).
+*
+* 2026-07-10 real-device observation: the Toss app native side added a
+* per-method rate limit to the 2.x bridge — calling the SAME bridge method
+* twice within a short window rejects the second call immediately with a
+* 2.x native envelope (`{name, code, userInfo, moduleName, __isError}`) whose
+* `code` is `'APP_BRIDGE_THROTTLED'` and whose `message` reads
+* `"Too many app bridge calls from <method>."`. The 3.x bridge path is
+* unaffected (devtools#767 issue body, sdk-example#284 2026-07-10 comment).
+*
+* This module is the SINGLE source of the detection predicate. Today's only
+* consumer is `runtime.ts` (in-page, per-test retry loop) — a plain static
+* import; esbuild inlines this file into the same IIFE bundle (same
+* mechanism as `bridge-stub.ts`, see `bundle.ts#getPageSideModulePath`). It
+* is exported from this standalone, dependency-free module (rather than
+* defined inline in `runtime.ts`) so a Node-side consumer could import the
+* exact same predicate in future if whole-FILE throttle-aware retry is ever
+* added on top of the per-test retry `runtime.ts` already performs — no such
+* Node-side caller exists yet (whole-file retry today only triggers on an
+* `injectAndRunBundle`-level timeout/exception, a distinct failure mode from
+* a `RunReport` that completed normally but contains a THROTTLED-failed
+* test — see `relay-worker.ts`'s `EVALUATE_TIMEOUT_MARKER` gate).
+*
+* Browser-compatible, dependency-free (no Node APIs) — safe to import from
+* either side of the CDP boundary, mirroring `runtime.ts`'s own constraint.
+*/
+/** The native error code the Toss app bridge returns when rate-limited. */
+const THROTTLED_ERROR_CODE = "APP_BRIDGE_THROTTLED";
+/** The message substring the native envelope carries when rate-limited. */
+const THROTTLED_MESSAGE_SUBSTRING = "Too many app bridge calls";
+//#endregion
 //#region src/mcp/deeplink.ts
 /**
 * URL of the AITC Sandbox launcher PWA.
@@ -2024,7 +2077,7 @@ async function readMcpSdkVersion() {
 * some test environments that skip the build step).
 */
 function readDevtoolsVersion() {
-	return "0.1.136";
+	return "0.1.138";
 }
 /**
 * Derives the next recommended action from a completed diagnostics snapshot.
@@ -2617,7 +2670,7 @@ async function prepareAttach(deps, env, args, conn) {
 		const buildProjectRoot = typeof rawProjectRoot === "string" ? rawProjectRoot : void 0;
 		let tunnelHttpUrl = process.env.AIT_TUNNEL_BASE_URL?.trim() ?? "";
 		if (tunnelHttpUrl === "" && buildProjectRoot !== void 0) {
-			const { readRelayUrls } = await import("../relay-url-store-CwKT7i04.js");
+			const { readRelayUrls } = await import("../relay-url-store-DaY1QPes.js");
 			tunnelHttpUrl = (await readRelayUrls({ projectRoot: buildProjectRoot }))?.tunnelBaseUrl ?? "";
 		}
 		if (tunnelHttpUrl === "") return {
@@ -2694,10 +2747,12 @@ async function prepareAttach(deps, env, args, conn) {
 		tool: "start_attach",
 		msg: "no _deploymentId in scheme_url; matching on presence only"
 	});
+	const wssForMatch = tunnelForBuild.wssUrl;
+	const matchesRelay = (url) => url.includes(wssForMatch) || url.includes(encodeURIComponent(wssForMatch));
 	const isMatchingPage = (pages) => {
 		if (pages.length === 0) return false;
 		if (deploymentId === null) return true;
-		return pages.some((p) => p.url.includes(deploymentId));
+		return pages.some((p) => p.url.includes(deploymentId) || matchesRelay(p.url));
 	};
 	const buildTimeoutError = (baseText, timeoutSec, observed) => {
 		const observedUrls = observed.slice(0, 3).map((p) => p.url.slice(0, 80)).join(", ");
@@ -2956,8 +3011,43 @@ const PERMISSION_PROBE_MAP = {
 	contacts: "fetchContacts",
 	location: "getCurrentLocation"
 };
-/** Non-fatal bound for the permission preflight `Runtime.evaluate` round-trip. */
-const PERMISSION_PREFLIGHT_TIMEOUT_MS = 1e4;
+/**
+* Inter-probe spacing (ms) applied BEFORE every probe after the first
+* (devtools#767). The native per-method bridge rate limit observed
+* 2026-07-10 rejects a SECOND call to the same method within a short window
+* with `APP_BRIDGE_THROTTLED` — the permission preflight's un-paced burst
+* (6 probes fired back-to-back) was the FIRST trigger of that limiter in the
+* wild (only the first probe passed; the remaining 5 came back throttled →
+* `unavailable`, cascading into skipped `__AIT_PERMS__`-branching tests).
+* Sequential-with-spacing is cheap insurance even though each probe targets a
+* DIFFERENT method — the limiter's exact scope (per-method vs. a shared
+* bridge-wide window) was not reverse-engineered (explicitly out of scope,
+* devtools#767) so spacing every probe is the conservative choice.
+*/
+const PROBE_INTER_CALL_DELAY_MS = 250;
+/**
+* Backoff delays (ms) between retry attempts when a probe is throttled. Its
+* `.length` IS the max retry count (devtools#767: "최대 2회 재시도") — the
+* generated page-side expression below derives `attempt < backoff.length`
+* from this same array (via `backoffArray`), so there is a single source for
+* both the delay ladder and the retry count; no separate max-retries
+* constant is kept in this module (unlike `runtime.ts`'s `TEST_MAX_RETRIES`,
+* which IS consumed directly by a Node-side loop condition).
+*/
+const PROBE_RETRY_BACKOFF_MS = [500, 1e3];
+/**
+* Non-fatal bound for the permission preflight `Runtime.evaluate` round-trip
+* (devtools#767: raised from the pre-pacing 10s to cover the new sequential +
+* backoff time budget).
+*
+* Worst-case budget with 6 probes, each requiring the full retry ladder:
+*   - inter-probe spacing: only BEFORE probes 2‑6 (none before the first) =
+*     5 × {@link PROBE_INTER_CALL_DELAY_MS} = 1 250ms
+*   - per-probe backoff (both retries taken): 6 × (500 + 1000) = 9 000ms
+*   - probe round-trips themselves (headroom, not just the sleeps): ~4 500ms
+*   total ≈ 14 750ms, rounded up to a clean 20 000ms for headroom.
+*/
+const PERMISSION_PREFLIGHT_TIMEOUT_MS = 2e4;
 /**
 * Builds the `Runtime.evaluate` expression for the permission-state preflight
 * (devtools#739). Evaluated ONCE per relay session, before the first test
@@ -2972,6 +3062,29 @@ const PERMISSION_PREFLIGHT_TIMEOUT_MS = 1e4;
 * caller, and a single slow/broken permission must not fail the others (each
 * probe is awaited independently, not short-circuited).
 *
+* devtools#767: probes run SEQUENTIALLY (not a parallel burst) with a
+* {@link PROBE_INTER_CALL_DELAY_MS} gap before each probe after the first, and
+* a probe that comes back `APP_BRIDGE_THROTTLED` (native per-method bridge
+* rate limit) is retried up to {@link PROBE_RETRY_BACKOFF_MS}`.length` times
+* with the same {@link PROBE_RETRY_BACKOFF_MS} ladder before falling back to
+* `'unavailable'`.
+* The THROTTLED detection mirrors `throttle.ts#isThrottledError` inline (this
+* expression is raw JS text evaluated via CDP, not an esbuild-bundled module,
+* so it cannot statically `import` that helper) — kept in sync by checking
+* BOTH `e.code === 'APP_BRIDGE_THROTTLED'` and a message substring match, the
+* same two signals `isThrottledError` checks.
+*
+* devtools#767 acceptance criteria 2 ("3.x run duration은 유의미하게 늘지 않음,
+* pacing은 opt-in 또는 throttle-adaptive") requires this NOT be an unconditional
+* cost — `pace` (default `true`, matching the pre-existing sequential+spacing
+* behavior for 2.x/unknown cells) lets a 3.x caller skip BOTH the inter-probe
+* `sleep(250)` AND the retry backoff ladder, since `APP_BRIDGE_THROTTLED` is a
+* 2.x-bridge-only limiter (see `--pace`'s own doc in `cli.ts`: "3.x cells are
+* unaffected by that limiter"). When `pace` is `false`, probes still run
+* sequentially (never a parallel burst) but back-to-back with no added delay,
+* and a THROTTLED result resolves to `'unavailable'` immediately (no retry) —
+* this matches the 3.x runtime, which never emits `APP_BRIDGE_THROTTLED`.
+*
 * Tests (sdk-example#265) read `globalThis.__AIT_PERMS__` to branch
 * deterministically per permission state instead of blanket outcome-branching.
 *
@@ -2982,9 +3095,18 @@ const PERMISSION_PREFLIGHT_TIMEOUT_MS = 1e4;
 *
 * Pure function — no I/O, no CDP call. Callers pass the returned string to
 * `Runtime.evaluate`.
+*
+* @param pace - Defaults to `true` (today's sequential+spacing+backoff
+*   behavior). Pass `false` for a 3.x cell to skip the inter-probe delay and
+*   the THROTTLED retry ladder entirely.
 */
-function buildPermissionPreflightExpression() {
-	return `(async () => {  const probe = async (fnName) => {    try {      const fn = globalThis.__sdk && globalThis.__sdk[fnName];      if (!fn || typeof fn.getPermission !== 'function') return 'unavailable';      const status = await fn.getPermission();      if (status === 'allowed' || status === 'denied' || status === 'notDetermined') return status;      return 'unavailable';    } catch (e) {      return 'unavailable';    }  };  const result = {};${Object.entries(PERMISSION_PROBE_MAP).map(([key, fnName]) => `    result[${JSON.stringify(key)}] = await probe(${JSON.stringify(fnName)});`).join("\n")}\n  globalThis.__AIT_PERMS__ = result;  return JSON.stringify(result);})()`;
+function buildPermissionPreflightExpression(pace = true) {
+	const probeCalls = Object.keys(PERMISSION_PROBE_MAP).map((key, i) => {
+		const fnName = PERMISSION_PROBE_MAP[key];
+		return `${i === 0 || !pace ? "" : `    await sleep(${PROBE_INTER_CALL_DELAY_MS});\n`}    result[${JSON.stringify(key)}] = await probeWithRetry(${JSON.stringify(fnName)});`;
+	}).join("\n");
+	const backoffArray = pace ? `[${PROBE_RETRY_BACKOFF_MS.join(",")}]` : "[]";
+	return `(async () => {  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));  const isThrottled = (e) => {    if (!e) return false;    if (e.code === ${JSON.stringify(THROTTLED_ERROR_CODE)}) return true;    const msg = typeof e.message === 'string' ? e.message : '';    return msg.indexOf(${JSON.stringify(THROTTLED_MESSAGE_SUBSTRING)}) !== -1;  };  const probe = async (fnName) => {    const fn = globalThis.__sdk && globalThis.__sdk[fnName];    if (!fn || typeof fn.getPermission !== 'function') return { ok: true, value: 'unavailable' };    const status = await fn.getPermission();    if (status === 'allowed' || status === 'denied' || status === 'notDetermined') return { ok: true, value: status };    return { ok: true, value: 'unavailable' };  };  const backoff = ${backoffArray};  const probeWithRetry = async (fnName) => {    for (let attempt = 0; attempt <= backoff.length; attempt++) {      try {        const r = await probe(fnName);        return r.value;      } catch (e) {        if (isThrottled(e) && attempt < backoff.length) {          await sleep(backoff[attempt]);          continue;        }        return 'unavailable';      }    }    return 'unavailable';  };  const result = {};${probeCalls}\n  globalThis.__AIT_PERMS__ = result;  return JSON.stringify(result);})()`;
 }
 /**
 * Runs the permission-state preflight (devtools#739) via `Runtime.evaluate`
@@ -3003,13 +3125,19 @@ function buildPermissionPreflightExpression() {
 *
 * @param conn      - The live CDP connection (relay-attached page).
 * @param timeoutMs - Round-trip bound. Defaults to {@link PERMISSION_PREFLIGHT_TIMEOUT_MS}.
-*/
-async function runPermissionPreflight(conn, timeoutMs = PERMISSION_PREFLIGHT_TIMEOUT_MS) {
+* @param pace      - Forwarded to {@link buildPermissionPreflightExpression}.
+*   Defaults to `true` (today's sequential+spacing+backoff behavior, correct
+*   for 2.x/unknown cells). Callers that know the cell is 3.x should pass
+*   `false` — devtools#767 acceptance criteria 2 requires 3.x run duration not
+*   grow from this preflight, and 3.x never hits the 2.x-only
+*   `APP_BRIDGE_THROTTLED` limiter this pacing exists to dodge.
+*/
+async function runPermissionPreflight(conn, timeoutMs = PERMISSION_PREFLIGHT_TIMEOUT_MS, pace = true) {
 	const TIMEOUT_SENTINEL = Symbol("permission-preflight-timeout");
 	const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs));
 	try {
 		const evalPromise = conn.send("Runtime.evaluate", {
-			expression: buildPermissionPreflightExpression(),
+			expression: buildPermissionPreflightExpression(pace),
 			returnByValue: true,
 			awaitPromise: true
 		});
@@ -3827,7 +3955,73 @@ const SDK_IMPORT_FILTER = new RegExp(`^${SDK_PACKAGE.replace(/[.*+?^${}()|[\]\\]
 *
 * If `window.__sdk` is absent (non-dog-food build), every access throws a
 * descriptive error rather than returning `undefined` silently.
+*
+* Bridge-stub interception (devtools#740, DT-2): the virtual module runs the
+* resolved `window.__sdk` object through `wrapSdkWithStub` before exporting
+* it. `wrapSdkWithStub` is a pass-through (returns the same object,
+* unwrapped) unless `isStubBlockingEnabled()` reads `true` off
+* `globalThis.__AIT_STUB_BLOCKING__` — an opt-in flag injected the same way
+* `__AIT_CELL__` is (`cell.ts#injectGlobals`, wired from the CLI's
+* `--stub-blocking` flag). Default off => zero behavior change: every existing
+* (non-stub) test run resolves the exact same `window.__sdk` reference it did
+* before this plugin learned about stubbing.
+*
+* Per-method pacing (devtools#769): BEFORE the stub wrap, `window.__sdk` is
+* run through `wrapWithMethodPacing`, which enforces a minimum interval
+* between calls to the SAME named SDK function (`getPaceMethodMs()` reads the
+* `__AIT_PACE_METHOD_MS__` page global — see `method-pace.ts`). Composition
+* order is pacing INSIDE the stub (`wrapSdkWithStub(wrapWithMethodPacing(sdk,
+* gap), enabled)`): a stubbed name resolves instantly from
+* `bridge-stub.ts`'s fixtures without ever reaching the paced wrapper, and
+* only calls that fall through to the real bridge — the ones that can
+* actually trigger `APP_BRIDGE_THROTTLED` — pay the pacing cost. `gapMs <= 0`
+* (default, no `--pace-method` / non-2.x cell) is a no-op fast path — see
+* `method-pace.ts#wrapWithMethodPacing`'s doc for the full contract.
+*/
+/**
+* Builds the virtual CommonJS-style module contents the `sdk-redirect`
+* esbuild plugin loads for every `@apps-in-toss/web-framework` import.
+*
+* Pulled out to a pure, exported function (rather than inlined at the
+* `build.onLoad` call site) so unit tests can assert the exact composition
+* order (pacing wraps the raw SDK; the stub wraps the paced result) as a
+* string-level contract, independent of esbuild — esbuild cannot run inside
+* this repo's jsdom vitest environment (see `bundleTestFile`'s module doc's
+* lazy-import note), so a real bundling round-trip is out of unit-test reach
+* here; `wrapSdkWithStub`/`wrapWithMethodPacing`'s own composed-call behavior
+* is covered directly (see `bundle.test.ts`).
+*
+* Generates a virtual CommonJS-style module so that esbuild does NOT perform
+* strict named-export matching. When `format:'iife'` bundles a CJS module, it
+* wraps it with its own `__toCommonJS` helper and satisfies named imports via
+* property access on the `module.exports` object — which is our Proxy. This
+* means `import { getPlatformOS } from '...'` becomes
+* `__proxy.getPlatformOS` at runtime, which correctly reads from
+* `window.__sdk`.
+*
+* The bridge-stub and method-pace imports are STATIC imports of the real
+* `bridge-stub.ts`/`method-pace.ts` modules (not inlined JS) so esbuild
+* bundles each once and the fixture registry / pacing registry have a single
+* source of truth shared with their own unit tests.
+*
+* Exported for unit testing.
 */
+function buildSdkRedirectModuleContents() {
+	return `
+import { wrapSdkWithStub, isStubBlockingEnabled } from ${JSON.stringify(getBridgeStubPath())};
+import { wrapWithMethodPacing, getPaceMethodMs } from ${JSON.stringify(getMethodPacePath())};
+var __rawSdk = (typeof window !== 'undefined' && window.__sdk)
+  ? window.__sdk
+  : new Proxy({}, {
+      get: function(_t, p) {
+        throw new Error('window.__sdk is not installed — run in a dog-food build. Missing: ' + String(p));
+      }
+    });
+var __pacedSdk = wrapWithMethodPacing(__rawSdk, getPaceMethodMs());
+var __proxy = wrapSdkWithStub(__pacedSdk, isStubBlockingEnabled());
+module.exports = __proxy;
+`;
+}
 function sdkRedirectPlugin() {
 	return {
 		name: "sdk-redirect",
@@ -3840,17 +4034,9 @@ function sdkRedirectPlugin() {
 				filter: /.*/,
 				namespace: "sdk-redirect"
 			}, () => ({
-				contents: `
-var __proxy = (typeof window !== 'undefined' && window.__sdk)
-  ? window.__sdk
-  : new Proxy({}, {
-      get: function(_t, p) {
-        throw new Error('window.__sdk is not installed — run in a dog-food build. Missing: ' + String(p));
-      }
-    });
-module.exports = __proxy;
-`,
-				loader: "js"
+				contents: buildSdkRedirectModuleContents(),
+				loader: "js",
+				resolveDir: process.cwd()
 			}));
 		}
 	};
@@ -3984,8 +4170,9 @@ function userFactoryPlugin(absPath) {
 	};
 }
 /**
-* Returns the absolute filesystem path to the test-runner runtime module
-* (dist/test-runner/runtime.js — a fully self-contained page-side bundle).
+* Returns the absolute filesystem path to a page-side leaf module shipped
+* alongside `bundle.ts` in dist (e.g. `runtime.js`, `bridge-stub.js`) — a
+* fully self-contained module with no further page-side deps of its own.
 *
 * Rolldown code-splitting duplicates this bundling logic into shared chunks
 * emitted at ARBITRARY dist depths: the `devtools-test` CLI pulls it from
@@ -3995,26 +4182,30 @@ function userFactoryPlugin(absPath) {
 * is therefore wrong from at least one chunk — the live #697 regression.
 *
 * This resolves WITHOUT assuming chunk depth: from `import.meta.url`'s dir it
-* probes the co-located `runtime.js` and the nested `test-runner/runtime.js`,
+* probes the co-located `<name>.js` and the nested `test-runner/<name>.js`,
 * then ascends one directory at a time (bounded) repeating both probes. The
-* nested probe catches dist/test-runner/runtime.js from the dist/ root level no
+* nested probe catches dist/test-runner/<name>.js from the dist/ root level no
 * matter which depth the chunk was hoisted to (root, dist/mcp/, or a future
-* relocation). The build always emits dist/test-runner/runtime.js (tsdown entry
-* `'test-runner/runtime'`; guarded by scripts/check-test-runner-dist.sh).
+* relocation). The build always emits dist/test-runner/<name>.js (tsdown entry
+* `'test-runner/<name>'`; guarded by scripts/check-test-runner-dist.sh for
+* `runtime`).
 *
 * An ABSOLUTE path is returned deliberately: esbuild loads it as a literal file
 * read, bypassing Node module resolution entirely, so this works identically in
 * the npx-daemon context (its own dist tree) and the consumer-CLI context
 * (the mini-app's installed @ait-co/devtools dist) — neither needs the package
 * to be node-resolvable from the caller.
+*
+* @param moduleName - The leaf module's basename without extension, e.g.
+*   `'runtime'` or `'bridge-stub'`.
 */
-function getRuntimePath() {
+function getPageSideModulePath(moduleName) {
 	const startDir = path.dirname(fileURLToPath(import.meta.url));
 	const RELATIVE_PROBES = [
-		["runtime.js"],
-		["test-runner", "runtime.js"],
-		["runtime.ts"],
-		["test-runner", "runtime.ts"]
+		[`${moduleName}.js`],
+		["test-runner", `${moduleName}.js`],
+		[`${moduleName}.ts`],
+		["test-runner", `${moduleName}.ts`]
 	];
 	let dir = startDir;
 	for (let i = 0; i < 12; i++) {
@@ -4029,7 +4220,27 @@ function getRuntimePath() {
 		if (parent === dir) break;
 		dir = parent;
 	}
-	return path.join(startDir, "runtime.js");
+	return path.join(startDir, `${moduleName}.js`);
+}
+/** Absolute path to the test-runner page-side runtime (describe/it/test/expect). */
+function getRuntimePath() {
+	return getPageSideModulePath("runtime");
+}
+/**
+* Absolute path to the bridge-stub interceptor (devtools#740, DT-2) —
+* `wrapSdkWithStub`/`isStubBlockingEnabled`, statically imported by the
+* `sdk-redirect` virtual module.
+*/
+function getBridgeStubPath() {
+	return getPageSideModulePath("bridge-stub");
+}
+/**
+* Absolute path to the per-method pacing wrapper (devtools#769) —
+* `wrapWithMethodPacing`/`getPaceMethodMs`, statically imported by the
+* `sdk-redirect` virtual module.
+*/
+function getMethodPacePath() {
+	return getPageSideModulePath("method-pace");
 }
 /**
 * Bundles `absPath` into a single IIFE string suitable for `Runtime.evaluate`.
@@ -4303,15 +4514,21 @@ async function runTestFilesOverRelay(connection, files, opts) {
 	const manualFiles = opts?.manualFiles;
 	const manualTotal = manualFiles?.size ?? 0;
 	let manualIndex = 0;
+	const stubBlockingFiles = opts?.stubBlockingFiles;
 	let preflightPermissions;
-	if (files.length > 0) preflightPermissions = await runPermissionPreflight(connection);
+	if (files.length > 0) preflightPermissions = await runPermissionPreflight(connection, PERMISSION_PREFLIGHT_TIMEOUT_MS, opts?.preflightSdkLine !== "3.x");
+	const paceMs = opts?.paceMs;
+	let ranFirstFile = false;
 	try {
 		for (const file of files) {
 			if (pendingReconnectCheck) {
 				await attemptReconnect("next-file");
 				pendingReconnectCheck = false;
 			}
-			const isManual = manualFiles?.has(file) === true;
+			if (paceMs !== void 0 && paceMs > 0 && ranFirstFile) await new Promise((resolve) => setTimeout(resolve, paceMs));
+			ranFirstFile = true;
+			const isStubbed = stubBlockingFiles?.has(file) === true;
+			const isManual = !isStubbed && manualFiles?.has(file) === true;
 			if (isManual) {
 				manualIndex += 1;
 				opts?.onManualFile?.(file, manualIndex, manualTotal);
@@ -4378,7 +4595,8 @@ async function runTestFilesOverRelay(connection, files, opts) {
 				};
 			}
 			if ("error" in fileEntry.result && isRelayDisconnectMessage(fileEntry.result.error)) pendingReconnectCheck = true;
-			if (isManual) fileEntry.mode = "manual";
+			if (isStubbed) fileEntry.mode = "stubbed";
+			else if (isManual) fileEntry.mode = "manual";
 			fileResults.push(fileEntry);
 		}
 	} finally {
@@ -4445,7 +4663,21 @@ USAGE
 
 OPTIONS
   --scheme-url <url>      intoss-private:// URL from \`ait deploy --scheme-only\`
-                          (required for standalone relay attach / env3)
+                          (required for standalone relay attach / env3). Unused
+                          and ignored when --attach-launcher is set.
+  --attach-launcher       Attach over the env-2 AITC Sandbox PWA launcher
+                          (real-device WebKit) instead of the env-3 intoss
+                          scheme deep-link. The relay/QR/dashboard/attach-wait
+                          are identical; only the QR is a launcher deep-link.
+                          Requires --app-url. The SDK still hits the mock in
+                          env 2, so this measures the mock + standard Web API
+                          layer's engine-attributable behavior (env1↔env2
+                          equivalence), NOT native-bridge fidelity (that is env3).
+  --app-url <url>         The consumer dev server's HTTP tunnel URL (e.g. the
+                          *.trycloudflare.com URL from \`pnpm dev:phone:cdp\`)
+                          that the launcher PWA frames. REQUIRED with
+                          --attach-launcher; ignored otherwise. SECRET: a tunnel
+                          host — never printed; it rides only inside the QR.
   --timeout <ms>          Per-file evaluate timeout in ms (default: 60000).
                           Controls how long a single test file is allowed to run
                           before it is considered hung. Does NOT affect how long
@@ -4457,7 +4689,10 @@ OPTIONS
                           Pass a value to bound the wait for CI/headless runs.
   --cell-sdk-line <line>  SDK line to inject as __AIT_CELL__.sdkLine (2.x|3.x)
   --cell-platform <plat>  Platform to inject as __AIT_CELL__.platform
-                          (mock|ios|android, default: AIT_CELL_PLATFORM env)
+                          (mock|ios|android|ios-pwa, default: AIT_CELL_PLATFORM
+                          env). Use ios-pwa for env-2 (--attach-launcher) runs
+                          so env1(mock@desktop) and env2(mock@WebKit) captures
+                          stay distinguishable. An unknown value is rejected.
   --report-dir <dir>      Persist a runner-agnostic report + captures to <dir>
                           (report: <sdkLine>.<platform>.json; captures:
                           <dir>/.ait-capture/<category>.<sdkLine>.<platform>.json).
@@ -4472,6 +4707,28 @@ OPTIONS
   --headless              Disable browser auto-open (text QR only)
   --project-root <dir>    Project root for .ait_relay secret lookup
                           (default: current working directory)
+  --pace <ms>             Minimum delay in ms between test-to-test AND
+                          file-to-file bridge calls (default: 0, i.e. no
+                          added delay — today's behavior byte-for-byte).
+                          Falls back to the AIT_PACE env var when omitted
+                          (--pace takes precedence over the env var when both
+                          are given). Use on a 2.x cell scan when the native
+                          per-method bridge rate limit (APP_BRIDGE_THROTTLED,
+                          devtools#767) is rejecting rapid same-method calls —
+                          3.x cells are unaffected by that limiter and do not
+                          need this flag.
+  --pace-method <ms>      Minimum delay in ms BETWEEN calls to the SAME named
+                          SDK function — paces a same-method burst WITHIN a
+                          single test body (e.g. a clipboard happy-path loop
+                          calling setClipboardText/getClipboardText 8 times
+                          back to back), which --pace's test/file spacing
+                          cannot reach (devtools#769). Falls back to the
+                          AIT_PACE_METHOD env var when omitted (--pace-method
+                          takes precedence over the env var when both are
+                          given). Default: 250ms when --cell-sdk-line is 2.x
+                          (unset --cell-sdk-line also defaults to 2.x — see
+                          --cell-sdk-line), 0 (no added delay) otherwise. Pass
+                          --pace-method 0 to opt out even on a 2.x cell.
   --manual-blocking       Run manual-tagged test files (*.manual.ait.test.ts)
                           LAST, after all regular files, with a human present.
                           Before each manual file, the QR dashboard is pushed
@@ -4490,6 +4747,24 @@ OPTIONS
                           each manual file's report entry is stamped
                           mode: 'manual' — never diff a manual run against an
                           unattended baseline as if they were equivalent.
+  --stub-blocking         Run manual-tagged test files (*.manual.ait.test.ts)
+                          UNATTENDED (devtools#740, DT-2) by intercepting a
+                          fixed allowlist of blocking-UI SDK calls (ads
+                          show*, openPermissionDialog/requestPermission,
+                          saveBase64Data) in the page and answering them from
+                          fixtures captured by a real --manual-blocking run,
+                          instead of forwarding them to native UI. Implies
+                          --manual-blocking (manual files are included in the
+                          run); no human presence or QR-dashboard prompt is
+                          needed for them. HYBRID cell, not pure env3 — every
+                          other SDK call in the same run still hits the real
+                          native bridge. With --report-dir, files that ran
+                          under the stub are written to a SEPARATE
+                          <sdkLine>.<platform>.stubbed.json artifact (never
+                          merged into the standard or .manual.json report) and
+                          the report body is stamped cell.bridgeStub: true —
+                          never diff a stubbed run against a real device
+                          baseline (manual or unattended) as if equivalent.
   --help, -h              Show this help message
 
 DESCRIPTION
@@ -4506,7 +4781,7 @@ DESCRIPTION
   The test files run against the live relay connection started by this process;
   no separate MCP daemon is required.
 
-EXAMPLE
+EXAMPLE (env 3 — intoss-private scheme)
   devtools-test 'src/**/*.ait.test.ts' \\
     --scheme-url "intoss-private://..." \\
     --cell-sdk-line 3.x \\
@@ -4514,6 +4789,14 @@ EXAMPLE
     --report-dir .ait-report \\
     --timeout 60000
 
+EXAMPLE (env 2 — AITC Sandbox PWA launcher)
+  devtools-test 'src/**/*.ait.test.ts' \\
+    --attach-launcher \\
+    --app-url "https://<subdomain>.trycloudflare.com" \\
+    --cell-sdk-line 3.x \\
+    --cell-platform ios-pwa \\
+    --report-dir .ait-report
+
 `.trimStart();
 /**
 * Renders per-file result lines and the aggregate totals line to a string.
@@ -7205,7 +7488,7 @@ function createDebugServer(deps) {
 	};
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.136"
+		version: "0.1.138"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const conn = router.active;
@@ -7641,6 +7924,13 @@ function errorResult(err, name, isLocal = false) {
 * SECRET-HANDLING: target `id`/`title`/`url` are not written to any log here.
 * Only an attach-detected stderr line is emitted (no target details).
 *
+* `server` is optional (devtools#772): the standalone test-runner path
+* (`test-runner/relay-factory.ts`) has no MCP `Server` instance to notify —
+* it only needs the `onAttach`/`onDetach` dashboard-push side effects. When
+* omitted, `sendToolListChanged()` is simply skipped; the signature-diff and
+* callback logic is byte-for-byte the same. Existing MCP daemon call sites
+* always pass a real `Server`, so their behavior is unchanged.
+*
 * @returns `stop` — call this during shutdown to clear the interval.
 */
 function startAttachWatcher(connection, server, intervalMs = 1e3, onAttach, onDetach) {
@@ -7650,7 +7940,7 @@ function startAttachWatcher(connection, server, intervalMs = 1e3, onAttach, onDe
 	}
 	let lastSignature = signature();
 	if (lastSignature !== "") {
-		server.sendToolListChanged();
+		server?.sendToolListChanged();
 		onAttach?.();
 	}
 	/** Compare current vs last signature and fire the appropriate callback. */
@@ -7660,7 +7950,7 @@ function startAttachWatcher(connection, server, intervalMs = 1e3, onAttach, onDe
 			const wasNonEmpty = lastSignature !== "";
 			lastSignature = current;
 			if (current !== "") {
-				server.sendToolListChanged();
+				server?.sendToolListChanged();
 				onAttach?.();
 			} else if (wasNonEmpty) onDetach?.();
 		}
@@ -7852,7 +8142,7 @@ async function readRelayLocalUrl(env = process.env, projectRoot) {
 	const envValue = (env.AIT_RELAY_LOCAL_URL ?? "").trim();
 	if (envValue !== "") return envValue;
 	if (projectRoot !== void 0) try {
-		const { readRelayUrls } = await import("../relay-url-store-CwKT7i04.js");
+		const { readRelayUrls } = await import("../relay-url-store-DaY1QPes.js");
 		const stored = await readRelayUrls({ projectRoot });
 		if (stored?.relayLocalUrl) return stored.relayLocalUrl;
 	} catch {}
@@ -7906,7 +8196,7 @@ async function readMobileRelayBaseUrl(env = process.env, projectRoot) {
 	const envValue = typeof raw === "string" ? raw.trim() : "";
 	if (envValue !== "") return envValue;
 	if (projectRoot !== void 0) {
-		const { readRelayUrls } = await import("../relay-url-store-CwKT7i04.js");
+		const { readRelayUrls } = await import("../relay-url-store-DaY1QPes.js");
 		const stored = await readRelayUrls({ projectRoot });
 		if (stored?.relayBaseUrl !== void 0) return stored.relayBaseUrl;
 	}
@@ -9189,7 +9479,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.136"
+		version: "0.1.138"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {