cdp-toolkit 1.7.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,6 +3,7 @@
  * ((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, readOrigin } from "./origins.ts";
 import { reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
@@ -42,6 +43,24 @@ export interface ClaimPageResult {
    *  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;
 }
 
 /**
@@ -74,6 +93,27 @@ export interface ClaimPageResult {
  * 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,
@@ -119,12 +159,21 @@ export async function claimPage(
     url = page.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,
@@ -133,6 +182,11 @@ export async function claimPage(
     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 } : {}),
   };
 }
 
@@ -202,22 +256,89 @@ export async function releasePage(
   return { released: true, closed: res.success === true, targetId };
 }
 
-/** Enumerate active leases for diagnosis. Requires no token by design. */
+/**
+ * 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.
+ *
+ * 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; reaped?: ReapedTab[] }> {
+): 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 liveIds = (await driver.listPages()).map((p) => p.id);
+  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 all = await listLeases({ liveIds, liveBackend: backend });
-  const leases = all.filter((l) => !(l.backend === backend && reapedIds.has(l.targetId)));
+  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 } : {}) };
 }
 

package/src/leases.ts

@@ -315,7 +315,7 @@ export async function releaseLeaseFor(backend: LeaseBackend, targetId: string):
  * This exists so enforcement can stay at ONE point per resolution path while
  * the token still reaches it. The token arrives as a key on a tool's args
  * object, many frames above resolveTarget, and threading a parameter through
- * all 41 tools would put the burden on every future contributor to remember
+ * all 45 tools would put the burden on every future contributor to remember
  * the check exists: one missed tool would silently defeat the feature for that
  * tool. mcp.ts and cli.ts open this scope once per dispatch instead, so a tool
  * added tomorrow is covered with no action from whoever writes it.