dsh-agent-team-ui-testing 0.1.1 → 0.1.3

package/index.js

@@ -8,30 +8,206 @@ import { mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
 import { homedir, tmpdir } from 'node:os';
 import { delimiter, extname, isAbsolute, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { FrameSource } from './frame-source.js';
 import { attachFramePush } from './frame-push.js';
+import { verifyProviderProduct } from './targets/web/adapter.js';
+import { WEB_PROVIDER_REASONS } from './core/contracts.js';
+import { resolveProviderExecutable } from './targets/web/adapter.js';
 import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 import http from 'node:http';
 import https from 'node:https';
 import net from 'node:net';
 import { performance } from 'node:perf_hooks';
 import { BrowserError, Cdp, asBrowserError, checkAbort, abortable, redactUrl, redactText, validateTarget } from './browser-safety.js';
+// Native <select> support for the debug panel: a browser-drawn popup never reaches the frame, so
+// the Host exposes a read-only option projection (POST /element) and one guarded write
+// (POST /select). Kept in its own pure module so the contract suite can pin it without a runtime.
 import {
-  CAPTURE_LIMITS, checkPixelSize, composeCanvasImage, createCaptureMapping, decodePng, detectImageAnomaly,
-  encodePngRgba, expectedPixelSize, hasPositiveOutputSize, inspectPng, intersectRects,
-  projectCaptureMapping, publishCapture, resolveCapturePath,
-} from './capture-p0.js';
-// Web T3 static vision (docs/t3-vision.md). The Host layer never
-// re-implements the pixel algorithms: it validates arguments, resolves sources, owns the product
-// store per scope, delivers the single PNG and implements the act/check decision rules on top of
-// the pure module API.
-import * as vision from './vision-t3.js';
-import { createBaselineStore } from './vision-baseline.js';
+  classifySelectWrite, normalizeSelectProjection, normalizeSelectWriteRequest,
+  selectProbeDeclaration, selectWriteExpression,
+} from './select-control.js';
+import { openPageContextMenu, applyPageContextAction } from './context-menu.js';
+import { createCrossEnvironment } from './integration/cross-environment.js';
+import { createDiagnose } from './integration/diagnose.js';
+import { nowMonoMs } from './core/clock.js';
+import { webProviderSupport } from './core/config.js';
+// M2a: the neutral page-access model (M1) is the single authority for "who may touch which page".
+// index.js keeps no authorisation rules of its own beyond mapping a tool call onto that model: it
+// resolves a Principal (integration/tab-principal.js), expands the call's real effects
+// (core/tab-access.js `operationEffect`) and asks `authorize`/`authorizeAll`. Re-deriving "the
+// 15s lease means permission" here is exactly the confusion this milestone removes.
+import {
+  ACTOR_SELECTION_KEY_PREFIX, AUTHORIZE_REASON, CONTROL_EVENT, CONTROL_STATE, EFFECT,
+  PAGE_GROUP_KEY_PREFIX, PAGE_TARGET_KEY_PREFIX, PRINCIPAL_ROLE, RESOURCE,
+  PRINCIPAL_SOURCE, applyControlTransition, authorize, authorizeAll, makeActorSelectionKey,
+  makeControl, makeOwnership, makePageAccess, makePageGroupKey, makePageTargetKey, makePrincipal,
+  operationEffect, parsePageGroupKey, projectPermissions,
+} from './core/index.js';
+import { defaultTabPrincipalResolver, resolvePrincipal } from './integration/tab-principal.js';
+/*
+ * Web-only host modules are loaded on demand (A14 按需加载).
+ *
+ * The frame source, capture pipeline, T3 vision, the baseline store and the P0 network collector
+ * exist only for the Web environment. Importing them at module load made every Host — including
+ * one whose configuration disables Web — pay for the whole Web dependency chain, which is exactly
+ * what "未启用环境不加载专用运行依赖" forbids. They are now behind `ensureWebHostModules()`:
+ * the tool/HTTP entry points await it before touching a page, and a Web-disabled Host never
+ * resolves these specifiers at all.
+ */
+const WEB_HOST_MODULE_SPECS = Object.freeze({
+  'frame-source': './frame-source.js',
+  'capture-p0': './capture-p0.js',
+  'annotation-capture': './annotation-capture.js',
+  'vision-t3': './vision-t3.js',
+  'vision-baseline': './vision-baseline.js',
+  'network-p0': './network-p0.js',
+});
+const webHostModules = { loaded: false, loading: null, namespaces: {}, failed: null };
+
+/** Resolved namespace, or a typed "not loaded" view when the Web chain was never demanded. */
+function webHostNamespace(id) {
+  const namespace = webHostModules.namespaces[id];
+  if (namespace) return namespace;
+  return null;
+}
+
+/**
+ * Load every Web-only module once. Safe to call from any concurrency: callers share one promise.
+ *
+ * This is the *only* place the Web dependency chain is resolved, so a host that never enables the
+ * Web environment (or never touches a page) never loads it.
+ */
+async function ensureWebHostModules() {
+  if (webHostModules.loaded) return webHostModules.namespaces;
+  if (webHostModules.loading) return webHostModules.loading;
+  webHostModules.loading = (async () => {
+    const entries = Object.entries(WEB_HOST_MODULE_SPECS);
+    const loaded = await Promise.all(entries.map(([, specifier]) => import(specifier)));
+    entries.forEach(([id], index) => { webHostModules.namespaces[id] = loaded[index]; });
+    webHostModules.loaded = true;
+    return webHostModules.namespaces;
+  })();
+  try {
+    return await webHostModules.loading;
+  } catch (error) {
+    webHostModules.loading = null;
+    webHostModules.failed = String((error && error.message) || error);
+    throw new BrowserError('ADAPTER_DISABLED', 'Web 专用模块加载失败：' + webHostModules.failed, {
+      module: Object.keys(WEB_HOST_MODULE_SPECS),
+    });
+  }
+}
+
+/**
+ * A namespace view that forwards to the lazily loaded module.
+ *
+ * Properties stay `undefined` until the module is loaded: read-only diagnostics that happen to
+ * touch a vision/network constant must answer "not available" instead of throwing. Constructions
+ * (`new FrameSource()`) are gated explicitly, because a silently inert page source would be worse
+ * than a typed refusal.
+ */
+function lazyWebNamespace(id) {
+  return new Proxy({}, {
+    get(_target, property) {
+      if (property === 'then' || typeof property === 'symbol') return undefined;
+      const namespace = webHostNamespace(id);
+      return namespace ? namespace[property] : undefined;
+    },
+    has(_target, property) {
+      const namespace = webHostNamespace(id);
+      return namespace ? property in namespace : false;
+    },
+    ownKeys() {
+      const namespace = webHostNamespace(id);
+      return namespace ? Reflect.ownKeys(namespace) : [];
+    },
+    getOwnPropertyDescriptor(_target, property) {
+      const namespace = webHostNamespace(id);
+      if (!namespace) return undefined;
+      const descriptor = Object.getOwnPropertyDescriptor(namespace, property);
+      return descriptor ? { ...descriptor, configurable: true } : undefined;
+    },
+  });
+}
+
+// Web T3 static vision (docs/t3-vision.md). The Host layer never re-implements the pixel
+// algorithms: it validates arguments, resolves sources, owns the product store per scope,
+// delivers the single PNG and implements the act/check decision rules on top of the pure API.
+const vision = lazyWebNamespace('vision-t3');
 // Web P0 network (docs/network-p0.md). The Host layer owns CDP collection, the single Fetch
 // dispatcher and the 7 tool surfaces; every projection/aggregation/evidence rule lives in the
 // pure module so it can be unit tested without a browser.
-import * as network from './network-p0.js';
+const network = lazyWebNamespace('network-p0');
+/**
+ * A lazily forwarded *value* export (not a namespace): `CAPTURE_LIMITS.scaleMin` must read the
+ * module's `CAPTURE_LIMITS` object, not the module namespace itself.
+ */
+function lazyWebValue(id, exportName) {
+  return new Proxy({}, {
+    get(_target, property) {
+      if (property === 'then' || typeof property === 'symbol') return undefined;
+      const namespace = webHostNamespace(id);
+      const value = namespace ? namespace[exportName] : undefined;
+      return value ? value[property] : undefined;
+    },
+    has(_target, property) {
+      const namespace = webHostNamespace(id);
+      const value = namespace ? namespace[exportName] : undefined;
+      return value ? property in value : false;
+    },
+    ownKeys() {
+      const namespace = webHostNamespace(id);
+      const value = namespace ? namespace[exportName] : undefined;
+      return value ? Reflect.ownKeys(value) : [];
+    },
+    getOwnPropertyDescriptor(_target, property) {
+      const namespace = webHostNamespace(id);
+      const value = namespace ? namespace[exportName] : undefined;
+      const descriptor = value ? Object.getOwnPropertyDescriptor(value, property) : undefined;
+      return descriptor ? { ...descriptor, configurable: true } : undefined;
+    },
+  });
+}
+
+/** Capture-p0 constants (a value export, hence `lazyWebValue`); functions forward on call. */
+const CAPTURE_LIMITS = lazyWebValue('capture-p0', 'CAPTURE_LIMITS');
+const checkPixelSize = (...args) => webHostNamespace('capture-p0').checkPixelSize(...args);
+const composeCanvasImage = (...args) => webHostNamespace('capture-p0').composeCanvasImage(...args);
+const createCaptureMapping = (...args) => webHostNamespace('capture-p0').createCaptureMapping(...args);
+const decodePng = (...args) => webHostNamespace('capture-p0').decodePng(...args);
+const detectImageAnomaly = (...args) => webHostNamespace('capture-p0').detectImageAnomaly(...args);
+const encodePngRgba = (...args) => webHostNamespace('capture-p0').encodePngRgba(...args);
+const expectedPixelSize = (...args) => webHostNamespace('capture-p0').expectedPixelSize(...args);
+const hasPositiveOutputSize = (...args) => webHostNamespace('capture-p0').hasPositiveOutputSize(...args);
+const inspectPng = (...args) => webHostNamespace('capture-p0').inspectPng(...args);
+const intersectRects = (...args) => webHostNamespace('capture-p0').intersectRects(...args);
+const projectCaptureMapping = (...args) => webHostNamespace('capture-p0').projectCaptureMapping(...args);
+const publishCapture = (...args) => webHostNamespace('capture-p0').publishCapture(...args);
+const resolveCapturePath = (...args) => webHostNamespace('capture-p0').resolveCapturePath(...args);
+const createBaselineStore = (...args) => webHostNamespace('vision-baseline').createBaselineStore(...args);
+/** `new FrameSource()` must refuse instead of returning an inert source. */
+const FrameSource = new Proxy(function FrameSourceLazy() {}, {
+  construct(_target, args, newTarget) {
+    const namespace = webHostNamespace('frame-source');
+    if (!namespace) {
+      throw new BrowserError('ADAPTER_DISABLED', 'Web 帧源尚未加载：当前进程未启用 Web 环境', {
+        module: 'frame-source',
+      });
+    }
+    return Reflect.construct(namespace.FrameSource, args, newTarget === FrameSource ? namespace.FrameSource : newTarget);
+  },
+  get(_target, property) {
+    if (property === 'prototype') return webHostNamespace('frame-source')?.FrameSource?.prototype ?? {};
+    return undefined;
+  },
+});
 export { BrowserError, Cdp } from './browser-safety.js';
+/**
+ * Load the Web-only host modules on demand (A14).
+ *
+ * The plugin loads them itself before the first call that needs them; this export exists for
+ * tests/diagnostics that construct the Web `Runtime` directly and therefore sit outside that gate.
+ */
+export const loadWebHostModules = ensureWebHostModules;
 
 export const inject = ['tools', 'webServer'];
 
@@ -314,8 +490,8 @@ const INPUT_EVENT_LIMIT = 200;
 export const IMAGE_INLINE_BASE64_LIMIT = 24 * 1024 * 1024;
 /** Throttle for the merged background title/url/history read (UI polls at 500ms / 80ms). */
 const METADATA_THROTTLE_MS = 250;
-const SKILL_NAME = 'ui-testing';
-const SKILL_DIR = fileURLToPath(new URL('./skills/ui-testing/', import.meta.url));
+const SKILL_NAME = 'ui-testing-web';
+const SKILL_DIR = fileURLToPath(new URL('./skills/ui-testing-web/', import.meta.url));
 const SKILL_FALLBACK_DESCRIPTION =
   'Web/Chromium UI testing through 36 bundled browser_* tools: T1 programmatic (navigation, eval, input, ' +
   'network, computed style, screenshots, independent HTTP, viewport, state, capabilities), T2 structured GUI, ' +
@@ -381,12 +557,56 @@ function normalizeKeyEventType(value) {
   return value;
 }
 
+/**
+ * Held-key identity for the input state machine (`browser_input`).
+ *
+ * Keyed by physical `code` when present (so `ShiftLeft`/`ShiftRight` stay distinct until the
+ * modifier bit is derived) and falling back to `key` for callers that only pass a character.
+ */
+function inputKeyIdentity(event) {
+  const code = typeof event.code === 'string' ? event.code.trim() : '';
+  const key = typeof event.key === 'string' ? event.key.trim() : '';
+  return (code || key).toLowerCase();
+}
+
+/** Which modifier bit a key stands for, if any (CDP: Alt=1, Ctrl=2, Meta=4, Shift=8). */
+function inputKeyModifier(event) {
+  const code = typeof event.code === 'string' ? event.code.toLowerCase() : '';
+  const key = typeof event.key === 'string' ? event.key.toLowerCase() : '';
+  if (code.startsWith('shift') || key === 'shift') return 8;
+  if (code.startsWith('control') || key === 'control') return 2;
+  if (code.startsWith('alt') || key === 'alt') return 1;
+  if (code.startsWith('meta') || key === 'meta' || key === 'os') return 4;
+  return 0;
+}
+
+/** True for the event types that *press* a key (everything except keyUp). */
+function inputPressesKey(type) {
+  const normalized = String(type || '').toLowerCase();
+  return normalized === 'keydown' || normalized === 'rawkeydown' || normalized === 'char';
+}
+
 /**
  * Turn one caller-supplied input event into CDP parameters.
  * Validation happens here, before the browser is started, so bad arguments never launch Chromium.
  */
 function prepareInputEvent(event) {
   const modifiers = normalizeModifiers(event.modifiers);
+  // Relative motion (`kind:'mouse'` + deltaX/deltaY) and the modifier-synthesis escape hatch are
+  // Host-side fields, not CDP parameters: validate them here so a bad value never starts Chromium.
+  for (const field of ['deltaX', 'deltaY']) {
+    if (event[field] === undefined) continue;
+    if (typeof event[field] !== 'number' || !Number.isFinite(event[field])) {
+      throw new BrowserError('INVALID_ARGUMENT', `输入事件 ${field} 必须是有限数`, {
+        field, valueType: typeof event[field],
+      });
+    }
+  }
+  if (event.synthesizeModifiers !== undefined && typeof event.synthesizeModifiers !== 'boolean') {
+    throw new BrowserError('INVALID_ARGUMENT', '输入事件 synthesizeModifiers 必须是布尔值', {
+      field: 'synthesizeModifiers', valueType: typeof event.synthesizeModifiers,
+    });
+  }
   if (event.kind === 'mouse') {
     return {
       kind: 'mouse',
@@ -795,7 +1015,13 @@ function normalizeCaptureRequest(args) {
     }
     persist = input.persist;
   }
-  return { scale, region, out, persist };
+  const includeAnnotations = input.includeAnnotations === undefined ? false : input.includeAnnotations;
+  if (typeof includeAnnotations !== 'boolean') {
+    throw new BrowserError('INVALID_ARGUMENT', 'includeAnnotations 必须是布尔值（true = 叠加面板标注）', {
+      field: 'includeAnnotations', valueType: typeof includeAnnotations,
+    });
+  }
+  return { scale, region, out, persist, includeAnnotations };
 }
 
 /** Pixel budget, judged before any CDP screenshot: Chrome must never be asked for more. */
@@ -894,7 +1120,7 @@ function readBundledSkill() {
     return undefined;
   }
   const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(raw);
-  if (!frontmatter) throw new Error('skills/ui-testing/SKILL.md 缺少 YAML frontmatter');
+  if (!frontmatter) throw new Error('skills/ui-testing-web/SKILL.md 缺少 YAML frontmatter');
   const singleLine = /^description:\s*(?!>)(.+)$/m.exec(frontmatter[1]);
   return {
     name: SKILL_NAME,
@@ -926,6 +1152,68 @@ function readBundledSkill() {
  * by the create that owns it. Everything else is a popup and is blocked before it resumes.
  * ------------------------------------------------------------------------------------------- */
 const MAX_PAGES_DEFAULT = 8;
+
+/**
+ * Runtime provider (browser) this host container is keyed by (contract §6). Mirrors core's
+ * `DEFAULT_WEB_PROVIDER`; the *support* truth (which providers may execute at all) lives only in
+ * core's `WEB_PROVIDER_SUPPORT`, never here.
+ */
+const DEFAULT_RUNTIME_PROVIDER = 'chrome';
+
+/**
+ * Every page group in this module belongs to the Web environment (index.js *is* the Web
+ * implementation); the neutral model still validates it like any other dimension.
+ */
+const PAGE_GROUP_ENVIRONMENT = 'web';
+
+/**
+ * Root dimension for callers that cannot carry a Principal at all: the legacy panel protocol
+ * (no scope headers) and any old client. It is a *separate* domain, never a wildcard — an unscoped
+ * caller must not inherit an Agent's page just because it named the same workspace.
+ */
+const UNSCOPED_ROOT = 'root:unscoped';
+
+/**
+ * The one function that composes a page-group key (M2a, ruling §7.4).
+ *
+ * It used to be `<provider>\u0000<baseKey>`, which made the workspace — not the Session — the unit
+ * of page ownership: two independent sessions in one workspace resolved to the *same* entry and
+ * therefore fought over one page. The root dimension is now part of the key, so "A's primary" and
+ * "B's primary" are simply different keys and can never alias, be evicted for each other, or be
+ * addressed across roots. No caller may hand-compose this string: everything goes through M1's
+ * factory, which rejects empty/composed dimensions instead of silently building a wrong root.
+ */
+function pageGroupKeyFor(provider, baseKey, rootSessionId) {
+  return makePageGroupKey({
+    environment: PAGE_GROUP_ENVIRONMENT,
+    workspaceKey: String(baseKey),
+    provider: String(provider ?? DEFAULT_RUNTIME_PROVIDER),
+    rootSessionId: String(rootSessionId || UNSCOPED_ROOT),
+  });
+}
+
+/** Canonical identity of one physical target inside a page group (primary stays a group alias). */
+function pageTargetKeyFor(groupKey, tabId) {
+  return makePageTargetKey({ groupKey: String(groupKey), tabId: String(tabId) });
+}
+
+/** True when the value is already a composed page-group key (binding/recent addressing). */
+function isPageGroupKey(value) {
+  return typeof value === 'string' && value.startsWith(PAGE_GROUP_KEY_PREFIX);
+}
+
+/** Root recorded in a group key; a malformed key degrades to the unscoped domain, never to "any". */
+function rootOfPageGroupKey(key) {
+  try { return parsePageGroupKey(key).rootSessionId; } catch { return UNSCOPED_ROOT; }
+}
+
+/**
+ * Provider index key: the provider fallback must also be per root, otherwise one root's last-used
+ * browser could silently become another root's routing decision for the same workspace.
+ */
+function providerIndexKey(baseKey, rootSessionId) {
+  return String(baseKey) + '\u0000' + String(rootSessionId || UNSCOPED_ROOT);
+}
 const IDLE_MS_DEFAULT = 600000;
 /** A viewer is only "visible" while the panel keeps posting metrics (WS liveness alone can leak). */
 const VIEWER_TTL_MS = 15000;
@@ -942,6 +1230,17 @@ const TAB_WAIT_TIMEOUT_MAX_MS = 30000;
 const TAB_WAIT_POLL_DEFAULT_MS = 100;
 const TAB_WAIT_POLL_MIN_MS = 50;
 const TAB_WAIT_POLL_MAX_MS = 1000;
+/**
+ * Bounded drain budget for a Lead takeover (ruling §5.1: default 5000ms, 0–30000).
+ *
+ * The budget covers *waiting for the current operation to reach a safe boundary*, never interrupting
+ * it: `Runtime.run` closes the page on ABORTED/CDP_TIMEOUT, so a forced takeover would destroy a
+ * member's logged-in page. Exceeding the budget is BUSY and leaves the record untouched.
+ */
+const TAB_ACQUIRE_TIMEOUT_DEFAULT_MS = 5000;
+const TAB_ACQUIRE_TIMEOUT_MAX_MS = 30000;
+/** How often the drain loop re-samples `active`/`inflight` (host memory only, no CDP). */
+const TAB_DRAIN_POLL_MS = 25;
 /** Per-workspace bounded lifecycle projections: blocked popup notices + close audit. */
 const POPUP_NOTICES_LIMIT = 8;
 const CLOSED_HISTORY_LIMIT = 8;
@@ -994,13 +1293,19 @@ function sha256Short(value, length = 16) {
  * (docs/viewport-control.md).
  *
  * The Host stores exactly one "last accepted" document per Runtime and exposes it through
- * `Runtime.state()` (→ `browser_state.annotations`) and the authenticated `ui.annotations`. The
- * panel writes it over its *only* write surface, `POST /plugins/ui-testing/annotations`; there is
- * deliberately no 37th tool (the tool surface stays 36).
+ * `Runtime.state()` (→ `browser_state.annotations`) and the authenticated `ui.annotations`. Two
+ * writers share that one document: the human panel over its scoped route
+ * `POST /plugins/ui-testing/annotations`, and the Agent over the 37th tool `browser_annotation`
+ * (read/draw/erase/clear). It stays ONE document on purpose: the panel already hydrates a newer
+ * Host revision, so an Agent note is visible to the human with no second store and no second
+ * conflict model. Agent writes additionally require a *fresh human-foreground claim* for the
+ * target tab (the panel reports "I am displaying my selected tab and I am visible"), otherwise a
+ * drawn note could be invisible to the person it is meant for.
  *
- * Everything below is pure data handling: annotations never touch the page DOM/CSS, never enter a
- * screenshot or a T3 source, never start Chromium, never take the page lease and never write the
- * page `lastError`. Human notes are untrusted hints (`source.trusted:false`).
+ * The document store below is pure data handling: it never touches page DOM/CSS, starts Chromium,
+ * takes the page lease or writes page lastError. browser_screenshot may explicitly rasterize a
+ * frozen document with includeAnnotations:true; raw captures and T3/T4 sources remain unannotated.
+ * Human notes are untrusted hints (`source.trusted:false`).
  *
  * The limits are soft and deterministic (§11.2), and the client applies the same rule so both
  * sides converge on one normalized set: keep the newest 128 shapes, downsample every brush to
@@ -1023,6 +1328,25 @@ const ANNOTATION_LIMITS = Object.freeze({
   strokeWidth: Object.freeze([1, 20]),
   textFontSize: 20,
 });
+/**
+ * Agent write surface (`browser_annotation`, docs/viewport-control.md).
+ *
+ * `foregroundTtlMs` is the freshness window of the panel's "this tab is my selected tab and I am
+ * visible" claim. The panel polls `/state` every 500ms for its selected tab, so a 1.5s window means
+ * "the human is looking at this tab right now" while a tab switch, a closed panel or a backgrounded
+ * DSH tab expires the claim within one or two polls instead of relying on the 15s viewer TTL.
+ */
+const ANNOTATION_FOREGROUND_TTL_MS = 1500;
+const ANNOTATION_AGENT_ACTIONS = Object.freeze(['read', 'draw', 'erase', 'clear']);
+/** One call may add at most this many shapes; the document budget is still 128. */
+const ANNOTATION_AGENT_MAX_SHAPES_PER_CALL = 64;
+const ANNOTATION_AGENT_DEFAULT_COLOR = '#ff3b30';
+const ANNOTATION_AGENT_DEFAULT_STROKE = 3;
+/** Panel eraser: r = max(strokeWidth / 2, 6) canvas CSS px (docs/viewport-control.md §11.4). */
+const ANNOTATION_ERASE_MIN_RADIUS = 6;
+const ANNOTATION_ERASE_DEFAULT_RADIUS = 8;
+/** Text has no measured box on the Host side: hit-test uses an estimate, never a DOM read. */
+const ANNOTATION_TEXT_BOX_CHAR_RATIO = 0.6;
 /** Shape geometry may sit anywhere on the canvas: C's lower bound plus the largest viewport. */
 const ANNOTATION_COORD_MIN = -10000000;
 const ANNOTATION_COORD_MAX = 10004096;
@@ -1069,6 +1393,8 @@ function annotationLimits() {
     maxBodyBytes: ANNOTATION_LIMITS.maxBodyBytes,
     maxPanels: ANNOTATION_LIMITS.maxPanels,
     staleAfterMs: ANNOTATION_LIMITS.staleAfterMs,
+    maxShapesPerCall: ANNOTATION_AGENT_MAX_SHAPES_PER_CALL,
+    foregroundTtlMs: ANNOTATION_FOREGROUND_TTL_MS,
   };
 }
 
@@ -1349,6 +1675,237 @@ function applyAnnotationLimits(shapes, clientTruncation, shortenedText) {
   return { shapes: list, truncation };
 }
 
+/**
+ * Agent annotation write surface — pure pre-flight, no browser, no CDP, no file
+ * (docs/viewport-control.md).
+ *
+ * `browser_annotation` writes the SAME document the human panel publishes, so both writers have to
+ * agree on one set of shapes and one limit application. Everything below is deterministic data
+ * handling: an invalid call costs nothing, and a shape that would not survive the panel's own
+ * `annotWireShape`/Host validation is refused here instead of being drawn differently later.
+ */
+const ANNOTATION_AGENT_SHAPE_FIELDS = Object.freeze([
+  'type', 'id', 'color', 'strokeWidth', 'style', 'fill', 'stroke',
+  'x', 'y', 'width', 'height', 'cx', 'cy', 'rx', 'ry', 'x1', 'y1', 'x2', 'y2', 'points', 'text', 'fontSize',
+]);
+
+/** Next free `a<N>` id, starting after every id already in the document and in this call. */
+function annotationAgentIdFactory(shapes, specs) {
+  let max = 0;
+  const consider = (id) => {
+    const match = typeof id === 'string' ? /^a([1-9][0-9]{0,15})$/u.exec(id) : null;
+    if (!match) return;
+    const numeric = Number(match[1]);
+    if (Number.isSafeInteger(numeric) && numeric > max) max = numeric;
+  };
+  for (const shape of shapes) consider(shape && shape.id);
+  for (const spec of specs) consider(spec && typeof spec === 'object' && !Array.isArray(spec) ? spec.id : null);
+  return () => { max += 1; return 'a' + max; };
+}
+
+/**
+ * 填充/外框 for one Agent shape. `style` is the panel's single-source mode; explicit
+ * `fill`/`stroke` booleans are accepted for callers that want the raw contract, but mixing both is
+ * refused instead of guessed (a silently ignored style would draw a different shape).
+ */
+function annotationAgentFillStroke(type, spec, field) {
+  const hasStyle = spec.style !== undefined && spec.style !== null;
+  const hasFlags = spec.fill !== undefined || spec.stroke !== undefined;
+  if (hasStyle && hasFlags) throw annotationInvalid(`${field}.style`, 'style-conflicts-fill-stroke');
+  if (hasStyle) {
+    if (spec.style !== 'fill' && spec.style !== 'stroke') throw annotationInvalid(`${field}.style`, 'invalid-enum');
+    // `外框` is the panel's default mode for closed tools (annotStyleFor in client.js).
+    return spec.style === 'fill' ? { fill: true, stroke: false } : { fill: false, stroke: true };
+  }
+  if (hasFlags) {
+    return {
+      fill: spec.fill === undefined ? false : annotationBoolean(spec.fill, `${field}.fill`),
+      stroke: spec.stroke === undefined ? false : annotationBoolean(spec.stroke, `${field}.stroke`),
+    };
+  }
+  // Panel defaults: text is filled text; free strokes/arrows are always outer strokes; circle and
+  // rect follow the panel's default 外框 mode.
+  return type === 'text' ? { fill: true, stroke: false } : { fill: false, stroke: true };
+}
+
+/** One Agent shape spec → the wire shape the panel and the screenshot overlay already understand. */
+function normalizeAgentAnnotationShape(raw, field, allocateId, seenIds) {
+  const spec = annotationObject(raw, field);
+  annotationRejectUnknown(spec, ANNOTATION_AGENT_SHAPE_FIELDS, field);
+  const type = spec.type;
+  if (typeof type !== 'string' || !ANNOTATION_TYPES.includes(type)) throw annotationInvalid(`${field}.type`, 'invalid-enum');
+  const style = annotationAgentFillStroke(type, spec, field);
+  const wire = {
+    id: spec.id === undefined || spec.id === null ? allocateId() : spec.id,
+    type,
+    color: spec.color === undefined || spec.color === null ? ANNOTATION_AGENT_DEFAULT_COLOR : spec.color,
+    strokeWidth: spec.strokeWidth === undefined || spec.strokeWidth === null
+      ? ANNOTATION_AGENT_DEFAULT_STROKE : spec.strokeWidth,
+    fill: style.fill,
+    stroke: style.stroke,
+  };
+  for (const key of ANNOTATION_GEOMETRY_FIELDS[type]) {
+    // The arrow head is derived from the endpoints + stroke width; a supplied head never wins.
+    if (key === 'head') continue;
+    if (key === 'fontSize') {
+      wire.fontSize = spec.fontSize === undefined || spec.fontSize === null
+        ? ANNOTATION_LIMITS.textFontSize : spec.fontSize;
+      continue;
+    }
+    wire[key] = spec[key];
+  }
+  return normalizeAnnotationShape(wire, field, seenIds);
+}
+
+function annotationSegmentDistance(px, py, ax, ay, bx, by) {
+  const dx = bx - ax;
+  const dy = by - ay;
+  const lengthSq = dx * dx + dy * dy;
+  if (!(lengthSq > 0)) return Math.hypot(px - ax, py - ay);
+  const t = Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / lengthSq));
+  return Math.hypot(px - (ax + t * dx), py - (ay + t * dy));
+}
+
+function annotationPointInRect(point, rect) {
+  return point.x >= rect.x && point.x <= rect.x + rect.width
+    && point.y >= rect.y && point.y <= rect.y + rect.height;
+}
+
+/** Distance from a point to a rect's outline (inside included): 0 on the border. */
+function annotationRectOutlineDistance(point, rect) {
+  const left = rect.x;
+  const right = rect.x + rect.width;
+  const top = rect.y;
+  const bottom = rect.y + rect.height;
+  if (!annotationPointInRect(point, rect)) {
+    const nx = Math.min(Math.max(point.x, left), right);
+    const ny = Math.min(Math.max(point.y, top), bottom);
+    return Math.hypot(point.x - nx, point.y - ny);
+  }
+  return Math.min(point.x - left, right - point.x, point.y - top, bottom - point.y);
+}
+
+/**
+ * Host-side eraser hit test (the panel uses Path2D/isPointInStroke plus the rendered text bbox; the
+ * Host must not read the page, so the rules below are analytic and stated in the docs):
+ *   rect   — inside when filled, else within `r` of the outline;
+ *   circle — normalized radial distance |k−1| · min(rx,ry) within `r`, inside when filled;
+ *   line   — point/segment distance within `r`;
+ *   arrow  — the shaft only (the head triangle is not modelled);
+ *   brush  — nearest polyline segment within `r`;
+ *   text   — an estimated box (see ANNOTATION_TEXT_BOX_CHAR_RATIO), expanded by `r`.
+ * `r = max(requested radius, strokeWidth / 2, 6)` mirrors `annotEraseRadius` in client.js.
+ */
+function annotationAgentHit(shape, point, radius) {
+  const width = Number(shape.strokeWidth);
+  const limit = Math.max(radius, Number.isFinite(width) ? width / 2 : 0, ANNOTATION_ERASE_MIN_RADIUS);
+  if (shape.type === 'rect') {
+    const rect = { x: shape.x, y: shape.y, width: shape.width, height: shape.height };
+    if (shape.fill === true && annotationPointInRect(point, rect)) return true;
+    if (shape.stroke !== true) return false;
+    return annotationRectOutlineDistance(point, rect) <= limit;
+  }
+  if (shape.type === 'circle') {
+    const rx = shape.rx;
+    const ry = shape.ry;
+    const k = Math.hypot((point.x - shape.cx) / rx, (point.y - shape.cy) / ry);
+    if (shape.fill === true && k <= 1) return true;
+    if (shape.stroke !== true) return false;
+    return Math.abs(k - 1) * Math.min(rx, ry) <= limit;
+  }
+  if (shape.type === 'line' || shape.type === 'arrow') {
+    return annotationSegmentDistance(point.x, point.y, shape.x1, shape.y1, shape.x2, shape.y2) <= limit;
+  }
+  if (shape.type === 'brush') {
+    const points = Array.isArray(shape.points) ? shape.points : [];
+    if (points.length === 1) return Math.hypot(point.x - points[0][0], point.y - points[0][1]) <= limit;
+    for (let index = 1; index < points.length; index += 1) {
+      if (annotationSegmentDistance(point.x, point.y, points[index - 1][0], points[index - 1][1],
+        points[index][0], points[index][1]) <= limit) return true;
+    }
+    return false;
+  }
+  if (shape.type === 'text') {
+    const size = Number(shape.fontSize);
+    const fontSize = Number.isFinite(size) && size > 0 ? size : ANNOTATION_LIMITS.textFontSize;
+    const chars = Math.max(1, String(shape.text || '').length);
+    const rect = {
+      x: shape.x,
+      y: shape.y - fontSize,
+      width: chars * fontSize * ANNOTATION_TEXT_BOX_CHAR_RATIO,
+      height: fontSize * 1.2,
+    };
+    return annotationRectOutlineDistance(point, rect) <= limit || annotationPointInRect(point, rect);
+  }
+  return false;
+}
+
+/**
+ * `browser_annotation` arguments → one validated call. Pure: no runtime, no browser, no file, so an
+ * invalid call is refused before any state is read (and before the foreground claim is consulted).
+ */
+function normalizeAgentAnnotationCall(args) {
+  const input = annotationObject(args, 'browser_annotation');
+  annotationRejectUnknown(input,
+    ['action', 'shapes', 'ids', 'point', 'expectRevision'], 'browser_annotation');
+  const action = input.action;
+  if (typeof action !== 'string' || !ANNOTATION_AGENT_ACTIONS.includes(action)) {
+    throw annotationInvalid('action', 'invalid-enum');
+  }
+  const allowed = {
+    read: [],
+    draw: ['shapes', 'expectRevision'],
+    erase: ['ids', 'point', 'expectRevision'],
+    clear: ['expectRevision'],
+  }[action];
+  for (const key of Object.keys(input)) {
+    if (key === 'action') continue;
+    if (!allowed.includes(key)) throw annotationInvalid(key, 'unknown-field');
+  }
+  let expectRevision = null;
+  if (input.expectRevision !== undefined && input.expectRevision !== null) {
+    expectRevision = annotationNumber(input.expectRevision, 'expectRevision', {
+      min: 0, max: Number.MAX_SAFE_INTEGER, integer: true,
+    });
+  }
+  if (action === 'read') return { action, specs: [], ids: [], point: null, expectRevision };
+  if (action === 'clear') return { action, specs: [], ids: [], point: null, expectRevision };
+  if (action === 'draw') {
+    if (!Array.isArray(input.shapes) || input.shapes.length === 0) throw annotationInvalid('shapes', 'not-an-array');
+    if (input.shapes.length > ANNOTATION_AGENT_MAX_SHAPES_PER_CALL) throw annotationInvalid('shapes', 'too-many');
+    return { action, specs: input.shapes, ids: [], point: null, expectRevision };
+  }
+  // erase: ids and/or a point hit. Both empty would be a no-op reported as success — refuse it.
+  const ids = [];
+  if (input.ids !== undefined && input.ids !== null) {
+    if (!Array.isArray(input.ids)) throw annotationInvalid('ids', 'not-an-array');
+    if (input.ids.length > ANNOTATION_AGENT_MAX_SHAPES_PER_CALL) throw annotationInvalid('ids', 'too-many');
+    for (let index = 0; index < input.ids.length; index += 1) {
+      const id = input.ids[index];
+      if (typeof id !== 'string' || !ANNOTATION_ID_PATTERN.test(id)) throw annotationInvalid(`ids[${index}]`, 'invalid-id');
+      if (ids.includes(id)) throw annotationInvalid(`ids[${index}]`, 'duplicate-id');
+      ids.push(id);
+    }
+  }
+  let point = null;
+  if (input.point !== undefined && input.point !== null) {
+    const raw = annotationObject(input.point, 'point');
+    annotationRejectUnknown(raw, ['x', 'y', 'radius'], 'point');
+    const coord = (value, name) => annotationNumber(value, `point.${name}`, {
+      min: ANNOTATION_COORD_MIN, max: ANNOTATION_COORD_MAX,
+    });
+    point = {
+      x: coord(raw.x, 'x'),
+      y: coord(raw.y, 'y'),
+      radius: raw.radius === undefined || raw.radius === null
+        ? ANNOTATION_ERASE_DEFAULT_RADIUS
+        : annotationNumber(raw.radius, 'point.radius', { min: 1, max: 4096 }),
+    };
+  }
+  if (ids.length === 0 && point === null) throw annotationInvalid('ids', 'erase-target-required');
+  return { action, specs: [], ids, point, expectRevision };
+}
+
 /** Content digest of one panel revision: the same revision must carry the same content. */
 function annotationDigest(request) {
   return createHash('sha256').update(JSON.stringify({
@@ -1503,9 +2060,13 @@ function isBlankPageUrl(value) {
 }
 
 class BrowserHost {
-  constructor(log) {
+  constructor(log, options = {}) {
     this.log = log;
     this.proc = undefined;
+    /** Runtime provider this host launches (chrome|edge); set by the registry, never by tools. */
+    this.provider = options?.provider ?? 'chrome';
+    this.product = null;
+    this.executablePath = null;
     this.profileDir = undefined;
     this.port = 0;
     this.browserCdp = undefined;
@@ -1594,7 +2155,10 @@ class BrowserHost {
     const override = process.env.DSH_UI_TESTING_PROFILE_DIR;
     if (override) return override;
     const home = process.env.DSH_HOME || join(homedir(), '.dsh');
-    return join(home, 'ui-testing', 'headed-profile');
+    // Per-provider persistent profile: Chrome keeps its historical directory, Edge gets its own.
+    // Sharing one headed profile across vendors would mix state and hide identity problems.
+    const suffix = this.provider === 'chrome' ? '' : `-${this.provider}`;
+    return join(home, 'ui-testing', `headed-profile${suffix}`);
   }
 
   /**
@@ -1737,8 +2301,18 @@ class BrowserHost {
   }
 
   async #spawn(signal) {
-    // Resolve first: a missing browser must fail before a profile directory is created.
-    const chromeBin = resolveChromeExecutable();
+    // Resolve first: a missing browser must fail before a profile directory is created. The
+    // resolution is per provider — an Edge host must never launch a Chrome binary (§8).
+    const resolution = resolveProviderExecutable({ provider: this.provider });
+    this.executablePath = resolution.path;
+    if (!resolution.path) {
+      throw new BrowserError(
+        'DEPENDENCY_MISSING',
+        `${this.provider} 可执行文件不可用（${resolution.reason}）：已尝试 ${resolution.candidates.slice(0, 4).join(', ')}`,
+        { provider: this.provider, reason: resolution.reason, candidates: resolution.candidates.slice(0, 8) },
+      );
+    }
+    const chromeBin = resolution.path;
     const generation = this.generation + 1;
     this.generation = generation;
     const overallDeadline = Date.now() + DEVTOOLS_STARTUP.totalBudgetMs;
@@ -1802,6 +2376,36 @@ class BrowserHost {
         // Record the pre-existing about:blank target BEFORE enabling auto-attach: setAutoAttach
         // also attaches to existing targets, and an attach event for the initial page must never
         // be classified as a popup (that would block/close the page we are about to reuse).
+        // §8: "CDP connected" is not proof of the product. Verify the vendor after the transport
+        // is up and before any page work; a mismatch is reported, never silently accepted.
+        {
+          // Every provider is checked; whether *missing* evidence rejects is per vendor
+          // (`WEB_PROVIDER_VENDOR.failClosedOnMissing`): edge fails closed, chrome stays lenient.
+          let version = null;
+          try {
+            version = await browserCdp.send('Browser.getVersion', {}, { signal });
+          } catch {
+            version = null; // no evidence; the vendor rule decides whether that is fatal
+          }
+          const identity = verifyProviderProduct({ provider: this.provider, version });
+          this.product = identity.product;
+          this.productVerified = identity.verified === true;
+          if (!identity.ok) {
+            throw new BrowserError(
+              'DEPENDENCY_MISSING',
+              identity.reason === WEB_PROVIDER_REASONS.IDENTITY_UNVERIFIED
+                ? `启动的产品身份无法确认（provider=${this.provider}）：拿不到 Browser.getVersion`
+                : `启动的产品身份与 provider 不符：期望 ${String(identity.expected)}，实际 ${String(identity.product)}`,
+              {
+                provider: this.provider,
+                product: identity.product,
+                expected: identity.expected,
+                reason: identity.reason,
+                path: resolution.path,
+              },
+            );
+          }
+        }
         this.initialTargetId = await this.#findInitialPage(signal);
         await browserCdp.send('Target.setAutoAttach', {
           autoAttach: true, waitForDebuggerOnStart: true, flatten: true,
@@ -4091,6 +4695,11 @@ export function inlineImageDelivery(base64, limit = IMAGE_INLINE_BASE64_LIMIT) {
 }
 
 export class Runtime {
+  #frames = null;
+  #visionStore = null;
+  #net = null;
+  #netCtl = null;
+
   /**
    * @param log logger
    * @param {{host?: BrowserHost, origins?: Set<string>, scope?: object, registry?: RuntimeRegistry}} [options]
@@ -4117,7 +4726,11 @@ export class Runtime {
     this.cdp = undefined;
     /** { targetId, generation } of this runtime's own page target (undefined when cold). */
     this.page = undefined;
-    this.frames = new FrameSource();
+    // A14: the frame source is the Web-only capture chain. Constructing it eagerly made
+    // `new Runtime()` require the whole Web module graph, so a host that never captures frames
+    // still paid for it (and a direct construction outside the plugin's load gate threw). It is
+    // created on first use instead; a runtime that never captures never loads it.
+    this.#frames = null;
     this.frameTransport = undefined;
     this.clientMetrics = undefined;
     this.ackFailures = 0;
@@ -4179,6 +4792,11 @@ export class Runtime {
       updatedAt: null,
       lastRotateReason: null,
       salt: randomUUID().replace(/-/gu, ''),
+      // Human-foreground claim (`browser_annotation`, docs/viewport-control.md): the panel reports
+      // "this runtime is my selected tab and I am visible" on its authenticated requests. It is a
+      // separate clock from `lastSeenAt` (document freshness) and from the 15s viewer TTL.
+      guiForegroundAt: 0,
+      guiForegroundView: null,
     };
     this.activity = '空闲';
     this.agentUntil = 0;
@@ -4189,8 +4807,16 @@ export class Runtime {
     this.lastErrorTarget = null;
     this.starting = undefined;
     this.queue = Promise.resolve();
+    // Cross-environment lifecycle (A12): a config transition that removes the Web selection for
+    // this page's scope must cancel queued/running operations instead of letting them mutate a
+    // page the environment no longer owns. The composed signal is what `run()` observes.
+    this.envController = new AbortController();
+    this.envAbortReason = null;
     this.lease = undefined;
     this.active = 0;
+    // `browser_input` state (docs/tools.md): the keys this page currently holds down and the
+    // virtual cursor position used by relative mouse moves. Both die with the document.
+    this.inputState = { keys: new Map(), cursor: null };
     // Every queued/running operation (agent OR panel): idle sweep/LRU must never close a page
     // that has work in flight.
     this.inflight = 0;
@@ -4221,7 +4847,7 @@ export class Runtime {
     // instance and independent of the page lifecycle — a page navigation/close keeps the stored
     // images analysable offline (their actionable资格 is invalidated separately). Only dispose
     // (plugin unload / runtime retire) clears it.
-    this.visionProducts = new vision.VisionProductStore({ now: () => Date.now() });
+    this.#visionStore = null;
     // Provenance per product (runtimeId/pageGeneration/documentEpoch) so `act` can prove it is
     // operating on the same page generation, and evidence can cite the capture lineage.
     this.visionProvenance = new Map();
@@ -4260,15 +4886,10 @@ export class Runtime {
     // TOOL-P1-04: session attribution is a construction-time fact -- scopeId from this Runtime's
     // workspace, runtimeId its own id, tabId 'primary' for the primary runtime and the popup viewId
     // for a child tab. It is never inferred from cdpSessionId/targetId and stays stable per tab.
-    this.net = new network.NetworkStore({
-      scopeId: this.scope.id,
-      attribution: {
-        scopeId: this.scope.id,
-        runtimeId: this.runtimeId,
-        tabId: this.kind === 'popup' ? (this.viewId || 'primary') : 'primary',
-      },
-    });
-    this.netCtl = new network.ControlState();
+    // A14: the P0 network store/control state belong to the Web-only module chain; they are
+    // created on first use so a runtime that never touches the network never loads them.
+    this.#net = null;
+    this.#netCtl = null;
     this.netTargets = new Map();
     this.netReq = new Map();
     this.netHops = new Map();
@@ -4279,7 +4900,8 @@ export class Runtime {
     this.netHoldTimer = null;
     this.netBodyTimeoutMs = 1500;
     // Tool-surface evidence: last real network tool call (projected into capabilities.network).
-    this.net.observed = null;
+    // The store itself is created on first network use, so the field is seeded here as data.
+    this.netObserved = null;
     this.lastNetSessionId = null;
     // Web T4 dynamic behaviour (docs/t4-dynamic-behavior.md, docs/t4-dynamic-behavior.md):
     // one active session per scope, up to four retained summaries, one screencast sink, and the
@@ -4347,6 +4969,52 @@ export class Runtime {
     cdp.send('Page.bringToFront', {}, { timeoutMs: 1000 }).catch(() => {});
   }
 
+  /** Lazily created P0 network store (scope-local attribution is fixed at first use). */
+  get net() {
+    if (!this.#net) {
+      this.#net = new network.NetworkStore({
+        scopeId: this.scope.id,
+        attribution: {
+          scopeId: this.scope.id,
+          runtimeId: this.runtimeId,
+          tabId: this.kind === 'popup' ? (this.viewId || 'primary') : 'primary',
+        },
+      });
+    }
+    return this.#net;
+  }
+
+  set net(value) { this.#net = value; }
+
+  /** Last real network tool call (`capabilities.network.observed`); null until one happens. */
+  get netObserved() { return this.#net ? this.#net.observed : null; }
+
+  set netObserved(value) { if (this.#net) this.#net.observed = value; }
+
+  /** Lazily created interception/throttle/hold state machine. */
+  get netCtl() {
+    if (!this.#netCtl) this.#netCtl = new network.ControlState();
+    return this.#netCtl;
+  }
+
+  set netCtl(value) { this.#netCtl = value; }
+
+  /** Lazily created T3 product store (created on first vision use, like the frame source). */
+  get visionProducts() {
+    if (!this.#visionStore) this.#visionStore = new vision.VisionProductStore({ now: () => Date.now() });
+    return this.#visionStore;
+  }
+
+  set visionProducts(value) { this.#visionStore = value; }
+
+  /** Lazily created frame source (see the constructor note). Throws only when actually used. */
+  get frames() {
+    if (!this.#frames) this.#frames = new FrameSource();
+    return this.#frames;
+  }
+
+  set frames(value) { this.#frames = value; }
+
   hasLease() { return Boolean(this.lease && (this.active || this.lease.expiresAt > Date.now())); }
 
   /** Idle sweep / LRU eviction is only allowed when nothing is using this page. */
@@ -4371,7 +5039,39 @@ export class Runtime {
    * and clear the error projection (contract §9.1). Diagnostics, HTTP requests, BUSY and
    * pre-validation failures pass no action, so they can never overwrite another owner's error.
    */
-  async run(operation, { signal, sessionId = 'anonymous', agent = false, action } = {}) {
+  /** Observed signal for one operation: caller cancellation plus the environment-transition gate. */
+  #effectiveSignal(signal) {
+    const environmentSignal = this.envController?.signal;
+    if (!environmentSignal) return signal;
+    if (!signal) return environmentSignal;
+    return typeof AbortSignal.any === 'function' ? AbortSignal.any([signal, environmentSignal]) : signal;
+  }
+
+  /**
+   * Cancel queued/running work because the configuration no longer selects this environment.
+   * The controller is replaced so later operations (after re-enabling Web) are not still aborted;
+   * `run()`'s ABORTED classification closes the page, releasing connection/frames/network/lease.
+   */
+  abortForEnvironmentChange(reason = 'config-transition') {
+    if (!this.envController || this.envController.signal.aborted) return { aborted: false, reason: this.envAbortReason };
+    this.envAbortReason = reason;
+    try { this.envController.abort(new Error('environment changed: ' + reason)); } catch { /* best effort */ }
+    this.envController = new AbortController();
+    return { aborted: true, reason };
+  }
+
+  /**
+   * Run one operation in the page queue.
+   *
+   * `activate` (default true) fronts the page so Chromium keeps compositing it — required for real
+   * page operations, and the reason a panel preview follows the operated tab. A **read-only
+   * observation** must pass `activate:false`: bringing a teammate's page to the front changes its
+   * `visibilityState` and can stall its background frames, which is exactly the interference the
+   * non-destructive-observation rule forbids. It still enters this queue (serialised with writes) —
+   * only the foreground switch is skipped.
+   */
+  async run(operation, { signal, sessionId = 'anonymous', agent = false, action, activate = true } = {}) {
+    signal = this.#effectiveSignal(signal);
     checkAbort(signal);
     this.inflight += 1;
     // Everything that can throw after the counter moved must sit inside the try/finally below:
@@ -4392,7 +5092,9 @@ export class Runtime {
         this.active += 1;
       }
       // The page being operated must be the compositing one, otherwise its preview freezes.
-      this.activate();
+      // A pure observation opts out (`activate:false`) so looking at somebody's page cannot move
+      // their foreground page or toggle their `visibilityState`.
+      if (activate) this.activate();
       await abortable(previous, signal);
       checkAbort(signal);
       if (agent) this.claim(sessionId);
@@ -6340,6 +7042,45 @@ export class Runtime {
     };
   }
 
+  /**
+   * Refresh the human-foreground claim for this runtime (`browser_annotation`).
+   *
+   * Only the authenticated panel sends the report (it does so on `/state`, `/frame` and `/metrics`
+   * for the tab it is actually displaying, and stops as soon as it is hidden or another tab is
+   * selected). The Agent cannot raise its own claim through any tool: this method is reachable only
+   * from the scoped GUI routes.
+   */
+  noteGuiForeground(viewId = null) {
+    this.annot.guiForegroundAt = Date.now();
+    this.annot.guiForegroundView = typeof viewId === 'string' && viewId.length > 0 ? viewId : 'primary';
+  }
+
+  /**
+   * Is this runtime the tab a human is looking at right now?
+   *
+   * `active` is a *freshness* answer, never a stored permission: it goes false on its own within
+   * `ANNOTATION_FOREGROUND_TTL_MS` when the panel stops reporting (tab switched away, panel closed,
+   * DSH tab backgrounded). A dead page is never in the foreground.
+   */
+  guiForeground() {
+    const at = Number(this.annot.guiForegroundAt) || 0;
+    const ageMs = at > 0 ? Math.max(0, Date.now() - at) : null;
+    return {
+      active: this.running && at > 0 && ageMs !== null && ageMs <= ANNOTATION_FOREGROUND_TTL_MS,
+      viewId: this.annot.guiForegroundView || null,
+      ageMs,
+      maxAgeMs: ANNOTATION_FOREGROUND_TTL_MS,
+    };
+  }
+
+  /** The document's shapes for a read-modify-write, or [] when the document is not this one. */
+  annotationCurrentShapes() {
+    this.#annotationPrune();
+    const document = this.annot.document;
+    if (!document || !document.context || document.context.documentKey !== this.annot.documentKey) return [];
+    return document.shapes.map((shape) => JSON.parse(JSON.stringify(shape)));
+  }
+
   /** Rotate the navigation token and drop everything stored under the old one (§11.2). */
   #annotationRotate(reason) {
     const hadDocument = this.annot.document !== null;
@@ -6394,6 +7135,9 @@ export class Runtime {
         : { droppedShapes: 0, droppedPoints: 0, shortenedTextCodeUnits: 0 },
       stale,
       staleReason,
+      // Human-foreground claim (docs/viewport-control.md): `browser_annotation` writes are refused
+      // unless `active` is true. Computed at read time, never stored in the document.
+      foreground: this.guiForeground(),
     };
   }
 
@@ -6427,13 +7171,17 @@ export class Runtime {
       space: ANNOTATION_SPACE,
       revision: this.annot.revision + 1,
       updatedAt,
-      source: {
-        kind: 'human-panel',
-        panelId: request.panelId,
-        surface: request.surface,
-        clientRevision: request.clientRevision,
-        trusted: false,
-      },
+      // A panel publish cites the panel; `browser_annotation` passes its own source so a document
+      // written by the Agent never claims a human drew it (`trusted` stays false either way).
+      source: request.source
+        ? { ...request.source }
+        : {
+          kind: 'human-panel',
+          panelId: request.panelId,
+          surface: request.surface,
+          clientRevision: request.clientRevision,
+          trusted: false,
+        },
       context: this.annotationContext(),
       view: { ...request.view },
       shapes: shapes.map((shape) => JSON.parse(JSON.stringify(shape))),
@@ -6511,6 +7259,132 @@ export class Runtime {
     return ack(true, false, request.clientRevision);
   }
 
+  /** The annotation document's `view` snapshot for an Agent write (canvas CSS px space). */
+  #annotationAgentView() {
+    const view = this.view;
+    const content = this.contentProjection();
+    return {
+      canvasX: view.canvasX,
+      canvasY: view.canvasY,
+      x: view.x,
+      y: view.y,
+      width: view.width,
+      height: view.height,
+      scale: view.scale,
+      contentWidth: content.width,
+      contentHeight: content.height,
+      viewRevision: view.revision,
+      frameEpoch: this.frames && Number.isFinite(this.frames.epoch) ? this.frames.epoch : null,
+    };
+  }
+
+  /**
+   * `browser_annotation` — the Agent's half of the same document (docs/viewport-control.md).
+   *
+   * Read-modify-write on ONE shape list: a human note is never overwritten by a draw, and an Agent
+   * note survives the human's next edit because the panel hydrates this document before it
+   * publishes its own. Every refusal happens before any state is touched, and nothing here starts a
+   * page, takes the page lease, dispatches CDP or writes page `lastError`.
+   *
+   * @param {{action:string, specs:ReadonlyArray<object>, ids:ReadonlyArray<string>,
+   *   point:{x:number,y:number,radius:number}|null, expectRevision:number|null}} call
+   *   Output of `normalizeAgentAnnotationCall` (already structurally validated).
+   * @param {{sessionId?:string|null}} [options] Caller identity for the document's `source`.
+   */
+  agentAnnotation(call, options = {}) {
+    // `read` answers on a cold runtime too (the document is simply empty / stale=not-running);
+    // only a *write* needs a page, because only a running page has a panel showing it.
+    if (call.action !== 'read' && !this.running) {
+      throw annotationInvalid('runtime', 'annotation-runtime-not-running');
+    }
+    const foreground = this.guiForeground();
+    if (call.action !== 'read' && !foreground.active) {
+      // The whole point of an Agent note is that a human sees it: drawing on a tab nobody displays
+      // would be an invisible write. Zero writes, and the caller is told what has to change.
+      throw new BrowserError(
+        'ANNOTATION_NOT_FOREGROUND',
+        '标注只能画在人类当前选中的标签页上：请在调试视图里选中该标签页并保持可见后重试（本次零写入）',
+        {
+          reason: 'annotation-not-foreground',
+          viewId: foreground.viewId,
+          ageMs: foreground.ageMs,
+          maxAgeMs: foreground.maxAgeMs,
+        },
+      );
+    }
+    const current = this.annotationCurrentShapes();
+    if (call.expectRevision !== null && call.expectRevision !== this.annot.revision) {
+      throw new BrowserError('ANNOTATION_REVISION_CONFLICT', '标注文档 revision 已变化：本次零写入，请先读取最新文档', {
+        reason: 'annotation-revision-conflict',
+        expectedRevision: call.expectRevision,
+        currentRevision: this.annot.revision,
+      });
+    }
+    if (call.action === 'read') {
+      return { ok: true, action: 'read', removed: [], ...this.annotationsDocument() };
+    }
+    let shapes = current;
+    const removed = [];
+    let shortenedText = 0;
+    if (call.action === 'draw') {
+      const allocateId = annotationAgentIdFactory(current, call.specs);
+      const seenIds = new Set(current.map((shape) => shape.id));
+      const added = [];
+      for (let index = 0; index < call.specs.length; index += 1) {
+        const result = normalizeAgentAnnotationShape(call.specs[index], `shapes[${index}]`, allocateId, seenIds);
+        added.push(result.shape);
+        shortenedText += result.shortenedText;
+      }
+      shapes = current.concat(added);
+    } else if (call.action === 'erase') {
+      const ids = new Set(call.ids);
+      shapes = current.filter((shape) => {
+        if (ids.has(shape.id)) { removed.push(shape.id); return false; }
+        if (call.point && annotationAgentHit(shape, call.point, call.point.radius)) { removed.push(shape.id); return false; }
+        return true;
+      });
+    } else {
+      for (const shape of current) removed.push(shape.id);
+      shapes = [];
+    }
+    const limited = applyAnnotationLimits(
+      shapes,
+      { droppedShapes: 0, droppedPoints: 0, shortenedTextCodeUnits: 0 },
+      shortenedText,
+    );
+    const updatedAt = Date.now();
+    const request = {
+      // No panel watermark is consumed: an Agent write must never satisfy a stale panel revision.
+      panelId: null,
+      surface: 'main',
+      clientRevision: 0,
+      view: this.#annotationAgentView(),
+      source: {
+        kind: 'agent-tool',
+        tool: 'browser_annotation',
+        agentSessionId: options.sessionId ? String(options.sessionId) : null,
+        surface: 'main',
+        trusted: false,
+      },
+    };
+    let finalShapes = limited.shapes;
+    let truncation = limited.truncation;
+    let document = this.#annotationBuild(request, finalShapes, truncation, updatedAt);
+    // Same byte budget as a panel publish: drop the oldest whole shapes, never a half shape.
+    while (Buffer.byteLength(JSON.stringify(document), 'utf8') > ANNOTATION_LIMITS.maxDocumentBytes
+      && finalShapes.length > 0) {
+      finalShapes = finalShapes.slice(1);
+      truncation = { ...truncation, droppedShapes: truncation.droppedShapes + 1 };
+      document = this.#annotationBuild(request, finalShapes, truncation, updatedAt);
+    }
+    this.annot.revision += 1;
+    document.revision = this.annot.revision;
+    this.annot.document = document;
+    this.annot.updatedAt = updatedAt;
+    this.annot.lastSeenAt = updatedAt;
+    return { ok: true, action: call.action, removed, ...this.annotationsDocument() };
+  }
+
   /** One HTTP-poll response in the historical shape plus frame metadata and epoch. */
   framePayload(since, state = this.state()) {
     const latest = this.frames.latest();
@@ -6729,30 +7603,155 @@ export class Runtime {
     return { moved: true, direction };
   }
 
-  async input(events, signal) {
-    if (!Array.isArray(events) || events.some((event) => !event || !['mouse', 'wheel', 'key', 'text'].includes(event.kind))) {
+  /** Drop the held-key table and the virtual cursor (document replaced or page closed). */
+  resetInputState() {
+    this.inputState.keys.clear();
+    this.inputState.cursor = null;
+  }
+
+  /** Modifier bits (CDP Alt=1/Ctrl=2/Meta=4/Shift=8) of every key this page holds down. */
+  #heldModifierBits() {
+    let bits = 0;
+    for (const modifier of this.inputState.keys.values()) bits |= modifier;
+    return bits;
+  }
+
+  /**
+   * Dispatch input events through the held-key state machine (docs/tools.md `browser_input`).
+   *
+   * Three things a real keyboard/mouse gives a page for free, and a stream of independent CDP
+   * dispatches does not:
+   *   1. **modifier synthesis** — while Shift is down, every later key/mouse/wheel event carries
+   *      `shiftKey:true`. The page's own `keydown` bookkeeping is not enough: `e.shiftKey` comes
+   *      from the browser, not from the page's listener.
+   *   2. **relative motion** — `deltaX/deltaY` advance a virtual cursor, so pointer-lock style
+   *      "move by delta" callers never have to know the absolute position.
+   *   3. **a release path** — `keyUp` clears the entry, and a replaced document clears everything
+   *      (a stale held key would otherwise keep marking events as Shift-pressed forever).
+   *
+   * @returns {{applied:number, modifiers:number, held:string[], cursor:{x:number,y:number}|null}}
+   */
+  async input(events, signal) {
+    if (!Array.isArray(events) || events.some((event) => !event || !['mouse', 'wheel', 'key', 'text'].includes(event.kind))) {
       throw new BrowserError('INVALID_ARGUMENT', '输入事件 kind 无效');
     }
     if (events.length > INPUT_EVENT_LIMIT) {
       throw new BrowserError('INVALID_ARGUMENT', `单批输入事件过多：${events.length} > ${INPUT_EVENT_LIMIT}`, { maxItems: INPUT_EVENT_LIMIT });
     }
     // Normalize/validate the whole batch first: a bad modifiers value must not start Chromium.
-    const prepared = events.map((event) => prepareInputEvent(event));
+    const prepared = events.map((event) => ({ event, prepared: prepareInputEvent(event) }));
     await this.ensure(signal);
-    for (const event of prepared) {
-      if (event.kind === 'mouse' || event.kind === 'wheel') {
-        await this.send('Input.dispatchMouseEvent', event.params, signal);
-      } else if (event.kind === 'key') {
-        await this.send('Input.dispatchKeyEvent', event.params, signal);
-      } else if (event.kind === 'text') {
-        await this.send('Input.insertText', event.params, signal);
+    const viewport = this.viewport;
+    for (const item of prepared) {
+      const { event } = item;
+      const params = item.prepared.params;
+      if (item.prepared.kind === 'key') {
+        const type = String(params.type || '').toLowerCase();
+        const identity = inputKeyIdentity(event);
+        const modifier = inputKeyModifier(event);
+        const synthesize = event.synthesizeModifiers !== false;
+        // A keyUp still reports the modifier it is releasing; a press reports the state *before*
+        // it lands (same order a real OS produces).
+        params.modifiers = (Number(params.modifiers) || 0) | (synthesize ? this.#heldModifierBits() : 0);
+        if (identity) {
+          if (inputPressesKey(type)) this.inputState.keys.set(identity, modifier);
+          else if (type === 'keyup') this.inputState.keys.delete(identity);
+        }
+      } else if (item.prepared.kind === 'mouse' || item.prepared.kind === 'wheel') {
+        if (event.synthesizeModifiers !== false) {
+          params.modifiers = (Number(params.modifiers) || 0) | this.#heldModifierBits();
+        }
+        if (item.prepared.kind === 'mouse') {
+          const hasDelta = Number.isFinite(event.deltaX) || Number.isFinite(event.deltaY);
+          if (hasDelta) {
+            if (!params.type) params.type = 'mouseMoved';
+            const base = this.inputState.cursor
+              || { x: Math.round(viewport.width / 2), y: Math.round(viewport.height / 2) };
+            const next = {
+              x: Math.min(Math.max(0, base.x + (Number.isFinite(event.deltaX) ? event.deltaX : 0)), Math.max(0, viewport.width - 1)),
+              y: Math.min(Math.max(0, base.y + (Number.isFinite(event.deltaY) ? event.deltaY : 0)), Math.max(0, viewport.height - 1)),
+            };
+            params.x = next.x;
+            params.y = next.y;
+            this.inputState.cursor = { ...next };
+            if (params.type === 'mouseMoved' && !Number.isFinite(event.buttons)) params.buttons = 0;
+          } else if (Number.isFinite(params.x) && Number.isFinite(params.y)) {
+            this.inputState.cursor = { x: params.x, y: params.y };
+          }
+        }
+      }
+      if (item.prepared.kind === 'mouse' || item.prepared.kind === 'wheel') {
+        await this.send('Input.dispatchMouseEvent', params, signal);
+      } else if (item.prepared.kind === 'key') {
+        await this.send('Input.dispatchKeyEvent', params, signal);
+      } else if (item.prepared.kind === 'text') {
+        await this.send('Input.insertText', params, signal);
       }
     }
     // A wheel/click/drag can move the page (momentum/smooth scroll/snap): two coalesced settling
     // samples, 50ms and 250ms after the dispatch (docs/viewport-control.md).
     this.refreshViewObservationSoon({ delayMs: 50 });
     this.refreshViewObservationSoon({ delayMs: 250 });
-    return events.length;
+    return {
+      applied: events.length,
+      modifiers: this.#heldModifierBits(),
+      held: [...this.inputState.keys.keys()],
+      cursor: this.inputState.cursor ? { ...this.inputState.cursor } : null,
+    };
+  }
+
+  /**
+   * Panel-side `<select>` write (`POST /select`).
+   *
+   * One DOM write through the page: the native `selectedIndex` setter plus `input`/`change`.
+   * Bound requests validate the document and resolve the original node before writing; compatibility
+   * requests may use a selector or focus. The write stays in the serial queue; the guards in the HTTP route
+   * (same order as `/input`) and complete before this method is reached.
+   */
+  async selectValue(request, signal) {
+    await this.ensure(signal);
+    let answer;
+    if (request.target) {
+      const stale = () => new BrowserError('INVALID_ARGUMENT', '下拉目标已变化，请重新打开', { reason: 'stale-target' });
+      const tree = await this.send('Page.getFrameTree', {}, signal);
+      // A bound `<select>` may live in a same-process child frame: validate the target document
+      // against the whole frame tree, not just the root frame.
+      if (!frameTreeHasLoaderId(tree && tree.frameTree, request.target.loaderId)) throw stale();
+      let objectId;
+      try {
+        const resolved = await this.send('DOM.resolveNode', { backendNodeId: request.target.backendNodeId }, signal);
+        objectId = resolved?.object?.objectId;
+      } catch (error) {
+        if (['ABORTED', 'CDP_TIMEOUT', 'CDP_DISCONNECTED'].includes(error?.code)) throw error;
+        throw stale();
+      }
+      if (!objectId) throw stale();
+      try {
+        answer = await this.send('Runtime.callFunctionOn', {
+          objectId,
+          functionDeclaration: `function () { return ${selectWriteExpression(request, { objectBound: true })}; }`,
+          returnByValue: true,
+          userGesture: true,
+        }, signal);
+      } finally {
+        try { await this.send('Runtime.releaseObject', { objectId }, signal); } catch { /* best effort */ }
+      }
+    } else {
+      answer = await this.send('Runtime.evaluate', {
+        expression: selectWriteExpression(request),
+        returnByValue: true,
+        awaitPromise: false,
+        userGesture: true,
+      }, signal);
+    }
+    if (answer && answer.exceptionDetails) {
+      const details = answer.exceptionDetails;
+      const description = details.exception ? details.exception.description : details.text;
+      throw new BrowserError('EVAL_ERROR', String(description || '<select> 写入失败'));
+    }
+    const classified = classifySelectWrite(answer && answer.result ? answer.result.value : null);
+    if (!classified.ok) throw new BrowserError(classified.code, classified.message, classified.details);
+    return classified;
   }
 
   async evaluate(expression, awaitPromise = true, signal) {
@@ -6846,13 +7845,19 @@ export class Runtime {
    * unchanged; only a protocol error, empty data or a capture failure without a more fitting code
    * becomes CAPTURE_FAILED.
    */
-  async capture({ scale = 1, region, scaleSource = 'explicit' } = {}, signal) {
+  async capture({ scale = 1, region, scaleSource = 'explicit', includeAnnotations = false } = {}, signal) {
     const capturedAt = Date.now();
     // The resolved density source travels with the capture so evidence can say whether the caller
     // asked for this scale or the shared view.scale supplied it (docs/viewport-control.md).
     const resolvedScaleSource = scaleSource === 'view' ? 'view' : 'explicit';
     const viewRevisionAtCapture = this.view.revision;
     await this.ensure(signal);
+    // Freeze the accepted panel document once, before sampling page pixels. Mid-capture edits
+    // cannot mix revisions, and a navigation during either stage fails closed.
+    const annotationDocument = includeAnnotations ? this.annotationsDocument() : null;
+    const annotationContext = includeAnnotations ? this.annotationContext() : null;
+    const finish = shot => includeAnnotations
+      ? this.compositeCaptureAnnotations(shot, annotationDocument, annotationContext, signal) : shot;
     const deviceScaleFactor = 1;
     const effectiveScale = scale * deviceScaleFactor;
 
@@ -6996,11 +8001,11 @@ export class Runtime {
           phase: 'captureScreenshot', reason: 'empty-bytes',
         });
       }
-      return {
+      return finish({
         base64: shot.data,
         pngBytes,
         capture: { ...baseCapture, pageCapture: null },
-      };
+      });
     }
 
     // O ≠ 0 must be composited (docs/viewport-control.md + the 2026-11-02 negative-clip spike):
@@ -7079,11 +8084,82 @@ export class Runtime {
         phase: 'encodeComposite', reason: redactText(String(error && error.message ? error.message : error)).slice(0, 200),
       });
     }
-    return {
+    return finish({
       base64: pngBytes.toString('base64'),
       pngBytes,
       capture: { ...baseCapture, pageCapture, composite: true },
+    });
+  }
+
+  /** Opt-in panel overlay. Raw capture/T3/T4 callers keep the original PNG path. */
+  async compositeCaptureAnnotations(shot, document, context, signal) {
+    const assertContext = () => {
+      const current = this.annotationContext();
+      if (current.documentKey !== context.documentKey
+        || current.pageGeneration !== context.pageGeneration
+        || current.documentEpoch !== context.documentEpoch) {
+        throw new BrowserError('CAPTURE_FAILED', '截图期间页面已切换，请重新读取标注并截图', {
+          phase: 'annotationOverlay', reason: 'annotation-context-changed',
+        });
+      }
     };
+    assertContext();
+    if (document.shapes.length && (!document.context
+      || document.context.documentKey !== context.documentKey
+      || document.context.pageGeneration !== context.pageGeneration
+      || document.context.documentEpoch !== context.documentEpoch)) {
+      throw new BrowserError('CAPTURE_FAILED', '标注与截图不属于同一页面文档', {
+        phase: 'annotationOverlay', reason: 'annotation-context-changed',
+      });
+    }
+    const annotations = {
+      enabled: true, composited: false, space: document.space,
+      revision: document.revision, updatedAt: document.updatedAt,
+      source: document.source, context: document.context,
+      shapeCount: document.shapes.length,
+      stale: document.stale, staleReason: document.staleReason,
+      truncated: document.truncated, truncation: document.truncation,
+    };
+    shot.capture.annotations = annotations;
+    if (!document.shapes.length) return shot;
+    const png = inspectPng(shot.pngBytes, { checkCrc: true });
+    if (!png.ok) throw new BrowserError('INVALID_PNG', '叠加前的页面 PNG 校验失败', { phase: 'annotationOverlay' });
+    const expected = expectedPixelSize({
+      width: shot.capture.region.width, height: shot.capture.region.height,
+      scale: shot.capture.effectiveScale, deviceScaleFactor: 1,
+    });
+    const size = checkPixelSize({ width: png.width, height: png.height }, expected);
+    if (!size.ok) throw new BrowserError(size.code, '叠加前的页面 PNG 尺寸不符', size.details);
+    const renderer = webHostNamespace('annotation-capture');
+    try {
+      const tree = await this.send('Page.getFrameTree', {}, signal);
+      const world = await this.send('Page.createIsolatedWorld', {
+        frameId: tree.frameTree.frame.id, worldName: 'dsh-annotation-capture',
+      }, signal);
+      const input = { shapes: document.shapes, region: shot.capture.region, width: png.width, height: png.height };
+      // A detached OffscreenCanvas in an isolated world avoids page prototype overrides and CSP
+      // image restrictions. No DOM insertion, image load, page state or extra browser tab.
+      const rendered = await this.send('Runtime.evaluate', {
+        contextId: world.executionContextId,
+        expression: `(${renderer.renderAnnotationOverlay.toString()})(${JSON.stringify(input)})`,
+        awaitPromise: true, returnByValue: true,
+      }, signal);
+      if (rendered.exceptionDetails || !rendered.result?.value?.base64) {
+        throw new BrowserError('CAPTURE_FAILED', '标注离屏绘制失败', { phase: 'annotationOverlay', reason: 'raster-failed' });
+      }
+      assertContext();
+      const page = decodePng(shot.pngBytes);
+      const overlay = decodePng(Buffer.from(rendered.result.value.base64, 'base64'));
+      if (!page.ok || !overlay.ok) {
+        throw new BrowserError('CAPTURE_FAILED', '标注叠加 PNG 无法解码', { phase: 'annotationOverlay' });
+      }
+      const pixels = renderer.compositeAnnotationPixels(page, overlay);
+      const pngBytes = encodePngRgba(pixels);
+      annotations.composited = true;
+      return { ...shot, pngBytes, base64: pngBytes.toString('base64') };
+    } catch (error) {
+      throw this.#captureError(error, 'annotationOverlay');
+    }
   }
 
   /**
@@ -10646,6 +11722,9 @@ export class Runtime {
     // §11.2): rotate the navigation token and drop the stored document with it, so a late publish
     // can only be refused as `annotation-context-stale`.
     this.#annotationRotate('document');
+    // A new document has no keys held and no known cursor: keeping them would synthesize modifiers
+    // from a page that no longer exists (docs/tools.md, browser_input).
+    this.resetInputState();
   }
 
   #t2ReleaseGroup(objectGroup) {
@@ -12185,7 +13264,8 @@ export class Runtime {
       this.dynamic.session = null;
       this.dynamic.sink = null;
     } catch { /* evidence only */ }
-    this.frames.stop();
+    // Teardown must never construct the lazily loaded Web chain (A14): stop only what exists.
+    if (this.#frames) this.#frames.stop();
     // Network collector teardown: release held requests (never leave a paused request behind),
     // stop collecting, drop child-session bookkeeping. Exported evidence files stay on disk.
     try { await this.#netReleaseAllHeld(); } catch { /* ignore */ }
@@ -12194,7 +13274,7 @@ export class Runtime {
     this.netReq.clear();
     this.netHops.clear();
     this.netCacheHits.clear();
-    if (this.net) this.net.stop();
+    if (this.#net) this.#net.stop();
     this.network.length = 0;
     this.requests.clear();
     this.url = '';
@@ -12257,6 +13337,14 @@ const SCOPE_HEADER_BINDING = 'x-ui-testing-scope-binding';
  */
 const SCOPE_HEADER_TAB = 'x-ui-testing-scope-tab';
 const SCOPE_TAB_PRIMARY = 'primary';
+/**
+ * "This runtime is my selected tab and I am visible" (P0-D `browser_annotation`).
+ *
+ * Only the authenticated panel sends it, and only while it is displaying that tab — a selected
+ * internal tab, its DSH seat visible, and the GUI page itself not hidden. It is a claim, not a
+ * permission: the Host only turns it into a short freshness window, and `read` never needs it.
+ */
+const SCOPE_HEADER_FOREGROUND = 'x-ui-testing-gui-foreground';
 const SCOPE_SPECIAL_VALUES = new Set(['recent', 'unassigned']);
 
 function headerValue(headers, name) {
@@ -12350,10 +13438,36 @@ function scopeHttpStatus(code) {
     case 'SCOPE_NOT_FOUND': return 404;
     case 'SCOPE_UNAVAILABLE': return 503;
     case 'RUNTIME_LIMIT': return 503;
+    // Team/page access model (M2a, ruling §7.3). The HTTP surface must answer with the same code
+    // the tool surface uses, otherwise a refused page write looks like a Host crash over HTTP.
+    case 'TAB_FORBIDDEN': return 403;
+    case 'TAB_NOT_FOUND': return 404;
+    case 'TARGET_GONE': return 410;
+    case 'TAB_CONTROL_CHANGED': return 409;
+    case 'TAB_OWNERSHIP_STALE': return 409;
+    case 'TAB_OBSERVATION_STALE': return 409;
+    case 'TAB_LIMIT': return 409;
+    case 'TAB_IDENTITY_UNAVAILABLE': return 503;
+    case 'OBSERVATION_UNAVAILABLE': return 503;
+    case 'TARGET_NOT_BOUND': return 400;
+    case 'INVALID_ARGUMENT': return 400;
     default: return 500;
   }
 }
 
+/**
+ * Codes that are *pre-dispatch refusals* and must never become a page's `lastError` (ruling §7.3).
+ *
+ * A page's lastError answers "what went wrong with this page". "You may not write it", "your
+ * revision is stale" and "the budget is full" are answers about the *caller*, and writing them onto
+ * the target would blame the page — and its owner — for somebody else's refusal.
+ */
+const NON_PAGE_ERROR_CODES = new Set([
+  'TAB_FORBIDDEN', 'TAB_NOT_FOUND', 'TAB_CONTROL_CHANGED', 'TAB_OWNERSHIP_STALE',
+  'TAB_OBSERVATION_STALE', 'TAB_IDENTITY_UNAVAILABLE', 'TAB_LIMIT', 'OBSERVATION_UNAVAILABLE',
+  'RUNTIME_LIMIT', 'TARGET_NOT_BOUND', 'INVALID_ARGUMENT', 'SCOPE_FORBIDDEN', 'SCOPE_NOT_FOUND',
+]);
+
 function hostService(ctx, name) {
   try {
     if (ctx && typeof ctx.get === 'function') {
@@ -12456,14 +13570,138 @@ async function resolveSessionScope(ctx, sessionId, { cwd, signal } = {}) {
   return sessionScope(sessionId);
 }
 
+/**
+ * The fake registry a host *without* `ctx.agents` gets (M2a).
+ *
+ * It can only ever confirm the exact object the host already attached to this execution, and it is
+ * one stable instance so the resolver's `membershipRevision` does not churn merely because a fresh
+ * adapter object was passed on every call. It is not a second identity source: nothing else may
+ * write to it.
+ */
+const DEGRADED_AGENT_OBJECTS = new Map();
+const DEGRADED_AGENT_REGISTRY = {
+  get(id) { return DEGRADED_AGENT_OBJECTS.get(String(id)); },
+};
+
+/**
+ * One stable stand-in object per Session id for the no-registry host.
+ *
+ * With no Agent registry there is nothing to compare against, so the *domain identity* is the
+ * Session id itself. Minting a fresh object per call would look — correctly, to the resolver — like
+ * a replaced instance, revoke the previous epoch and refuse every later call; callers legitimately
+ * pass copies of `exec.agent` (the acceptance suites spread it to attach a signal), so the copy must
+ * not be able to invalidate the domain.
+ */
+function degradedAgentIdentity(actorId) {
+  const id = String(actorId);
+  let canonical = DEGRADED_AGENT_OBJECTS.get(id);
+  if (canonical === undefined) {
+    canonical = Object.freeze({ id, degraded: 'host-has-no-agent-registry' });
+    DEGRADED_AGENT_OBJECTS.set(id, canonical);
+  }
+  return canonical;
+}
+
+/**
+ * Resolve the calling Agent's trusted Principal.
+ *
+ * Three host states, three different answers — conflating them is what makes a permission model
+ * either useless or unusable:
+ *   1. `ctx.agents` present: identity must be *proved*. The exact object must come back from
+ *      `agents.get(id)`, and the Team service (when installed) must return a native membership
+ *      whose root is still the exact registry object. `tryMembership === undefined` is
+ *      TAB_IDENTITY_UNAVAILABLE — never "this must be a standalone session".
+ *   2. `ctx.agents` present, `ctx.agentTeams` absent (Team plugin not installed): exact-object
+ *      proof plus the host's explicit standalone proof from ruling §2.2. The root is the actor, so
+ *      it reaches exactly its own pages.
+ *   3. `ctx.agents` absent (the acceptance harness, a non-Team host): there is nothing to compare
+ *      against, so the caller degrades to a standalone domain keyed by its own Session id. This is
+ *      the *only* allowed degradation and it is deliberately not a wildcard: a missing service
+ *      grants "my own domain", never "any page". Note it still cannot be forged — `exec.agent` is
+ *      put on the execution by the Host, and no tool argument, header or query can set it.
+ */
+function resolveToolPrincipal(ctx, exec) {
+  const agent = exec && exec.agent;
+  if (!agent || typeof agent !== 'object' || typeof agent.id !== 'string' || agent.id.trim() === '') {
+    // No subject at all: the documented legacy tool protocol (an old client, or a harness that
+    // drives tools without an exec identity). This is *not* "a session we could not verify" — there
+    // is no session — so it keeps its own isolated domain (`root:unscoped`, where `legacy:default`
+    // already lived) instead of being refused. It can therefore never reach an Agent's page, which
+    // is strictly stronger than the old behaviour where the legacy entry shared the workspace.
+    return resolvePrincipal(degradedAgentIdentity(UNSCOPED_ROOT), {
+      agentRegistry: DEGRADED_AGENT_REGISTRY,
+      teamService: undefined,
+      standaloneProof: () => true,
+    });
+  }
+  const agents = hostService(ctx, 'agents');
+  if (!agents || typeof agents.get !== 'function') {
+    return resolvePrincipal(degradedAgentIdentity(agent.id), {
+      agentRegistry: DEGRADED_AGENT_REGISTRY,
+      teamService: undefined,
+      standaloneProof: () => true,
+    });
+  }
+  const agentTeams = hostService(ctx, 'agentTeams');
+  const hasTeamService = Boolean(agentTeams)
+    && (typeof agentTeams.tryMembership === 'function' || typeof agentTeams.membership === 'function');
+  return resolvePrincipal(agent, {
+    agentRegistry: agents,
+    teamService: hasTeamService ? agentTeams : undefined,
+    // Without a Team service the host itself is the proof of "no team": the actor is its own root.
+    standaloneProof: hasTeamService ? undefined : () => true,
+  });
+}
+
+/**
+ * Principal for one **diagnostic dispatcher** probe (task-12), or `null` for every other call.
+ *
+ * `integration/diagnose.js` runs a fixed set of read-only probes against a page it already froze.
+ * That page belongs to a *root* (page groups are keyed by workspace × provider × root), so the probe
+ * has to act inside that root; the frozen entry records its owner, which is exactly the identity the
+ * probe is entitled to use.
+ *
+ * Why this is not an identity backdoor:
+ *   - it exists only when `exec.diagnosticScope.entry` is present, which only the diagnose
+ *     dispatcher sets — no tool call, header, argument or RPC can attach it;
+ *   - the entry was resolved by the same authenticated GUI scope resolution every other panel route
+ *     uses (session header, or a binding that must hit an existing runtime), so the panel could
+ *     already read that page through `/state|/frame`;
+ *   - the probe set and its arguments come from `DISPATCHER_ALLOWED` + `validateProbeArgs`
+ *     (expression `1`, snapshot, screenshot, computedStyle, network list): no navigation, no input,
+ *     no arbitrary script, and the response is a structural summary, never page content;
+ *   - the principal is `source:'panel'`, is never persisted into any long-lived record and cannot be
+ *     handed to another call, so it buys exactly one probe round.
+ *
+ * It deliberately does NOT consult `ctx.agents`: a panel may diagnose a session whose agent is not
+ * currently loaded, and the subject here is the panel acting on its own resolved page — not a turn.
+ */
+function diagnosticPrincipalFor(exec) {
+  const entry = exec?.diagnosticScope?.entry;
+  const owner = entry?.ownership?.ownerSessionId || entry?.rootSessionId || null;
+  if (!owner) return null;
+  return makePrincipal({
+    actorSessionId: String(owner),
+    rootSessionId: String(entry.rootSessionId || owner),
+    role: PRINCIPAL_ROLE.STANDALONE,
+    membershipRevision: 1,
+    executionEpoch: 1,
+    source: PRINCIPAL_SOURCE.PANEL,
+    hostEpoch: defaultTabPrincipalResolver().hostEpoch,
+  });
+}
+
 /** Tools carry the Agent's session header; no exec identity at all is the old protocol. */
-function toolScopeRequest(exec) {
+function toolScopeRequest(exec, principal = null) {
   const agent = exec && exec.agent;
   if (!agent || !agent.id) return { mode: 'legacy' };
   const headerCwd = agent.session && agent.session.header && agent.session.header.cwd;
   return {
     mode: 'session',
     sessionId: String(agent.id),
+    // The verified identity decides the page domain. A tool call never gets to name its own root:
+    // it is whatever `integration/tab-principal.js` proved from the exact agent object.
+    ...(principal ? { rootSessionId: principal.rootSessionId, creatorSessionId: principal.actorSessionId } : {}),
     ...(typeof headerCwd === 'string' && headerCwd ? { cwd: headerCwd } : {}),
     ...(exec && exec.signal ? { signal: exec.signal } : {}),
   };
@@ -12473,22 +13711,53 @@ function toolScopeRequest(exec) {
  * Resolve a parsed scope request to { key, scope }. A `binding` must hit an existing runtime
  * (404 otherwise) and is owner-only at the HTTP/WS layer; `recent` never falls back to legacy.
  */
+/**
+ * Resolve a parsed scope request to `{ key, scope, provider, rootSessionId, creatorSessionId }`.
+ *
+ * The **root** dimension is resolved here and nowhere else (M2a, ruling §7.4):
+ *   - a tool call supplies the verified Principal's root (`request.rootSessionId`);
+ *   - a bound/recent GUI request inherits the root of the entry it already names (the runtime id is
+ *     the only thing it knows, and it was minted inside one group);
+ *   - a session-addressed GUI request resolves to *that session's* domain, so a panel bound to a
+ *     session still shows exactly the page that session drives — the pre-M5 panel has no verified
+ *     actor of its own, and inventing one would be worse than reusing the addressed session id;
+ *   - the legacy protocol (no scope headers at all) gets `UNSCOPED_ROOT`, its own domain: an old
+ *     client must not silently inherit an Agent's page just because it named the workspace.
+ */
 async function resolveScopeRequest(ctx, registry, request) {
-  if (!request || request.mode === 'legacy') return LEGACY_SCOPE;
-  if (request.mode === 'unassigned') return UNASSIGNED_SCOPE;
+  if (!request || request.mode === 'legacy') return { ...LEGACY_SCOPE, rootSessionId: UNSCOPED_ROOT };
+  if (request.mode === 'unassigned') {
+    return { ...UNSCOPED_SCOPE_FACTORY(), rootSessionId: String(request.rootSessionId || UNSCOPED_ROOT) };
+  }
   if (request.mode === 'recent') {
-    const entry = registry.recentEntry();
-    return entry ? { key: entry.key, scope: entry.scope } : UNASSIGNED_SCOPE;
+    // A tool/GUI request that carries a root only follows that root; a rootless (legacy panel)
+    // request keeps the historical global pointer. See RuntimeRegistry#recentEntry.
+    const entry = registry.recentEntry(request.rootSessionId);
+    const rootSessionId = String(request.rootSessionId || entry?.rootSessionId || UNSCOPED_ROOT);
+    return entry
+      ? { key: entry.key, scope: entry.scope, provider: entry.provider, rootSessionId: entry.rootSessionId }
+      : { ...UNSCOPED_SCOPE_FACTORY(), rootSessionId };
   }
   if (request.mode === 'binding') {
     const entry = registry.findByRuntimeId(request.runtimeId);
     if (!entry) throw new BrowserError('SCOPE_NOT_FOUND', 'scope binding 指向的运行时不存在', { scope: 'binding' });
-    return { key: entry.key, scope: entry.scope };
+    // `key` is the entry's own page-group key (root + provider + workspace, or a PageTargetKey);
+    // the provider and root travel with it so a bound lookup never has to guess them back.
+    return { key: entry.key, scope: entry.scope, provider: entry.provider, rootSessionId: entry.rootSessionId };
   }
   // Bounded: tools pass exec.signal; HTTP/WS requests get a 5s metadata-read budget.
-  return resolveSessionScope(ctx, request.sessionId, { cwd: request.cwd, signal: request.signal || AbortSignal.timeout(5000) });
+  const resolved = await resolveSessionScope(ctx, request.sessionId, { cwd: request.cwd, signal: request.signal || AbortSignal.timeout(5000) });
+  const rootSessionId = String(request.rootSessionId || request.sessionId || UNSCOPED_ROOT);
+  return {
+    ...resolved,
+    rootSessionId,
+    creatorSessionId: String(request.creatorSessionId || request.sessionId || rootSessionId),
+  };
 }
 
+/** A fresh (mutable) copy of the unassigned scope so a root dimension can be attached. */
+function UNSCOPED_SCOPE_FACTORY() { return { key: UNASSIGNED_SCOPE.key, scope: UNASSIGNED_SCOPE.scope }; }
+
 function emptyMetrics() {
   return {
     ok: true,
@@ -12534,38 +13803,459 @@ export class RuntimeRegistry {
     this.selectedBySession = new Map();
     /** P0-E/T2: one monotonic ref allocator across all tabs of this registry. */
     this.nextGlobalRef = 1;
-    this.host = undefined;
+    /** provider -> BrowserHost. A provider only gets a host once its driver exists (§6). */
+    this.hosts = new Map();
+    /** base scope key -> provider that most recently used it (GUI/session fallback, §16 open item 2). */
+    this.providerByBaseKey = new Map();
     this.reservations = 0;
-    this.recentKey = undefined;
+    /** rootSessionId -> entry key of the last real interaction in that root (never cross-root). */
+    this.recentByRoot = new Map();
     this.disposed = false;
     this.sweeping = false;
     this.sweepTimer = setInterval(() => { this.sweep().catch(() => {}); }, Math.max(1000, Math.min(60000, Math.floor(idleMs / 4))));
     this.sweepTimer.unref?.();
   }
 
-  get pageCount() { return this.host ? this.host.pageCount : 0; }
+  /**
+   * Pages across **all** provider hosts. The page budget stays one global `maxPages`: splitting
+   * hosts must never multiply the ceiling, so every budget check compares this sum.
+   */
+  get pageCount() {
+    let total = 0;
+    for (const host of this.hosts.values()) total += host.pageCount;
+    return total;
+  }
 
-  browserHost() {
-    if (!this.host) this.host = new BrowserHost(this.log);
-    return this.host;
+  /**
+   * Compatibility accessor for host-idle checks only. It can never hand out another provider's host:
+   * a question about a non-chrome provider must go through `hostFor(provider)`.
+   */
+  get host() { return this.hosts.get(DEFAULT_RUNTIME_PROVIDER); }
+
+  /**
+   * Test/stepper seam for the default provider slot only — retained **solely** for the existing
+   * A12 stub injection in the acceptance suite; never use it on an execution path. It can never install a stub for another
+   * provider: a non-default provider is addressed through `hostFor`/`browserHost` and must have a
+   * real driver behind it.
+   */
+  set host(value) {
+    if (value === undefined || value === null) {
+      this.hosts.delete(DEFAULT_RUNTIME_PROVIDER);
+      return;
+    }
+    this.hosts.set(DEFAULT_RUNTIME_PROVIDER, value);
   }
 
-  peek(key) { return this.entries.get(key); }
+  /** Existing host for one provider, or undefined. Never creates, never substitutes chrome. */
+  hostFor(provider = DEFAULT_RUNTIME_PROVIDER) {
+    const id = typeof provider === 'string' && provider.length > 0 ? provider : DEFAULT_RUNTIME_PROVIDER;
+    return this.hosts.get(id);
+  }
 
+  /**
+   * Create (lazily) the host for one provider.
+   *
+   * A provider without a driver must never reach this point: `resolveWebDriver()` refuses
+   * `pending`/`unsupported` providers before any execution, exactly so an "edge" label cannot end up
+   * spawning Chrome (§8).
+   */
+  browserHost(provider = DEFAULT_RUNTIME_PROVIDER) {
+    const id = typeof provider === 'string' && provider.length > 0 ? provider : DEFAULT_RUNTIME_PROVIDER;
+    let host = this.hosts.get(id);
+    if (!host) {
+      host = new BrowserHost(this.log, { provider: id });
+      this.hosts.set(id, host);
+    }
+    return host;
+  }
+
+  /**
+   * Provider identity for one resolved scope request.
+   *
+   * `binding` is reserved for an *explicit* provider (the caller already knows which browser it
+   * means). Everything else resolves to "the provider that last touched this workspace" and is
+   * reported as `recent`, even when only one provider exists — callers never have to guess.
+   */
+  providerFor(resolved) {
+    const explicit = typeof resolved?.provider === 'string' && resolved.provider.length > 0
+      ? resolved.provider
+      : null;
+    if (explicit !== null) return { provider: explicit, providerResolved: 'binding' };
+    // The provider fallback is per (workspace, root): another root's last-used browser must never
+    // become this root's routing decision for the same workspace.
+    const recent = this.providerByBaseKey.get(providerIndexKey(resolved?.key, resolved?.rootSessionId));
+    return {
+      provider: typeof recent === 'string' && recent.length > 0 ? recent : DEFAULT_RUNTIME_PROVIDER,
+      providerResolved: 'recent',
+    };
+  }
+
+  /**
+   * Provider facts for a response, so a fallback never looks like an exact match.
+   * `resolved` (the lookup that produced the entry) wins: `binding` only when the caller named the
+   * provider; every fallback reports `recent`, even with a single provider installed.
+   */
+  providerFacts(entry, resolved = null) {
+    const providerResolved = resolved
+      ? this.providerFor(resolved).providerResolved
+      : (entry?.providerResolved === 'binding' ? 'binding' : 'recent');
+    return {
+      provider: entry?.provider ?? DEFAULT_RUNTIME_PROVIDER,
+      providerResolved,
+    };
+  }
+
+  peek(input) {
+    // Both addressing styles must produce the identical composed key (asserted in the contract suite).
+    if (typeof input === 'string') return this.entries.get(input);
+    if (!input || typeof input !== 'object') return undefined;
+    // A `binding` resolves to an entry key that ALREADY carries the provider prefix
+    // (`<provider>\0<base>`, or `<provider>\0<base>:view:<id>` for a child tab), so composing the
+    // provider again would double it and miss every bound runtime — that silently broke every
+    // panel request addressed by runtime id (child tab /state + /frame, the tab `+` and the `×`).
+    // Exact entry keys win; a bare workspace/scope key still goes through the provider composition.
+    const exact = this.entries.get(String(input.key));
+    if (exact) return exact;
+    // A binding/recent request already carries a composed page-group key: composing it again would
+    // manufacture a second root and silently miss the bound runtime.
+    if (isPageGroupKey(input.key)) return undefined;
+    const { provider } = this.providerFor(input);
+    return this.entries.get(pageGroupKeyFor(provider, input.key, input.rootSessionId));
+  }
+
+  /**
+   * Get (or lazily create) the page group of one (workspace, provider, **root**).
+   *
+   * The root dimension is what makes two independent sessions in one workspace stop sharing a
+   * page: their keys can never collide, so neither can address, evict or write the other's target.
+   * Creation is still cold (no page, no Chromium); it only binds an ownership record so the first
+   * real operation has an owner to authorise against.
+   */
   getOrCreate(resolved) {
     if (this.disposed) throw new BrowserError('SCOPE_UNAVAILABLE', '插件正在卸载');
-    const { key, scope } = resolved;
+    const { scope } = resolved;
+    const baseKey = resolved.key;
+    // A `recent` resolution hands back an ALREADY composed entry key (`<provider>\0<base>`), so
+    // composing the provider again would manufacture a second runtime — with its own page — for a
+    // workspace that already has one, on every `scope=recent` request (and it burns the global
+    // page budget until `+` answers TAB_LIMIT for a workspace with two tabs). An exact key wins.
+    const exact = this.entries.get(String(baseKey));
+    if (exact) return exact;
+    const { provider, providerResolved } = this.providerFor(resolved);
+    const rootSessionId = String(resolved.rootSessionId || UNSCOPED_ROOT);
+    // §6/§7.4: an entry is owned by (workspace, provider, root). `baseKey` stays the raw
+    // workspace/scope identity (aggregate counting and config transitions address it that way);
+    // the composed key carries all four dimensions and is never built by hand.
+    const key = pageGroupKeyFor(provider, baseKey, rootSessionId);
     const existing = this.entries.get(key);
     if (existing) return existing;
     if (this.entries.size >= this.maxEntries) this.#evictColdEntry();
-    const runtime = new Runtime(this.log, { host: this.browserHost(), origins: this.origins, scope, registry: this, viewerTtlMs: this.viewerTtlMs });
-    const entry = { key, scope, runtime, kind: 'primary', viewId: 'primary', primaryKey: key,
+    const runtime = new Runtime(this.log, {
+      host: this.browserHost(provider), origins: this.origins, scope, registry: this, viewerTtlMs: this.viewerTtlMs,
+    });
+    // Ownership is bound at first sight of the group, not at first page: an entry that exists but
+    // has no owner could never be authorised, and "no owner yet" would have to mean "anyone".
+    const creatorSessionId = String(resolved.creatorSessionId || resolved.sessionId || rootSessionId);
+    const access = makePageAccess({ rootSessionId, creatorSessionId });
+    const entry = { key, baseKey, provider, providerResolved, scope, runtime, kind: 'primary',
+      viewId: 'primary', primaryKey: key, rootSessionId,
+      ownership: access.ownership, control: access.control,
       parentRuntimeId: null, parentTabId: null, openEventId: null, createdBy: 'host',
       tabId: 'primary', createdAt: Date.now(), lastUsedAt: Date.now() };
     this.entries.set(key, entry);
+    this.providerByBaseKey.set(providerIndexKey(baseKey, rootSessionId), provider);
     return entry;
   }
 
+  /**
+   * Frozen M1 records of one physical page.
+   *
+   * Every entry (primary slot *and* child) carries its own ownership/control pair: a child page is
+   * a separate page with a separate controller, and sharing the primary's records would let a
+   * takeover of one silently authorise the other.
+   */
+  accessOf(entry) {
+    const target = entry || {};
+    return { ownership: target.ownership ?? null, control: target.control ?? null };
+  }
+
+  /** Replace an entry's records after a transition (M1 returns fresh frozen objects). */
+  setAccess(entry, next) {
+    if (!entry || !next) return;
+    entry.ownership = next.ownership;
+    entry.control = next.control;
+  }
+
+  /**
+   * Authorise one effect against one page, throwing the mapped structured error on refusal.
+   *
+   * This is the only place index.js turns a permission verdict into an error, so every surface
+   * reports the same code for the same reason (and the cross-root answer carries no details).
+   */
+  authorizePage(entry, principal, effect, operation = null, extra = {}) {
+    const { ownership, control } = this.accessOf(entry);
+    const verdict = authorize({ principal, ownership, control, effect, operation, ...extra });
+    if (verdict.allowed) return verdict;
+    throw this.accessError(verdict, operation);
+  }
+
+  accessError(verdict, operation) {
+    if (verdict.notFound || verdict.reason === AUTHORIZE_REASON.CROSS_ROOT) {
+      // Uniform, detail-free: a foreign root learns nothing about whether the page exists.
+      return new BrowserError('TAB_NOT_FOUND', '标签不存在或不属于当前调用者', {
+        hidden: true, operation: operation || null,
+      });
+    }
+    const reason = verdict.reason;
+    const message = reason === AUTHORIZE_REASON.ROLE_FORBIDDEN ? '当前会话无权操作该标签'
+      : reason === AUTHORIZE_REASON.NOT_CONTROLLER ? '该标签当前由其他会话控制（读取最新状态后重新决策，不要自动重试）'
+      : reason === AUTHORIZE_REASON.CONTROL_DRAINING ? '该标签正在被接管，旧版本写入已关闭'
+      : reason === AUTHORIZE_REASON.TARGET_RETIRED ? '该标签已关闭或退休'
+      : reason === AUTHORIZE_REASON.CONTROL_REVISION_STALE ? '标签控制版本已变化'
+      : reason === AUTHORIZE_REASON.OWNERSHIP_REVISION_STALE ? '标签归属版本已变化'
+      : reason === AUTHORIZE_REASON.IDENTITY_UNAVAILABLE ? '当前调用者身份无法证明'
+      : reason === AUTHORIZE_REASON.HOST_MANAGE_FORBIDDEN ? '该操作只能由独立宿主管理通道执行'
+      : '该操作不被允许';
+    return new BrowserError(verdict.code || 'TAB_FORBIDDEN', message, {
+      reason, effect: verdict.effect, resource: verdict.resource, operation: operation || null,
+    });
+  }
+
+  /**
+   * Read projection of one page's long-lived ownership/control (ruling §5: management replies carry
+   * `changed` plus the final controller/versions, so callers never re-derive them from `busy`).
+   */
+  controlProjection(entry) {
+    const { ownership, control } = this.accessOf(entry);
+    return {
+      accessVersion: 1,
+      tabId: entry ? this.#tabId(entry) : null,
+      rootSessionId: entry?.rootSessionId ?? null,
+      creatorSessionId: ownership?.creatorSessionId ?? null,
+      ownerSessionId: ownership?.ownerSessionId ?? null,
+      ownershipRevision: ownership?.ownershipRevision ?? null,
+      controllerSessionId: control?.controllerSessionId ?? null,
+      controlRevision: control?.controlRevision ?? null,
+      state: control?.state ?? null,
+      pendingControllerSessionId: control?.pendingControllerSessionId ?? null,
+    };
+  }
+
+  /**
+   * Undo our own drain marker, leaving the record byte-identical (ruling §5.2 step 6).
+   *
+   * Only the actor that started the drain may cancel it, and only while the record is still the one
+   * we drained (same state + same revision). Anything else is somebody else's move: the controller
+   * must never "quietly" change because our request finished late, so we simply do not touch it.
+   */
+  cancelDrain(entry, principal, expectedControlRevision) {
+    const { ownership, control } = this.accessOf(entry);
+    if (!control || control.state !== CONTROL_STATE.DRAINING) return false;
+    if (control.pendingControllerSessionId !== principal?.actorSessionId) return false;
+    if (control.controlRevision !== expectedControlRevision) return false;
+    try {
+      const cancelled = applyControlTransition({ ownership, control }, {
+        type: CONTROL_EVENT.ACQUIRE_CANCEL, principal, expectedControlRevision,
+      });
+      this.setAccess(entry, cancelled);
+      return true;
+    } catch {
+      // The record moved on (closed/retired/transferred): never invent a state we cannot prove.
+      return false;
+    }
+  }
+
+  /**
+   * Lead takeover: drain, wait for a safe boundary, then commit. Never abort in-flight work.
+   *
+   * Sequence (plan §5.2 / ruling §5.1):
+   *   1. root → role → expected control version, all before anything moves (zero dispatch on refuse)
+   *   2. mark draining: older writes now see a closed gate, while the controller is still the member
+   *   3. wait (bounded, cancellable) until nothing is queued or running — `active`/`inflight` reach 0,
+   *      which is host memory only: no CDP, no lease games, no interruption
+   *   4. re-read the version, then commit controller=Lead with controlRevision+1 — or, on
+   *      timeout/cancel/race, revoke the drain marker and report BUSY/ABORTED/CHANGED with the
+   *      controller exactly where it was
+   *
+   * @returns {{changed:boolean, ownership:object, control:object, state:string, waitedMs:number}}
+   */
+  async acquireControl(entry, principal, {
+    expectedControlRevision, timeoutMs = TAB_ACQUIRE_TIMEOUT_DEFAULT_MS, signal = undefined,
+  } = {}) {
+    this.authorizePage(entry, principal,
+      { effect: EFFECT.MANAGE, resource: RESOURCE.PAGE, targetRequired: true },
+      'browser_tabs.acquire', { expectedControlRevision });
+    const runtime = entry.runtime;
+    const startedAt = Date.now();
+    const drained = applyControlTransition(this.accessOf(entry), {
+      type: CONTROL_EVENT.ACQUIRE, principal, expectedControlRevision,
+    });
+    this.setAccess(entry, drained);
+    if (!drained.changed) {
+      return { changed: false, ownership: entry.ownership, control: entry.control, state: entry.control.state, waitedMs: 0 };
+    }
+
+    let outcome = 'settled';
+    try {
+      const deadline = startedAt + timeoutMs;
+      for (;;) {
+        if (runtime.active === 0 && runtime.inflight === 0) break;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) { outcome = 'timeout'; break; }
+        await this.#waitNextPoll(Math.min(TAB_DRAIN_POLL_MS, remaining), signal);
+      }
+    } catch (error) {
+      outcome = asBrowserError(error).code === 'ABORTED' ? 'aborted' : 'failed';
+    }
+
+    if (outcome === 'settled') {
+      const current = this.accessOf(entry);
+      const stillOurs = current.control
+        && current.control.state === CONTROL_STATE.DRAINING
+        && current.control.controlRevision === expectedControlRevision
+        && current.control.pendingControllerSessionId === principal.actorSessionId;
+      if (stillOurs) {
+        const committed = applyControlTransition(current, {
+          type: CONTROL_EVENT.ACQUIRE_COMMIT, principal, expectedControlRevision,
+        });
+        this.setAccess(entry, committed);
+        // The drain proved there is no in-flight work, so the member's stale "recently wrote" lease
+        // must not block the new controller's first write.
+        this.clearForeignLease(entry, principal.actorSessionId);
+        return {
+          changed: committed.changed, ownership: entry.ownership, control: entry.control,
+          state: entry.control.state, waitedMs: Date.now() - startedAt,
+        };
+      }
+      outcome = 'raced';
+    }
+
+    this.cancelDrain(entry, principal, expectedControlRevision);
+    const waitedMs = Date.now() - startedAt;
+    if (outcome === 'aborted') {
+      throw new BrowserError('ABORTED', '接管已取消：controller 与 controlRevision 均未改变', {
+        reason: 'acquire-cancelled', controlRevision: entry.control?.controlRevision ?? null, waitedMs,
+      });
+    }
+    if (outcome === 'raced') {
+      throw new BrowserError('TAB_CONTROL_CHANGED', '接管期间控制版本已变化（draining 已撤销）', {
+        reason: 'control-revision-stale', controlRevision: entry.control?.controlRevision ?? null, waitedMs,
+      });
+    }
+    if (outcome === 'failed') {
+      throw new BrowserError('TAB_CONTROL_CHANGED', '接管等待失败（draining 已撤销）', {
+        reason: 'drain-failed', controlRevision: entry.control?.controlRevision ?? null, waitedMs,
+      });
+    }
+    // BUSY, never "we finished it in the background": the drain marker is already gone.
+    throw new BrowserError('BUSY', `接管在 ${timeoutMs}ms 内未等到安全边界，已撤销 draining，controller 未改变`, {
+      reason: 'drain-timeout', timeoutMs, waitedMs, controlRevision: entry.control?.controlRevision ?? null,
+    });
+  }
+
+  /**
+   * A completed control transition voids the previous writer's short lease.
+   *
+   * The 15s lease only means "this session wrote recently"; it is not an ACL. Once control has moved
+   * — and the drain certified there is no in-flight work — keeping the old lease would refuse the new
+   * controller's very first write with BUSY, making the takeover useless for the 15s that follow.
+   */
+  clearForeignLease(entry, keepSessionId) {
+    const runtime = entry?.runtime;
+    if (!runtime || !runtime.lease) return false;
+    if (runtime.lease.sessionId === keepSessionId) return false;
+    runtime.release(runtime.lease.sessionId);
+    return true;
+  }
+
+  /** Lead gives control back to the owner (controlRevision+1, ownership untouched). */
+  releaseControl(entry, principal, { expectedControlRevision } = {}) {
+    this.authorizePage(entry, principal,
+      { effect: EFFECT.MANAGE, resource: RESOURCE.PAGE, targetRequired: true },
+      'browser_tabs.release', { expectedControlRevision });
+    const next = applyControlTransition(this.accessOf(entry), {
+      type: CONTROL_EVENT.RELEASE, principal, expectedControlRevision,
+    });
+    this.setAccess(entry, next);
+    this.clearForeignLease(entry, entry.ownership.ownerSessionId);
+    return { changed: next.changed, ownership: entry.ownership, control: entry.control, state: entry.control.state };
+  }
+
+  /**
+   * Lead transfers ownership+control to another valid member of this root.
+   *
+   * The roster is re-read from the native service **before** the metadata commit (ruling §2.2):
+   * a cached membership list could already be stale, and handing a page to somebody who left the
+   * team is exactly the kind of grant that must not survive on stale data.
+   */
+  transferControl(entry, principal, { toSessionId, expectedControlRevision, expectedOwnershipRevision } = {}) {
+    this.authorizePage(entry, principal,
+      { effect: EFFECT.MANAGE, resource: RESOURCE.PAGE, targetRequired: true },
+      'browser_tabs.transfer', { expectedControlRevision, expectedOwnershipRevision });
+    const row = this.assertTransferTarget(principal, toSessionId);
+    const next = applyControlTransition(this.accessOf(entry), {
+      type: CONTROL_EVENT.TRANSFER, principal, toSessionId: String(toSessionId).trim(),
+      expectedControlRevision, expectedOwnershipRevision,
+    });
+    this.setAccess(entry, next);
+    this.clearForeignLease(entry, String(toSessionId).trim());
+    return {
+      changed: next.changed, ownership: entry.ownership, control: entry.control,
+      state: entry.control.state, to: row,
+    };
+  }
+
+  /**
+   * Validate a transfer target against the **fresh** native roster.
+   *
+   * A transfer is a grant, so "cannot prove membership" must never read as "allowed": without a
+   * roster service the answer is TAB_IDENTITY_UNAVAILABLE, an unknown row is TAB_FORBIDDEN, and a
+   * failed/provisioning row is TAB_FORBIDDEN too. Self-transfer is an argument error.
+   */
+  assertTransferTarget(principal, toSessionId) {
+    const to = typeof toSessionId === 'string' ? toSessionId.trim() : '';
+    if (!to || to.length > 128) {
+      throw new BrowserError('INVALID_ARGUMENT', 'transfer.toSessionId 必须是 1–128 字符', { field: 'toSessionId' });
+    }
+    if (to === principal?.actorSessionId) {
+      throw new BrowserError('INVALID_ARGUMENT', 'transfer 不能转交给自己', { field: 'toSessionId' });
+    }
+    const teams = hostService(this.ctx, 'agentTeams');
+    const agents = hostService(this.ctx, 'agents');
+    if (!teams || typeof teams.listMembers !== 'function' || !agents || typeof agents.get !== 'function') {
+      throw new BrowserError('TAB_IDENTITY_UNAVAILABLE', 'transfer 需要原生 roster 才能证明目标成员身份', {
+        reason: 'transfer-needs-roster',
+      });
+    }
+    const rootAgent = agents.get(principal.rootSessionId);
+    if (!rootAgent) {
+      throw new BrowserError('TAB_IDENTITY_UNAVAILABLE', 'root 未加载，无法核对 roster', {
+        reason: 'root-not-loaded', rootSessionId: principal.rootSessionId,
+      });
+    }
+    let rows;
+    try {
+      rows = teams.listMembers(rootAgent);
+    } catch {
+      throw new BrowserError('TAB_IDENTITY_UNAVAILABLE', 'roster 读取失败', { reason: 'roster-failed' });
+    }
+    if (!Array.isArray(rows)) {
+      throw new BrowserError('TAB_IDENTITY_UNAVAILABLE', 'roster 形状异常', { reason: 'roster-malformed' });
+    }
+    const row = rows.find((candidate) => candidate && candidate.id === to);
+    if (!row) {
+      throw new BrowserError('TAB_FORBIDDEN', 'transfer 目标不是本 root 的成员', {
+        reason: 'not-a-member', toSessionId: to,
+      });
+    }
+    if (row.status === 'failed' || row.status === 'provisioning') {
+      throw new BrowserError('TAB_FORBIDDEN', 'transfer 目标成员当前无有效身份', {
+        reason: 'member-not-active', toSessionId: to, status: row.status,
+      });
+    }
+    return { id: row.id, role: row.role ?? null, status: row.status ?? null };
+  }
+
   findByRuntimeId(runtimeId) {
     if (typeof runtimeId !== 'string' || !runtimeId) return undefined;
     for (const entry of this.entries.values()) if (entry.runtime.runtimeId === runtimeId) return entry;
@@ -12584,9 +14274,27 @@ export class RuntimeRegistry {
     return this.entries.get(key) || (entry.kind === 'primary' ? entry : undefined);
   }
 
-  popupCount(primaryKey) {
+  /**
+   * Child pages of one **(workspace, provider)** — deliberately *not* of one root.
+   *
+   * The product budget is "4 pages per workspace/provider" (1 primary + 3 children). Counting per
+   * page-group key would turn that into "3 children per root", so two roots in one workspace could
+   * hold 8 pages there and the per-workspace ceiling would be multiplied by the root count. The
+   * global `maxPages` ceiling stays one number across every provider and root (a later quota slice
+   * rewrites the full reservation algorithm; this is the minimal correction that keeps today's
+   * numbers true).
+   */
+  popupCount(primaryEntry) {
+    if (!primaryEntry) return 0;
+    const workspaceKey = primaryEntry.baseKey;
+    const provider = primaryEntry.provider ?? DEFAULT_RUNTIME_PROVIDER;
     let count = 0;
-    for (const entry of this.entries.values()) if (entry.kind === 'popup' && entry.primaryKey === primaryKey) count += 1;
+    for (const entry of this.entries.values()) {
+      if (entry.kind !== 'popup') continue;
+      if (entry.baseKey !== workspaceKey) continue;
+      if ((entry.provider ?? DEFAULT_RUNTIME_PROVIDER) !== provider) continue;
+      count += 1;
+    }
     return count;
   }
 
@@ -12598,18 +14306,23 @@ export class RuntimeRegistry {
   /** Reserve one popup slot without ever evicting a parent or another workspace. */
   reservePopupSlot(primaryEntry) {
     if (this.disposed) throw new BrowserError('SCOPE_UNAVAILABLE', '插件正在卸载');
-    if (!primaryEntry) throw new BrowserError('TAB_LIMIT', '找不到 popup 所属的 primary 工作区');
-    if (this.popupCount(primaryEntry.key) >= this.maxPopupChildren) {
+    // A missing page group is a scope-resolution failure, never a tab-count limit: answering
+    // TAB_LIMIT here made the panel tell a user with two tabs "最多 4 个标签".
+    if (!primaryEntry) throw new BrowserError('SCOPE_NOT_FOUND', '找不到 popup 所属的 primary 工作区', { scope: 'binding' });
+    if (this.popupCount(primaryEntry) >= this.maxPopupChildren) {
       throw new BrowserError('TAB_LIMIT', `每个工作区最多 ${this.maxPopupChildren} 个 popup 子页`, {
-        maxPopupChildren: this.maxPopupChildren, popupCount: this.popupCount(primaryEntry.key),
+        dimension: 'workspace-provider',
+        maxPopupChildren: this.maxPopupChildren, popupCount: this.popupCount(primaryEntry),
       });
     }
-    const host = this.browserHost();
+    const provider = primaryEntry.provider ?? DEFAULT_RUNTIME_PROVIDER;
+    this.browserHost(provider);
     this.reservations += 1;
-    if (host.pageCount + this.reservations > this.maxPages) {
+    // Cross-provider sum against the *same* ceiling: splitting hosts must not widen the budget.
+    if (this.pageCount + this.reservations > this.maxPages) {
       this.reservations = Math.max(0, this.reservations - 1);
       throw new BrowserError('TAB_LIMIT', `popup 超出全局 ${this.maxPages} 页上限`, {
-        maxPages: this.maxPages, pageCount: host.pageCount, reservations: this.reservations,
+        maxPages: this.maxPages, pageCount: this.pageCount, reservations: this.reservations,
       });
     }
     let released = false;
@@ -12620,11 +14333,21 @@ export class RuntimeRegistry {
     };
   }
 
-  addPopupEntry({ parentEntry, runtime, viewId, openEventId, sourcePanelId }) {
+  addPopupEntry({ parentEntry, runtime, viewId, openEventId, sourcePanelId, creatorSessionId = null }) {
     const primaryKey = parentEntry.primaryKey || parentEntry.key;
-    const key = `${parentEntry.key}:view:${viewId}`;
+    // A child is its own target inside the same page group (ruling §7.4: PageTargetKey wraps the
+    // group key, never a hand-built colon suffix on a composed key).
+    const key = pageTargetKeyFor(primaryKey, viewId);
+    const access = makePageAccess({
+      rootSessionId: parentEntry.rootSessionId,
+      creatorSessionId: creatorSessionId || parentEntry.rootSessionId,
+    });
     const entry = {
-      key, scope: parentEntry.scope, runtime, kind: 'popup', viewId, tabId: viewId,
+      key, baseKey: parentEntry.baseKey ?? key, provider: parentEntry.provider ?? DEFAULT_RUNTIME_PROVIDER,
+      providerResolved: parentEntry.providerResolved ?? 'recent',
+      scope: parentEntry.scope, runtime, kind: 'popup', viewId, tabId: viewId,
+      rootSessionId: parentEntry.rootSessionId,
+      ownership: access.ownership, control: access.control,
       primaryKey, parentKey: parentEntry.key, parentRuntimeId: parentEntry.runtime.runtimeId,
       parentTabId: parentEntry.tabId || (parentEntry.kind === 'primary' ? 'primary' : parentEntry.viewId),
       openEventId: openEventId || null, sourcePanelId: sourcePanelId || null,
@@ -12751,13 +14474,59 @@ export class RuntimeRegistry {
       && entry.primaryKey === primaryKey && (entry.tabId === tabId || entry.viewId === tabId));
   }
 
+  /**
+   * Selection identity: one row per (page group, actor). Both dimensions matter — a selection is
+   * the *actor's* view of *their* group, so it can never be inherited across roots or actors.
+   */
   #selectionKey(primaryEntry, sessionId) {
-    return String(primaryEntry.key) + '\u0000' + String(sessionId || 'anonymous');
+    return makeActorSelectionKey({
+      groupKey: String(primaryEntry.key),
+      actorSessionId: String(sessionId || 'anonymous'),
+    });
   }
 
+  /**
+   * One actor's two selections inside one page group.
+   *
+   * `tabId` is the **work** selection and stays the compatibility projection (`selection` in every
+   * response). `observationTabId` is the read-only selection: it is set only by an explicit
+   * `select(mode:'observe')` and never by a write, so watching a teammate's page cannot redirect
+   * either side's writes.
+   */
   selectionFor(primaryEntry, sessionId) {
     const key = this.#selectionKey(primaryEntry, sessionId);
-    return this.selectedBySession.get(key) || { tabId: 'primary', revision: 0, resetReason: null, pendingReset: false };
+    const stored = this.selectedBySession.get(key);
+    if (stored) return stored;
+    const actor = String(sessionId || 'anonymous');
+    return {
+      // No record yet: default to the page this actor *already owns* in this group — its primary if
+      // it owns the primary, otherwise a child it created — and to "no work page" when it owns
+      // nothing. Defaulting a teammate to the Lead's primary turned "you have no page yet"
+      // (TARGET_NOT_BOUND, "open one") into "you may not touch this page" (TAB_FORBIDDEN), which is
+      // both the wrong code and a misleading story.
+      tabId: this.#ownWorkTabId(primaryEntry, actor),
+      observationTabId: null, revision: 0, resetReason: null, pendingReset: false,
+      groupKey: String(primaryEntry.key), actorSessionId: actor,
+      rootSessionId: primaryEntry.rootSessionId ?? rootOfPageGroupKey(primaryEntry.key),
+      workspaceKey: primaryEntry.baseKey ?? null, provider: primaryEntry.provider ?? null,
+    };
+  }
+
+  /**
+   * The tab id this actor already owns in the group, or `null` when it owns none.
+   *
+   * Ownership — not the short lease and not "the group has a primary" — decides it: a teammate that
+   * never opened a page must have no work selection at all rather than borrow somebody else's.
+   */
+  #ownWorkTabId(primaryEntry, actor) {
+    if (!primaryEntry) return null;
+    const primary = this.entries.get(primaryEntry.primaryKey || primaryEntry.key) || primaryEntry;
+    if (primary?.ownership?.ownerSessionId === actor) return this.#tabId(primary);
+    for (const entry of this.tabEntries(primaryEntry)) {
+      if (entry.kind !== 'popup') continue;
+      if (entry.ownership?.ownerSessionId === actor) return this.#tabId(entry);
+    }
+    return null;
   }
 
   /** Confirm a pending tab retirement (browser_tabs.current / explicit select). */
@@ -12769,49 +14538,97 @@ export class RuntimeRegistry {
     if (!record.pendingReset) return { ...record, confirmedResetReason: null };
     record.pendingReset = false;
     record.resetReason = null;
-    record.tabId = 'primary';
+    // Back to the page this actor actually owns (their own primary, a child they created, or
+    // nothing) — never blindly to "primary", which may belong to the Lead.
+    record.tabId = this.#ownWorkTabId(primaryEntry, String(sessionId || 'anonymous'));
+    record.observationTabId = null;
+    delete record.resetTabId;
     record.revision += 1;
     this.selectedBySession.set(key, record);
     return { ...record, confirmedResetReason: previous };
   }
 
-  /** Resolve the page tool target for one Agent session; pending retirement is a zero-dispatch error. */
-  resolveSessionTab(primaryEntry, sessionId) {
+  /**
+   * Resolve the page tool target for one Agent session.
+   *
+   * Reads use the observation selection when the caller set one, writes always use the work
+   * selection (plan §5: "只读默认 observationSelection，未设再取 workSelection；写仅取 workSelection").
+   * A pending retirement is a zero-dispatch error: the caller must confirm instead of being silently
+   * re-pointed at another tab.
+   */
+  resolveSessionTab(primaryEntry, sessionId, { mode = 'work' } = {}) {
     const record = this.selectionFor(primaryEntry, sessionId);
     if (record.pendingReset) {
       throw new BrowserError('TARGET_NOT_FOUND', '选中的标签已关闭或退休，需用 browser_tabs.current 或 select 确认', {
         reason: record.resetReason || 'selected-tab-closed', tabId: record.tabId, fallbackTabId: 'primary',
       });
     }
-    if (record.tabId === 'primary') return { entry: this.entries.get(primaryEntry.key) || primaryEntry, selection: record };
-    const entry = this.tabEntry(primaryEntry, record.tabId);
+    const tabId = mode === 'read' ? (record.observationTabId || record.tabId) : record.tabId;
+    if (tabId === null || tabId === undefined) {
+      // "You have no page of your own yet" is a binding answer, not a permission one (plan §6.1).
+      throw new BrowserError('TARGET_NOT_BOUND', '当前会话还没有自己的工作页：先用 browser_tabs open 新建，或 select 自己拥有的标签', {
+        reason: 'no-work-page', fallbackTabId: null, hint: 'browser_tabs.open', mode,
+      });
+    }
+    if (tabId === 'primary') return { entry: this.entries.get(primaryEntry.key) || primaryEntry, selection: record };
+    const entry = this.tabEntry(primaryEntry, tabId);
     if (!entry) {
       const key = this.#selectionKey(primaryEntry, sessionId);
-      const next = { ...record, tabId: 'primary', resetReason: 'tab-closed', pendingReset: true, revision: record.revision + 1 };
+      const next = {
+        ...record, tabId: null, observationTabId: null, resetTabId: tabId,
+        resetReason: 'tab-closed', pendingReset: true, revision: record.revision + 1,
+      };
       this.selectedBySession.set(key, next);
       throw new BrowserError('TARGET_NOT_FOUND', '选中的标签已被关闭', {
-        reason: 'selected-tab-closed', tabId: record.tabId, fallbackTabId: 'primary',
+        reason: 'selected-tab-closed', tabId, fallbackTabId: 'primary',
       });
     }
     return { entry, selection: record };
   }
 
-  selectTab(primaryEntry, sessionId, tabId) {
+  /**
+   * Select a tab for one actor, in two independent modes (plan §5, ruling §7.5).
+   *
+   * `mode:'work'` needs the right to *write* that page (owner/controller, or this root's Lead);
+   * `mode:'observe'` needs only the right to *read* it. Selecting never claims the short lease and
+   * never activates the page: a selection is a routing preference, and the old "select claims, so
+   * everyone else is BUSY" behaviour was the very thing that made two sessions fight over one tab.
+   * A refused selection leaves the caller's existing selection untouched.
+   */
+  selectTab(primaryEntry, sessionId, tabId, { mode = 'work', principal = null } = {}) {
     if (!sessionId || sessionId === 'anonymous') {
       throw new BrowserError('UNSUPPORTED', 'browser_tabs 需要真实 Agent 会话身份', { reason: 'agent-session-required' });
     }
     const target = this.tabEntry(primaryEntry, tabId);
     if (!target) throw new BrowserError('TAB_NOT_FOUND', '标签不存在或不属于当前 workspace', { tabId, fallbackTabId: 'primary' });
-    if (target !== primaryEntry && target.scope !== primaryEntry.scope) {
-      throw new BrowserError('TAB_FORBIDDEN', '标签属于其他 workspace', { tabId });
+    // `tabEntry` already filters by page group, so a foreign root's tabId cannot resolve here at
+    // all; the ACL below is about role/control *inside* the group.
+    if (principal) {
+      if (mode === 'observe') {
+        this.authorizePage(target, principal, { effect: EFFECT.OBSERVE, resource: RESOURCE.PAGE, targetRequired: true }, 'browser_tabs.select');
+      } else {
+        const verdict = authorize({
+          principal, ...this.accessOf(target),
+          effect: { effect: EFFECT.WRITE, resource: RESOURCE.PAGE, targetRequired: true },
+          operation: 'browser_tabs.select',
+        });
+        // A Lead who may *manage* the page may also aim work at it (the takeover happens on the
+        // first write, M4); a teammate who may not write it may not work-select it either.
+        const manageable = verdict.allowed || authorize({
+          principal, ...this.accessOf(target),
+          effect: { effect: EFFECT.MANAGE, resource: RESOURCE.PAGE, targetRequired: true },
+          operation: 'browser_tabs.acquire',
+        }).allowed;
+        if (!manageable) throw this.accessError(verdict, 'browser_tabs.select');
+      }
     }
     const record = this.selectionFor(primaryEntry, sessionId);
-    const previous = this.tabEntry(primaryEntry, record.tabId) || primaryEntry;
-    target.runtime.claim(sessionId);
-    if (previous !== target) previous.runtime.release(sessionId);
     const next = {
-      tabId: target.tabId || target.viewId || 'primary', revision: (record.revision || 0) + 1,
-      resetReason: null, pendingReset: false,
+      ...record,
+      ...(mode === 'observe'
+        ? { observationTabId: target.tabId || target.viewId || 'primary' }
+        : { tabId: target.tabId || target.viewId || 'primary', pendingReset: false, resetReason: null }),
+      revision: (record.revision || 0) + 1,
     };
     this.selectedBySession.set(this.#selectionKey(primaryEntry, sessionId), next);
     return { entry: target, selection: next };
@@ -12834,7 +14651,7 @@ export class RuntimeRegistry {
   }
 
   /** One list row. Read-only: no ensure, no queue, no lease, no CDP. */
-  #tabView(entry, selection, sessionId, now = Date.now()) {
+  #tabView(entry, selection, sessionId, now = Date.now(), principal = null) {
     const runtime = entry.runtime;
     const owner = runtime.lease && runtime.hasLease() ? runtime.lease.sessionId : null;
     const tabId = this.#tabId(entry);
@@ -12848,7 +14665,8 @@ export class RuntimeRegistry {
       status: runtime.page && runtime.cdp && !runtime.cdp.closed ? 'ready' : 'closed',
       selected: selection.tabId === tabId,
       busy: Boolean(owner), owner: owner === sessionId ? 'self' : (owner ? 'other' : null),
-      reset: selection.pendingReset && selection.tabId === tabId ? selection.resetReason || null : null,
+      reset: selection.pendingReset && (selection.resetTabId || selection.tabId) === tabId
+        ? selection.resetReason || null : null,
       // P0-E lifecycle projection: where the tab came from, who opened it and how long it lives.
       source: this.#tabSource(entry),
       parentTabId: entry.kind === 'popup' ? (entry.parentTabId || null) : null,
@@ -12858,15 +14676,28 @@ export class RuntimeRegistry {
       idleRemainingMs: Number.isFinite(this.idleMs) && Number.isFinite(lastUsedAt)
         ? Math.max(0, this.idleMs - Math.max(0, now - lastUsedAt)) : null,
       // `manageable` = this Agent session may act on the tab now (not another session's lease).
-      // Closing additionally needs the caller's own lease and no in-flight operation.
+      // Kept ONLY as the legacy short-lease projection (ruling §5): it never expressed an ACL, and
+      // new callers must read `permissions` instead.
       manageable: owner === null || owner === sessionId,
+      // Long-lived ownership/control projection (ruling §5 "每页返回", all of it root-scoped: the
+      // rows only ever describe pages inside the caller's own page group).
+      accessVersion: 1,
+      rootSessionId: entry.rootSessionId ?? null,
+      creatorSessionId: entry.ownership?.creatorSessionId ?? null,
+      ownerSessionId: entry.ownership?.ownerSessionId ?? null,
+      controllerSessionId: entry.control?.controllerSessionId ?? null,
+      ownershipRevision: entry.ownership?.ownershipRevision ?? null,
+      controlRevision: entry.control?.controlRevision ?? null,
+      accessState: entry.control?.state ?? null,
+      permissions: principal ? projectPermissions({ principal, ...this.accessOf(entry) }) : null,
     };
   }
 
-  listTabs(primaryEntry, sessionId) {
+  listTabs(primaryEntry, sessionId, principal = null) {
     const selection = this.selectionFor(primaryEntry, sessionId);
     const now = Date.now();
-    return this.tabEntries(primaryEntry).map((entry) => this.#tabView(entry, selection, sessionId, now));
+    return this.tabEntries(primaryEntry)
+      .map((entry) => this.#tabView(entry, selection, sessionId, now, principal));
   }
 
   /**
@@ -12944,10 +14775,16 @@ export class RuntimeRegistry {
   }
 
   /** P0-E explicit open: create about:blank child and select it for this session. */
-  async openTab(primaryEntry, sessionId, source = 'agent', { select = true } = {}) {
+  async openTab(primaryEntry, sessionId, source = 'agent', { select = true, principal = null } = {}) {
     if (!sessionId || sessionId === 'anonymous') {
       throw new BrowserError('UNSUPPORTED', 'browser_tabs 需要真实 Agent 会话身份', { reason: 'agent-session-required' });
     }
+    // Creation authorisation runs *before* the reservation and before any CDP: a caller that may
+    // not create pages in this group must not even reach `createTarget`.
+    if (principal) {
+      this.authorizePage(primaryEntry, principal,
+        { effect: EFFECT.WRITE, resource: RESOURCE.PAGE, targetRequired: false }, 'browser_tabs.open');
+    }
     const release = this.reservePopupSlot(primaryEntry);
     const viewId = randomUUID().replace(/-/gu, '').slice(0, 20);
     const primary = this.entries.get(primaryEntry.primaryKey || primaryEntry.key) || primaryEntry;
@@ -12956,14 +14793,29 @@ export class RuntimeRegistry {
       kind: 'popup', parentRuntimeId: primary.runtime.runtimeId, viewId, parentKey: primary.key,
       openEventId: null, sourcePanelId: null, createdBy: source, inheritView: primary.runtime.view,
     });
-    const entry = this.addPopupEntry({ parentEntry: primary, runtime: child, viewId, openEventId: null, sourcePanelId: null });
+    // Who owns a page the *panel* opened? The session the panel is showing, not the panel's own
+    // synthetic actor: the panel is a view of that session's domain, and a tab opened from it must
+    // stay drivable by that session. A tool-driven open is owned by the calling actor.
+    const creatorSessionId = principal ? sessionId : (primary.ownership?.ownerSessionId || sessionId);
+    const entry = this.addPopupEntry({
+      parentEntry: primary, runtime: child, viewId, openEventId: null, sourcePanelId: null,
+      creatorSessionId,
+    });
     entry.status = 'initializing';
     try {
       const page = await this.browserHost().createPage(child, AbortSignal.timeout(10000));
       await child.adoptPage(page, { signal: AbortSignal.timeout(10000) });
       entry.status = 'ready';
       this.bumpViews(entry.primaryKey);
-      const selected = select ? this.selectTab(primary, sessionId, viewId) : { selection: this.selectionFor(primary, sessionId) };
+      // `open` sets both selections for its own actor (plan §5): the caller asked for this page
+      // as its work target *and* as the thing it is looking at.
+      const selected = select
+        ? this.selectTab(primary, sessionId, viewId, { mode: 'work', principal })
+        : { selection: this.selectionFor(primary, sessionId) };
+      if (select) {
+        const record = this.selectionFor(primary, sessionId);
+        this.selectedBySession.set(this.#selectionKey(primary, sessionId), { ...record, observationTabId: viewId });
+      }
       return { entry, selection: selected.selection };
     } catch (error) {
       try { await child.close(); } catch { /* ignore */ }
@@ -12974,13 +14826,35 @@ export class RuntimeRegistry {
     }
   }
 
-  /** Close one tab. Agent close requires the caller's own live lease; primary only goes cold. */
-  async closeTab(primaryEntry, sessionId, tabId, { gui = false } = {}) {
-    const target = this.tabEntry(primaryEntry, tabId || this.selectionFor(primaryEntry, sessionId).tabId);
+  /**
+   * Close one tab. Primary only goes cold; children are destroyed.
+   *
+   * Agent close is now authorised by *ownership/control* (M1 `authorize`), not by holding the 15s
+   * lease: the lease says "someone is busy right now", which is a scheduling fact, not a permission.
+   * A teammate closing a teammate's page is refused here; a foreign root never resolves the tab at
+   * all. The GUI path (`gui:true`) keeps its historical shape — it has no Principal until M5, which
+   * is reported as a known gap rather than papered over with a fake one.
+   */
+  async closeTab(primaryEntry, sessionId, tabId, { gui = false, principal = null } = {}) {
+    const wanted = tabId || this.selectionFor(primaryEntry, sessionId).tabId;
+    if (!wanted) {
+      // Same rule as a page tool: nothing selected means "no page yet", never "the primary".
+      throw new BrowserError('TARGET_NOT_BOUND', '当前会话没有可关闭的页：省略 tabId 时需要先 open/select', {
+        reason: 'no-work-page', hint: 'browser_tabs.open',
+      });
+    }
+    const target = this.tabEntry(primaryEntry, wanted);
     if (!target) throw new BrowserError('TAB_NOT_FOUND', '标签不存在或不属于当前 workspace', { tabId });
     if (!gui) {
-      const owner = target.runtime.lease && target.runtime.hasLease() ? target.runtime.lease.sessionId : null;
-      if (owner !== sessionId) throw new BrowserError('TAB_FORBIDDEN', '关闭标签需要当前会话持有该标签的 lease', { tabId, owner });
+      if (principal) {
+        this.authorizePage(target, principal,
+          { effect: EFFECT.MANAGE, resource: RESOURCE.PAGE, targetRequired: true }, 'browser_tabs.close');
+      } else {
+        // Legacy/GUI callers without a Principal keep the old short-lease rule (M5 will replace it
+        // with a verified panel seat; until then this must not silently become "anyone may close").
+        const owner = target.runtime.lease && target.runtime.hasLease() ? target.runtime.lease.sessionId : null;
+        if (owner !== sessionId) throw new BrowserError('TAB_FORBIDDEN', '关闭标签需要当前会话持有该标签的 lease', { tabId, owner });
+      }
     }
     if (gui && target.runtime.hasLease()) throw new BrowserError('BUSY', '标签正由 Agent 操作，GUI 暂不能关闭', { tabId });
     if (target.runtime.active > 0 || target.runtime.inflight > 0) {
@@ -12988,6 +14862,17 @@ export class RuntimeRegistry {
     }
     // Primary close only makes primary cold; children stay live (P0-E §1).
     target.closeReason = 'closed';
+    // Lifecycle versioning (ruling §7.1): a close always advances controlRevision, so a management
+    // CAS that was in flight against the old page can never land on the reopened one. A child page
+    // is retired outright; a primary slot keeps its history and stays `owned` because it will be
+    // reopened in place (M4 adds the explicit acquire/release/transfer transitions).
+    if (target.ownership && target.control) {
+      target.control = makeControl({
+        state: target.kind === 'popup' ? CONTROL_STATE.RETIRED : CONTROL_STATE.OWNED,
+        controllerSessionId: target.kind === 'popup' ? null : target.ownership.ownerSessionId,
+        controlRevision: target.control.controlRevision + 1,
+      });
+    }
     await target.runtime.run(() => target.runtime.close(), { sessionId, agent: false });
     return { closed: target.tabId || (target.kind === 'primary' ? 'primary' : target.viewId) };
   }
@@ -13006,9 +14891,22 @@ export class RuntimeRegistry {
     if (entry.kind === 'popup') {
       const tabId = entry.tabId || entry.viewId;
       for (const [key, record] of this.selectedBySession) {
-        if (record && record.tabId === tabId) {
-          this.selectedBySession.set(key, { ...record, tabId: 'primary', resetReason: 'tab-closed', pendingReset: true, revision: record.revision + 1 });
-        }
+        // Only selections *inside this page group* may be reset: a same-named tabId in another
+        // root's group is a different page and must not be disturbed.
+        if (!record || record.groupKey !== entry.primaryKey) continue;
+        const touchesWork = record.tabId === tabId;
+        const touchesObserve = record.observationTabId === tabId;
+        if (!touchesWork && !touchesObserve) continue;
+        this.selectedBySession.set(key, {
+          ...record,
+          // The retired tab must not be replaced by "primary": for a teammate the primary belongs to
+          // the Lead, and pointing there would turn the confirm flow into "you may not touch this
+          // page". The work selection becomes *unbound* and `resetTabId` keeps the audit of what
+          // retired (the panel still shows which tab was reset).
+          ...(touchesWork ? { tabId: null, resetTabId: tabId, resetReason: 'tab-closed', pendingReset: true } : {}),
+          ...(touchesObserve ? { observationTabId: null } : {}),
+          revision: record.revision + 1,
+        });
       }
       this.entries.delete(entry.key);
       this.bumpViews(entry.primaryKey);
@@ -13017,13 +14915,39 @@ export class RuntimeRegistry {
     }
   }
 
-  recentEntry() { return this.recentKey ? this.entries.get(this.recentKey) : undefined; }
+  /**
+   * Last real interaction, per root when a root is named.
+   *
+   * A root-scoped caller only ever sees its own root's entry. A **rootless** caller (the legacy
+   * panel protocol, which carries no session identity at all) keeps the historical single
+   * "most recently used page" pointer: that is a navigation convenience, not an authorisation —
+   * every page operation re-authorises against the caller's own identity, and M5 replaces the
+   * unbound panel with a verified seat. Answering `undefined` there would break the panel without
+   * making anything safer.
+   */
+  recentEntry(rootSessionId) {
+    if (rootSessionId !== undefined && rootSessionId !== null && rootSessionId !== '') {
+      const root = String(rootSessionId);
+      const key = this.recentByRoot.get(root);
+      if (!key) return undefined;
+      const entry = this.entries.get(key);
+      if (!entry) this.recentByRoot.delete(root);
+      return entry;
+    }
+    let best;
+    for (const entry of this.entries.values()) {
+      if (entry.kind === 'popup') continue;
+      if (entry.baseKey === LEGACY_SCOPE.key) continue;
+      if (!best || (entry.lastUsedAt || 0) > (best.lastUsedAt || 0)) best = entry;
+    }
+    return best;
+  }
 
   markRecent(entry) {
-    if (!entry || entry.key === LEGACY_SCOPE.key) return;
+    if (!entry || entry.baseKey === LEGACY_SCOPE.key) return;
     // A popup child never becomes the Agent's recent/primary target.
     if (entry.kind === 'popup') return;
-    this.recentKey = entry.key;
+    this.recentByRoot.set(String(entry.rootSessionId || UNSCOPED_ROOT), entry.key);
   }
 
   touch(entry) { if (entry) entry.lastUsedAt = Date.now(); }
@@ -13095,7 +15019,8 @@ export class RuntimeRegistry {
     } catch { /* audit only */ }
     this.entries.delete(entry.key);
     if (entry.kind === 'popup' && entry.primaryKey) this.bumpViews(entry.primaryKey);
-    if (this.recentKey === entry.key) this.recentKey = undefined;
+    else if (entry.kind === 'primary') this.pruneSelections();
+    for (const [root, key] of [...this.recentByRoot]) if (key === entry.key) this.recentByRoot.delete(root);
     try { this.onRetire?.(entry.runtime); } catch { /* ignore */ }
     try { entry.runtime.frameTransport?.dispose?.(); } catch { /* ignore */ }
     // A retired scope runtime is gone: its stored images must not outlive it (a later productId
@@ -13110,7 +15035,7 @@ export class RuntimeRegistry {
     try {
       const now = Date.now();
       for (const entry of [...this.entries.values()]) {
-        if (entry.key === LEGACY_SCOPE.key) continue; // old client compatibility: keep the entry
+        if (entry.baseKey === LEGACY_SCOPE.key) continue; // old client compatibility: keep the entry
         const runtime = entry.runtime;
         const idleFor = now - entry.lastUsedAt;
         if (idleFor < this.idleMs) continue;
@@ -13136,25 +15061,51 @@ export class RuntimeRegistry {
   }
 
   /** The shared host exits only when the last page is gone and no create is in flight. */
-  async maybeCloseHost() {
+  async maybeCloseHost(provider = null) {
     if (this.disposed) return;
     if (this.reservations > 0) return;
-    const host = this.host;
-    if (!host) return;
-    if (host.pageCount > 0 || host.pendingCreates > 0 || host.starting) return;
-    if (host.closing) return host.closing;
-    if (!host.proc && !host.profileDir && !host.browserCdp) return undefined;
-    return host.close();
+    const candidates = provider === null
+      ? [...this.hosts.values()]
+      : [this.hosts.get(provider)].filter(Boolean);
+    let closing;
+    for (const host of candidates) {
+      if (host.pageCount > 0 || host.pendingCreates > 0 || host.starting) continue;
+      if (host.closing) { closing = closing ?? host.closing; continue; }
+      if (!host.proc && !host.profileDir && !host.browserCdp) continue;
+      closing = closing ?? host.close();
+    }
+    return closing;
   }
 
   releaseSession(sessionId) {
     for (const entry of this.entries.values()) entry.runtime.release(sessionId);
-    // Selection keys are `<primaryKey>\u0000<sessionId>`: drop the records of a session that ended,
-    // otherwise every closed agent session pins one small record per workspace it touched.
-    const suffix = '\u0000' + String(sessionId || 'anonymous');
-    for (const key of [...this.selectedBySession.keys()]) {
-      if (key.endsWith(suffix)) this.selectedBySession.delete(key);
+    // Selections are deliberately NOT dropped here any more.
+    //
+    // A real host emits `agent/disposed` at almost every turn boundary, so deleting the record there
+    // reset the selection revision to 0 and silently discarded `pendingReset`: the caller was never
+    // told "your tab was retired, confirm with current", it just got a fresh default that pointed at
+    // the Lead's primary. A selection is (page group, actor) state — it outlives an execution
+    // instance and is pruned when its page group disappears (see `pruneSelections`).
+    this.pruneSelections();
+  }
+
+  /** Drop selection rows whose page group is gone (bounded by the live entry table). */
+  pruneSelections() {
+    if (this.selectedBySession.size === 0) return 0;
+    const liveGroups = new Set();
+    for (const entry of this.entries.values()) {
+      if (entry.kind === 'primary') liveGroups.add(entry.key);
+      if (entry.primaryKey) liveGroups.add(entry.primaryKey);
+    }
+    let dropped = 0;
+    for (const [key, record] of [...this.selectedBySession]) {
+      const groupKey = record && record.groupKey;
+      if (!groupKey || !liveGroups.has(groupKey)) {
+        this.selectedBySession.delete(key);
+        dropped += 1;
+      }
     }
+    return dropped;
   }
 
   capabilities() {
@@ -13176,7 +15127,7 @@ export class RuntimeRegistry {
     clearInterval(this.sweepTimer);
     const runtimes = [...this.entries.values()].map((entry) => entry.runtime);
     this.entries.clear();
-    this.recentKey = undefined;
+    this.recentByRoot.clear();
     for (const runtime of runtimes) {
       try { await runtime.close(); } catch { /* ignore */ }
       try { this.onRetire?.(runtime); } catch { /* ignore */ }
@@ -13184,7 +15135,33 @@ export class RuntimeRegistry {
       try { runtime.disposeVision?.(); } catch { /* ignore */ }
       try { await runtime.disposeDynamic?.(); } catch { /* ignore */ }
     }
-    if (this.host) { try { await this.host.close(); } catch { /* ignore */ } }
+    for (const host of this.hosts.values()) {
+      try { await host.close(); } catch { /* one provider's failure must not mask the others */ }
+    }
+    this.hosts.clear();
+    this.providerByBaseKey.clear();
+  }
+
+  /**
+   * Close one provider only (§6): its entries and its host. Another provider's pages, leases and
+   * refs are untouched, so closing Chrome never kills an Agent's Edge session.
+   */
+  async closeProvider(provider) {
+    const id = typeof provider === 'string' && provider.length > 0 ? provider : DEFAULT_RUNTIME_PROVIDER;
+    const doomed = [...this.entries.values()].filter((entry) => (entry.provider ?? DEFAULT_RUNTIME_PROVIDER) === id);
+    for (const entry of doomed) {
+      try { await entry.runtime.close(); } catch { /* ignore */ }
+      try { this.onRetire?.(entry.runtime); } catch { /* ignore */ }
+      this.entries.delete(entry.key);
+      for (const [root, key] of [...this.recentByRoot]) if (key === entry.key) this.recentByRoot.delete(root);
+    }
+    for (const [baseKey, owner] of [...this.providerByBaseKey]) {
+      if (owner === id) this.providerByBaseKey.delete(baseKey);
+    }
+    const host = this.hosts.get(id);
+    this.hosts.delete(id);
+    if (host) { try { await host.close(); } catch { /* ignore */ } }
+    return { provider: id, closedEntries: doomed.length };
   }
 }
 
@@ -13885,7 +15862,11 @@ function elementPickRequest(body) {
   if (body.detail !== undefined && body.detail !== null && typeof body.detail !== 'boolean') {
     throw new BrowserError('INVALID_ARGUMENT', 'element detail 必须是布尔值', { field: 'detail', valueType: typeof body.detail });
   }
-  return { x, y, detail: body.detail === true };
+  const cursorOnly = body.cursorOnly === true;
+  // A cursor-only probe answers just the computed `cursor` of the hit: it exists so the panel can
+  // mirror the page's hand/text/grab cursor onto the preview while the pointer moves, without
+  // paying for the box model, frame tree and selector work a full pick needs.
+  return { x, y, detail: body.detail === true, cursorOnly };
 }
 
 /**
@@ -13914,6 +15895,49 @@ function elementAttributes(node) {
   return out;
 }
 
+/**
+ * The frame a pick belongs to, read from the `Page.getFrameTree` reply.
+ *
+ * `main` marks the root frame; a nested frame carries its own `loaderId` (document generation) and
+ * URL so the reply can say that the selector/rect are scoped to that document. An id absent from
+ * the tree answers `null`: the caller fails closed instead of trusting an unverifiable frame.
+ */
+function elementFrameOf(frameTree, frameId) {
+  const wanted = String(frameId || '');
+  if (!wanted || !frameTree || !frameTree.frame) return null;
+  const walk = (node, depth) => {
+    if (!node || !node.frame || depth > 32) return null;
+    if (String(node.frame.id) === wanted) {
+      return {
+        id: String(node.frame.id),
+        loaderId: typeof node.frame.loaderId === 'string' ? node.frame.loaderId : null,
+        url: typeof node.frame.url === 'string' ? node.frame.url : '',
+        main: depth === 0,
+      };
+    }
+    const children = Array.isArray(node.childFrames) ? node.childFrames : [];
+    for (const child of children) {
+      const found = walk(child, depth + 1);
+      if (found) return found;
+    }
+    return null;
+  };
+  return walk(frameTree, 0);
+}
+
+/** Does this frame tree still carry a document whose loader id is `loaderId`? */
+function frameTreeHasLoaderId(frameTree, loaderId) {
+  const wanted = String(loaderId || '');
+  if (!wanted) return false;
+  const walk = (node, depth) => {
+    if (!node || !node.frame || depth > 32) return false;
+    if (String(node.frame.loaderId || '') === wanted) return true;
+    const children = Array.isArray(node.childFrames) ? node.childFrames : [];
+    return children.some((child) => walk(child, depth + 1));
+  };
+  return walk(frameTree, 0);
+}
+
 /** Border-box quad (viewport CSS px) -> document rect; a degenerate/absent quad is `null`. */
 function elementQuadRect(model, scrollX, scrollY) {
   const quad = model && (model.border || model.padding || model.content);
@@ -13993,7 +16017,7 @@ async function elementDetailFacts(cdp, backendNodeId) {
  * Read the element at one document point. Never throws and never mutates the runtime: the caller
  * turns the result into `{ok:true, element, reason}`.
  */
-async function pickElementAt(runtime, { x, y, detail }) {
+async function pickElementAt(runtime, { x, y, detail, cursorOnly = false }) {
   if (!runtime || !runtime.running || !runtime.cdp) return { element: null, reason: 'no-page' };
   const cdp = runtime.cdp;
   const bounded = (method, params) => cdp.send(method, params, { timeoutMs: ELEMENT_CDP_TIMEOUT_MS });
@@ -14018,7 +16042,10 @@ async function pickElementAt(runtime, { x, y, detail }) {
       // quantised (nothing is dispatched and nothing is mutated).
       hit = await bounded('DOM.getNodeForLocation', {
         x: Math.floor(x), y: Math.floor(y),
-        includeUserAgentShadowDOM: true, ignorePointerEventsNone: false,
+        // Native controls contain browser-owned shadow nodes (e.g. select's inner DIV).
+        // Pick the authored control so its options and identity can be read. This flag only
+        // excludes UA shadow; authored open/closed shadow roots keep their existing behavior.
+        includeUserAgentShadowDOM: false, ignorePointerEventsNone: false,
       });
     } catch (error) {
       // "No node found at given location" is a miss; a timeout / detached document / closed CDP
@@ -14027,14 +16054,13 @@ async function pickElementAt(runtime, { x, y, detail }) {
       return { element: null, reason: noNode ? 'no-hit' : 'stale' };
     }
     if (!hit || !Number.isInteger(hit.backendNodeId)) return { element: null, reason: 'no-hit' };
-    // v1 picks inside the main frame only (the same "frame: main" tree T2 snapshots use). A hit in
-    // a child frame fails closed instead of returning a child-frame-relative selector/rect; when
-    // the main frame id is not known yet, a hit that claims a frame is fail-closed as `stale`
-    // (never trust an unverifiable frame, e.g. mid-navigation).
-    if (hit.frameId) {
-      if (!runtime.mainFrameId) return { element: null, reason: 'stale' };
-      if (hit.frameId !== runtime.mainFrameId) return { element: null, reason: 'frame' };
-    }
+    // A hit may land in a same-process child frame: a native `<select>` inside an `<iframe>` still
+    // needs the picker's popover, and `DOM.getBoxModel` already reports ROOT-frame viewport quads,
+    // so the document rect stays comparable with the panel's coordinates. Only what cannot be
+    // verified is refused: an unknown main frame id (mid-navigation) is `stale`, and a hit whose
+    // frame is missing from the frame tree (read below) is `stale` too — never unchecked cross-frame
+    // data. OOPIF/closed targets simply never hit on this session.
+    if (hit.frameId && !runtime.mainFrameId) return { element: null, reason: 'stale' };
     const described = await bounded('DOM.describeNode', { backendNodeId: hit.backendNodeId, depth: 0 });
     // A hit may land on a text (or shadow-root) node: walk up to its element, bounded.
     let node = described && described.node;
@@ -14044,18 +16070,54 @@ async function pickElementAt(runtime, { x, y, detail }) {
       node = parent && parent.node;
     }
     if (!node || node.nodeType !== 1) return { element: null, reason: 'no-hit' };
+    // List-style selects hit their OPTION/OPTGROUP rather than the control's border. Project the
+    // owning control too, so unsupported shapes can show the keyboard hint instead of disappearing.
+    if (['option', 'optgroup'].includes(String(node.localName || '').toLowerCase())) {
+      const handles = [];
+      try {
+        const resolved = await bounded('DOM.resolveNode', { backendNodeId: node.backendNodeId });
+        const objectId = resolved?.object?.objectId;
+        if (objectId) {
+          handles.push(objectId);
+          const owner = await bounded('Runtime.callFunctionOn', {
+            objectId, functionDeclaration: 'function () { return this.closest("select"); }',
+          });
+          if (owner?.result?.objectId) {
+            handles.push(owner.result.objectId);
+            const describedOwner = await bounded('DOM.describeNode', { objectId: owner.result.objectId, depth: 0 });
+            if (describedOwner?.node?.localName === 'select') node = describedOwner.node;
+          }
+        }
+      } finally {
+        for (const objectId of handles) {
+          try { await bounded('Runtime.releaseObject', { objectId }); } catch { /* best effort */ }
+        }
+      }
+    }
     const tag = String(node.localName || '').toLowerCase();
+    if (cursorOnly) {
+      // Empty page background is a legitimate cursor answer (`default`), not a miss: the panel is
+      // asking "what would the real page show here", and a straight arrow is a real answer.
+      const cursor = ['html', 'body'].includes(tag)
+        ? { cursor: 'default', tag: tag || 'html' }
+        : await cursorProjectionAt(bounded, node.backendNodeId);
+      return { element: cursor, cursorOnly: true };
+    }
     // A point on empty page background resolves to <html>/<body>; for a picker that is "nothing".
     if (!tag || tag === 'html' || tag === 'body') return { element: null, reason: 'no-hit' };
     const box = await bounded('DOM.getBoxModel', { backendNodeId: node.backendNodeId });
     // Loader id = the document generation the hit belongs to (the panel uses it to discard a
-    // response that raced a navigation). Best-effort: an unreadable frame tree omits the field.
-    let loaderId = null;
+    // response that raced a navigation). The frame tree read also proves that a child-frame hit
+    // still belongs to a live frame; `main` separates the root frame from a nested one.
+    let frame = null;
     try {
       const tree = await bounded('Page.getFrameTree', {});
-      const mainFrame = tree && tree.frameTree && tree.frameTree.frame;
-      loaderId = mainFrame && typeof mainFrame.loaderId === 'string' && mainFrame.loaderId ? mainFrame.loaderId : null;
-    } catch { loaderId = null; }
+      frame = elementFrameOf(tree && tree.frameTree, hit.frameId || runtime.mainFrameId);
+    } catch { frame = null; }
+    // An unreadable frame tree keeps the historical best-effort shape for root-frame hits (no
+    // loaderId), but a nested hit without a verifiable frame is refused.
+    if (!frame && hit.frameId && hit.frameId !== runtime.mainFrameId) return { element: null, reason: 'stale' };
+    const loaderId = frame && typeof frame.loaderId === 'string' && frame.loaderId ? frame.loaderId : null;
     const attributes = elementAttributes(node);
     const element = {
       tag,
@@ -14063,6 +16125,9 @@ async function pickElementAt(runtime, { x, y, detail }) {
       classes: attributes.class ? attributes.class.split(/\s+/u).filter(Boolean) : [],
       rect: elementQuadRect(box && box.model, scrollX, scrollY),
       frameId: String(hit.frameId || runtime.mainFrameId || ''),
+      // Nested frames only: the selector/outerHTML above are valid inside that frame's document,
+      // not in the main document, so the caller gets the frame identity instead of guessing.
+      ...(frame && frame.main === false ? { frame: { id: frame.id, url: redactUrl(frame.url), main: false } } : {}),
       // The SAME Page.getLayoutMetrics read that produced the document rect: the panel compares it
       // with its own view to detect a response computed while the page was still scrolling.
       scroll: { x: scrollX, y: scrollY },
@@ -14072,7 +16137,22 @@ async function pickElementAt(runtime, { x, y, detail }) {
         title: runtime.title ? String(runtime.title) : '',
       },
     };
-    if (detail) Object.assign(element, await elementDetailFacts(cdp, node.backendNodeId));
+    if (detail) {
+      Object.assign(element, await elementDetailFacts(cdp, node.backendNodeId));
+      // The picker's own preview mirrors the page cursor from the hit it already has.
+      const pointer = await cursorProjectionAt(bounded, node.backendNodeId);
+      if (pointer) element.cursor = pointer.cursor;
+    }
+    // A native <select> popup is painted by the browser UI layer, never by the page, so the panel
+    // cannot see it in the frame. Only for a select hit (and only when the projection is readable)
+    // does the reply gain a `select` field; every other hit keeps the exact historical shape.
+    if (tag === 'select') {
+      const select = await selectProjectionAt(bounded, node.backendNodeId);
+      if (select) element.select = {
+        ...select,
+        ...(loaderId ? { target: { backendNodeId: node.backendNodeId, loaderId } } : {}),
+      };
+    }
     return { element };
   } catch {
     // Any other read failure (CDP timeout/disconnect, detached target, missing box) is stale.
@@ -14080,6 +16160,69 @@ async function pickElementAt(runtime, { x, y, detail }) {
   }
 }
 
+/**
+ * Computed `cursor` of one hit node (POST /element `cursorOnly`, and the detail projection).
+ *
+ * Read-only and failure-tolerant, exactly like `selectProjectionAt`: one `DOM.resolveNode` plus one
+ * `Runtime.callFunctionOn` that only reads, `null` on any failure, so an unreadable node never turns
+ * a successful hover into an error. The value passes through verbatim — the CLIENT decides which
+ * keywords it is willing to apply, because `cursor:url(...)` must never reach a style attribute.
+ */
+async function cursorProjectionAt(bounded, backendNodeId) {
+  let objectId = null;
+  try {
+    const resolved = await bounded('DOM.resolveNode', { backendNodeId });
+    objectId = resolved && resolved.object ? resolved.object.objectId : null;
+    if (!objectId) return null;
+    const answer = await bounded('Runtime.callFunctionOn', {
+      objectId,
+      functionDeclaration: 'function () { return String(getComputedStyle(this).cursor || "") }',
+      returnByValue: true,
+    });
+    const value = answer && answer.result ? answer.result.value : null;
+    if (typeof value !== 'string' || !value) return null;
+    return { cursor: value.slice(0, 64) };
+  } catch {
+    return null;
+  } finally {
+    if (objectId) {
+      try { await bounded('Runtime.releaseObject', { objectId }); } catch { /* best effort */ }
+    }
+  }
+}
+
+/**
+ * Read-only option projection for a hit `<select>` (POST /element).
+ *
+ * Same read-only contract as `pickElementAt` (no ensure, no queue, no lease, no `lastError`): one
+ * `DOM.resolveNode` + one `Runtime.callFunctionOn` that merely reads. Every failure answers `null`
+ * so the element reply keeps its historical shape — a page that cannot be read must not turn a
+ * successful pick into an error, and a non-select hit must never grow a new field.
+ */
+async function selectProjectionAt(bounded, backendNodeId) {
+  let objectId = null;
+  try {
+    const resolved = await bounded('DOM.resolveNode', { backendNodeId });
+    objectId = resolved && resolved.object ? resolved.object.objectId : null;
+    if (!objectId) return null;
+    const answer = await bounded('Runtime.callFunctionOn', {
+      objectId,
+      functionDeclaration: selectProbeDeclaration(),
+      returnByValue: true,
+    });
+    const value = answer && answer.result ? answer.result.value : null;
+    return normalizeSelectProjection(value);
+  } catch {
+    return null;
+  } finally {
+    // CallFunctionOn leaves a remote handle behind; releasing it is best-effort and must never
+    // mask the read result (a dropped handle only costs the inspector's object group).
+    if (objectId) {
+      try { await bounded('Runtime.releaseObject', { objectId }); } catch { /* best effort */ }
+    }
+  }
+}
+
 /** Register the runtime, its HTTP surface, and the agent tools. */
 export function apply(ctx) {
   const log = (text) => {
@@ -14096,6 +16239,11 @@ export function apply(ctx) {
     idleMs: envPositiveInt('DSH_UI_TESTING_IDLE_MS', IDLE_MS_DEFAULT),
     viewerTtlMs: envPositiveInt('DSH_UI_TESTING_VIEWER_TTL_MS', VIEWER_TTL_MS),
   });
+  // Cross-environment composition root (M2/M3): authoritative config, adapter registry, tool
+  // admission, per-execution adapter dispatch, readiness and Skill discovery. The Web runtime
+  // stays here; `integration/` only consumes the public core/targets contracts.
+  const crossEnvironment = createCrossEnvironment({ ctx, registry, log, BrowserError, asBrowserError });
+  ctx.effect(() => () => crossEnvironment.dispose(), 'ui-testing: cross-environment');
   // Independent HTTP client: shares only the collected host origins, never a page runtime.
   const httpClient = new HttpClient({ origins: () => [...origins] });
   ctx.effect(() => () => { httpClient.dispose(); }, 'ui-testing: http client');
@@ -14197,7 +16345,7 @@ export function apply(ctx) {
         resolve: async (scopeRequest) => {
           const resolved = await resolveScopeRequest(ctx, registry, scopeRequest);
           let entry = scopeRequest && scopeRequest.mode === 'binding'
-            ? registry.peek(resolved.key) : registry.getOrCreate(resolved);
+            ? registry.peek(resolved) : registry.getOrCreate(resolved);
           if (!entry) throw new BrowserError('SCOPE_NOT_FOUND', 'scope binding 指向的运行时不存在', { scope: 'binding' });
           if (scopeRequest && scopeRequest.mode === 'session' && scopeRequest.tab !== SCOPE_TAB_PRIMARY) {
             entry = registry.resolveSessionTab(entry, scopeRequest.sessionId).entry;
@@ -14221,22 +16369,15 @@ export function apply(ctx) {
     };
   }, 'ui-testing: frame push');
 
-  // The bundled Skill is the documented, structured tool surface plus capability discovery.
-  // It is optional: a deployment without the skill asset (or without the skills service) keeps
-  // the browser tools working, and the failure is logged instead of aborting the plugin.
+  // Environment-aware Skill discovery (M3). The provider exposes the common rules plus only the
+  // current environment's extension; `get()` re-checks visibility because an explicit skill load
+  // does not pass through `list()`. The legacy single-skill registration is the fallback.
   ctx.inject(['skills'], (sub) => {
-    let skill;
     try {
-      skill = readBundledSkill();
+      crossEnvironment.registerSkills(sub);
     } catch (error) {
       log('ui-testing skill 未注册：' + String((error && error.message) || error));
-      return;
-    }
-    if (!skill) {
-      log('ui-testing skill 未注册：skills/ui-testing/SKILL.md 不存在');
-      return;
     }
-    sub.effect(() => sub.skills.register(skill), 'ui-testing: bundled skill');
   });
 
   /**
@@ -14266,7 +16407,38 @@ export function apply(ctx) {
     return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
   };
 
+  /**
+   * Provider diagnostics (Host slice): `POST /plugins/ui-testing/diagnose` streams NDJSON and runs
+   * five real checks. It reuses the registered tool handlers (never `/test/invoke`) through a
+   * restricted dispatcher; `toolDefinitions` is read lazily because it is declared later.
+   */
+  const diagnose = createDiagnose({
+    log,
+    crossEnvironment,
+    registry,
+    readJson,
+    sendJson,
+    nowMonoMs,
+    resolveProviderExecutable,
+    randomUUID,
+    webProviderSupport: (providerId) => {
+      try { return webProviderSupport(providerId); } catch { return undefined; }
+    },
+    toolDefinitions: {
+      get(name) { return toolDefinitions.get(name); },
+      keys() { return [...toolDefinitions.keys()]; },
+      has(name) { return toolDefinitions.has(name); },
+    },
+  });
+
   const handle = async (req, res) => {
+    // A14: the HTTP surface (panel/WS/legacy routes) may create or drive a page; resolve the Web
+    // module chain before the first such request instead of at module load.
+    try {
+      await ensureWebHostModules();
+    } catch (error) {
+      log('ui-testing: web host modules unavailable: ' + String((error && error.message) || error));
+    }
     let action = '/';
     let selected;
     try {
@@ -14319,6 +16491,22 @@ export function apply(ctx) {
         const status = scopeAuthorization(req);
         if (status) { scopeAuthError(res, status); return; }
       }
+      // Host-side provider diagnostics. Handled before the page-route dispatch so it never creates
+      // a Runtime or starts Chromium just by being routed (observe must stay cheap).
+      if (await diagnose.handleHttp(req, res, {
+        action,
+        url,
+        scopeRequest: parseHttpScope(req),
+        scoped,
+        requestRejection,
+        rejectUi,
+        readJson,
+        sendJson,
+        // Bound resolver: this seam calls `resolveScopeRequest(request)`. Passing the 3-argument
+        // module function unbound left `request` undefined, so every diagnose run silently froze
+        // the LEGACY scope instead of the panel's own session/binding.
+        resolveScopeRequest: (request) => resolveScopeRequest(ctx, registry, request),
+      })) return;
       const scopeRequest = parseHttpScope(req);
       if (req.headers?.host) {
         try { origins.add(new URL('http://' + req.headers.host).origin); } catch { /* invalid host */ }
@@ -14326,21 +16514,43 @@ export function apply(ctx) {
       const select = async ({ create = true } = {}) => {
         const resolved = await resolveScopeRequest(ctx, registry, scopeRequest);
         // A binding already names an existing primary/child; never create a new runtime for it.
-        let entry = create && scopeRequest.mode !== 'binding' ? registry.getOrCreate(resolved) : registry.peek(resolved.key);
+        let entry = create && scopeRequest.mode !== 'binding' ? registry.getOrCreate(resolved) : registry.peek(resolved);
         if (entry && scopeRequest.mode === 'session' && scopeRequest.tab !== SCOPE_TAB_PRIMARY) {
           // P0-E: a session-scoped HTTP read/write follows that Agent session's selectedTab.
           // `scope-tab: primary` opts out: a GUI panel renders its own selected tab, so the Agent's
           // selection must never redirect it (docs/multi-tab.md).
           entry = registry.resolveSessionTab(entry, scopeRequest.sessionId).entry;
         }
+        if (entry && scoped && headerValue(req.headers, SCOPE_HEADER_FOREGROUND) === '1') {
+          // Human-foreground claim (docs/viewport-control.md): the panel reports it on the requests
+          // it makes for the tab it is displaying, so switching tabs/closing the panel/backgrounding
+          // the GUI lets the claim expire instead of leaving a stale "somebody is watching" bit.
+          entry.runtime.noteGuiForeground(entry.viewId);
+        }
         return { resolved, entry };
       };
       const assertGuiPageWrite = (runtime, selfSessionId = null) => {
+        // Configuration gate: a disabled/non-Web environment must not be bypassed through the
+        // panel HTTP routes (the same snapshot as tool admission).
+        crossEnvironment.assertGuiAllowed(scopeRequest);
         const lease = runtime && runtime.lease;
         if (lease && lease.sessionId !== selfSessionId && (runtime.active > 0 || lease.expiresAt > Date.now())) {
           throw new BrowserError('BUSY', '该标签正由 Agent 操作，GUI 输入暂不可用', { owner: lease.sessionId });
         }
       };
+      // Cross-environment control plane: /config, /config/select, /readiness. Consumed before the
+      // page-route dispatch so these endpoints never create a Runtime or start Chromium.
+      if (await crossEnvironment.handleHttp(req, res, {
+        action,
+        url,
+        scopeRequest,
+        scoped,
+        requestRejection,
+        rejectUi,
+        readJson,
+        sendJson,
+        resolveScopeRequest: (request) => resolveScopeRequest(ctx, registry, request),
+      })) return;
       // Scoped callers are owner-only by construction; legacy callers keep the old fail-closed
       // requestRejection projection. `ui.devtools` is scoped-only: the legacy uiState() shape must
       // not expose the loopback port/target id even to an accepted old client.
@@ -14363,7 +16573,7 @@ export function apply(ctx) {
         return;
       }
       if (req.method === 'GET' && action === '/state') {
-        const { entry } = await select();
+        const { entry, resolved } = await select();
         selected = entry;
         const runtime = entry.runtime;
         if (runtime.running) {
@@ -14371,7 +16581,10 @@ export function apply(ctx) {
           // Same for the 500ms GUI state poll: coalesced + ≥200ms throttled, no standing timer.
           runtime.refreshViewObservationSoon();
         }
-        sendJson(res, 200, projected(runtime));
+        sendJson(res, 200, {
+          ...projected(runtime),
+          ...registry.providerFacts(entry, resolved),
+        });
         return;
       }
       if (req.method === 'GET' && action === '/metrics') {
@@ -14404,6 +16617,7 @@ export function apply(ctx) {
           sendJson(res, 403, { ok: false, ...error.payload(), error: error.message });
           return;
         }
+        crossEnvironment.assertGuiAllowed(scopeRequest);
         let ack;
         try {
           const request = normalizeAnnotationPublish(await readAnnotationBody(req, ANNOTATION_LIMITS.maxBodyBytes));
@@ -14472,11 +16686,16 @@ export function apply(ctx) {
         return;
       }
       if (action === '/ensure') {
+        // Environment gate (A10): a legacy/unscoped caller must not warm up (or navigate) a page
+        // for an environment the configuration disabled. This runs for scoped *and* legacy
+        // callers, before `select()` can create a page, so the bypass cannot resurrect Chromium.
+        crossEnvironment.assertGuiAllowed(scopeRequest);
         const { entry } = await select();
         selected = entry;
         registry.touch(entry);
         // A URL here is a page write, not a warm-up: gate it exactly like /navigate so a GUI
-        // caller cannot navigate a tab an Agent owns.
+        // caller cannot navigate a tab an Agent owns. The lease gate stays scoped-only; the
+        // environment gate above applies to every caller.
         if (body.url && scoped) assertGuiPageWrite(entry.runtime, scopeRequest.mode === 'session' ? scopeRequest.sessionId : null);
         await entry.runtime.run(async () => {
           await entry.runtime.ensure();
@@ -14487,6 +16706,9 @@ export function apply(ctx) {
         return;
       }
       if (action === '/navigate') {
+        // Environment gate (A10): the legacy compatibility route used to skip every config check
+        // unless the caller was scoped, so `enabledEnvironments=[]` still let it navigate.
+        crossEnvironment.assertGuiAllowed(scopeRequest);
         const { entry } = await select();
         selected = entry;
         registry.touch(entry);
@@ -14512,6 +16734,8 @@ export function apply(ctx) {
         return;
       }
       if (action === '/reload') {
+        // A10: reload/history are page writes too; the environment switch gates every caller.
+        crossEnvironment.assertGuiAllowed(scopeRequest);
         // These two routes exist only for the authenticated GUI. Scoped callers already passed
         // the strict owner-only gate above; legacy callers keep the historical check.
         if (!scoped) {
@@ -14528,6 +16752,7 @@ export function apply(ctx) {
         return;
       }
       if (action === '/history') {
+        crossEnvironment.assertGuiAllowed(scopeRequest); // A10: page write, same gate as /reload.
         if (!scoped) {
           const rejection = requestRejection(req);
           if (rejection) { rejectUi(res, rejection); return; }
@@ -14542,6 +16767,9 @@ export function apply(ctx) {
         return;
       }
       if (action === '/viewport') {
+        // A10: changing the shared viewport is a page write; a disabled Web environment must not
+        // drive it through the legacy GUI route.
+        crossEnvironment.assertGuiAllowed(scopeRequest);
         // Two shapes (docs/viewport-control.md):
         //   legacy {width,height}                 -> historical Number/round/clamp, same reply
         //   v1 {version:1, ...patch, expectedRevision?, originId?} -> strict, same validation as
@@ -14609,6 +16837,7 @@ export function apply(ctx) {
         return;
       }
       if (action === '/input') {
+        crossEnvironment.assertGuiAllowed(scopeRequest); // A10: same environment gate as /navigate.
         const { entry } = await select();
         selected = entry;
         registry.touch(entry);
@@ -14624,7 +16853,57 @@ export function apply(ctx) {
         sendJson(res, 200, { ok: true, applied });
         return;
       }
+      if (action === '/context-menu' || action === '/context-action') {
+        crossEnvironment.assertGuiAllowed(scopeRequest);
+        const { entry } = await select();
+        selected = entry;
+        registry.touch(entry);
+        if (scoped) assertGuiPageWrite(entry.runtime, scopeRequest.mode === 'session' ? scopeRequest.sessionId : null);
+        const result = await entry.runtime.run(async () => {
+          entry.runtime.touchHuman();
+          return action === '/context-menu'
+            ? openPageContextMenu(entry.runtime, body)
+            : applyPageContextAction(entry.runtime, body);
+        });
+        registry.markRecent(entry);
+        sendJson(res, 200, { ok: true, ...result, state: projected(entry.runtime) });
+        return;
+      }
+      if (action === '/select') {
+        // Panel-side native <select> write (POST /select, body {value, selector?}).
+        //
+        // Why this exists: the popup of a native <select> is drawn by the browser UI layer, so the
+        // panel's frame shows nothing and a mouse user cannot pick an option. The panel renders its
+        // own list (POST /element gives it the options) and writes the chosen value back here.
+        //
+        // Gate order is byte-for-byte the same as `/input` — environment/config gate, scoped
+        // ownership + lease (BUSY), body validation, and only then the serial queue + dispatch:
+        //   * `crossEnvironment.assertGuiAllowed(scopeRequest)` first (A10: a disabled Web
+        //     environment must not be bypassed through a panel route);
+        //   * `assertGuiPageWrite` before anything reaches the page, so a refused write dispatches
+        //     nothing at all (the tests assert the interception point, not a message);
+        //   * the body is validated outside `runtime.run`, so a bad request costs zero CDP;
+        //   * `runtime.run` gives the same single-owner serial queue and lease semantics as input.
+        // A refusal is a panel-facing input answer: INVALID_ARGUMENT is in NON_PAGE_ERROR_CODES, so
+        // a rejected value never overwrites the page's `lastError` projection.
+        crossEnvironment.assertGuiAllowed(scopeRequest); // A10: same environment gate as /input.
+        const { entry } = await select();
+        selected = entry;
+        registry.touch(entry);
+        if (scoped) assertGuiPageWrite(entry.runtime, scopeRequest.mode === 'session' ? scopeRequest.sessionId : null);
+        const request = normalizeSelectWriteRequest(body);
+        if (!request.ok) {
+          const refused = new BrowserError(request.code, request.message, request.details);
+          sendJson(res, scopeHttpStatus(request.code), { ok: false, ...refused.payload(), error: refused.message });
+          return;
+        }
+        const applied = await entry.runtime.run(() => entry.runtime.selectValue(request));
+        registry.markRecent(entry);
+        sendJson(res, 200, { ok: true, value: applied.value, selectedIndex: applied.selectedIndex, selector: request.selector });
+        return;
+      }
       if (action === '/eval') {
+        crossEnvironment.assertGuiAllowed(scopeRequest); // A10: same environment gate as /navigate.
         const { entry } = await select();
         selected = entry;
         registry.touch(entry);
@@ -14635,12 +16914,18 @@ export function apply(ctx) {
         return;
       }
       if (action === '/screenshot') {
+        crossEnvironment.assertGuiAllowed(scopeRequest);
         const { entry } = await select();
         selected = entry;
         registry.touch(entry);
         // `canvas:true` enables the canvas-space seed provenance (O = 0 keeps the raw single-CDP
         // PNG path). Empty/legacy bodies keep the historical raw reply shape byte-for-byte.
         const canvas = body && typeof body === 'object' && body.canvas === true;
+        // `includeAnnotations:true` (annot bar → 截图): the panel asks for the SAME composited
+        // capture the agent's `browser_screenshot{includeAnnotations:true}` produces, so the human
+        // can hand its own page+notes to the chat as one image. It goes through `capture()`, i.e.
+        // the documented canvas-space path, and therefore also carries `capture`.
+        const includeAnnotations = body && typeof body === 'object' && body.includeAnnotations === true;
         // The panel's seed capture is a display request, not a lifecycle action: a closed primary
         // must stay closed (the empty tab state), otherwise every panel mount would resurrect a
         // blank tab. Agent screenshot calls go through the tool runtime, not this GUI route.
@@ -14648,18 +16933,28 @@ export function apply(ctx) {
           sendJson(res, 200, { ok: true, closed: true, image: null, capturedAt: Date.now() });
           return;
         }
-        const shot = await entry.runtime.run(() => entry.runtime.screenshot(canvas ? { canvas: true } : {}));
+        const shot = includeAnnotations
+          ? await entry.runtime.run(() => entry.runtime.capture({ scale: 1, includeAnnotations: true }))
+          : await entry.runtime.run(() => entry.runtime.screenshot(canvas ? { canvas: true } : {}));
         registry.markRecent(entry);
+        const capture = shot.capture || null;
+        const viewport = capture && capture.viewport ? capture.viewport : null;
         sendJson(res, 200, {
           ok: true,
           image: shot.base64,
-          viewport: shot.viewport,
-          capturedAt: shot.capturedAt,
-          ...(canvas ? { view: shot.view, capture: shot.capture } : {}),
+          viewport: viewport || shot.viewport || null,
+          capturedAt: (capture && capture.capturedAt) || shot.capturedAt || Date.now(),
+          ...(includeAnnotations ? {
+            capture,
+            // Same metadata the tool reports: revision/context/source/truncation of the frozen
+            // document, so the panel can say which document the picture shows.
+            annotations: (capture && capture.annotations) || null,
+          } : canvas ? { view: shot.view, capture } : {}),
         });
         return;
       }
       if (action === '/tabs') {
+        crossEnvironment.assertGuiAllowed(scopeRequest);
         const { entry } = await select();
         selected = entry;
         const primary = registry.primaryEntry(entry) || entry;
@@ -14687,13 +16982,23 @@ export function apply(ctx) {
         // scope binding remain stable; the shared host exits only when no page is left.
         const { entry } = await select({ create: false });
         selected = entry;
-        if (entry) {
-          registry.touch(entry);
-          // P0-E: primary close only makes it cold; child tabs stay live. Closing a page is a
-          // lifecycle action, not page input, so it is not gated by the per-tab Agent lease;
-          // browser_tabs.close keeps its own session/lease rule.
-          await entry.runtime.run(() => entry.runtime.close());
+        if (!entry) {
+          // A scoped close that names no live runtime must not answer ok:true: the panel would
+          // drop its tab locally while the Host kept the page (an unresolved scope binding used to
+          // look like a successful close). Legacy callers keep the historical idempotent reply.
+          if (!scoped) {
+            sendJson(res, 200, { ok: true });
+            return;
+          }
+          const error = new BrowserError('SCOPE_NOT_FOUND', '关闭请求指向的运行时不存在', { scope: 'binding' });
+          sendJson(res, 404, { ok: false, ...error.payload(), error: error.message });
+          return;
         }
+        registry.touch(entry);
+        // P0-E: primary close only makes it cold; child tabs stay live. Closing a page is a
+        // lifecycle action, not page input, so it is not gated by the per-tab Agent lease;
+        // browser_tabs.close keeps its own session/lease rule.
+        await entry.runtime.run(() => entry.runtime.close());
         sendJson(res, 200, { ok: true });
         return;
       }
@@ -14701,7 +17006,7 @@ export function apply(ctx) {
       sendJson(res, 404, { ok: false, ...error.payload(), error: error.message });
     } catch (error) {
       const classified = asBrowserError(error);
-      if (selected) {
+      if (selected && !NON_PAGE_ERROR_CODES.has(classified.code)) {
         selected.runtime.setError(classified.message, {
           actionId: null,
           target: selected.runtime.url ? redactUrl(selected.runtime.url) : null,
@@ -14713,13 +17018,96 @@ export function apply(ctx) {
 
   ctx.effect(() => ctx.webServer.register({ kind: 'prefix', path: ROUTE_PREFIX, handler: handle }), 'ui-testing: http routes');
 
+  /**
+   * Describe the *live* target this tool call is running against, when it has one.
+   *
+   * Readiness must answer "is the target this session is actually driving bound?", not a static
+   * projection: a running page with a runtimeId is a bound target with a connected transport
+   * (plan §6.2 six axes, A13). Diagnostics never start a target, so an idle runtime reports null
+   * and the axes stay `not-probed`/`unbound` truthfully.
+   */
+  function liveReadinessTarget(exec, runtime) {
+    const rt = runtime || exec?.runtime || null;
+    if (!rt || typeof rt !== 'object') return null;
+    // A created-but-idle runtime entry is not a bound target: only a running page (or a live CDP
+    // transport) proves the connection/target axes. Otherwise the probe's not-probed/unbound stay.
+    const live = rt.running === true || Boolean(rt.cdp && rt.cdp.closed !== true);
+    if (!live) return null;
+    const runtimeId = rt.runtimeId || rt.id || null;
+    if (!runtimeId) return null;
+    return {
+      sessionId: exec?.agent?.id ? String(exec.agent.id) : null,
+      runtimeId: String(runtimeId),
+      url: typeof rt.url === 'string' ? redactUrl(rt.url) : null,
+      transport: rt.transport || (rt.send ? 'ws' : null),
+      // The Runtime keeps the page/document generation as `generation`; both names are accepted so
+      // the target axis can carry a real generation instead of a null placeholder.
+      pageGeneration: Number.isInteger(rt.pageGeneration) ? rt.pageGeneration
+        : (Number.isInteger(rt.generation) ? rt.generation : null),
+      documentEpoch: Number.isInteger(rt.documentEpoch) ? rt.documentEpoch : null,
+    };
+  }
+
   const text = (value) => [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value) }];
+  /**
+   * P0 data access for tools (A01): one entry through the environment's P0 provider.
+   *
+   * The provider owns target binding, generation and the evidence envelope; the tool keeps its
+   * public result shape. `raw: true` (default) keeps platform-shaped payloads untouched.
+   */
+  const p0 = async (exec, family, method, args = {}, extra = {}) => {
+    const result = await crossEnvironment.p0Call({
+      family,
+      method,
+      args,
+      exec,
+      runtime: exec?.runtime ?? null,
+      entry: extra.entry ?? null,
+      meta: exec?.meta ?? null,
+      selection: extra.selection ?? null,
+      resolvedScope: extra.resolvedScope ?? null,
+      raw: extra.raw !== false,
+    });
+    return extra.withEvidence === true ? result : result.value;
+  };
   const register = (definition) => {
     const execute = definition.execute;
     if (!definition.timeoutMs) definition.timeoutMs = 30000;
     definition.execute = async (args, exec = {}) => {
+      // Execution guard: conditional registration alone is not enough (old calls, /test/invoke,
+      // programmatic dispatch). The same snapshot gates the actual dispatch.
+      crossEnvironment.assertToolAllowed(exec.agent, definition.name);
+      // A14: the Web-only module chain is resolved here, once, before any page/state work — and
+      // only when this call actually needs it. Neutral diagnostics must still answer on a host
+      // whose Web environment is disabled, so for them the load is optional and failure-tolerant:
+      // the capability matrix then reports "limits not available" instead of the tool failing.
+      // The two neutral diagnostics describe the Web capability matrix, so they need the module
+      // chain too — but they must keep answering if it cannot be loaded (a disabled/absent
+      // environment then reports "limits unavailable" instead of failing the whole tool).
+      if (definition.name !== 'browser_fake_probe') {
+        if (['browser_state', 'browser_capabilities'].includes(definition.name)) {
+          try { await ensureWebHostModules(); } catch { /* diagnostics keep answering */ }
+        } else {
+          await ensureWebHostModules();
+        }
+      }
+      const admissionSnapshot = crossEnvironment.snapshotForAgent(exec.agent);
       const sessionId = String(exec.agent?.id || 'anonymous');
+      // M2a: prove *who* is calling before any scope resolution, entry creation or CDP. An
+      // unprovable identity must fail while there is still nothing to dispatch to.
+      // The diagnostic dispatcher is the one narrow exception: its probes act as the panel inside the
+      // root of the page the run froze (see `diagnosticPrincipalFor`).
+      const principal = diagnosticPrincipalFor(exec) || resolveToolPrincipal(ctx, exec);
+      // The call's real effects are known before any scope/entry work: they decide which selection
+      // this call uses (observation vs work) and later authorise its page part. One expansion, one
+      // truth — re-deriving "is this a read?" from the tool name is how a read tool ends up writing.
+      const callEffects = operationEffect(definition.name, args);
+      const observeOnlyCall = callEffects.length > 0
+        && callEffects.every((row) => row.effect === EFFECT.OBSERVE || row.effect === EFFECT.CALLER_LOCAL);
       const meta = { actionId: randomUUID(), sessionId, startedAt: Date.now(), tool: definition.name,
+        configRevision: admissionSnapshot.revision,
+        environment: admissionSnapshot.environment,
+        adapterId: admissionSnapshot.adapterId,
         // Expressions and input text may contain secrets: record a bounded structural summary.
         args: Object.fromEntries(Object.entries(args || {}).map(([key, value]) => [key,
           key === 'url' ? redactUrl(String(value))
@@ -14738,6 +17126,15 @@ export function apply(ctx) {
       // no recent/error bookkeeping. It may still read another owner's cached view.
       const readOnly = typeof definition.readOnly === 'function' && definition.readOnly(args) === true;
       const isHttpRequest = definition.name === 'browser_http_request';
+      // test-only fake environment tool: no Web runtime/page is created or touched.
+      const isFakeTool = definition.name === 'browser_fake_probe';
+      // Environment-neutral diagnostics (browser_state / browser_capabilities) answer "what is
+      // here / why is it refused". Outside the Web environment there is no page to report, and
+      // creating one would start a target the user did not enable — so they run without a runtime.
+      // Only `browser_state` needs the runtime-free path: `browser_capabilities` is documented as
+      // never starting a target, so it keeps its (inert) page entry and reports the adapter matrix.
+      const neutralWithoutWeb = definition.name === 'browser_state'
+        && admissionSnapshot.environment !== 'web';
       // Web P0 network read-only tools (session.status/reset, events, detail, trace query, evidence,
       // subscribe) are scope-local reads: they resolve the workspace runtime but never take the page
       // queue, the lease, or lazily start Chromium (docs/network-p0.md, R1-5).
@@ -14748,25 +17145,47 @@ export function apply(ctx) {
       let primaryEntry;
       let selection;
       let runtime;
+      let resolvedScope = null;
       try {
-        const resolved = await resolveScopeRequest(ctx, registry, toolScopeRequest(exec));
+        // Diagnostic dispatcher (integration/diagnose.js): the caller already froze the scope and
+        // the runtime it is looking at, and re-resolving here would manufacture a second runtime
+        // for the same workspace (or fail with SCOPE_NOT_FOUND for an unassigned scope). The call
+        // still goes through admission, the adapter and Runtime.run below.
+        const diagnostic = exec.diagnosticScope;
+        if (diagnostic && diagnostic.entry && diagnostic.resolved) {
+          resolvedScope = diagnostic.resolved;
+          meta.scope = resolvedScope.scope;
+          if (definition.name !== 'browser_http_request' && definition.name !== 'browser_fake_probe' && !neutralWithoutWeb) {
+            entry = diagnostic.entry;
+            primaryEntry = entry;
+            runtime = entry.runtime;
+            selection = null;
+          }
+          throw { __diagnosticScope: true };
+        }
+        const resolved = await resolveScopeRequest(ctx, registry, toolScopeRequest(exec, principal));
+        resolvedScope = resolved;
         meta.scope = resolved.scope;
         // The independent HTTP tool is evidence-only: resolve identity, but never create/touch a
-        // page entry (no queue, no lease, no page).
-        if (!isHttpRequest) {
+        // page entry (no queue, no lease, no page). The fake tool has no Web runtime either.
+        if (!isHttpRequest && !isFakeTool && !neutralWithoutWeb) {
           entry = registry.getOrCreate(resolved);
           primaryEntry = entry;
           if (isTabsTool) {
             runtime = entry.runtime;
           } else {
-            const selected = registry.resolveSessionTab(entry, sessionId);
+            const selected = registry.resolveSessionTab(entry, sessionId, {
+              mode: observeOnlyCall ? 'read' : 'work',
+            });
             entry = selected.entry;
             selection = selected.selection;
             runtime = entry.runtime;
           }
         }
       } catch (error) {
-        if (!isHttpRequest) {
+        if (error && error.__diagnosticScope) {
+          // Scope already frozen by the diagnostic dispatcher: nothing left to resolve.
+        } else if (!isHttpRequest && !isFakeTool && !neutralWithoutWeb) {
           const classified = asBrowserError(error);
           const evidence = { ...meta, finishedAt: Date.now(), target: '' };
           classified.details = losslessJson({ ...classified.details, ...evidence }, definition.name + '.details', []);
@@ -14782,10 +17201,45 @@ export function apply(ctx) {
       const hostOnly = typeof definition.hostOnly === 'function' && definition.hostOnly(args, runtime) === true;
       // The independent HTTP tool must not enter the page queue, the lease, activity or lastError;
       // only real page/network operations participate in the error projection.
-      const pageOperation = !readOnly && !hostOnly && !diagnostic && !isHttpRequest && !isNetworkRead;
+      const pageOperation = !readOnly && !hostOnly && !diagnostic && !isHttpRequest && !isNetworkRead && !isFakeTool;
       const actionTarget = definition.name === 'browser_navigate'
         ? redactUrl(String((args && args.url) || ''))
         : (runtime && runtime.url ? redactUrl(runtime.url) : null);
+      // M2a: authorise the *page* part of this call before it can touch a target.
+      //
+      // This runs after the target has been resolved (so the verdict is about the page this call
+      // will really drive) and before `runtime.run` — i.e. before ensure, bringToFront, the queue
+      // and any CDP command. `browser_tabs` is excluded here because it authorises per action and
+      // per tab inside its own implementation, where the target is known.
+      let pageEffects = null;
+      let pageControlRevision = null;
+      let autoAcquired = false;
+      if (pageOperation && entry && !isTabsTool) {
+        const effects = callEffects.filter((row) => row.resource === RESOURCE.PAGE);
+        if (effects.length > 0) {
+          pageEffects = effects;
+          const verdict = authorizeAll({
+            principal,
+            ...registry.accessOf(entry),
+            effects,
+            operation: definition.name,
+          });
+          if (!verdict.allowed) throw registry.accessError(verdict.verdict, definition.name);
+          if (verdict.verdict.autoAcquire === true) {
+            // Atomic "take over, then dispatch" (plan §5.1): a Lead writing an idle member page
+            // acquires control *inside this call* and keeps it until an explicit release, so a
+            // member cannot slip a write into the middle of a multi-step Lead flow. The drain/commit
+            // pair is the same bounded, non-aborting one the explicit `acquire` action uses.
+            const acquired = await registry.acquireControl(entry, principal, {
+              expectedControlRevision: registry.accessOf(entry).control.controlRevision,
+              timeoutMs: TAB_ACQUIRE_TIMEOUT_DEFAULT_MS,
+              signal: exec.signal,
+            });
+            autoAcquired = acquired.changed === true;
+          }
+          pageControlRevision = registry.accessOf(entry).control?.controlRevision ?? null;
+        }
+      }
       // Every tool value leaves through this single lossless-JSON boundary.
       const finish = (value, target) => {
         // Envelope ordering matters per tool family (docs/network-p0.md):
@@ -14795,24 +17249,49 @@ export function apply(ctx) {
         const tabMeta = selection
           ? { id: selection.tabId, runtimeId: runtime ? runtime.runtimeId : null, selectionRevision: selection.revision }
           : (runtime ? { id: 'primary', runtimeId: runtime.runtimeId, selectionRevision: 0 } : null);
+        const controlMeta = autoAcquired
+          ? { autoAcquired: true, control: registry.controlProjection(entry) }
+          : {};
         const result = isNetworkRead
-          ? { ...meta, ...value, agentSessionId: meta.sessionId, ...(tabMeta ? { tab: tabMeta } : {}), finishedAt: Date.now(), target }
-          : { ...value, ...meta, ...(tabMeta ? { tab: tabMeta } : {}), finishedAt: Date.now(), target };
+          ? { ...meta, ...value, agentSessionId: meta.sessionId, ...(tabMeta ? { tab: tabMeta } : {}), ...controlMeta, finishedAt: Date.now(), target }
+          : { ...value, ...meta, ...(tabMeta ? { tab: tabMeta } : {}), ...controlMeta, finishedAt: Date.now(), target };
         const notes = [];
         const clean = losslessJson(result, definition.name, notes);
         if (!clean || typeof clean !== 'object' || Array.isArray(clean)) throw new BrowserError('INTERNAL', '工具返回值不是对象');
         if (notes.length > 0) clean.sanitized = notes;
         return clean;
       };
+      // Every tool implementation goes through the environment's capability adapter. The caller
+      // keeps the existing execution-class branch (queue/ensure/lease); the adapter validates
+      // admission/identity and wraps the value with an evidence envelope.
+      const runThroughAdapter = (thunk, executionClass) => crossEnvironment.invokeTool({
+        name: definition.name,
+        args,
+        exec,
+        thunk,
+        // The wrapper branch decides queue/ensure; the adapter class is the operation's declared
+        // class refined by its action (e.g. network_session status=readOnly, start=hostOnly).
+        executionClass: crossEnvironment.executionClassFor(definition.name, args) || executionClass,
+        resolvedScope,
+        runtime,
+        entry,
+        selection,
+        meta,
+      });
       try {
         if (isTabsTool) {
-          const value = await execute(args, { ...exec, meta, sessionId, runtime, primaryEntry, registry, httpClient });
+          const value = await runThroughAdapter(() => execute(args, {
+            ...exec, meta, sessionId, principal, runtime, primaryEntry, registry, httpClient,
+          }), 'tabs');
           return finish(value, runtime && runtime.url ? redactUrl(runtime.url) : '');
         }
-        if (isHttpRequest || isNetworkRead) {
+        if (isHttpRequest || isNetworkRead || isFakeTool) {
           // Independent dispatch branch: no ensure/run/claim/touchAgent, no page queue, no
           // profile, no page lastError. The implementation does its own argument validation.
-          const value = await execute(args, { ...exec, meta, sessionId, runtime, httpClient });
+          const value = await runThroughAdapter(
+            () => execute(args, { ...exec, meta, sessionId, principal, runtime, httpClient }),
+            isFakeTool ? 'page' : (isHttpRequest ? 'independentHttp' : 'networkRead'),
+          );
           return finish(value, meta.target || '');
         }
         // Optional pure pre-flight, outside the queue: an invalid argument must cost zero CDP
@@ -14823,10 +17302,27 @@ export function apply(ctx) {
           // Cache-only diagnostic / host-memory-only action: deliberately outside run() so it cannot activate the page,
           // wait behind the queue, claim the lease or mark the entry recent.
           meta.target = runtime.url ? redactUrl(runtime.url) : '';
-          const value = await execute(args, { ...exec, meta, sessionId, runtime, httpClient });
+          const value = await runThroughAdapter(
+            () => execute(args, { ...exec, meta, sessionId, principal, runtime, httpClient }),
+            hostOnly ? 'hostOnly' : 'readOnly',
+          );
           return finish(value, meta.target);
         }
         const value = await runtime.run(async () => {
+          // Dispatch-time re-check (plan §5.3 last bullet: "真正派发前重验 … ownership/controlRevision").
+          // Between admission and this point another actor may have drained the page; the answer is
+          // TAB_CONTROL_CHANGED with ZERO dispatch — never a write against a page whose control moved
+          // while the call was queued.
+          if (pageEffects) {
+            const recheck = authorizeAll({
+              principal,
+              ...registry.accessOf(entry),
+              effects: pageEffects,
+              operation: definition.name,
+              expectedControlRevision: pageControlRevision,
+            });
+            if (!recheck.allowed) throw registry.accessError(recheck.verdict, definition.name);
+          }
           meta.target = runtime.url ? redactUrl(runtime.url) : '';
           if (pageOperation) runtime.touchAgent(definition.name === 'browser_navigate' ? '正在打开 ' + redactUrl(String(args?.url || '')) : ({
             browser_eval: '执行脚本', browser_input: '派发输入事件', browser_network: '读取网络记录',
@@ -14844,12 +17340,27 @@ export function apply(ctx) {
           // ever claiming causality.
           runtime.netMark({ tool: definition.name, actionId: meta.actionId, kind: 'tool', text: 'begin' });
           try {
-            return await execute(args, { ...exec, meta, runtime, httpClient });
+            return await runThroughAdapter(
+              () => execute(args, { ...exec, meta, runtime, httpClient, sessionId, principal }),
+              diagnostic ? 'diagnostic' : 'page',
+            );
           } finally {
             runtime.netMark({ tool: definition.name, actionId: meta.actionId, kind: 'tool', text: 'end' });
           }
-        }, { signal: exec.signal, sessionId, agent: pageOperation,
-          action: pageOperation ? { actionId: meta.actionId, target: actionTarget } : undefined });
+        }, {
+          signal: exec.signal,
+          sessionId,
+          // A read-only page operation must not take the single-owner write lease: claiming it made
+          // "look at a teammate's page" block that teammate's next write for 15s. `activate()` still
+          // runs inside run() — non-interference of the *foreground* switch is NOT implemented here
+          // (see the M4 report: measured, reported, not papered over).
+          agent: pageOperation && !observeOnlyCall,
+          // An all-observe call must not bring the page to the front: that is what made a read of a
+          // teammate's page flip its visibilityState / freeze its background frames. Reads still run
+          // in this queue and still need read authorisation — only `activate()` is skipped.
+          activate: !observeOnlyCall,
+          action: pageOperation ? { actionId: meta.actionId, target: actionTarget } : undefined,
+        });
         if (pageOperation) {
           registry.touch(entry);
           registry.markRecent(entry);
@@ -14886,9 +17397,68 @@ export function apply(ctx) {
       }
     };
     testToolDefs.set(definition.name, definition);
-    return ctx.effect(() => ctx.tools.register(definition), 'ui-testing: tool ' + definition.name);
+    // Per-step admission: the same snapshot decides model-visible schema and dispatch. `when`
+    // must never throw (a rejected condition fails the whole step preparation).
+    const when = (context = {}) => {
+      try {
+        return crossEnvironment.toolAdmitted(context.agent, definition.name);
+      } catch {
+        return false;
+      }
+    };
+    // Registration is deferred to `syncToolVisibility()`, which registers the *union* of tool
+    // definitions once and lets the host resolve `when(agent)` per step. The host's declaration
+    // path (`ToolsService.resolve` -> the `systemPrompt.tools` provider reading
+    // `definitions(scope, toolSet)` in dsh-tools/lib/index.js) filters the model-facing list with
+    // that same admitted set, so a per-agent snapshot decides declaration and dispatch together
+    // (A08). The earlier global register/unregister sync leaked one agent's selection to every
+    // other agent in the process.
+    toolDefinitions.set(definition.name, { definition, when });
+    return null;
   };
 
+  /**
+   * Register the union of tool definitions, each with its per-agent `when` predicate.
+   *
+   * Registration no longer depends on the *global* selection: the host admits per step, so every
+   * environment's tools can stay registered without leaking into another agent's request (A08).
+   * Environment-neutral diagnostics stay registered in every environment (including a disabled
+   * one) so "why is it unavailable" remains answerable.
+   */
+  function syncToolVisibility() {
+    let wanted;
+    try {
+      wanted = crossEnvironment.declarableToolNames();
+    } catch (error) {
+      log('ui-testing: tool visibility sync skipped: ' + String((error && error.message) || error));
+      return;
+    }
+    for (const [name, dispose] of toolDisposers) {
+      if (wanted.has(name)) continue;
+      try { dispose(); } catch { /* best effort */ }
+      toolDisposers.delete(name);
+    }
+    for (const name of wanted) {
+      if (toolDisposers.has(name)) continue;
+      const entry = toolDefinitions.get(name);
+      if (!entry) continue;
+      try {
+        toolDisposers.set(name, ctx.tools.register(entry.definition, { when: entry.when }));
+      } catch (error) {
+        log('ui-testing: tool registration failed for ' + name + ': ' + String((error && error.message) || error));
+      }
+    }
+  }
+
+  const toolDefinitions = new Map();
+  const toolDisposers = new Map();
+  ctx.effect(() => () => {
+    for (const dispose of toolDisposers.values()) {
+      try { dispose(); } catch { /* best effort */ }
+    }
+    toolDisposers.clear();
+  }, 'ui-testing: tool visibility');
+
   register({
     name: 'browser_navigate',
     description: '在调试视图的内嵌浏览器里打开一个 HTTP(S) 地址。',
@@ -14922,7 +17492,8 @@ export function apply(ctx) {
     name: 'browser_screenshot',
     description: '截取内嵌浏览器的画面（PNG）：默认 canvas 视口 [C,C+W)×[C,C+H)、默认比例 = 当前共享显示比例 view.scale（冷启动 100%）；可选 scale（连续 0.1–4，可用小数；重新光栅化，不是位图放大）、'
       + 'region（canvas CSS 像素矩形；O=0 时与文档坐标相同，可为负 → blank 纯白）、persist（默认 false：写插件暂存目录，不落工作区）、out（工作区相对 .png，提供即视为持久留存）。'
-      + 'O≠0 时以真实 S 截页面再白底合成（重编码），证据 capture.canvas.composite=true；O=0 保持单次 CDP PNG 不重编码。'
+      + '用户提到标注、画、圈、框、箭头或笔迹等面板标注时，传 includeAnnotations:true，把已提交标注按当前画布坐标叠加到截图（含文字和画笔），返回 capture.annotations 版本与来源；默认 false。'
+      + 'O≠0 时以真实 S 截页面再白底合成（重编码），证据 capture.canvas.composite=true；O=0 且未叠加标注时保持单次 CDP PNG 不重编码。'
       + '只有 out / persist:true / DSH_UI_TESTING_CAPTURE_DIR 三者之一才持久落盘（0600、原子写入、绝不覆盖）；'
       + '暂存文件返回绝对路径并在插件卸载时删除。返回 PNG 结构/尺寸校验/空白识别/落盘/附件对比证据与 warnings；尺寸不符或 PNG 损坏时不交付图片。',
     parameters: {
@@ -14943,6 +17514,10 @@ export function apply(ctx) {
           },
           required: ['x', 'y', 'width', 'height'],
         },
+        includeAnnotations: {
+          type: 'boolean',
+          description: '默认 false。用户提到标注、画、圈、框、箭头、笔迹等面板标注时设为 true：将当前已提交的圆、矩形、线、箭头、画笔与文字叠加到浏览器截图，按 region/scale 一起裁剪缩放。只含 Host 已接受的标注，不含未提交草稿和面板工具栏；capture.annotations 记录版本、来源、过期与截断状态。标注是人类线索，不是页面事实。',
+        },
         persist: {
           type: 'boolean',
           description: '是否持久留存（默认 false）。false/省略 = 写插件暂存目录（返回绝对路径，插件卸载时删除，不落工作区）；true = 持久写入可用根（DSH_UI_TESTING_CAPTURE_DIR，未配置时为工作区）下的 output/capture/<actionId>.png；根不可用则 OUTPUT_PATH_INVALID，不回落。',
@@ -15001,10 +17576,12 @@ export function apply(ctx) {
       }
 
       // 3) The single capture (no retry, no second encoding).
-      const shot = await runtime.capture({ scale, region: request.region, scaleSource }, exec.signal);
+      // A01: the capture data plane goes through the P0 provider (target binding + evidence),
+      // while the screenshot tool keeps owning its public result shape.
+      const shot = await p0(exec, 'A', 'capture', { scale, region: request.region, scaleSource, includeAnnotations: request.includeAnnotations });
       const data = shot.pngBytes;
       const captured = shot.capture;
-      const product = await runtime.browserProduct(exec.signal);
+      const product = await p0(exec, 'A', 'product');
 
       const warnings = [];
       const sha256 = createHash('sha256').update(data).digest('hex');
@@ -15021,6 +17598,7 @@ export function apply(ctx) {
         coordinateSpace: captured.composite ? 'canvas-css-px' : 'document-css-px',
         out: request.out,
         persist: request.persist,
+        includeAnnotations: request.includeAnnotations,
       };
       const environment = {
         browser: 'chromium',
@@ -15068,6 +17646,7 @@ export function apply(ctx) {
         composite: captured.composite,
         contentRect: captured.contentRect,
         pageCapture: captured.pageCapture,
+        annotations: captured.annotations || null,
       };
       if (!sizeCheck.ok) {
         // Use the module's own verdict verbatim: CAPTURE_UPSCALED only says "larger than expected"
@@ -15322,7 +17901,10 @@ export function apply(ctx) {
   register({
     name: 'browser_input',
     description: '向内嵌浏览器派发鼠标 / 滚轮 / 键盘事件（T1 原生事件能力）。坐标使用页面 CSS 像素。'
-      + '修饰键用 modifiers（字符串数组 alt/ctrl/meta/shift，或 CDP 位掩码整数 Alt=1/Ctrl=2/Meta=4/Shift=8）。',
+      + '修饰键用 modifiers（字符串数组 alt/ctrl/meta/shift，或 CDP 位掩码整数 Alt=1/Ctrl=2/Meta=4/Shift=8）。'
+      + '带按键状态机：keyDown 记位、keyUp 清位，按住 Shift 后其它事件自动带上 shiftKey（synthesizeModifiers:false 可关）；'
+      + 'mouse 事件给 deltaX/deltaY 时按相对位移移动虚拟光标（无需知道绝对位置）；导航/关闭会清空状态。'
+      + '返回 {ok,applied,modifiers,held,cursor}，held 是当前仍按住的键。',
     parameters: {
       type: 'object',
       properties: {
@@ -15341,8 +17923,18 @@ export function apply(ctx) {
               buttons: { type: 'number', description: '按下的鼠标键位掩码（CDP buttons），移动/拖拽时需带上' },
               pointerType: { type: 'string', enum: ['mouse', 'pen'] },
               clickCount: { type: 'number' },
-              deltaX: { type: 'number' },
-              deltaY: { type: 'number' },
+              deltaX: {
+                type: 'number',
+                description: 'mouse：相对位移 X（虚拟光标 += deltaX；用于 pointer-lock 类"按增量移动"）；wheel：滚动增量',
+              },
+              deltaY: {
+                type: 'number',
+                description: 'mouse：相对位移 Y（同上）；wheel：滚动增量',
+              },
+              synthesizeModifiers: {
+                type: 'boolean',
+                description: '默认 true：把当前按住的修饰键自动合进本事件的 modifiers（页面 e.shiftKey 等）。false 用于刻意复现"按住但没带修饰位"的行为',
+              },
               modifiers: {
                 description: '修饰键：字符串数组 alt/ctrl/meta/shift，或 CDP 位掩码整数（Alt=1,Ctrl=2,Meta=4,Shift=8）。key/mouse/wheel 都支持。',
                 // Host-supported JSON-schema subset only (no minimum/maximum): the 0–15 range
@@ -15370,12 +17962,19 @@ export function apply(ctx) {
     },
     output: { schema: { type: 'object' }, render: (args, value) => text(value) },
     async execute(args, exec) {
-      const applied = await exec.runtime.input(args?.events, exec.signal);
-      return { ok: true, applied };
+      // `held`/`modifiers` are the state machine's echo: a model that lost track of a keyDown can
+      // see the leftover keys instead of guessing, and `cursor` is where relative moves now point.
+      const result = await exec.runtime.input(args?.events, exec.signal);
+      return { ok: true, ...result };
     },
   });
 
   register({
+    // Read-only metadata read: it resolves the workspace scope but never takes the page queue or the
+    // single-owner lease. The lease exists to serialise page *writes*; a traffic snapshot neither
+    // writes the page nor needs ownership, and holding it for the lease TTL would block the next
+    // page operation of another session in the same workspace.
+    networkRead: true,
     name: 'browser_network',
     description: '读取内嵌浏览器最近捕获的网络请求（T1 网络抓包，默认不含请求体）。',
     parameters: {
@@ -15410,7 +18009,7 @@ export function apply(ctx) {
     },
     output: { schema: { type: 'object' }, render: (args, value) => text(value) },
     async execute(args, exec) {
-      return exec.runtime.netSession(args || {}, exec, exec.signal);
+      return p0(exec, 'B', String(args?.action || 'start'), args || {});
     },
   });
 
@@ -15438,7 +18037,7 @@ export function apply(ctx) {
     },
     output: { schema: { type: 'object' }, render: (args, value) => text(value) },
     async execute(args, exec) {
-      return exec.runtime.netEvents(args || {});
+      return p0(exec, 'B', 'events', args || {});
     },
   });
 
@@ -15463,7 +18062,7 @@ export function apply(ctx) {
     },
     output: { schema: { type: 'object' }, render: (args, value) => text(value) },
     async execute(args, exec) {
-      return exec.runtime.netDetail(args || {});
+      return p0(exec, 'B', 'detail', args || {});
     },
   });
 
@@ -15494,7 +18093,7 @@ export function apply(ctx) {
     },
     output: { schema: { type: 'object' }, render: (args, value) => text(value) },
     async execute(args, exec) {
-      return exec.runtime.netTrace(args || {});
+      return p0(exec, 'B', 'trace', args || {});
     },
   });
 
@@ -15527,7 +18126,7 @@ export function apply(ctx) {
     },
     output: { schema: { type: 'object' }, render: (args, value) => text(value) },
     async execute(args, exec) {
-      return exec.runtime.netControl(args || {}, exec, exec.signal);
+      return p0(exec, 'B', 'control', args || {});
     },
   });
 
@@ -15556,7 +18155,7 @@ export function apply(ctx) {
     },
     output: { schema: { type: 'object' }, render: (args, value) => text(value) },
     async execute(args, exec) {
-      return exec.runtime.netEvidence(args || {}, exec);
+      return p0(exec, 'B', 'evidence', args || {});
     },
   });
 
@@ -15582,7 +18181,7 @@ export function apply(ctx) {
     },
     output: { schema: { type: 'object' }, render: (args, value) => text(value) },
     async execute(args, exec) {
-      return exec.runtime.netSubscribe(args || {}, exec.meta.sessionId);
+      return p0(exec, 'B', 'subscribe', args || {});
     },
   });
 
@@ -16015,15 +18614,25 @@ export function apply(ctx) {
     description: 'P0-E 多标签页：list/current 只读诊断；wait 纯内存等待调用开始后新出现的标签（0–30000ms，不启动 Chromium、不取 lease），命中返回 matched/matchedTab/elapsedMs/polls，超时抛 WAIT_TIMEOUT；'
       + 'select 选择当前 Agent 会话的 tab（原子 claim，不启动页面）；open 新建 about:blank 并选中；close 关闭当前会话持有 lease 的 tab（primary 只变 cold）。'
       + 'list 每项含 source/parentTabId/openEventId/createdAt/lastUsedAt/idleRemainingMs/manageable，并返回本 workspace 最近 8 条 blocked popup notices 与最近 8 条 recentClosed（reason closed|idle|evicted）。'
-      + '每个 Agent session 独立 selectedTab，默认 primary。',
+      + 'select 的 mode=work（默认）设置写目标、observe 设置只读观察目标；select 不再 claim 15 秒写租约，被拒绝的 select 不改变调用者已有选择。'
+      + '页面按 (workspace, provider, root) 分组：跨会话/跨 root 的标签根本不在同一组，因此 tabId 只会解析到本 root 的页。'
+      + '每行新增 accessVersion/rootSessionId/ownerSessionId/controllerSessionId/ownershipRevision/controlRevision/accessState/permissions；busy/owner/manageable 仍表示原短租约含义（不作为 ACL）。',
     parameters: {
       type: 'object',
       properties: {
-        action: { type: 'string', enum: ['list', 'current', 'select', 'open', 'close', 'wait'] },
+        action: {
+          type: 'string',
+          enum: ['list', 'current', 'select', 'open', 'close', 'wait', 'acquire', 'release', 'transfer'],
+          description: 'acquire/release/transfer 为队长控制权动作（仅本 root Lead）：acquire 进入 draining 等安全边界后接管，release 归还 owner，transfer 转交本 root 有效成员。',
+        },
+        toSessionId: { type: 'string', minLength: 1, maxLength: 128, description: '仅 transfer：本 root 内有效 roster 成员 SessionId（提交前重取原生 roster 校验）。' },
+        expectedControlRevision: { type: 'integer', minimum: 1, maximum: 9007199254740991, description: '仅 acquire/release/transfer：CAS 期望的 controlRevision，不匹配返回 TAB_CONTROL_CHANGED。' },
+        expectedOwnershipRevision: { type: 'integer', minimum: 1, maximum: 9007199254740991, description: '仅 transfer：CAS 期望的 ownershipRevision，不匹配返回 TAB_OWNERSHIP_STALE。' },
+        mode: { type: 'string', enum: ['work', 'observe'], description: '仅 select：work（默认）=该页成为本会话写目标，需本会话可写或本 root Lead 可管理；observe=只读观察目标，只改 observationSelection，不 claim、不 activate。' },
         tabId: { type: 'string', description: '目标 tabId（1–128 字符）；select/close 使用；wait 用它是等待该 tabId 出现（已存在则立即命中），其余 action 忽略。' },
         kind: { type: 'string', enum: ['primary', 'tab'], description: '仅 wait：只匹配该 kind（list 中 primary/tab）。' },
         source: { type: 'string', enum: ['primary', 'gui-popup', 'agent-open'], description: '仅 wait：只匹配该来源（primary 槽 / GUI 真人 popup 或 GUI + / Agent open）。' },
-        timeoutMs: { type: 'integer', minimum: 0, maximum: 30000, description: '仅 wait：等待预算，默认 5000；0 表示只采样一次。超时抛 WAIT_TIMEOUT（details 含 elapsedMs/polls/condition）。' },
+        timeoutMs: { type: 'integer', minimum: 0, maximum: 30000, description: '仅 wait/acquire：wait 是等待预算（默认 5000，0 只采样一次，超时 WAIT_TIMEOUT）；acquire 是等待安全边界的预算（默认 5000，超时返回 BUSY 并撤销 draining）。' },
         pollMs: { type: 'integer', minimum: 50, maximum: 1000, description: '仅 wait：轮询间隔，默认 100。' },
       },
       required: ['action'],
@@ -16038,37 +18647,159 @@ export function apply(ctx) {
       const registry = exec.registry;
       const sessionId = exec.sessionId;
       if (!primary || !registry) throw new BrowserError('UNSUPPORTED', 'browser_tabs 需要 workspace 页面组');
-      const allowed = ['action', 'tabId', 'kind', 'source', 'timeoutMs', 'pollMs'];
+      const allowed = ['action', 'tabId', 'mode', 'kind', 'source', 'timeoutMs', 'pollMs',
+        'toSessionId', 'expectedControlRevision', 'expectedOwnershipRevision'];
       if (args && Object.keys(args).some((key) => !allowed.includes(key))) {
         throw new BrowserError('INVALID_ARGUMENT', 'browser_tabs 不接受未知字段', { field: 'additionalProperties', allowed });
       }
-      if (action !== 'wait' && args && ['kind', 'source', 'timeoutMs', 'pollMs'].some((key) => args[key] !== undefined)) {
-        throw new BrowserError('INVALID_ARGUMENT', 'kind/source/timeoutMs/pollMs 只用于 wait', { field: 'action' });
+      // Every action declares exactly the fields it owns (ruling §7.5: "非所属 action 字段拒绝").
+      // A field that belongs to another action is never ignored: silently dropping
+      // `expectedControlRevision` would turn a CAS-guarded management call into an unguarded one.
+      const actionFields = {
+        list: ['action'],
+        current: ['action'],
+        open: ['action'],
+        select: ['action', 'tabId', 'mode'],
+        close: ['action', 'tabId'],
+        wait: ['action', 'tabId', 'kind', 'source', 'timeoutMs', 'pollMs'],
+        acquire: ['action', 'tabId', 'expectedControlRevision', 'timeoutMs'],
+        release: ['action', 'tabId', 'expectedControlRevision'],
+        transfer: ['action', 'tabId', 'toSessionId', 'expectedControlRevision', 'expectedOwnershipRevision'],
+      };
+      const foreign = Object.keys(args || {}).filter((key) => !(actionFields[action] || ['action']).includes(key));
+      if (foreign.length > 0) {
+        throw new BrowserError('INVALID_ARGUMENT', `${action} 不接受字段 ${foreign.join(',')}`, {
+          field: 'action', action, allowed: actionFields[action] || ['action'], rejected: foreign,
+        });
       }
+      const principal = exec.principal || null;
       if (action === 'list') {
+        // A01: the target list is a P0-E read; it goes through the provider so the projection and
+        // its evidence come from one place (the provider binds the calling target internally).
+        const listed = await p0(exec, 'E', 'list', {}, { entry: primary });
+        const providerRows = Array.isArray(listed) ? listed : (Array.isArray(listed?.tabs) ? listed.tabs : []);
+        // The provider projection answers "what target is this", not "may this caller act on it".
+        // The long-lived ownership/control/permission fields are added here, from the registry this
+        // call is authorised against, so the tool result carries one consistent ACL story (ruling
+        // §5 "每页返回") without teaching the P0 adapter about principals (that is M3's wiring).
+        const ownRows = new Map(registry.listTabs(primary, sessionId, principal)
+          .map((row) => [String(row.tabId), row]));
+        const tabs = providerRows.map((row) => {
+          const own = ownRows.get(String(row.tabId));
+          if (!own) return row;
+          return {
+            ...row,
+            accessVersion: own.accessVersion,
+            rootSessionId: own.rootSessionId,
+            creatorSessionId: own.creatorSessionId,
+            ownerSessionId: own.ownerSessionId,
+            controllerSessionId: own.controllerSessionId,
+            ownershipRevision: own.ownershipRevision,
+            controlRevision: own.controlRevision,
+            accessState: own.accessState,
+            permissions: own.permissions,
+          };
+        });
+        const selection = registry.selectionFor(primary, sessionId);
         return {
-          ok: true, action, tabs: registry.listTabs(primary, sessionId),
+          ok: true, action, tabs,
           notices: registry.noticesView(primary), recentClosed: registry.recentClosedView(primary),
-          selection: registry.selectionFor(primary, sessionId),
+          accessVersion: 1,
+          // `selection` stays the workSelection compatibility projection (ruling §5).
+          selection,
+          workSelection: selection,
+          observationSelection: selection.observationTabId
+            ? { ...selection, tabId: selection.observationTabId }
+            : null,
         };
       }
       if (action === 'current') {
+        // current never claims: it only confirms the caller's own (possibly retired) selection.
         const selection = registry.confirmSelection(primary, sessionId);
-        return { ok: true, action, tabId: selection.tabId, selection, confirmedResetReason: selection.confirmedResetReason || null };
+        return {
+          ok: true, action, tabId: selection.tabId, selection, workSelection: selection,
+          observationSelection: selection.observationTabId ? { ...selection, tabId: selection.observationTabId } : null,
+          confirmedResetReason: selection.confirmedResetReason || null,
+        };
       }
       if (action === 'select') {
         if (typeof args.tabId !== 'string' || !args.tabId.trim()) throw new BrowserError('INVALID_ARGUMENT', 'select 需要 tabId', { field: 'tabId' });
-        const selected = registry.selectTab(primary, sessionId, args.tabId.trim());
-        return { ok: true, action, tabId: selected.entry.tabId || selected.entry.viewId || 'primary', selection: selected.selection };
+        if (args.tabId.trim().length > 128) throw new BrowserError('INVALID_ARGUMENT', 'select.tabId 必须是 1–128 字符', { field: 'tabId' });
+        const mode = args.mode === undefined ? 'work' : String(args.mode);
+        if (!['work', 'observe'].includes(mode)) {
+          throw new BrowserError('INVALID_ARGUMENT', 'select.mode 只接受 work/observe', { field: 'mode', allowed: ['work', 'observe'] });
+        }
+        // A refusal throws before anything is written, so a denied select leaves the caller's
+        // existing work/observation selection exactly as it was (plan §5).
+        const selected = registry.selectTab(primary, sessionId, args.tabId.trim(), { mode, principal });
+        return {
+          ok: true, action, mode,
+          tabId: selected.entry.tabId || selected.entry.viewId || 'primary',
+          selection: selected.selection,
+          workSelection: selected.selection.tabId ? selected.selection : null,
+          observationSelection: selected.selection.observationTabId
+            ? { ...selected.selection, tabId: selected.selection.observationTabId } : null,
+          // select never claims a lease any more: say so instead of leaving callers to infer it.
+          claimed: false,
+        };
       }
       if (action === 'open') {
-        const opened = await registry.openTab(primary, sessionId, 'agent');
+        const opened = await registry.openTab(primary, sessionId, 'agent', { principal });
         return { ok: true, action, tabId: opened.entry.tabId || opened.entry.viewId, selection: opened.selection };
       }
       if (action === 'close') {
         const tabId = typeof args.tabId === 'string' && args.tabId.trim() ? args.tabId.trim() : registry.selectionFor(primary, sessionId).tabId;
-        const closed = await registry.closeTab(primary, sessionId, tabId);
-        return { ok: true, action, tabId: closed.closed };
+        const closed = await registry.closeTab(primary, sessionId, tabId, { principal });
+        const closedEntry = registry.tabEntry(primary, tabId) || registry.primaryEntry(primary);
+        return { ok: true, action, tabId: closed.closed, changed: true, control: registry.controlProjection(closedEntry) };
+      }
+      if (action === 'acquire' || action === 'release' || action === 'transfer') {
+        // Management path. Order is the contract (plan §5.2): principal → same root → Lead role →
+        // target → expected version. `authorizePage` inside the registry enforces the first four,
+        // the transition enforces the versions, and the drain wait is the only thing that runs
+        // before the commit — never an abort of somebody's in-flight page operation.
+        if (typeof args.tabId !== 'string' || !args.tabId.trim()) {
+          throw new BrowserError('INVALID_ARGUMENT', `${action} 需要 tabId`, { field: 'tabId' });
+        }
+        const target = registry.tabEntry(primary, args.tabId.trim());
+        if (!target) throw new BrowserError('TAB_NOT_FOUND', '标签不存在或不属于当前 workspace', { tabId: args.tabId, fallbackTabId: 'primary' });
+        const revisionOf = (value, field) => {
+          if (value === undefined || value === null) {
+            throw new BrowserError('INVALID_ARGUMENT', `${action} 需要 ${field}`, { field });
+          }
+          if (!Number.isInteger(value) || value < 1 || value > Number.MAX_SAFE_INTEGER) {
+            throw new BrowserError('INVALID_ARGUMENT', `${field} 必须是 1–9007199254740991 的整数`, { field });
+          }
+          return value;
+        };
+        const expectedControlRevision = revisionOf(args.expectedControlRevision, 'expectedControlRevision');
+        if (action === 'acquire') {
+          const timeoutMs = args.timeoutMs === undefined ? TAB_ACQUIRE_TIMEOUT_DEFAULT_MS : args.timeoutMs;
+          if (!Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > TAB_ACQUIRE_TIMEOUT_MAX_MS) {
+            throw new BrowserError('INVALID_ARGUMENT', `acquire.timeoutMs 必须是 0–${TAB_ACQUIRE_TIMEOUT_MAX_MS} 的整数`, {
+              field: 'timeoutMs', min: 0, max: TAB_ACQUIRE_TIMEOUT_MAX_MS,
+            });
+          }
+          const result = await registry.acquireControl(target, principal, {
+            expectedControlRevision, timeoutMs, signal: exec.signal,
+          });
+          return {
+            ok: true, action, changed: result.changed, waitedMs: result.waitedMs,
+            control: registry.controlProjection(target),
+          };
+        }
+        if (action === 'release') {
+          const result = registry.releaseControl(target, principal, { expectedControlRevision });
+          return { ok: true, action, changed: result.changed, control: registry.controlProjection(target) };
+        }
+        const expectedOwnershipRevision = revisionOf(args.expectedOwnershipRevision, 'expectedOwnershipRevision');
+        const result = registry.transferControl(target, principal, {
+          toSessionId: args.toSessionId, expectedControlRevision, expectedOwnershipRevision,
+        });
+        return {
+          ok: true, action, changed: result.changed, to: result.to,
+          control: registry.controlProjection(target),
+        };
       }
       if (action === 'wait') {
         const timeoutMs = args.timeoutMs === undefined ? TAB_WAIT_TIMEOUT_DEFAULT_MS : args.timeoutMs;
@@ -16159,6 +18890,125 @@ export function apply(ctx) {
     },
   });
 
+  register({
+    name: 'browser_annotation',
+    // Reading is a cached host read; every mutating action only rewrites the Host-side document.
+    // Neither branch may ensure a page, take the page queue/lease, activate the tab or touch
+    // `lastError`: a drawn note must cost the page nothing (docs/viewport-control.md).
+    readOnly: (args) => Boolean(args) && typeof args === 'object' && args.action === 'read',
+    hostOnly: (args) => Boolean(args) && typeof args === 'object' && args.action !== 'read',
+    // Pure pre-flight outside the queue: a refused call costs zero state and zero CDP.
+    preflight: (args) => { normalizeAgentAnnotationCall(args); },
+    description: 'P0 标注（人类可见）：读写调试视图里同一份标注文档，人类在面板里能立刻看到。'
+      + 'action=read 返回图形列表与 revision（不写、不需要前台）；'
+      + 'draw 追加图形（circle/rect/line/arrow/brush/text，对应面板的圆形/矩形/线段/箭头/画笔/文字）；'
+      + 'erase 按 id 或按点命中删除（对应橡皮擦）；clear 清空画布。'
+      + '每个图形可带 color（#rrggbb，默认 #ff3b30）、strokeWidth（1–20，默认 3）与 style=stroke|fill（对应外框/填充，仅圆形/矩形；'
+      + '也可显式 fill/stroke 布尔值，二者不可同时给）。'
+      + '坐标是画布 CSS px：q=d-C、O=C-S、页面视口 p=q+O=d-S；与 browser_screenshot{includeAnnotations:true} 同一空间。'
+      + 'draw/erase/clear 只在目标标签页正被人类在调试视图选中并可见时才允许，否则 ANNOTATION_NOT_FOREGROUND 零写入；'
+      + 'expectRevision 不一致返回 ANNOTATION_REVISION_CONFLICT。'
+      + '只写 Host 文档：不启动浏览器、不进页面队列、不占租约、不改页面 DOM 与 lastError；软限额与面板写面相同（128 图形/8192 点/65536 字节，Host 确定性裁剪并如实报 truncated）。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['action'],
+      properties: {
+        action: {
+          type: 'string',
+          enum: [...ANNOTATION_AGENT_ACTIONS],
+          description: 'read=读当前文档；draw=追加图形；erase=删除图形；clear=清空画布（后三者需要人类前台标签页）',
+        },
+        shapes: {
+          type: 'array',
+          minItems: 1,
+          maxItems: ANNOTATION_AGENT_MAX_SHAPES_PER_CALL,
+          description: 'draw 专用：要追加的图形（1–64 个）。省略 id 时 Host 从现有最大 id 续分配 a<N>；id 一旦重复或格式不符即整批拒绝。',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['type'],
+            properties: {
+              type: {
+                type: 'string',
+                enum: [...ANNOTATION_TYPES],
+                description: 'circle=圆形 / rect=矩形 / line=线段 / arrow=箭头 / brush=画笔（铅笔）/ text=文字（写问题、问号、说明）',
+              },
+              id: { type: 'string', description: '可选，形如 a12（^a[1-9][0-9]{0,15}$）；省略时由 Host 分配' },
+              color: { type: 'string', description: '可选，#rrggbb，默认 #ff3b30（面板默认色）' },
+              strokeWidth: {
+                type: 'integer',
+                description: `可选，粗细 ${ANNOTATION_LIMITS.strokeWidth[0]}–${ANNOTATION_LIMITS.strokeWidth[1]}，默认 ${ANNOTATION_AGENT_DEFAULT_STROKE}；箭头头部按端点+线宽派生`,
+              },
+              style: {
+                type: 'string',
+                enum: ['stroke', 'fill'],
+                description: '可选：stroke=外框（默认）/ fill=填充；只对 circle/rect 有意义（text 固定填充，line/arrow/brush 固定外框）。与 fill/stroke 互斥。',
+              },
+              fill: { type: 'boolean', description: '可选：显式填充位；与 style 互斥' },
+              stroke: { type: 'boolean', description: '可选：显式外框位；与 style 互斥' },
+              x: { type: 'number', description: 'rect/text 的 x（画布 CSS px）' },
+              y: { type: 'number', description: 'rect 的左上 y；text 的基线 y（画布 CSS px）' },
+              width: { type: 'number', description: 'rect 宽（>0）' },
+              height: { type: 'number', description: 'rect 高（>0）' },
+              cx: { type: 'number', description: 'circle 中心 x' },
+              cy: { type: 'number', description: 'circle 中心 y' },
+              rx: { type: 'number', description: 'circle 半径 x（>0）' },
+              ry: { type: 'number', description: 'circle 半径 y（>0）' },
+              x1: { type: 'number', description: 'line/arrow 起点 x' },
+              y1: { type: 'number', description: 'line/arrow 起点 y' },
+              x2: { type: 'number', description: 'line/arrow 终点 x（不得与起点重合）' },
+              y2: { type: 'number', description: 'line/arrow 终点 y' },
+              points: {
+                type: 'array',
+                minItems: 2,
+                description: 'brush 笔迹：按顺序的 [[x,y],...] 画布坐标点（Host 会按单笔 512 点上限下采样并保留首末点）',
+                items: {
+                  type: 'array',
+                  minItems: 2,
+                  maxItems: 2,
+                  items: { type: 'number' },
+                },
+              },
+              text: { type: 'string', description: `text 内容（超过 ${ANNOTATION_LIMITS.maxTextCodeUnits} 字符会截断并在 truncation 里计数）` },
+              fontSize: {
+                type: 'integer',
+                description: `可选，只能等于 ${ANNOTATION_LIMITS.textFontSize}（面板文字固定字号，其它值报 font-size-fixed）`,
+              },
+            },
+          },
+        },
+        ids: {
+          type: 'array',
+          minItems: 1,
+          maxItems: ANNOTATION_AGENT_MAX_SHAPES_PER_CALL,
+          description: 'erase 专用：要删除的图形 id（形如 a12）。与 point 至少给一个；不存在的 id 只是不命中，不报错。',
+          items: { type: 'string' },
+        },
+        point: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['x', 'y'],
+          description: 'erase 专用：橡皮擦命中点（画布 CSS px）。命中规则见文档：形状几何到该点距离 ≤ max(radius, strokeWidth/2, 6)。',
+          properties: {
+            x: { type: 'number', description: '命中点 x（画布 CSS px）' },
+            y: { type: 'number', description: '命中点 y（画布 CSS px）' },
+            radius: { type: 'number', description: `可选半径，默认 ${ANNOTATION_ERASE_DEFAULT_RADIUS}（1–4096）` },
+          },
+        },
+        expectRevision: {
+          type: 'integer',
+          description: '可选 CAS：与当前文档 revision 不同则 ANNOTATION_REVISION_CONFLICT（零写入，返回 currentRevision）',
+        },
+      },
+    },
+    output: { schema: { type: 'object' }, render: (args, value) => text(value) },
+    async execute(args, exec) {
+      const call = normalizeAgentAnnotationCall(args);
+      return exec.runtime.agentAnnotation(call, { sessionId: exec.sessionId });
+    },
+  });
+
   register({
     name: 'browser_state',
     description: '读取内嵌浏览器的当前状态：地址、标题、视口（旧 {width,height}、安全 view 投影与 canvas 画布投影）、控制权归属。'
@@ -16166,6 +19016,24 @@ export function apply(ctx) {
     parameters: { type: 'object', properties: {}, required: [] },
     output: { schema: { type: 'object' }, render: (args, value) => text(value) },
     async execute(args, exec) {
+      if (!exec.runtime) {
+        // Neutral diagnostic outside the Web environment (fake contract environment, or a Web
+        // environment the user disabled): report the environment-scoped truth instead of failing
+        // or starting a page. Nothing here claims a bound Web target.
+        const snapshot = crossEnvironment.snapshotForAgent(exec.agent);
+        return {
+          mode: 'idle',
+          activity: '空闲',
+          url: '',
+          environment: snapshot.environment,
+          adapterId: snapshot.adapterId,
+          configRevision: snapshot.revision,
+          enabledEnvironments: snapshot.enabledEnvironments,
+          running: false,
+          target: null,
+          note: 'no Web runtime: this environment has no page target (environment-neutral diagnostic)',
+        };
+      }
       await exec.runtime.refreshTitle(exec.signal);
       // Page-state ↔ network correlation (§3.3 / G2.6): one state mark per state read so the
       // timeline can replay url/title/revision changes next to the traffic they belong to.
@@ -16437,9 +19305,9 @@ export function apply(ctx) {
         ? normalized.scale
         : (Number.isFinite(liveScale) ? liveScale : runtime.view.scale);
       const scaleSource = normalized.scale !== undefined ? 'explicit' : 'view';
-      const shot = await runtime.capture({
+      const shot = await p0(exec, 'A', 'capture', {
         scale: resolvedScale, region: normalized.region ?? undefined, scaleSource,
-      }, exec.signal);
+      });
       const png = inspectPng(shot.pngBytes, { checkCrc: true });
       if (!png.ok) {
         throw new BrowserError('INVALID_PNG', '实时采集返回的字节不是结构完整的 PNG（不交付坏图）', {
@@ -17546,7 +20414,9 @@ export function apply(ctx) {
     description: 'T3 静态视觉：对两张显式源图做 YIQ 像素差异比较（固定算法 t3-v1），输出完整尺寸的标注差异 PNG（红=差异、黄=AA、灰=mask、蓝=区域 bbox）与 PASS/WARN/FAIL。'
       + 'before/after 必须显式给出；两图必须同像素尺寸，否则 VISION_SIZE_MISMATCH；region 是两图共同的图像像素 Rect。'
       + 'masks 缺省继承 before 基线元数据（before 非基线则空），显式 [] 清空；options/thresholds 逐字段覆盖 before 基线默认。'
-      + '全屏蔽无分母抛 VISION_EMPTY_COMPARISON，不返回 similarity=1；similarity 是阈值化差异覆盖率，不是语义相似度。',
+      + '全屏蔽无分母抛 VISION_EMPTY_COMPARISON，不返回 similarity=1；similarity 是阈值化差异覆盖率，不是语义相似度。'
+      + '映射门禁：两图几何映射不兼容（不同目标/缩放/坐标空间）时 verdict=BLOCKED/mapping-incompatible，不再给 PASS；'
+      + '只有显式 bitmapOnly=true 才降级为纯位图比较（标注 bitmap-only，不可当作几何验收）。',
     parameters: {
       type: 'object',
       additionalProperties: false,
@@ -17573,6 +20443,11 @@ export function apply(ctx) {
           properties: { warnRatio: { type: 'number' }, failRatio: { type: 'number' } },
           required: [],
         },
+        bitmapOnly: {
+          type: 'boolean',
+          description: '显式选择"只比较位图、不参与几何验收"（默认 false）。false 时两图 mapping 不兼容会返回 BLOCKED/mapping-incompatible，'
+            + '不再给 PASS；true 时只返回位图差异比率并标 bitmap-only，其结论不得当作几何验收证据。',
+        },
         output: {
           type: 'object',
           description: '差异 PNG 的落盘选择（同 browser_vision_image.output）：默认暂存，out/persist:true/env 触发持久。',
@@ -17651,6 +20526,13 @@ export function apply(ctx) {
         });
         if (comparisonRegions.length > T3_EVIDENCE_REGIONS) t3Warning(warnings, 'regions-truncated');
         if (!mappingCompatible) t3Warning(warnings, 'mapping-incompatible');
+        // Mapping gate (plan §4.5 / A03): a bitmap ratio over incompatible geometry is not an
+        // acceptance signal. Without an explicit `bitmapOnly` opt-in the comparison is BLOCKED, so
+        // "same pixels, different target region" can never come back as PASS.
+        const bitmapOnly = request.bitmapOnly === true;
+        const gatedVerdict = mappingCompatible ? verdict : (bitmapOnly ? verdict : 'BLOCKED');
+        const gatedReason = mappingCompatible ? 'ratio' : (bitmapOnly ? 'bitmap-only' : 'mapping-incompatible');
+        if (!mappingCompatible && bitmapOnly) t3Warning(warnings, 'advisory-only');
         const highlight = Buffer.isBuffer(diff.highlight) ? diff.highlight : Buffer.from(diff.highlight ?? []);
         const png = inspectPng(highlight, { checkCrc: true });
         if (!png.ok) throw new BrowserError('INVALID_PNG', '差异图未通过 PNG 结构/CRC 校验', { phase: 'inspectPng', reason: png.message });
@@ -17677,8 +20559,10 @@ export function apply(ctx) {
           regions: comparisonRegions,
           regionCount: Number.isInteger(diff.regionCount) ? diff.regionCount : comparisonRegions.length,
           regionsTruncated: diff.regionsTruncated === true || comparisonRegions.length > T3_EVIDENCE_REGIONS,
-          verdict,
-          reason: 'ratio',
+          verdict: gatedVerdict,
+          reason: gatedReason,
+          ratioVerdict: verdict,
+          bitmapOnly,
           mappingCompatible,
         };
         const metrics = {
@@ -17694,11 +20578,11 @@ export function apply(ctx) {
             beforeDocumentCss: item.beforeDocumentCss, afterDocumentCss: item.afterDocumentCss, area: item.area,
           })),
           metrics,
-          verdict: { status: verdict, reason: 'ratio' },
+          verdict: { status: gatedVerdict, reason: gatedReason },
           output: { productId: diffProduct.productId, sha256: delivered.sha256, file: delivered.file, delivery: delivered.delivery },
           incomplete: comparison.regionsTruncated ? ['regions-truncated'] : [],
         }));
-        runtime.noteVisionOperation('compare', verdict);
+        runtime.noteVisionOperation('compare', gatedVerdict);
         return {
           ok: true,
           before: resolvedBefore.product,
@@ -18045,7 +20929,7 @@ export function apply(ctx) {
         }
         if (mapping.visualViewportScale === null) incomplete.push('visual-viewport-scale-unknown');
         // §6 step 2: re-capture the ancestor capture rect/scale and compare decoded RGBA hashes.
-        const recapture = await runtime.capture({ scale: captureFacts.scale, region: captureFacts.region }, exec.signal);
+        const recapture = await p0(exec, 'A', 'capture', { scale: captureFacts.scale, region: captureFacts.region });
         const recapturePng = inspectPng(recapture.pngBytes, { checkCrc: true });
         if (!recapturePng.ok) {
           throw new BrowserError('INVALID_PNG', '复验截图不是结构完整的 PNG', { phase: 'inspectPng', reason: recapturePng.message });
@@ -18161,7 +21045,7 @@ export function apply(ctx) {
         // §6 step 6: one immediate after-capture of the same rect/scale (no file/base64).
         let afterProduct = null;
         try {
-          const after = await runtime.capture({ scale: captureFacts.scale, region: captureFacts.region }, exec.signal);
+          const after = await p0(exec, 'A', 'capture', { scale: captureFacts.scale, region: captureFacts.region });
           const afterPng = inspectPng(after.pngBytes, { checkCrc: true });
           if (!afterPng.ok) throw new Error('after PNG invalid');
           const afterDecoded = await t3Decode(after.pngBytes, exec.signal, t3NewBudget());
@@ -19389,7 +22273,13 @@ export function apply(ctx) {
             : null,
         }
         : null;
+      // The capability matrix below describes the *Web* surface. In another environment it would be
+      // a lie: report the environment-scoped truth (adapter.capabilities) and say so, rather than
+      // listing web.* entries that this environment does not offer (A13/A08).
+      const activeEnvironment = crossEnvironment.snapshotForAgent(exec.agent).environment;
+      const webSurface = activeEnvironment === 'web';
       return { ok: true,
+        environment: activeEnvironment,
         runtime: {
           running, browser: 'chromium', transport: running ? 'ws' : 'unavailable',
           isolation: 'single-owner-lease', attachments: typeof attachments?.saveImage === 'function',
@@ -19400,9 +22290,11 @@ export function apply(ctx) {
         },
         capabilities: [
           ...pageTools.map((name) => ({ id: 'web.t1.' + name, tool: 'browser_' + name,
-            status: busy ? 'unavailable' : 'available',
-            ...(busy ? { reason: 'BUSY: browser owned by another session' } : {}),
-            constraints: pageConstraints })),
+            // The legacy traffic snapshot is a read-only metadata read: it neither takes nor
+            // validates the single-owner lease, so another owner's BUSY never applies to it.
+            status: name === 'network' ? 'available' : (busy ? 'unavailable' : 'available'),
+            ...(name !== 'network' && busy ? { reason: 'BUSY: browser owned by another session' } : {}),
+            ...(name === 'network' ? { reason: null, constraints: [...pageConstraints, 'read-only: no page queue and no single-owner lease'] } : { constraints: pageConstraints }) })),
           ...t2Tools.map((name) => ({ id: 'web.t2.' + name, tool: 'browser_' + name,
             status: busy ? 'unavailable' : 'available',
             ...(busy ? { reason: 'BUSY: browser owned by another session' } : {}),
@@ -19418,6 +22310,19 @@ export function apply(ctx) {
             status: busy ? 'unavailable' : 'available',
             ...(busy ? { reason: 'BUSY: browser owned by another session (get 仍可只读诊断)' } : {}),
             constraints: viewportConstraints },
+          // P0-D annotations (docs/viewport-control.md): the document lives on the Host side, so
+          // neither reading nor drawing waits for another session's page lease. `draw/erase/clear`
+          // refuse with ANNOTATION_NOT_FOREGROUND unless a human is displaying that tab.
+          { id: 'web.p0d.annotations', tool: 'browser_annotation', status: 'available',
+            constraints: [
+              'One document per Runtime, shared with the human panel (read-modify-write; the panel hydrates newer Host revisions)',
+              'read never needs the foreground; draw/erase/clear need a fresh human-foreground claim ('
+                + ANNOTATION_FOREGROUND_TTL_MS + 'ms) for the target tab, else ANNOTATION_NOT_FOREGROUND with zero writes',
+              'Host-side only: no page queue, no single-owner lease, no ensure, no page DOM/CSS/lastError change',
+              'Same soft limits as the panel write surface ('
+                + ANNOTATION_LIMITS.maxShapes + ' shapes / ' + ANNOTATION_LIMITS.maxPointsPerDocument
+                + ' points / ' + ANNOTATION_LIMITS.maxDocumentBytes + ' bytes); truncation is deterministic and reported',
+            ] },
           { id: 'web.p0e.tabs', tool: 'browser_tabs', status: 'available',
             constraints: [
               'P0-E page group: primary + up to 3 child tabs per workspace (4 total; global maxPages still 8)',
@@ -19512,7 +22417,10 @@ export function apply(ctx) {
           { id: 'web.t4.dynamic-vision', status: 'available', aliasOf: 'web.t4.dynamic-behavior',
             constraints: ['legacy alias of web.t4.dynamic-behavior; not an independent tool', 'tool count unchanged'] },
           { id: 'web.t1.browser-extras', status: 'unsupported', reason: 'Not implemented' },
-        ],
+        ].filter(() => webSurface),
+        capabilitiesNote: webSurface
+          ? null
+          : 'capabilities 描述的是 Web 专属操作面；当前环境不是 web，请以 adapter.capabilities / adapter.p0 为准',
         // TOOL-P1-03 caps-level disclosure: measured beats requested, and low sampling can never
         // prove a negative. Same rule the T4 analyzers enforce in metrics.sampling/verdict.
         limitations: [
@@ -19745,19 +22653,28 @@ export function apply(ctx) {
             : null,
         },
         // P0-D annotations (docs/viewport-control.md). Declared, never probed: reading this
-        // starts nothing. This is NOT a tool — the Agent reads the document through
-        // `browser_state.annotations`, and only the authenticated scoped HTTP surface writes it, so
-        // the registered tool surface stays at 30.
+        // starts nothing. Two writers share ONE document: the human panel over the authenticated
+        // scoped route, and the Agent over `browser_annotation` (which additionally needs a fresh
+        // human-foreground claim for the target tab).
         annotations: {
           version: ANNOTATION_VERSION,
           space: ANNOTATION_SPACE,
           readTool: 'browser_state',
           readPath: 'annotations',
+          readTools: ['browser_state', 'browser_annotation'],
           writeSurface: 'authenticated-scoped-http',
           writeRoute: 'POST /plugins/ui-testing/annotations',
+          writeTool: 'browser_annotation',
+          writeActions: ['draw', 'erase', 'clear'],
+          writeModel: 'read-modify-write of one document; the panel hydrates a newer Host revision',
+          foregroundRequiredForWrite: true,
+          foregroundTtlMs: ANNOTATION_FOREGROUND_TTL_MS,
           source: 'human-panel',
           trusted: false,
-          screenshotOverlay: false,
+          screenshotOverlay: true,
+          screenshotTool: 'browser_screenshot',
+          screenshotParameter: 'includeAnnotations',
+          screenshotDefault: false,
           coordinateSpace: 'canvas-css-px',
           // d = a shape's canvas point; q = d − C, O = C − S, page-viewport p = q + O = d − S. The
           // published `view` is the panel's accepted snapshot, not a live truth: read the current S
@@ -19775,6 +22692,9 @@ export function apply(ctx) {
               shapeCount: document.shapes.length,
               stale: document.stale,
               staleReason: document.staleReason,
+              // Whether `browser_annotation` could write right now (a human displays this tab).
+              foreground: document.foreground.active,
+              foregroundAgeMs: document.foreground.ageMs,
             };
           })(),
         },
@@ -20007,10 +22927,102 @@ export function apply(ctx) {
             security: 'Not a complete network sandbox; DNS rebinding remains possible; unknown host origins and response content may contain secrets',
           },
         },
+        // Cross-environment control plane (M2/M3): the same config revision that admitted this
+        // call, the adapter capability matrix and the six-axis readiness. Reading it starts nothing.
+        adapter: await crossEnvironment.capabilitiesBlock(
+          null,
+          liveReadinessTarget(exec, runtime),
+          crossEnvironment.snapshotForAgent(exec.agent),
+        ),
       };
     },
   });
+  // Test-only fake environment tool. It is registered only when the explicit test hook is on,
+  // and `when` keeps it invisible unless the resolved environment is the fake adapter.
+  if (crossEnvironment.allowTestEnvironments) {
+    register({
+      name: 'browser_fake_probe',
+      description: 'test-only：假环境契约探针（不启动浏览器，不代表任何真实平台）。',
+      parameters: { type: 'object', properties: { payload: { type: 'object' } }, required: [] },
+      output: { schema: { type: 'object' }, render: (args, value) => text(value) },
+      async execute(args) {
+        return { ok: true, environment: 'fake', payload: (args && args.payload) || null };
+      },
+    });
+  }
+  /**
+   * Apply one authoritative config transition to the *running* resources (A12).
+   *
+   * Re-admitting the tool surface is not enough: a selection that no longer resolves to Web must
+   * also cancel queued/running work, release the connection/frame source/network collector/lease
+   * and rotate the tab selection, otherwise an old reference keeps operating a page its
+   * environment no longer owns. Only pages whose scope lost Web are touched, so an unrelated
+   * write (e.g. enabling the fake environment) never tears down a live Web page.
+   *
+   * @returns {{transitioned: Array<{scope:string, environment:string, reason:string}>}}
+   */
+  async function applyConfigTransition(notification = {}) {
+    const transitioned = [];
+    for (const entry of [...registry.entries.values()]) {
+      const scope = entry.scope || {};
+      let snapshot;
+      try {
+        snapshot = crossEnvironment.snapshotForScope({ id: scope.id, workspaceId: scope.workspaceId, cwd: scope.cwd });
+      } catch {
+        continue;
+      }
+      const webSelected = snapshot.environment === 'web'
+        && Array.isArray(snapshot.enabledEnvironments)
+        && snapshot.enabledEnvironments.includes('web');
+      if (webSelected) continue;
+      const runtime = entry.runtime;
+      const reason = snapshot.enabledEnvironments.includes(snapshot.environment)
+        ? 'environment-switched'
+        : 'environment-disabled';
+      const cancelled = typeof runtime?.abortForEnvironmentChange === 'function'
+        ? runtime.abortForEnvironmentChange(reason)
+        : { aborted: false, reason };
+      // Rotate the per-session tab selection: an old tabId/ref must not resolve through the new
+      // environment's page (identity rotation, not just cancellation).
+      for (const [key, value] of [...registry.selectedBySession.entries()]) {
+        // Match the provider-qualified key *and* the bare workspace key: an entry key is now
+        // `<provider>\u0000<baseKey>`, and a stale selection record may still reference either form.
+        // A provider switch must invalidate the old selection, so both are purged.
+        // Exact match on the complete dimensions this entry owns (its page-group key, or the
+        // group key a child belongs to). The old `key.includes(baseKey)` form matched every root
+        // sharing one workspace and deleted *other* roots' selections on an unrelated config
+        // change — the cross-root cleanup this milestone removes.
+        if (!value) continue;
+        const groupKey = entry.primaryKey || entry.key;
+        if (value.groupKey === groupKey || value.groupKey === entry.key) {
+          registry.selectedBySession.delete(key);
+        }
+      }
+      registry.bumpViews(entry.key);
+      if (typeof registry.touch === 'function') registry.touch(entry);
+      try { await runtime?.close?.(); } catch { /* teardown is best effort */ }
+      transitioned.push({ scope: entry.key, environment: snapshot.environment, reason, cancelled: cancelled.aborted });
+    }
+    if (transitioned.length > 0) {
+      log('ui-testing: config transition released ' + transitioned.length + ' web scope(s): '
+        + transitioned.map((item) => `${item.scope}:${item.reason}`).join(', '));
+    }
+    return { transitioned, revision: notification.revision ?? null };
+  }
+
+  // Initial admission + re-admission on every successful config write: schema declaration follows
+  // the same authoritative snapshot that execution uses (plan §5.1/§5.3, A08/A10), and the same
+  // notification drives resource release for scopes that no longer own the Web environment (A12).
+  syncToolVisibility();
+  crossEnvironment.onConfigChange((notification) => {
+    try { syncToolVisibility(); } catch (error) {
+      log('ui-testing: tool visibility sync failed: ' + String((error && error.message) || error));
+    }
+    applyConfigTransition(notification).catch((error) => {
+      log('ui-testing: config transition cleanup failed: ' + String((error && error.message) || error));
+    });
+  });
   // Returned for the fake-ctx acceptance harness only (Cordis ignores apply()'s return value);
   // production callers must keep using the HTTP/tool surface, not this handle.
-  return { registry };
+  return { registry, syncToolVisibility, toolDefinitions, applyConfigTransition };
 }