Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

92.3 KB
Raw Blame
#!/usr/bin/env node
/**
 * Deterministic multi-source vendoring sync for the neutral browser-control runtime.
 *
 * Sources (all version-pinned in browser-runtime.lock.json):
 *   1. extensions/browser/src/**          (GitHub tarball @ commit)  -> _generated/extension/
 *   2. packages/net-policy/src/**         (GitHub tarball, unpublished pkg) -> _generated/packages/net-policy/
 *   3. packages/normalization-core/src/** (GitHub tarball, unpublished pkg) -> _generated/packages/normalization-core/
 *   4. SSRF/security leaf closure under src/infra/** + src/security/** + src/config/zod-schema.* (tarball)
 *                                          -> _generated/leaf/
 *   5. @openclaw/fs-safe@<ver> npm dist    (NOT in repo; published) -> _generated/vendor/fs-safe/
 *
 * Import rewriting (mechanical, deterministic):
 *   - `openclaw/plugin-sdk/<x>`         -> ../shim/<x>.js              (hand-written shim)
 *   - `@openclaw/net-policy[/x]`        -> _generated/packages/net-policy/...
 *   - `@openclaw/normalization-core/x`  -> _generated/packages/normalization-core/x.js
 *   - `@openclaw/fs-safe[/x]`           -> _generated/vendor/fs-safe/dist/...
 *   - bare `from "../../config/zod-schema.proxy.js"` etc inside leaf closure stay relative
 *     because the leaf closure preserves the upstream src/ subtree shape under _generated/leaf/src/.
 *
 * _generated/ is GENERATED — do not edit. Edit src/shim/* or this script.
 *
 * Neutrality: upstream project name appears only here + in upstream/ metadata.
 */
import { execFileSync } from 'node:child_process';
import crypto from 'node:crypto';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { resolvePosixShell } from '../lib/posix-shell.mjs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const repoRoot = path.resolve(__dirname, '../..');
const pkgRoot = path.join(repoRoot, 'packages/browser-control-runtime');
const lockPath = path.join(pkgRoot, 'upstream/browser-runtime.lock.json');
const manifestPath = path.join(pkgRoot, 'upstream/vendor-manifest.txt');
const genRoot = path.join(pkgRoot, 'src/_generated');
const shimDir = path.join(pkgRoot, 'src/shim');

const readJson = (f) => JSON.parse(fs.readFileSync(f, 'utf8'));
const writeJson = (f, v) => {
  fs.writeFileSync(`${f}.tmp`, `${JSON.stringify(v, null, 2)}\n`);
  fs.renameSync(`${f}.tmp`, f);
};
const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
function parseGithubRepo(url) {
  const m = String(url).match(/^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/);
  if (!m) throw new Error(`Unsupported repo URL: ${url}`);
  return `${m[1]}/${m[2]}`;
}
function resolveRef(repoSlug, ref) {
  return execFileSync('gh', ['api', `repos/${repoSlug}/commits/${ref}`, '--jq', '.sha'], {
    encoding: 'utf8',
    stdio: ['ignore', 'pipe', 'inherit'],
  }).trim();
}
/** Whether the `tar` on PATH is GNU tar (msys/GNU accept `--wildcards`;
 * bsdtar/libarchive — the Windows/macOS system default — rejects it). */
let gnuTarChecked = false;
let gnuTar = false;
function isGnuTar() {
  if (!gnuTarChecked) {
    gnuTarChecked = true;
    try {
      // Probe tar in the SAME environment that will execute it: on win32 the
      // Node process PATH may resolve `tar` to System32\bsdtar while the Git
      // sh resolves GNU tar — probing through the resolved sh keeps
      // detection and execution consistent (Greptile P1 + codex-connector
      // P1, round 4).
      const sh = resolvePosixShell('sh');
      if (!sh) throw new Error('no sh resolved');
      gnuTar = /GNU tar/i.test(
        execFileSync(sh, ['-c', 'tar --version'], {
          encoding: 'utf8',
          stdio: ['ignore', 'pipe', 'ignore'],
        }),
      );
    } catch {
      gnuTar = false;
    }
  }
  return gnuTar;
}
function shHide(cmd) {
  // Windows (msys) compatibility ONLY. On win32, msys GNU tar treats `C:\`
  // drive letters as remote hosts and does not glob by default, so quoted
  // Windows paths are converted to /c/... and tar gets --wildcards. On POSIX
  // (incl. macOS BSD/libarchive tar) the command runs UNCHANGED — no
  // GNU-only flags are injected, so other platforms keep upstream behavior.
  // Locate a real sh up front: on win32 the PATH may only contain Git\cmd
  // (without Git\bin), so a bare `sh` would ENOENT — the repo resolver finds
  // the Git-bundled sh.exe in standard install locations (codex-connector
  // P1, round 3). Non-win32 callers keep using their normal PATH ('sh').
  const sh = resolvePosixShell('sh');
  if (!sh) {
    throw new Error(
      'sync: could not locate a usable sh (Git for Windows not detected). ' +
        'Install Git for Windows and retry.',
    );
  }
  if (process.platform !== 'win32') {
    execFileSync(sh, ['-c', cmd], { stdio: ['ignore', 'ignore', 'inherit'] });
    return;
  }
  // Inject --wildcards ONLY when the resolved tar is actually GNU tar: on
  // win32 the PATH may resolve to the system bsdtar, which treats unsupported
  // options as fatal errors (Greptile P1 round 1). bsdtar matches extraction
  // paths as shell-style patterns natively, so no flag is needed there.
  const wildcards = isGnuTar() ? ' --wildcards' : '';
  const toMsys = (p) =>
    p
      // Collapse JSON-escaped double backslashes FIRST: converting each `\\`
      // separately would emit doubled separators like /c//Users//foo
      // (Copilot P1, round 2).
      .replace(/\\\\/g, '\\')
      .replace(/^([A-Za-z]):[\\/]/, (_, d) => `/${d.toLowerCase()}/`)
      .replace(/\\/g, '/');
  const posix = cmd
    .replace(/"((?:[A-Za-z]:)?[^"]*)"/g, (m, p) => JSON.stringify(toMsys(p)))
    .replace(/(^|\s)tar(\s)/g, `$1tar${wildcards}$2`);
  execFileSync(sh, ['-c', posix], { stdio: ['ignore', 'ignore', 'inherit'] });
}

/**
 * Preflight: the sync pulls upstream via `gh api` (tarball + commit resolve), so
 * a missing / unauthenticated gh CLI must fail loudly up front rather than mid-run.
 */
function ghPreflight() {
  try {
    execFileSync('gh', ['auth', 'status'], { stdio: ['ignore', 'ignore', 'ignore'] });
  } catch {
    throw new Error(
      'gh CLI is required and must be authenticated (this script uses `gh api`). ' +
        'Install it from https://cli.github.com/ and run `gh auth login`, then retry.',
    );
  }
}

/** Resolve a relative import inside a temp src tree to a .ts file path. */
function tryTs(p) {
  if (/\.js$/.test(p)) p = p.replace(/\.js$/, '.ts');
  if (!/\.ts$/.test(p) && fs.existsSync(`${p}.ts`)) return `${p}.ts`;
  if (fs.existsSync(p) && fs.statSync(p).isFile()) return p;
  const idx = `${p.replace(/\.ts$/, '')}/index.ts`;
  if (fs.existsSync(idx)) return idx;
  return null;
}

/**
 * Compute the transitive closure of SSRF/security leaf files, seeded from the
 * files the browser core imports out of src/infra/** + src/security/**.
 * Maps @openclaw/net-policy + normalization-core onto their tarball src.
 * Returns repo-relative paths under src/ (the leaf subtree we vendor verbatim).
 */
function computeLeafClosure(repoTmp) {
  const SEEDS = [
    'src/infra/net/ssrf.ts',
    'src/infra/net/hostname.ts',
    'src/infra/net/proxy-env.ts',
    'src/security/external-content.ts',
    'src/security/secret-equal.ts',
  ];
  const PKG_SRC = {
    '@openclaw/net-policy': path.join(repoTmp, 'packages/net-policy/src'),
    '@openclaw/normalization-core': path.join(repoTmp, 'packages/normalization-core/src'),
  };
  const visited = new Set();
  const reFrom = /(?:import|export)\s+(?:type\s+)?[^'"]*?from\s*['"]([^'"]+)['"]/g;
  const reDyn = /import\(\s*['"]([^'"]+)['"]\s*\)/g;
  function resolve(file, spec) {
    for (const [name, dir] of Object.entries(PKG_SRC)) {
      if (spec === name) return tryTs(path.join(dir, 'index'));
      if (spec.startsWith(`${name}/`)) return tryTs(path.join(dir, spec.slice(name.length + 1)));
    }
    if (spec.startsWith('.')) return tryTs(path.resolve(path.dirname(file), spec));
    return null; // node:, undici, ipaddr.js, zod, openclaw/plugin-sdk -> external/shim, not vendored as leaf
  }
  function walk(file) {
    if (!file || visited.has(file) || /\.test\.ts$/.test(file)) return;
    visited.add(file);
    const src = fs.readFileSync(file, 'utf8');
    let m;
    for (const re of [reFrom, reDyn]) {
      re.lastIndex = 0;
      while ((m = re.exec(src))) {
        const r = resolve(file, m[1]);
        if (r) walk(r);
      }
    }
  }
  for (const s of SEEDS) walk(path.join(repoTmp, s));
  // Normalize separators: on win32 path.relative emits '\', and the 'src/'
  // prefix filter below is POSIX-separator based.
  return [...visited].map((f) => path.relative(repoTmp, f).split(path.sep).join('/')).sort();
}

/** Rewrite all bare/aliased imports for a generated file at `genRelFromGenRoot`. */
function rewriteImports(source, genAbsFile) {
  const fileDir = path.dirname(genAbsFile);
  const rel = (toAbs) => {
    let r = path.relative(fileDir, toAbs);
    if (!r.startsWith('.')) r = `./${r}`;
    return r.split(path.sep).join('/');
  };
  return source.replace(
    /(['"])(openclaw\/plugin-sdk\/[^'"]+|@openclaw\/(?:net-policy|normalization-core|fs-safe)(?:\/[^'"]+)?)\1/g,
    (_full, q, spec) => {
      if (spec.startsWith('openclaw/plugin-sdk/')) {
        const sub = spec.slice('openclaw/plugin-sdk/'.length);
        return `${q}${rel(path.join(shimDir, `${sub}.js`))}${q}`;
      }
      if (spec === '@openclaw/net-policy' || spec.startsWith('@openclaw/net-policy/')) {
        const sub = spec === '@openclaw/net-policy' ? 'index' : spec.slice('@openclaw/net-policy/'.length);
        return `${q}${rel(path.join(genRoot, 'packages/net-policy', `${sub}.js`))}${q}`;
      }
      if (spec.startsWith('@openclaw/normalization-core/')) {
        const sub = spec.slice('@openclaw/normalization-core/'.length);
        return `${q}${rel(path.join(genRoot, 'packages/normalization-core', `${sub}.js`))}${q}`;
      }
      if (spec === '@openclaw/normalization-core') {
        return `${q}${rel(path.join(genRoot, 'packages/normalization-core/index.js'))}${q}`;
      }
      if (spec === '@openclaw/fs-safe' || spec.startsWith('@openclaw/fs-safe/')) {
        const sub = spec === '@openclaw/fs-safe' ? 'index' : spec.slice('@openclaw/fs-safe/'.length);
        return `${q}${rel(path.join(genRoot, 'vendor/fs-safe/dist', `${sub}.js`))}${q}`;
      }
      return _full;
    },
  );
}

function header(srcLabel) {
  return (
    '/* eslint-disable */\n' +
    '// @generated by scripts/browser-runtime/sync.mjs — DO NOT EDIT.\n' +
    `// upstream: ${srcLabel}\n`
  );
}

/**
 * LOCAL PATCHES — durable edits to vendored upstream sources, re-applied on every
 * sync so they survive the wipe-and-replace pipeline (editing _generated/ by hand
 * does NOT survive). Keyed by the _generated-relative path. Patches use literal
 * replacements or a bounded transform made only from exact-count replacements;
 * missing/duplicate anchors throw so upstream refactors surface loudly instead of
 * silently dropping a patch. Keep these minimal and prefer src/shim/* for anything
 * that can live at the adapter boundary.
 */
const LOCAL_PATCHES = {
  'extension/src/browser/navigation-guard.ts': [
    {
      desc: 'allow explicit browser proxies only for public hostnames named in the strict hostname allowlist',
      find: `  // Browser proxy routing hides the final connect target from this process.
  // Only block when the browser profile is known to be proxy-routed; Gateway
  // provider proxy env alone is not proof of browser page proxy behavior.
  if (
    opts.browserProxyMode === "explicit-browser-proxy" &&
    !isPrivateNetworkAllowedByPolicy(opts.ssrfPolicy)
  ) {
    throw new InvalidBrowserNavigationUrlError(
      "Navigation blocked: strict browser SSRF policy cannot be enforced while this browser profile is proxy-routed",
    );
  }`,
      replace: `  // An explicit browser proxy resolves and connects outside this process, so
  // local DNS pinning alone cannot prove the final connect target. Keep proxy
  // navigation fail-closed unless the caller supplied a narrow public-hostname
  // allowlist for this launch. The normal policy resolver below still rejects
  // blocked names and private/special-use DNS answers for every permitted host.
  if (
    opts.browserProxyMode === "explicit-browser-proxy" &&
    parsed.protocol !== "https:"
  ) {
    throw new InvalidBrowserNavigationUrlError(
      "Navigation blocked: proxied browser navigation requires HTTPS",
    );
  }
  const proxyHostnameAllowlist = (opts.ssrfPolicy?.hostnameAllowlist ?? [])
    .map((pattern) => normalizeHostname(pattern))
    .filter(Boolean);
  if (
    opts.browserProxyMode === "explicit-browser-proxy" &&
    !isPrivateNetworkAllowedByPolicy(opts.ssrfPolicy) &&
    (proxyHostnameAllowlist.length === 0 ||
      !matchesHostnameAllowlist(normalizeHostname(parsed.hostname), proxyHostnameAllowlist))
  ) {
    throw new InvalidBrowserNavigationUrlError(
      "Navigation blocked: proxied browser navigation requires an explicit public-hostname allowlist",
    );
  }`,
    },
  ],
  'extension/src/browser/routes/agent.act.ts': [
    {
      desc: 'execute fixed structured DOM reads in an isolated world without the interaction grace delay',
      transform: (source) => applyExactReplacements(source, [
        [
          `import { normalizeActRequest, validateBatchTargetIds } from "./agent.act.normalize.js";`,
          `import { normalizeActRequest, validateBatchTargetIds } from "./agent.act.normalize.js";
import { readBrowserDom } from "../../../../../shim/browser-dom-read.js";`,
        ],
        [
          `          const profileName = profileCtx.profile.name;
          if (isExistingSession) {`,
          `          // Only structured host reads enter this path. Arbitrary fn is
          // ignored here, never trusted as a promise of read-only behavior.
          if (action.kind === "evaluate" && body.domRead !== undefined && !isExistingSession) {
            if (!evaluateEnabled) {
              return jsonActError(res, 403, ACT_ERROR_CODES.evaluateDisabled,
                browserEvaluateDisabledMessage("evaluate"));
            }
            const observed = await readBrowserDom({
              cdpUrl, targetId: tab.targetId, spec: body.domRead,
              timeoutMs: action.timeoutMs, ssrfPolicy,
              browserProxyMode: navigationPolicy.browserProxyMode, signal: req.signal,
            });
            if ("blockedByDialog" in observed) {
              return res.json({ ok: true, targetId: tab.targetId, ...observed });
            }
            return res.json({ ok: true, targetId: tab.targetId, url: observed.url, result: observed.value });
          }
          const profileName = profileCtx.profile.name;
          if (isExistingSession) {`,
        ],
      ]),
    },
    {
      desc: 'resolve the selected tab alias before comparing or executing action targets',
      transform: (source) => applyExactReplacements(source, [
        [
          `import { normalizeActRequest, validateBatchTargetIds } from "./agent.act.normalize.js";`,
          `import { normalizeActRequest, validateBatchTargetIds } from "./agent.act.normalize.js";
import { resolveActionTargetIds } from "openclaw/plugin-sdk/browser-action-targets";`,
        ],
        [
          `      await withRouteTabContext({
        req,
        res,
        ctx,
        targetId,
        enforceCurrentUrlAllowed: shouldEnforceCurrentUrlForAct(action),
        run: async ({ profileCtx, cdpUrl, tab, resolveTabUrl }) => {`,
          `      const requestedAction = action;
      await withRouteTabContext({
        req,
        res,
        ctx,
        targetId,
        enforceCurrentUrlAllowed: shouldEnforceCurrentUrlForAct(action),
        run: async ({ profileCtx, cdpUrl, tab, resolveTabUrl }) => {
          let resolvedAction: BrowserActRequest;
          try {
            resolvedAction = resolveActionTargetIds(requestedAction, targetId, tab.targetId);
          } catch {
            return jsonActError(res, 403, ACT_ERROR_CODES.targetIdMismatch,
              "action targetId must match request targetId");
          }
          const action = resolvedAction;`,
        ],
        [
          `          if (action.targetId && action.targetId !== tab.targetId) {
            return jsonActError(
              res,
              403,
              ACT_ERROR_CODES.targetIdMismatch,
              "action targetId must match request targetId",
            );
          }
`,
          ``,
        ],
      ]),
    },
    {
      desc: 'carry the effective browser proxy mode through interaction navigation guards',
      transform: (source) => applyExactReplacements(source, [
        [
          `  readBody,
  requirePwAi,
  resolveTargetIdFromBody,`,
          `  browserNavigationPolicyForProfile,
  readBody,
  requirePwAi,
  resolveTargetIdFromBody,`,
        ],
        [
          `  ssrfPolicy?: BrowserNavigationPolicyOptions["ssrfPolicy"];
  listTabs: () => Promise<Array<{ targetId: string; url: string }>>;`,
          `  ssrfPolicy?: BrowserNavigationPolicyOptions["ssrfPolicy"];
  browserProxyMode?: BrowserNavigationPolicyOptions["browserProxyMode"];
  listTabs: () => Promise<Array<{ targetId: string; url: string }>>;`,
        ],
        [
          `  const ssrfPolicyOpts = withBrowserNavigationPolicy(params.ssrfPolicy);`,
          `  const ssrfPolicyOpts = withBrowserNavigationPolicy(params.ssrfPolicy, {
    browserProxyMode: params.browserProxyMode,
  });`,
        ],
        [
          `  if (!ssrfPolicyOpts.ssrfPolicy) {
    return;
  }`,
          `  if (!ssrfPolicyOpts.ssrfPolicy && !ssrfPolicyOpts.browserProxyMode) {
    return;
  }`,
        ],
        [
          `          const evaluateEnabled = ctx.state().resolved.evaluateEnabled;
          const ssrfPolicy = ctx.state().resolved.ssrfPolicy;
          const isExistingSession = getBrowserProfileCapabilities(profileCtx.profile).usesChromeMcp;
          const hasNavigationResultPolicy = Boolean(
            withBrowserNavigationPolicy(ssrfPolicy).ssrfPolicy,
          );`,
          `          const evaluateEnabled = ctx.state().resolved.evaluateEnabled;
          const navigationPolicy = browserNavigationPolicyForProfile(ctx, profileCtx);
          const ssrfPolicy = navigationPolicy.ssrfPolicy;
          const isExistingSession = getBrowserProfileCapabilities(profileCtx.profile).usesChromeMcp;
          const hasNavigationResultPolicy = Boolean(
            navigationPolicy.ssrfPolicy || navigationPolicy.browserProxyMode,
          );`,
        ],
        [
          `              targetId: tab.targetId,
              ssrfPolicy,
              listTabs: () => profileCtx.listTabs(),`,
          `              targetId: tab.targetId,
              ssrfPolicy,
              browserProxyMode: navigationPolicy.browserProxyMode,
              listTabs: () => profileCtx.listTabs(),`,
        ],
        [
          `            evaluateEnabled,
            ssrfPolicy,
            signal: req.signal,`,
          `            evaluateEnabled,
            ssrfPolicy,
            browserProxyMode: navigationPolicy.browserProxyMode,
            signal: req.signal,`,
        ],
      ]),
    },
  ],
  'extension/src/browser/routes/agent.act.hooks.ts': [
    {
      desc: 'apply the effective browser proxy mode to file-chooser click navigation',
      transform: (source) => applyExactReplacements(source, [
        [
          `  readBody,
  requirePwAi,
  resolveTargetIdFromBody,`,
          `  browserNavigationPolicyForProfile,
  readBody,
  requirePwAi,
  resolveTargetIdFromBody,`,
        ],
        [
          `                cdpUrl,
                targetId: tab.targetId,
                ssrfPolicy: ctx.state().resolved.ssrfPolicy,
                ref,`,
          `                cdpUrl,
                targetId: tab.targetId,
                ...browserNavigationPolicyForProfile(ctx, profileCtx),
                ref,`,
        ],
      ]),
    },
    {
      desc: 'apply the effective browser proxy mode to direct input file uploads',
      transform: (source) => applyExactReplacements(source, [
        [
          `            await pw.setInputFilesViaPlaywright({
              cdpUrl,
              targetId: tab.targetId,
              inputRef,
              element,
              paths: resolvedPaths,
            });`,
          `            await pw.setInputFilesViaPlaywright({
              cdpUrl,
              targetId: tab.targetId,
              ...browserNavigationPolicyForProfile(ctx, profileCtx),
              inputRef,
              element,
              paths: resolvedPaths,
            });`,
        ],
      ]),
    },
  ],
  'extension/src/browser/pw-tools-core.interactions.ts': [
    {
      desc: 'propagate proxy mode through Playwright interaction navigation checks',
      transform: (source) => applyExactReplacements(source, [
        [
          `  assertBrowserNavigationResultAllowed,
  withBrowserNavigationPolicy,`,
          `  assertBrowserNavigationResultAllowed,
  type BrowserNavigationPolicyOptions,
  withBrowserNavigationPolicy,`,
        ],
        [
          `  frameUrl: string,
  ssrfPolicy?: SsrFPolicy,
): Promise<void> {`,
          `  frameUrl: string,
  ssrfPolicy?: SsrFPolicy,
  browserProxyMode?: BrowserNavigationPolicyOptions["browserProxyMode"],
): Promise<void> {`,
        ],
        [
          `  if (!ssrfPolicy || (!frameUrl.startsWith("http://") && !frameUrl.startsWith("https://"))) {`,
          `  if (
    (!ssrfPolicy && !browserProxyMode) ||
    (!frameUrl.startsWith("http://") && !frameUrl.startsWith("https://"))
  ) {`,
        ],
        [
          `    ...withBrowserNavigationPolicy(ssrfPolicy),`,
          `    ...withBrowserNavigationPolicy(ssrfPolicy, { browserProxyMode }),`,
        ],
        [
          `  ssrfPolicy?: SsrFPolicy;
  targetId?: string;`,
          `  ssrfPolicy?: SsrFPolicy;
  browserProxyMode?: BrowserNavigationPolicyOptions["browserProxyMode"];
  targetId?: string;`,
          3,
        ],
        [
          `  if (!opts.ssrfPolicy) {`,
          `  if (!opts.ssrfPolicy && !opts.browserProxyMode) {`,
          2,
        ],
        [
          `await assertSubframeNavigationAllowed(frameUrl, opts.ssrfPolicy);`,
          `await assertSubframeNavigationAllowed(
        frameUrl,
        opts.ssrfPolicy,
        opts.browserProxyMode,
      );`,
          2,
        ],
        [
          `
      ssrfPolicy: opts.ssrfPolicy,
      targetId: opts.targetId,`,
          `
      ssrfPolicy: opts.ssrfPolicy,
      browserProxyMode: opts.browserProxyMode,
      targetId: opts.targetId,`,
          8,
        ],
        [
          `
        ssrfPolicy: opts.ssrfPolicy,
        targetId: opts.targetId,`,
          `
        ssrfPolicy: opts.ssrfPolicy,
        browserProxyMode: opts.browserProxyMode,
        targetId: opts.targetId,`,
          7,
        ],
        [
          `
    ssrfPolicy: opts.ssrfPolicy,
    targetId: opts.targetId,`,
          `
    ssrfPolicy: opts.ssrfPolicy,
    browserProxyMode: opts.browserProxyMode,
    targetId: opts.targetId,`,
        ],
        [
          `
            ssrfPolicy: opts.ssrfPolicy,
            targetId: opts.targetId,`,
          `
            ssrfPolicy: opts.ssrfPolicy,
            browserProxyMode: opts.browserProxyMode,
            targetId: opts.targetId,`,
        ],
        [
          `
          ssrfPolicy: opts.ssrfPolicy,
          targetId: opts.targetId,`,
          `
          ssrfPolicy: opts.ssrfPolicy,
          browserProxyMode: opts.browserProxyMode,
          targetId: opts.targetId,`,
        ],
        [
          `  ssrfPolicy?: SsrFPolicy;
  signal?: AbortSignal;`,
          `  ssrfPolicy?: SsrFPolicy;
  browserProxyMode?: BrowserNavigationPolicyOptions["browserProxyMode"];
  signal?: AbortSignal;`,
          7,
        ],
        [
          `  ssrfPolicy?: SsrFPolicy;
  fn: string;`,
          `  ssrfPolicy?: SsrFPolicy;
  browserProxyMode?: BrowserNavigationPolicyOptions["browserProxyMode"];
  fn: string;`,
        ],
        [
          `  ssrfPolicy?: SsrFPolicy;
  depth?: number;`,
          `  ssrfPolicy?: SsrFPolicy;
  browserProxyMode?: BrowserNavigationPolicyOptions["browserProxyMode"];
  depth?: number;`,
        ],
        [
          `    if (opts.ssrfPolicy) {
      await assertPageNavigationCompletedSafely({`,
          `    if (opts.ssrfPolicy || opts.browserProxyMode) {
      await assertPageNavigationCompletedSafely({`,
        ],
        [
          `  evaluateEnabled?: boolean,
  ssrfPolicy?: SsrFPolicy,
  depth = 0,`,
          `  evaluateEnabled?: boolean,
  ssrfPolicy?: SsrFPolicy,
  browserProxyMode?: BrowserNavigationPolicyOptions["browserProxyMode"],
  depth = 0,`,
        ],
        [
          `
        ssrfPolicy,
        signal,`,
          `
        ssrfPolicy,
        browserProxyMode,
        signal,`,
          6,
        ],
        [
          `        ssrfPolicy,
        fn: action.fn,`,
          `        ssrfPolicy,
        browserProxyMode,
        fn: action.fn,`,
        ],
        [
          `        ssrfPolicy,
        actions: action.actions,`,
          `        ssrfPolicy,
        browserProxyMode,
        actions: action.actions,`,
        ],
        [
          `        ssrfPolicy: opts.ssrfPolicy,
        actions: opts.action.actions,`,
          `        ssrfPolicy: opts.ssrfPolicy,
        browserProxyMode: opts.browserProxyMode,
        actions: opts.action.actions,`,
        ],
        [
          `      opts.evaluateEnabled,
      opts.ssrfPolicy,
      0,`,
          `      opts.evaluateEnabled,
      opts.ssrfPolicy,
      opts.browserProxyMode,
      0,`,
        ],
        [
          `        opts.evaluateEnabled,
        opts.ssrfPolicy,
        depth,`,
          `        opts.evaluateEnabled,
        opts.ssrfPolicy,
        opts.browserProxyMode,
        depth,`,
        ],
      ]),
    },
    {
      desc: 'guard direct input file uploads with the proxy navigation policy',
      transform: (source) => applyExactReplacements(source, [
        [
          `  inputRef?: string;
  element?: string;
  paths: string[];
}): Promise<void> {`,
          `  inputRef?: string;
  element?: string;
  paths: string[];
  ssrfPolicy?: SsrFPolicy;
  browserProxyMode?: BrowserNavigationPolicyOptions["browserProxyMode"];
}): Promise<void> {`,
        ],
        // input/change handlers can assign location after files are set; run
        // both the file assignment and the event dispatch inside the guard.
        [
          `  try {
    await locator.setInputFiles(resolvedPaths);
  } catch (err) {
    throw toFriendlyInteractionError(err, inputRef || element);
  }
  try {
    const handle = await locator.elementHandle();
    if (handle) {
      await handle.evaluate((el) => {
        el.dispatchEvent(new Event("input", { bubbles: true }));
        el.dispatchEvent(new Event("change", { bubbles: true }));
      });
    }
  } catch {
    // Best-effort for sites that don't react to setInputFiles alone.
  }
}`,
          `  const previousUrl = page.url();
  await assertInteractionNavigationCompletedSafely({
    action: async () => {
      try {
        await locator.setInputFiles(resolvedPaths);
      } catch (err) {
        throw toFriendlyInteractionError(err, inputRef || element);
      }
      try {
        const handle = await locator.elementHandle();
        if (handle) {
          await handle.evaluate((el) => {
            el.dispatchEvent(new Event("input", { bubbles: true }));
            el.dispatchEvent(new Event("change", { bubbles: true }));
          });
        }
      } catch {
        // Best-effort for sites that don't react to setInputFiles alone.
      }
    },
    cdpUrl: opts.cdpUrl,
    page,
    previousUrl,
    ssrfPolicy: opts.ssrfPolicy,
    browserProxyMode: opts.browserProxyMode,
    targetId: opts.targetId,
  });
}`,
        ],
      ]),
    },
    {
      desc: 'guard hover/drag/scrollIntoView/wait interactions with the same proxy navigation policy',
      transform: (source) => applyExactReplacements(source, [
        // hover + scrollIntoView share this options signature.
        [
          `  ref?: string;
  selector?: string;
  timeoutMs?: number;
  signal?: AbortSignal;
}): Promise<void> {`,
          `  ref?: string;
  selector?: string;
  timeoutMs?: number;
  ssrfPolicy?: SsrFPolicy;
  browserProxyMode?: BrowserNavigationPolicyOptions["browserProxyMode"];
  signal?: AbortSignal;
}): Promise<void> {`,
          2,
        ],
        [
          `  endRef?: string;
  endSelector?: string;
  timeoutMs?: number;
  signal?: AbortSignal;`,
          `  endRef?: string;
  endSelector?: string;
  timeoutMs?: number;
  ssrfPolicy?: SsrFPolicy;
  browserProxyMode?: BrowserNavigationPolicyOptions["browserProxyMode"];
  signal?: AbortSignal;`,
        ],
        [
          `  fn?: string;
  timeoutMs?: number;
  signal?: AbortSignal;`,
          `  fn?: string;
  timeoutMs?: number;
  ssrfPolicy?: SsrFPolicy;
  browserProxyMode?: BrowserNavigationPolicyOptions["browserProxyMode"];
  signal?: AbortSignal;`,
        ],
        // hover: mouseover handlers can assign location; run the interaction
        // navigation guard like click/press instead of skipping it.
        [
          `  const { abortPromise, cleanup } = createAbortPromise(opts.signal);
  const reconcileRemoteDialog = () => reconcileRemoteDialogAfterActionSettled(page, opts.signal);
  try {
    await awaitActionWithAbort(
      locator.hover({
        timeout: resolveInteractionTimeoutMs(opts.timeoutMs),
      }),
      abortPromise,
      reconcileRemoteDialog,
    );
  } catch (err) {`,
          `  const previousUrl = page.url();
  const { abortPromise, cleanup } = createAbortPromise(opts.signal);
  const reconcileRemoteDialog = () => reconcileRemoteDialogAfterActionSettled(page, opts.signal);
  try {
    await assertInteractionNavigationCompletedSafely({
      action: async () => {
        await awaitActionWithAbort(
          locator.hover({
            timeout: resolveInteractionTimeoutMs(opts.timeoutMs),
          }),
          abortPromise,
          reconcileRemoteDialog,
        );
      },
      cdpUrl: opts.cdpUrl,
      page,
      previousUrl,
      ssrfPolicy: opts.ssrfPolicy,
      browserProxyMode: opts.browserProxyMode,
      targetId: opts.targetId,
    });
  } catch (err) {`,
        ],
        // drag: dragstart/drop handlers can assign location.
        [
          `  const { abortPromise, cleanup } = createAbortPromise(opts.signal);
  const reconcileRemoteDialog = () => reconcileRemoteDialogAfterActionSettled(page, opts.signal);
  try {
    await awaitActionWithAbort(
      startLocator.dragTo(endLocator, {
        timeout: resolveInteractionTimeoutMs(opts.timeoutMs),
      }),
      abortPromise,
      reconcileRemoteDialog,
    );
  } catch (err) {`,
          `  const previousUrl = page.url();
  const { abortPromise, cleanup } = createAbortPromise(opts.signal);
  const reconcileRemoteDialog = () => reconcileRemoteDialogAfterActionSettled(page, opts.signal);
  try {
    await assertInteractionNavigationCompletedSafely({
      action: async () => {
        await awaitActionWithAbort(
          startLocator.dragTo(endLocator, {
            timeout: resolveInteractionTimeoutMs(opts.timeoutMs),
          }),
          abortPromise,
          reconcileRemoteDialog,
        );
      },
      cdpUrl: opts.cdpUrl,
      page,
      previousUrl,
      ssrfPolicy: opts.ssrfPolicy,
      browserProxyMode: opts.browserProxyMode,
      targetId: opts.targetId,
    });
  } catch (err) {`,
        ],
        // scrollIntoView: scroll handlers can assign location.
        [
          `  const { abortPromise, cleanup } = createAbortPromise(opts.signal);
  const reconcileRemoteDialog = () => reconcileRemoteDialogAfterActionSettled(page, opts.signal);
  try {
    await awaitActionWithAbort(
      locator.scrollIntoViewIfNeeded({ timeout }),
      abortPromise,
      reconcileRemoteDialog,
    );
  } catch (err) {`,
          `  const previousUrl = page.url();
  const { abortPromise, cleanup } = createAbortPromise(opts.signal);
  const reconcileRemoteDialog = () => reconcileRemoteDialogAfterActionSettled(page, opts.signal);
  try {
    await assertInteractionNavigationCompletedSafely({
      action: async () => {
        await awaitActionWithAbort(
          locator.scrollIntoViewIfNeeded({ timeout }),
          abortPromise,
          reconcileRemoteDialog,
        );
      },
      cdpUrl: opts.cdpUrl,
      page,
      previousUrl,
      ssrfPolicy: opts.ssrfPolicy,
      browserProxyMode: opts.browserProxyMode,
      targetId: opts.targetId,
    });
  } catch (err) {`,
        ],
        // wait: wait.fn and observed load states can land on a new location.
        [
          `  try {
    if (typeof opts.timeMs === "number" && Number.isFinite(opts.timeMs)) {`,
          `  const previousUrl = page.url();
  try {
    await assertInteractionNavigationCompletedSafely({
      action: async () => {
    if (typeof opts.timeMs === "number" && Number.isFinite(opts.timeMs)) {`,
        ],
        [
          `        await waitForStep(page.waitForFunction(fn, { timeout }));
      }
    }
  } finally {
    cleanup();
  }
}`,
          `        // Pass a real function so Playwright caches its compilation between
        // polls (string expressions re-eval and can fail under Trusted Types).
        // Compile only on the host; execution stays in the page context.
        const predicate = new Function(
          "const value = (" + normalizeBrowserEvaluateFunctionSource(fn) + ")(); " +
            "if (value && typeof value.then === 'function') { " +
            "Promise.resolve(value).catch(() => {}); throw new Error('wait.fn requires a synchronous predicate'); } " +
            "return value;",
        ) as () => unknown;
        await waitForStep(page.waitForFunction(predicate, undefined, { timeout }));
      }
    }
      },
      cdpUrl: opts.cdpUrl,
      page,
      previousUrl,
      ssrfPolicy: opts.ssrfPolicy,
      browserProxyMode: opts.browserProxyMode,
      targetId: opts.targetId,
    });
  } finally {
    cleanup();
  }
}`,
        ],
        // Popups: window.open / target=_blank tabs opened by a guarded
        // interaction bypass the per-page framenavigated listener; collect
        // them from the context and validate/quarantine before returning.
        [
          `  const navPage = opts.page as unknown as NavigationObservablePage;
  let navigatedDuringAction = false;
  const subframeNavigationsDuringAction: string[] = [];`,
          `  const navPage = opts.page as unknown as NavigationObservablePage;
  const pageContext = (
    opts.page as unknown as {
      context?: () => { on?: (event: string, listener: (page: Page) => void) => void; off?: (event: string, listener: (page: Page) => void) => void; close?: () => Promise<void>; browser?: () => { close?: () => Promise<void> } | undefined };
    }
  ).context?.();
  const popupsDuringAction: Page[] = [];
  // The context is PERSISTENT and shared with the user, who can open tabs at
  // any moment — as can any unrelated producer. The page event fires for all of
  // them, so tracking every new page would let the drain below validate, and on
  // denial CLOSE, a tab the user opened themselves; a busy stream of them could
  // even escalate to tearing down the whole context. Only pages that descend
  // from the page being acted on are ours to police.
  //
  // opener() is async and this listener must stay synchronous (an await here
  // would drop events), so kick the probe off on arrival and record the answer;
  // consumers below wait for the probe of the page they are about to touch.
  const openerOfPopup = new Map<unknown, unknown>();
  const popupOwnershipProbe = new Map<unknown, Promise<void>>();
  const popupOwnershipPending = new Set<unknown>();
  const onContextPage = (newPage: Page) => {
    popupsDuringAction.push(newPage);
    const opener = (newPage as unknown as { opener?: () => Promise<Page | null> }).opener;
    if (typeof opener !== "function") return;
    popupOwnershipPending.add(newPage);
    popupOwnershipProbe.set(
      newPage,
      Promise.resolve()
        .then(() => opener.call(newPage))
        .then(
          (parent) => {
            if (parent) openerOfPopup.set(newPage, parent);
          },
          () => undefined,
        )
        .then(() => {
          popupOwnershipPending.delete(newPage);
        }),
    );
  };
  /**
   * Whether this page's lineage question has been ANSWERED yet. A pending probe
   * is not the same as "not ours": treating it that way would let a popup the
   * action opened slip past the cleanup below, unvalidated and still live.
   */
  const ownershipAnswered = (page: unknown): boolean => !popupOwnershipPending.has(page);
  /**
   * Settle outstanding lineage probes, re-checking after every round: a popup
   * can open a child while we await, and that child's probe is registered after
   * any snapshot we took, so a single allSettled would never wait for it.
   * Bounded by the caller's deadline so an unresponsive page cannot hold the
   * action — and the serialized stop/quit behind it — open.
   */
  const settleOwnershipProbes = async (deadline: Promise<void>): Promise<void> => {
    let expired = false;
    void deadline.then(() => {
      expired = true;
    });
    while (!expired && popupOwnershipPending.size > 0) {
      const outstanding = [...popupOwnershipPending]
        .map((page) => popupOwnershipProbe.get(page))
        .filter((probe): probe is Promise<void> => probe !== undefined);
      if (outstanding.length === 0) return;
      await Promise.race([Promise.allSettled(outstanding), deadline]);
    }
  };
  /**
   * Whether a page's opener chain reaches the page being acted on. Walks the
   * chain so a popup opened BY a popup still counts as ours, and is bounded so
   * a cycle or an absurdly deep chain cannot hang the drain.
   *
   * Fails closed toward the USER's data: a page whose lineage we could not
   * establish is treated as not ours, so it is never validated and never
   * closed. Anything the action itself opened does report an opener.
   */
  const descendsFromActedPage = (page: unknown): boolean => {
    let cursor = page;
    for (let hops = 0; hops < POPUP_CHAIN_MAX_VALIDATIONS; hops += 1) {
      const parent = openerOfPopup.get(cursor);
      if (parent === undefined) return false;
      if (parent === opts.page) return true;
      cursor = parent;
    }
    return false;
  };
  if (pageContext && typeof pageContext.on === "function") {
    pageContext.on("page", onContextPage);
  }
  let navigatedDuringAction = false;
  const subframeNavigationsDuringAction: string[] = [];`,
        ],
        [
          `  markObservedDialogsHandledRemotelyForPage,
  refLocator,`,
          `  markObservedDialogsHandledRemotelyForPage,
  quarantineTargetWithoutClosing,
  refLocator,`,
        ],
        [
          `  assertPageNavigationCompletedSafely,
  createObservedDialogAbortSignalForPage,`,
          `  assertPageNavigationCompletedSafely,
  closeBlockedNavigationTarget,
  createObservedDialogAbortSignalForPage,`,
        ],
        [
          `const INTERACTION_NAVIGATION_GRACE_MS = 250;`,
          `const INTERACTION_NAVIGATION_GRACE_MS = 250;

// Bounds for draining the popup chain after an interaction. The queue is
// adversarial — validating a popup can append another — so it needs a ceiling
// on both count and wall-clock, or a page that opens one popup per grace
// window keeps the action (and every serialized call behind it) alive forever.
const POPUP_CHAIN_MAX_VALIDATIONS = 32;
const POPUP_CHAIN_DRAIN_BUDGET_MS = 5_000;
// Quarantining the overflow needs its own bounds: an unresponsive close() must
// not keep the action pending any more than an endless popup chain may.
const POPUP_CHAIN_MAX_CLOSES = 256;
const POPUP_CHAIN_CLOSE_BUDGET_MS = 2_000;

// The one message the host matches on to distrust the whole route
// (\`mentionsUntornDownBrowser\` in external-chrome-backend.ts). Every path that
// fails to contain a page must report exactly this, or the host keeps serving
// a route whose pages are still live.
const UNTORN_DOWN_BROWSER_MESSAGE =
  "Navigation blocked: popup chain exceeded the validation budget and the browser could not be torn down; unvalidated pages may still be live";`,
        ],
        // Capture (do not propagate) a main-navigation policy deny so the
        // popup pass below still runs: an interaction can both navigate the
        // main frame somewhere denied AND open a tab, and the popup must be
        // validated/quarantined rather than left live. Precedence is resolved
        // at the end. This also guarantees the context listener is detached on
        // every path.
        [
          `  if (navigationObserved) {
    await assertPageNavigationCompletedSafely({`,
          `  let navigationError: unknown;
  try {
  if (navigationObserved) {
    await assertPageNavigationCompletedSafely({`,
        ],
        [
          `  if (subframeError) {
    throw toLintErrorObject(subframeError, "Non-Error thrown");
  }

  if (actionError) {
    throw toLintErrorObject(actionError, "Non-Error thrown");
  }
  return result as T;
}`,
          `  } catch (err) {
    navigationError = err;
  }
  // NOTE: the context listener stays attached across popup validation below —
  // a popup can open a further popup inside its own grace window, and
  // detaching here would leave that second-generation tab uncollected and
  // unvalidated (in direct mode nothing else would catch it).
  let popupError: unknown;
  // Shared last-resort teardown for pages we could not contain individually.
  // Both the per-popup close failure and the overflow path escalate through
  // this, so a stuck page has exactly one ladder: context close, then browser
  // close.
  //
  // Only a resolved CONTEXT close proves containment from in here: its pages
  // are gone with it. A resolved BROWSER close proves only that the call
  // returned — the process can still be alive with pages running, and nothing
  // in this runtime can observe process exit. So browser close reports
  // "unproven" and the caller raises the untorn-down signal, which is what
  // makes the host run its own verified process teardown.
  const tearDownUncontainedPages = async (
    deadline?: Promise<void>,
  ): Promise<"contained" | "unproven"> => {
    const closeContext = (
      pageContext as unknown as { close?: () => Promise<void> } | undefined
    )?.close;
    if (typeof closeContext === "function") {
      const contextClosed = await Promise.race([
        Promise.resolve()
          .then(() => closeContext.call(pageContext))
          .then(
            () => true,
            () => false,
          ),
        // A caller that already burned its budget passes no deadline: racing a
        // fired one would resolve instantly and prove nothing.
        deadline
          ? deadline.then(() => false)
          : new Promise<boolean>((resolve) => {
              const timer = setTimeout(() => resolve(false), POPUP_CHAIN_CLOSE_BUDGET_MS);
              (timer as unknown as { unref?: () => void }).unref?.();
            }),
      ]);
      if (contextClosed) return "contained";
    }
    // The context would not close (rejected, or still not settled at the
    // deadline), so live pages that were never validated survive and the
    // listener is about to detach. Every per-page and per-context remedy has
    // now failed, so try the browser. Give this its own budget.
    const browserOf = (
      pageContext as unknown as { browser?: () => { close?: () => Promise<void> } | undefined }
        | undefined
    )?.browser;
    const browser = typeof browserOf === "function" ? browserOf.call(pageContext) : undefined;
    if (!browser || typeof browser.close !== "function") return "unproven";
    await Promise.race([
      Promise.resolve()
        .then(() => browser.close?.())
        .then(
          () => undefined,
          () => undefined,
        ),
      new Promise<void>((resolve) => {
        const timer = setTimeout(resolve, POPUP_CHAIN_CLOSE_BUDGET_MS);
        (timer as unknown as { unref?: () => void }).unref?.();
      }),
    ]);
    // Deliberately NOT reporting success on a resolved close: the host owns
    // process teardown and must verify the exit itself.
    return "unproven";
  };
  try {
    // Drain the chain rather than a snapshot: validating a popup can append
    // more entries to popupsDuringAction, so index forward as it grows.
    //
    // BOUNDED, because the queue is adversarial: each iteration awaits a
    // ~250ms grace window, so a page that opens one popup per window appends
    // at least as fast as this drains and the loop never empties. That would
    // hang the action forever — and the backend serializes every browser call,
    // so a later stop (and dispose at quit) would queue behind it indefinitely.
    // On overrun, stop validating and CLOSE the remainder: leaving them live
    // would be the unvalidated-tab bug this drain exists to prevent.
    const drainDeadline = Date.now() + POPUP_CHAIN_DRAIN_BUDGET_MS;
    let popupIndex = 0;
    for (
      ;
      popupIndex < popupsDuringAction.length
      && popupIndex < POPUP_CHAIN_MAX_VALIDATIONS
      && Date.now() < drainDeadline;
      popupIndex += 1
    ) {
      const popupPage = popupsDuringAction[popupIndex]!;
      // Wait for this page's lineage answer, then skip anything PROVEN not to
      // be ours: validating it could quarantine or close one of the user's own
      // tabs, which is strictly worse than not policing a page we never opened.
      // A page that never answered is not proven either way, so it stays in
      // scope here and the overflow cleanup below decides its fate.
      await popupOwnershipProbe.get(popupPage);
      if (ownershipAnswered(popupPage) && !descendsFromActedPage(popupPage)) continue;
      // Per popup, not around the loop: a denial on the first popup must not
      // leave later ones unvalidated and selectable on a denied URL. Keep the
      // first error and keep going.
      try {
        // A popup starts at about:blank; reuse the delayed-navigation observer
        // so a still-loading popup gets the same grace window before
        // validation, and a policy deny quarantines/closes the popup target
        // like any other block.
        const observedPopup = await observeDelayedInteractionNavigation(
          popupPage as unknown as NavigationObservablePage,
          "about:blank",
        );
        await assertObservedDelayedNavigations({
          cdpUrl: opts.cdpUrl,
          page: popupPage,
          ssrfPolicy: opts.ssrfPolicy,
          browserProxyMode: opts.browserProxyMode,
          observed: observedPopup,
        });
      } catch (err) {
        if (popupError === undefined) popupError = err;
        // Fail closed on the rejected popup itself. A policy deny above only
        // quarantines — assertPageNavigationCompletedSafely never closes; that
        // step belongs to callers that own the navigation lifecycle — and this
        // popup was created BY the action, not by the user, so it is ours to
        // tear down. Left open, the denied page keeps executing after the
        // context listener detaches (in direct mode no lifetime request gate
        // remains to catch it).
        //
        // Bounded, because close() can hang forever on an adversarial page.
        // But a timeout is NOT success: the page is still live and scriptable.
        // Escalate exactly like the overflow path — context, then browser —
        // and if none of that works, report the untorn-down browser so the
        // host distrusts the route instead of returning an ordinary denial.
        await Promise.race([
          closeBlockedNavigationTarget({
            cdpUrl: opts.cdpUrl,
            page: popupPage as Page,
          }).then(
            () => undefined,
            () => undefined,
          ),
          new Promise<void>((resolve) => {
            const timer = setTimeout(resolve, POPUP_CHAIN_CLOSE_BUDGET_MS);
            (timer as unknown as { unref?: () => void }).unref?.();
          }),
        ]);
        // Ask the PAGE whether it closed, rather than trusting the call to have
        // reported it. closeBlockedNavigationTarget swallows page.close()
        // rejections internally (pw-session.ts), so it resolves even when the
        // page refused to go — reading its resolution as success would silently
        // skip the escalation for exactly the pages that need it. A page that
        // cannot answer isClosed() has not proven anything either, so it counts
        // as uncontained too.
        const isClosed = (popupPage as { isClosed?: () => boolean }).isClosed;
        const popupClosed = typeof isClosed === "function" && isClosed.call(popupPage) === true;
        if (!popupClosed && (await tearDownUncontainedPages()) !== "contained") {
          popupError = new Error(UNTORN_DOWN_BROWSER_MESSAGE);
          break;
        }
      }
    }
    // Settle outstanding lineage probes before the sweep below: it runs
    // synchronously (so pending page events can still enqueue) and must be able
    // to tell our popups from the user's without awaiting per page. Bounded on
    // its own budget, and repeated internally so a child popup that arrives
    // mid-await is waited on too.
    const ownershipDeadline = new Promise<void>((resolve) => {
      const timer = setTimeout(resolve, POPUP_CHAIN_CLOSE_BUDGET_MS);
      (timer as unknown as { unref?: () => void }).unref?.();
    });
    await settleOwnershipProbes(ownershipDeadline);
    // A page whose probe never answered counts as OURS. Once the budget above
    // is spent the browser is already failing to answer, and dropping such a
    // page would mean the listener detaches with an unvalidated, never-closed
    // popup and no untorn-down signal for the host — silently
    // losing containment. The user's genuinely own tabs answer opener() with
    // null promptly, so they are still excluded.
    const isOursOrUnanswered = (page: unknown): boolean =>
      descendsFromActedPage(page) || !ownershipAnswered(page);
    const ownedPagesRemain = (): boolean => {
      for (let i = popupIndex; i < popupsDuringAction.length; i += 1) {
        if (isOursOrUnanswered(popupsDuringAction[i]!)) return true;
      }
      return false;
    };
    if (ownedPagesRemain()) {
      // Quarantine must be bounded too, for the same reason the drain above is:
      // a burst of popups, or one unresponsive close(), would otherwise keep
      // this action — and the serialized stop/quit cleanup behind it — pending
      // indefinitely. Close concurrently under a single deadline rather than
      // serially awaiting each one, and re-read the queue (not a snapshot) so
      // popups appended while these closes run are quarantined too.
      const closeDeadline = new Promise<void>((resolve) => {
        const timer = setTimeout(resolve, POPUP_CHAIN_CLOSE_BUDGET_MS);
        // Do not hold the process open on this timer.
        (timer as unknown as { unref?: () => void }).unref?.();
      });
      const closing: Array<Promise<void>> = [];
      let deadlineReached = false;
      void closeDeadline.then(() => { deadlineReached = true; });
      // Outer loop so newly-arrived popups are picked up: the inner loop never
      // awaits, so on its own it drains the queue as it stands and returns
      // before the event loop can deliver another page event. Yielding
      // between sweeps is what actually lets the queue grow and be re-read;
      // without it a popup created during cleanup would be left live,
      // unvalidated and unquarantined once the listener detaches.
      while (
        !deadlineReached
        && popupIndex < popupsDuringAction.length
        && closing.length < POPUP_CHAIN_MAX_CLOSES
      ) {
        for (
          ;
          popupIndex < popupsDuringAction.length
          && closing.length < POPUP_CHAIN_MAX_CLOSES;
          popupIndex += 1
        ) {
          const unvalidated = popupsDuringAction[popupIndex]!;
          // A page that arrived mid-sweep may not have answered opener() yet.
          // Do NOT advance past it: this index only moves forward, so skipping
          // it here would strand an action-created popup that proves ours a
          // moment later — unvalidated, unquarantined, and invisible to
          // ownedPagesRemain(). Stop the sweep instead; the yield below lets
          // the probe settle and the outer loop retries the same page, all
          // still under closeDeadline.
          if (!ownershipAnswered(unvalidated)) break;
          // Same boundary as the drain: the user's own tabs are not ours to
          // quarantine or close, however far behind this cleanup falls.
          if (!descendsFromActedPage(unvalidated)) continue;
          // Quarantine BEFORE closing, and do not make it conditional on the
          // close succeeding: close() can hang forever on an adversarial page,
          // and when the deadline below fires we would otherwise leave a live,
          // never-validated popup selectable — in direct mode there is no
          // lifetime CDP request gate to catch it afterwards. Marking is
          // synchronous bookkeeping, so it completes regardless.
          closing.push(
            quarantineTargetWithoutClosing({
              cdpUrl: opts.cdpUrl,
              page: unvalidated as Page,
            })
              .catch(() => undefined)
              .then(() => (unvalidated as { close?: () => Promise<void> }).close?.())
              .then(
                () => undefined,
                () => undefined,
              ),
          );
        }
        // Hand control back so pending page events can enqueue, then re-check.
        // Racing the deadline keeps this bounded even against a page that
        // appends a new popup on every turn.
        await Promise.race([
          new Promise<void>((resolve) => {
            const timer = setTimeout(resolve, 0);
            (timer as unknown as { unref?: () => void }).unref?.();
          }),
          closeDeadline,
        ]);
      }
      // Never await a popup's close() unbounded: a hung page must not outrank
      // returning from the interaction.
      //
      // Track whether they actually finished. popupIndex only records that a
      // close was ISSUED, and quarantine is bookkeeping that never closes a
      // page (see quarantineTargetWithoutClosing), so a fully-drained queue
      // whose closes all hang would otherwise look fully handled while every
      // one of those popups is still live and scriptable.
      const allClosesSettled = await Promise.race([
        Promise.all(closing).then(() => true),
        closeDeadline.then(() => false),
      ]);
      // If the bounds cut us off with popups still unaccounted for, they were
      // neither validated nor quarantined and the listener is about to detach —
      // in direct mode nothing else would ever check them. Per-page cleanup has
      // already failed to keep up here, so fail closed on the whole context
      // rather than leaving live, never-validated pages behind.
      if (ownedPagesRemain() || !allClosesSettled) {
        // Nothing reachable from this process can shut the browser down, and a
        // resolved close() would only prove the call returned, not that the
        // process exited. Say so explicitly rather than reporting a generic
        // policy denial: the host owns process teardown and must treat this
        // route as untrusted until it verifies an exit itself.
        if ((await tearDownUncontainedPages(closeDeadline)) !== "contained") {
          popupError = new Error(UNTORN_DOWN_BROWSER_MESSAGE);
        }
      }
      if (popupError === undefined) {
        popupError = new Error(
          "Navigation blocked: popup chain exceeded the validation budget; remaining popups were closed",
        );
      }
    }
  } finally {
    // Always detach: a throw here would otherwise leak the listener, retaining
    // every tab opened afterwards for the life of the context.
    if (pageContext && typeof pageContext.off === "function") {
      pageContext.off("page", onContextPage);
    }
  }

  // A containment failure outranks EVERYTHING. Ordinary denials describe a
  // request that was refused — the safe outcome. This one says pages we never
  // validated are still live and could not be torn down, and it is the only
  // signal the host uses to distrust the route. If a denied main-frame
  // navigation happened in the same interaction (easy for an adversarial page
  // to arrange), reporting that instead would leave the route usable while
  // those pages keep running.
  if (popupError && /could not be torn down/.test(String((popupError as Error)?.message ?? ""))) {
    throw toLintErrorObject(popupError, "Non-Error thrown");
  }

  // Otherwise policy denials outrank the action's own error, and the main-frame
  // denial outranks subframe/popup denials, so the caller sees the navigation it
  // asked for being refused. All were still evaluated above.
  if (navigationError) {
    throw toLintErrorObject(navigationError, "Non-Error thrown");
  }

  if (subframeError) {
    throw toLintErrorObject(subframeError, "Non-Error thrown");
  }

  if (popupError) {
    throw toLintErrorObject(popupError, "Non-Error thrown");
  }

  if (actionError) {
    throw toLintErrorObject(actionError, "Non-Error thrown");
  }
  return result as T;
}`,
        ],
        // resize: page resize handlers can assign location; run the viewport
        // change inside the same guard at the dispatch (the implementation
        // lives in pw-tools-core.snapshot.ts, which cannot reach this
        // file-private guard).
        [
          `    case "resize":
      await resizeViewportViaPlaywright({
        cdpUrl,
        targetId: effectiveTargetId,
        width: action.width,
        height: action.height,
      });
      break;`,
          `    case "resize": {
      const resizePage = await getPageForTargetId({ cdpUrl, targetId: effectiveTargetId });
      ensurePageState(resizePage);
      const resizePreviousUrl = resizePage.url();
      await assertInteractionNavigationCompletedSafely({
        action: async () => {
          await resizeViewportViaPlaywright({
            cdpUrl,
            targetId: effectiveTargetId,
            width: action.width,
            height: action.height,
          });
        },
        cdpUrl,
        page: resizePage,
        previousUrl: resizePreviousUrl,
        ssrfPolicy,
        browserProxyMode,
        targetId: effectiveTargetId,
      });
      break;
    }`,
        ],
        // act dispatch: pass the policy into the four newly guarded branches.
        [
          `    case "hover":
      await hoverViaPlaywright({
        cdpUrl,
        targetId: effectiveTargetId,
        ref: action.ref,
        selector: action.selector,
        timeoutMs: action.timeoutMs,
        signal,
      });`,
          `    case "hover":
      await hoverViaPlaywright({
        cdpUrl,
        targetId: effectiveTargetId,
        ref: action.ref,
        selector: action.selector,
        timeoutMs: action.timeoutMs,
        ssrfPolicy,
        browserProxyMode,
        signal,
      });`,
        ],
        [
          `    case "scrollIntoView":
      await scrollIntoViewViaPlaywright({
        cdpUrl,
        targetId: effectiveTargetId,
        ref: action.ref,
        selector: action.selector,
        timeoutMs: action.timeoutMs,
        signal,
      });`,
          `    case "scrollIntoView":
      await scrollIntoViewViaPlaywright({
        cdpUrl,
        targetId: effectiveTargetId,
        ref: action.ref,
        selector: action.selector,
        timeoutMs: action.timeoutMs,
        ssrfPolicy,
        browserProxyMode,
        signal,
      });`,
        ],
        [
          `    case "drag":
      await dragViaPlaywright({
        cdpUrl,
        targetId: effectiveTargetId,
        startRef: action.startRef,
        startSelector: action.startSelector,
        endRef: action.endRef,
        endSelector: action.endSelector,
        timeoutMs: action.timeoutMs,
        signal,
      });`,
          `    case "drag":
      await dragViaPlaywright({
        cdpUrl,
        targetId: effectiveTargetId,
        startRef: action.startRef,
        startSelector: action.startSelector,
        endRef: action.endRef,
        endSelector: action.endSelector,
        timeoutMs: action.timeoutMs,
        ssrfPolicy,
        browserProxyMode,
        signal,
      });`,
        ],
        [
          `        loadState: action.loadState,
        fn: action.fn,
        timeoutMs: action.timeoutMs,
        signal,
      });`,
          `        loadState: action.loadState,
        fn: action.fn,
        timeoutMs: action.timeoutMs,
        ssrfPolicy,
        browserProxyMode,
        signal,
      });`,
        ],
      ]),
    },
  ],
  'extension/src/browser/pw-session.ts': [
    {
      desc: 'use Playwright local-path uploads only for a live browser managed by this runtime',
      transform: (source) => applyExactReplacements(source, [
        [
          `import path from "node:path";`,
          `import path from "node:path";
import { getBrowserControlState } from "../browser-control-state.js";
import { isManagedLocalCdpConnection } from "openclaw/plugin-sdk/cdp-locality";`,
        ],
        [
          `          const headers = getHeadersWithAuth(target);
          // Bypass proxy for loopback CDP connections (#31219)`,
          `          const headers = getHeadersWithAuth(target);
          const isLocal = isManagedLocalCdpConnection(
            normalized, target, getBrowserControlState()?.profiles.values() ?? [],
          );
          // Bypass proxy for loopback CDP connections (#31219)`,
        ],
        [
          `chromium.connectOverCDP(target, { timeout, headers })`,
          `chromium.connectOverCDP(target, { timeout, headers, isLocal })`,
        ],
      ]),
    },
    {
      desc: 'export a non-blocking quarantine so the popup-overflow path can mark a target unusable without awaiting close() (a hung page must not keep the interaction pending)',
      find: `// Quarantine and close a tab that OpenClaw itself navigated to a blocked URL.`,
      replace: `/**
 * Mark a target unusable WITHOUT closing it.
 *
 * closeBlockedNavigationTarget awaits page.close(), which an adversarial or
 * hung page can stall indefinitely. Quarantine is the part that must not
 * depend on the page cooperating: marking is synchronous bookkeeping, so a
 * target can be made unselectable even when its close never returns.
 */
export async function quarantineTargetWithoutClosing(opts: {
  cdpUrl: string;
  page: Page;
  targetId?: string;
}): Promise<void> {
  await quarantineBlockedTarget(opts);
}

// Quarantine and close a tab that OpenClaw itself navigated to a blocked URL.`,
    },
  ],
  'extension/src/browser/ssrf-policy-helpers.ts': [
    {
      desc: 'one-off hostname grants must also pass a strict hostnameAllowlist (else the loopback CDP endpoint is blocked by proxyAllowedHostnames and every proxied navigation fails)',
      find: `export function withAllowedHostname(
  ssrfPolicy: SsrFPolicy | undefined,
  hostname: string,
): SsrFPolicy {
  return {
    ...ssrfPolicy,
    allowedHostnames: uniqueStrings([...(ssrfPolicy?.allowedHostnames ?? []), hostname]),
  };
}`,
      replace: `export function withAllowedHostname(
  ssrfPolicy: SsrFPolicy | undefined,
  hostname: string,
): SsrFPolicy {
  return {
    ...ssrfPolicy,
    allowedHostnames: uniqueStrings([...(ssrfPolicy?.allowedHostnames ?? []), hostname]),
    // A one-off grant must grant through BOTH policy fields: exact-host trust
    // (allowedHostnames) and, when a strict hostnameAllowlist is active, the
    // allowlist match itself. Otherwise a per-start proxyAllowedHostnames
    // blocks the browser's own loopback CDP endpoint, and every proxied
    // navigation fails before it starts. An absent/empty allowlist stays
    // empty: it means "no allowlist", not "allow only this host".
    ...(ssrfPolicy?.hostnameAllowlist?.length
      ? { hostnameAllowlist: uniqueStrings([...ssrfPolicy.hostnameAllowlist, hostname]) }
      : {}),
  };
}`,
    },
  ],
  'extension/src/browser/cdp.ts': [
    {
      desc: 'let callers create automation-only tabs without activating the headed browser window',
      transform: (source) =>
        applyExactReplacements(source, [
          [
            `  cdpUrl: string;\n  url: string;\n  ssrfPolicy?: SsrFPolicy;`,
            `  cdpUrl: string;\n  url: string;\n  background?: boolean;\n  navigationPolicy?: ReturnType<typeof withBrowserNavigationPolicy>;\n  ssrfPolicy?: SsrFPolicy;`,
          ],
          [
            `    url: opts.url,\n    ...withBrowserNavigationPolicy(opts.ssrfPolicy),`,
            `    url: opts.url,\n    ...(opts.navigationPolicy ?? withBrowserNavigationPolicy(opts.ssrfPolicy)),`,
          ],
          [
            `          const created = (await send("Target.createTarget", { url: opts.url })) as {`,
            `          const created = (await send("Target.createTarget", {\n            url: opts.url,\n            background: opts.background === true,\n          })) as {`,
          ],
        ]),
    },
  ],
  'extension/src/browser/routes/tabs.ts': [
    {
      desc: 'carry the background-open intent from the neutral runtime into tab creation',
      transform: (source) =>
        applyExactReplacements(source, [
          [
            `      const url = toStringOrEmpty((req.body as { url?: unknown })?.url);\n      const label = readOptionalTabLabel(req.body);`,
            `      const url = toStringOrEmpty((req.body as { url?: unknown })?.url);\n      const label = readOptionalTabLabel(req.body);\n      const background = (req.body as { background?: unknown })?.background === true;`,
          ],
          [
            `          const tab = await profileCtx.openTab(url, { label });`,
            `          const tab = await profileCtx.openTab(url, { label, background });`,
          ],
        ]),
    },
  ],
  'extension/src/browser/server-context.selection.ts': [
    {
      desc: 'keep the implicit first tab used by agent navigation in the background',
      transform: (source) =>
        applyExactReplacements(source, [
          [
            `  openTab: (url: string) => Promise<BrowserTab>;`,
            `  openTab: (url: string, opts?: { background?: boolean }) => Promise<BrowserTab>;`,
          ],
          [
            `        openedTab = await openTab("about:blank");`,
            `        openedTab = await openTab("about:blank", { background: true });`,
          ],
        ]),
    },
  ],
  'extension/src/browser/server-context.tab-ops.ts': [
    {
      desc: 'propagate background tab creation to the managed Chrome CDP target',
      transform: (source) =>
        applyExactReplacements(source, [
          [
            `  openTab: (url: string, opts?: { label?: string }) => Promise<BrowserTab>;`,
            `  openTab: (url: string, opts?: { label?: string; background?: boolean }) => Promise<BrowserTab>;`,
          ],
          [
            `  const openTab = async (url: string, opts?: { label?: string }): Promise<BrowserTab> => {`,
            `  const openTab = async (\n    url: string,\n    opts?: { label?: string; background?: boolean },\n  ): Promise<BrowserTab> => {`,
          ],
          [
            `      cdpUrl: profile.cdpUrl,\n      url,\n      ssrfPolicy: getCdpControlPolicy(),`,
            `      cdpUrl: profile.cdpUrl,\n      url,\n      background: opts?.background,\n      navigationPolicy: ssrfPolicyOpts,\n      ssrfPolicy: getCdpControlPolicy(),`,
          ],
          [
            `    const createdViaCdp = await createTargetViaCdp(createTargetOpts)\n      .then((r) => r.targetId)\n      .catch(() => null);`,
            `    const createdViaCdp = await createTargetViaCdp(createTargetOpts)\n      .then((r) => r.targetId)\n      .catch((err: unknown) => {\n        if (opts?.background === true) {\n          throw err;\n        }\n        return null;\n      });`,
          ],
        ]),
    },
  ],
  'extension/src/browser/server-context.types.ts': [
    {
      desc: 'type the host-only background option on profile tab operations',
      find: `  openTab: (url: string, opts?: { label?: string }) => Promise<BrowserTab>;`,
      replace: `  openTab: (url: string, opts?: { label?: string; background?: boolean }) => Promise<BrowserTab>;`,
    },
  ],
  'extension/src/browser/chrome.ts': [
    {
      desc: 'reuse the bounded CDP command helper for graceful Windows Chrome shutdown',
      find: `  openCdpWebSocket,\n} from "./cdp.helpers.js";`,
      replace: `  openCdpWebSocket,\n  withCdpSocket,\n} from "./cdp.helpers.js";`,
    },
    {
      desc: 'close Windows Chrome via CDP and wait for actual process exit before force-stop',
      find: `    if (proc.killed) {
      return;
    }
    try {
      proc.kill("SIGTERM");
    } catch {
      // ignore
    }

    const start = Date.now();
    while (Date.now() - start < timeoutMs) {
      if (!proc.exitCode && proc.killed) {
        break;
      }
      if (
        !(await isChromeReachable(cdpUrlForPort(running.cdpPort), CHROME_STOP_PROBE_TIMEOUT_MS))
      ) {
        return;
      }
      const remainingMs = timeoutMs - (Date.now() - start);`,
      replace: `    if (proc.exitCode != null || proc.signalCode != null) {
      return;
    }
    // LOCAL PATCH (Cindy, via sync.mjs): Windows SIGTERM force-kills too.
    // Ask Chrome to flush and close via CDP, within the existing grace period.
    const start = Date.now();
    if (!proc.killed && process.platform === "win32" && timeoutMs > 0) {
      try {
        // Discovery, WebSocket handshake and command each share the budget.
        const cdpTimeoutMs = Math.max(1, Math.floor(timeoutMs / 3));
        const wsUrl = await getChromeWebSocketUrl(
          cdpUrlForPort(running.cdpPort), cdpTimeoutMs,
        );
        if (wsUrl && proc.exitCode == null && proc.signalCode == null && Date.now() - start < timeoutMs) {
          await withCdpSocket(wsUrl, (send) => send("Browser.close"), {
            handshakeTimeoutMs: cdpTimeoutMs,
            commandTimeoutMs: cdpTimeoutMs,
            handshakeRetries: 0,
          });
        }
      } catch {
        // Closing Chrome can drop CDP before replying. Still wait for exit.
      }
    } else if (!proc.killed && process.platform !== "win32") {
      try {
        proc.kill("SIGTERM");
      } catch {
        // ignore
      }
    }

    while (true) {
      // CDP can disappear while Chrome is still flushing its profile.
      if (proc.exitCode != null || proc.signalCode != null) {
        return;
      }
      const remainingMs = timeoutMs - (Date.now() - start);
      if (remainingMs <= 0) break;`,
    },
    {
      desc: 'start headed automation Chrome without an empty foreground window',
      find: `  if (headlessMode.headless) {\n    args.push("--headless=new");\n    args.push("--disable-gpu");\n  }`,
      replace: `  if (headlessMode.headless) {\n    args.push("--headless=new");\n    args.push("--disable-gpu");\n  } else {\n    args.push("--no-startup-window");\n  }`,
    },
    {
      desc: 'expose managed-profile PID lookup so the host can confirm process exit from the OS, not from CDP endpoint silence (a stalled Chrome stops answering while still alive)',
      find: `function clearChromeSingletonArtifacts(userDataDir: string) {`,
      replace: `/**
 * PID of the live Chrome owning this managed profile, or null if none.
 *
 * Reads the profile's SingletonLock and confirms the process actually exists,
 * so callers can distinguish "the process is gone" from "the CDP endpoint went
 * quiet" — a busy or stalled Chrome produces the latter while still running.
 */
export function readManagedProfileOwnerPid(userDataDir: string): number | null {
  return readCurrentHostSingletonPid(userDataDir);
}

/**
 * Whether this exact PID holds the CDP port.
 *
 * Positive identity, unlike the lock alone: the lock records a PID that the OS
 * may since have recycled, so anything destructive must confirm the process it
 * is about to signal is really the browser. Returns false on platforms with no
 * probe (Windows), which keeps callers fail-safe rather than fail-destructive.
 */
export function managedProfilePidOwnsCdpPort(pid: number, cdpPort: number): boolean {
  return pidListensOnPort(pid, cdpPort);
}

/**
 * Whether this PID is a Chrome launched for exactly this profile and port.
 *
 * Identity from the process itself, not inferred from what it happens to hold:
 * holding a port proves only that something is listening, and a port freed by
 * an exited Chrome can be taken over by anything. Required before anything
 * destructive — the command line must carry both our --user-data-dir and our
 * --remote-debugging-port. Returns false wherever the command line cannot be
 * read, so callers fail safe rather than fail destructive.
 */
export function pidIsManagedChromeForProfile(params: {
  pid: number;
  cdpPort: number;
  userDataDir: string;
}): boolean {
  if (!processExists(params.pid)) return false;
  const command = readManagedProcessCommandLine(params.pid);
  if (!command) return false;
  return (
    managedCommandHasExactArg(command, \`--remote-debugging-port=\${params.cdpPort}\`) &&
    managedCommandHasExactArg(command, \`--user-data-dir=\${params.userDataDir}\`)
  );
}

/**
 * Exact-argument match for a process command line.
 *
 * NOT processCommandHasArg: that falls back to \`text.includes\` when argv is
 * unavailable, which it always is on Darwin (ps yields a flat string). A
 * substring test accepts \`--user-data-dir=<dir>-backup\` for \`<dir>\`, and this
 * result gates SIGTERM/SIGKILL — so an unrelated Chrome could be killed. Where
 * argv exists the element comparison is already exact; otherwise require a
 * whitespace or quote delimiter on both sides.
 */
function managedCommandHasExactArg(
  command: { argv: string[] | null; text: string },
  expected: string,
): boolean {
  if (command.argv) {
    return command.argv.includes(expected);
  }
  let offset = command.text.indexOf(expected);
  while (offset >= 0) {
    const before = offset === 0 ? "" : command.text[offset - 1];
    const after = command.text[offset + expected.length] ?? "";
    if ((!before || /[\\s"']/.test(before)) && (!after || /[\\s"']/.test(after))) return true;
    offset = command.text.indexOf(expected, offset + 1);
  }
  return false;
}

function clearChromeSingletonArtifacts(userDataDir: string) {`,
    },
    {
      desc: 'decorate Chrome chip with host displayName so Cindy-real stays disk-only',
      find: `  fs.mkdirSync(userDataDir, { recursive: true });
  await ensureOutputDirectory(DEFAULT_DOWNLOAD_DIR);

  const needsDecorate = !isProfileDecorated(
    userDataDir,
    profile.name,
    (profile.color ?? DEFAULT_OPENCLAW_BROWSER_COLOR).toUpperCase(),
    DEFAULT_DOWNLOAD_DIR,
  );`,
      replace: `  fs.mkdirSync(userDataDir, { recursive: true });
  await ensureOutputDirectory(DEFAULT_DOWNLOAD_DIR);

  // LOCAL PATCH (Cindy, via sync.mjs): Chrome chip follows host displayName
  // when set so the disk key (Cindy-real) never leaks into the profile button.
  const chipName =
    normalizeOptionalString(resolved.profiles[profile.name]?.displayName) ?? profile.name;

  const needsDecorate = !isProfileDecorated(
    userDataDir,
    chipName,
    (profile.color ?? DEFAULT_OPENCLAW_BROWSER_COLOR).toUpperCase(),
    DEFAULT_DOWNLOAD_DIR,
  );`,
    },
    {
      desc: 'pass chipName into decorateOpenClawProfile instead of the disk key',
      find: `      decorateOpenClawProfile(userDataDir, {
        name: profile.name,
        color: profile.color,
        downloadDir: DEFAULT_DOWNLOAD_DIR,
      });`,
      replace: `      decorateOpenClawProfile(userDataDir, {
        name: chipName,
        color: profile.color,
        downloadDir: DEFAULT_DOWNLOAD_DIR,
      });`,
    },
  ],
  'extension/src/browser/chrome.executables.ts': [
    {
      desc: 'detect macOS Google Chrome Beta after stable Chromium-family browsers',
      find: `    {
      kind: "chromium",
      path: path.join(os.homedir(), "Applications/Chromium.app/Contents/MacOS/Chromium"),
    },
    {
      kind: "canary",`,
      replace: `    {
      kind: "chromium",
      path: path.join(os.homedir(), "Applications/Chromium.app/Contents/MacOS/Chromium"),
    },
    {
      kind: "chrome",
      path: "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
    },
    {
      kind: "chrome",
      path: path.join(
        os.homedir(),
        "Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
      ),
    },
    {
      kind: "canary",`,
    },
    {
      desc: 'classify macOS Google Chrome Beta within the Chrome-only fallback',
      find: `function findGoogleChromeExecutableMac(): BrowserExecutable | null {
  return findFirstChromeExecutable([
    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
    path.join(os.homedir(), "Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
    "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
    path.join(
      os.homedir(),
      "Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
    ),
  ]);
}`,
      replace: `function findGoogleChromeExecutableMac(): BrowserExecutable | null {
  return findFirstExecutable([
    {
      kind: "chrome",
      path: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
    },
    {
      kind: "chrome",
      path: path.join(os.homedir(), "Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
    },
    {
      kind: "chrome",
      path: "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
    },
    {
      kind: "chrome",
      path: path.join(
        os.homedir(),
        "Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
      ),
    },
    {
      kind: "canary",
      path: "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
    },
    {
      kind: "canary",
      path: path.join(
        os.homedir(),
        "Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
      ),
    },
  ]);
}`,
    },
  ],
  'extension/src/browser/config.ts': [
    {
      desc: 'preserve narrow fake-IP SSRF allowances from the host config without enabling general private-network access',
      find: `function resolveBrowserSsrFPolicy(cfg: BrowserConfig | undefined): SsrFPolicy | undefined {
  const rawPolicy = cfg?.ssrfPolicy as BrowserSsrFPolicyCompat | undefined;
  const allowPrivateNetwork = rawPolicy?.allowPrivateNetwork;
  const dangerouslyAllowPrivateNetwork = rawPolicy?.dangerouslyAllowPrivateNetwork;
  const allowedHostnames = normalizeStringList(rawPolicy?.allowedHostnames);
  const hostnameAllowlist = normalizeStringList(rawPolicy?.hostnameAllowlist);
  const hasExplicitPrivateSetting =
    allowPrivateNetwork !== undefined || dangerouslyAllowPrivateNetwork !== undefined;
  const resolvedAllowPrivateNetwork =
    dangerouslyAllowPrivateNetwork === true || allowPrivateNetwork === true;

  if (
    !resolvedAllowPrivateNetwork &&
    !hasExplicitPrivateSetting &&
    !allowedHostnames &&
    !hostnameAllowlist
  ) {
    // Keep the default policy object present so CDP guards still enforce
    // fail-closed private-network checks on unconfigured installs.
    return {};
  }

  return {
    ...(resolvedAllowPrivateNetwork ||
    dangerouslyAllowPrivateNetwork === false ||
    allowPrivateNetwork === false
      ? { dangerouslyAllowPrivateNetwork: resolvedAllowPrivateNetwork }
      : {}),
    ...(allowedHostnames ? { allowedHostnames } : {}),
    ...(hostnameAllowlist ? { hostnameAllowlist } : {}),
  };
}`,
      replace: `function resolveBrowserSsrFPolicy(cfg: BrowserConfig | undefined): SsrFPolicy | undefined {
  const rawPolicy = cfg?.ssrfPolicy as BrowserSsrFPolicyCompat | undefined;
  const allowPrivateNetwork = rawPolicy?.allowPrivateNetwork;
  const dangerouslyAllowPrivateNetwork = rawPolicy?.dangerouslyAllowPrivateNetwork;
  // LOCAL PATCH (Cindy, via sync.mjs): upstream's config resolver currently
  // drops the narrow fake-IP allowances even though the SSRF layer supports
  // them. Preserve explicit booleans so hosts can allow only proxy fake-IP
  // ranges without disabling protection for metadata, link-local, or RFC1918.
  const allowRfc2544BenchmarkRange = rawPolicy?.allowRfc2544BenchmarkRange;
  const allowIpv6UniqueLocalRange = rawPolicy?.allowIpv6UniqueLocalRange;
  const allowedHostnames = normalizeStringList(rawPolicy?.allowedHostnames);
  const hostnameAllowlist = normalizeStringList(rawPolicy?.hostnameAllowlist);
  const hasExplicitPrivateSetting =
    allowPrivateNetwork !== undefined || dangerouslyAllowPrivateNetwork !== undefined;
  const hasExplicitFakeIpSetting =
    allowRfc2544BenchmarkRange !== undefined || allowIpv6UniqueLocalRange !== undefined;
  const resolvedAllowPrivateNetwork =
    dangerouslyAllowPrivateNetwork === true || allowPrivateNetwork === true;

  if (
    !resolvedAllowPrivateNetwork &&
    !hasExplicitPrivateSetting &&
    !hasExplicitFakeIpSetting &&
    !allowedHostnames &&
    !hostnameAllowlist
  ) {
    // Keep the default policy object present so CDP guards still enforce
    // fail-closed private-network checks on unconfigured installs.
    return {};
  }

  return {
    ...(resolvedAllowPrivateNetwork ||
    dangerouslyAllowPrivateNetwork === false ||
    allowPrivateNetwork === false
      ? { dangerouslyAllowPrivateNetwork: resolvedAllowPrivateNetwork }
      : {}),
    ...(allowRfc2544BenchmarkRange !== undefined ? { allowRfc2544BenchmarkRange } : {}),
    ...(allowIpv6UniqueLocalRange !== undefined ? { allowIpv6UniqueLocalRange } : {}),
    ...(allowedHostnames ? { allowedHostnames } : {}),
    ...(hostnameAllowlist ? { hostnameAllowlist } : {}),
  };
}`,
    },
    {
      desc: 'skip upstream auto-injected "openclaw"/"user" profiles when the host provides its own (avoids CDP port 18800 collision with the managed profile + never drives the user\'s Chrome)',
      find:
        '  let profiles = ensureDefaultUserBrowserProfile(\n' +
        '    ensureDefaultProfile(\n' +
        '      cfg?.profiles,\n' +
        '      defaultColor,\n' +
        '      legacyCdpPort,\n' +
        '      cdpPortRangeStart,\n' +
        '      legacyCdpUrl,\n' +
        '    ),\n' +
        '  );',
      replace:
        '  // LOCAL PATCH (xdt-maker, via sync.mjs): when the host supplies explicit\n' +
        '  // profiles, resolve ONLY those — do not auto-inject the upstream default\n' +
        '  // "openclaw" profile (shares CDP port 18800 with the managed profile →\n' +
        '  // launch collision) nor the "user" attach-to-existing profile (we never\n' +
        '  // drive the user\'s own Chrome). Falls back to upstream behavior otherwise.\n' +
        '  let profiles =\n' +
        '    cfg?.profiles && Object.keys(cfg.profiles).length > 0\n' +
        '      ? { ...cfg.profiles }\n' +
        '      : ensureDefaultUserBrowserProfile(\n' +
        '          ensureDefaultProfile(\n' +
        '            cfg?.profiles,\n' +
        '            defaultColor,\n' +
        '            legacyCdpPort,\n' +
        '            cdpPortRangeStart,\n' +
        '            legacyCdpUrl,\n' +
        '          ),\n' +
        '        );',
    },
  ],
};

function applyExactReplacements(source, replacements) {
  let patched = source;
  for (const [find, replace, expectedCount = 1] of replacements) {
    const actualCount = patched.split(find).length - 1;
    if (actualCount !== expectedCount) {
      throw new Error(
        `LOCAL_PATCH exact replacement count mismatch (expected ${expectedCount}, found ${actualCount}). ` +
          'Upstream likely refactored the patched region — update LOCAL_PATCHES in sync.mjs.',
      );
    }
    patched = expectedCount === 1 ? patched.replace(find, replace) : patched.split(find).join(replace);
  }
  return patched;
}

/**
 * Apply any LOCAL_PATCHES registered for `relDest` to upstream `raw`. Throws if a
 * patch anchor is gone (upstream drift). Returns the patched source + the applied
 * patch descriptors (recorded into the lock for provenance).
 */
function applyLocalPatches(relDest, raw) {
  const patches = LOCAL_PATCHES[relDest];
  if (!patches) return { patched: raw, applied: [] };
  let patched = raw;
  const applied = [];
  for (const { desc, find, replace, transform } of patches) {
    if (transform) {
      patched = transform(patched);
      applied.push({ file: relDest, desc });
      continue;
    }
    if (!patched.includes(find)) {
      throw new Error(
        `LOCAL_PATCH anchor not found in ${relDest}: "${desc}". ` +
          'Upstream likely refactored the patched region — update LOCAL_PATCHES in sync.mjs.',
      );
    }
    patched = patched.replace(find, replace);
    applied.push({ file: relDest, desc });
  }
  return { patched, applied };
}

function writeGen(relDest, raw, srcLabel, hashes, appliedPatches) {
  // Normalize to POSIX separators: LOCAL_PATCHES keys and the lock's patch
  // records use '/', but path.join on win32 emits '\' — without this the
  // patches silently never match on Windows.
  relDest = relDest.replace(/\\/g, '/');
  const { patched, applied } = applyLocalPatches(relDest, raw);
  if (appliedPatches) appliedPatches.push(...applied);
  const dest = path.join(genRoot, relDest);
  fs.mkdirSync(path.dirname(dest), { recursive: true });
  fs.writeFileSync(dest, header(srcLabel) + rewriteImports(patched, dest));
  // Hash the PATCHED source so the lock's contentHash reflects local patches —
  // `--check` re-fetches upstream, re-applies patches, and must match.
  hashes[relDest] = sha256(Buffer.from(patched));
}

function main() {
  const checkMode = process.argv.includes('--check');
  ghPreflight();
  const lock = readJson(lockPath);
  const repoSlug = parseGithubRepo(lock.source.repo);
  const refArg = process.argv.find((a) => a.startsWith('--ref='));
  const ref = refArg ? refArg.slice('--ref='.length) : (lock.source.commit ?? 'main');
  // Require an explicit pinned version — never fall back to a hardcoded default.
  // A soft default would silently vendor an unpinned npm release (supply-chain
  // risk) if the lock ever omitted it.
  const fsSafeVer = lock.fsSafe?.version;
  if (!fsSafeVer || typeof fsSafeVer !== 'string') {
    throw new Error(
      'browser-runtime.lock.json: `fsSafe.version` is required (no implicit default) — ' +
        'set it explicitly to pin the vendored @openclaw/fs-safe version.',
    );
  }

  const commit = resolveRef(repoSlug, ref);
  const manifest = fs
    .readFileSync(manifestPath, 'utf8')
    .split('\n')
    .map((l) => l.trim())
    .filter((l) => l && !l.startsWith('#'));

  console.log(`[browser-runtime] ${repoSlug}@${ref} -> ${commit}`);
  console.log(`[browser-runtime] core manifest: ${manifest.length} files; fs-safe ${fsSafeVer}`);

  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'br-sync-'));
  const tar = path.join(tmp, 'oc.tar.gz');
  console.log('[browser-runtime] downloading repo tarball...');
  shHide(`gh api repos/${repoSlug}/tarball/${commit} > ${JSON.stringify(tar)}`);
  // extract extensions/browser + the two workspace pkgs + the src/ leaf areas
  shHide(
    `tar -xzf ${JSON.stringify(tar)} -C ${JSON.stringify(tmp)} --strip-components=1 ` +
      `'*/extensions/browser' '*/packages/net-policy/src' '*/packages/normalization-core/src' '*/src/infra' '*/src/security' '*/src/config'`,
  );
  const repoTmp = tmp; // strip-components=1 lands repo content directly under tmp
  const upstreamBrowser = path.join(repoTmp, 'extensions/browser');
  // Assert every expected top-level source area actually extracted. A `tar` glob
  // whose upstream path was moved/renamed extracts NOTHING silently — without this
  // a partial/empty leaf closure could still "succeed" and quietly change
  // counts/contentHash. Fail loudly + point at the fix, mirroring the same intent
  // as the per-file `manifest file missing` guard below.
  const EXPECTED_DIRS = [
    'extensions/browser',
    'packages/net-policy/src',
    'packages/normalization-core/src',
    'src/infra',
    'src/security',
    'src/config',
  ];
  for (const d of EXPECTED_DIRS) {
    if (!fs.existsSync(path.join(repoTmp, d))) {
      throw new Error(
        `extraction failed: "${d}" missing from the upstream tarball — the upstream path likely ` +
          'moved/renamed. Update the tar glob (and manifest/seeds) in sync.mjs before re-vendoring.',
      );
    }
  }

  // wipe & regenerate
  fs.rmSync(genRoot, { recursive: true, force: true });
  fs.mkdirSync(genRoot, { recursive: true });
  const hashes = {};
  const appliedPatches = [];

  // 1. browser core (133)
  for (const rel of manifest) {
    const srcFile = path.join(upstreamBrowser, rel);
    if (!fs.existsSync(srcFile)) throw new Error(`manifest file missing: ${rel}`);
    writeGen(path.join('extension', rel), fs.readFileSync(srcFile, 'utf8'), `extensions/browser/${rel}`, hashes, appliedPatches);
  }

  // 2+3. vendored workspace packages (verbatim subtree)
  let packagesCount = 0;
  for (const [pkg, srcDir] of [
    ['net-policy', path.join(repoTmp, 'packages/net-policy/src')],
    ['normalization-core', path.join(repoTmp, 'packages/normalization-core/src')],
  ]) {
    const files = fs.readdirSync(srcDir).filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts') && !f.includes('fixtures'));
    for (const f of files) {
      writeGen(path.join('packages', pkg, f), fs.readFileSync(path.join(srcDir, f), 'utf8'), `packages/${pkg}/src/${f}`, hashes, appliedPatches);
      packagesCount++;
    }
  }

  // 4. SSRF/security leaf closure (preserve src/ subtree shape under leaf/)
  const leaf = computeLeafClosure(repoTmp).filter((p) => p.startsWith('src/'));
  for (const rel of leaf) {
    writeGen(path.join('leaf', rel), fs.readFileSync(path.join(repoTmp, rel), 'utf8'), rel, hashes, appliedPatches);
  }

  // Every registered patch must have actually applied (a typo'd relDest key would
  // otherwise silently never run); assert the applied set covers LOCAL_PATCHES.
  const expectedPatchCount = Object.values(LOCAL_PATCHES).reduce((n, arr) => n + arr.length, 0);
  if (appliedPatches.length !== expectedPatchCount) {
    throw new Error(
      `LOCAL_PATCHES: expected ${expectedPatchCount} patch(es) to apply but ${appliedPatches.length} did — ` +
        'a patch key likely does not match any vendored file path.',
    );
  }

  // 5. fs-safe dist from npm (zero-dep ESM, vendored as a unit)
  console.log('[browser-runtime] packing @openclaw/fs-safe from npm...');
  const fsTmp = fs.mkdtempSync(path.join(os.tmpdir(), 'fssafe-'));
  shHide(`cd ${JSON.stringify(fsTmp)} && npm pack @openclaw/fs-safe@${fsSafeVer} >/dev/null 2>&1 && tar -xzf *.tgz`);
  const distSrc = path.join(fsTmp, 'package/dist');
  let fsSafeCount = 0;
  for (const f of fs.readdirSync(distSrc)) {
    // vendor .js + .d.ts (skip maps to keep tree lean)
    if (f.endsWith('.js') || f.endsWith('.d.ts')) {
      const raw = fs.readFileSync(path.join(distSrc, f), 'utf8');
      const dest = path.join(genRoot, 'vendor/fs-safe/dist', f);
      fs.mkdirSync(path.dirname(dest), { recursive: true });
      fs.writeFileSync(dest, raw); // fs-safe is self-contained; no rewrite needed
      hashes[`vendor/fs-safe/dist/${f}`] = sha256(Buffer.from(raw));
      fsSafeCount++;
    }
  }
  fs.copyFileSync(path.join(fsTmp, 'package/LICENSE'), path.join(genRoot, 'vendor/fs-safe/LICENSE'));

  fs.rmSync(tmp, { recursive: true, force: true });
  fs.rmSync(fsTmp, { recursive: true, force: true });

  // lock
  const counts = {
    core: manifest.length,
    packages: packagesCount,
    leaf: leaf.length,
    fsSafe: fsSafeCount,
  };
  // true total across every vendored source (was previously the misleading core-only count)
  const fileCount = counts.core + counts.packages + counts.leaf + counts.fsSafe;
  const contentHash = sha256(Buffer.from(JSON.stringify(hashes)));

  console.log(
    `[browser-runtime] generated: core=${counts.core} packages=${counts.packages} leaf=${counts.leaf} fs-safe=${counts.fsSafe} (total=${fileCount})`,
  );
  console.log(`[browser-runtime] contentHash=${contentHash.slice(0, 12)}`);

  if (checkMode) {
    // Drift detection: recompute exactly like a normal run, but compare against the
    // committed lock instead of writing. Exit non-zero on any contentHash/counts diff.
    const drift = [];
    if (lock.contentHash !== contentHash) {
      drift.push(`contentHash: committed=${lock.contentHash} recomputed=${contentHash}`);
    }
    const committedCounts = lock.counts ?? {};
    for (const key of Object.keys(counts)) {
      if (committedCounts[key] !== counts[key]) {
        drift.push(`counts.${key}: committed=${committedCounts[key]} recomputed=${counts[key]}`);
      }
    }
    if (drift.length > 0) {
      console.error('[browser-runtime] LOCK DRIFT detected vs upstream/browser-runtime.lock.json:');
      for (const d of drift) console.error(`  - ${d}`);
      console.error('[browser-runtime] run `node scripts/browser-runtime/sync.mjs` to regenerate the lock.');
      process.exit(1);
    }
    console.log('[browser-runtime] lock is up to date (contentHash + counts match).');
    return;
  }

  lock.source.commit = commit;
  lock.generated = true;
  lock.fsSafe = { package: '@openclaw/fs-safe', version: fsSafeVer };
  lock.fileCount = fileCount;
  lock.counts = counts;
  lock.patches = appliedPatches;
  lock.contentHash = contentHash;
  writeJson(lockPath, lock);

  console.log('[browser-runtime] next: typecheck to surface remaining shim gaps (src/shim/*).');
}

main();