@farmslot/adapter-web 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,11 @@ All notable changes to `@farmslot/adapter-web` are tracked here.
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
+## 0.2.0 - 2026-10-05
+
+- Add `launch-browser` (`launchBrowser`: launch or release one isolated, detached, owned Chromium with an unpacked extension; `homeTabsToClose`) and `slot-title` (stamp the farm slot id into the extension home tab's title), moved from `@deeeed/metamask-harness`. Product knowledge is now passed in: the home page, its default title, the owner-root rule, a lock held for the launch, and the rerun command named in hints. `slot-title`'s `applyPersistentSlotTitle` takes `{ slotId, defaultTitle }`, `buildStampExpression(slotId, defaultTitle)` and `stampHomeTabsViaCdp({ homePage, defaultTitle, ... })` match it, and CDP stamping uses the global `WebSocket` (else `ws`), loaded only when it stamps.
+- README: document the `browser-resolver.cjs` command (`resolve`, `load-unpacked`, `open-window`): arguments, output, exit codes and the 120 s bound.
+
 ## 0.1.0 - 2026-10-04
 
 - Add the package with the browser process and CDP layer moved from `@deeeed/metamask-harness`, unchanged in behaviour: `browser-resolver` (Chrome for Testing vs branded Chrome, probe cache, `runCli` entry), `browser-cdp` (deadline-bound browser CDP client, CDP-port ownership proof, `Extensions.loadUnpacked`, extension isolation), `chrome-args` (remote-debugging flags, runtime identity nonce, launch quarantine), `extension-id`, `macos-focus`, `playwright-cdp` (LavaMoat-safe page evaluation), `validation-process-ownership` and `validation-launch-supervisor`. Process, on-disk and environment names are Farmslot's: `--farmslot-runtime-nonce=`, `.farmslot-detached-launch-unproven`, `/tmp/farmslot-browser-validation-<uid>`, `~/.cache/farmslot/browser-probe.json`, `farmslot-browser-probe-*`, `FARMSLOT_FOCUS_HOLD`, `FARMSLOT_FOCUS_BROWSER` and `FARMSLOT_VALIDATION_PORT_LEASE`; remediation hints name no product command.

package/README.md

@@ -18,14 +18,50 @@ Docs: https://farmslot.io/docs/reference/adapter-web
 | `browser-cdp`                  | browser-level CDP client with deadlines, CDP-port ownership proof, `Extensions.loadUnpacked`, window placement |
 | `chrome-args`                  | remote-debugging flags, isolated profile flags, runtime identity nonce, launch quarantine markers              |
 | `extension-id`                 | Chromium extension id from a manifest key or an unpacked directory                                             |
+| `launch-browser`               | launch (or release) one isolated, detached, owned Chromium with an unpacked extension                          |
 | `macos-focus`                  | capture the frontmost app before a headed launch and restore it if one of our browsers took it                 |
 | `page-target`                  | pick the page on an origin, preferring one whose URL carries a hash                                            |
 | `playwright-cdp`               | page evaluation over a raw CDP session (safe under LavaMoat scuttling)                                         |
+| `slot-title`                   | prefix the extension home tab's title with the farm slot id, kept across the page's own title resets           |
 | `validation-process-ownership` | find and stop the processes that own a slot profile                                                            |
 | `validation-launch-supervisor` | supervised child for one validation launch: port lease, quarantine and cleanup                                 |
 
 Sources are CommonJS (`src/*.cjs`) and ship as is; `yarn build` emits `.d.cts` declarations. Every library subpath can be `require`d or `import`ed with named imports, except `validation-launch-supervisor`: it is a child-process entry (it runs when loaded), so hosts `require.resolve` it and fork it.
 
+## Launching a browser
+
+`launchBrowser` is synchronous and owns one launch end to end: it refuses a CDP port held by a process it cannot prove is its own, stops the previous owned browser of the profile, starts the browser detached (on macOS through Launch Services in the background), loads the extension, records the resolution and runtime identity under `runtimeDir`, and gives the front back if the new browser took it. `stopOnly: true` does only the release part.
+
+```js
+const { launchBrowser } = require('@farmslot/adapter-web/launch-browser');
+
+launchBrowser({
+  cdpPort: 9333,
+  chromeBin,
+  profile: `${runtimeDir}/profile`,
+  extensionDir: `${runtimeDir}/runtime-dist`,
+  runtimeDir,
+  chromeLog: `${runtimeDir}/logs/chrome.log`,
+  chromePid: `${runtimeDir}/logs/chrome.pid`,
+  // Product knowledge comes from the host:
+  homePage: 'home.html', // opened first, kept to one tab
+  defaultTitle: 'My Extension', // the page's own title; a slot-stamped tab is the one kept
+  acquireRuntimeLock: (dir) => lockBuild(dir), // returns its release
+  extensionOwnerRoot: (dir) => ownerRootFor(dir), // another way to prove a browser is ours
+  rerunCommand: 'my-harness launch',
+});
+```
+
+## Resolver CLI
+
+`browser-resolver.cjs` is also a command, for hosts that need a bounded child process (a hung CDP call can't stall the caller). Every command finishes within 120 s, exits 0 on success and 1 with the error message on stderr otherwise. Hosts can keep their own script path by calling `runCli(argv)`.
+
+| command                                                                                                                                               | output                                                                                                                               |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `resolve [--target <checkout>] [--launch-method spawn\|launch-services] [--display headless\|headful] [--recorded <file>] [--out <file>]... [--json]` | stdout: the browser path, or the resolution record with `--json`; each `--out` gets the record; stderr: one `[browser]` summary line |
+| `load-unpacked --port <cdp> --path <dist> --profile <dir> [--expect-id <id>] [--open-url <url>] [--timeout-ms <ms>]`                                  | stdout: one JSON line `{ id, otherExtensions, owner }`                                                                               |
+| `open-window --port <cdp> --url <url>`                                                                                                                | stdout: one JSON line `{ targetId }` for a new background window                                                                     |
+
 ## Maintenance rules
 
 1. No product knowledge. A product's build locks, titles, fixtures and wallet state stay in its harness and reach these modules as arguments.

package/dist/launch-browser.d.cts

@@ -0,0 +1,106 @@
+export type LaunchBrowserOptions = {
+    cdpPort: number;
+    chromeBin: string;
+    profile: string;
+    /**
+     * Unpacked extension to load.
+     */
+    extensionDir: string;
+    /**
+     * Holds browser-resolution.json and the runtime identity.
+     */
+    runtimeDir: string;
+    chromeLog: string;
+    chromePid: string;
+    /**
+     * Resolver record for this launch; reused when it names `chromeBin`.
+     */
+    browserResolution?: string | undefined;
+    /**
+     * First tab; defaults to the extension's `homePage`, else chrome://extensions/.
+     */
+    startUrl?: string | undefined;
+    /**
+     * Release the profile (owned browser stopped, singleton locks cleared) without launching.
+     */
+    stopOnly?: boolean | undefined;
+    /**
+     * Recreate the profile; it must be a dedicated child of `runtimeDir`.
+     */
+    resetProfile?: boolean | undefined;
+    /**
+     * Extension page (e.g. `home.html`) opened at start and kept to one tab.
+     */
+    homePage?: string | undefined;
+    /**
+     * That page's own title: a home tab with any other title (a slot-stamped one) is the one kept.
+     */
+    defaultTitle?: string | undefined;
+    /**
+     * Path prefix whose `--load-extension=` also proves a browser is ours.
+     */
+    extensionOwnerRoot?: ((extensionDir: string) => string | null) | undefined;
+    /**
+     * Taken once the profile, log and pid directories exist, before any browser is stopped or started; the returned release runs when the launch returns or throws.
+     */
+    acquireRuntimeLock?: ((runtimeDir: string) => () => void) | undefined;
+    /**
+     * Command named in "Next:" hints.
+     */
+    rerunCommand?: string | undefined;
+    /**
+     * macOS: wait before the one focus check (default 1000).
+     */
+    focusSettleMs?: number | undefined;
+    /**
+     * Progress lines (default stderr).
+     */
+    log?: ((line: string) => void) | undefined;
+};
+/**
+ * @typedef {object} LaunchBrowserOptions
+ * @property {number} cdpPort
+ * @property {string} chromeBin
+ * @property {string} profile
+ * @property {string} extensionDir Unpacked extension to load.
+ * @property {string} runtimeDir Holds browser-resolution.json and the runtime identity.
+ * @property {string} chromeLog
+ * @property {string} chromePid
+ * @property {string} [browserResolution] Resolver record for this launch; reused when it names `chromeBin`.
+ * @property {string} [startUrl] First tab; defaults to the extension's `homePage`, else chrome://extensions/.
+ * @property {boolean} [stopOnly] Release the profile (owned browser stopped, singleton locks cleared) without launching.
+ * @property {boolean} [resetProfile] Recreate the profile; it must be a dedicated child of `runtimeDir`.
+ * @property {string} [homePage] Extension page (e.g. `home.html`) opened at start and kept to one tab.
+ * @property {string} [defaultTitle] That page's own title: a home tab with any other title (a slot-stamped one) is the one kept.
+ * @property {(extensionDir: string) => string | null} [extensionOwnerRoot] Path prefix whose `--load-extension=` also proves a browser is ours.
+ * @property {(runtimeDir: string) => () => void} [acquireRuntimeLock] Taken once the profile, log and pid directories exist, before any browser is stopped or started; the returned release runs when the launch returns or throws.
+ * @property {string} [rerunCommand] Command named in "Next:" hints.
+ * @property {number} [focusSettleMs] macOS: wait before the one focus check (default 1000).
+ * @property {(line: string) => void} [log] Progress lines (default stderr).
+ */
+/**
+ * @param {LaunchBrowserOptions} options
+ * @returns {{ stopped: true } | { stopped: false, pid: number }}
+ */
+export function launchBrowser(options: LaunchBrowserOptions): {
+    stopped: true;
+} | {
+    stopped: false;
+    pid: number;
+};
+/**
+ * The page targets to close so one `homePage` tab of the extension remains and no
+ * disposable blank/new-tab page is left. The kept home tab is the first whose
+ * title is set and differs from `defaultTitle` (a slot-stamped tab), else the first.
+ * @param {unknown[]} targets CDP /json/list entries.
+ * @param {{ extensionId: string, homePage: string, defaultTitle?: string }} options
+ * @returns {{ id: string, url: string }[]}
+ */
+export function homeTabsToClose(targets: unknown[], { extensionId, homePage, defaultTitle }: {
+    extensionId: string;
+    homePage: string;
+    defaultTitle?: string;
+}): {
+    id: string;
+    url: string;
+}[];

package/dist/slot-title.d.cts

@@ -0,0 +1,49 @@
+/**
+ * @param {unknown} value
+ * @returns {string} The trimmed slot id, or '' when it is not a safe id.
+ */
+export function sanitizeSlotId(value: unknown): string;
+/**
+ * Slot id from RECIPE_SLOT_ID / SLOT_ID / FARMSLOT_SLOT_ID, else from
+ * `<target>/<runtimeDir>/agentic-runtime.json`; '' outside a farm slot.
+ * @param {string} [target]
+ * @param {string} [runtimeDir]
+ * @returns {string}
+ */
+export function readSlotId(target?: string, runtimeDir?: string): string;
+/**
+ * Serialized page-evaluation callback. Must stay a plain function (no closure).
+ * `defaultTitle` is the page's own title (as in launchBrowser), used when the document has none.
+ * @param {{ slotId: string, defaultTitle?: string }} options
+ * @returns {string}
+ */
+export function applyPersistentSlotTitle({ slotId, defaultTitle }: {
+    slotId: string;
+    defaultTitle?: string;
+}): string;
+/**
+ * @param {string} slotId
+ * @param {string} [defaultTitle]
+ * @returns {string}
+ */
+export function buildStampExpression(slotId: string, defaultTitle?: string): string;
+/**
+ * Stamp every inspectable `homePage` tab of this extension over CDP.
+ * Attached tabs (no webSocketDebuggerUrl) are skipped — another client owns them.
+ * @param {{ cdpPort: number, extensionId: string, homePage: string, defaultTitle?: string, slotId?: string, target?: string, runtimeDir?: string }} options
+ * @returns {Promise<{ slotId: string, stamped: number, skipped: number, titles: string[] }>}
+ */
+export function stampHomeTabsViaCdp(options: {
+    cdpPort: number;
+    extensionId: string;
+    homePage: string;
+    defaultTitle?: string;
+    slotId?: string;
+    target?: string;
+    runtimeDir?: string;
+}): Promise<{
+    slotId: string;
+    stamped: number;
+    skipped: number;
+    titles: string[];
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/adapter-web",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Web platform adapter for Farmslot recipes: resolve and launch an isolated Chromium, own its CDP port, load unpacked extensions, and keep macOS focus.",
   "type": "commonjs",
   "exports": {
@@ -20,10 +20,15 @@
       "types": "./dist/extension-id.d.cts",
       "default": "./src/extension-id.cjs"
     },
+    "./launch-browser": {
+      "types": "./dist/launch-browser.d.cts",
+      "default": "./src/launch-browser.cjs"
+    },
     "./macos-focus": {
       "types": "./dist/macos-focus.d.cts",
       "default": "./src/macos-focus.cjs"
     },
+    "./package.json": "./package.json",
     "./page-target": {
       "types": "./dist/page-target.d.cts",
       "default": "./src/page-target.cjs"
@@ -32,6 +37,10 @@
       "types": "./dist/playwright-cdp.d.cts",
       "default": "./src/playwright-cdp.cjs"
     },
+    "./slot-title": {
+      "types": "./dist/slot-title.d.cts",
+      "default": "./src/slot-title.cjs"
+    },
     "./validation-launch-supervisor": {
       "types": "./dist/validation-launch-supervisor.d.cts",
       "default": "./src/validation-launch-supervisor.cjs"
@@ -39,8 +48,7 @@
     "./validation-process-ownership": {
       "types": "./dist/validation-process-ownership.d.cts",
       "default": "./src/validation-process-ownership.cjs"
-    },
-    "./package.json": "./package.json"
+    }
   },
   "scripts": {
     "typecheck": "tsc --noEmit --project tsconfig.json && yarn build && tsc --project tsconfig.consumer.json",

package/src/launch-browser.cjs

@@ -0,0 +1,718 @@
+'use strict';
+// launch-browser.cjs — per-instance isolated detached Chrome launch
+//
+// Starts a detached Chrome bound to 127.0.0.1:<cdpPort> with its own profile and
+// an unpacked extension loaded: by --load-extension, or over CDP
+// (Extensions.loadUnpacked) for branded Chrome, which ignores that flag. The
+// browser choice comes from the resolver record (`browserResolution`) when it
+// names `chromeBin`.
+//
+// Writes: the pid file, an append-only Chrome log, and under `runtimeDir` the
+// resolution record (browser-resolution.json) and the runtime identity. Never
+// touches the extension dir (read-only) or anything outside the paths it is given.
+//
+// Product knowledge comes from the caller: the extension page to open
+// (`homePage`), that page's own title (`defaultTitle`), how to recognise an
+// owned browser by its extension path (`extensionOwnerRoot`), a lock held for
+// the whole launch (`acquireRuntimeLock`), and the rerun command for hints.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync, spawn, spawnSync } = require('node:child_process');
+
+const { cdpListenerPids } = require('./browser-cdp.cjs');
+const {
+  CDP_LOAD_UNPACKED,
+  describeBrowser,
+  extensionLaunchArgs,
+  waitForCdpOwner,
+} = require('./browser-resolver.cjs');
+const {
+  automationRuntimeArgs,
+  clearDetachedLaunchUnproven,
+  clearValidationPortQuarantine,
+  createRuntimeIdentityNonce,
+  hasDetachedLaunchUnproven,
+  isolatedProfileArgs,
+  markDetachedLaunchUnproven,
+  markValidationPortLaunchUnproven,
+  readValidationPortQuarantine,
+  remoteDebuggingArgs,
+  removeRuntimeIdentity,
+  runtimeIdentityArgs,
+  validationLaunchQuarantineError,
+  writeRuntimeIdentity,
+} = require('./chrome-args.cjs');
+const { extensionIdFromExtensionDir } = require('./extension-id.cjs');
+const {
+  captureMacFrontmost,
+  macBackgroundOpenArgs,
+  restoreFrontmostIfOurs,
+} = require('./macos-focus.cjs');
+const {
+  profileProcessPids,
+  stopProfileProcessesSync,
+} = require('./validation-process-ownership.cjs');
+
+// The resolver CLI runs as a bounded child for CDP calls the launch must not hang on.
+const BROWSER_RESOLVER_CLI = require.resolve('./browser-resolver.cjs');
+
+/**
+ * @typedef {object} LaunchBrowserOptions
+ * @property {number} cdpPort
+ * @property {string} chromeBin
+ * @property {string} profile
+ * @property {string} extensionDir Unpacked extension to load.
+ * @property {string} runtimeDir Holds browser-resolution.json and the runtime identity.
+ * @property {string} chromeLog
+ * @property {string} chromePid
+ * @property {string} [browserResolution] Resolver record for this launch; reused when it names `chromeBin`.
+ * @property {string} [startUrl] First tab; defaults to the extension's `homePage`, else chrome://extensions/.
+ * @property {boolean} [stopOnly] Release the profile (owned browser stopped, singleton locks cleared) without launching.
+ * @property {boolean} [resetProfile] Recreate the profile; it must be a dedicated child of `runtimeDir`.
+ * @property {string} [homePage] Extension page (e.g. `home.html`) opened at start and kept to one tab.
+ * @property {string} [defaultTitle] That page's own title: a home tab with any other title (a slot-stamped one) is the one kept.
+ * @property {(extensionDir: string) => string | null} [extensionOwnerRoot] Path prefix whose `--load-extension=` also proves a browser is ours.
+ * @property {(runtimeDir: string) => () => void} [acquireRuntimeLock] Taken once the profile, log and pid directories exist, before any browser is stopped or started; the returned release runs when the launch returns or throws.
+ * @property {string} [rerunCommand] Command named in "Next:" hints.
+ * @property {number} [focusSettleMs] macOS: wait before the one focus check (default 1000).
+ * @property {(line: string) => void} [log] Progress lines (default stderr).
+ */
+
+/**
+ * @param {LaunchBrowserOptions} options
+ * @returns {{ stopped: true } | { stopped: false, pid: number }}
+ */
+function launchBrowser(options) {
+  const opts = normalizeOptions(options);
+  let release = null;
+  try {
+    return runLaunch(opts, () => {
+      if (opts.acquireRuntimeLock) release = opts.acquireRuntimeLock(opts.runtimeDir);
+    });
+  } finally {
+    if (typeof release === 'function') release();
+  }
+}
+
+// The rerun step named in "Next:" hints.
+function rerunHint({ rerunCommand }) {
+  return rerunCommand ? `rerun: ${rerunCommand}` : 'rerun the launch';
+}
+
+function normalizeOptions(options) {
+  const opts = { ...options };
+  if (!Number.isInteger(opts.cdpPort) || opts.cdpPort <= 0)
+    throw new Error(`Invalid --cdp-port: ${opts.cdpPort ?? ''}`);
+  const flags = {
+    chromeBin: 'chrome-bin',
+    profile: 'profile',
+    extensionDir: 'extension-dir',
+    runtimeDir: 'runtime-dir',
+    chromeLog: 'chrome-log',
+    chromePid: 'chrome-pid',
+  };
+  for (const [key, flag] of Object.entries(flags)) {
+    if (!opts[key]) throw new Error(`Missing --${flag}`);
+  }
+  opts.log = opts.log ?? ((line) => process.stderr.write(`${line}\n`));
+  return opts;
+}
+
+function runLaunch(opts, acquireLock) {
+  const { cdpPort, profile, extensionDir, runtimeDir, log } = opts;
+  const rerun = rerunHint(opts);
+  // stopOnly releases the profile before the extension snapshot exists on a first
+  // run, so launch-input validation applies only to a real launch.
+  if (!opts.stopOnly) {
+    if (!fs.existsSync(opts.chromeBin))
+      throw new Error(`Chrome binary not found: ${opts.chromeBin}`);
+    if (!fs.existsSync(path.join(extensionDir, 'manifest.json'))) {
+      throw new Error(
+        `Extension dist manifest not found: ${path.join(extensionDir, 'manifest.json')}`,
+      );
+    }
+  }
+
+  // Isolation guard: a standalone launch must use a per-checkout profile, never a
+  // shared (e.g. ~/.chrome-farmslot) or the OS-default browser profile. Farm dispatch
+  // injects its own already-isolated profile, so this only trips on a genuinely
+  // personal/shared path — protecting the user's browser data.
+  assertIsolatedProfile(profile);
+  if (opts.resetProfile) assertResettableProfile(profile, runtimeDir);
+
+  fs.mkdirSync(profile, { recursive: true });
+  fs.mkdirSync(path.dirname(opts.chromeLog), { recursive: true });
+  fs.mkdirSync(path.dirname(opts.chromePid), { recursive: true });
+  acquireLock();
+
+  const ownedBrowser = (pid) =>
+    processIsOwnedBrowser(pid, profile, extensionDir, opts.extensionOwnerRoot);
+
+  // Ownership guard: only ever take over a CDP endpoint we provably launched. A pid
+  // on this port is ours iff its command line loads our --user-data-dir; anything
+  // else is a browser this harness did not launch (possibly the user's personal
+  // Chrome), so we refuse rather than kill it or attach to it.
+  const listenerPids = cdpListenerPids(cdpPort);
+  const foreignPids = listenerPids.filter((pid) => !ownedBrowser(pid));
+  if (foreignPids.length > 0) {
+    throw new Error(
+      `Refusing to launch on CDP port ${cdpPort}: it is held by a browser this harness did not launch (pid ${foreignPids.join(', ')}). ` +
+        `Next: pick a free --cdp-port, or stop that browser.`,
+    );
+  }
+  const ownedPids = new Set(listenerPids);
+  for (const pid of profileProcessPids(profile)) ownedPids.add(pid);
+  const previousPid = readPidFile(opts.chromePid);
+  if (previousPid !== null && ownedBrowser(previousPid)) ownedPids.add(previousPid);
+  try {
+    removeRuntimeIdentity(runtimeDir);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to invalidate Extension runtime identity under ${runtimeDir}: ${detail}. ` +
+        `Next: remove the invalid runtime identity and fix owner permissions, then ${rerun}`,
+    );
+  }
+  stopProfileProcessesSync(profile, { extraPids: [...ownedPids] });
+  if (opts.resetProfile) {
+    fs.rmSync(profile, { recursive: true, force: true });
+    fs.mkdirSync(profile, { recursive: true });
+  }
+  removeProfileSingletonLocks(profile);
+
+  // stopOnly: release the profile without launching. A caller that writes into
+  // the profile (fixture prefill into LevelDB) needs it unlocked first; a prior
+  // run's Chrome would hold the lock and the write fails.
+  if (opts.stopOnly) return { stopped: true };
+
+  const requestedProfileQuarantined = hasDetachedLaunchUnproven(profile);
+  const portQuarantine = readValidationPortQuarantine(cdpPort);
+  const validationPortLease = process.env.FARMSLOT_VALIDATION_PORT_LEASE;
+  const activeValidationLease = Boolean(
+    portQuarantine?.profile === path.resolve(profile) &&
+    portQuarantine.lease === validationPortLease &&
+    /^[a-f0-9]{64}$/u.test(validationPortLease || ''),
+  );
+  if (requestedProfileQuarantined || (portQuarantine && !activeValidationLease)) {
+    throw validationLaunchQuarantineError(
+      cdpPort,
+      portQuarantine?.profile || (requestedProfileQuarantined ? profile : undefined),
+      requestedProfileQuarantined ? profile : undefined,
+    );
+  }
+  const clearLaunchMarkers = () => {
+    clearDetachedLaunchUnproven(profile);
+    if (!activeValidationLease) clearValidationPortQuarantine(cdpPort, profile);
+  };
+
+  const initialUrl =
+    opts.startUrl || extensionPageUrl(extensionDir, opts.homePage) || 'chrome://extensions/';
+  const browser = launchBrowserResolution(opts.browserResolution, opts.chromeBin);
+  const loadsOverCdp = browser.extensionLoading === CDP_LOAD_UNPACKED;
+  let cdpLoad = null;
+  let owner = null;
+  const runtimeNonce = createRuntimeIdentityNonce();
+  const startedAt = Date.now();
+  const chromeArgs = [
+    `--user-data-dir=${profile}`,
+    // Debug-port trio (address + port + scoped allow-origins) from the shared module,
+    // so the DevTools origin allow-list can never drift away from the port.
+    ...remoteDebuggingArgs(cdpPort),
+    '--no-first-run',
+    '--disable-first-run-ui',
+    ...automationRuntimeArgs(),
+    ...runtimeIdentityArgs(runtimeNonce),
+    ...isolatedProfileArgs(),
+    '--disable-default-apps',
+    '--disable-popup-blocking',
+    '--disable-extensions-file-access-check',
+    '--disable-extensions-content-verification',
+    '--disable-features=ExtensionContentVerification,DisableLoadExtensionCommandLineSwitch',
+    ...extensionLaunchArgs(extensionDir, browser.extensionLoading),
+  ];
+  // Initial tab: the caller's URL when provided, else the extension home. The
+  // extension home avoids leaving disposable chrome://newtab/ or extensions
+  // manager tabs in the operator's slot browser. On macOS the browser starts
+  // through Launch Services in the background with no startup window (Chrome
+  // activates itself when it opens one), and the first window is opened over
+  // CDP as a background window. A CDP-loaded extension does not exist yet at
+  // startup, so its window is opened after the load.
+  const application =
+    process.platform === 'darwin' ? macApplicationForExecutable(opts.chromeBin) : null;
+  if (application) chromeArgs.push('--no-startup-window');
+  else chromeArgs.push(loadsOverCdp ? 'about:blank' : initialUrl);
+  const ownedListenerMissing = () =>
+    new Error(
+      `Chrome launched but did not expose an owned CDP listener on 127.0.0.1:${cdpPort}. ` +
+        `Next: inspect ${opts.chromeLog}, then ${rerun}`,
+    );
+  const logFd = fs.openSync(opts.chromeLog, 'a');
+  const previousFrontmost = captureMacFrontmost();
+  let browserPid;
+  try {
+    try {
+      beginDetachedLaunch(cdpPort, profile, activeValidationLease);
+      if (application) {
+        execFileSync('open', macBackgroundOpenArgs(application, chromeArgs), {
+          env: sanitizedChildEnv(),
+          stdio: ['ignore', logFd, logFd],
+        });
+        browserPid = waitForOwnedCdpPid(cdpPort, ownedBrowser);
+        if (browserPid === null) {
+          stopProfileProcessesSync(profile, { waitForAppearanceMs: 400 });
+          throw ownedListenerMissing();
+        }
+      } else {
+        const child = spawn(opts.chromeBin, chromeArgs, {
+          detached: true,
+          env: sanitizedChildEnv(),
+          stdio: ['ignore', logFd, logFd],
+        });
+        child.unref();
+        browserPid = waitForOwnedCdpPid(cdpPort, ownedBrowser);
+        if (browserPid === null) {
+          stopProfileProcessesSync(profile, { extraPids: child.pid ? [child.pid] : [] });
+          throw ownedListenerMissing();
+        }
+      }
+      if (loadsOverCdp)
+        cdpLoad = loadExtensionOverCdp(opts, browserPid, initialUrl, clearLaunchMarkers);
+      else if (application) openBackgroundWindow(opts, browserPid, initialUrl, clearLaunchMarkers);
+      owner = cdpLoad?.owner ?? ownerIdentity(cdpPort, profile, browserPid, log);
+      for (const problem of pruneExtraHomeTabs(cdpPort, extensionDir, opts)) {
+        log(`[launch] home-tab pruning: ${problem}`);
+      }
+    } finally {
+      fs.closeSync(logFd);
+    }
+    fs.writeFileSync(opts.chromePid, `${browserPid}\n`);
+    writeBrowserResolution(runtimeDir, {
+      ...browser,
+      launch: {
+        pid: browserPid,
+        cdpPort,
+        startedAt: new Date(startedAt).toISOString(),
+        ...(owner ? { profile: owner.profile, processStartedAt: owner.startedAt } : {}),
+        ...(cdpLoad ? { extensionId: cdpLoad.id, otherExtensions: cdpLoad.otherExtensions } : {}),
+      },
+    });
+    try {
+      writeRuntimeIdentity(runtimeDir, {
+        port: cdpPort,
+        pid: browserPid,
+        startedAt,
+        nonce: runtimeNonce,
+      });
+      clearLaunchMarkers();
+    } catch (error) {
+      terminatePids([browserPid]);
+      fs.rmSync(opts.chromePid, { force: true });
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Failed to persist Extension runtime identity under ${runtimeDir}: ${detail}. ` +
+          `Next: fix owner write permissions for the runtime directory, then ${rerun}`,
+      );
+    }
+    if (process.platform === 'darwin') {
+      const wake = spawn('caffeinate', ['-dims', '-w', String(browserPid)], {
+        detached: true,
+        stdio: 'ignore',
+      });
+      wake.unref();
+      // Let the first window settle before the one focus check below.
+      const settleMs =
+        Number.isFinite(opts.focusSettleMs) && opts.focusSettleMs >= 0 ? opts.focusSettleMs : 1000;
+      if (settleMs > 0) spawnSync('sleep', [String(settleMs / 1000)]);
+    }
+  } finally {
+    // One check, at most one restore, and only if OUR browser (this launch's
+    // CDP owner pid) holds the front; any other app in front is left alone.
+    if (browserPid) {
+      const outcome = restoreFrontmostIfOurs(previousFrontmost, [Number(browserPid)]);
+      if (outcome === 'restored')
+        log(`[launch] focus: the slot browser took the front; restored ${previousFrontmost.name}`);
+    }
+  }
+  return { stopped: false, pid: browserPid };
+}
+
+// The first window of a browser started without one, opened in the background.
+// Without it the slot has no window at all, so a failure fails the launch:
+// the owned browser is stopped (its markers kept if it cannot be).
+function openBackgroundWindow(opts, pid, url, clearLaunchMarkers) {
+  const result = spawnSync(
+    process.execPath,
+    [BROWSER_RESOLVER_CLI, 'open-window', '--port', String(opts.cdpPort), '--url', url],
+    { encoding: 'utf8', timeout: 30_000 },
+  );
+  if (result.status === 0) return;
+  const openError = (result.stderr || result.error?.message || `exit ${result.status}`).trim();
+  try {
+    stopProfileProcessesSync(opts.profile, { extraPids: [pid] });
+  } catch (stopError) {
+    throw new Error(
+      `Chrome started but its start window could not be opened (${openError}), and stopping it failed: ${stopError.message}. ` +
+        `The launch markers for port ${opts.cdpPort} and ${opts.profile} are kept. Next: stop pid ${pid}, then ${rerunHint(opts)}`,
+    );
+  }
+  clearLaunchMarkers();
+  throw new Error(
+    `Chrome started but its start window could not be opened: ${openError}. Next: inspect ${opts.chromeLog}, then ${rerunHint(opts)}`,
+  );
+}
+
+// The caller passes the record its resolver just wrote; reuse it when it names
+// the same binary. A direct chromeBin without it is the caller's own explicit
+// choice and is recorded as such, whatever an older record of this profile says.
+function launchBrowserResolution(file, chromeBin) {
+  if (!file) return explicitResolution(chromeBin);
+  try {
+    const recorded = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (recorded && recorded.bin === chromeBin && typeof recorded.extensionLoading === 'string') {
+      const { launch: _previousLaunch, ...resolution } = recorded;
+      return resolution;
+    }
+  } catch {
+    // No resolver record for this launch; fall through to a direct description.
+  }
+  return explicitResolution(chromeBin);
+}
+
+function explicitResolution(chromeBin) {
+  return {
+    schemaVersion: 2,
+    ...describeBrowser(chromeBin),
+    source: '--chrome-bin',
+    mode: 'explicit',
+    selection: 'explicit',
+    resolvedAt: new Date().toISOString(),
+  };
+}
+
+function writeBrowserResolution(runtime, resolution) {
+  fs.writeFileSync(
+    path.join(runtime, 'browser-resolution.json'),
+    `${JSON.stringify(resolution, null, 2)}\n`,
+  );
+}
+
+function loadExtensionOverCdp(opts, pid, initialUrl, clearLaunchMarkers) {
+  const result = spawnSync(
+    process.execPath,
+    [
+      BROWSER_RESOLVER_CLI,
+      'load-unpacked',
+      '--port',
+      String(opts.cdpPort),
+      '--path',
+      opts.extensionDir,
+      '--profile',
+      opts.profile,
+      '--open-url',
+      initialUrl,
+    ],
+    { encoding: 'utf8', timeout: 130_000 },
+  );
+  if (result.status === 0) {
+    const loaded = JSON.parse(result.stdout);
+    opts.log(`[launch] extension ${loaded.id} loaded over CDP`);
+    for (const entry of loaded.otherExtensions?.disabled ?? []) {
+      opts.log(`[launch] disabled ${entry.id} (${entry.name}) in the slot profile`);
+    }
+    for (const entry of loaded.otherExtensions?.policyPinned ?? []) {
+      opts.log(
+        `[launch] WARN: enterprise policy keeps ${entry.id} (${entry.name}) enabled in the slot profile`,
+      );
+    }
+    return loaded;
+  }
+  // Ownership was proven; once the browser is stopped the launch markers would
+  // only quarantine a port and profile that nothing holds. If it cannot be
+  // stopped, the markers stay and both failures are reported.
+  const loadError = (result.stderr || result.error?.message || '').trim();
+  try {
+    stopProfileProcessesSync(opts.profile, { extraPids: [pid] });
+  } catch (stopError) {
+    throw new Error(
+      `Chrome started but the extension did not load over CDP (${loadError}), and stopping it failed: ${stopError.message}. ` +
+        `The launch markers for port ${opts.cdpPort} and ${opts.profile} are kept. Next: stop pid ${pid}, then ${rerunHint(opts)}`,
+    );
+  }
+  clearLaunchMarkers();
+  throw new Error(
+    `Chrome started but the extension did not load over CDP: ${loadError}. ` +
+      `Next: inspect ${opts.chromeLog}, or set RECIPE_HARNESS_BROWSER=cft to use Chrome for Testing, then ${rerunHint(opts)}`,
+  );
+}
+
+// Identity of the browser that holds the profile (pid + start time), recorded
+// so run evidence can later prove it names this exact process.
+// Best effort, so a short budget: a browser that never proves ownership (a
+// stub without a SingletonLock, say) costs seconds, not the full default.
+function ownerIdentity(cdpPort, profile, pid, log) {
+  try {
+    const identity = waitForCdpOwner(cdpPort, profile, { timeoutMs: 15000 });
+    return identity.pid === pid ? identity : null;
+  } catch (error) {
+    log(`[launch] could not record the browser identity: ${error.message}`);
+    return null;
+  }
+}
+
+function sanitizedChildEnv() {
+  return {
+    ...process.env,
+    BUNDLED_DEBUGPY_PATH: undefined,
+    PYTHONHOME: undefined,
+    PYTHONPATH: undefined,
+    DYLD_LIBRARY_PATH: undefined,
+    DYLD_FALLBACK_LIBRARY_PATH: undefined,
+    DYLD_INSERT_LIBRARIES: undefined,
+  };
+}
+
+function beginDetachedLaunch(port, profile, activeLease) {
+  try {
+    if (!activeLease) markValidationPortLaunchUnproven(port, profile);
+    markDetachedLaunchUnproven(profile);
+  } catch (error) {
+    if (error.code === 'EEXIST') {
+      const quarantine = readValidationPortQuarantine(port);
+      throw validationLaunchQuarantineError(port, quarantine?.profile || profile);
+    }
+    throw error;
+  }
+}
+
+function macApplicationForExecutable(executable) {
+  let current = path.resolve(executable);
+  while (current !== path.dirname(current)) {
+    if (current.endsWith('.app')) return current;
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+function waitForOwnedCdpPid(port, ownedBrowser) {
+  for (let i = 0; i < 300; i += 1) {
+    const pid = cdpListenerPids(port).find(ownedBrowser);
+    if (pid !== undefined) return pid;
+    spawnSync('sleep', ['0.1']);
+  }
+  return null;
+}
+
+function assertIsolatedProfile(profile) {
+  const resolved = path.resolve(profile);
+  const home = os.homedir();
+  const osDefaults = [
+    path.join(home, 'Library/Application Support/Google/Chrome'),
+    path.join(home, 'Library/Application Support/Chromium'),
+    path.join(home, 'Library/Application Support/Microsoft Edge'),
+    path.join(home, '.config/google-chrome'),
+    path.join(home, '.config/chromium'),
+    path.join(home, '.config/microsoft-edge'),
+  ];
+  const underDefault = (dir) => resolved === dir || resolved.startsWith(`${dir}${path.sep}`);
+  if (
+    resolved === home ||
+    resolved.includes(`${path.sep}.chrome-farmslot`) ||
+    osDefaults.some(underDefault)
+  ) {
+    throw new Error(
+      `Refusing to launch: --profile ${resolved} is a shared or default browser profile; ` +
+        `standalone launches must use a per-checkout profile under the harness runtime dir.`,
+    );
+  }
+}
+
+function assertResettableProfile(profile, expectedRuntimeDir) {
+  const resolved = path.resolve(profile);
+  const runtime = path.resolve(expectedRuntimeDir);
+  if (!resolved.startsWith(`${runtime}${path.sep}`)) {
+    throw new Error(
+      `Refusing to reset --profile ${resolved}: it must be a dedicated child of ${runtime}.`,
+    );
+  }
+  const runtimeStat = fs.lstatSync(runtime);
+  if (!runtimeStat.isDirectory() || runtimeStat.isSymbolicLink()) {
+    throw new Error(
+      `Refusing to reset --profile: runtime directory is not a regular directory: ${runtime}.`,
+    );
+  }
+  let current = runtime;
+  for (const segment of path.relative(runtime, resolved).split(path.sep)) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) break;
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error(`Refusing to reset --profile: path contains an unsafe entry: ${current}.`);
+    }
+  }
+}
+
+// Proof of ownership: a process is ours iff its command line loads the exact
+// --user-data-dir we launch with, or an extension under the caller's owner root.
+// If the process can't be inspected we treat it as NOT ours (fail safe — never
+// assume ownership of an opaque process).
+function processIsOwnedBrowser(pid, profile, extensionDir, extensionOwnerRoot) {
+  const command = processCommand(pid);
+  if (!command) return false;
+  if (command.includes(`--user-data-dir=${profile}`)) return true;
+  const ownerRoot = extensionOwnerRoot ? extensionOwnerRoot(path.resolve(extensionDir)) : null;
+  return Boolean(ownerRoot && command.includes(`--load-extension=${ownerRoot}`));
+}
+
+function processCommand(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    return execFileSync('ps', ['-ww', '-o', 'command=', '-p', String(pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch {
+    return null;
+  }
+}
+
+function readPidFile(file) {
+  if (!fs.existsSync(file)) return null;
+  const pid = Number.parseInt(fs.readFileSync(file, 'utf8').trim(), 10);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+function terminatePids(pids) {
+  const unique = [...new Set(pids)].filter((pid) => pid !== process.pid);
+  for (const pid of unique) signalPid(pid, 'SIGTERM');
+  for (let i = 0; i < 10 && unique.some(processRespondsToSignal); i += 1) {
+    spawnSync('sleep', ['0.2']);
+  }
+  for (const pid of unique) {
+    if (processRespondsToSignal(pid)) signalPid(pid, 'SIGKILL');
+  }
+}
+
+function signalPid(pid, signal) {
+  try {
+    process.kill(pid, signal);
+    return true;
+  } catch (error) {
+    if (error.code === 'ESRCH') return false;
+    throw error;
+  }
+}
+
+function processRespondsToSignal(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error.code === 'ESRCH') return false;
+    throw error;
+  }
+}
+
+function removeProfileSingletonLocks(profile) {
+  for (const name of ['SingletonLock', 'SingletonSocket', 'SingletonCookie']) {
+    const file = path.join(profile, name);
+    if (fs.existsSync(file)) fs.rmSync(file, { force: true });
+  }
+}
+
+function extensionPageUrl(extensionDir, page) {
+  if (!page) return '';
+  const id = extensionIdFromExtensionDir(extensionDir);
+  return id ? `chrome-extension://${id}/${page}` : '';
+}
+
+function cdpHttp(port, pathname) {
+  const result = spawnSync(
+    process.execPath,
+    [
+      '-e',
+      `
+    const http = require('http');
+    http.get('http://127.0.0.1:${Number(port)}${pathname}', (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        process.stdout.write(body);
+        process.exitCode = res.statusCode === 200 ? 0 : 1;
+      });
+    }).on('error', () => process.exit(1));
+  `,
+    ],
+    { encoding: 'utf8', timeout: 4000 },
+  );
+  if (result.status !== 0) return null;
+  return result.stdout;
+}
+
+/**
+ * The page targets to close so one `homePage` tab of the extension remains and no
+ * disposable blank/new-tab page is left. The kept home tab is the first whose
+ * title is set and differs from `defaultTitle` (a slot-stamped tab), else the first.
+ * @param {unknown[]} targets CDP /json/list entries.
+ * @param {{ extensionId: string, homePage: string, defaultTitle?: string }} options
+ * @returns {{ id: string, url: string }[]}
+ */
+function homeTabsToClose(targets, { extensionId, homePage, defaultTitle }) {
+  const pages = targets.filter(
+    (target) =>
+      target &&
+      target.type === 'page' &&
+      typeof target.id === 'string' &&
+      typeof target.url === 'string',
+  );
+  const homes = pages.filter(
+    (target) =>
+      target.url.startsWith(`chrome-extension://${extensionId}/`) &&
+      target.url.includes(`/${homePage}`),
+  );
+  if (homes.length === 0) return [];
+  const strays = pages.filter(
+    (target) =>
+      target.url === 'about:blank' ||
+      target.url === 'chrome://newtab/' ||
+      target.url.startsWith('chrome://new-tab-page'),
+  );
+  const keeper =
+    homes.find(
+      (target) =>
+        typeof target.title === 'string' &&
+        target.title.trim() !== '' &&
+        target.title.trim() !== defaultTitle,
+    ) ?? homes[0];
+  return [...homes, ...strays]
+    .filter((target) => target.id !== keeper.id)
+    .map((target) => ({ id: target.id, url: target.url }));
+}
+
+// Best effort by design: CDP ownership is already proven and the caller's
+// readiness converges home tabs again, so a pruning failure must not fail the
+// launch. Every failure is returned so the launch log says why a duplicate tab
+// survived instead of hiding it.
+function pruneExtraHomeTabs(port, extensionDir, { homePage, defaultTitle }) {
+  if (!homePage) return [];
+  const extensionId = extensionIdFromExtensionDir(extensionDir);
+  if (!extensionId) return ['extension id unavailable; skipped'];
+  const raw = cdpHttp(port, '/json/list');
+  if (raw === null) return [`GET http://127.0.0.1:${port}/json/list failed`];
+  let targets;
+  try {
+    targets = JSON.parse(raw);
+  } catch (error) {
+    return [`/json/list returned malformed JSON: ${error.message}`];
+  }
+  if (!Array.isArray(targets)) return ['/json/list did not return a target list'];
+  const problems = [];
+  for (const target of homeTabsToClose(targets, { extensionId, homePage, defaultTitle })) {
+    if (cdpHttp(port, `/json/close/${target.id}`) === null)
+      problems.push(`could not close ${target.url} (${target.id})`);
+  }
+  return problems;
+}
+
+module.exports = { launchBrowser, homeTabsToClose };

package/src/slot-title.cjs

@@ -0,0 +1,299 @@
+'use strict';
+
+/**
+ * Operator slot title for headed extension Chrome.
+ *
+ * Chrome's window label is the active tab's document.title. Farmslot stamps the
+ * extension's home page to "<slot-id> — <page title>" so operators can tell
+ * which slot owns a window when several farms run side by side.
+ *
+ * Stamping is best-effort: missing slot context or an uninspectable tab must
+ * never fail launch/readiness. A MutationObserver keeps the prefix across the
+ * page's own (SPA) title resets.
+ */
+
+const fs = require('node:fs');
+const http = require('node:http');
+const path = require('node:path');
+
+/**
+ * @param {unknown} value
+ * @returns {string} The trimmed slot id, or '' when it is not a safe id.
+ */
+function sanitizeSlotId(value) {
+  const slotId = typeof value === 'string' ? value.trim() : '';
+  return /^[A-Za-z0-9._:-]{1,64}$/u.test(slotId) ? slotId : '';
+}
+
+/**
+ * Slot id from RECIPE_SLOT_ID / SLOT_ID / FARMSLOT_SLOT_ID, else from
+ * `<target>/<runtimeDir>/agentic-runtime.json`; '' outside a farm slot.
+ * @param {string} [target]
+ * @param {string} [runtimeDir]
+ * @returns {string}
+ */
+function readSlotId(target, runtimeDir) {
+  for (const key of ['RECIPE_SLOT_ID', 'SLOT_ID', 'FARMSLOT_SLOT_ID']) {
+    const value = sanitizeSlotId(process.env[key]);
+    if (value) return value;
+  }
+  if (!target || !runtimeDir) return '';
+  try {
+    const runtimeContext = JSON.parse(
+      fs.readFileSync(path.join(target, runtimeDir, 'agentic-runtime.json'), 'utf8'),
+    );
+    return sanitizeSlotId(runtimeContext.slotId);
+  } catch {
+    // Standalone harness users do not need a custom browser title.
+    return '';
+  }
+}
+
+/**
+ * Serialized page-evaluation callback. Must stay a plain function (no closure).
+ * `defaultTitle` is the page's own title (as in launchBrowser), used when the document has none.
+ * @param {{ slotId: string, defaultTitle?: string }} options
+ * @returns {string}
+ */
+function applyPersistentSlotTitle({ slotId, defaultTitle = '' }) {
+  // Inline sanitize because the serialized function cannot call Node helpers.
+  const id =
+    typeof slotId === 'string' && /^[A-Za-z0-9._:-]{1,64}$/u.test(slotId.trim())
+      ? slotId.trim()
+      : '';
+  if (!id) return document.title;
+  window.__farmslotSlotId = id;
+  window.__farmslotSlotDefaultTitle = String(defaultTitle || '');
+
+  const stripSlotPrefixes = (title) => {
+    const ownTitle = window.__farmslotSlotDefaultTitle;
+    let base = String(title || ownTitle);
+    // Accept em dash, en dash, or hyphen — historical stampers mixed them.
+    for (let i = 0; i < 32; i += 1) {
+      const stripped = base.replace(/^.+?\s+[—–-]\s+/u, '');
+      if (stripped === base) break;
+      base = stripped;
+    }
+    return base || ownTitle;
+  };
+
+  const desiredTitle = () => {
+    const id = window.__farmslotSlotId;
+    if (!id) return document.title;
+    const base = stripSlotPrefixes(document.title);
+    if (base && base !== id) return `${id} — ${base}`;
+    // A bare id is this stamp's own output for an untitled page: never prefix it
+    // with itself, but complete it once the page title is known.
+    const ownTitle = window.__farmslotSlotDefaultTitle;
+    return ownTitle ? `${id} — ${ownTitle}` : id;
+  };
+
+  const setTitle = () => {
+    if (window.__farmslotSlotTitleLock) {
+      window.__farmslotSlotTitlePending = true;
+      return;
+    }
+    const next = desiredTitle();
+    if (document.title === next) return;
+    window.__farmslotSlotTitleLock = true;
+    try {
+      document.title = next;
+    } finally {
+      // Release after the title mutation is delivered so the observer cannot
+      // re-enter and stack prefixes while React also mutates the DOM. If a
+      // mutation arrived while locked, re-apply once after unlock.
+      queueMicrotask(() => {
+        window.__farmslotSlotTitleLock = false;
+        if (window.__farmslotSlotTitlePending) {
+          window.__farmslotSlotTitlePending = false;
+          setTitle();
+        }
+      });
+    }
+  };
+
+  setTitle();
+  if (!window.__farmslotSlotTitleObserver) {
+    let node = document.querySelector('title');
+    if (!node) {
+      node = document.createElement('title');
+      (document.head || document.documentElement).appendChild(node);
+    }
+    window.__farmslotSlotTitleObserver = new MutationObserver(setTitle);
+    // Observe only the <title> element — watching head/documentElement with
+    // subtree:true re-fires on every React DOM mutation and can livelock CDP.
+    window.__farmslotSlotTitleObserver.observe(node, {
+      childList: true,
+      characterData: true,
+      subtree: true,
+    });
+  }
+  return document.title;
+}
+
+/**
+ * @param {string} slotId
+ * @param {string} [defaultTitle]
+ * @returns {string}
+ */
+function buildStampExpression(slotId, defaultTitle = '') {
+  const slot = sanitizeSlotId(slotId);
+  if (!slot) return 'document.title';
+  // Single source of truth: serialize the Playwright callback for CDP evaluate.
+  const argument = JSON.stringify({ slotId: slot, defaultTitle: String(defaultTitle) });
+  return `(${applyPersistentSlotTitle.toString()})(${argument})`;
+}
+
+function assertLocalUrl(url) {
+  if (!/^http:\/\/127\.0\.0\.1:\d+\//u.test(url)) {
+    throw new Error(`slot-title: refusing non-local URL: ${url}`);
+  }
+}
+
+function assertLocalWebSocketUrl(url) {
+  if (!/^ws:\/\/(?:127\.0\.0\.1|localhost):\d+\//u.test(String(url))) {
+    throw new Error(`slot-title: refusing non-local websocket URL: ${url}`);
+  }
+}
+
+function httpJson(url, timeoutMs = 3000) {
+  assertLocalUrl(url);
+  return new Promise((resolve, reject) => {
+    const req = http.get(url, (res) => {
+      let data = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch (err) {
+          reject(new Error(`invalid JSON from ${url}: ${err.message}`));
+        }
+      });
+    });
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`timeout from ${url}`));
+    });
+    req.on('error', reject);
+  });
+}
+
+async function cdpEvaluate(webSocketDebuggerUrl, expression, timeoutMs = 5000) {
+  assertLocalWebSocketUrl(webSocketDebuggerUrl);
+  return new Promise((resolve, reject) => {
+    // Loaded only here, so the slot-id helpers work where `ws` is not installed.
+    const WebSocketImpl = globalThis.WebSocket ?? require('ws');
+    const ws = new WebSocketImpl(webSocketDebuggerUrl);
+    const timer = setTimeout(() => {
+      try {
+        ws.close();
+      } catch {
+        // Best-effort timeout cleanup.
+      }
+      reject(new Error('timeout evaluating extension page via CDP'));
+    }, timeoutMs);
+    const onOpen = () => {
+      ws.send(
+        JSON.stringify({
+          id: 1,
+          method: 'Runtime.evaluate',
+          params: { expression, awaitPromise: true, returnByValue: true },
+        }),
+      );
+    };
+    const onMessage = (event) => {
+      const raw = event?.data ?? event;
+      const msg = JSON.parse(Buffer.isBuffer(raw) ? raw.toString('utf8') : String(raw));
+      if (msg.id !== 1) return;
+      clearTimeout(timer);
+      ws.close();
+      if (msg.error) {
+        reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+        return;
+      }
+      resolve(msg.result?.result?.value ?? null);
+    };
+    const onError = (err) => {
+      clearTimeout(timer);
+      reject(
+        new Error(
+          `CDP websocket error while stamping slot title: ${err?.message || err?.error?.message || err?.type || 'unknown'}`,
+        ),
+      );
+    };
+    ws.addEventListener('open', onOpen);
+    ws.addEventListener('message', onMessage);
+    ws.addEventListener('error', onError);
+  });
+}
+
+function isHomePage(target, extensionId, homePage) {
+  if (!target || target.type !== 'page' || typeof target.url !== 'string') return false;
+  if (!target.url.startsWith(`chrome-extension://${extensionId}/`)) return false;
+  return target.url.includes(`/${homePage}`);
+}
+
+/**
+ * Stamp every inspectable `homePage` tab of this extension over CDP.
+ * Attached tabs (no webSocketDebuggerUrl) are skipped — another client owns them.
+ * @param {{ cdpPort: number, extensionId: string, homePage: string, defaultTitle?: string, slotId?: string, target?: string, runtimeDir?: string }} options
+ * @returns {Promise<{ slotId: string, stamped: number, skipped: number, titles: string[] }>}
+ */
+async function stampHomeTabsViaCdp(options) {
+  const {
+    target = process.cwd(),
+    cdpPort,
+    extensionId,
+    homePage,
+    defaultTitle = '',
+    slotId: slotIdOption,
+    runtimeDir,
+  } = options || {};
+  const slotId = sanitizeSlotId(slotIdOption) || readSlotId(target, runtimeDir);
+  const empty = { slotId: slotId || '', stamped: 0, skipped: 0, titles: [] };
+  if (!slotId || !cdpPort || !extensionId || !homePage) return empty;
+
+  let targets;
+  try {
+    targets = await httpJson(`http://127.0.0.1:${cdpPort}/json/list`);
+  } catch {
+    return empty;
+  }
+  if (!Array.isArray(targets)) return empty;
+
+  const homes = targets.filter((t) => isHomePage(t, extensionId, homePage));
+  const titles = [];
+  let stamped = 0;
+  let skipped = 0;
+  const expression = buildStampExpression(slotId, defaultTitle);
+
+  for (const home of homes) {
+    if (typeof home.webSocketDebuggerUrl !== 'string') {
+      skipped += 1;
+      continue;
+    }
+    try {
+      const title = await cdpEvaluate(home.webSocketDebuggerUrl, expression);
+      if (typeof title === 'string') {
+        titles.push(title);
+        stamped += 1;
+      } else {
+        skipped += 1;
+      }
+    } catch {
+      skipped += 1;
+    }
+  }
+
+  return { slotId, stamped, skipped, titles };
+}
+
+module.exports = {
+  sanitizeSlotId,
+  readSlotId,
+  applyPersistentSlotTitle,
+  buildStampExpression,
+  stampHomeTabsViaCdp,
+};