cdp-toolkit 1.4.0 → 1.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cdp-toolkit",
-  "version": "1.4.0",
-  "description": "A lightweight chrome-devtools-mcp alternative: a single-target MCP server + CLI that drives one tab over a direct WebSocket with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 39 tools including built-in network mocking and a cookie group. No Puppeteer, no all-target fan-out.",
+  "version": "1.7.0",
+  "description": "A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one direct WebSocket, with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 41 tools including built-in network mocking, a cookie group, tab leases, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -75,6 +75,7 @@
     "test": "bun test",
     "smoke": "bun run ./test/smoke.ts",
     "mock:smoke": "bun run ./test/mock-smoke.ts",
+    "screencast:smoke": "bun run ./test/screencast-smoke.ts",
     "mcp:smoke": "bun run ./test/mcp-smoke.ts",
     "firefox:smoke": "bun run ./test/firefox-smoke.ts",
     "lease:smoke": "bun run ./test/lease-smoke.ts"

package/src/bidi/driver.ts

@@ -269,6 +269,10 @@ const BUTTON_CODES: Record<"left" | "right" | "middle", number> = { left: 0, mid
  * supported yet" on real Firefox 153.0.3, contradicting the initial assumption that both text and
  * xpath locators were live; ElementLocator's `text` branch still resolves and correctly surfaces
  * "unsupported" rather than silently misbehaving, it is simply not offered as a capability.
+ * capture.screencast is absent because WebDriver BiDi has no streamed-frame primitive at all:
+ * the spec offers only the one-shot browsingContext.captureScreenshot, with no screencast
+ * start/stop command and no per-repaint frame event to subscribe to, so the screen-recording
+ * pair is honestly missing under Firefox rather than present and throwing.
  * network.intercept rides network.addIntercept + network.beforeRequestSent, verified working
  * (see intercept()'s comment on why urlPatterns is never populated). screenshot.fullPage uses
  * captureScreenshot's origin:"document", screenshot.element uses its clip:{type:"element"}, both verified.

package/src/capabilities.ts

@@ -1,5 +1,5 @@
 /**
- * Per-backend tool availability: filters the 36-tool registry down to what a
+ * Per-backend tool availability: filters the 41-tool registry down to what a
  * given DriverKind can actually run, per ADR-001's rule that tools/list
  * discovers gaps, not runtime "unsupported" throws. Pure and I/O-free: driver
  * construction reads a static readonly `capabilities` set, it does not dial a

package/src/cdp/driver.ts

@@ -259,12 +259,15 @@ async function elementClip(conn: CdpConnection, loc: ElementLocator): Promise<{
  * not "not armed in advance", so an honest capability set omits it rather than reading true by
  * construction. locate.text/locate.xpath both ride DOM.performSearch (see searchLocate above),
  * which is a real Chrome capability, not a line-budget artifact, so both ARE declared.
+ * capture.screencast rides Page.startScreencast / Page.screencastFrame / Page.screencastFrameAck,
+ * the streamed-repaint primitive behind start_screen_recording and stop_screen_recording.
  */
 const CDP_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
   "trace.performance", "heap.snapshot", "audit.lighthouse", "emulate.cpuThrottling",
   "emulate.mediaFeatures", "emulate.deviceMetrics", "emulate.networkConditions",
   "screenshot.fullPage", "screenshot.element", "network.intercept",
   "snapshot.accessibilityTree", "input.insertTextAtomic", "locate.text", "locate.xpath",
+  "capture.screencast",
 ]);
 /* ---------------------------------- PageDriver ---------------------------------- */
 class CdpPageDriver implements PageDriver {

package/src/driver.ts

@@ -1,5 +1,5 @@
 /**
- * ADR-001: one browser-neutral Driver interface behind the 36 tools.
+ * ADR-001: one browser-neutral Driver interface behind the 41 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`
@@ -126,6 +126,7 @@ export type Capability =
   | "trace.performance" // Chrome tracing, behind every performance_* tool
   | "heap.snapshot" // V8 heap snapshots
   | "audit.lighthouse" // shelling out to lighthouse against a debug port
+  | "capture.screencast" // streamed repaint frames (CDP Page.startScreencast); BiDi has no equivalent
   | "emulate.cpuThrottling" // CPU multiplier; absent from BiDi's emulation module
   | "emulate.mediaFeatures" // media type + features, e.g. prefers-color-scheme
   | "emulate.deviceMetrics" // past width/height: scale factor, mobile flag
@@ -151,6 +152,8 @@ export const REQUIRED_CAPABILITIES: Partial<Record<ToolName, readonly Capability
   performance_trace: ["trace.performance"],
   take_heapsnapshot: ["heap.snapshot"],
   lighthouse_audit: ["audit.lighthouse"],
+  start_screen_recording: ["capture.screencast"],
+  stop_screen_recording: ["capture.screencast"],
   mock_request: ["network.intercept"],
   list_mocks: ["network.intercept"],
   clear_mocks: ["network.intercept"],

package/src/index.ts

@@ -3,7 +3,8 @@
  *
  * Two exports:
  *   1. `TOOLS` : the registry mapping every chrome-devtools-mcp tool name
- *      (snake_case string, all 29) to its raw-CDP implementation function. The
+ *      (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
  *      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.
@@ -12,8 +13,9 @@
  * value (or throws). See CONTRACT.md for the design rules each module follows.
  */
 
-// --- the 20 tools unified with Firefox onto one Driver-based implementation ---
+// --- the 23 tools unified with Firefox onto one Driver-based implementation ---
 // (list_pages/new_page/close_page/select_page, navigate_page/wait_for, evaluate_script,
+// list_cookies/set_cookie/delete_cookies,
 // take_snapshot, click/hover/drag/fill/fill_form/type_text/press_key/upload_file,
 // take_screenshot/emulate/resize_page, handle_dialog). See shared-tools.ts's file header for
 // the byte-identical-Chrome-behavior contract this bind honors, and for the 7 tools that stay
@@ -31,6 +33,8 @@ import {
   performanceAnalyzeInsight,
   performanceTrace,
 } from "./tools/performance.ts";
+// --- screen recording (Page.startScreencast + ffmpeg) ---
+import { startScreenRecording, stopScreenRecording } from "./tools/screencast.ts";
 // --- heap ---
 import { takeHeapsnapshot } from "./tools/heap.ts";
 // --- lighthouse (the sole non-CDP tool) ---
@@ -59,8 +63,12 @@ function onCdp<A>(fn: (driver: ReturnType<typeof createCdpDriver>, args: A) => P
  * (mock_request/list_mocks/clear_mocks : a persistent per-target fake backend),
  * plus a 3-tool cookie group (list_cookies/set_cookie/delete_cookies : the
  * cookie store including httpOnly cookies, which no page script can read or
- * write).
- * 39 entries total. Listed explicitly so the mapping is auditable at a glance and
+ * write), plus a 3-tool lease group (claim_page/release_page/list_leases :
+ * 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
  * the CLI can `--list` it.
  *
  * 20 of the 29 MCP-parity tools (pages/navigation/evaluate/snapshot/interaction/
@@ -110,6 +118,9 @@ export const TOOLS = {
   performance_stop_trace: performanceStopTrace,
   performance_analyze_insight: performanceAnalyzeInsight,
   performance_trace: performanceTrace,
+  // screen recording (2) : toolkit addition, a tab-to-H.265-MP4 pair over Page.startScreencast
+  start_screen_recording: startScreenRecording,
+  stop_screen_recording: stopScreenRecording,
   // heap (1)
   take_heapsnapshot: takeHeapsnapshot,
   // lighthouse (1) : the only non-CDP tool

package/src/leases-tools.ts

@@ -1,16 +1,22 @@
 /**
  * The three lease tools, shaped like src/shared-tools.ts entries
  * ((driver, args) => Promise<result>) so ONE implementation serves Chrome and
- * Firefox, exactly as the other 20 unified tools do.
+ * Firefox, exactly as the 23 unified tools in that file do.
  */
 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,34 +37,87 @@ 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;
 }
 
 /**
- * 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.
  */
 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;
   }
   const liveIds = [...pages.map((p) => p.id), targetId];
   const { record, token } = await claimLease(backend, targetId, {
@@ -73,31 +132,93 @@ export async function claimPage(
     label: record.label,
     ttlMs: record.ttlMs,
     expiresAt: record.lastUsedAt + record.ttlMs,
+    opened,
   };
 }
 
-/** 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)",
+    );
+  }
+
+  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;
   }
-  return releaseLease(args.lease);
+
+  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 };
 }
 
 /** Enumerate active leases for diagnosis. Requires no token by design. */
 export async function listLeasesTool(
   driver: BrowserDriver,
   _args: Record<string, never> = {} as Record<string, never>,
-): Promise<{ leases: LeaseSummary[]; count: number }> {
+): Promise<{ leases: LeaseSummary[]; 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);
   // 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 leases = all.filter((l) => !(l.backend === backend && reapedIds.has(l.targetId)));
+  return { leases, count: leases.length, ...(reaped.length ? { reaped } : {}) };
 }
 
 export const LEASE_TOOLS = {

package/src/leases.ts

@@ -49,6 +49,15 @@ export interface LeaseRecord {
   createdAt: number;
   lastUsedAt: number;
   ttlMs: number;
+  /**
+   * How this lease was taken, and therefore who may use it without a token.
+   *   true  - the gate acquired it implicitly; passes for any call from `pid`.
+   *   false - claim_page or new_page{claim:true}; the token is required, even
+   *           from the owning process.
+   * Absent on records written by <=1.4.0 and read as false, so an upgrade never
+   * downgrades a held lease from token-required to pid-only.
+   */
+  auto?: boolean;
 }
 
 /** 15 minutes. Refresh-on-use means an active agent never expires, so this only
@@ -65,6 +74,43 @@ export function leaseTtlMs(): number {
   return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_LEASE_TTL_MS;
 }
 
+/**
+ * Whether THIS process is the long-lived MCP server rather than a one-shot CLI
+ * invocation. Module state, which this file's header otherwise forbids: that
+ * prohibition is about state describing OTHER processes' ownership, which must
+ * live on disk because two MCP servers drive one browser. This describes this
+ * process's own role, which no other process can observe or contend for, so a
+ * module flag is the correct scope rather than a violation of the rule.
+ */
+let longLived = false;
+
+/** Called once by mcp.ts at startup. cli.ts never calls it. The parameter
+ *  exists so a test can put the module back into CLI state. */
+export function markLongLivedProcess(value = true): void {
+  longLived = value;
+}
+
+/**
+ * Strict mode: every tool call acquires a lease for the tab it resolves, and
+ * stale agent tabs are reaped on read. Off by default, so 1.4.0 consumers are
+ * unaffected.
+ *
+ * ALWAYS FALSE UNDER THE CLI, regardless of the env var, and that is not a
+ * convenience. cli.ts already refuses claim_page because a CLI invocation is
+ * one process per call, so its lease is reclaimable by the dead-pid rule the
+ * moment the process exits, and "a lease that is reclaimable on arrival is
+ * worse than no lease". Auto-acquire would mint exactly such a lease on every
+ * call. The sharper danger is reap: those dead-pid records would read as
+ * orphaned agent tabs, so a CLI user running list_pages twice could watch the
+ * second run close the tabs the first run leased. Read per call, like
+ * leaseDir(), so a test can flip it.
+ */
+export function requireLease(): boolean {
+  if (!longLived) return false;
+  const raw = (process.env.CDP_REQUIRE_LEASE ?? "").trim().toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+
 /** The label recorded when a caller supplies none. ONE definition, because it
  *  is now written by three call sites (claim_page, new_page, and the origin
  *  ledger) and a second rule would make the same tab describe itself two
@@ -158,6 +204,9 @@ export interface ClaimOptions {
   now?: number;
   /** Live target ids from the browser, enabling the "target-gone" reclamation. */
   liveIds?: readonly string[];
+  /** Marks the lease gate-acquired. See LeaseRecord.auto. Defaults to false:
+   *  an unmarked claim is an explicit one, which is the stricter reading. */
+  auto?: boolean;
 }
 
 /** Why an existing lease may be taken over. All three are sufficient alone. */
@@ -214,6 +263,7 @@ export async function claimLease(
       createdAt: now,
       lastUsedAt: now,
       ttlMs: opts.ttlMs ?? leaseTtlMs(),
+      auto: opts.auto === true,
     };
     try {
       await writeFile(leaseFile(backend, targetId), JSON.stringify(record), { flag: "wx" });
@@ -265,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 36 tools would put the burden on every future contributor to remember
+ * all 41 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.
@@ -370,7 +420,29 @@ export async function assertLeaseOk(
   const where = describeTarget(targetId, ctx);
 
   if (token === undefined) {
-    if (!held) return; // unleased, or leased-but-reclaimable: today's behavior
+    if (!held) {
+      // STRICT MODE: acquire rather than wave through. This is the change that
+      // makes "you cannot drive a tab you do not hold" true, and it is done
+      // here rather than by refusing because refusing would force every caller
+      // to learn a claim/release protocol to do what used to just work.
+      // Marked auto:true, which is what lets a later call from this same
+      // process pass with no token. A LeaseConflictError from claimLease (two
+      // processes racing to acquire the same tab, resolved by the "wx"
+      // exclusive create) propagates: the loser is genuinely refused.
+      if (requireLease()) {
+        await claimLease(backend, targetId, { label: defaultLabel(), ttlMs: leaseTtlMs(), auto: true, now });
+      }
+      return; // unleased, or leased-but-reclaimable: today's behavior
+    }
+    // An auto lease is owned by a PROCESS, not by a token, so any call from the
+    // owning pid passes. NOT gated on requireLease(): an auto:true record can
+    // only exist because strict mode created it, and gating this too would mean
+    // turning the flag off locks this process out of leases it still holds. It
+    // cannot regress 1.4.0, where no auto:true record can exist at all.
+    if (held.auto === true && held.pid === process.pid) {
+      await touchLease(held, now);
+      return;
+    }
     throw new LeaseConflictError(
       `${where} is leased by '${held.label}' (pid ${held.pid}). Pass that lease's token as the 'lease' argument, or call release_page to free it. list_leases shows every active lease.`,
       targetId,
@@ -396,8 +468,16 @@ export async function assertLeaseOk(
   // call arrives here, select_page via activatePage included.
   if (parts.backend !== backend || parts.targetId !== targetId) {
     // The token is about a different tab, so it says nothing about this one.
-    // An unleased tab is open to everyone, token in hand or not.
-    if (!held) return;
+    // Under strict mode this tab still has to be acquired: an agent holding
+    // tab A that reaches into unleased tab C is exactly the case the feature
+    // exists to cover, and it is the COMMON case under the ambient dispatch
+    // scope, not an edge one.
+    if (!held) {
+      if (requireLease()) {
+        await claimLease(backend, targetId, { label: defaultLabel(), ttlMs: leaseTtlMs(), auto: true, now });
+      }
+      return;
+    }
     throw new LeaseConflictError(
       `the lease token you passed is for ${parts.backend} target '${parts.targetId}', not ${where}, which is leased by '${held.label}'. Resolve the tab you actually hold, or claim this one.`,
       targetId,