cdp-toolkit 1.1.0 → 1.2.0

package/dist/mcp.js

@@ -1,5 +1,257 @@
 #!/usr/bin/env node
 
+// src/leases.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+var DEFAULT_LEASE_TTL_MS = 900000;
+function leaseDir() {
+  return process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+}
+function leaseTtlMs() {
+  const raw = Number(process.env.CDP_LEASE_TTL_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_LEASE_TTL_MS;
+}
+function safeId(id) {
+  return id.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+function leaseFile(backend, targetId) {
+  return join(leaseDir(), `lease-${backend}-${safeId(targetId)}.json`);
+}
+function mintToken(backend, targetId, nonce) {
+  return `${backend}:${targetId}:${nonce}`;
+}
+function tokenParts(token) {
+  if (typeof token !== "string")
+    return;
+  const first = token.indexOf(":");
+  const last = token.lastIndexOf(":");
+  if (first <= 0 || last <= first)
+    return;
+  const backend = token.slice(0, first);
+  if (backend !== "chrome" && backend !== "firefox")
+    return;
+  const targetId = token.slice(first + 1, last);
+  const nonce = token.slice(last + 1);
+  if (!targetId.length || !/^[0-9a-f]{24}$/.test(nonce))
+    return;
+  return { backend, targetId, nonce };
+}
+
+class LeaseConflictError extends Error {
+  targetId;
+  holder;
+  constructor(message, targetId, holder) {
+    super(message);
+    this.targetId = targetId;
+    this.holder = holder;
+    this.name = "LeaseConflictError";
+  }
+}
+async function readLease(backend, targetId) {
+  let raw;
+  try {
+    raw = await readFile(leaseFile(backend, targetId), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return;
+    throw err;
+  }
+  try {
+    const rec = JSON.parse(raw);
+    if (typeof rec?.nonce === "string" && typeof rec?.pid === "number")
+      return rec;
+  } catch {}
+  return;
+}
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0)
+    return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function staleReason(rec, opts) {
+  if (!isPidAlive(rec.pid))
+    return "dead-pid";
+  if (opts.now - rec.lastUsedAt > rec.ttlMs)
+    return "expired";
+  if (opts.liveIds && !opts.liveIds.includes(rec.targetId))
+    return "target-gone";
+  return false;
+}
+async function claimLease(backend, targetId, opts) {
+  const now = opts.now ?? Date.now();
+  await mkdir(leaseDir(), { recursive: true });
+  for (let attempt = 0;attempt < 3; attempt++) {
+    const record = {
+      backend,
+      targetId,
+      nonce: randomBytes(12).toString("hex"),
+      pid: process.pid,
+      label: opts.label,
+      createdAt: now,
+      lastUsedAt: now,
+      ttlMs: opts.ttlMs ?? leaseTtlMs()
+    };
+    try {
+      await writeFile(leaseFile(backend, targetId), JSON.stringify(record), { flag: "wx" });
+      return { token: mintToken(backend, targetId, record.nonce), record };
+    } catch (err) {
+      if (err.code !== "EEXIST")
+        throw err;
+    }
+    const existing = await readLease(backend, targetId);
+    if (!existing)
+      continue;
+    const stale = staleReason(existing, { now, liveIds: opts.liveIds });
+    if (!stale) {
+      throw new LeaseConflictError(`target '${targetId}' is already leased by '${existing.label}' (pid ${existing.pid}); call release_page with that lease's token, or list_leases to inspect it`, targetId, existing.label);
+    }
+    await unlink(leaseFile(backend, targetId)).catch(() => {
+      return;
+    });
+  }
+  throw new LeaseConflictError(`target '${targetId}' could not be claimed after 3 attempts: another process is claiming and releasing it concurrently`, targetId);
+}
+async function releaseLease(token) {
+  const parts = tokenParts(token);
+  if (!parts)
+    return { released: false };
+  const rec = await readLease(parts.backend, parts.targetId);
+  if (!rec || rec.nonce !== parts.nonce)
+    return { released: false };
+  await unlink(leaseFile(parts.backend, parts.targetId)).catch(() => {
+    return;
+  });
+  return { released: true };
+}
+async function releaseLeaseFor(backend, targetId) {
+  if (!await readLease(backend, targetId))
+    return { released: false };
+  await unlink(leaseFile(backend, targetId)).catch(() => {
+    return;
+  });
+  return { released: true };
+}
+var leaseScope = new AsyncLocalStorage;
+function withLeaseScope(lease, fn) {
+  return leaseScope.run(lease, fn);
+}
+function currentLease() {
+  return leaseScope.getStore();
+}
+function leaseFromArgs(args) {
+  if (!args || typeof args !== "object")
+    return;
+  const lease = args.lease;
+  return typeof lease === "string" && lease.length > 0 ? lease : undefined;
+}
+async function touchLease(rec, now = Date.now()) {
+  const current = await readLease(rec.backend, rec.targetId).catch(() => {
+    return;
+  });
+  if (!current || current.nonce !== rec.nonce)
+    return;
+  await writeFile(leaseFile(current.backend, current.targetId), JSON.stringify({ ...current, lastUsedAt: now }), "utf8").catch(() => {
+    return;
+  });
+}
+function describeTarget(targetId, ctx) {
+  const url = ctx.url ? ` (url ${ctx.url})` : ctx.title ? ` (title ${JSON.stringify(ctx.title)})` : "";
+  return `target '${targetId}'${url}`;
+}
+async function assertLeaseOk(backend, targetId, ctx = {}) {
+  const token = ctx.lease ?? currentLease();
+  const now = ctx.now ?? Date.now();
+  const rec = await readLease(backend, targetId);
+  const held = rec && !staleReason(rec, { now, liveIds: ctx.liveIds }) ? rec : undefined;
+  const where = describeTarget(targetId, ctx);
+  if (token === undefined) {
+    if (!held)
+      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, held.label);
+  }
+  const parts = tokenParts(token);
+  if (!parts) {
+    throw new LeaseConflictError(`malformed lease token for ${where}. Pass back the token claim_page returned, never a constructed one.`, targetId);
+  }
+  if (parts.backend !== backend || parts.targetId !== targetId) {
+    if (!held)
+      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, held.label);
+  }
+  if (!held) {
+    throw new LeaseConflictError(`${where} is not leased any more: the token you passed belongs to a lease that was released or reclaimed. Call claim_page again to take the tab.`, targetId);
+  }
+  if (parts.nonce !== held.nonce) {
+    throw new LeaseConflictError(`${where} was reclaimed and is now leased by '${held.label}' (pid ${held.pid}). Your token was invalidated by that reclamation. Call claim_page again if you still need this tab.`, targetId, held.label);
+  }
+  await touchLease(held, now);
+}
+var LEASE_FILE_RE = /^lease-(chrome|firefox)-(.+)\.json$/;
+async function listLeases(opts = {}) {
+  const now = opts.now ?? Date.now();
+  let names = [];
+  try {
+    names = await readdir(leaseDir());
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return [];
+    throw err;
+  }
+  const out = [];
+  for (const name of names) {
+    const parts = LEASE_FILE_RE.exec(name);
+    if (!parts)
+      continue;
+    const fromName = {
+      backend: parts[1],
+      targetId: parts[2],
+      label: "",
+      pid: 0,
+      createdAt: 0,
+      lastUsedAt: 0,
+      ttlMs: 0,
+      pidAlive: false,
+      stale: false
+    };
+    let rec;
+    try {
+      rec = JSON.parse(await readFile(join(leaseDir(), name), "utf8"));
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT")
+        continue;
+      out.push({ ...fromName, unreadable: code ?? "unparseable" });
+      continue;
+    }
+    if (typeof rec?.nonce !== "string" || typeof rec?.pid !== "number") {
+      out.push({ ...fromName, unreadable: "unparseable" });
+      continue;
+    }
+    out.push({
+      backend: rec.backend,
+      targetId: rec.targetId,
+      label: rec.label,
+      pid: rec.pid,
+      createdAt: rec.createdAt,
+      lastUsedAt: rec.lastUsedAt,
+      ttlMs: rec.ttlMs,
+      pidAlive: isPidAlive(rec.pid),
+      stale: staleReason(rec, {
+        now,
+        liveIds: opts.liveBackend === undefined || opts.liveBackend === rec.backend ? opts.liveIds : undefined
+      })
+    });
+  }
+  return out;
+}
+
 // src/client.ts
 var BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
 var DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15000);
@@ -153,8 +405,13 @@ async function browserWsUrl() {
   const v = await httpJson("/json/version");
   return v.webSocketDebuggerUrl;
 }
-async function resolveTarget(selector) {
+async function resolveTarget(selector, opts = {}) {
   const targets = await listTargets();
+  const hit = pickTarget(targets, selector);
+  await assertLeaseOk("chrome", hit.id, { lease: opts.lease, url: hit.url, title: hit.title });
+  return hit;
+}
+function pickTarget(targets, selector) {
   const pages = targets.filter((t) => t.type === "page");
   if (!selector || selector === "active") {
     if (!pages.length)
@@ -190,7 +447,7 @@ async function openBrowser(opts = {}) {
   return new CdpConnection(await browserWsUrl(), opts).connect();
 }
 async function openPage(selector, opts = {}) {
-  const target = await resolveTarget(selector);
+  const target = await resolveTarget(selector, { lease: opts.lease });
   const conn = await new CdpConnection(target.webSocketDebuggerUrl, opts).connect();
   return { conn, target };
 }
@@ -1071,9 +1328,63 @@ function createCdpDriver() {
   return new CdpBrowserDriver;
 }
 
+// src/leases-tools.ts
+class LeaseToolError extends Error {
+}
+function backendOf(driver) {
+  return driver.scheme === "bidi" ? "firefox" : "chrome";
+}
+async function claimPage(driver, args = {}) {
+  const backend = backendOf(driver);
+  const label = typeof args.label === "string" && args.label.length ? args.label : `pid-${process.pid}`;
+  const pages = await driver.listPages();
+  let targetId = args.targetId;
+  let url = args.url ?? "about:blank";
+  if (targetId === undefined || targetId === "") {
+    const page = await driver.newPage(args.url);
+    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;
+  }
+  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
+  });
+  return {
+    lease: token,
+    targetId,
+    url,
+    label: record.label,
+    ttlMs: record.ttlMs,
+    expiresAt: record.lastUsedAt + record.ttlMs
+  };
+}
+async function releasePage(_driver, args) {
+  if (typeof args.lease !== "string" || !args.lease.length) {
+    throw new LeaseToolError("release_page requires the 'lease' token returned by claim_page");
+  }
+  return releaseLease(args.lease);
+}
+async function listLeasesTool(driver, _args = {}) {
+  const liveIds = (await driver.listPages()).map((p) => p.id);
+  const leases = await listLeases({ liveIds, liveBackend: backendOf(driver) });
+  return { leases, count: leases.length };
+}
+var LEASE_TOOLS = {
+  claim_page: claimPage,
+  release_page: releasePage,
+  list_leases: listLeasesTool
+};
+
 // src/shared-tools.ts
-import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
 var ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 
@@ -1082,6 +1393,9 @@ class SharedToolError extends Error {
 function target3(p) {
   return { id: p.id, url: p.url, title: p.title };
 }
+function backendOf2(driver) {
+  return driver.scheme === "bidi" ? "firefox" : "chrome";
+}
 async function withPage2(driver, target, fn) {
   const page = await driver.page(target);
   try {
@@ -1092,6 +1406,11 @@ async function withPage2(driver, target, fn) {
 }
 async function resolvePage(driver, selector) {
   const pages = await driver.listPages();
+  const hit = await pickPage(driver, pages, selector);
+  await assertLeaseOk(backendOf2(driver), hit.id, { url: hit.url, title: hit.title });
+  return hit;
+}
+async function pickPage(driver, pages, selector) {
   if (selector === undefined || selector === "active") {
     if (!pages.length)
       throw new SharedToolError("no page targets open");
@@ -1139,18 +1458,27 @@ async function listPages(driver, args = {}) {
 }
 async function newPage(driver, args = {}) {
   const p = await driver.newPage(args.url);
-  return { targetId: p.id, url: p.url };
+  if (args.claim !== true)
+    return { targetId: p.id, url: p.url };
+  const { record, token } = await claimLease(backendOf2(driver), p.id, {
+    label: typeof args.label === "string" && args.label.length ? args.label : `pid-${process.pid}`,
+    ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs()
+  });
+  return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
 }
 async function closePage(driver, args) {
   if (args.target === undefined || args.target === "")
     throw new SharedToolError("close_page requires an explicit target; refusing to guess which page to close");
   const p = await resolvePage(driver, args.target);
   const res = await driver.closePage(p.id);
-  return { closed: p.id, success: res.success };
+  if (!res.success)
+    return { closed: p.id, success: false, leaseReleased: false };
+  const released = await releaseLeaseFor(backendOf2(driver), p.id);
+  return { closed: p.id, success: true, ...released.released ? { leaseReleased: true } : {} };
 }
 async function writeSelectedFile(id) {
-  await mkdir(STATE_DIR, { recursive: true });
-  await writeFile(join(STATE_DIR, "selected"), id, "utf8");
+  await mkdir2(STATE_DIR, { recursive: true });
+  await writeFile2(join2(STATE_DIR, "selected"), id, "utf8");
 }
 async function selectPage(driver, args) {
   if (args.target === undefined || args.target === "")
@@ -1305,10 +1633,10 @@ async function takeScreenshot(driver, args = {}) {
     const { data, format: outFormat } = await page.screenshot({ format, quality: args.quality, fullPage: args.fullPage, ...clip ? { clip } : {} });
     if (data.byteLength === 0)
       throw new SharedToolError("captureScreenshot returned empty data");
-    await mkdir(ARTIFACT_DIR, { recursive: true });
+    await mkdir2(ARTIFACT_DIR, { recursive: true });
     const ext = outFormat === "jpeg" ? "jpg" : "png";
-    const path = args.savePath ?? join(ARTIFACT_DIR, `screenshot-${page.info.id.slice(0, 8)}-${stamp()}.${ext}`);
-    await writeFile(path, Buffer.from(data));
+    const path = args.savePath ?? join2(ARTIFACT_DIR, `screenshot-${page.info.id.slice(0, 8)}-${stamp()}.${ext}`);
+    await writeFile2(path, Buffer.from(data));
     const result = {
       path,
       bytes: data.byteLength,
@@ -1371,10 +1699,10 @@ var SHARED_TOOLS = {
 };
 
 // src/tools/console.ts
-import { readFile } from "node:fs/promises";
+import { readFile as readFile2 } from "node:fs/promises";
 
 // src/tools/recorder.ts
-import { mkdir as mkdir2, appendFile, writeFile as writeFile2, copyFile } from "node:fs/promises";
+import { mkdir as mkdir3, appendFile, writeFile as writeFile3, copyFile } from "node:fs/promises";
 var ARTIFACT_DIR2 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function recFile(targetId) {
   return `${ARTIFACT_DIR2}/rec-${targetId}.jsonl`;
@@ -1395,11 +1723,11 @@ var CONSOLE_EVENTS = ["Runtime.consoleAPICalled", "Runtime.exceptionThrown", "Lo
 async function startRecorder(target, opts = {}) {
   const network = opts.network ?? true;
   const consoleCap = opts.console ?? true;
-  await mkdir2(ARTIFACT_DIR2, { recursive: true });
+  await mkdir3(ARTIFACT_DIR2, { recursive: true });
   const { conn, target: resolved } = await openPage(target, { timeoutMs: opts.timeoutMs });
   const file = opts.file ?? recFile(resolved.id);
   if (opts.truncate) {
-    await writeFile2(file, "");
+    await writeFile3(file, "");
   }
   let chain = Promise.resolve();
   let dropped = 0;
@@ -1541,7 +1869,7 @@ function lineToEntry(line, index) {
 async function readConsoleEntries(file) {
   let raw;
   try {
-    raw = await readFile(file, "utf8");
+    raw = await readFile2(file, "utf8");
   } catch {
     return [];
   }
@@ -1597,7 +1925,7 @@ async function getConsoleMessage(args = {}) {
 }
 
 // src/tools/network.ts
-import { readFile as readFile2 } from "node:fs/promises";
+import { readFile as readFile3 } from "node:fs/promises";
 var DEFAULT_CAPTURE_MS2 = 2500;
 function asHeaders(v) {
   if (!v || typeof v !== "object")
@@ -1664,7 +1992,7 @@ function correlate(lines) {
 async function readNetworkRequests(file) {
   let raw;
   try {
-    raw = await readFile2(file, "utf8");
+    raw = await readFile3(file, "utf8");
   } catch {
     return [];
   }
@@ -1746,8 +2074,8 @@ async function getNetworkRequest(args = {}) {
 }
 
 // src/tools/performance.ts
-import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3, stat, unlink } from "node:fs/promises";
-import { join as join2 } from "node:path";
+import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4, stat, unlink as unlink2 } from "node:fs/promises";
+import { join as join3 } from "node:path";
 var ARTIFACT_DIR3 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR2 = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 var DEFAULT_CATEGORIES = [
@@ -1765,7 +2093,7 @@ function shortId(id) {
   return id.slice(0, 8);
 }
 function stateFilePath() {
-  return join2(STATE_DIR2, "trace-state.json");
+  return join3(STATE_DIR2, "trace-state.json");
 }
 function bufferTraceData(conn, sink) {
   return conn.on("Tracing.dataCollected", (params) => {
@@ -1787,10 +2115,10 @@ async function endTrace(conn, sink, timeoutMs = 30000) {
   return sink;
 }
 async function writeTrace(events, targetId) {
-  await mkdir3(ARTIFACT_DIR3, { recursive: true });
-  const path = join2(ARTIFACT_DIR3, `trace-${shortId(targetId)}-${stamp2()}.json`);
+  await mkdir4(ARTIFACT_DIR3, { recursive: true });
+  const path = join3(ARTIFACT_DIR3, `trace-${shortId(targetId)}-${stamp2()}.json`);
   const body = JSON.stringify({ traceEvents: events, metadata: { source: "cdp-toolkit" } });
-  await writeFile3(path, body, "utf8");
+  await writeFile4(path, body, "utf8");
   const { size } = await stat(path);
   return { path, bytes: size };
 }
@@ -1810,7 +2138,7 @@ async function performanceStartTrace(args = {}) {
     throw err;
   }
   liveTraces.set(target.id, { conn, target, events, startedAt: Date.now() });
-  await mkdir3(STATE_DIR2, { recursive: true });
+  await mkdir4(STATE_DIR2, { recursive: true });
   const state = {
     targetId: target.id,
     url: target.url,
@@ -1818,7 +2146,7 @@ async function performanceStartTrace(args = {}) {
     pid: process.pid,
     categories
   };
-  await writeFile3(stateFilePath(), JSON.stringify(state), "utf8");
+  await writeFile4(stateFilePath(), JSON.stringify(state), "utf8");
   return {
     target: { id: target.id, url: target.url, title: target.title },
     categories,
@@ -1831,7 +2159,7 @@ async function performanceStopTrace(args = {}) {
   if (!entry) {
     let hint = "";
     try {
-      const raw = await readFile3(stateFilePath(), "utf8");
+      const raw = await readFile4(stateFilePath(), "utf8");
       const state = JSON.parse(raw);
       hint = state.pid === process.pid ? ` (state file lists target ${shortId(state.targetId)} but its live connection is gone)` : ` (trace was started by a DIFFERENT process pid=${state.pid}; live recordings cannot cross process boundaries)`;
     } catch {}
@@ -1843,7 +2171,7 @@ async function performanceStopTrace(args = {}) {
   } finally {
     conn.close();
     liveTraces.delete(target.id);
-    await unlink(stateFilePath()).catch(() => {});
+    await unlink2(stateFilePath()).catch(() => {});
   }
   const written = await writeTrace(events, target.id);
   const metrics = analyzeEvents(events);
@@ -1961,7 +2289,7 @@ async function performanceAnalyzeInsight(args = {}) {
   }
   let raw;
   try {
-    raw = await readFile3(args.tracePath, "utf8");
+    raw = await readFile4(args.tracePath, "utf8");
   } catch (err) {
     throw new CdpError(`cannot read trace file '${args.tracePath}': ${err.message}`);
   }
@@ -1978,8 +2306,8 @@ async function performanceAnalyzeInsight(args = {}) {
 }
 
 // src/tools/heap.ts
-import { mkdir as mkdir4, writeFile as writeFile4 } from "node:fs/promises";
-import { join as join3 } from "node:path";
+import { mkdir as mkdir5, writeFile as writeFile5 } from "node:fs/promises";
+import { join as join4 } from "node:path";
 var ARTIFACT_DIR4 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function stamp3(targetId) {
   const short = targetId.slice(0, 8);
@@ -2004,9 +2332,9 @@ async function takeHeapsnapshot(args = {}) {
     if (snapshot.length === 0) {
       throw new Error("HeapProfiler.takeHeapSnapshot produced no chunks");
     }
-    await mkdir4(ARTIFACT_DIR4, { recursive: true });
-    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join3(ARTIFACT_DIR4, args.savePath) : join3(ARTIFACT_DIR4, `take_heapsnapshot-${stamp3(target.id)}.heapsnapshot`);
-    await writeFile4(path, snapshot, "utf8");
+    await mkdir5(ARTIFACT_DIR4, { recursive: true });
+    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join4(ARTIFACT_DIR4, args.savePath) : join4(ARTIFACT_DIR4, `take_heapsnapshot-${stamp3(target.id)}.heapsnapshot`);
+    await writeFile5(path, snapshot, "utf8");
     const bytes = Buffer.byteLength(snapshot, "utf8");
     return {
       path,
@@ -2019,7 +2347,7 @@ async function takeHeapsnapshot(args = {}) {
 
 // src/tools/lighthouse.ts
 import { spawn } from "node:child_process";
-import { mkdir as mkdir5, readFile as readFile4, stat as stat2 } from "node:fs/promises";
+import { mkdir as mkdir6, readFile as readFile5, stat as stat2 } from "node:fs/promises";
 var ARTIFACT_DIR5 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function cdpPort() {
   const base = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
@@ -2080,7 +2408,7 @@ async function lighthouseAudit(args) {
   const url = args.url.trim();
   const timeoutMs = args.timeoutMs ?? 120000;
   const port = cdpPort();
-  await mkdir5(ARTIFACT_DIR5, { recursive: true });
+  await mkdir6(ARTIFACT_DIR5, { recursive: true });
   const outPath = args.savePath ?? `${ARTIFACT_DIR5}/lighthouse-${shortHost(url)}-${stamp4()}.json`;
   const formFactor = args.formFactor ?? "desktop";
   const lhArgs = [
@@ -2109,7 +2437,7 @@ async function lighthouseAudit(args) {
   }
   let raw;
   try {
-    raw = await readFile4(outPath, "utf8");
+    raw = await readFile5(outPath, "utf8");
   } catch {
     raw = undefined;
   }
@@ -2117,7 +2445,7 @@ async function lighthouseAudit(args) {
     if (res.signal === "SIGKILL") {
       throw new CdpError(`lighthouse_audit timed out after ${timeoutMs}ms (no report written). stderr: ${truncate(res.stderr)}`);
     }
-    const hint = /not found|could not determine executable|npm ERR|E404|ERR_MODULE/i.test(res.stderr) ? " The Lighthouse CLI could not be fetched/installed via npx — ensure network access and that 'lighthouse' is installable." : "";
+    const hint = /not found|could not determine executable|npm ERR|E404|ERR_MODULE/i.test(res.stderr) ? " The Lighthouse CLI could not be fetched/installed via npx; ensure network access and that 'lighthouse' is installable." : "";
     throw new CdpError(`lighthouse_audit produced no report (exit code ${res.code}).${hint} stderr: ${truncate(res.stderr)}`);
   }
   let report;
@@ -2191,7 +2519,10 @@ var TOOLS = {
   lighthouse_audit: lighthouseAudit,
   mock_request: mockRequest,
   list_mocks: listMocks,
-  clear_mocks: clearMocks
+  clear_mocks: clearMocks,
+  claim_page: onCdp(LEASE_TOOLS.claim_page),
+  release_page: onCdp(LEASE_TOOLS.release_page),
+  list_leases: onCdp(LEASE_TOOLS.list_leases)
 };
 var TOOL_NAMES = Object.keys(TOOLS);
 
@@ -2208,6 +2539,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         all: {
           type: "boolean",
           description: "Include non-page targets (service/shared workers, background pages) when true; otherwise only page-type tabs are listed."
@@ -2223,9 +2558,25 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         url: {
           type: "string",
           description: "URL to open in the new tab; defaults to about:blank."
+        },
+        claim: {
+          type: "boolean",
+          description: "Claim the new tab atomically as part of creating it and return a lease token alongside {targetId,url}. Default false, which is byte-identical to the pre-1.2 behavior."
+        },
+        label: {
+          type: "string",
+          description: "Agent label recorded on the lease when claim:true, surfaced in conflict errors and list_leases. Defaults to pid-<pid>."
+        },
+        ttlMs: {
+          type: "number",
+          description: "How long the lease taken by claim:true survives without use before it is reclaimable. Defaults to CDP_LEASE_TTL_MS, else 900000 (15 minutes). Every checked call refreshes it, so an active agent never expires. Ignored without claim:true."
         }
       },
       required: [],
@@ -2238,6 +2589,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2255,6 +2610,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2272,6 +2631,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2306,10 +2669,14 @@ var MANIFEST = [
   },
   {
     name: "wait_for",
-    description: "Poll a target page until the given substring appears in document.body.innerText (Runtime.evaluate on a fixed interval), or throw on timeout. Text-substring waiting only — no aria/role/selector or event variants; throws rather than returning {found:false}.",
+    description: "Poll a target page until the given substring appears in document.body.innerText (Runtime.evaluate on a fixed interval), or throw on timeout. Text-substring waiting only: no aria/role/selector or event variants; throws rather than returning {found:false}.",
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2339,6 +2706,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Page selector: 'active' (or omit) -> first page-type target | '<32-hex targetId>' -> exact target by id | 'index:N' -> Nth page-type target (0-based) | 'url:<substring>' -> first page whose url contains substring | 'title:<substring>' -> first page whose title contains substring."
@@ -2364,10 +2735,14 @@ var MANIFEST = [
   },
   {
     name: "take_snapshot",
-    description: "Capture the page's accessibility tree (Accessibility.getFullAXTree) as a compact indented text tree where each line is prefixed with [uid] — the node's CDP backendDOMNodeId. These uids are the stateless element references that every interaction tool (click/hover/fill/etc.) feeds back to resolve a live DOM node (via DOM.resolveNode({ backendNodeId: uid })), so run this first to discover uids.",
+    description: "Capture the page's accessibility tree (Accessibility.getFullAXTree) as a compact indented text tree where each line is prefixed with [uid], the node's CDP backendDOMNodeId. These uids are the stateless element references that every interaction tool (click/hover/fill/etc.) feeds back to resolve a live DOM node (via DOM.resolveNode({ backendNodeId: uid })), so run this first to discover uids.",
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default, = first page-type target) | 'index:N' (Nth page-type target, 0-based) | 'url:<substring>' | 'title:<substring>' | '<32-hex targetId>' (exact target by id)."
@@ -2387,6 +2762,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2423,6 +2802,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2446,6 +2829,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2494,6 +2881,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2523,6 +2914,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2565,6 +2960,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2594,6 +2993,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2622,6 +3025,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2653,10 +3060,14 @@ var MANIFEST = [
   },
   {
     name: "take_screenshot",
-    description: "Capture the viewport (default), the full scrollable page (fullPage), or a single element (uid or selector — exactly one, mutually exclusive) via raw CDP Page.captureScreenshot. Writes a PNG/JPEG under /tmp/cdp-toolkit (override with savePath) and returns {path,bytes,format,target}; raw base64 is only included when returnBase64 is set. quality applies to jpeg only.",
+    description: "Capture the viewport (default), the full scrollable page (fullPage), or a single element (uid or selector, exactly one and mutually exclusive) via raw CDP Page.captureScreenshot. Writes a PNG/JPEG under /tmp/cdp-toolkit (override with savePath) and returns {path,bytes,format,target}; raw base64 is only included when returnBase64 is set. quality applies to jpeg only.",
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector. undefined or 'active' -> first page target; '<32-hex targetId>' -> exact target by id; 'index:N' -> Nth page target (0-based); 'url:<substring>' -> first page whose url contains substring; 'title:<substring>' -> first page whose title contains substring."
@@ -2679,7 +3090,7 @@ var MANIFEST = [
         },
         uid: {
           type: "number",
-          description: "Element to clip to — a CDP backendDOMNodeId obtained from take_snapshot. Mutually exclusive with selector."
+          description: "Element to clip to: a CDP backendDOMNodeId obtained from take_snapshot. Mutually exclusive with selector."
         },
         selector: {
           type: "string",
@@ -2704,6 +3115,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2800,6 +3215,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2834,6 +3253,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (or omitted) for the first page-type target | 'index:N' (0-based) | 'url:<substring>' | 'title:<substring>' | a 32-hex <targetId>."
@@ -2867,6 +3290,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
@@ -2886,10 +3313,14 @@ var MANIFEST = [
   },
   {
     name: "get_console_message",
-    description: "Return a single console entry by zero-based index from the target's existing console buffer. Throws if the index is out of range — run list_console_messages (optionally with reload:true) first to populate the buffer.",
+    description: "Return a single console entry by zero-based index from the target's existing console buffer. Throws if the index is out of range; run list_console_messages (optionally with reload:true) first to populate the buffer.",
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
@@ -2909,6 +3340,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
@@ -2932,17 +3367,21 @@ var MANIFEST = [
   },
   {
     name: "get_network_request",
-    description: "Return one network request (matched by exact requestId, else by url substring) including status/headers. Requires at least one of requestId or url (throws otherwise). With includeBody:true the body fetch drives a fresh reload capture and is matched by url ONLY (reload re-mints requestIds, so a carried-over requestId cannot fetch a body — it returns metadata plus bodyUnavailableReason).",
+    description: "Return one network request (matched by exact requestId, else by url substring) including status/headers. Requires at least one of requestId or url (throws otherwise). With includeBody:true the body fetch drives a fresh reload capture and is matched by url ONLY (reload re-mints requestIds, so a carried-over requestId cannot fetch a body, so it returns metadata plus bodyUnavailableReason).",
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
         },
         requestId: {
           type: "string",
-          description: "Match by exact requestId (metadata only — cannot fetch a body, since reload re-mints requestIds)."
+          description: "Match by exact requestId (metadata only, cannot fetch a body, since reload re-mints requestIds)."
         },
         url: {
           type: "string",
@@ -2967,6 +3406,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -2985,10 +3428,14 @@ var MANIFEST = [
   },
   {
     name: "performance_stop_trace",
-    description: "Stop the in-process trace started by performance_start_trace, drain buffered Tracing.dataCollected events, write the trace JSON under /tmp/cdp-toolkit, and return {path,bytes,events,metrics}. Throws if no live trace exists in this process (e.g. start ran in a different process) — use performance_trace instead. The 'target' arg is accepted only for API symmetry; at most one trace is ever live per process.",
+    description: "Stop the in-process trace started by performance_start_trace, drain buffered Tracing.dataCollected events, write the trace JSON under /tmp/cdp-toolkit, and return {path,bytes,events,metrics}. Throws if no live trace exists in this process (e.g. start ran in a different process); use performance_trace instead. The 'target' arg is accepted only for API symmetry; at most one trace is ever live per process.",
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -3000,10 +3447,14 @@ var MANIFEST = [
   },
   {
     name: "performance_analyze_insight",
-    description: "CDP-native approximation of the DevTools insight analyzer: read a trace JSON file (bare array or {traceEvents:[...]}) at the given tracePath and return headline metrics (FCP/LCP/CLS/TBT, long tasks, layout shifts). Requires an explicit tracePath returned by performance_trace/performance_stop_trace — there is no implicit 'latest trace'. Numbers approximate DevTools (no main-thread attribution or frame-scoped LCP).",
+    description: "CDP-native approximation of the DevTools insight analyzer: read a trace JSON file (bare array or {traceEvents:[...]}) at the given tracePath and return headline metrics (FCP/LCP/CLS/TBT, long tasks, layout shifts). Requires an explicit tracePath returned by performance_trace/performance_stop_trace; there is no implicit 'latest trace'. Numbers approximate DevTools (no main-thread attribution or frame-scoped LCP).",
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         tracePath: {
           type: "string",
           description: "Filesystem path to a trace JSON file written by performance_trace or performance_stop_trace (bare array OR {traceEvents:[...]}). Required."
@@ -3015,10 +3466,14 @@ var MANIFEST = [
   },
   {
     name: "performance_trace",
-    description: "PRIMARY one-shot trace: start tracing, optionally reload or navigate the page, wait durationMs (default 3000), end the trace, write the trace JSON under /tmp/cdp-toolkit, and return {path,bytes,events,metrics,target}. Holds one connection open for the whole window, so it is immune to the cross-process limitation of start/stop — the recommended entry point.",
+    description: "PRIMARY one-shot trace: start tracing, optionally reload or navigate the page, wait durationMs (default 3000), end the trace, write the trace JSON under /tmp/cdp-toolkit, and return {path,bytes,events,metrics,target}. Holds one connection open for the whole window, so it is immune to the cross-process limitation of start/stop, and it is the recommended entry point.",
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -3053,6 +3508,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -3072,9 +3531,13 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         url: {
           type: "string",
-          description: "The URL to audit. Required — never points at a user tab implicitly."
+          description: "The URL to audit. Required, and never points at a user tab implicitly."
         },
         categories: {
           type: "array",
@@ -3108,10 +3571,14 @@ var MANIFEST = [
   },
   {
     name: "mock_request",
-    description: "Register a mock rule on a target's persistent fake-backend session (CDP Fetch domain): intercept requests whose URL matches urlPattern and fulfill them with a canned response, fail (abort) them, or continue them — optionally with fault injection (delayMs/failRate). The session survives reloads and navigations and lives until clear_mocks. Call repeatedly to mock several endpoints on the same target. Pass reload:true to apply immediately. Persistent across calls only via the MCP server (not the one-shot CLI).",
+    description: "Register a mock rule on a target's persistent fake-backend session (CDP Fetch domain): intercept requests whose URL matches urlPattern and fulfill them with a canned response, fail (abort) them, or continue them, optionally with fault injection (delayMs/failRate). The session survives reloads and navigations and lives until clear_mocks. Call repeatedly to mock several endpoints on the same target. Pass reload:true to apply immediately. Persistent across calls only via the MCP server (not the one-shot CLI).",
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target selector: active | index:N | url:<substr> | title:<substr> | <targetId>. Defaults to the active page."
@@ -3178,6 +3645,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Unused filter placeholder; list_mocks returns all active sessions."
@@ -3193,6 +3664,10 @@ var MANIFEST = [
     inputSchema: {
       type: "object",
       properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         target: {
           type: "string",
           description: "Target selector whose mock session to clear. Defaults to the active page. Ignored when all:true."
@@ -3205,6 +3680,60 @@ var MANIFEST = [
       required: [],
       additionalProperties: false
     }
+  },
+  {
+    name: "claim_page",
+    description: "Take exclusive ownership of a browser tab and return an opaque lease token. With no targetId, opens a fresh tab (optionally at url) and claims it, so 'give me my own tab' is one call. Any later tool call against a leased tab must carry the matching token in its 'lease' argument or it is refused, naming the holder. The lease is reclaimable once its owning process dies, its ttlMs elapses without use, or its tab is closed. Refused from the CLI: a CLI invocation is one process per call, so its lease would be reclaimable immediately.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        targetId: {
+          type: "string",
+          description: "Claim this already-open page target instead of opening a new tab. Must be an exact target id, not a selector."
+        },
+        url: {
+          type: "string",
+          description: "When opening a fresh tab, navigate it here. Ignored when targetId is given."
+        },
+        label: {
+          type: "string",
+          description: "Agent label recorded on the lease and surfaced in conflict errors and list_leases. Defaults to pid-<pid>."
+        },
+        ttlMs: {
+          type: "number",
+          description: "How long the lease survives without use before it is reclaimable. Defaults to CDP_LEASE_TTL_MS, else 900000 (15 minutes). Every checked call refreshes it, so an active agent never expires."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "release_page",
+    description: "Release a held lease, given its token. Idempotent: releasing an already-released, reclaimed, or expired lease reports released:false rather than erroring. Does not close the tab.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "The opaque token claim_page (or new_page with claim:true) returned."
+        }
+      },
+      required: [
+        "lease"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "list_leases",
+    description: 'Enumerate every active lease for diagnosis: backend, target id, agent label, pid, createdAt, lastUsedAt, ttlMs, whether the owning process is still alive, and whether the lease is reclaimable and why. Requires no token. Never returns the lease nonce, so this cannot be used to forge a token. A row for a lease file that could not be read or parsed instead carries `unreadable` (the errno, or "unparseable"), with label, pid, and the timestamp fields as zero placeholders and stale always false, since stale is what marks a lease free to take and an unreadable one must never read that way.',
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false
+    }
   }
 ];
 
@@ -3963,12 +4492,17 @@ async function safeTitle(conn, contextId) {
 async function pageInfoOf(conn, ctx) {
   return { id: ctx.context, url: ctx.url, title: await safeTitle(conn, ctx.context) };
 }
-async function resolveContext(conn, selector) {
+async function resolveContext(conn, selector, opts = {}) {
   const { contexts } = await conn.send("browsingContext.getTree", {}).catch((e) => {
     throw mapBidiError(e);
   });
   if (!contexts.length)
     throw driverError2("no-such-target", "no browsing contexts available");
+  const hit = await pickContext(conn, contexts, selector);
+  await assertLeaseOk("firefox", hit.context, { lease: opts.lease, url: hit.url });
+  return hit;
+}
+async function pickContext(conn, contexts, selector) {
   if (selector === undefined || selector === "active")
     return contexts[0];
   if (selector.startsWith("index:")) {
@@ -4489,7 +5023,7 @@ import { spawn as spawn2 } from "node:child_process";
 import { mkdtempSync, rmSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
 import { tmpdir } from "node:os";
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 function resolveBinary() {
   const candidates = [
     process.env.FIREFOX_BIN,
@@ -4563,7 +5097,7 @@ async function launchFirefox(opts = {}) {
   const binary = resolveBinary();
   const port = await pickPort(opts.port);
   const isThrowaway = opts.profilePath === undefined;
-  const profilePath = opts.profilePath ?? mkdtempSync(join4(tmpdir(), "cdp-toolkit-ff-profile-"));
+  const profilePath = opts.profilePath ?? mkdtempSync(join5(tmpdir(), "cdp-toolkit-ff-profile-"));
   const args = ["--profile", profilePath, "--remote-debugging-port", String(port), "--no-remote"];
   if (opts.headless)
     args.push("--headless");
@@ -4828,11 +5362,12 @@ var BIDI_ONLY_TOOLS = {
 // src/firefox-tools.ts
 var FIREFOX_TOOLS = {
   ...SHARED_TOOLS,
-  ...BIDI_ONLY_TOOLS
+  ...BIDI_ONLY_TOOLS,
+  ...LEASE_TOOLS
 };
 
 // src/mcp.ts
-var VERSION = "1.1.0";
+var VERSION = "1.2.0";
 var BROWSER = resolveBrowserKind(stripBrowserFlag(process.argv.slice(2)));
 var AVAILABILITY = toolAvailability(BROWSER);
 var AVAILABLE_NAMES = new Set(AVAILABILITY.available);
@@ -4862,29 +5397,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       isError: true
     };
   }
-  if (BROWSER === "chrome") {
-    const fn = dispatch[name];
-    if (!fn)
+  return withLeaseScope(leaseFromArgs(args), async () => {
+    if (BROWSER === "chrome") {
+      const fn = dispatch[name];
+      if (!fn)
+        return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
+      try {
+        const result = await fn(args);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+      }
+    }
+    const neutralFn = neutralDispatch[name];
+    if (!neutralFn)
       return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
     try {
-      const result = await fn(args);
+      const session = await getOrCreateFirefoxSession();
+      const result = await neutralFn(session.driver, args);
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
     }
-  }
-  const neutralFn = neutralDispatch[name];
-  if (!neutralFn)
-    return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
-  try {
-    const session = await getOrCreateFirefoxSession();
-    const result = await neutralFn(session.driver, args);
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
-  }
+  });
 });
 auditCoverage();
 await server.connect(new StdioServerTransport);