cdp-toolkit 1.2.0 → 1.6.0

package/src/leases.ts

@@ -65,6 +65,14 @@ export function leaseTtlMs(): number {
   return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_LEASE_TTL_MS;
 }
 
+/** 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
+ *  different ways depending on which of them wrote first. */
+export function defaultLabel(): string {
+  return `pid-${process.pid}`;
+}
+
 function safeId(id: string): string {
   return id.replace(/[^A-Za-z0-9._-]/g, "_");
 }
@@ -257,7 +265,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.

package/src/manifest.ts

@@ -25,7 +25,7 @@ export interface ToolSpec {
 export const MANIFEST: ToolSpec[] = [
   {
     "name": "list_pages",
-    "description": "Enumerate browser page targets via the CDP browser endpoint (GET /json/list). By default returns only page-type tabs; set 'all' to also include workers and background pages. Each entry carries the targetId used as a target selector elsewhere.",
+    "description": "Enumerate browser page targets via the CDP browser endpoint (GET /json/list). By default returns only page-type tabs; set 'all' to also include workers and background pages. Each entry carries the targetId used as a target selector elsewhere, plus an 'origin' field recording where the tab came from: 'agent' means this toolkit created it (the entry then also carries the creating 'label' and 'createdAt'), and this stays true after the creating agent releases its lease or dies, which is what makes a stray agent tab findable later. 'unknown' means there is no creation record. It never says 'human': the toolkit cannot prove a person opened a tab, so 'unknown' is the honest word for a tab it did not create, one opened before the toolkit ran, or one whose record could not be written. A tab whose record exists but could not be read reports origin 'unknown' plus 'originUnreadable', so a broken record is never mistaken for no record.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -192,7 +192,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "evaluate_script",
-    "description": "Run arbitrary JavaScript in the target page's main-world context over raw CDP and return the evaluated value (returnByValue). With no 'args' the 'expression' is evaluated as a raw expression; when 'args' is provided 'expression' must be a function literal (arrow or classic) invoked on globalThis with the args passed positionally. A thrown exception surfaces as an error; non-serializable returns (DOM nodes, functions) come back as their CDP description string.",
+    "description": "Run arbitrary JavaScript in the target page's main-world context over raw CDP and return the evaluated value (returnByValue). With no 'args' the 'expression' is evaluated as a raw expression; when 'args' is provided 'expression' must be a function literal (arrow or classic) invoked on globalThis with the args passed positionally. A thrown exception surfaces as an error; non-serializable returns (DOM nodes, functions) come back as their CDP description string. Pass 'savePath' to write the evaluated value to a JSON file instead: the response then carries only {path,bytes,type,target} and the value itself never appears in it, in any form. That is the way to read a credential (a JWT or session token out of localStorage, for example) without putting the secret into the caller's transcript.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -215,6 +215,10 @@ export const MANIFEST: ToolSpec[] = [
         "args": {
           "type": "array",
           "description": "Positional JSON-serializable arguments to pass to the expression, treating it as a function. No live element/page handle is bound."
+        },
+        "savePath": {
+          "type": "string",
+          "description": "Write the evaluated value to this file as JSON and KEEP IT OUT OF THE RESPONSE: with savePath set the result is {path,bytes,type,target} only, with no copy, preview or truncation of the value. Use it to read credentials without putting them in a transcript. An absolute path (starting with /) is used as-is; a relative path is resolved under the artifact dir (/tmp/cdp-toolkit). Missing parent directories are created. Omit it to get the value back inline, exactly as before."
         }
       },
       "required": [
@@ -223,6 +227,128 @@ export const MANIFEST: ToolSpec[] = [
       "additionalProperties": false
     }
   },
+  {
+    "name": "list_cookies",
+    "description": "Read the cookie store for the target page, INCLUDING httpOnly cookies, which document.cookie cannot see and an evaluate_script call therefore cannot reach. Each cookie carries name, value, domain, path, expires (Unix seconds, -1 for a session cookie), size, httpOnly, secure, sameSite ('strict'|'lax'|'none'|'default') and session. The read is page-scoped, not browser-wide: it returns the cookies of the resolved tab (Chrome: Network.getCookies; Firefox: storage.getCookies partitioned by that browsing context), so point at a page on the site whose cookies you want. Filter with 'domain' and/or 'name'. Pass 'savePath' to write the cookie array to a JSON file instead: the response is then {path,bytes,count,target} only, with no cookie value in it in any form, which is how to capture a session cookie without putting the credential in the caller's transcript.",
+    "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."
+        },
+        "target": {
+          "type": "string",
+          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+        },
+        "domain": {
+          "type": "string",
+          "description": "Keep only cookies for this domain. A leading dot is ignored on both sides and subdomains of the given domain match too, so 'example.test' matches '.example.test' and 'app.example.test'. No wildcards."
+        },
+        "name": {
+          "type": "string",
+          "description": "Keep only the cookie with exactly this name. Exact match, not a substring."
+        },
+        "savePath": {
+          "type": "string",
+          "description": "Write the cookie array to this file as JSON and KEEP THE VALUES OUT OF THE RESPONSE: with savePath set the result is {path,bytes,count,target} only, with no copy, preview or truncation of any cookie value. An absolute path (starting with /) is used as-is; a relative path is resolved under the artifact dir (/tmp/cdp-toolkit). Missing parent directories are created. Omit it to get the cookies back inline."
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "set_cookie",
+    "description": "Write one cookie into the target page's cookie store, INCLUDING an httpOnly or secure cookie, which document.cookie cannot create and an evaluate_script call therefore cannot either. Chrome uses Network.setCookie, Firefox uses storage.setCookie partitioned by the resolved browsing context. Either 'url' or 'domain' is REQUIRED: a cookie has to be attributed to a site and the call is refused with an error when neither is given, rather than guessing the current page's origin. The response is {set:true,target} and never echoes the value back, so a credential you just supplied does not land in the transcript twice. A 'set:true' is earned, not assumed: Chrome answers Network.setCookie with success:false when it declines a cookie (a domain the url does not belong to, a secure cookie on an insecure origin, an oversized value) and that refusal is raised as an error. On Firefox, 'domain' is derived from 'url' when only the url was given, because BiDi has no url parameter; a url with no host, such as about:blank or a data URL, is an error rather than a silent no-op. Read the result back with list_cookies when you need proof.",
+    "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."
+        },
+        "target": {
+          "type": "string",
+          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+        },
+        "name": {
+          "type": "string",
+          "description": "Cookie name. Required and non-empty."
+        },
+        "value": {
+          "type": "string",
+          "description": "Cookie value. Required. It is not echoed back in the response."
+        },
+        "url": {
+          "type": "string",
+          "description": "The URL the cookie is set for, for example 'https://example.com/'. Chrome derives domain, path and secure from it. Firefox derives only the domain from its host. Give this or 'domain'."
+        },
+        "domain": {
+          "type": "string",
+          "description": "Cookie domain, for example 'example.com' or '.example.com' for subdomains. Give this or 'url'. When both are given, this wins on Firefox and Chrome applies its own url plus domain consistency rule."
+        },
+        "path": {
+          "type": "string",
+          "description": "Cookie path. Passed through exactly as given and NOT defaulted to '/': with a 'url' Chrome derives the path from it, so an invented default here would widen a cookie you meant to scope narrowly."
+        },
+        "expires": {
+          "type": "number",
+          "description": "Expiry as Unix time in SECONDS, matching what list_cookies reports. Omit it for a session cookie, which is what both backends do when no expiry is supplied."
+        },
+        "httpOnly": {
+          "type": "boolean",
+          "description": "Set the httpOnly flag, making the cookie invisible to document.cookie. Only a protocol write like this one can create such a cookie."
+        },
+        "secure": {
+          "type": "boolean",
+          "description": "Set the secure flag. Chrome declines a secure cookie on an insecure origin, and that refusal surfaces as an error."
+        },
+        "sameSite": {
+          "type": "string",
+          "enum": ["strict", "lax", "none", "default"],
+          "description": "SameSite attribute, lowercase, matching what list_cookies reports. 'default' means the attribute is not set at all."
+        }
+      },
+      "required": ["name", "value"],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "delete_cookies",
+    "description": "Delete the named cookie from the target page's cookie store, httpOnly cookies included. Chrome uses Network.deleteCookies, Firefox uses storage.deleteCookies with a filter, partitioned by the resolved browsing context. Both 'name' and one of 'url' or 'domain' are REQUIRED: without a site constraint the call would delete by name across the whole partition, so it is refused with an error instead. Narrow further with 'path'. The response is {deleted:true,target} and carries NO count, because neither protocol reports how many cookies it removed and a number here would be invented; call list_cookies before and after when you need a real count. 'deleted:true' means the backend accepted and performed the deletion, not that a matching cookie existed, since deleting an absent cookie is a success on both backends.",
+    "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."
+        },
+        "target": {
+          "type": "string",
+          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+        },
+        "name": {
+          "type": "string",
+          "description": "Exact cookie name to delete. Required and non-empty. No wildcards: this removes a named cookie, not a swathe of them."
+        },
+        "url": {
+          "type": "string",
+          "description": "Delete cookies matching this URL, for example 'https://example.com/'. Give this or 'domain'. On Firefox only the host is used, because BiDi's filter has no url field."
+        },
+        "domain": {
+          "type": "string",
+          "description": "Delete cookies with this exact domain. Give this or 'url'."
+        },
+        "path": {
+          "type": "string",
+          "description": "Narrow the deletion to cookies with this exact path. Omit to match any path allowed by the other constraints."
+        }
+      },
+      "required": ["name"],
+      "additionalProperties": false
+    }
+  },
   {
     "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.",
@@ -992,6 +1118,76 @@ export const MANIFEST: ToolSpec[] = [
       "additionalProperties": false
     }
   },
+  {
+    "name": "start_screen_recording",
+    "description": "Start recording the target tab to video over raw CDP (Page.startScreencast), holding one persistent connection open and spooling every Page.screencastFrame to disk. Chrome emits a frame ON REPAINT, not on a clock, so the stream is variable-rate: each frame is timestamped into a ledger and stop_screen_recording turns those timestamps into per-frame display durations, which is what makes a still page hold one long frame instead of the video racing or freezing. Every frame is acked immediately (an unacked frame stalls the stream). ffmpeg is probed here, not at stop, so a missing encoder fails before a recording is captured and thrown away. Must be paired with stop_screen_recording WITHIN THE SAME PROCESS (the frames are events on this connection and cannot be re-attached from another process, so the pair works under the MCP server, not the one-process-per-call CLI). Throws if a recording is already in progress for the target; recordings on DIFFERENT targets run concurrently. Chrome only: WebDriver BiDi has no screencast primitive, so both tools are absent under --browser firefox.",
+    "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>'."
+        },
+        "format": {
+          "type": "string",
+          "enum": [
+            "jpeg",
+            "png"
+          ],
+          "description": "Frame image format. Defaults to jpeg (far smaller per repaint); png is lossless. quality applies to jpeg only."
+        },
+        "quality": {
+          "type": "number",
+          "description": "JPEG frame quality 0-100. Ignored for png. Omitted by default, which leaves Chrome's own default in place."
+        },
+        "maxWidth": {
+          "type": "number",
+          "description": "Cap the streamed frame width in pixels. Also the way to pin frame size if the viewport might change mid-recording."
+        },
+        "maxHeight": {
+          "type": "number",
+          "description": "Cap the streamed frame height in pixels."
+        },
+        "everyNthFrame": {
+          "type": "number",
+          "description": "Capture only every Nth repaint (1 = every frame). Reduces spool size on a busy page; per-frame durations keep playback at wallclock speed either way."
+        },
+        "bringToFront": {
+          "type": "boolean",
+          "description": "Activate the tab (Page.bringToFront) before recording. Default false. A fully backgrounded or occluded tab may never repaint, and a recording of one captures 0 frames."
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "stop_screen_recording",
+    "description": "Stop the recording started by start_screen_recording, assemble the spooled frames into an MP4 with ffmpeg using PER-FRAME durations from the ledger (frame N is held until frame N+1 painted; the last frame is held until this call), and return {path,bytes,durationMs,frameCount,encodedFrames,codec,encoder,width,height,droppedFrames,target}. Encoder ladder, probed once at start: hevc_videotoolbox then h264_videotoolbox then libx265 then libx264, with -tag:v hvc1 on HEVC so QuickTime plays it, +faststart, yuv420p, and even dimensions forced. With one recording in flight 'target' may be omitted; with several it is required, because guessing which to stop can lose another agent's recording. Throws if nothing is recording in this process, and throws rather than writing a silent empty video when 0 frames arrived. On an ffmpeg failure the spooled frames are KEPT and the spool path plus the exact command are named in the error. Encoded video tops out at 25 fps: ffmpeg's concat demuxer represents image timestamps on a 1/25s grid, so frames captured less than 40ms apart are coalesced deliberately (frameCount reports what was captured, encodedFrames what reached the video) instead of being dropped silently by ffmpeg. durationMs is the sum of the encoded durations; the file itself runs one 40ms step longer, because the concat demuxer needs the final frame repeated for its hold to count.",
+    "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": "Which recording to stop: 'active' (default, valid only when exactly one recording is in flight) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+        },
+        "savePath": {
+          "type": "string",
+          "description": "Override the output file path. Default: /tmp/cdp-toolkit/screen-recording-<targetIdShort>-<stamp>.mp4."
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    }
+  },
   {
     "name": "take_heapsnapshot",
     "description": "Capture a V8 heap snapshot of the selected page target over raw CDP (HeapProfiler.takeHeapSnapshot, accumulating addHeapSnapshotChunk events) and write it as a .heapsnapshot JSON file loadable by the DevTools Memory panel; returns {path,bytes,chunks,target} only and does not parse/summarize the snapshot. Writes under /tmp/cdp-toolkit (CDP_ARTIFACT_DIR) unless savePath is given.",

package/src/mcp.ts

@@ -23,7 +23,7 @@ import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, withLeaseScope } from "./leases.ts";
 
-const VERSION = "1.2.0";
+const VERSION = "1.6.0";
 
 // --browser is read once at startup (MCP has no per-call notion of backend): explicit flag,
 // else CDP_BROWSER env var, else "chrome" (zero behavior change for existing users/configs).

package/src/origins.ts

@@ -0,0 +1,266 @@
+/**
+ * Tab origins: a creation ledger recording every tab THIS TOOLKIT opened.
+ *
+ * WHY THIS IS NOT list_leases. A lease answers "who is DRIVING this tab right
+ * now". Provenance is a different and longer-lived question: "who OPENED this
+ * tab". The two diverge the moment an agent releases, expires, or dies, and
+ * that is exactly when a human most needs the answer, because from then on the
+ * agent's abandoned tab is indistinguishable from one the human opened. So a
+ * record here deliberately OUTLIVES the lease and is never removed by
+ * release_page, by expiry, or by reclamation.
+ *
+ * WHY ONE FILE PER TAB, IN THE LEASE DIRECTORY. Same reasoning as leases.ts:
+ * two MCP server processes drive one browser, so module state would protect
+ * one process and miss the collision that matters, and a single registry file
+ * would need its own lock. Exclusive-create ("wx") per tab gives the atomicity
+ * for free, and the filename carries enough to describe a row whose contents
+ * cannot be read.
+ *
+ * WHY THE ONLY DELETE IS A REAP ON READ. A background sweeper would be a
+ * second lifetime to reason about and a process that has to be running. The
+ * ledger is read rarely (list_pages) and the browser's own target list is
+ * already in hand at that moment, so dropping records for targets that no
+ * longer exist costs nothing and keeps the directory bounded without anything
+ * scheduled.
+ *
+ * WHAT THIS CANNOT PROVE. The absence of a record is not evidence that a human
+ * opened the tab: an agent driving Chrome by some other means, a tab restored
+ * from a previous session, or a record lost to a write failure all read the
+ * same way. That is why the annotation on list_pages says "unknown" and never
+ * "human". Never add a "human" value here.
+ */
+import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { BrowserDriver, PageInfo } from "./driver.ts";
+import { defaultLabel, leaseDir, type LeaseBackend } from "./leases.ts";
+
+/** What list_pages can say about where a tab came from. There is deliberately
+ *  no "human": see the file header. */
+export type PageOrigin = "agent" | "unknown";
+
+export interface OriginRecord {
+  backend: LeaseBackend;
+  targetId: string;
+  /** Caller-supplied agent label, or leases.ts's pid-derived default. */
+  label: string;
+  /** The MCP server process that created the tab. Recorded for diagnosis only:
+   *  unlike a lease, this record stays meaningful after that pid is gone. */
+  pid: number;
+  createdAt: number;
+}
+
+/** Same character policy as leaseFile, so the two stores agree on what a
+ *  filename-safe id looks like and a reader can compare them. */
+function safeId(id: string): string {
+  return id.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+/** Sibling of leases.ts's lease-<backend>-<targetId>.json, same directory. */
+export function originFile(backend: LeaseBackend, targetId: string): string {
+  return join(leaseDir(), `origin-${backend}-${safeId(targetId)}.json`);
+}
+
+const ORIGIN_FILE_RE = /^origin-(chrome|firefox)-(.+)\.json$/;
+
+/**
+ * Record that this toolkit just created `targetId`.
+ *
+ * ATOMICITY MATCHES leases.ts: exclusive create, never a modify in place. A
+ * record is written once and thereafter only deleted, so two processes racing
+ * on the same id cannot interleave a half-written file.
+ *
+ * ON EEXIST THE NEW RECORD WINS, and that is the answer to target-id reuse.
+ * A browser is free to hand out an id that a closed tab used to hold. Reaping
+ * on read makes that benign in the normal case: the old record is dropped the
+ * first time anyone lists pages after the old tab closed, so the id is usually
+ * free by the time it is reused. If nobody read the ledger in between, the
+ * stale record is still sitting there when this runs, and the unlink-then-
+ * recreate below replaces it. The residual case is a reused id whose new tab
+ * this toolkit did NOT create: that tab inherits the old record and reports
+ * origin "agent" with a createdAt older than the tab itself. It errs toward
+ * flagging a tab as agent-created, which is the safe direction for a tool whose
+ * job is to help a human find stray agent tabs, and the stale createdAt is the
+ * tell. Do not "fix" it by trusting the record blindly in the other direction.
+ *
+ * FAILURES ARE SWALLOWED DELIBERATELY. This is an annotation, not the work the
+ * caller asked for: new_page must not fail because a provenance record could
+ * not be persisted. The cost is real and worth stating plainly: a tab created
+ * while the artifact directory is unwritable reports origin "unknown" forever,
+ * with no signal anywhere. If agent tabs ever start reading as unknown, an
+ * ENOSPC or EACCES here is the first place to look.
+ */
+export async function recordOrigin(
+  backend: LeaseBackend,
+  targetId: string,
+  opts: { label?: string; now?: number } = {},
+): Promise<void> {
+  const record: OriginRecord = {
+    backend,
+    targetId,
+    label: typeof opts.label === "string" && opts.label.length ? opts.label : defaultLabel(),
+    pid: process.pid,
+    createdAt: opts.now ?? Date.now(),
+  };
+  const file = originFile(backend, targetId);
+  try {
+    await mkdir(leaseDir(), { recursive: true });
+    try {
+      await writeFile(file, JSON.stringify(record), { flag: "wx" });
+      return;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+    }
+    // A record already exists for this id: the browser reused it. Replace
+    // rather than modify in place, so a reader never sees a partial rewrite.
+    await unlink(file).catch(() => undefined);
+    await writeFile(file, JSON.stringify(record), { flag: "wx" });
+  } catch {
+    /* annotation only, never fail the caller's real work: see the doc comment */
+  }
+}
+
+/**
+ * Read one origin record, or undefined if this toolkit did not create the tab.
+ *
+ * UNLIKE readLease, AN UNREADABLE FILE IS NOT RETHROWN HERE. The asymmetry is
+ * deliberate and rests on what each answer authorizes. readLease's answer gates
+ * ADMISSION to a tab, so "unreadable" reading as "unleased" would hand a held
+ * tab to a stranger, and failing the call is the lesser harm. This answer gates
+ * nothing: it decorates a listing. Failing list_pages because one provenance
+ * file is unreadable would break a working tool over a cosmetic field. The
+ * honesty requirement is met a different way, by listOrigins, which reports an
+ * unreadable row rather than omitting it, so "unreadable" never silently reads
+ * as "no record". Callers that need that distinction use listOrigins, not this.
+ */
+export async function readOrigin(backend: LeaseBackend, targetId: string): Promise<OriginRecord | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(originFile(backend, targetId), "utf8");
+  } catch {
+    return undefined;
+  }
+  try {
+    const rec = JSON.parse(raw) as OriginRecord;
+    if (typeof rec?.targetId === "string" && typeof rec?.label === "string" && typeof rec?.createdAt === "number") return rec;
+  } catch {
+    /* unparseable: see listOrigins, which surfaces it as an unreadable row */
+  }
+  return undefined;
+}
+
+export interface OriginSummary {
+  backend: LeaseBackend;
+  targetId: string;
+  label: string;
+  pid: number;
+  createdAt: number;
+  /**
+   * Present ONLY on a row this function could not read: the errno of the failed
+   * read, or "unparseable" for a file whose contents are not an origin record.
+   * Same convention, and the same reason, as LeaseSummary.unreadable: a
+   * silently skipped file is the one thing that makes a broken record
+   * impossible to diagnose, and it would make a tab that HAS a record read as
+   * a clean "no record at all". Every other field on such a row is a
+   * placeholder derived from the FILENAME and nothing else.
+   */
+  unreadable?: string;
+}
+
+/**
+ * Enumerate the ledger, dropping records for targets the browser no longer has.
+ *
+ * `liveIds` is the reap set and is optional on purpose. When it is undefined
+ * nothing is reaped: a caller that could not enumerate the browser's targets
+ * must not be able to delete the ledger by failing. Passing an EMPTY array is
+ * a real statement ("the browser has no targets") and does reap.
+ *
+ * `liveBackend` scopes the reap to the browser those ids came from, exactly as
+ * listLeases does: a Chrome target list says nothing about whether a Firefox
+ * context is still open, and reaping on it would delete live Firefox records.
+ */
+export async function listOrigins(
+  opts: { liveIds?: readonly string[]; liveBackend?: LeaseBackend } = {},
+): Promise<OriginSummary[]> {
+  let names: string[] = [];
+  try {
+    names = await readdir(leaseDir());
+  } catch {
+    // Unlike listLeases, an unreadable directory is reported as an empty
+    // ledger rather than thrown: every consumer of this list degrades to
+    // origin "unknown", which is the honest answer when provenance cannot be
+    // read, and no caller of this function is making an authorization decision.
+    return [];
+  }
+  const live = opts.liveIds === undefined ? undefined : new Set(opts.liveIds.map((id) => safeId(id)));
+  const out: OriginSummary[] = [];
+  for (const name of names) {
+    const parts = ORIGIN_FILE_RE.exec(name);
+    if (!parts) continue;
+    const backend = parts[1] as LeaseBackend;
+    const nameId = parts[2] as string;
+    // The reap test runs on the FILENAME id, which is the only id an unreadable
+    // row has. safeId() is applied to both sides so the comparison is like for
+    // like; an id that safeId rewrote is an identifying label, not a key, so a
+    // collision would at worst spare a record from reaping.
+    const scoped = live !== undefined && (opts.liveBackend === undefined || opts.liveBackend === backend);
+    if (scoped && !live.has(nameId)) {
+      await unlink(join(leaseDir(), name)).catch(() => undefined);
+      continue;
+    }
+    const fromName: OriginSummary = { backend, targetId: nameId, label: "", pid: 0, createdAt: 0 };
+    let rec: OriginRecord;
+    try {
+      rec = JSON.parse(await readFile(join(leaseDir(), name), "utf8")) as OriginRecord;
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      // Vanished between readdir and readFile: reaped by a concurrent reader.
+      if (code === "ENOENT") continue;
+      out.push({ ...fromName, unreadable: code ?? "unparseable" });
+      continue;
+    }
+    if (typeof rec?.targetId !== "string" || typeof rec?.label !== "string" || typeof rec?.createdAt !== "number") {
+      out.push({ ...fromName, unreadable: "unparseable" });
+      continue;
+    }
+    out.push({ backend: rec.backend, targetId: rec.targetId, label: rec.label, pid: rec.pid, createdAt: rec.createdAt });
+  }
+  return out;
+}
+
+/**
+ * listOrigins keyed by targetId, for annotating a page listing.
+ *
+ * NEVER THROWS. The whole annotation is best-effort: a caller that cannot read
+ * the ledger reports every page as origin "unknown", which is what a consumer
+ * with no ledger at all has always seen. An empty map and a missing ledger are
+ * the same thing to the caller by construction.
+ */
+export async function originIndex(
+  backend: LeaseBackend,
+  liveIds?: readonly string[],
+): Promise<Map<string, OriginSummary>> {
+  const rows = await listOrigins({ liveIds, liveBackend: backend }).catch(() => [] as OriginSummary[]);
+  const index = new Map<string, OriginSummary>();
+  for (const row of rows) {
+    if (row.backend !== backend) continue;
+    index.set(row.targetId, row);
+  }
+  return index;
+}
+
+/**
+ * Open a tab AND record its provenance. THE ONLY WAY THE TOOLKIT SHOULD CREATE
+ * A PAGE. Both creation paths (new_page in shared-tools.ts, claim_page opening
+ * a fresh tab in leases-tools.ts) route through here so a third path added
+ * later cannot forget the ledger write by omission: `driver.newPage(` should
+ * appear in exactly one place outside the drivers themselves, which is here.
+ */
+export async function newTrackedPage(
+  driver: BrowserDriver,
+  backend: LeaseBackend,
+  opts: { url?: string; label?: string } = {},
+): Promise<PageInfo> {
+  const page = await driver.newPage(opts.url);
+  await recordOrigin(backend, page.id, { label: opts.label });
+  return page;
+}