harnery 0.42.0 → 0.44.0

package/src/lib/browser/windows-chrome.ts

@@ -7,18 +7,19 @@ import type { Cookie } from "../cookies/client.ts";
 /**
  * Sign-in through the Windows host's Google Chrome when running under WSL.
  *
- * Some sign-in flows (X is the reported case) reject every browser running
- * inside WSL, including a plain Linux Google Chrome with nothing attached:
- * the sign-in request comes back "429 Too Many Requests" while the same
- * account signs in from the Windows desktop browser without trouble. The
- * Windows Chrome is the client those flows accept, so `browse --login
- * --plain` under WSL opens it on a dedicated Windows-side profile. The
- * person signs in there with nothing attached. Afterwards the profile is
- * reopened headless for a moment, its cookies for the sign-in site are read
- * through the DevTools protocol, and they are merged into the shared cookie
- * store that later `browse` runs attach. The Windows profile cannot be shared
- * with Linux Chromium directly because Windows encrypts its cookie database
- * with keys only Windows can read.
+ * Some sign-in flows reject every browser running inside WSL, including a
+ * plain Linux Google Chrome with nothing attached: the sign-in request comes
+ * back "429 Too Many Requests" while the same account signs in from the
+ * Windows desktop browser without trouble. The Windows Chrome is the client
+ * those flows accept, so `browse --login --plain` under WSL opens it on a
+ * dedicated Windows-side profile. The person signs in there with nothing
+ * attached. Afterwards the profile is reopened headless for a moment with its
+ * last session restored, its cookies for the sign-in site (browser-session
+ * cookies included) and its open pages on that site are read through the
+ * DevTools protocol, and the cookies are merged into the shared cookie store
+ * that later `browse` runs attach. The Windows profile cannot be shared with
+ * Linux Chromium directly because Windows encrypts its cookie database with
+ * keys only Windows can read.
  *
  * Under WSL2's default NAT networking the Windows loopback port is not
  * reachable from Linux, so the DevTools conversation runs inside a short
@@ -106,117 +107,376 @@ export function cookiesForDomain(cdpCookies: CdpCookie[], domain: string): Cooki
 }
 
 /**
- * PowerShell that does the whole read on the Windows side: start Chrome
- * headless on the profile, wait for the DevToolsActivePort file it writes,
- * read every cookie with `Storage.getCookies`, write the raw response to
- * stdout, and close the browser. WSL never touches the profile folder, which
- * it may not be able to list. Every wait carries a deadline.
+ * Regular expression, valid in both JavaScript and .NET, that matches a Chrome
+ * command line running on `profileWindows`. It matches the `--user-data-dir`
+ * argument exactly, with or without quotes around the path, so `...\profile`
+ * never matches `...\profile-2`. Quotes are written as `\x22` so the pattern
+ * survives being passed to PowerShell as an argument. Case-insensitive use is
+ * intended, as Windows paths are.
  */
-export function harvestScript(): string {
+export function profileCommandLinePattern(profileWindows: string): string {
+  const path = profileWindows.replace(/\\+$/, "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return `--user-data-dir=\\x22?${path}\\\\?(\\x22|\\s|$)`;
+}
+
+/** PowerShell function listing the Chrome processes whose command line matches `$Pattern`. */
+const PROFILE_PROCESS_FUNCTION =
+  "function Get-ProfileChrome { @(Get-CimInstance Win32_Process -Filter \"Name='chrome.exe'\" | Where-Object { $_.CommandLine -and $_.CommandLine -match $Pattern }) }";
+
+/**
+ * PowerShell that throws while any Chrome is still running on the profile: a
+ * second Chrome on the same profile hands its work to the first and exits.
+ */
+const REFUSE_OPEN_PROFILE_LINES = [
+  PROFILE_PROCESS_FUNCTION,
+  "$alive = Get-ProfileChrome",
+  "if ($alive.Count -gt 0) { throw \"Chrome is still running on the sign-in profile (process $(($alive | ForEach-Object { $_.ProcessId }) -join ', ')). Close that window and try again.\" }",
+];
+
+/**
+ * PowerShell that starts Chrome headless on `$Profile` with `extraArgs`, waits
+ * for the DevToolsActivePort file it writes, and connects to the browser
+ * endpoint, defining `Send`, `Recv`, and `Wait-Reply` for the conversation.
+ * It refuses to start while any Chrome is still running on the profile,
+ * which would otherwise surface as a confusing startup failure.
+ */
+function headlessSessionLines(extraArgs: string[]): string[] {
+  const quoted = extraArgs.map((arg) => `'${arg}'`).join(", ");
   return [
-    "param([string]$Chrome, [string]$Profile, [int]$StartupSeconds = 30)",
-    "$ErrorActionPreference = 'Stop'",
+    ...REFUSE_OPEN_PROFILE_LINES,
     "$portFile = Join-Path $Profile 'DevToolsActivePort'",
     "if (Test-Path $portFile) { Remove-Item $portFile -Force }",
-    "$args = @('--headless=new', '--no-first-run', '--no-default-browser-check', '--remote-debugging-port=0', \"--user-data-dir=$Profile\", 'about:blank')",
-    "$proc = Start-Process -FilePath $Chrome -ArgumentList $args -PassThru -WindowStyle Hidden",
+    `$chromeArgs = @('--headless=new', '--no-first-run', '--no-default-browser-check', ${quoted ? `${quoted}, ` : ""}'--remote-debugging-port=0', "--user-data-dir=\`"$Profile\`"", 'about:blank')`,
+    "$proc = Start-Process -FilePath $Chrome -ArgumentList $chromeArgs -PassThru -WindowStyle Hidden",
     "$deadline = (Get-Date).AddSeconds($StartupSeconds)",
-    "while (-not (Test-Path $portFile)) { if ((Get-Date) -gt $deadline) { throw 'Windows Chrome did not open its DevTools port in time.' }; if ($proc.HasExited) { throw 'Windows Chrome exited before opening its DevTools port.' }; Start-Sleep -Milliseconds 250 }",
+    "while (-not (Test-Path $portFile)) { if ((Get-Date) -gt $deadline) { throw 'Windows Chrome did not open its DevTools port in time.' }; if ($proc.HasExited) { throw 'Windows Chrome exited before opening its DevTools port; another Chrome may have opened on the sign-in profile.' }; Start-Sleep -Milliseconds 250 }",
     "Start-Sleep -Milliseconds 200",
     "$lines = Get-Content $portFile",
     "$port = [int]$lines[0]; $path = $lines[1]",
     "$ws = New-Object System.Net.WebSockets.ClientWebSocket",
-    "$cts = New-Object System.Threading.CancellationTokenSource 20000",
+    "$cts = New-Object System.Threading.CancellationTokenSource 30000",
     '$ws.ConnectAsync([Uri]("ws://127.0.0.1:$port$path"), $cts.Token).Wait()',
-    "function Send($obj) { $b = [Text.Encoding]::UTF8.GetBytes(($obj | ConvertTo-Json -Compress)); $ws.SendAsync([ArraySegment[byte]]$b, 'Text', $true, $cts.Token).Wait() }",
+    "function Send($obj) { $b = [Text.Encoding]::UTF8.GetBytes(($obj | ConvertTo-Json -Compress -Depth 6)); $ws.SendAsync([ArraySegment[byte]]$b, 'Text', $true, $cts.Token).Wait() }",
     "function Recv() { $buf = New-Object byte[] 65536; $ms = New-Object IO.MemoryStream; do { $r = $ws.ReceiveAsync([ArraySegment[byte]]$buf, $cts.Token).Result; $ms.Write($buf, 0, $r.Count) } while (-not $r.EndOfMessage); [Text.Encoding]::UTF8.GetString($ms.ToArray()) }",
+    "function Wait-Reply([int]$n) { while ($true) { $m = Recv; if ($m -match ('\"id\":' + $n + '[,}]')) { return $m } } }",
+  ];
+}
+
+/** PowerShell that closes the headless browser started by `headlessSessionLines`. */
+const CLOSE_HEADLESS_LINES = [
+  "try { Send @{ id = 0; method = 'Browser.close' } } catch {}",
+  "if (-not $proc.WaitForExit(10000)) { Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue }",
+];
+
+/**
+ * PowerShell that sets the profile's startup preference to "continue where
+ * you left off". Chrome deletes browser-session cookies (cookies with no
+ * expiry) when it exits normally unless that preference is set, and many
+ * sign-ins keep the signed-in state only in such cookies. With it set, the
+ * person can simply close the window and the sign-in survives for the
+ * harvest, and the next sign-in window reopens where they left off.
+ *
+ * The preference is protected against edits to the profile's files, so the
+ * script sets it the way the settings page does: it opens the profile
+ * headless, loads the settings page, and calls the settings API there. When
+ * the profile's preference files already show the value, Chrome is not
+ * started. The script prints `{"changed":bool,"value":n}`.
+ */
+export function keepSessionScript(): string {
+  return [
+    "param([string]$Chrome, [string]$Profile, [string]$Pattern, [int]$StartupSeconds = 30)",
+    "$ErrorActionPreference = 'Stop'",
+    ...REFUSE_OPEN_PROFILE_LINES,
+    "foreach ($name in @('Secure Preferences', 'Preferences')) { $prefsFile = Join-Path (Join-Path $Profile 'Default') $name; if (Test-Path $prefsFile) { try { $prefs = Get-Content -Raw $prefsFile | ConvertFrom-Json; if ($prefs.session.restore_on_startup -eq 1) { [Console]::Out.Write('{\"changed\":false,\"value\":1}'); exit 0 } } catch {} } }",
+    ...headlessSessionLines([]),
+    "Send @{ id = 1; method = 'Target.createTarget'; params = @{ url = 'chrome://settings/onStartup' } }",
+    "$targetId = (ConvertFrom-Json (Wait-Reply 1)).result.targetId",
+    "Send @{ id = 2; method = 'Target.attachToTarget'; params = @{ targetId = $targetId; flatten = $true } }",
+    "$sessionId = (ConvertFrom-Json (Wait-Reply 2)).result.sessionId",
+    "$expr = \"new Promise((resolve) => { const started = Date.now(); const attempt = () => { const api = globalThis.chrome && chrome.settingsPrivate; if (api) { api.setPref('session.restore_on_startup', 1, '', () => api.getPref('session.restore_on_startup', (pref) => resolve(JSON.stringify({ changed: true, value: pref ? pref.value : null })))); } else if (Date.now() - started > 10000) { resolve(JSON.stringify({ changed: false, value: null })); } else { setTimeout(attempt, 100); } }; attempt(); })\"",
+    "Send @{ id = 3; sessionId = $sessionId; method = 'Runtime.evaluate'; params = @{ expression = $expr; awaitPromise = $true; returnByValue = $true } }",
+    "$value = (ConvertFrom-Json (Wait-Reply 3)).result.result.value",
+    "Start-Sleep -Milliseconds 300",
+    ...CLOSE_HEADLESS_LINES,
+    "[Console]::Out.Write($value)",
+  ].join("\r\n");
+}
+
+/**
+ * PowerShell that does the whole read on the Windows side: start Chrome
+ * headless on the profile with its last session restored, read every cookie
+ * with `Storage.getCookies`, list the open pages with `Target.getTargets`,
+ * write both raw responses to stdout as one JSON object, and close the
+ * browser. WSL never touches the profile folder, which it may not be able to
+ * list. Every wait carries a deadline.
+ *
+ * Restoring the session keeps browser-session cookies that a forced stop left
+ * on disk, and it reopens the tabs the person had open, so the harvest can
+ * report the last page they reached on the sign-in site. That page's URL may
+ * carry a per-session token that cookies alone do not replace. The page list
+ * is polled for up to `$PageSeconds` until a page on `$Domain` appears.
+ */
+export function harvestScript(): string {
+  return [
+    "param([string]$Chrome, [string]$Profile, [string]$Pattern, [string]$Domain = '', [int]$StartupSeconds = 30, [int]$PageSeconds = 5)",
+    "$ErrorActionPreference = 'Stop'",
+    ...headlessSessionLines(["--restore-last-session"]),
+    "function Test-SiteUrl([string]$u) { if (-not $Domain) { return $false }; try { $h = ([Uri]$u).Host.ToLowerInvariant() } catch { return $false }; return ($h -eq $Domain -or $h.EndsWith('.' + $Domain)) }",
     "Send @{ id = 1; method = 'Storage.getCookies' }",
-    "$out = $null",
-    "while ($null -eq $out) { $m = Recv; if ($m -match '\"id\":1[,}]') { $out = $m } }",
-    "[Console]::Out.Write($out)",
-    "try { Send @{ id = 2; method = 'Browser.close' } } catch {}",
-    "if (-not $proc.WaitForExit(10000)) { Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue }",
+    "$cookiesReply = Wait-Reply 1",
+    "$pageDeadline = (Get-Date).AddSeconds($PageSeconds)",
+    "$n = 1",
+    "while ($true) { $n++; Send @{ id = $n; method = 'Target.getTargets' }; $targetsReply = Wait-Reply $n; $sitePages = @((ConvertFrom-Json $targetsReply).result.targetInfos | Where-Object { $_.type -eq 'page' -and (Test-SiteUrl $_.url) }); if ($sitePages.Count -gt 0 -or (Get-Date) -gt $pageDeadline) { break }; Start-Sleep -Milliseconds 250 }",
+    "[Console]::Out.Write('{\"cookies\":' + $cookiesReply + ',\"targets\":' + $targetsReply + '}')",
+    ...CLOSE_HEADLESS_LINES,
   ].join("\r\n");
 }
 
+/** Shape `Target.getTargets` returns; extra fields are ignored. */
+interface CdpTargetInfo {
+  type: string;
+  url: string;
+}
+
 /**
- * Reopen the Windows profile headless, read its cookies for `domain`, and
- * close it. Returns the cookies in the store's shape.
+ * URLs of the open pages on the sign-in site, in the order Chrome lists them,
+ * without duplicates.
  */
-export function harvestWindowsChromeCookies(input: {
-  chromeWindows: string;
-  profileWindows: string;
-  domain: string;
-  startupTimeoutSeconds?: number;
-}): Cookie[] {
+export function sitePages(targets: CdpTargetInfo[], domain: string): string[] {
+  const pages: string[] = [];
+  for (const target of targets) {
+    if (target.type !== "page") continue;
+    let host: string;
+    try {
+      host = new URL(target.url).hostname;
+    } catch {
+      continue;
+    }
+    if (host && cookieInDomain(host, domain) && !pages.includes(target.url)) pages.push(target.url);
+  }
+  return pages;
+}
+
+export interface WindowsChromeHarvest {
+  /** The sign-in site's cookies, browser-session cookies included. */
+  cookies: Cookie[];
+  /** Open pages on the sign-in site; the first is the one to resume from. */
+  pages: string[];
+}
+
+/** Parse the harvest script's stdout. */
+export function parseHarvestOutput(stdout: string, domain: string): WindowsChromeHarvest {
+  const parsed = JSON.parse(stdout) as {
+    cookies?: { result?: { cookies?: CdpCookie[] }; error?: { message?: string } };
+    targets?: { result?: { targetInfos?: CdpTargetInfo[] } };
+  };
+  const cookieList = parsed.cookies?.result?.cookies;
+  if (!cookieList)
+    throw new Error(
+      `Windows Chrome returned no cookie list: ${parsed.cookies?.error?.message ?? "unknown response"}`,
+    );
+  return {
+    cookies: cookiesForDomain(cookieList, domain),
+    pages: sitePages(parsed.targets?.result?.targetInfos ?? [], domain),
+  };
+}
+
+/** Write a PowerShell script to a temp file and run it with `-File`. */
+function runPowerShellScript(
+  name: string,
+  script: string,
+  args: string[],
+  timeoutMs: number,
+): { status: number | null; stdout: string; stderr: string; error?: Error } {
   const scriptDir = join(tmpdir(), "harnery-windows-chrome");
   mkdirSync(scriptDir, { recursive: true });
-  const scriptLinux = join(scriptDir, `harvest-cookies-${process.pid}.ps1`);
-  writeFileSync(scriptLinux, harvestScript(), { mode: 0o600 });
+  const scriptLinux = join(scriptDir, `${name}-${process.pid}.ps1`);
+  writeFileSync(scriptLinux, script, { mode: 0o600 });
   try {
     const scriptWindows = spawnSync("wslpath", ["-w", scriptLinux], {
       encoding: "utf8",
     }).stdout.trim();
     const result = spawnSync(
       "powershell.exe",
-      [
-        "-NoProfile",
-        "-ExecutionPolicy",
-        "Bypass",
-        "-File",
-        scriptWindows,
-        "-Chrome",
-        input.chromeWindows,
-        "-Profile",
-        input.profileWindows,
-        "-StartupSeconds",
-        String(input.startupTimeoutSeconds ?? 30),
-      ],
-      { encoding: "utf8", timeout: 90_000, maxBuffer: 64 * 1024 * 1024 },
+      ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", scriptWindows, ...args],
+      { encoding: "utf8", timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 },
     );
-    if (result.status !== 0) {
-      throw new Error(
-        `Reading cookies from Windows Chrome failed: ${(result.stderr || result.stdout || "no output").trim().slice(0, 400)}`,
-      );
-    }
-    const parsed = JSON.parse(result.stdout) as {
-      result?: { cookies?: CdpCookie[] };
-      error?: { message?: string };
+    return {
+      status: result.status,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      ...(result.error ? { error: result.error } : {}),
     };
-    if (!parsed.result?.cookies)
-      throw new Error(
-        `Windows Chrome returned no cookie list: ${parsed.error?.message ?? "unknown response"}`,
-      );
-    return cookiesForDomain(parsed.result.cookies, input.domain);
   } finally {
     rmSync(scriptLinux, { force: true });
   }
 }
 
 /**
- * Close any Chrome still running on `profileWindows`, for when the person ends
- * the sign-in from the terminal while the window is open. The profile must be
- * closed before its cookies can be read. Closing the window first lets Chrome
- * write recent cookies to disk; a forced stop is the fallback after 15 s.
+ * Reopen the Windows profile headless with its last session restored, read
+ * its cookies for `domain` and its open pages on that site, and close it.
+ * The profile must already be closed; see `stopWindowsChromeProfile`.
+ */
+export function harvestWindowsChromeCookies(input: {
+  chromeWindows: string;
+  profileWindows: string;
+  domain: string;
+  startupTimeoutSeconds?: number;
+  pageTimeoutSeconds?: number;
+}): WindowsChromeHarvest {
+  const result = runPowerShellScript(
+    "harvest-cookies",
+    harvestScript(),
+    [
+      "-Chrome",
+      input.chromeWindows,
+      "-Profile",
+      input.profileWindows,
+      "-Pattern",
+      profileCommandLinePattern(input.profileWindows),
+      "-Domain",
+      input.domain,
+      "-StartupSeconds",
+      String(input.startupTimeoutSeconds ?? 30),
+      "-PageSeconds",
+      String(input.pageTimeoutSeconds ?? 5),
+    ],
+    90_000,
+  );
+  if (result.status !== 0) {
+    throw new Error(
+      `Reading cookies from Windows Chrome failed: ${(result.stderr || result.stdout || result.error?.message || "no output").trim().slice(0, 400)}`,
+    );
+  }
+  return parseHarvestOutput(result.stdout, input.domain);
+}
+
+export interface WindowsChromeKeepSession {
+  /** True when the preference was already set or is now set. */
+  kept: boolean;
+  /** True when this call changed the preference. */
+  changed: boolean;
+}
+
+/**
+ * Set the profile to keep browser-session cookies across a normal exit; see
+ * `keepSessionScript`. Throws when Chrome is already open on the profile,
+ * since a second sign-in window would hand off to it. Any other failure
+ * returns `kept: false` so the caller can warn and continue.
  */
-export function stopWindowsChromeProfile(profileWindows: string): void {
-  const escaped = profileWindows.replace(/'/g, "''");
-  const select = `Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" | Where-Object { $_.CommandLine -like '*${escaped}*' }`;
-  spawnSync(
-    "powershell.exe",
+export function keepWindowsChromeSession(input: {
+  chromeWindows: string;
+  profileWindows: string;
+  startupTimeoutSeconds?: number;
+}): WindowsChromeKeepSession {
+  const result = runPowerShellScript(
+    "keep-session",
+    keepSessionScript(),
     [
-      "-NoProfile",
-      "-Command",
-      [
-        `$ids = @(${select} | ForEach-Object { $_.ProcessId })`,
-        "foreach ($id in $ids) { $p = Get-Process -Id $id -ErrorAction SilentlyContinue; if ($p -and $p.MainWindowHandle -ne 0) { [void]$p.CloseMainWindow() } }",
-        "$deadline = (Get-Date).AddSeconds(15)",
-        `while ((Get-Date) -lt $deadline -and @(${select}).Count -gt 0) { Start-Sleep -Milliseconds 250 }`,
-        `${select} | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }`,
-      ].join("; "),
+      "-Chrome",
+      input.chromeWindows,
+      "-Profile",
+      input.profileWindows,
+      "-Pattern",
+      profileCommandLinePattern(input.profileWindows),
+      "-StartupSeconds",
+      String(input.startupTimeoutSeconds ?? 30),
     ],
-    { encoding: "utf8", timeout: 45_000 },
+    90_000,
+  );
+  const detail = (result.stderr || result.stdout || result.error?.message || "").trim();
+  if (result.status !== 0) {
+    if (detail.includes("Chrome is still running on the sign-in profile"))
+      throw new Error(
+        `Chrome is already open on the sign-in profile ${input.profileWindows}. Close that window and run the sign-in again.`,
+      );
+    return { kept: false, changed: false };
+  }
+  try {
+    const parsed = JSON.parse(result.stdout) as { changed?: boolean; value?: unknown };
+    return { kept: parsed.value === 1, changed: parsed.changed === true };
+  } catch {
+    return { kept: false, changed: false };
+  }
+}
+
+/**
+ * PowerShell that closes every Chrome whose command line matches `$Pattern`. It asks each window to
+ * close, repeating so a profile with several windows closes them all, which
+ * lets Chrome write its cookies and session to disk. Whatever is still
+ * running after `$CloseSeconds` is stopped by force. The script prints
+ * `{found, forced, remaining}` as JSON; `remaining` lists process ids that
+ * survived even the forced stop.
+ */
+export function stopScript(): string {
+  return [
+    "param([string]$Pattern, [int]$CloseSeconds = 15)",
+    "$ErrorActionPreference = 'Stop'",
+    PROFILE_PROCESS_FUNCTION,
+    "$found = (Get-ProfileChrome).Count",
+    "$deadline = (Get-Date).AddSeconds($CloseSeconds)",
+    "while ($true) { $procs = Get-ProfileChrome; if ($procs.Count -eq 0 -or (Get-Date) -gt $deadline) { break }; foreach ($c in $procs) { try { $p = Get-Process -Id $c.ProcessId -ErrorAction SilentlyContinue; if ($p -and $p.MainWindowHandle -ne 0) { [void]$p.CloseMainWindow() } } catch {} }; Start-Sleep -Milliseconds 500 }",
+    "$forced = 0",
+    "foreach ($c in $(Get-ProfileChrome)) { Stop-Process -Id $c.ProcessId -Force -ErrorAction SilentlyContinue; $forced++ }",
+    "if ($forced -gt 0) { $killDeadline = (Get-Date).AddSeconds(10); while ((Get-ProfileChrome).Count -gt 0 -and (Get-Date) -lt $killDeadline) { Start-Sleep -Milliseconds 250 } }",
+    "$remaining = @(Get-ProfileChrome | ForEach-Object { [int]$_.ProcessId })",
+    "[Console]::Out.Write((@{ found = $found; forced = $forced; remaining = $remaining } | ConvertTo-Json -Compress))",
+  ].join("\r\n");
+}
+
+export interface WindowsChromeStop {
+  /** Chrome processes running on the profile when the stop began. */
+  found: number;
+  /** Processes that ignored the close request and were stopped by force. */
+  forced: number;
+}
+
+/** Parse the stop script's stdout; throws when a process survived. */
+export function parseStopOutput(stdout: string, profileWindows: string): WindowsChromeStop {
+  const parsed = JSON.parse(stdout) as {
+    found?: number;
+    forced?: number;
+    remaining?: number | number[] | null;
+  };
+  const remaining =
+    parsed.remaining === undefined || parsed.remaining === null
+      ? []
+      : Array.isArray(parsed.remaining)
+        ? parsed.remaining
+        : [parsed.remaining];
+  if (remaining.length > 0) {
+    throw new Error(
+      `Chrome is still running on ${profileWindows} (process ${remaining.join(", ")}) after a forced stop; its cookies cannot be read until it exits.`,
+    );
+  }
+  return { found: Number(parsed.found ?? 0), forced: Number(parsed.forced ?? 0) };
+}
+
+/**
+ * Close every Chrome still running on `profileWindows`, for when the person
+ * ends the sign-in from the terminal while the window is open. The profile
+ * must be closed before its cookies can be read. Closing the windows lets
+ * Chrome write recent cookies to disk; a forced stop is the fallback after
+ * `closeSeconds`, and it can lose cookies Chrome had not yet written. Throws
+ * when the stop cannot be confirmed, so the harvest never runs against a
+ * profile that is still open.
+ */
+export function stopWindowsChromeProfile(
+  profileWindows: string,
+  closeSeconds = 15,
+): WindowsChromeStop {
+  const result = runPowerShellScript(
+    "stop-profile",
+    stopScript(),
+    ["-Pattern", profileCommandLinePattern(profileWindows), "-CloseSeconds", String(closeSeconds)],
+    (closeSeconds + 60) * 1000,
   );
+  if (result.status !== 0) {
+    throw new Error(
+      `Closing Chrome on ${profileWindows} failed: ${(result.stderr || result.stdout || result.error?.message || "no output").trim().slice(0, 400)}`,
+    );
+  }
+  return parseStopOutput(result.stdout, profileWindows);
 }
 
 /** Windows form of a `/mnt/<drive>/...` path. */

package/src/lib/docs-links.ts

@@ -363,6 +363,52 @@ export function slugify(heading: string): string {
     .replace(/\s/g, "-");
 }
 
+/** Keep literal code text out of the heading's inline-markup replacements. */
+function shieldHeadingCode(text: string): { text: string; restore: (text: string) => string } {
+  let marker = "\u0000";
+  while (text.includes(marker)) marker += "\u0000";
+  const spans: string[] = [];
+  const tokens = /<[^>]+>|`+/g;
+  let masked = "";
+  let copiedThrough = 0;
+
+  for (let opening = tokens.exec(text); opening; opening = tokens.exec(text)) {
+    // An HTML tag starts before its attribute values; their backticks are not
+    // code delimiters. Escaped opening backticks are literal punctuation too.
+    if (!opening[0].startsWith("`")) continue;
+    let backslashes = 0;
+    for (let i = opening.index - 1; i >= 0 && text[i] === "\\"; i--) backslashes++;
+    if (backslashes % 2 !== 0) continue;
+
+    const closingRuns = /`+/g;
+    closingRuns.lastIndex = opening.index + opening[0].length;
+    let closing = closingRuns.exec(text);
+    while (closing && closing[0].length !== opening[0].length) {
+      closing = closingRuns.exec(text);
+    }
+    if (!closing) continue;
+
+    let code = text.slice(opening.index + opening[0].length, closing.index);
+    // Code spans remove one padding space at each end, except all-space spans.
+    if (code.startsWith(" ") && code.endsWith(" ") && /[^ ]/.test(code)) {
+      code = code.slice(1, -1);
+    }
+    masked += text.slice(copiedThrough, opening.index) + marker + spans.length + marker;
+    spans.push(code);
+    copiedThrough = closing.index + closing[0].length;
+    tokens.lastIndex = copiedThrough;
+  }
+
+  return {
+    text: masked + text.slice(copiedThrough),
+    restore: (filtered) =>
+      filtered.replace(
+        new RegExp(`${marker}(\\d+)${marker}`, "g"),
+        (_, index: string) => spans[Number(index)]!,
+      ),
+  };
+}
+
 /**
  * Every fragment a reader can legitimately target in one document: Markdown
  * heading slugs (ATX and Setext), explicit `{#custom-id}` suffixes, and HTML
@@ -388,7 +434,8 @@ export function collectAnchors(content: string): Set<string> {
     // so only word-boundary underscores are markup. `_` counts as a word
     // character in JS regex, so \b sits exactly at the space-to-underscore
     // seam these delimiters occupy.
-    text = text
+    const code = shieldHeadingCode(text);
+    text = code.text
       // Backslash escapes render as the bare character, so `snake\_case`
       // must anchor exactly like `snake_case`. Unescape before the emphasis
       // strip or the escaped underscore gains a phantom word boundary.
@@ -397,7 +444,7 @@ export function collectAnchors(content: string): Set<string> {
       .replace(/[*~`]/g, "")
       .replace(/\b_+|_+\b/g, "")
       .replace(/<[^>]+>/g, "");
-    const base = slugify(text);
+    const base = slugify(code.restore(text));
     if (!base) return;
     const n = seen.get(base) ?? 0;
     seen.set(base, n + 1);