@amg555/frameforge-mcp 2.7.6 → 2.7.7

package/.agent/skills/gstack-browse/src/xprotect-heal.ts

@@ -1,439 +0,0 @@
-/**
- * XProtect launch-kill self-heal (P0 #2554).
- *
- * macOS XProtect definition updates can start killing the exact Chromium
- * revision the committed bun.lock pins (observed: revision 1208 under
- * playwright 1.58.2 — xprotectd SIGKILLs chrome-headless-shell at spawn, so
- * the failure surfaces as a Playwright launch timeout or a "Browser closed"
- * error carrying `signal=SIGKILL`, never anything naming XProtect).
- *
- * The heal, in order, at most ONCE per process (F4):
- *   1. Classify the launch failure against the XProtect kill signature
- *      (positive AND negative fixtures under test, F9).
- *   2. Clear com.apple.quarantine on the Playwright cache bundles ONLY —
- *      a GSTACK_CHROMIUM_PATH bundle belongs to the wrapper/embedder and is
- *      never touched (same scope contract as probePoisonedChromiumBundle).
- *   3. Force-reinstall Chromium FROM THE GSTACK INSTALL ROOT (ENG-OV3: the
- *      root whose node_modules pins the same playwright-core our compiled
- *      binary embeds — a cwd-resolved `bunx playwright install` would fetch
- *      the LATEST playwright's revision, which the embedded playwright-core
- *      won't find, and the one-shot guard would then block the retry).
- *      The install is BOUNDED (~120s, process-GROUP kill on timeout; E1).
- *   4. Verify the revision dir the embedded playwright-core EXPECTS exists
- *      post-heal (registry-derived expectation, not merely install exit 0).
- *
- * Every action emits one structured stderr line (F11). When the heal cannot
- * complete (offline, timeout, no install root, one-shot spent), the caller
- * surfaces the ORIGINAL launch error plus manual
- * `bunx playwright install chromium` guidance — the CLI never hangs on it.
- */
-
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import { spawn } from 'child_process';
-import { chromium } from 'playwright';
-
-/** F11: one structured stderr line per self-heal action. */
-function logHeal(action: string, fields: Record<string, unknown> = {}): void {
-  console.error(`[browse:xprotect-heal] ${JSON.stringify({ action, ...fields })}`);
-}
-
-// ─── Classifier (F9: positives AND negatives) ────────────────────────────
-
-/**
- * Failure shapes that are definitively NOT an XProtect kill. Checked before
- * the positives so an ambiguous message never triggers a pointless reinstall:
- *   - missing executable (browser was never installed / cache wiped)
- *   - spawn-level permission errors (EACCES / EPERM / ENOENT)
- *   - Linux sandbox denials (wrong OS anyway, but the text is distinctive)
- */
-const NEGATIVE_SIGNATURES: RegExp[] = [
-  /executable doesn't exist/i,
-  /spawn\s+\S+\s+(EACCES|EPERM|ENOENT)/i,
-  /\b(EACCES|EPERM)\b/,
-  /no usable sandbox/i,
-  /failed to move to new namespace/i,
-  /suid sandbox helper/i,
-];
-
-/**
- * Failure shapes an OS-level kill produces (sourced from the #2554 report
- * plus Playwright's launch-error format): the browser process SPAWNED, then
- * died to SIGKILL, or never became ready (launch timeout with a `<launched>`
- * marker — the report's visible symptom, since xprotectd kills the child
- * without Playwright ever learning why).
- */
-const POSITIVE_SIGNATURES: RegExp[] = [
-  /<process did exit:[^>]*signal=SIGKILL/i,
-  /signal[:=]\s*['"]?SIGKILL/i,
-];
-
-/**
- * True when a launch failure message matches the macOS XProtect kill
- * signature. Platform-gated: XProtect exists only on darwin.
- */
-export function isXProtectKillSignature(
-  message: string,
-  platform: NodeJS.Platform = process.platform,
-): boolean {
-  if (platform !== 'darwin') return false;
-  if (!message) return false;
-  for (const neg of NEGATIVE_SIGNATURES) {
-    if (neg.test(message)) return false;
-  }
-  for (const pos of POSITIVE_SIGNATURES) {
-    if (pos.test(message)) return true;
-  }
-  // XProtect kill at spawn also surfaces as a launch timeout where the
-  // process DID launch (<launched> marker present) but never became ready —
-  // this is the exact symptom the #2554 report describes.
-  return /timeout \d+\s*ms exceeded/i.test(message) && /<launched>/i.test(message);
-}
-
-// ─── Playwright cache path helpers (pure) ────────────────────────────────
-
-const REVISION_DIR_RE = /^chromium(?:_headless_shell)?-\d+$/;
-
-/**
- * Walk up from a Chromium executable to its Playwright cache revision dir
- * (e.g. …/ms-playwright/chromium-1234 or …/chromium_headless_shell-1234).
- * Returns null when the executable is not in the standard cache layout.
- */
-export function findPlaywrightRevisionDir(executablePath: string): string | null {
-  let dir = path.dirname(executablePath);
-  for (let i = 0; i < 8; i++) {
-    if (REVISION_DIR_RE.test(path.basename(dir))) return dir;
-    const parent = path.dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-  return null;
-}
-
-/**
- * The Chromium revision the EMBEDDED playwright-core expects, derived from
- * the registry-computed executable path (chromium.executablePath() embeds
- * the revision from playwright-core's browsers.json — it is not read from
- * disk, so it stays correct even when nothing is installed yet).
- */
-export function expectedChromiumRevision(executablePath: string): string | null {
-  const revDir = findPlaywrightRevisionDir(executablePath);
-  if (!revDir) return null;
-  const m = path.basename(revDir).match(/-(\d+)$/);
-  return m ? m[1] : null;
-}
-
-/**
- * Find the gstack install root whose node_modules pins the SAME
- * playwright-core revision our binary embeds (ENG-OV3). Candidates:
- * the dev checkout (source runs) and the global ./setup install. A candidate
- * qualifies only when its playwright-core/browsers.json chromium revision
- * matches — running the reinstall anywhere else heals to the WRONG revision.
- */
-export function findGstackInstallRoot(
-  expectedRevision: string,
-  candidates?: string[],
-): string | null {
-  const roots = candidates ?? [
-    // Dev checkout: browse/src/ → repo root. In the compiled binary
-    // __dirname points into the bunfs bundle and won't exist on disk,
-    // so this candidate simply fails the existsSync below.
-    path.resolve(__dirname, '..', '..'),
-    // Global install root (the ./setup target). os.homedir() rather than
-    // process.env.HOME: with HOME unset the env form produced the RELATIVE
-    // path '.claude/skills/gstack' under the daemon's cwd — often an
-    // untrusted repo being QA'd, whose planted node_modules would then be
-    // where the heal runs the playwright install (repo-controlled code
-    // execution). The absolute-or-skip guard below backstops the class.
-    path.join(os.homedir(), '.claude', 'skills', 'gstack'),
-  ];
-  for (const root of roots) {
-    if (!path.isAbsolute(root)) continue;
-    try {
-      const browsersJson = path.join(root, 'node_modules', 'playwright-core', 'browsers.json');
-      if (!fs.existsSync(browsersJson)) continue;
-      const parsed = JSON.parse(fs.readFileSync(browsersJson, 'utf-8'));
-      const rev = parsed?.browsers?.find((b: { name?: string }) => b?.name === 'chromium')?.revision;
-      if (String(rev) === String(expectedRevision)) return root;
-    } catch {
-      continue; // unreadable/malformed candidate — try the next one
-    }
-  }
-  return null;
-}
-
-// ─── Quarantine clear ────────────────────────────────────────────────────
-
-function defaultRunXattr(target: string): number | null {
-  const res = Bun.spawnSync(['xattr', '-dr', 'com.apple.quarantine', target], {
-    windowsHide: true,
-    stdout: 'pipe',
-    stderr: 'pipe',
-    timeout: 10_000,
-  });
-  return res.exitCode;
-}
-
-/**
- * Clear com.apple.quarantine on every chromium* revision dir in the
- * Playwright cache (the headless shell is what XProtect actually killed in
- * #2554; the headed bundle rides along so a later headed launch doesn't
- * re-trip). Scope contract mirrors probePoisonedChromiumBundle: NEVER act
- * on a GSTACK_CHROMIUM_PATH bundle — that belongs to the wrapper/embedder.
- * Best-effort: xattr failures are logged, never thrown (the forced
- * reinstall below is the real heal).
- */
-export function clearQuarantineOnPlaywrightCache(
-  executablePath: string,
-  runXattr: (target: string) => number | null = defaultRunXattr,
-): boolean {
-  const customPath = process.env.GSTACK_CHROMIUM_PATH;
-  if (customPath && path.resolve(executablePath) === path.resolve(customPath)) {
-    logHeal('quarantine-clear-skipped', { reason: 'custom-chromium-path' });
-    return false;
-  }
-  const revDir = findPlaywrightRevisionDir(executablePath);
-  if (!revDir) {
-    logHeal('quarantine-clear-skipped', { reason: 'not-in-playwright-cache', executablePath });
-    return false;
-  }
-  const cacheRoot = path.dirname(revDir);
-  let cleared = 0;
-  let entries: string[];
-  try {
-    entries = fs.readdirSync(cacheRoot);
-  } catch (err) {
-    logHeal('quarantine-clear-skipped', {
-      reason: 'cache-unreadable',
-      error: err instanceof Error ? err.message : String(err),
-    });
-    return false;
-  }
-  for (const entry of entries) {
-    if (!REVISION_DIR_RE.test(entry)) continue;
-    const target = path.join(cacheRoot, entry);
-    try {
-      const exitCode = runXattr(target);
-      // Non-zero usually means "no such xattr" — nothing to clear, fine.
-      logHeal('quarantine-clear', { target, exitCode });
-      cleared++;
-    } catch (err) {
-      logHeal('quarantine-clear', {
-        target,
-        error: err instanceof Error ? err.message : String(err),
-      });
-    }
-  }
-  return cleared > 0;
-}
-
-// ─── Bounded forced reinstall (E1) ───────────────────────────────────────
-
-export const XPROTECT_REINSTALL_TIMEOUT_MS = 120_000;
-
-export interface ReinstallResult {
-  ok: boolean;
-  reason?: string;
-  exitCode?: number | null;
-}
-
-/**
- * Run `bunx playwright install --force chromium` from the gstack install
- * root, bounded at ~120s. The child gets its own process group (detached)
- * so a timeout kills the WHOLE tree (bunx → playwright CLI → download
- * workers), never leaving a zombie download saturating the network.
- */
-export function runBoundedChromiumReinstall(
-  installRoot: string,
-  timeoutMs: number = XPROTECT_REINSTALL_TIMEOUT_MS,
-): Promise<ReinstallResult> {
-  return new Promise((resolve) => {
-    let settled = false;
-    let child: ReturnType<typeof spawn>;
-    try {
-      child = spawn('bunx', ['playwright', 'install', '--force', 'chromium'], {
-        cwd: installRoot,
-        detached: true, // own process group → group-kill on timeout
-        stdio: ['ignore', 'ignore', 'pipe'],
-        windowsHide: true,
-      });
-    } catch (err) {
-      resolve({ ok: false, reason: `spawn-error: ${err instanceof Error ? err.message : String(err)}` });
-      return;
-    }
-    let stderrTail = '';
-    child.stderr?.on('data', (d: Buffer) => {
-      stderrTail = (stderrTail + String(d)).slice(-2000);
-    });
-    const timer = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      try {
-        if (child.pid) process.kill(-child.pid, 'SIGKILL'); // whole group
-      } catch (err: unknown) {
-        if ((err as NodeJS.ErrnoException)?.code !== 'ESRCH') {
-          try { child.kill('SIGKILL'); } catch { /* already gone */ }
-        }
-      }
-      resolve({ ok: false, reason: 'timeout' });
-    }, timeoutMs);
-    child.on('error', (err) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      resolve({ ok: false, reason: `spawn-error: ${err.message}` });
-    });
-    child.on('exit', (code) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (code === 0) {
-        resolve({ ok: true, exitCode: code });
-      } else {
-        resolve({
-          ok: false,
-          reason: `install-exit-${code}${stderrTail ? `: ${stderrTail.slice(-300)}` : ''}`,
-          exitCode: code,
-        });
-      }
-    });
-  });
-}
-
-// ─── One-shot orchestration (F4) ─────────────────────────────────────────
-
-let healAttempted = false;
-
-/** Test seam only — production never resets the one-shot guard. */
-export function resetXProtectHealForTests(): void {
-  healAttempted = false;
-}
-
-export interface XProtectHealDeps {
-  platform?: NodeJS.Platform;
-  executablePath?: () => string;
-  clearQuarantine?: (execPath: string) => boolean;
-  installRoot?: (expectedRevision: string) => string | null;
-  runReinstall?: (installRoot: string) => Promise<ReinstallResult>;
-  verifyInstalled?: (execPath: string) => boolean;
-}
-
-/**
- * Attempt the XProtect self-heal for a classified launch failure.
- *
- * Returns true when the heal completed AND the revision dir the embedded
- * playwright-core expects exists on disk — the caller should retry the
- * launch exactly once. Returns false when the error doesn't match the
- * signature, the launch used a custom executable, the one-shot guard
- * already fired, or any heal step failed (the caller then surfaces the
- * original error + manual guidance).
- */
-export async function maybeHealXProtectKill(
-  err: unknown,
-  opts: { usesCustomExecutable?: boolean } = {},
-  deps: XProtectHealDeps = {},
-): Promise<boolean> {
-  const message = err instanceof Error ? err.message : String(err);
-  if (!isXProtectKillSignature(message, deps.platform ?? process.platform)) return false;
-  if (opts.usesCustomExecutable) {
-    // A GSTACK_CHROMIUM_PATH bundle belongs to the wrapper/embedder — never
-    // quarantine-clear or reinstall over it (probePoisonedChromiumBundle's
-    // scope contract).
-    logHeal('skip', { reason: 'custom-executable' });
-    return false;
-  }
-  if (healAttempted) {
-    logHeal('skip', { reason: 'already-attempted-this-process' });
-    return false;
-  }
-  healAttempted = true; // F4: at most one heal per process, even on failure
-  logHeal('classified', { signature: 'xprotect-kill' });
-
-  const execPath = (deps.executablePath ?? (() => chromium.executablePath()))();
-  (deps.clearQuarantine ?? clearQuarantineOnPlaywrightCache)(execPath);
-
-  const revision = expectedChromiumRevision(execPath);
-  if (!revision) {
-    logHeal('reinstall-skipped', { reason: 'no-revision-in-path', execPath });
-    return false;
-  }
-  const root = (deps.installRoot ?? findGstackInstallRoot)(revision);
-  if (!root) {
-    // No install root pins our revision — a cwd-resolved install would heal
-    // to the WRONG revision (ENG-OV3), so surface guidance instead.
-    logHeal('reinstall-skipped', { reason: 'no-install-root', revision });
-    return false;
-  }
-
-  logHeal('reinstall-start', { installRoot: root, revision, timeoutMs: XPROTECT_REINSTALL_TIMEOUT_MS });
-  const result = await (deps.runReinstall ?? runBoundedChromiumReinstall)(root);
-  if (!result.ok) {
-    logHeal('reinstall-failed', { reason: result.reason });
-    return false;
-  }
-
-  // F9/ENG-OV3: assert the revision dir the embedded playwright-core
-  // EXPECTS exists post-heal — install exit 0 alone can mean "installed the
-  // wrong revision" when resolution went sideways.
-  const verify = deps.verifyInstalled ?? ((p: string) => fs.existsSync(p));
-  if (!verify(execPath)) {
-    logHeal('verify-failed', { expected: execPath });
-    return false;
-  }
-  logHeal('reinstall-ok', { installRoot: root, revision });
-  return true;
-}
-
-/**
- * Original launch error + manual remediation, for classified failures the
- * heal could not fix (offline, timeout, one-shot spent, no install root).
- */
-export function buildXProtectGuidance(originalMessage: string): string {
-  return (
-    `${originalMessage}\n` +
-    '[browse] This launch failure matches the macOS XProtect kill signature (#2554): ' +
-    "the OS killed Playwright's Chromium at spawn. Automatic self-heal did not complete. " +
-    'Fix manually: run `bunx playwright install chromium` from your gstack install ' +
-    '(the directory whose node_modules pins playwright — ~/.claude/skills/gstack for ' +
-    'global installs), then retry.'
-  );
-}
-
-/**
- * Wrap a Playwright launch call with the XProtect self-heal: on a classified
- * failure, heal once and retry the launch once. On a classified failure the
- * heal could not fix, throw the ORIGINAL error text augmented with manual
- * guidance. Unclassified failures pass through untouched.
- */
-export async function launchWithXProtectHeal<T>(
-  doLaunch: () => Promise<T>,
-  opts: { usesCustomExecutable?: boolean } = {},
-  deps: XProtectHealDeps = {},
-): Promise<T> {
-  try {
-    return await doLaunch();
-  } catch (err) {
-    const healed = await maybeHealXProtectKill(err, opts, deps);
-    if (healed) {
-      logHeal('retry-launch', {});
-      try {
-        return await doLaunch();
-      } catch (retryErr) {
-        // The heal ran but the retry died too. Without this wrap the second
-        // error propagated raw and the manual-remediation guidance was lost
-        // exactly when the automatic path had just proven insufficient.
-        const retryMessage = retryErr instanceof Error ? retryErr.message : String(retryErr);
-        if (isXProtectKillSignature(retryMessage, deps.platform ?? process.platform)) {
-          throw new Error(buildXProtectGuidance(retryMessage), { cause: retryErr });
-        }
-        throw retryErr;
-      }
-    }
-    const message = err instanceof Error ? err.message : String(err);
-    if (isXProtectKillSignature(message, deps.platform ?? process.platform)) {
-      throw new Error(buildXProtectGuidance(message), { cause: err });
-    }
-    throw err;
-  }
-}