cdp-toolkit 1.6.0 → 1.8.0

package/src/driver.ts

@@ -1,5 +1,5 @@
 /**
- * ADR-001: one browser-neutral Driver interface behind the 41 tools.
+ * ADR-001: one browser-neutral Driver interface behind the 45 tools.
  *
  * Context. Every tool in src/tools/ is a stateless one-shot on withPage():
  * open a socket, act, always close. That is only correct because a CDP `Uid`
@@ -138,7 +138,11 @@ export type Capability =
   | "snapshot.accessibilityTree" // native a11y dump, not a DOM-walk approximation
   | "input.insertTextAtomic" // atomic value commit, not synthesized keystrokes
   | "locate.text" // find a node by visible text substring
-  | "locate.xpath"; // find a node by xpath
+  | "locate.xpath" // find a node by xpath
+  | "input.raw" // raw single mouse-event dispatch (dispatch_mouse's move/down/up primitive); Chrome only
+  | "input.html5Drag" // real HTML5 drag events (drag's mode:"html5"); Chrome only, see PageDriver.drag
+  | "browser.downloads" // capture a file download to a known path (wait_for_download); Chrome only
+  | "browser.permissions"; // grant/reset browser permissions for an origin (grant_permissions); Chrome only
 
 /**
  * Tools whose availability depends on a capability. A tool absent from this
@@ -157,6 +161,9 @@ export const REQUIRED_CAPABILITIES: Partial<Record<ToolName, readonly Capability
   mock_request: ["network.intercept"],
   list_mocks: ["network.intercept"],
   clear_mocks: ["network.intercept"],
+  dispatch_mouse: ["input.raw"],
+  wait_for_download: ["browser.downloads"],
+  grant_permissions: ["browser.permissions"],
 } as const;
 
 /* --------------------------------- errors --------------------------------- */
@@ -213,6 +220,19 @@ export interface NavigateOptions {
   url?: string;
   reload?: boolean;
   ignoreCache?: boolean;
+  /**
+   * Traverse the tab's session history instead of loading a URL: the browser Back / Forward
+   * buttons. Mutually exclusive with `url` and `reload` (the tool layer enforces that; a driver
+   * trusts its caller). Chrome: Page.getNavigationHistory + Page.navigateToHistoryEntry. Firefox:
+   * browsingContext.traverseHistory{delta:-1|+1}. Universal — both drivers implement it, so this is
+   * deliberately NOT a Capability.
+   *
+   * NO SILENT NO-OP. Asking to go back from the first history entry (or forward from the last) is a
+   * caller mistake, not a legal outcome: both drivers MUST throw an error naming the direction
+   * rather than return a success that navigated nowhere, because a no-op success reads as "you are
+   * on the previous page" and the caller acts on that.
+   */
+  history?: "back" | "forward";
   waitUntil?: "load" | "domcontentloaded";
   timeoutMs?: number;
 }
@@ -222,12 +242,93 @@ export interface NavigateResult {
   /** CDP frameId or BiDi context id. Opaque. */
   contextId: string;
   reloaded?: boolean;
+  /** Which direction a `history` traversal actually moved. Present only for a history navigation,
+   *  the same way `reloaded` is present only for a reload. */
+  traversed?: "back" | "forward";
   waitedFor: "load" | "domcontentloaded" | "committed" | "timeout";
 }
 
 export interface MouseButtonOptions {
   button?: "left" | "right" | "middle";
   clickCount?: number;
+  /** "Alt" | "Control" | "Meta" | "Shift", held for the press/release. CDP bits: Alt=1,
+   *  Control=2, Meta=4, Shift=8 (cdp/driver.ts's inputModifierBits). A non-empty array is
+   *  "unsupported" on the Firefox/BiDi driver today: see click()'s implementation note. */
+  modifiers?: readonly string[];
+}
+
+/**
+ * Where a drag ends. 1.8.0 Track P2 widened this past "an element": an absolute viewport point
+ * ({x,y}) and an offset from the source point ({dx,dy}) are both real destinations for widgets
+ * that have no droppable element to name — a range slider's track, a map canvas, a resize gutter.
+ * The three branches are discriminated structurally ("dx" in / "x" in), the same way
+ * PageDriver.scroll's anchor already discriminates an ElementLocator from a viewport point; no
+ * ElementLocator variant carries an `x` or `dx` field, so the check is exact and not a heuristic.
+ */
+export type DragDestination = ElementLocator | { x: number; y: number } | { dx: number; dy: number };
+
+export interface DragOptions {
+  /**
+   * "mouse" (default): synthetic mousePressed/mouseMoved…/mouseReleased. Fine for widgets built on
+   * raw pointer events, and it is what `drag` has always done.
+   *
+   * "html5": a REAL HTML5 drag — Input.setInterceptDrags(true), the same press/move sequence, then
+   * the intercepted DragData replayed as Input.dispatchDragEvent dragEnter/dragOver/drop at the
+   * destination.
+   *
+   * WHAT THE DIFFERENCE ACTUALLY IS (measured on Chrome 151.0.7922.109, macOS, both --headless=new
+   * and headed — NOT assumed). Synthetic mouse events DO start a real drag in modern Chrome, so
+   * mouse mode is not inert on HTML5 drop zones the way the folklore says. What mouse mode does
+   * not control is WHICH drag events the page receives: that follows the interpolated pointer
+   * path, and at the default steps:2 a source-to-zone drag delivered dragstart and drop but ZERO
+   * dragover. A drop zone written the standard way — preventDefault inside dragover, which is how
+   * the HTML spec says you mark a valid drop target — therefore refused the drop outright, while
+   * steps:1 and steps:8 on the very same page happened to work. html5 mode removes the luck: the
+   * dragEnter/dragOver/drop triple is dispatched explicitly at the destination every time.
+   *
+   * Requires Capability "input.html5Drag" — Chrome only. A driver without that capability MUST
+   * throw "unsupported"; it must never silently downgrade to mouse mode, because a caller who
+   * asked for html5 asked precisely because mouse mode was not delivering the drop.
+   */
+  mode?: "mouse" | "html5";
+  /** Interpolated mouseMoved events dispatched between the source and destination points, evenly
+   *  spaced, the last one landing exactly on the destination. Default 2 (the pre-1.8.0 hardcoded
+   *  behavior: midpoint, then destination). DnD libraries with a movement threshold or per-frame
+   *  sampling need more. The tool layer validates the range; a driver trusts its caller. */
+  steps?: number;
+}
+
+/**
+ * The `steps` evenly-spaced points between `from` (exclusive) and `to` (inclusive), for a drag's
+ * interpolated move sequence. The last point is EXACTLY `to`, emitted as `to` itself rather than
+ * computed, so float error can never leave the pointer a fraction of a pixel short of the
+ * destination element. steps:1 is a single jump to the destination; steps:2 is
+ * midpoint-then-destination, the pre-1.8.0 hardcoded behavior.
+ *
+ * Lives here, in the backend-neutral module, because BOTH drivers need the identical geometry:
+ * the CDP driver turns each point into an Input.dispatchMouseEvent{mouseMoved} and the BiDi driver
+ * into a performActions pointerMove, but "where the pointer goes" must not differ by backend.
+ * Callers pass an already-validated integer >= 1 (the tool layer validates; a driver trusts it).
+ */
+export function interpolatePoints(
+  from: { x: number; y: number },
+  to: { x: number; y: number },
+  steps: number,
+): Array<{ x: number; y: number }> {
+  const out: Array<{ x: number; y: number }> = [];
+  for (let i = 1; i < steps; i++) {
+    out.push({ x: from.x + ((to.x - from.x) * i) / steps, y: from.y + ((to.y - from.y) * i) / steps });
+  }
+  out.push({ x: to.x, y: to.y });
+  return out;
+}
+
+export interface ScrollOptions {
+  /** Positive scrolls DOWN, positive scrolls RIGHT: wheel-event convention. The tool layer
+   *  (shared-tools.ts) requires at least one of deltaX/deltaY; a driver trusts its caller and
+   *  does not re-validate. */
+  deltaX?: number;
+  deltaY?: number;
 }
 
 export interface KeyPress {
@@ -414,6 +515,54 @@ export interface BrowserDriver {
   /** Acquire a page handle. The caller MUST release() it. Prefer withDriver. */
   page(selector: TargetSelector): Promise<PageDriver>;
 
+  /**
+   * Install the activity beacon into a target and, where the backend can, into
+   * every document it navigates to afterwards. Resolves true when the beacon is
+   * in place. See src/activity.ts.
+   *
+   * OPTIONAL, per ADR-001's "absent rather than present-and-throwing" rule, but
+   * NOT a `Capability`: that union gates whole tools out of tools/list, and no
+   * tool is gated here. The beacon is an additive FIELD on claim_page and
+   * list_leases, both of which work unchanged without it, so the honest
+   * expression of a backend that cannot do this is an absent method producing an
+   * absent field — not a missing tool and not a throw.
+   */
+  installActivityBeacon?(targetId: string): Promise<boolean>;
+
+  /**
+   * Read the beacon's timestamp for a target, or null when the target has no
+   * beacon. WITHOUT THE LEASE GATE, which is required rather than convenient:
+   * claim_page{target} must read this BEFORE claiming, and under
+   * CDP_REQUIRE_LEASE a gated read would auto-acquire the lease and then collide
+   * with the explicit claim behind it (the same reason pickPage is gate-free;
+   * see leases-tools.ts's header).
+   *
+   * This is not a general gate bypass and must never become one: it returns one
+   * number and takes no expression, so it cannot be made to read or change
+   * anything else about the page.
+   */
+  readActivityBeacon?(targetId: string): Promise<number | null>;
+
+  /**
+   * Bounded liveness probe behind list_pages{probe:true}: run ONE Runtime.evaluate
+   * (or backend equivalent) capped at `timeoutMs`, and report whether it
+   * answered in time plus whatever the activity beacon said in that same round
+   * trip. See src/activity.ts's RENDERER_PROBE_EXPRESSION for exactly what is
+   * evaluated and why.
+   *
+   * MUST NEVER REJECT. A timeout, a thrown page-side exception, a dead
+   * connection, or a target that no longer exists are all
+   * `{responsive:false, beaconTs:null}` — indistinguishable from each other and
+   * from a genuinely wedged renderer, which is the honest answer: none of them
+   * let the caller drive that tab any faster than this call already told it.
+   *
+   * OPTIONAL and NOT a `Capability`, for the same reason installActivityBeacon
+   * and readActivityBeacon are not: no whole tool is gated, only an additive
+   * field on list_pages, so the honest expression of a backend that cannot do
+   * this is an absent method producing an absent field.
+   */
+  probeRenderer?(targetId: string, timeoutMs?: number): Promise<{ responsive: boolean; beaconTs: number | null }>;
+
   /** Tear down the transport: process exit (CLI) or shutdown (MCP server).
    *  Idempotent. MUST NOT be called by a tool. */
   dispose(): Promise<void>;
@@ -446,7 +595,16 @@ export interface PageDriver {
   /* input */
   click(loc: ElementLocator, opts?: MouseButtonOptions): Promise<{ x: number; y: number }>;
   hover(loc: ElementLocator): Promise<{ x: number; y: number }>;
-  drag(from: ElementLocator, to: ElementLocator): Promise<{ from: { x: number; y: number }; to: { x: number; y: number } }>;
+  /** Press at `from`, move to `to`, release. `to` is an element, an absolute viewport point, or an
+   *  offset from the resolved source point (DragDestination). opts.mode picks synthetic-mouse vs.
+   *  real HTML5 drag events; opts.steps sets how many interpolated moves are dispatched. */
+  drag(from: ElementLocator, to: DragDestination, opts?: DragOptions): Promise<{ from: { x: number; y: number }; to: { x: number; y: number } }>;
+  /** Dispatch a wheel/scroll event at an anchor point. `anchor` is an ElementLocator (scrolled
+   *  into view first, exactly like click/hover), an absolute viewport point, or `undefined` for
+   *  the viewport center. Chrome: Input.dispatchMouseEvent{type:"mouseWheel"}. Firefox: BiDi's
+   *  "wheel" input source via input.performActions. Universal: both drivers must implement it
+   *  (absent from driver.ts's REQUIRED_CAPABILITIES, unlike dispatch_mouse). */
+  scroll(anchor: ElementLocator | { x: number; y: number } | undefined, opts: ScrollOptions): Promise<{ x: number; y: number }>;
   /** Overwrite an element's value. One atomic commit under
    *  "input.insertTextAtomic", else synthesized keystrokes, so per-key handlers
    *  on the page WILL fire. Callers must not depend on either behavior. */

package/src/index.ts

@@ -4,7 +4,7 @@
  * Two exports:
  *   1. `TOOLS` : the registry mapping every chrome-devtools-mcp tool name
  *      (snake_case string, all 29 of them) plus the toolkit's own superset
- *      tools, 41 entries in all, to its raw-CDP implementation function. The
+ *      tools, 45 entries in all, to its raw-CDP implementation function. The
  *      CLI and any embedder dispatch through this single table.
  *   2. The client primitives, re-exported so consumers can build their own
  *      flows on the same connection/timeout machinery the tools use.
@@ -41,6 +41,11 @@ import { takeHeapsnapshot } from "./tools/heap.ts";
 import { lighthouseAudit } from "./tools/lighthouse.ts";
 // --- network mocking (Fetch domain) : toolkit addition beyond the 29 parity tools ---
 import { mockRequest, listMocks, clearMocks } from "./tools/network_mock.ts";
+// --- raw mouse dispatch (Input.dispatchMouseEvent, one event per call) : chrome-only, capability "input.raw" ---
+import { dispatchMouse } from "./tools/dispatch-mouse.ts";
+// --- downloads + permissions (browser-endpoint state on a standing connection) : chrome-only, 1.8.0 Track P3 ---
+import { waitForDownload } from "./tools/downloads.ts";
+import { grantPermissions } from "./tools/permissions.ts";
 
 /** A toolkit tool: a single typed-args function returning JSON-serializable data. */
 export type ToolFn = (args: never) => Promise<unknown>;
@@ -67,8 +72,16 @@ function onCdp<A>(fn: (driver: ReturnType<typeof createCdpDriver>, args: A) => P
  * opt-in tab ownership so many agents can share one browser), plus a 2-tool
  * screen-recording pair (start_screen_recording/stop_screen_recording : a tab
  * captured to an H.265 MP4 with per-frame durations, so a variable-rate
- * repaint stream plays back at wallclock speed).
- * 29 + 1 + 3 + 3 + 3 + 2 = 41 entries total. Listed explicitly so the mapping is auditable at a glance and
+ * repaint stream plays back at wallclock speed), plus a 2-tool input-parity
+ * addition (1.8.0 Track P1: `scroll`, a wheel-event dispatch at an anchor
+ * point sharing click/hover's element-locator and lease-gate contract; and
+ * `dispatch_mouse`, the raw move/down/up mouse-event primitive composable
+ * into anything a physical mouse can do, chrome-only per capability "input.raw"), plus a 2-tool
+ * browser-state addition (1.8.0 Track P3: `wait_for_download`, which captures a file download to a
+ * named path, and `grant_permissions`, which answers permission prompts for an origin; both
+ * chrome-only and both driven from a standing browser-endpoint connection, see
+ * tools/browser-session.ts).
+ * 29 + 1 + 3 + 3 + 3 + 2 + 2 + 2 = 45 entries total. Listed explicitly so the mapping is auditable at a glance and
  * the CLI can `--list` it.
  *
  * 20 of the 29 MCP-parity tools (pages/navigation/evaluate/snapshot/interaction/
@@ -93,10 +106,11 @@ export const TOOLS = {
   delete_cookies: onCdp(SHARED_TOOLS.delete_cookies),
   // snapshot (1)
   take_snapshot: onCdp(SHARED_TOOLS.take_snapshot),
-  // interaction (8)
+  // interaction (9) : scroll is 1.8.0 Track P1, a toolkit addition beyond the 29 parity tools
   click: onCdp(SHARED_TOOLS.click),
   hover: onCdp(SHARED_TOOLS.hover),
   drag: onCdp(SHARED_TOOLS.drag),
+  scroll: onCdp(SHARED_TOOLS.scroll),
   fill: onCdp(SHARED_TOOLS.fill),
   fill_form: onCdp(SHARED_TOOLS.fill_form),
   type_text: onCdp(SHARED_TOOLS.type_text),
@@ -129,6 +143,14 @@ export const TOOLS = {
   mock_request: mockRequest,
   list_mocks: listMocks,
   clear_mocks: clearMocks,
+  // raw mouse dispatch (1) : 1.8.0 Track P1 toolkit addition, chrome-only (capability "input.raw")
+  dispatch_mouse: dispatchMouse,
+  // downloads + permissions (2) : 1.8.0 Track P3 toolkit additions, chrome-only (capabilities
+  // "browser.downloads" / "browser.permissions"). Both drive browser-endpoint state that Chrome
+  // reverts when the issuing client disconnects, so both run on tools/browser-session.ts's standing
+  // connection rather than a per-call socket : see that module's header for the measurements.
+  wait_for_download: waitForDownload,
+  grant_permissions: grantPermissions,
   // tab leases (3) : opt-in ownership so many agents can share one browser
   claim_page: onCdp(LEASE_TOOLS.claim_page),
   release_page: onCdp(LEASE_TOOLS.release_page),

package/src/leases-tools.ts

@@ -3,14 +3,21 @@
  * ((driver, args) => Promise<result>) so ONE implementation serves Chrome and
  * Firefox, exactly as the 23 unified tools in that file do.
  */
+import { beaconSupported, contentionWarning, installBeacon, readHumanActiveMs } from "./activity.ts";
 import type { BrowserDriver } from "./driver.ts";
-import { newTrackedPage } from "./origins.ts";
+import { newTrackedPage, readOrigin } from "./origins.ts";
+import { reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
+import { pickPage, resolvePage } from "./shared-tools.ts";
+import type { TargetSelector } from "./types.ts";
 import {
   claimLease,
   defaultLabel,
   leaseTtlMs,
   listLeases,
   releaseLease,
+  releaseLeaseFor,
+  requireLease,
+  tokenParts,
   type LeaseBackend,
   type LeaseSummary,
   type LeaseToken,
@@ -31,41 +38,142 @@ export interface ClaimPageResult {
   label: string;
   ttlMs: number;
   expiresAt: number;
+  /** true when this call CREATED the tab, false when it claimed one that was
+   *  already open. The same distinction the creation ledger records, surfaced
+   *  in the answer so a caller knows without a second lookup whether
+   *  release_page will close the tab. */
+  opened: boolean;
+  /**
+   * Milliseconds since the last input this server cannot account for — i.e.
+   * since a HUMAN last touched this tab. See src/activity.ts for how that
+   * attribution is made and what it cannot prove.
+   *
+   * `null` means NO DATA, and never "no human": the tab carries no beacon (the
+   * usual case the first time anyone claims a person's tab), or every timestamp
+   * on it is explained by this server's own dispatches. ABSENT ENTIRELY on a
+   * backend with no beacon support, so a caller can tell "this browser cannot
+   * answer" from "this browser answered, and the answer is no data".
+   */
+  humanActiveMs?: number | null;
+  /**
+   * Present only on a TAKEOVER of a tab a human used within the last 30s. A
+   * warning, never a refusal — the claim in this same result already succeeded.
+   * See contentionWarning in src/activity.ts for why refusing would be wrong.
+   */
+  contention?: string;
 }
 
 /**
- * Claim a tab. With no targetId, opens a fresh tab first (optionally at `url`)
- * and claims that, so "give me my own tab" is one call. With a targetId, claims
- * an already-open tab.
+ * Claim a tab, in one of two modes.
+ *
+ * OPEN: with neither `target` nor `targetId`, opens a fresh tab (optionally at
+ * `url`) and claims that, so "give me my own tab" is one call.
+ *
+ * TAKE OVER: with `target`, claims a tab that is ALREADY OPEN — the first-class
+ * path for "work in the tab I have open", which previously had none, because
+ * `targetId` demands an exact id a human never has to hand and no id at all
+ * meant a brand new tab. `target` takes the toolkit's whole selector grammar
+ * (active | index:N | url:<substr> | title:<substr> | <targetId>).
+ *
+ * `targetId` is unchanged and still accepted; `target` is the same thing with a
+ * grammar, so exactly one of the two may be given.
+ *
+ * WHY RESOLUTION IS GATE-FREE HERE. `target` resolves through pickPage, NOT
+ * resolvePage. resolvePage runs assertLeaseOk, which under CDP_REQUIRE_LEASE
+ * auto-acquires a lease on an unleased tab: routing a claim through it would
+ * claim the tab twice and collide with itself. The protection is not lost, only
+ * moved — claimLease below still refuses a tab a live process holds.
+ *
+ * TAKEOVER IS OF UNLEASED TABS ONLY. There is deliberately no force/steal
+ * option: a tab another live agent holds stays refused with the same conflict
+ * error as before. The tab this feature exists to take over is a human's, and a
+ * human's tab carries no lease.
+ *
+ * RESOLUTION NEVER CREATES A TAB. With `target` given, the open branch is
+ * unreachable: an unmatched selector is an error, never a silently substituted
+ * new tab, because "the tab I asked for is not there" and "here is an empty one
+ * instead" are answers a caller must be able to tell apart.
+ *
+ * THE ACTIVITY BEACON IS READ BEFORE THE CLAIM AND INSTALLED AFTER IT, and the
+ * order is not arbitrary in either half.
+ *
+ * Read first, because the read has to be GATE-FREE for exactly the reason the
+ * resolution above is: under CDP_REQUIRE_LEASE, anything that touches the tab
+ * through the lease gate auto-acquires a lease on it, and a claim that ran after
+ * that would collide with the lease taken on its own behalf. The driver members
+ * behind readHumanActiveMs bypass the gate and can do nothing but return one
+ * number (see driver.ts).
+ *
+ * Install after, because installing is a WRITE into the page, and this is the
+ * first moment we are entitled to make one: the claim has succeeded, so the tab
+ * is ours. It is also the only ordering that keeps the read honest, since
+ * installing first cannot invent a timestamp but re-arming a beacon on a tab
+ * whose claim then FAILED would leave our script running in somebody else's tab
+ * for nothing.
+ *
+ * A CLAIM IS NEVER REFUSED ON HUMAN ACTIVITY. Taking over a person's tab is the
+ * feature; a caller that asked for this tab gets this tab. Contention is
+ * reported in the result and the caller decides. See contentionWarning.
  */
 export async function claimPage(
   driver: BrowserDriver,
-  args: { targetId?: string; url?: string; label?: string; ttlMs?: number } = {},
+  args: { target?: TargetSelector; targetId?: string; url?: string; label?: string; ttlMs?: number } = {},
 ): Promise<ClaimPageResult> {
+  const hasTarget = typeof args.target === "string" && args.target.length > 0;
+  const hasTargetId = typeof args.targetId === "string" && args.targetId.length > 0;
+  if (hasTarget && hasTargetId) {
+    throw new LeaseToolError(
+      "claim_page takes at most one of 'target' (any selector: active | index:N | url:<substr> | title:<substr> | <targetId>) or 'targetId' (an exact target id, kept for back-compat). Pass 'target' alone to claim an open tab, or neither to open a fresh one.",
+    );
+  }
   const backend = backendOf(driver);
   const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
   const pages = await driver.listPages();
-  let targetId = args.targetId;
-  let url = args.url ?? "about:blank";
-  if (targetId === undefined || targetId === "") {
+  let targetId: string;
+  let url: string;
+  let opened: boolean;
+  if (hasTarget) {
+    // Gate-free on purpose: see the header. No tab is created on this path,
+    // including when nothing matches.
+    const hit = await pickPage(driver, pages, args.target).catch((err: unknown) => {
+      throw new LeaseToolError(
+        `claim_page: no open tab matches target '${args.target}' (${(err as Error).message}). No tab was opened: claim_page never creates one when 'target' is given.`,
+      );
+    });
+    targetId = hit.id;
+    url = hit.url;
+    opened = false;
+  } else if (hasTargetId) {
+    const existing = pages.find((p) => p.id === args.targetId);
+    if (!existing) throw new LeaseToolError(`claim_page: no page target with id '${args.targetId}'`);
+    targetId = existing.id;
+    url = existing.url;
+    opened = false;
+  } else {
     // Creation ledger, not the lease: this record survives release_page and
     // expiry, so the tab stays attributable to `label` after the lease is gone.
-    // Claiming an EXISTING tab (the else branch) records nothing, because this
-    // toolkit did not create it and provenance is not ownership.
+    // Claiming an EXISTING tab (the branches above) records nothing, because
+    // this toolkit did not create it and provenance is not ownership.
     const page = await newTrackedPage(driver, backend, { url: args.url, label });
     targetId = page.id;
     url = page.url;
-  } else {
-    const existing = pages.find((p) => p.id === targetId);
-    if (!existing) throw new LeaseToolError(`claim_page: no page target with id '${targetId}'`);
-    url = existing.url;
+    opened = true;
   }
+  // Gate-free, before the claim, and only for a takeover: a tab this call is
+  // about to CREATE cannot have a human in it, so asking would be theatre.
+  const humanMs = opened ? null : await readHumanActiveMs(driver, backend, targetId);
   const liveIds = [...pages.map((p) => p.id), targetId];
   const { record, token } = await claimLease(backend, targetId, {
     label,
     ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
     liveIds,
   });
+  // Best effort by construction (installBeacon never throws): a claim that
+  // succeeded must not be reported as a failure because a diagnostic script
+  // could not be injected. The cost is a tab that reports humanActiveMs null
+  // forever, which reads the same as a tab nobody has touched.
+  await installBeacon(driver, targetId);
+  const contention = contentionWarning(humanMs, { takeover: !opened });
   return {
     lease: token,
     targetId,
@@ -73,31 +181,165 @@ export async function claimPage(
     label: record.label,
     ttlMs: record.ttlMs,
     expiresAt: record.lastUsedAt + record.ttlMs,
+    opened,
+    // Absent, not null, when the backend has no beacon at all: "cannot answer"
+    // and "answered, no data" are different facts (ADR-001's absent-over-
+    // throwing rule applied to a field rather than to a whole tool).
+    ...(beaconSupported(driver) ? { humanActiveMs: humanMs } : {}),
+    ...(contention !== undefined ? { contention } : {}),
   };
 }
 
-/** Release a held lease. Idempotent: an already-released or reclaimed lease
- *  reports released:false rather than throwing. */
+/**
+ * Give a lease back, and close the tab if this toolkit opened it.
+ *
+ * TWO WAYS IN, because an auto-acquired lease never handed the caller a token:
+ * `lease` is the 1.4.0 path, `target` resolves through shared-tools' resolvePage
+ * and is authorized by the same gate as any other call. Exactly one is required;
+ * accepting both would leave it ambiguous which one authorizes the close.
+ *
+ * WHY PROVENANCE DECIDES THE CLOSE. A lease says who is driving a tab, never who
+ * opened it. Closing on release is right for a tab this toolkit opened for an
+ * agent and wrong for a tab the human already had open and an agent merely
+ * claimed. origins.ts records exactly that distinction and its records outlive
+ * the lease, so the answer is still there at release time.
+ *
+ * A RELEASE THAT DID NOT HAPPEN NEVER CLOSES. An already-released or reclaimed
+ * lease reports released:false, and the tab may well belong to another agent by
+ * then; closing it would destroy a tab someone else is driving. This is the one
+ * rule in this function that is a safety property rather than a convenience.
+ */
 export async function releasePage(
-  _driver: BrowserDriver,
-  args: { lease?: LeaseToken },
-): Promise<{ released: boolean }> {
-  if (typeof args.lease !== "string" || !args.lease.length) {
-    throw new LeaseToolError("release_page requires the 'lease' token returned by claim_page");
+  driver: BrowserDriver,
+  args: { lease?: LeaseToken; target?: TargetSelector; close?: boolean } = {},
+): Promise<{ released: boolean; closed: boolean; targetId?: string }> {
+  const hasLease = typeof args.lease === "string" && args.lease.length > 0;
+  const hasTarget = typeof args.target === "string" && args.target.length > 0;
+  if (hasLease === hasTarget) {
+    throw new LeaseToolError(
+      "release_page takes exactly one of 'lease' (the token claim_page returned) or 'target' (a selector for a tab this process holds)",
+    );
   }
-  return releaseLease(args.lease);
+
+  const backend = backendOf(driver);
+  let targetId: string;
+  let released: boolean;
+
+  if (hasLease) {
+    const parts = tokenParts(args.lease as LeaseToken);
+    // A malformed token names no tab, so there is nothing to release and
+    // nothing to close. Idempotent rather than throwing, as in 1.4.0.
+    if (!parts) return { released: false, closed: false };
+    targetId = parts.targetId;
+    released = (await releaseLease(args.lease as LeaseToken)).released;
+  } else {
+    // resolvePage runs assertLeaseOk, which IS the authorization: a tab held by
+    // another process throws here, and under strict mode an unleased tab is
+    // acquired first, so the caller holds it by the time we release it.
+    const page = await resolvePage(driver, args.target);
+    targetId = page.id;
+    released = (await releaseLeaseFor(backend, targetId)).released;
+  }
+
+  if (!released) return { released: false, closed: false, ...(hasTarget ? { targetId } : {}) };
+
+  const shouldClose =
+    args.close === false ? false
+    : args.close === true ? true
+    : (await readOrigin(backend, targetId)) !== undefined;
+  if (!shouldClose) return { released: true, closed: false, targetId };
+
+  // The release already succeeded and is not undone by a failed close: the
+  // caller has genuinely given the lease back either way, and throwing here
+  // would report a release that did happen as an error.
+  const res = await driver.closePage(targetId).catch(() => ({ success: false }));
+  return { released: true, closed: res.success === true, targetId };
+}
+
+/**
+ * One list_leases row: everything the lease store knows, plus what the browser
+ * can add.
+ *
+ * `humanActiveMs` lives HERE and not on LeaseSummary because leases.ts is
+ * deliberately free of any CDP or BiDi import ("it takes browser-derived input
+ * as data", see its staleReason) and answering this needs a live driver. Keeping
+ * the annotation in the tool layer is what preserves that, and it is the same
+ * split shared-tools.ts uses for ListedPage's provenance fields.
+ *
+ * `idleMs` and `expiresAt` need no driver at all — they are arithmetic on a
+ * record leases.ts already has in hand — but they live here for the same
+ * reason: this is the DISPLAY layer, and the rule "compute presentation
+ * fields where they are shown, not in the store that owns the data" should
+ * not have two different homes depending on whether a given field happens to
+ * need a browser.
+ */
+export interface LeaseRow extends LeaseSummary {
+  /** Ms since a human last touched this tab (src/activity.ts). ABSENT — never
+   *  null — when the tab has no beacon, when every timestamp on it was this
+   *  server's own, when the row belongs to the other backend, or when the read
+   *  failed. A diagnosis tool must not fail because one page would not answer. */
+  humanActiveMs?: number;
+  /** now - lastUsedAt, computed fresh on every call and never stored: storing
+   *  it would mean every row goes stale the instant it is written. ABSENT on
+   *  an `unreadable` row, whose lastUsedAt is a zeroed placeholder (see
+   *  LeaseSummary) that would otherwise print as "idle since the epoch". */
+  idleMs?: number;
+  /** lastUsedAt + ttlMs — the same value claim_page already returns under this
+   *  name. Same omission rule as idleMs. */
+  expiresAt?: number;
 }
 
-/** Enumerate active leases for diagnosis. Requires no token by design. */
+/**
+ * Enumerate active leases for diagnosis. Requires no token by design.
+ *
+ * The beacon annotation is per-row, best effort, and NEVER fatal: an evaluate
+ * that throws, a tab that closed mid-listing, or a page with no beacon all leave
+ * the field off that row and change nothing else. list_leases is what an
+ * operator runs when tabs already look wrong, so it failing on a wrong-looking
+ * tab would be exactly backwards.
+ *
+ * Only rows of THIS driver's backend are annotated, mirroring the liveBackend
+ * scoping just below: a Chrome driver cannot read a Firefox context, and asking
+ * it to would either error or, worse, resolve some unrelated id.
+ */
 export async function listLeasesTool(
   driver: BrowserDriver,
   _args: Record<string, never> = {} as Record<string, never>,
-): Promise<{ leases: LeaseSummary[]; count: number }> {
-  const liveIds = (await driver.listPages()).map((p) => p.id);
+): Promise<{ leases: LeaseRow[]; count: number; reaped?: ReapedTab[] }> {
+  const backend = backendOf(driver);
+  // Same reap as list_pages, and for the same reason: this is the other tool an
+  // operator runs when tabs look wrong, so it must not report a lease it is
+  // about to delete. Strict mode only.
+  const reaped = requireLease() ? await reapStaleAgentTabs(driver, backend) : [];
+  const reapedIds = new Set(reaped.map((r) => r.targetId));
+  const livePages = await driver.listPages();
+  const liveIds = livePages.map((p) => p.id);
   // liveBackend scopes the target-gone test to the browser these ids came from,
   // so leases held on the OTHER backend are not mislabeled as reclaimable.
-  const leases = await listLeases({ liveIds, liveBackend: backendOf(driver) });
-  return { leases, count: leases.length };
+  const all = await listLeases({ liveIds, liveBackend: backend });
+  const kept = all.filter((l) => !(l.backend === backend && reapedIds.has(l.targetId)));
+  const liveSet = new Set(liveIds);
+  const now = Date.now();
+  const leases: LeaseRow[] = [];
+  for (const row of kept) {
+    // idleMs/expiresAt are pure arithmetic on the record itself, so they apply
+    // to BOTH backends and to leases on tabs that are not currently open — the
+    // browser has nothing to do with this computation. An unreadable row is
+    // the one exception: its lastUsedAt/ttlMs are zeroed placeholders (see
+    // LeaseSummary), and computing off zeros would print a meaningless number
+    // rather than the honest "we cannot say" an unreadable row already means.
+    const computed: LeaseRow = row.unreadable !== undefined ? row : { ...row, idleMs: now - row.lastUsedAt, expiresAt: row.lastUsedAt + row.ttlMs };
+    // A row this driver cannot speak to at all: other backend, unreadable
+    // record (its targetId came from a FILENAME, not from the browser), or a
+    // tab that is simply not open any more.
+    if (row.backend !== backend || row.unreadable !== undefined || !liveSet.has(row.targetId)) {
+      leases.push(computed);
+      continue;
+    }
+    const humanMs = await readHumanActiveMs(driver, backend, row.targetId, now).catch(() => null);
+    leases.push(humanMs === null ? computed : { ...computed, humanActiveMs: humanMs });
+  }
+  return { leases, count: leases.length, ...(reaped.length ? { reaped } : {}) };
 }
 
 export const LEASE_TOOLS = {