@trusty-squire/mcp 1.1.13-rc.8 → 1.1.13

package/dist/bot/google-login.js

@@ -1,45 +1,29 @@
 // google-login.ts — Phase 1, T2 (/plan-eng-review).
 //
-// Ensures the bot's persistent Chrome profile holds a valid Google
-// session. This is the one-time interactive login; every signup after
-// it is fully automated.
+// Establishes and reads the provider sessions in the bot's persistent Chrome
+// profile. `connect` (install/cli.ts) is the ONLY caller that opens a login;
+// every signup after it is fully automated.
 //
-// TWO PATHS, by environment — deliberately just two (decided after the
-// 2026-05-17 spike). Tailscale and Codespaces/Replit-native forwarding
-// were considered and dropped: they add environment-detection code for
-// a minority of users, and the cloudflared tunnel covers everyone.
+// The login browser is always PLAIN Chrome (launchPlainLoginBrowser): no
+// `--remote-debugging-port`, no `connectOverCDP`. Google's OAuth secure-browser
+// check rejects a CDP attach (STATE.md 2026-07-20), so the CDP login path was
+// deleted along with the `login` subcommand rather than kept beside it.
+// Completion therefore never comes off a live BrowserContext — it arrives out
+// of band from the install claim plus its nonce-scoped Finish callback.
 //
-//   1. A display is available → launch Chrome headed. A window opens,
-//      the user logs in. No virtual display, no noVNC, no tunnel.
-//
-//   2. Headless (no DISPLAY) → run Chrome on a phone-shaped virtual
-//      display (Xvfb), bridge it out with x11vnc + noVNC + a cloudflared
-//      tunnel, and print one URL + a VNC password. The user logs in from
-//      any browser on any network. The per-session stack and public URL
-//      are removed when the flow completes, times out, errors, or is
-//      interrupted; an operator-managed named tunnel remains external.
-//
-// Binaries the headless path needs: Xvfb, x11vnc, websockify
-// (with /usr/share/novnc), cloudflared, and Google Chrome. Missing ones
-// produce a clear, actionable error rather than a cryptic crash.
-import { spawn } from "node:child_process";
+// Interactive login uses a local visible Chrome window when one exists. On a
+// headless host it starts a login-scoped Xvfb + noVNC tunnel so a human can
+// drive that same browser remotely. Automated operator sessions do not use
+// this module's display stack and remain on Chrome's new-headless path.
 import { createRequire } from "node:module";
-import { createServer } from "node:net";
-import { cpSync, chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
-import Database from "better-sqlite3";
-import boxen from "boxen";
 import chalk from "chalk";
-import { shortenVncUrl } from "../api-client.js";
-import { CHROME_PROFILE_DIR, closeProfileWithProof, currentProfileHolderPid, launchWithProfileGate, profileProcessIdentity, PROFILE_BUSY_MESSAGE, ProfileBusyError, reapProfileHolderIfOwned, waitForProfileFree, withProfileOperationGuard, } from "./profile.js";
-import { isSelfManagedChromeTerminationSignalExitEnabled, launchPlainLoginBrowser, launchSelfManagedLoginContext, resolveChannelBinary, selfLaunchEnabled, setSelfManagedChromeTerminationSignalExitEnabled, } from "./browser.js";
-export { extractGoogleAccountEmail } from "./browser.js";
+import { CHROME_PROFILE_DIR, closeProfileWithProof, currentProfileHolderPid, launchWithProfileGate, profileProcessIdentity, PROFILE_BUSY_MESSAGE, ProfileBusyError, waitForProfileFree, withProfileOperationGuard, } from "./profile.js";
+import { closeBrowserContextWithin, extractGoogleAccountEmail, launchPlainLoginBrowser, registerLocalBrowserLaunch, resolveChannelBinary, } from "./browser.js";
+export { extractGoogleAccountEmail };
 import { startInstallCompletionListener, withInstallCompletionCallback, } from "./install-completion.js";
-import { markProviderLoggedIn } from "./login-state.js";
-import { randomBytes } from "node:crypto";
-import { canPublishOperatorProfileSeed, GOOGLE_LOGIN_COOKIE_MARKERS, publishOperatorProfileSeed, } from "./operator-profile-pool.js";
+import { bindOwnerBrowserLaunch, markOwnerBrowserLaunchTerminal, terminateOwnerBrowserLaunch, untrackOwnerBrowserLaunch, } from "./owner-process-reaper.js";
+import { assertRemoteLoginRigLive, createRemoteLoginRig, exposeRemoteLoginDisplay, registerRemoteLoginRigCleanup, remoteLoginEnvironment, startRemoteLoginDisplay, teardownRemoteLoginRig, } from "./remote-login-display.js";
+export { extractOAuthScopes, scopesAreBasic, scrapeGoogleScopePhrases } from "./oauth-scope.js";
 const require = createRequire(import.meta.url);
 function loginProxyOption() {
     return undefined;
@@ -47,11 +31,57 @@ function loginProxyOption() {
 function selfLaunchProxyDisposition(proxy) {
     return proxy === undefined ? null : { server: proxy.server };
 }
-export async function launchPersistentLoginContext(launcher, userDataDir, options) {
-    return await launcher.launchPersistentContext(userDataDir, {
-        ...options,
-        channel: "chrome",
-    });
+export async function launchPersistentLoginContext(launcher, userDataDir, options, runtime = {}) {
+    const register = runtime.registerLocalBrowserLaunch ?? registerLocalBrowserLaunch;
+    const markTerminal = runtime.markTerminal ?? markOwnerBrowserLaunchTerminal;
+    const terminate = runtime.terminate ?? terminateOwnerBrowserLaunch;
+    const untrack = runtime.untrack ?? untrackOwnerBrowserLaunch;
+    const ownership = register(userDataDir, options.env ?? process.env);
+    let context = null;
+    try {
+        context = await launcher.launchPersistentContext(userDataDir, {
+            ...options,
+            env: ownership.env,
+            channel: "chrome",
+        });
+        const bindLaunch = runtime.bindLaunch ??
+            ((marker, profileDir) => {
+                const holderPid = currentProfileHolderPid(profileDir);
+                const identity = holderPid === null ? null : profileProcessIdentity(holderPid, profileDir);
+                return identity !== null && bindOwnerBrowserLaunch(marker, identity);
+            });
+        if (!bindLaunch(ownership.marker, userDataDir)) {
+            throw new Error("persistent login browser identity could not be bound to owner custody");
+        }
+    }
+    catch (error) {
+        markTerminal(ownership.marker);
+        if (context !== null)
+            await closeBrowserContextWithin(context, runtime.closeTimeoutMs);
+        if (await terminate(ownership.marker, userDataDir).catch(() => false)) {
+            untrack(ownership.marker);
+        }
+        throw error;
+    }
+    if (context === null)
+        throw new Error("persistent login browser did not start");
+    const boundContext = context;
+    let closing;
+    return {
+        context: boundContext,
+        marker: ownership.marker,
+        close: () => {
+            closing ??= (async () => {
+                markTerminal(ownership.marker);
+                await closeBrowserContextWithin(boundContext, runtime.closeTimeoutMs);
+                const terminated = await terminate(ownership.marker, userDataDir).catch(() => false);
+                if (!terminated)
+                    throw new Error("persistent login browser closure unproven");
+                untrack(ownership.marker);
+            })();
+            return closing;
+        },
+    };
 }
 function resolveChromium() {
     try {
@@ -64,91 +94,58 @@ function resolveChromium() {
         return require("playwright").chromium;
     }
 }
+async function detectGoogleAccountEmailInContext(context) {
+    let page = null;
+    try {
+        page = await context.newPage();
+        await page.goto("https://myaccount.google.com/", {
+            waitUntil: "domcontentloaded",
+            timeout: 20_000,
+        });
+        if (new URL(page.url()).hostname !== "myaccount.google.com")
+            return null;
+        const labels = await page
+            .locator("[aria-label]")
+            .evaluateAll((elements) => elements.map((element) => element.getAttribute("aria-label") ?? ""));
+        for (const label of labels) {
+            const email = extractGoogleAccountEmail(label.trim());
+            if (email !== null)
+                return email;
+        }
+        return null;
+    }
+    catch (err) {
+        // A probe failure is NOT proof of "signed out", but every caller treats a
+        // null the same way, so name it. Losing this line is how a broken probe
+        // reads as an empty profile.
+        console.error(`[connect] Google identity probe failed: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    finally {
+        await page?.close().catch(() => undefined);
+    }
+}
 const LOGIN_TARGETS = {
     google: {
         provider: "google",
         label: "Google",
-        loginUrl: "https://accounts.google.com/",
         cookieOrigin: "https://www.google.com",
-        cookies: GOOGLE_LOGIN_COOKIE_MARKERS,
+        cookies: ["__Secure-1PSID", "SID", "HSID", "SSID", "APISID", "SAPISID"],
     },
     github: {
         provider: "github",
         label: "GitHub",
-        loginUrl: "https://github.com/login",
         cookieOrigin: "https://github.com",
         cookies: ["user_session", "__Host-user_session_same_site"],
     },
 };
-// Phone-shaped virtual display — portrait so it scales cleanly onto a
-// phone via noVNC (the spike's 1920x1080 was the UX mistake). 720x1280
-// is the smallest size that doesn't look pixel-y on a 1080p+ phone
-// screen, and stays bandwidth-friendly compared to 1080x1920.
-// Overridable via BOT_NOVNC_W/H — a desktop-width display (e.g. 1440x900) is
-// needed when the remote page is a responsive app whose desktop-only controls
-// (hover-revealed row menus in the Workspace Admin console) collapse at phone
-// width. Defaults stay phone-shaped for the common login-from-phone case.
-const HEADLESS_W = Number(process.env.BOT_NOVNC_W) || 720;
-const HEADLESS_H = Number(process.env.BOT_NOVNC_H) || 1280;
-// The Debian/Ubuntu `novnc` package installs its web assets here — the
-// `core/` RFB library our branded page reuses (see runHeadlessChrome).
-const NOVNC_INSTALL_DIR = "/usr/share/novnc";
-// Resolve a bundled login asset (the branded vnc.html / interstitial).
-// `../../assets/login/` from this module resolves to apps/mcp/assets/
-// whether running from src/ (tsx) or dist/ (compiled) — assets/ sits
-// beside both. Shipped via the package.json `files` allowlist.
-function loginAssetPath(name) {
-    return fileURLToPath(new URL(`../../assets/login/${name}`, import.meta.url));
-}
 // --- session detection -------------------------------------------------
 async function hasProviderSession(context, target) {
-    const cookies = await context.cookies(target.cookieOrigin);
-    return cookies.some((c) => target.cookies.includes(c.name));
-}
-// Exported for the connect claim loop: does this LIVE context already hold the
-// given provider's session cookies? The force-relogin teardown gates on this so
-// it never closes the noVNC on the bare API claim while the interactive sign-in
-// (e.g. Google's cold-profile second challenge) is still in flight.
-export async function contextHasProviderSession(context, provider) {
-    return hasProviderSession(context, LOGIN_TARGETS[provider]);
-}
-const PROVIDER_COOKIE_MARKERS = {
-    google: GOOGLE_LOGIN_COOKIE_MARKERS,
-    github: ["user_session"],
-};
-export function profileHasProviderCookies(profileDir, provider) {
-    const markers = PROVIDER_COOKIE_MARKERS[provider];
-    const bases = [join(profileDir, "Default", "Cookies"), join(profileDir, "Cookies")];
-    const root = provider === "google" ? "google.com" : "github.com";
-    for (const path of bases) {
-        if (!existsSync(path))
-            continue;
-        let db = null;
-        try {
-            db = new Database(path, {
-                readonly: true,
-                fileMustExist: true,
-                timeout: 250,
-            });
-            const placeholders = markers.map(() => "?").join(", ");
-            const row = db
-                .prepare(`SELECT 1
-             FROM cookies
-            WHERE (host_key = ? OR host_key = ? OR host_key LIKE ?)
-              AND name IN (${placeholders})
-            LIMIT 1`)
-                .get(root, `.${root}`, `%.${root}`, ...markers);
-            if (row !== undefined)
-                return true;
-        }
-        catch {
-            continue;
-        }
-        finally {
-            db?.close();
-        }
+    if (target.provider === "google") {
+        return (await detectGoogleAccountEmailInContext(context)) !== null;
     }
-    return false;
+    const cookies = await context.cookies(target.cookieOrigin);
+    return cookies.some((cookie) => target.cookies.includes(cookie.name));
 }
 // VALIDATE a session instead of just spotting a cookie. A provider session that
 // expired server-side often leaves its `user_session` cookie sitting in the
@@ -157,11 +154,12 @@ export function profileHasProviderCookies(profileDir, provider) {
 // auth state — and read that, so a dead-but-present session reports false.
 // GitHub: an anonymous/expired visit sets `logged_in=no`; a live one, `=yes`.
 async function validateProviderSession(context, target) {
+    if (target.provider === "google") {
+        return (await detectGoogleAccountEmailInContext(context)) !== null;
+    }
     // Cheap negative: no session cookie at all → definitely not logged in.
     if (!(await hasProviderSession(context, target)))
         return false;
-    if (target.provider !== "github")
-        return true; // only GitHub's marker is known to lie
     const page = await context.newPage();
     try {
         await page
@@ -180,15 +178,12 @@ async function validateProviderSession(context, target) {
         await page.close().catch(() => undefined);
     }
 }
-// Inspect the bot Chrome profile on disk and return the set of OAuth
-// providers whose session cookies are currently present. The marker
-// file at logged-in-providers.json is a write-once memo from prior
-// runs and can lie (cookies expire, the user logs out from the
-// provider's site, etc.). This function is the source of truth.
+// Inspect a live bot Chrome context and return the providers whose sessions are
+// currently present. This is the source of truth for provider availability.
 //
 // Cost is ~1-1.5s for the persistent-context launch + cookie read +
 // teardown. We only call it at install boundaries (after the install
-// confirm seeds whatever provider the user clicked, before the
+// confirm establishes whichever provider the user clicked, before the
 // secondary-provider prompt fires) so the latency is acceptable.
 export async function detectActiveProviderSessions(profileDir = CHROME_PROFILE_DIR) {
     return await withProfileOperationGuard(profileDir, async () => {
@@ -196,11 +191,12 @@ export async function detectActiveProviderSessions(profileDir = CHROME_PROFILE_D
         // wait is fine: reclaim a stale lock, or briefly yield to a live run.
         await waitForProfileFree(profileDir, { deadlineMs: 15_000, pollMs: 500 });
         const chromium = resolveChromium();
-        const ctx = await launchWithProfileGate(profileDir, () => launchPersistentLoginContext(chromium, profileDir, {
+        const persistent = await launchWithProfileGate(profileDir, () => launchPersistentLoginContext(chromium, profileDir, {
             headless: true,
             ignoreDefaultArgs: ["--enable-automation"],
             args: ["--no-sandbox", "--disable-dev-shm-usage"],
         }));
+        const ctx = persistent.context;
         try {
             const present = [];
             for (const id of Object.keys(LOGIN_TARGETS)) {
@@ -209,14 +205,15 @@ export async function detectActiveProviderSessions(profileDir = CHROME_PROFILE_D
                 // just the install display. validateProviderSession is cheap: it returns
                 // a fast false when no cookie is present (no navigation), and only pays
                 // the github.com round-trip when a github cookie EXISTS and must be proven
-                // live. Google stays presence-based (it doesn't lie this way).
+                // live. Google is verified by a My Account identity probe, since its
+                // chooser cookies can survive after the account is signed out.
                 if (await validateProviderSession(ctx, LOGIN_TARGETS[id]))
                     present.push(id);
             }
             return present;
         }
         finally {
-            await ctx.close();
+            await persistent.close();
         }
     });
 }
@@ -254,102 +251,6 @@ export function classifyGoogleAuthState(url, bodyText) {
     // rather than risk it proceeding into a page it must not automate.
     return "needs_login";
 }
-// --- T7: OAuth consent scope gate --------------------------------------
-// After the bot clicks "Sign in with Google" and lands on a consent
-// screen, the OAuth signup flow auto-approves it ONLY when every scope
-// the service requested is a basic-identity scope. Anything broader
-// (Gmail/Drive/contacts) aborts the run for human review — a
-// prompt-injected or confused agent must not be able to grant a wide
-// OAuth scope on the user's behalf (see the plan's Security Boundary).
-//
-// The allowlist is Google-OIDC vocabulary. GitHub (Phase 2, D7) gets
-// its own provider-aware allowlist when that provider lands.
-const BASIC_OAUTH_SCOPES = new Set([
-    "openid",
-    "email",
-    "profile",
-    "https://www.googleapis.com/auth/userinfo.email",
-    "https://www.googleapis.com/auth/userinfo.profile",
-]);
-// Pull the OAuth `scope` parameter off a Google consent URL. Robust by
-// design (a spec refinement): a query-param read, never a DOM scrape or
-// a vision call. Google nests the real authorize request inside a
-// `continue=` (or similar) param on the consent/chooser URL, so this
-// walks nested URL-valued params up to a small depth to find `scope`.
-//
-// Returns the parsed scope list, or null when no `scope` param is
-// present anywhere — the caller treats "can't read the scopes" as
-// "can't confirm they're basic" and pauses for human review.
-//
-// Exported for unit testing — the nested-URL walk is the error-prone bit.
-export function extractOAuthScopes(rawUrl) {
-    const scopes = [];
-    const visit = (urlStr, depth) => {
-        if (scopes.length > 0 || depth > 8)
-            return;
-        let u;
-        try {
-            u = new URL(urlStr);
-        }
-        catch {
-            return;
-        }
-        const scope = u.searchParams.get("scope");
-        if (scope !== null && scope.trim().length > 0) {
-            // Google separates scopes with spaces; tolerate "+" and "," too.
-            for (const s of scope.split(/[\s,+]+/)) {
-                const trimmed = s.trim();
-                if (trimmed.length > 0)
-                    scopes.push(trimmed);
-            }
-            return;
-        }
-        // Recurse into any param whose value is itself a URL (Google's
-        // `continue`, `authError`, etc. carry the nested authorize request).
-        for (const value of u.searchParams.values()) {
-            if (/^https?:\/\//i.test(value.trim()))
-                visit(value, depth + 1);
-        }
-    };
-    visit(rawUrl, 0);
-    return scopes.length > 0 ? scopes : null;
-}
-// True when EVERY requested scope is in the basic-identity allowlist —
-// the gate for auto-approving a consent screen. An empty list returns
-// false: no scopes parsed means we could not confirm, so we do not
-// auto-approve. Exported for unit testing.
-export function scopesAreBasic(scopes) {
-    return scopes.length > 0 && scopes.every((s) => BASIC_OAUTH_SCOPES.has(s));
-}
-// Defense-in-depth for the case where extractOAuthScopes returns null
-// (no parseable scope= param) but the page IS a real scope-grant
-// consent. Google's consent screen lists each scope visually with a
-// templated verb phrase: "See your", "Manage your", "Edit your", "Send
-// email", etc. A scope-summary / account-chooser / post-grant
-// confirmation does not include these phrases. So when the URL gives
-// us nothing, the visible-text phrases are the next best signal.
-//
-// Returns the list of suspicious phrases found (each capped at 80 chars
-// so a runaway match cannot blow up the response). Empty list = the
-// page does not appear to grant any sensitive scope.
-export function scrapeGoogleScopePhrases(text) {
-    const patterns = [
-        /see\s+(?:and\s+download|and\s+manage)\s+[^.\n]+/gi,
-        /manage\s+(?:your|all|all\s+your)\s+(?:contacts|google\s+drive|photos|calendars?|tasks|mail|gmail|files|account|youtube)[^.\n]*/gi,
-        /edit\s+(?:your|all)\s+(?:contacts|google\s+drive|photos|calendars?|tasks|mail|gmail|files)[^.\n]*/gi,
-        /send\s+(?:email|mail|messages)\s+(?:on\s+your\s+behalf|as\s+you)[^.\n]*/gi,
-        /view\s+(?:your|all|all\s+your)\s+(?:contacts|google\s+drive|photos|calendars?|tasks|mail|gmail|files|youtube|location\s+history)[^.\n]*/gi,
-        /access\s+your\s+(?:google\s+drive|gmail|contacts|calendars?|photos|youtube)[^.\n]*/gi,
-        /delete\s+(?:your|all)\s+[^.\n]+/gi,
-    ];
-    const matches = new Set();
-    for (const p of patterns) {
-        for (const m of text.matchAll(p)) {
-            matches.add(m[0].slice(0, 80).trim());
-        }
-    }
-    return Array.from(matches);
-}
 // Google's "number-match" challenge (URL: /signin/challenge/dp) shows
 // ONE big number on the desktop browser; the user's phone shows three
 // options and they tap the matching one. The number is the only piece
@@ -381,290 +282,59 @@ export function extractGoogleNumberMatch(text) {
     return null;
 }
 // --- environment helpers ----------------------------------------------
-export function hasDisplay() {
-    if (process.env.TRUSTY_SQUIRE_FORCE_HEADLESS === "true")
-        return false;
-    if (process.env.TRUSTY_SQUIRE_FORCE_DISPLAY === "true")
+export function hasDisplay(platform = process.platform, env = process.env) {
+    // macOS (Aqua) and Windows (Win32) have native windowing; Linux needs
+    // an existing user-visible X display.
+    if (platform === "darwin" || platform === "win32")
         return true;
-    // macOS (Aqua) and Windows (Win32) have native windowing — Chrome
-    // opens a real window without an X server. DISPLAY is a Unix concept
-    // they don't set, so a DISPLAY-only check would have wrongly routed
-    // every Mac/Windows install into the headless+noVNC+cloudflared rig
-    // (which needs Xvfb/x11vnc/etc. that aren't installed on those
-    // platforms).
-    if (process.platform === "darwin" || process.platform === "win32")
-        return true;
-    // Linux: a non-empty DISPLAY means there's an X server we can draw to.
-    // Headless boxes often inherit an automation/Xvfb DISPLAY over SSH, though;
-    // that is NOT a human-visible desktop. Prefer noVNC for SSH/TTY Linux
-    // sessions unless explicitly overridden with TRUSTY_SQUIRE_FORCE_DISPLAY.
-    if (process.env.SSH_CONNECTION !== undefined ||
-        process.env.SSH_TTY !== undefined ||
-        process.env.XDG_SESSION_TYPE === "tty") {
+    if (typeof env.DISPLAY !== "string" || env.DISPLAY.trim().length === 0)
+        return false;
+    if ((typeof env.SSH_CONNECTION === "string" && env.SSH_CONNECTION.trim().length > 0) ||
+        (typeof env.SSH_TTY === "string" && env.SSH_TTY.trim().length > 0) ||
+        env.XDG_SESSION_TYPE?.trim().toLowerCase() === "tty") {
         return false;
     }
-    return typeof process.env.DISPLAY === "string" && process.env.DISPLAY.length > 0;
-}
-// First :N (99..120) whose X socket is free.
-function pickFreeDisplay() {
-    for (let n = 99; n <= 120; n++) {
-        if (!existsSync(`/tmp/.X11-unix/X${n}`))
-            return `:${n}`;
-    }
-    throw new Error("no free X display number in :99..:120");
-}
-// An OS-assigned free TCP port.
-export function findFreePort() {
-    return new Promise((resolve, reject) => {
-        const srv = createServer();
-        srv.on("error", reject);
-        srv.listen(0, "127.0.0.1", () => {
-            const addr = srv.address();
-            if (addr === null || typeof addr === "string") {
-                srv.close();
-                reject(new Error("could not resolve a free port"));
-                return;
-            }
-            const { port } = addr;
-            srv.close(() => resolve(port));
-        });
-    });
-}
-// Standard install locations probed IN ADDITION to $PATH. A binary can be
-// installed yet invisible to `binaryOnPath` when the process that spawned
-// this one trimmed PATH — systemd units and agent/MCP spawns routinely drop
-// /usr/local/bin, which is exactly where cloudflared lands. Probing the
-// well-known dirs stops an installed binary from being reported "missing".
-const STANDARD_BIN_DIRS = [
-    "/usr/local/bin",
-    "/usr/bin",
-    "/bin",
-    "/usr/local/sbin",
-    "/usr/sbin",
-    "/sbin",
-];
-// Is `bin` an executable on PATH (or in a standard bin dir)? A cheap
-// synchronous `command -v` that also probes well-known locations so an
-// installed-but-off-PATH binary isn't misreported as absent.
-export function binaryOnPath(bin) {
-    const dirs = [...(process.env.PATH ?? "").split(":"), ...STANDARD_BIN_DIRS];
-    return dirs.some((p) => p.length > 0 && existsSync(join(p, bin)));
-}
-// cloudflared's .deb is published per-arch; pick the suffix matching this
-// machine so the suggested install command actually resolves.
-function cloudflaredDebArch() {
-    switch (process.arch) {
-        case "arm64":
-            return "arm64";
-        case "arm":
-            return "arm";
-        case "ia32":
-            return "386";
-        default:
-            return "amd64";
-    }
-}
-// Correct remediation for the specific binaries that are missing. cloudflared
-// is NOT in Debian/Ubuntu's default repos, so an apt-get line can never
-// install it — it needs Cloudflare's own package. The rest are plain apt
-// packages (websockify's noVNC assets ship in the `novnc` package, so both).
-export function installHint(missing) {
-    const aptPkgs = missing.flatMap((n) => {
-        if (n === "Xvfb")
-            return ["xvfb"];
-        if (n === "x11vnc")
-            return ["x11vnc"];
-        if (n === "websockify")
-            return ["novnc", "websockify"];
-        return [];
-    });
-    const lines = [];
-    if (aptPkgs.length > 0) {
-        lines.push(`On Debian/Ubuntu: sudo apt-get install -y ${aptPkgs.join(" ")}`);
-    }
-    if (missing.includes("cloudflared")) {
-        const arch = cloudflaredDebArch();
-        lines.push("cloudflared is not in Debian/Ubuntu repos — install its package: " +
-            `curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-${arch}.deb ` +
-            "-o /tmp/cloudflared.deb && sudo dpkg -i /tmp/cloudflared.deb");
-    }
-    return lines.join("\n");
-}
-function requireBinaries(names) {
-    const missing = names.filter((n) => !binaryOnPath(n));
-    if (missing.length > 0) {
-        throw new Error(`headless login needs these not-installed binaries: ${missing.join(", ")}.\n` +
-            installHint(missing));
-    }
-}
-function spawnBg(cmd, args, env) {
-    const child = spawn(cmd, args, {
-        stdio: ["ignore", "pipe", "pipe"],
-        env: env ?? process.env,
-    });
-    child.on("error", (e) => console.error(`[login] ${cmd} failed to spawn: ${String(e)}`));
-    return child;
-}
-// Read cloudflared's output until it prints its public trycloudflare URL.
-// Accumulates a rolling buffer rather than matching per-chunk — the URL
-// can straddle two `data` events, and a per-chunk match would miss it
-// and hang until the timeout.
-function awaitTunnelUrl(cf, timeoutMs) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error("cloudflared did not produce a URL in time")), timeoutMs);
-        let acc = "";
-        const scan = (buf) => {
-            acc += buf.toString();
-            const m = acc.match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/);
-            if (m !== null) {
-                clearTimeout(timer);
-                resolve(m[0]);
-            }
-            // Bound memory if cloudflared is chatty before the URL appears.
-            if (acc.length > 65536)
-                acc = acc.slice(-4096);
-        };
-        cf.stdout?.on("data", scan);
-        cf.stderr?.on("data", scan);
-    });
-}
-// Width-aware, boxed VNC banner. Replaces the old hardcoded
-// `"=".repeat(64)` lines that looked broken on narrow phone-via-SSH
-// terminals and lost on wide ones. boxen handles the reflow.
-function printBanner(opts) {
-    const width = Math.max(40, Math.min((process.stdout.columns ?? 80) - 2, 78));
-    // OSC 8 hyperlink: modern terminals render the URL as cmd-clickable
-    // (label = the URL itself so it still copies cleanly). Non-TTY
-    // pipes get the raw URL — no escape garbage in logs. Wine-underlined
-    // text inside the OSC 8 wrapper preserves a visual cue on terminals
-    // that ignore the hyperlink escape.
-    const styledUrl = process.stderr.isTTY
-        ? `\x1b]8;;${opts.tunnelUrl}\x1b\\${chalk.hex("#cf3a52").underline(opts.tunnelUrl)}\x1b]8;;\x1b\\`
-        : opts.tunnelUrl;
-    const body = `Open this on any device, any network:\n\n` +
-        `  ${styledUrl}\n\n` +
-        `If asked for a VNC password:  ${chalk.bold(opts.vncPassword)}\n\n` +
-        opts.label;
-    console.error("\n" +
-        boxen(body, {
-            title: "Sign in to Trusty Squire",
-            titleAlignment: "left",
-            padding: { top: 0, bottom: 0, left: 1, right: 1 },
-            borderStyle: "single",
-            borderColor: "#cf3a52",
-            width,
-        }) +
-        "\n");
-}
-const headlessRigTeardowns = new WeakMap();
-function childHasExited(child) {
-    return child.exitCode !== null || child.signalCode !== null;
+    return true;
 }
-function waitForChildExit(child, timeoutMs) {
-    if (childHasExited(child))
-        return Promise.resolve(true);
-    return new Promise((resolve) => {
-        const onExit = () => finish(true);
-        const timer = setTimeout(() => finish(childHasExited(child)), timeoutMs);
-        const finish = (exited) => {
+export async function teardownLoginBrowser(opts) {
+    let profileState;
+    if (opts.identity === null && opts.isRunning !== undefined) {
+        const timeoutMs = opts.timeoutMs ?? 15_000;
+        let timer;
+        const closed = await Promise.race([
+            Promise.resolve()
+                .then(opts.closeBrowser)
+                .then(() => true, () => false),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), timeoutMs);
+            }),
+        ]);
+        if (timer !== undefined)
             clearTimeout(timer);
-            child.removeListener("exit", onExit);
-            resolve(exited);
+        const waitForExit = async () => {
+            const deadline = Date.now() + 2_000;
+            while (opts.isRunning() && Date.now() < deadline) {
+                await new Promise((resolve) => setTimeout(resolve, 25));
+            }
+            return !opts.isRunning();
         };
-        child.once("exit", onExit);
-    });
-}
-function removeHeadlessRigFiles(rig) {
-    if (rig.webDir !== undefined) {
-        try {
-            rmSync(rig.webDir, { recursive: true, force: true });
-        }
-        catch {
-            // best-effort
-        }
-    }
-    if (rig.passFile !== undefined) {
-        try {
-            rmSync(rig.passFile, { force: true });
-        }
-        catch {
-            // best-effort
+        if (closed && (await waitForExit()))
+            profileState = "closed";
+        else {
+            opts.forceClose();
+            profileState = (await waitForExit()) ? "closed" : "force_closed_unproven";
         }
     }
-}
-function releaseChildHandles(child) {
-    try {
-        child.stdout?.destroy();
-    }
-    catch {
-        // best-effort
-    }
-    try {
-        child.stderr?.destroy();
-    }
-    catch {
-        // best-effort
-    }
-    try {
-        child.unref();
-    }
-    catch {
-        // best-effort
-    }
-}
-function forceTeardownHeadlessRig(rig) {
-    for (const child of rig.procs) {
-        try {
-            if (!childHasExited(child))
-                child.kill("SIGKILL");
-        }
-        catch {
-            // best-effort
-        }
-        releaseChildHandles(child);
+    else {
+        profileState = await closeProfileWithProof({
+            profileDir: opts.profileDir,
+            identity: opts.identity,
+            close: opts.closeBrowser,
+            forceClose: opts.forceClose,
+            ...(opts.timeoutMs !== undefined ? { closeTimeoutMs: opts.timeoutMs } : {}),
+        });
     }
-    removeHeadlessRigFiles(rig);
-}
-export function teardownHeadlessRig(rig, graceMs = 1_000) {
-    const existing = headlessRigTeardowns.get(rig);
-    if (existing !== undefined)
-        return existing;
-    const teardown = (async () => {
-        const running = rig.procs.filter((child) => !childHasExited(child));
-        for (const child of running) {
-            try {
-                child.kill("SIGTERM");
-            }
-            catch {
-                // best-effort
-            }
-        }
-        await Promise.all(running.map((child) => waitForChildExit(child, graceMs)));
-        const resistant = running.filter((child) => !childHasExited(child));
-        for (const child of resistant) {
-            try {
-                child.kill("SIGKILL");
-            }
-            catch {
-                // best-effort
-            }
-        }
-        await Promise.all(resistant.map((child) => waitForChildExit(child, graceMs)));
-        for (const child of rig.procs)
-            releaseChildHandles(child);
-        removeHeadlessRigFiles(rig);
-    })();
-    headlessRigTeardowns.set(rig, teardown);
-    return teardown;
-}
-export async function teardownLoginBrowser(opts) {
-    return await closeProfileWithProof({
-        profileDir: opts.profileDir,
-        identity: opts.identity,
-        close: opts.closeBrowser,
-        forceClose: opts.forceClose,
-        ...(opts.timeoutMs !== undefined ? { closeTimeoutMs: opts.timeoutMs } : {}),
-    });
+    return profileState;
 }
 // --- shutdown coordination with the operator server -------------------
 // Every in-flight login run registers a cancel closure here so an external
@@ -674,16 +344,15 @@ export async function teardownLoginBrowser(opts) {
 // process identity), so cancellation never signals a PID it cannot prove
 // ownership of.
 const activeLoginBrowserCancels = new Set();
-// Exported for tests; runDisplayedChrome/runHeadlessChrome are the real
-// callers. Returns the unregister disposer for the normal completion path.
+// Returns the unregister disposer for the normal completion path.
 export function trackActiveLoginBrowser(cancel) {
     activeLoginBrowserCancels.add(cancel);
     return () => {
         activeLoginBrowserCancels.delete(cancel);
     };
 }
-// Cancel every in-flight login run's browser (and headless rig, where one
-// exists). Called by the MCP server's shutdown path; idempotent and
+// Cancel every in-flight login run's browser. Called by the MCP server's
+// shutdown path; idempotent and
 // best-effort — a failed teardown must not stall the process exit, whose
 // process-level exit hooks still force-kill anything identity-proven.
 export async function cancelActiveLoginBrowsers() {
@@ -702,6 +371,10 @@ function createTrackedLoginBrowserLifecycle(teardownRun) {
     let browserTeardown;
     let runTeardown;
     let cancellation;
+    let resolveCancellation;
+    const cancellationSignal = new Promise((resolve) => {
+        resolveCancellation = resolve;
+    });
     let finishing;
     const settleLaunch = () => {
         if (launchSettled)
@@ -724,8 +397,10 @@ function createTrackedLoginBrowserLifecycle(teardownRun) {
     let lifecycle;
     const untrack = trackActiveLoginBrowser(async () => await lifecycle.cancel());
     lifecycle = {
+        cancellation: cancellationSignal,
         cancel: () => {
             cancelled = true;
+            resolveCancellation();
             cancellation ??= (async () => {
                 await launchSettlement;
                 try {
@@ -768,570 +443,129 @@ function createTrackedLoginBrowserLifecycle(teardownRun) {
     };
     return lifecycle;
 }
-const selfManagedSignalExitCoordination = {
-    enabled: isSelfManagedChromeTerminationSignalExitEnabled,
-    set: setSelfManagedChromeTerminationSignalExitEnabled,
-};
-// Attach the per-login rig to every process termination route. The function
-// returns a disposer for the normal completion path; callers must keep the
-// browser teardown in the getter so an interrupt can also release the Chrome
-// profile lock before Node exits. The hard cap prevents a wedged browser from
-// keeping Xvfb/x11vnc/websockify (or cloudflared) alive indefinitely.
-//
-// Exit ownership is coordinated through `signalExit`, one owner at a time:
-// - When self-managed signal exits are ENABLED (the CLI default), this login
-//   takes sole ownership for its duration — it suspends browser.ts's
-//   SIGKILL-and-exit handlers (which would otherwise preempt the capped
-//   graceful teardown below on the same signal) and restores them on
-//   disposal. The always-on `exit` hooks (here for the rig, browser.ts's for
-//   identity-proven Chromes) stay as the force-kill backstop.
-// - When they are DISABLED, a central shutdown coordinator (the MCP server's
-//   requestShutdown) already owns process exit and drains this login via
-//   cancelActiveLoginBrowsers(); installing exit-calling signal or
-//   uncaughtException handlers here would race it (and would violate the
-//   server's log-and-keep-serving process guards), so only the pure-cleanup
-//   `exit` hook is registered.
-export function registerHeadlessRigCleanup(rig, activeBrowserTeardown, runtime = process, signalExit = selfManagedSignalExitCoordination) {
-    let finishing = false;
-    let signalExitSuspended = false;
-    const restoreSignalExitOwnership = () => {
-        if (!signalExitSuspended)
-            return;
-        signalExitSuspended = false;
-        signalExit.set(true);
-    };
-    const teardownBrowserWithin = async () => {
-        const closeBrowser = activeBrowserTeardown();
-        if (closeBrowser === undefined)
-            return;
-        await new Promise((resolve) => {
-            const timer = setTimeout(resolve, 3_000);
-            void closeBrowser()
-                .catch(() => undefined)
-                .finally(() => {
-                clearTimeout(timer);
-                resolve();
-            });
-        });
-    };
-    const exitAfterCleanup = (code) => {
-        if (finishing) {
-            forceTeardownHeadlessRig(rig);
-            restoreSignalExitOwnership();
-            runtime.exit(code);
-            return;
-        }
-        finishing = true;
-        void teardownBrowserWithin().finally(async () => {
-            await teardownHeadlessRig(rig);
-            restoreSignalExitOwnership();
-            runtime.exit(code);
-        });
-    };
-    const onExit = () => forceTeardownHeadlessRig(rig);
-    const onSigterm = () => exitAfterCleanup(143);
-    const onSigint = () => exitAfterCleanup(130);
-    const onUncaughtException = (error) => {
-        console.error("[login] uncaught exception; tearing down the login browser", error);
-        exitAfterCleanup(1);
-    };
-    const onUnhandledRejection = (reason) => {
-        console.error("[login] unhandled rejection; tearing down the login browser", reason);
-        exitAfterCleanup(1);
-    };
-    runtime.once("exit", onExit);
-    const ownsTerminationExit = signalExit.enabled();
-    if (ownsTerminationExit) {
-        signalExit.set(false);
-        signalExitSuspended = true;
-        runtime.on("SIGTERM", onSigterm);
-        runtime.on("SIGINT", onSigint);
-        runtime.once("uncaughtException", onUncaughtException);
-        runtime.once("unhandledRejection", onUnhandledRejection);
-    }
-    return () => {
-        if (finishing)
-            return;
-        runtime.removeListener("exit", onExit);
-        if (!ownsTerminationExit)
-            return;
-        runtime.removeListener("SIGTERM", onSigterm);
-        runtime.removeListener("SIGINT", onSigint);
-        runtime.removeListener("uncaughtException", onUncaughtException);
-        runtime.removeListener("unhandledRejection", onUnhandledRejection);
-        restoreSignalExitOwnership();
-    };
-}
-export function fallbackCloudflaredArgs(webPort) {
-    return ["tunnel", "--protocol", "http2", "--url", `http://127.0.0.1:${webPort}`];
-}
-// Assemble the directory websockify serves: a copy of the installed
-// noVNC web assets (for the `core/` RFB library) with our branded
-// vnc.html written over the stock one. A temp dir, NOT the package's
-// own assets/ — under `npx` the package runs from a read-only cache,
-// so the noVNC core cannot be copied into it. Torn down with the rig.
-function buildVncWebDir() {
-    const webDir = mkdtempSync(join(tmpdir(), "ts-novnc-"));
-    cpSync(NOVNC_INSTALL_DIR, webDir, { recursive: true });
-    // The branded page imports `./core/rfb.js`. If the distro's novnc
-    // package put its core somewhere else, fail loudly here rather than
-    // serving a page that 404s its own script and shows a blank screen.
-    if (!existsSync(join(webDir, "core", "rfb.js"))) {
-        rmSync(webDir, { recursive: true, force: true });
-        throw new Error(`noVNC core not found at ${NOVNC_INSTALL_DIR}/core/rfb.js — the ` +
-            `installed novnc package has an unexpected layout`);
-    }
-    const branded = readFileSync(loginAssetPath("vnc.html"), "utf8");
-    writeFileSync(join(webDir, "vnc.html"), branded);
-    // Also write index.html so the URL printed to the user's terminal can
-    // drop `/vnc.html` — every saved character matters on a phone, where
-    // line-wrapping the URL across two terminal lines makes copy/paste
-    // hostile. websockify's static server returns index.html for `/`.
-    writeFileSync(join(webDir, "index.html"), branded);
-    return webDir;
-}
 const LOGIN_BROWSER_CLOSED_ERROR = "the login browser closed before the session completed — re-run the command after closing any other Trusty Squire session";
 const LOGIN_STATUS_CHECK_STALLED_ERROR = "the login status check stopped responding before the session completed";
 export async function runInBotChrome(opts) {
-    return await withProfileOperationGuard(opts.profileDir, async () => {
-        const result = await runInBotChromeWithProfileGuard(opts);
-        await finalizeLoginRun(opts, result);
-        return { status: result.status };
-    });
-}
-export async function finalizeLoginRun(opts, result, publishSeed = publishOperatorProfileSeed) {
-    if (result.status === "completed" || result.status === "preflight_satisfied") {
-        await opts.onConfirmedLogin?.();
-    }
-    const provider = typeof opts.seedProvider === "function" ? opts.seedProvider() : (opts.seedProvider ?? null);
-    const proof = { loginStatus: result.status, closeState: result.closeState, provider };
-    if (canPublishOperatorProfileSeed(proof)) {
-        await publishSeed(opts.profileDir, { proof });
-    }
+    return await withProfileOperationGuard(opts.profileDir, async () => await runInBotChromeWithProfileGuard(opts));
 }
 async function runInBotChromeWithProfileGuard(opts) {
-    // `mcp login` runs in a SEPARATE process from the MCP server, so the
+    // `mcp connect` runs in a SEPARATE process from the MCP server, so the
     // in-process OAuth mutex can't serialize it against an in-flight signup.
     // Chrome's SingletonLock is the cross-process semaphore: reclaim a stale
-    // holder, but fail immediately for a live one. Waiting here used to leave a
-    // second connect apparently frozen while a duplicate noVNC stack accumulated.
+    // holder, but fail immediately for a live one.
     const free = await waitForProfileFree(opts.profileDir, {
         deadlineMs: 0,
     });
     if (!free) {
         throw new ProfileBusyError(PROFILE_BUSY_MESSAGE);
     }
-    if (hasDisplay()) {
-        return await runDisplayedChrome(opts);
-    }
-    return await runHeadlessChrome(opts);
+    return await runLoginBrowserForEnvironment(opts);
+}
+export async function runLoginBrowserForEnvironment(opts, runtime = { hasDisplay, runDisplayedChrome, runRemoteLoginChrome }) {
+    return runtime.hasDisplay()
+        ? await runtime.runDisplayedChrome(opts)
+        : await runtime.runRemoteLoginChrome(opts);
 }
 export async function runDisplayedChrome(opts, runtime = { resolveChannelBinary, launchPlainLoginBrowser }) {
-    // PLAIN-BROWSER path (connect claim): launch plain Chrome, never attach CDP,
-    // detect completion off the API + SQLite cookie store. See
-    // launchPlainLoginBrowser / RunInBotChromeOpts.plainProfileLogin.
-    if (opts.plainProfileLogin === true) {
-        if (opts.plainPollUntilDone === undefined) {
-            throw new Error("plainProfileLogin set without plainPollUntilDone");
-        }
-        const binary = runtime.resolveChannelBinary("chrome");
-        if (binary === null) {
-            throw new Error("no Chrome binary found for the plain login browser");
-        }
-        const proxyOpt = loginProxyOption();
-        const proxyDisposition = proxyOpt !== undefined && proxyOpt.password === undefined
-            ? selfLaunchProxyDisposition(proxyOpt)
-            : null;
-        opts.onProxyDisposition?.(proxyDisposition);
-        const lifecycle = createTrackedLoginBrowserLifecycle();
-        let status = "timeout";
-        let closeState = "unknown";
-        try {
-            const browser = await runtime.launchPlainLoginBrowser({
-                binary,
-                profileDir: opts.profileDir,
-                url: opts.url,
-                window: { width: 1280, height: 800 },
-                env: process.env,
-                // Self-launch/--proxy-server can't carry proxy auth — drop a credentialed
-                // proxy (direct). Connect from the box is the point anyway.
-                proxyServer: proxyDisposition?.server ?? null,
-                extraArgs: ["--no-sandbox", "--disable-dev-shm-usage"],
-            });
-            lifecycle.browserLaunched(async () => await teardownLoginBrowser({
-                profileDir: opts.profileDir,
-                identity: browser.identity,
-                closeBrowser: browser.teardown,
-                forceClose: browser.forceTeardown,
-            }));
-            console.error(`\n[login] A Chrome window has opened. ${opts.bannerLabel}\n`);
-            const ok = await pollUntil(opts.deadline, () => opts.plainPollUntilDone(opts.profileDir), opts.heartbeatMessage, () => {
-                if (!browser.isRunning())
-                    throw new Error(LOGIN_BROWSER_CLOSED_ERROR);
-            });
-            if (ok && opts.plainOnSuccess !== undefined) {
-                try {
-                    await opts.plainOnSuccess(opts.profileDir);
-                }
-                catch {
-                    /* swallow */
-                }
-            }
-            status = ok ? "completed" : "timeout";
-        }
-        finally {
-            closeState = await lifecycle.finish();
-        }
-        return { status, closeState };
+    const binary = runtime.resolveChannelBinary("chrome");
+    if (binary === null) {
+        throw new Error("no Chrome binary found for the plain login browser");
     }
-    const chromium = resolveChromium();
     const proxyOpt = loginProxyOption();
-    opts.onProxyDisposition?.(proxyOpt ?? null);
+    const proxyDisposition = proxyOpt !== undefined && proxyOpt.password === undefined
+        ? selfLaunchProxyDisposition(proxyOpt)
+        : null;
+    opts.onProxyDisposition?.(proxyDisposition);
     const lifecycle = createTrackedLoginBrowserLifecycle();
     let status = "timeout";
     let closeState = "unknown";
     try {
-        const context = await launchWithProfileGate(opts.profileDir, () => launchPersistentLoginContext(chromium, opts.profileDir, {
-            headless: false,
-            viewport: { width: 1280, height: 800 },
-            // Drop Playwright's default --enable-automation switch: it paints the
-            // "Chrome is being controlled by automated test software" infobar AND
-            // is itself an automation fingerprint the provider can read during the
-            // sign-in (so removing it also helps the session survive).
-            ignoreDefaultArgs: ["--enable-automation"],
-            args: [
-                "--disable-blink-features=AutomationControlled",
-                "--no-sandbox",
-                "--disable-dev-shm-usage",
-            ],
-            ...(proxyOpt !== undefined ? { proxy: proxyOpt } : {}),
-        }), { failFast: true });
-        const holderPid = currentProfileHolderPid(opts.profileDir);
-        const identity = holderPid === null ? null : profileProcessIdentity(holderPid, opts.profileDir);
+        const browser = await runtime.launchPlainLoginBrowser({
+            binary,
+            profileDir: opts.profileDir,
+            url: opts.url,
+            window: { width: 1280, height: 800 },
+            env: process.env,
+            // Self-launch/--proxy-server can't carry proxy auth — drop a credentialed
+            // proxy (direct). Connect from the box is the point anyway.
+            proxyServer: proxyDisposition?.server ?? null,
+            extraArgs: ["--no-sandbox", "--disable-dev-shm-usage"],
+        });
         lifecycle.browserLaunched(async () => await teardownLoginBrowser({
             profileDir: opts.profileDir,
-            identity,
-            closeBrowser: () => context.close(),
-            forceClose: () => reapProfileHolderIfOwned(opts.profileDir, identity),
+            identity: browser.identity,
+            closeBrowser: browser.teardown,
+            forceClose: browser.forceTeardown,
+            isRunning: browser.isRunning,
         }));
-        const preflightSatisfied = opts.preflight !== undefined &&
-            (await checkLoginStatusWithin(opts.deadline, () => opts.preflight(context)));
-        if (preflightSatisfied) {
-            status = "preflight_satisfied";
-        }
-        else {
-            const page = context.pages()[0] ?? (await context.newPage());
-            await page.goto(opts.url, { waitUntil: "domcontentloaded" });
-            console.error(`\n[login] A Chrome window has opened. ${opts.bannerLabel}\n`);
-            const ok = await pollUntil(opts.deadline, () => opts.pollUntilDone(context), opts.heartbeatMessage);
-            if (ok && opts.onSuccess !== undefined) {
-                try {
-                    await opts.onSuccess(context);
-                }
-                catch {
-                    /* swallow */
-                }
-            }
-            status = ok ? "completed" : "timeout";
-        }
+        console.error(`\n[login] A Chrome window has opened. ${opts.bannerLabel}\n`);
+        const ok = await pollUntil(opts.deadline, () => opts.pollUntilDone(), opts.heartbeatMessage, () => {
+            if (!browser.isRunning())
+                throw new Error(LOGIN_BROWSER_CLOSED_ERROR);
+        });
+        status = ok ? "satisfied" : "timeout";
     }
     finally {
         closeState = await lifecycle.finish();
     }
     return { status, closeState };
 }
-async function runHeadlessChrome(opts) {
-    requireBinaries(["Xvfb", "x11vnc", "websockify", "cloudflared"]);
-    if (!existsSync("/usr/share/novnc")) {
-        throw new Error("noVNC web assets not found at /usr/share/novnc — install the `novnc` package");
-    }
-    // G16 — named-tunnel mode. When the operator has set up a dedicated
-    // Cloudflare named tunnel pointing at a fixed local port, opt in via
-    // env. The bot then:
-    //   - binds websockify to that fixed local port (so the pre-configured
-    //     tunnel's ingress finds it)
-    //   - skips the per-session `cloudflared tunnel --url` spawn (the
-    //     named tunnel runs as a systemd service outside this process)
-    //   - prints the short branded URL instead of the long random one
-    // Both env vars must be set; absence (default) keeps the existing
-    // random `*.trycloudflare.com` flow.
-    const namedTunnelHost = process.env.TS_LOGIN_PUBLIC_HOSTNAME;
-    const namedTunnelPortStr = process.env.TS_LOGIN_LOCAL_PORT;
-    const usingNamedTunnel = namedTunnelHost !== undefined &&
-        namedTunnelHost.length > 0 &&
-        namedTunnelPortStr !== undefined &&
-        namedTunnelPortStr.length > 0;
-    const display = pickFreeDisplay();
-    const vncPort = await findFreePort();
-    const webPort = usingNamedTunnel ? Number(namedTunnelPortStr) : await findFreePort();
-    if (usingNamedTunnel && (!Number.isFinite(webPort) || webPort <= 0)) {
-        throw new Error(`TS_LOGIN_LOCAL_PORT=${JSON.stringify(namedTunnelPortStr)} is not a valid port number`);
-    }
-    const vncPassword = randomBytes(4).toString("hex"); // 8 chars — VNC's limit
-    const rig = { procs: [], display };
-    // The lifecycle below memoizes browser and rig teardown across normal
-    // completion, CLI signals, and server cancellation. Self-launched Chrome
-    // needs child teardown as well as context.close(); every forced close still
-    // goes through the launch-time process-identity proof.
+export async function runRemoteLoginChrome(opts) {
+    const rig = createRemoteLoginRig();
     let activeTeardown;
-    let plainBrowserIsRunning;
-    // Cover normal cleanup, interrupts, and fatal process errors. The returned
-    // disposer removes process-global listeners once this login finishes.
-    const removeRigCleanup = registerHeadlessRigCleanup(rig, () => activeTeardown);
-    const lifecycle = createTrackedLoginBrowserLifecycle(async () => await teardownHeadlessRig(rig));
+    const removeRigCleanup = registerRemoteLoginRigCleanup(rig, () => activeTeardown);
+    const lifecycle = createTrackedLoginBrowserLifecycle(async () => await teardownRemoteLoginRig(rig));
     activeTeardown = lifecycle.cancel;
     try {
-        // 1. Virtual display — phone-shaped.
-        rig.procs.push(spawnBg("Xvfb", [display, "-screen", "0", `${HEADLESS_W}x${HEADLESS_H}x24`, "-ac"]));
-        await new Promise((r) => setTimeout(r, 1500));
+        await startRemoteLoginDisplay(rig);
         lifecycle.throwIfCancelled();
-        // 2. Chrome on that display, persistent profile, window filling the display.
-        //    Self-launch + connectOverCDP is the STATE.md 2026-06-12 launcher fix:
-        //    a launchPersistentContext-driven Chrome carries the launch-time
-        //    instrumentation anti-bot (Cloudflare Turnstile, and — the bug this
-        //    ports the fix for — Google's sign-in device-prompt) reads as a bot,
-        //    while a self-launched Chrome attached over CDP does not. The signup
-        //    path (BrowserController) already migrated; the connect login was the
-        //    last consumer of the detectable launcher. Fall back to the old
-        //    launcher when self-launch is opted out (BOT_SELF_LAUNCH=0), Chrome
-        //    isn't resolvable as a real binary, or a credentialed proxy is set
-        //    (self-launch's --proxy-server can't carry proxy auth).
         const proxyOpt = loginProxyOption();
         const chromeBinary = resolveChannelBinary("chrome");
-        const useSelfLaunch = selfLaunchEnabled() &&
-            chromeBinary !== null &&
-            (proxyOpt === undefined || proxyOpt.password === undefined);
         const sharedChromeArgs = [
             "--disable-blink-features=AutomationControlled",
-            // --test-type suppresses the "unsupported command-line flag:
-            // --no-sandbox" yellow infobar that otherwise eats the top strip of the
-            // phone-shaped framebuffer once handed to noVNC. Standard automation
-            // flag; doesn't affect OAuth/cookies.
             "--test-type",
             "--no-sandbox",
             "--disable-dev-shm-usage",
         ];
-        // PLAIN-BROWSER mode (connect claim): NO CDP at all — a CDP-attached Chrome
-        // fails Google's OAuth "secure browser" check (STATE.md 2026-07-20, fully
-        // bisected). `context` stays undefined; completion is read via
-        // plainPollUntilDone (API + on-disk cookies), never a live context.
-        const plain = opts.plainProfileLogin === true;
-        let context;
-        if (plain) {
-            if (opts.plainPollUntilDone === undefined) {
-                throw new Error("plainProfileLogin set without plainPollUntilDone");
-            }
-            if (chromeBinary === null) {
-                throw new Error("no Chrome binary found for the plain login browser");
-            }
-            const proxyDisposition = proxyOpt !== undefined && proxyOpt.password === undefined
-                ? selfLaunchProxyDisposition(proxyOpt)
-                : null;
-            opts.onProxyDisposition?.(proxyDisposition);
-            const browser = await launchPlainLoginBrowser({
-                binary: chromeBinary,
-                profileDir: opts.profileDir,
-                url: opts.url,
-                window: { width: HEADLESS_W, height: HEADLESS_H },
-                env: { ...process.env, DISPLAY: display },
-                proxyServer: proxyDisposition?.server ?? null,
-                extraArgs: sharedChromeArgs,
-            });
-            lifecycle.browserLaunched(async () => await teardownLoginBrowser({
-                profileDir: opts.profileDir,
-                identity: browser.identity,
-                closeBrowser: browser.teardown,
-                forceClose: browser.forceTeardown,
-            }));
-            plainBrowserIsRunning = browser.isRunning;
-        }
-        else if (useSelfLaunch && chromeBinary !== null) {
-            const proxyDisposition = selfLaunchProxyDisposition(proxyOpt);
-            opts.onProxyDisposition?.(proxyDisposition);
-            const launched = await launchSelfManagedLoginContext({
-                binary: chromeBinary,
-                profileDir: opts.profileDir,
-                // App mode (--app) strips tabs/URL bar so the install page gets the
-                // full phone-shaped framebuffer under noVNC.
-                initialUrl: opts.url,
-                appMode: true,
-                window: { width: HEADLESS_W, height: HEADLESS_H },
-                env: { ...process.env, DISPLAY: display },
-                proxyServer: proxyDisposition?.server ?? null,
-                extraArgs: sharedChromeArgs,
-            });
-            lifecycle.browserLaunched(async () => await teardownLoginBrowser({
-                profileDir: opts.profileDir,
-                identity: launched.identity,
-                closeBrowser: launched.teardown,
-                forceClose: launched.forceTeardown,
-            }));
-            context = launched.context;
-        }
-        else {
-            const chromium = resolveChromium();
-            opts.onProxyDisposition?.(proxyOpt ?? null);
-            const persistent = await launchWithProfileGate(opts.profileDir, () => launchPersistentLoginContext(chromium, opts.profileDir, {
-                headless: false,
-                viewport: null, // use the real window size
-                env: { ...process.env, DISPLAY: display },
-                // Drop --enable-automation: kills the "controlled by automated test
-                // software" infobar and the matching automation fingerprint.
-                ignoreDefaultArgs: ["--enable-automation"],
-                ...(proxyOpt !== undefined ? { proxy: proxyOpt } : {}),
-                args: [
-                    `--window-position=0,0`,
-                    `--window-size=${HEADLESS_W},${HEADLESS_H}`,
-                    `--app=${opts.url}`,
-                    ...sharedChromeArgs,
-                ],
-            }), { failFast: true });
-            const persistentPid = currentProfileHolderPid(opts.profileDir);
-            const identity = persistentPid === null ? null : profileProcessIdentity(persistentPid, opts.profileDir);
-            lifecycle.browserLaunched(async () => await teardownLoginBrowser({
-                profileDir: opts.profileDir,
-                identity,
-                closeBrowser: () => persistent.close(),
-                forceClose: () => reapProfileHolderIfOwned(opts.profileDir, identity),
-            }));
-            context = persistent;
+        const browserEnv = remoteLoginEnvironment(rig);
+        if (chromeBinary === null) {
+            throw new Error("no Chrome binary found for the plain login browser");
         }
+        const proxyDisposition = proxyOpt !== undefined && proxyOpt.password === undefined
+            ? selfLaunchProxyDisposition(proxyOpt)
+            : null;
+        opts.onProxyDisposition?.(proxyDisposition);
+        const browser = await launchPlainLoginBrowser({
+            binary: chromeBinary,
+            profileDir: opts.profileDir,
+            url: opts.url,
+            window: { width: rig.width, height: rig.height },
+            env: browserEnv,
+            proxyServer: proxyDisposition?.server ?? null,
+            extraArgs: sharedChromeArgs,
+        });
+        lifecycle.browserLaunched(async () => await teardownLoginBrowser({
+            profileDir: opts.profileDir,
+            identity: browser.identity,
+            closeBrowser: browser.teardown,
+            forceClose: browser.forceTeardown,
+        }));
         try {
-            // CDP path only: preflight + drive the first page to the URL. The plain
-            // path has no context — plain Chrome's --app already opened opts.url.
-            if (context !== undefined) {
-                if (opts.preflight !== undefined &&
-                    (await checkLoginStatusWithin(opts.deadline, () => opts.preflight(context)))) {
-                    const closeState = await lifecycle.finish();
-                    return { status: "preflight_satisfied", closeState };
-                }
-                const page = context.pages()[0] ?? (await context.newPage());
-                await page.goto(opts.url, { waitUntil: "domcontentloaded" });
-            }
-            // 3. x11vnc on the display — localhost-only, password-gated, -noshm
-            //    (the box's X server lacks the shared-memory extension).
-            //    G14 — pass the password via a 0600 file, NOT `-passwd <plain>`
-            //    on argv (which any `ps` could read). `rm:` makes x11vnc unlink
-            //    the file right after reading it.
-            const passFile = join(tmpdir(), `tsq-vnc-${process.pid}-${vncPort}.pass`);
-            writeFileSync(passFile, vncPassword, { mode: 0o600 });
-            chmodSync(passFile, 0o600); // writeFileSync's mode is honored only on create
-            rig.passFile = passFile;
-            rig.procs.push(spawnBg("x11vnc", [
-                "-display",
-                display,
-                "-rfbport",
-                String(vncPort),
-                "-passwdfile",
-                `rm:${passFile}`,
-                "-localhost",
-                "-forever",
-                "-shared",
-                "-noshm",
-                "-quiet",
-            ]));
-            await new Promise((r) => setTimeout(r, 1500));
+            await exposeRemoteLoginDisplay(rig, opts.bannerLabel);
             lifecycle.throwIfCancelled();
-            // 4. noVNC web bridge — serves our branded vnc.html plus the
-            //    installed noVNC core from a temp dir; localhost only,
-            //    cloudflared reaches it.
-            rig.webDir = buildVncWebDir();
-            rig.procs.push(spawnBg("websockify", [
-                `--web=${rig.webDir}`,
-                `127.0.0.1:${webPort}`,
-                `localhost:${vncPort}`,
-            ]));
-            await new Promise((r) => setTimeout(r, 1500));
-            lifecycle.throwIfCancelled();
-            // 5. Outbound tunnel.
-            //
-            // G16 named-tunnel mode (env-gated): the operator pre-provisioned
-            // a dedicated cloudflared tunnel pointed at our fixed webPort
-            // (running as a systemd service outside this process). No per-
-            // session cloudflared spawn — saves ~5-10s of cold-start, and
-            // the URL is short + branded (vnc.trustysquire.ai instead of
-            // shouts-clean-mediawiki-cookies.trycloudflare.com).
-            //
-            // Random-tunnel fallback (default): spawn a fresh trycloudflare
-            // tunnel per session. Works everywhere, no operator setup, but
-            // the URL is ~80 chars and the cold-start hurts.
-            let bannerUrl;
-            if (usingNamedTunnel) {
-                // The persistent operator-managed named tunnel lives outside this
-                // process; run that service with `--protocol http2` too, avoiding the
-                // same QUIC datagram-manager drops as the per-session fallback.
-                // No `/vnc.html` — websockify serves the same content as
-                // index.html (buildVncWebDir writes both). Shorter URL fits
-                // one line on a phone terminal.
-                bannerUrl = `https://${namedTunnelHost}/#p=${vncPassword}`;
-            }
-            else {
-                const cf = spawnBg("cloudflared", fallbackCloudflaredArgs(webPort));
-                rig.procs.push(cf);
-                const tunnelUrl = await awaitTunnelUrl(cf, 30000);
-                lifecycle.throwIfCancelled();
-                const longVncUrl = `${tunnelUrl}/#p=${vncPassword}`;
-                // G15 (deprecated by G16): shorten the cloudflared URL through
-                // the API when we have an API base — much less transcription-
-                // hostile on a phone than the raw cloudflared subdomain. Still
-                // used on the random-tunnel fallback path; the named-tunnel
-                // path doesn't need it (URL is already short).
-                bannerUrl = longVncUrl;
-                if (opts.apiBaseUrl !== undefined) {
-                    bannerUrl = await shortenVncUrl(opts.apiBaseUrl, longVncUrl);
-                    lifecycle.throwIfCancelled();
-                }
-            }
-            // The VNC password rides in the URL *fragment* (#), not the query
-            // string — a fragment is never sent to the server, so it stays
-            // out of the cloudflared edge logs and any proxy in between. The
-            // branded vnc.html reads it from location.hash and connects with
-            // no prompt.
-            printBanner({
-                tunnelUrl: bannerUrl,
-                vncPassword,
-                label: opts.bannerLabel,
-            });
-            // 6. Wait for the side effect, run the success hook against the
-            //    live context (e.g. inspect cookies that the user's sign-in
-            //    set — opening a second context after teardown is racy and
-            //    silently fails on profile lock), then tear the whole stack
-            //    down.
-            const ok = await pollUntil(opts.deadline, () => context !== undefined
-                ? opts.pollUntilDone(context)
-                : opts.plainPollUntilDone(opts.profileDir), opts.heartbeatMessage, () => {
-                if (plainBrowserIsRunning !== undefined && !plainBrowserIsRunning()) {
+            const completed = await pollUntil(opts.deadline, () => opts.pollUntilDone(), opts.heartbeatMessage, () => {
+                assertRemoteLoginRigLive(rig);
+                if (!browser.isRunning())
                     throw new Error(LOGIN_BROWSER_CLOSED_ERROR);
-                }
             });
-            if (ok) {
-                if (context !== undefined) {
-                    if (opts.onSuccess !== undefined) {
-                        try {
-                            await opts.onSuccess(context);
-                        }
-                        catch {
-                            /* swallow */
-                        }
-                    }
-                }
-                else if (opts.plainOnSuccess !== undefined) {
-                    try {
-                        await opts.plainOnSuccess(opts.profileDir);
-                    }
-                    catch {
-                        /* swallow */
-                    }
-                }
-            }
             const closeState = await lifecycle.finish();
-            return { status: ok ? "completed" : "timeout", closeState };
+            return {
+                status: completed ? "satisfied" : "timeout",
+                closeState,
+            };
         }
         finally {
-            // Shared and memoized with the success and cancellation paths, so this
-            // finally cannot double-tear the browser or rig.
             await lifecycle.finish();
-            // Torn down — the signal handler must not double-tear it.
             activeTeardown = undefined;
         }
     }
@@ -1347,8 +581,8 @@ async function runHeadlessChrome(opts) {
 }
 // Shared timed-poll helper. `check` is invoked every 3s until it
 // resolves true or the deadline passes.
-// Emits a heartbeat to stderr every ~20s while waiting. After the noVNC banner
-// (or the Chrome window) opens, this loop is otherwise silent for up to the full
+// Emits a heartbeat to stderr every ~20s while waiting. After the local Chrome
+// window or remote noVNC URL opens, this loop is otherwise silent for up to the full
 // deadline — which is the connect-hang report: a headless box printed the
 // sign-in URL and then sat on a blank cursor, looking frozen. The heartbeat
 // (with remaining time) makes it obviously alive; quick completions (< 20s,
@@ -1400,74 +634,6 @@ export function checkLoginStatusWithin(deadline, check, assertStillLive, maxChec
     });
 }
 // --- public entry ------------------------------------------------------
-// Ensures `profileDir` holds a valid session for `provider`, doing
-// whichever login flow the environment calls for. Returns when the
-// session is present, the deadline passes, or setup fails. T13: the
-// provider defaults to Google; `mcp login --provider=github` reuses
-// the same flow against github.com.
-export async function ensureOAuthSession(opts) {
-    const provider = opts?.provider ?? "google";
-    const target = LOGIN_TARGETS[provider];
-    const profileDir = opts?.profileDir ?? CHROME_PROFILE_DIR;
-    const timeoutMinutes = Math.max(1, opts?.timeoutMinutes ?? 15);
-    const deadline = Date.now() + timeoutMinutes * 60 * 1000;
-    try {
-        const result = await runInBotChrome({
-            profileDir,
-            url: target.loginUrl,
-            deadline,
-            bannerLabel: `You'll see a Chrome window — log into your ${target.label} account.`,
-            // When forceOpen is true, the preflight ALSO clears the
-            // provider's session cookies before returning false. Without
-            // this the noVNC opens but pollUntilDone immediately sees the
-            // still-valid cached session and exits — the operator never
-            // gets a chance to interactively log in or clear a server-side
-            // challenge (GitHub "verify it's you"). Clearing the cookies
-            // forces the next page load to land on the provider's login
-            // page in a real, interactive session.
-            preflight: async (ctx) => {
-                if (opts?.forceOpen === true) {
-                    try {
-                        // Clear ONLY this provider's session cookies — never a bare
-                        // ctx.clearCookies(), which wiped EVERY provider (a
-                        // force-relogin=github would nuke the live Google session and the
-                        // operate precondition gate would then fail "no Google session").
-                        // The named session cookies are what define the login; dropping
-                        // them forces the next load to the provider's login page.
-                        for (const name of target.cookies) {
-                            await ctx.clearCookies({ name });
-                        }
-                    }
-                    catch {
-                        // best-effort — if clear fails we still proceed and let
-                        // the operator hit Sign Out manually in the noVNC.
-                    }
-                    return false;
-                }
-                return hasProviderSession(ctx, target);
-            },
-            pollUntilDone: (ctx) => hasProviderSession(ctx, target),
-            onConfirmedLogin: async () => markProviderLoggedIn(provider, profileDir),
-            seedProvider: provider,
-            ...(opts?.apiBaseUrl !== undefined ? { apiBaseUrl: opts.apiBaseUrl } : {}),
-        });
-        // Map runInBotChrome's status set to ensureOAuthSession's contract.
-        let mapped;
-        if (result.status === "preflight_satisfied") {
-            mapped = { status: "already_valid" };
-        }
-        else if (result.status === "completed") {
-            mapped = { status: "logged_in" };
-        }
-        else {
-            mapped = { status: "timeout", detail: "no login completed before the deadline" };
-        }
-        return mapped;
-    }
-    catch (err) {
-        return { status: "error", detail: err instanceof Error ? err.message : String(err) };
-    }
-}
 // Public entry for the install flow: opens the trustysquire /install
 // confirm URL in the bot's persistent Chrome profile, runs the
 // user-supplied check until the active flow's completion gate passes
@@ -1480,8 +646,6 @@ export async function openInstallConfirmInBotChrome(opts, runChrome = runInBotCh
     const timeoutMinutes = Math.max(1, opts.timeoutMinutes ?? 15);
     const deadline = Date.now() + timeoutMinutes * 60 * 1000;
     let completion;
-    let observedGoogleIdentity = false;
-    const completedProviders = new Set();
     try {
         const doneUrl = new URL("/install/done", opts.confirmUrl).toString();
         completion = await startInstallCompletionListener(doneUrl, opts.confirmUrl);
@@ -1492,47 +656,10 @@ export async function openInstallConfirmInBotChrome(opts, runChrome = runInBotCh
             deadline,
             bannerLabel: `You'll see a Chrome window with the Trusty Squire install page. ` +
                 `Sign in there to connect this machine — you only sign in once.`,
-            // PLAIN browser — no CDP. Google's OAuth flow (which this confirm page
-            // initiates) rejects a CDP-attached Chrome (STATE.md 2026-07-20). The
-            // context-taking pollUntilDone is never invoked in this mode; supply a
-            // stub to satisfy the (CDP-path) type.
-            plainProfileLogin: true,
-            pollUntilDone: () => Promise.resolve(false),
-            plainPollUntilDone: async (dir) => {
-                const claim = await opts.pollUntilClaimed(dir, completion?.isCompleted() === true);
-                if (typeof claim === "object" && claim.provider !== null) {
-                    completedProviders.add(claim.provider);
-                }
-                for (const provider of completion?.completedProviders() ?? []) {
-                    completedProviders.add(provider);
-                }
-                return installClaimPollCompleted(claim);
-            },
-            ...(opts.apiBaseUrl !== undefined ? { apiBaseUrl: opts.apiBaseUrl } : {}),
+            pollUntilDone: async () => installClaimPollCompleted(await opts.pollUntilClaimed(completion?.isCompleted() === true)),
             ...(opts.heartbeatMessage !== undefined ? { heartbeatMessage: opts.heartbeatMessage } : {}),
-            // The user's sign-in inside this Chrome leaves a provider session in the
-            // persistent profile. We don't know WHICH provider they used, so probe
-            // both cookie sets (from the on-disk store — no live context in plain
-            // mode) and mark whichever seeded.
-            plainOnSuccess: async (dir) => {
-                for (const provider of ["google", "github"]) {
-                    if (profileHasProviderCookies(dir, provider)) {
-                        markProviderLoggedIn(provider, dir);
-                        if (provider === "google" && completedProviders.has("google")) {
-                            observedGoogleIdentity = true;
-                        }
-                    }
-                }
-                // NB: eager Google-email capture (captureGoogleEmail) needed a live
-                // context to scrape myaccount.google.com; the plain login path has
-                // none. It was only an optimization ("provision proceeds without a
-                // pre-known email" otherwise) — provision scrapes the email per-run
-                // when unset, so dropping eager capture is safe and keeping CDP off
-                // the OAuth login is the whole point of the plain path.
-            },
-            seedProvider: () => (observedGoogleIdentity ? "google" : null),
         });
-        if (result.status === "completed") {
+        if (result.status === "satisfied") {
             return { status: "claimed" };
         }
         return { status: "timeout", detail: "no install completed before the deadline" };