harnery 0.31.6 → 0.32.0

package/src/commands/browse.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, resolve } from "node:path";
 import type { Command } from "commander";
@@ -7,6 +7,8 @@ import { resolveBinName } from "../core/config.ts";
 import {
   type AssertResult,
   Browser,
+  browserProxyFromEnv,
+  browserProxyGateFromEnv,
   type ContentAnnotationBox,
   type ContentChecksResult,
   type CritiqueResult,
@@ -15,6 +17,7 @@ import {
   DEFAULT_CRITIQUE_RUBRIC,
   type DevOverlayResult,
   type Diagnostics,
+  extractObservedIp,
   type LayoutAxis,
   type LayoutLintResult,
   type OverflowResult,
@@ -25,9 +28,15 @@ import {
   type TargetSizeResult,
   tilesFromFullPage,
   type VisibilityResult,
+  WEBRTC_PROXY_ONLY_ARG,
   type WidthResult,
+  writeNetscapeCookieFile,
   wslHeadedLaunchArgs,
 } from "../lib/browser/index.ts";
+import {
+  type BrowserSessionServer,
+  startBrowserSessionServer,
+} from "../lib/browser/session-control.ts";
 import {
   type DiffResult,
   diffAgainstBaseline,
@@ -66,7 +75,6 @@ interface BrowseOpts {
   // `opts.noX`. So `--no-screenshot` toggles `screenshot`, `--no-full-page`
   // toggles `fullPage`, `--no-cookies` toggles `cookies`.
   screenshot?: boolean;
-  domOnly?: boolean;
   fullPage?: boolean;
   snapshot?: boolean;
   html?: boolean;
@@ -80,8 +88,12 @@ interface BrowseOpts {
   batch?: string;
   networkHar?: string;
   login?: boolean;
+  loginCloseFile?: string;
+  controlFile?: string;
   headed?: boolean;
   browserArg?: string[];
+  proxyFromEnv?: boolean;
+  exportCookies?: string;
   cookies?: boolean;
   store?: string;
   profile?: string;
@@ -201,7 +213,6 @@ export function registerBrowseCommand(
       "Output prefix for the trio (writes <prefix>.png, .html, .json). Defaults to ~/.cache/harnery/browse/last.",
     )
     .option("--no-screenshot", "Skip the .png in the trio (DOM + JSON only)")
-    .option("--dom-only", "Alias for --no-screenshot")
     .option("--no-full-page", "Capture only the viewport, not the full scrollable page")
     .option("--snapshot", "Print body innerText to stdout (skips file writes)")
     .option(
@@ -235,6 +246,14 @@ export function registerBrowseCommand(
       "desktop",
     )
     .option("--login", "Headed mode for one-time auth flow (cookies persist in profile)")
+    .option(
+      "--login-close-file <path>",
+      "With --login, wait for this file instead of terminal Enter, then remove it and close cleanly",
+    )
+    .option(
+      "--control-file <path>",
+      "With --login, publish an owner-only descriptor for repeated browse-session control",
+    )
     .option("--headed", "Headed mode for one-off (no auth-flow framing)")
     .option(
       "--browser-arg <flag>",
@@ -246,9 +265,20 @@ export function registerBrowseCommand(
       (value: string, prev: string[] = []) => [...prev, value],
       [] as string[],
     )
+    .option(
+      "--proxy-from-env",
+      "Pass HTTP(S)_PROXY to Playwright as an authenticated browser proxy. " +
+        "Credentials stay in the child environment, never command arguments. " +
+        "When the host also injects the HARNERY_BROWSER_PROXY_* gate variables, " +
+        "the expected IP is verified before the requested URL opens.",
+    )
     .option("--no-cookies", "Skip cookie-jar attach and persist")
     .option("--store <path>", `Cookie store path (default ${DEFAULT_STORE})`)
     .option("--profile <dir>", `Persistent Chromium profile dir (default ${DEFAULT_PROFILE})`)
+    .option(
+      "--export-cookies <path>",
+      "Write live profile cookies as an owner-only Netscape cookies.txt file on close",
+    )
     .option(
       "--wait-until <strategy>",
       "Navigation wait strategy: load | domcontentloaded | networkidle | commit",
@@ -317,7 +347,7 @@ export function registerBrowseCommand(
     )
     .option(
       "--check-overflow-fail",
-      "Exit non-zero if --check-overflow detects horizontal overflow.",
+      "Run --check-overflow and exit 2 if horizontal overflow is detected.",
     )
     .option(
       "--no-check-overflow-annotate",
@@ -336,7 +366,10 @@ export function registerBrowseCommand(
       "Minimum block text length to scan (default 40; smaller labels can't meaningfully wrap).",
       "40",
     )
-    .option("--check-runts-fail", "Exit non-zero if any runt is detected.")
+    .option(
+      "--check-runts-fail",
+      "Run a document-wide runt check when needed; exit 2 on a runt, missing scope, or incomplete sweep.",
+    )
     .option(
       "--no-check-runts-annotate",
       "Skip drawing runt boxes on the screenshot (JSON still emitted).",
@@ -353,7 +386,10 @@ export function registerBrowseCommand(
       "Maximum rendered-center drift in CSS pixels (default 2).",
       "2",
     )
-    .option("--check-align-fail", "Exit 2 when an alignment target fails or is missing.")
+    .option(
+      "--check-align-fail",
+      "Exit 2 when an alignment target fails, is unknown, or is missing.",
+    )
     .option("--no-check-align-annotate", "Skip alignment screenshot annotations.")
     .option(
       "--check-gap <selector>",
@@ -367,11 +403,12 @@ export function registerBrowseCommand(
       "Expected gap in CSS pixels. Without it, groups of 3+ infer the median gap.",
     )
     .option("--check-gap-threshold <px>", "Maximum gap deviation in CSS pixels (default 2).", "2")
-    .option("--check-gap-fail", "Exit 2 when a gap target fails or is missing.")
+    .option("--check-gap-fail", "Exit 2 when a gap target fails, is unknown, or is missing.")
     .option("--no-check-gap-annotate", "Skip gap screenshot annotations.")
     .option(
       "--check-clip <selector>",
-      "Check descendants against this container's rectangular clipping chain (repeatable).",
+      "Check every matching container for descendant boxes or text paint leaving its " +
+        "rectangular clipping chain or nearest block parent (repeatable).",
       (value: string, previous: string[] = []) => [...previous, value],
       [] as string[],
     )
@@ -380,7 +417,7 @@ export function registerBrowseCommand(
       "Allowed rectangular overrun in CSS pixels (default 0).",
       "0",
     )
-    .option("--check-clip-fail", "Exit 2 when a clip target fails or is missing.")
+    .option("--check-clip-fail", "Exit 2 when a clip target fails, is unknown, or is missing.")
     .option("--no-check-clip-annotate", "Skip clip screenshot annotations.")
     .option(
       "--check-overlap <selector>",
@@ -393,7 +430,10 @@ export function registerBrowseCommand(
       "Allowed overlap depth on either axis in CSS pixels (default 0).",
       "0",
     )
-    .option("--check-overlap-fail", "Exit 2 when an overlap target fails or is missing.")
+    .option(
+      "--check-overlap-fail",
+      "Exit 2 when an overlap target fails, is unknown, or is missing.",
+    )
     .option("--no-check-overlap-annotate", "Skip overlap screenshot annotations.")
     .option(
       "--check-crowd <selector>",
@@ -413,7 +453,7 @@ export function registerBrowseCommand(
         "Pairs closer than this are flagged; negative separation (overlap) always flags.",
       "6",
     )
-    .option("--check-crowd-fail", "Exit 2 when a crowd target fails or is missing.")
+    .option("--check-crowd-fail", "Exit 2 when a crowd target fails, is unknown, or is missing.")
     .option("--no-check-crowd-annotate", "Skip crowd screenshot annotations.")
     .option(
       "--check-placeholder [selector]",
@@ -424,7 +464,10 @@ export function registerBrowseCommand(
         "bug on funnels and reports. Do not point it at a page that documents template " +
         "syntax in prose.",
     )
-    .option("--check-placeholder-fail", "Exit 2 if any placeholder tell is found.")
+    .option(
+      "--check-placeholder-fail",
+      "Run a document-wide placeholder check when needed; exit 2 if the result does not pass.",
+    )
     .option("--no-check-placeholder-annotate", "Skip placeholder screenshot annotations.")
     .option(
       "--check-images [selector]",
@@ -438,7 +481,10 @@ export function registerBrowseCommand(
       "Aspect-ratio deviation above which an image counts as stretched (0–1, default 0.1 = 10%).",
       "0.1",
     )
-    .option("--check-images-fail", "Exit 2 if any image failed to load or is stretched.")
+    .option(
+      "--check-images-fail",
+      "Run a document-wide image check when needed; exit 2 if the result does not pass.",
+    )
     .option("--no-check-images-annotate", "Skip image screenshot annotations.")
     .option(
       "--check-truncation [selector]",
@@ -451,7 +497,10 @@ export function registerBrowseCommand(
       "Overflow past the clip box, in CSS px, above which truncation counts (default 2).",
       "2",
     )
-    .option("--check-truncation-fail", "Exit 2 if any text is actively truncated.")
+    .option(
+      "--check-truncation-fail",
+      "Run a document-wide truncation check when needed; exit 2 if the result does not pass.",
+    )
     .option("--no-check-truncation-annotate", "Skip truncation screenshot annotations.")
     .option(
       "--check-contrast [selector]",
@@ -460,7 +509,10 @@ export function registerBrowseCommand(
         "with --batch to cover light and dark. Text over an image or gradient is reported as " +
         "`unknown`, not failed. Optional selector scopes the sweep (default: whole body).",
     )
-    .option("--check-contrast-fail", "Exit 2 if any text fails the contrast ratio.")
+    .option(
+      "--check-contrast-fail",
+      "Run a document-wide contrast check when needed; exit 2 on fail, unknown, or a missing scope.",
+    )
     .option("--no-check-contrast-annotate", "Skip contrast screenshot annotations.")
     .option(
       "--check-critique [selector]",
@@ -483,7 +535,10 @@ export function registerBrowseCommand(
       "24",
     )
     .option("--check-critique-rubric <text>", "Override the default critique rubric.")
-    .option("--check-critique-fail", "Exit 2 if the critique returns any high-severity finding.")
+    .option(
+      "--check-critique-fail",
+      "Run a whole-page critique when needed; exit 2 unless the critique conclusively passes.",
+    )
     .option(
       "--assert <expr>",
       "Assert a page value (repeatable). Grammar: '<op> <selector> => <expected>', where op is " +
@@ -493,7 +548,7 @@ export function registerBrowseCommand(
       (value: string, previous: string[] = []) => [...previous, value],
       [] as string[],
     )
-    .option("--assert-fail", "Exit 2 if any --assert fails.")
+    .option("--assert-fail", "Exit 2 if any --assert fails; requires at least one --assert.")
     .option(
       "--check-hit [selector]",
       "Check pointer-target size and spacing in the document or optional scope (repeatable).",
@@ -510,7 +565,7 @@ export function registerBrowseCommand(
     )
     .option(
       "--check-hit-fail",
-      "Exit 2 when target sizing fails, is incomplete, or a scope is missing.",
+      "Run a document-wide target-size check when needed; exit 2 when it fails or is incomplete.",
     )
     .option("--no-check-hit-annotate", "Skip target-size screenshot annotations.")
     .option(
@@ -531,7 +586,10 @@ export function registerBrowseCommand(
         "considered a match (0–1, default 0.01 = 1%).",
       "0.01",
     )
-    .option("--diff-fail", "Exit non-zero if --diff mismatchRatio exceeds --diff-threshold.")
+    .option(
+      "--diff-fail",
+      "Exit non-zero if --diff mismatchRatio exceeds --diff-threshold; requires --diff.",
+    )
     .option(
       "--no-dev-overlay",
       "Skip auto-capture of Next.js dev-overlay issues. Default: capture every queued error (kind/code/message/stack) when a <nextjs-portal> shadow root is present. Necessary because Next.js 16 + React 19 route hydration errors + most React warnings through onCaughtError → next-devtools' errorQueue, NOT through console.error, so Playwright's standard listener doesn't see them. Surfaces them in the JSON envelope under `devOverlay`.",
@@ -552,6 +610,7 @@ async function runBrowse(
   opts: BrowseOpts,
   context: HarneryProgramContext | undefined,
 ): Promise<void> {
+  normalizeCheckFailOptions(opts);
   const alignAxis = parseLayoutAxis(opts.checkAlignAxis ?? "auto", "--check-align-axis");
   const gapAxis = parseLayoutAxis(opts.checkGapAxis ?? "auto", "--check-gap-axis");
   const alignThreshold = parseNonNegativeNumber(
@@ -584,6 +643,20 @@ async function runBrowse(
       : new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "harn-browse" });
   const headed = opts.login || opts.headed;
   const viewport = parseViewport(opts.viewport ?? "desktop");
+  const proxy = opts.proxyFromEnv ? browserProxyFromEnv() : undefined;
+  const proxyGate = opts.proxyFromEnv ? browserProxyGateFromEnv() : null;
+  if (opts.loginCloseFile && !opts.login) {
+    throw new Error("--login-close-file requires --login.");
+  }
+  if (opts.controlFile && !opts.login) {
+    throw new Error("--control-file requires --login.");
+  }
+  const loginCloseFile = opts.loginCloseFile ? resolve(opts.loginCloseFile) : null;
+  if (loginCloseFile && existsSync(loginCloseFile)) {
+    throw new Error(
+      `Login close signal already exists at ${loginCloseFile}. Remove the stale file before launching.`,
+    );
+  }
 
   const browser = new Browser({
     profileDir: opts.profile ?? DEFAULT_PROFILE,
@@ -594,14 +667,28 @@ async function runBrowse(
     waitUntil: opts.waitUntil as BrowseOpts["waitUntil"] as never,
     recordHarPath: opts.networkHar ? resolve(opts.networkHar) : undefined,
     extraHeaders: context?.extraHeaders,
-    launchArgs: resolveLaunchArgs(opts, Boolean(headed)),
+    launchArgs: resolveLaunchArgs(opts, Boolean(headed), Boolean(proxy)),
+    proxy,
   });
 
   // Print mode: --snapshot / --html / --json all suppress file writes.
   const printMode = opts.snapshot || opts.html || opts.json;
+  let controlServer: BrowserSessionServer | null = null;
+  let receivedSignal: NodeJS.Signals | null = null;
+  let resolveSignal: (() => void) | null = null;
+  const signalPromise = new Promise<void>((resolveSignalPromise) => {
+    resolveSignal = resolveSignalPromise;
+  });
+  const handleSignal = (signal: NodeJS.Signals) => {
+    receivedSignal = signal;
+    resolveSignal?.();
+  };
+  const handleSigint = () => handleSignal("SIGINT");
+  const handleSigterm = () => handleSignal("SIGTERM");
 
   try {
     await browser.open();
+    if (proxyGate) await verifyBrowserProxyGate(browser, proxyGate);
     const navResult = await browser.navigate(url);
 
     if (opts.fill) {
@@ -790,14 +877,41 @@ async function runBrowse(
       await browser.annotateContent(contentBoxes);
     }
 
+    if (opts.controlFile) {
+      controlServer = await startBrowserSessionServer(opts.controlFile, browser);
+      process.once("SIGINT", handleSigint);
+      process.once("SIGTERM", handleSigterm);
+      emit.log(`browser session ready: ${controlServer.descriptorPath}`, "info");
+    }
+
     if (opts.login) {
-      await new Promise<void>((res) => {
+      const lifecycleAbort = new AbortController();
+      const closeWaits: Promise<void>[] = [];
+      if (loginCloseFile) {
+        emit.log(
+          `[--login] Headed Chromium is open. Drive the visible window now. Create ${loginCloseFile} to close cleanly.`,
+          "info",
+        );
+        closeWaits.push(waitForLoginCloseFile(loginCloseFile, lifecycleAbort.signal));
+      } else {
         emit.log(
           "[--login] Headed Chromium is open. Walk through your auth flow now. Press Enter here to close + persist cookies into the profile.",
           "info",
         );
-        process.stdin.once("data", () => res());
-      });
+        closeWaits.push(waitForTerminalEnter(lifecycleAbort.signal));
+      }
+      if (controlServer) {
+        closeWaits.push(controlServer.closeRequested, signalPromise);
+      }
+      await Promise.race(closeWaits);
+      lifecycleAbort.abort();
+      if (controlServer) await controlServer.stopAccepting();
+    }
+
+    if (opts.exportCookies) {
+      const exportPath = resolve(opts.exportCookies);
+      writeNetscapeCookieFile(exportPath, await browser.cookies());
+      emit.log(`exported live profile cookies to ${exportPath} (mode 600)`, "info");
     }
 
     // Auto-capture Next.js dev-overlay issues unless --no-dev-overlay was passed.
@@ -911,12 +1025,21 @@ async function runBrowse(
       }
     }
 
-    if (opts.checkRuntsFail && runts && runts.runts.length > 0) {
-      for (const hit of runts.runts) {
+    if (opts.checkRuntsFail && runts && runts.outcome !== "pass") {
+      if (!runts.found) {
+        emit.log(`check-runts FAIL ${runts.scope}: scope not found`, "warn");
+      } else if (runts.outcome === "unknown") {
         emit.log(
-          `check-runts FAIL ${hit.block}: last line is a lone "${hit.word}" ("…${hit.snippet.slice(-40)}")`,
+          `check-runts FAIL ${runts.scope ?? "document"}: sweep incomplete after ${runts.scannedBlocks} blocks`,
           "warn",
         );
+      } else {
+        for (const hit of runts.runts) {
+          emit.log(
+            `check-runts FAIL ${hit.block}: last line is a lone "${hit.word}" ("…${hit.snippet.slice(-40)}")`,
+            "warn",
+          );
+        }
       }
       process.exitCode = 2;
     }
@@ -935,9 +1058,12 @@ async function runBrowse(
 
     applyLayoutLintFailGates(opts, layoutLint, hit);
     applyContentFailGates(opts, content);
-    if (opts.checkCritiqueFail && critique && critique.outcome === "fail") {
-      const high = critique.findings.filter((f) => f.severity === "high").length;
-      emit.log(`check-critique FAIL: ${high} high-severity finding(s)`, "warn");
+    if (opts.checkCritiqueFail && critique && critique.outcome !== "pass") {
+      const detail =
+        critique.outcome === "skipped"
+          ? (critique.error ?? "critique was skipped")
+          : `${critique.findings.filter((f) => f.severity === "high").length} high-severity finding(s)`;
+      emit.log(`check-critique FAIL: ${detail}`, "warn");
       process.exitCode = 2;
     }
     if (opts.assertFail && asserts) {
@@ -951,7 +1077,11 @@ async function runBrowse(
       if (failed.length > 0) process.exitCode = 2;
     }
   } finally {
+    process.removeListener("SIGINT", handleSigint);
+    process.removeListener("SIGTERM", handleSigterm);
+    await controlServer?.cleanup();
     await browser.close();
+    if (receivedSignal) process.exitCode = receivedSignal === "SIGINT" ? 130 : 143;
   }
 }
 
@@ -1155,7 +1285,7 @@ async function runTrioMode(
 
   const written: string[] = [];
 
-  const skipScreenshot = opts.screenshot === false || opts.domOnly === true;
+  const skipScreenshot = opts.screenshot === false;
   let pngPath: string | undefined;
   let pngBytes: number | undefined;
   let captureEvalResult: unknown;
@@ -1176,9 +1306,7 @@ async function runTrioMode(
     }
     written.push(pngPath);
   } else if (opts.captureEvaluate) {
-    throw new Error(
-      "--capture-evaluate requires a screenshot; remove --no-screenshot / --dom-only.",
-    );
+    throw new Error("--capture-evaluate requires a screenshot; remove --no-screenshot.");
   }
 
   const htmlPath = `${prefix}.html`;
@@ -1232,9 +1360,7 @@ async function runTrioMode(
   let savedBaseline: SaveBaselineResult | undefined;
   let diff: DiffResult | undefined;
   if ((opts.baseline || opts.diff) && !pngPath) {
-    throw new Error(
-      "--baseline / --diff require a screenshot; --no-screenshot / --dom-only disables it.",
-    );
+    throw new Error("--baseline / --diff require a screenshot; --no-screenshot disables it.");
   }
   if (opts.baseline && pngPath) {
     savedBaseline = saveBaseline(pngPath, opts.baseline);
@@ -1328,6 +1454,13 @@ async function runTrioMode(
     emit.log(`check-overflow: [${ok ? "OK" : "FAIL"}] ${detail}`, ok ? "info" : "warn");
   }
 
+  if (runts) {
+    emit.log(
+      `check-runts: [${runts.outcome.toUpperCase()}] ${runts.scope ?? "document"}: ${runts.runts.length} runt${runts.runts.length === 1 ? "" : "s"} in ${runts.scannedBlocks} scanned block${runts.scannedBlocks === 1 ? "" : "s"}${runts.truncated ? " (incomplete)" : ""}`,
+      runts.outcome === "pass" ? "info" : "warn",
+    );
+  }
+
   if (layoutLint) {
     logLayoutLintSummary(layoutLint);
   }
@@ -1397,6 +1530,59 @@ function parseNonNegativeNumber(value: string, flag: string): number {
   return parsed;
 }
 
+function normalizeCheckFailOptions(opts: BrowseOpts): void {
+  // Whole-document checks can be enabled by their fail flag. Selector-based
+  // checks cannot invent a scope, so reject the invocation before Chromium
+  // opens instead of returning a misleading zero.
+  if (opts.checkOverflowFail) opts.checkOverflow = true;
+  if (opts.checkRuntsFail && opts.checkRunts === undefined) opts.checkRunts = true;
+  if (opts.checkPlaceholderFail && opts.checkPlaceholder === undefined) {
+    opts.checkPlaceholder = true;
+  }
+  if (opts.checkImagesFail && opts.checkImages === undefined) opts.checkImages = true;
+  if (opts.checkTruncationFail && opts.checkTruncation === undefined) {
+    opts.checkTruncation = true;
+  }
+  if (opts.checkContrastFail && opts.checkContrast === undefined) opts.checkContrast = true;
+  if (opts.checkCritiqueFail && opts.checkCritique === undefined) opts.checkCritique = true;
+  if (opts.checkHitFail && (!opts.checkHit || opts.checkHit.length === 0)) {
+    opts.checkHit = [null];
+  }
+
+  const requireTargets = (
+    failEnabled: boolean | undefined,
+    targets: unknown[] | undefined,
+    failFlag: string,
+    checkFlag: string,
+  ): void => {
+    if (failEnabled && (!targets || targets.length === 0)) {
+      throw new Error(`${failFlag} requires ${checkFlag}.`);
+    }
+  };
+
+  requireTargets(
+    opts.checkVisibleFail,
+    opts.checkVisible,
+    "--check-visible-fail",
+    "--check-visible",
+  );
+  requireTargets(opts.checkWidthFail, opts.checkWidth, "--check-width-fail", "--check-width");
+  requireTargets(opts.checkAlignFail, opts.checkAlign, "--check-align-fail", "--check-align");
+  requireTargets(opts.checkGapFail, opts.checkGap, "--check-gap-fail", "--check-gap");
+  requireTargets(opts.checkClipFail, opts.checkClip, "--check-clip-fail", "--check-clip");
+  requireTargets(
+    opts.checkOverlapFail,
+    opts.checkOverlap,
+    "--check-overlap-fail",
+    "--check-overlap",
+  );
+  requireTargets(opts.checkCrowdFail, opts.checkCrowd, "--check-crowd-fail", "--check-crowd");
+  requireTargets(opts.assertFail, opts.assert, "--assert-fail", "--assert");
+  if (opts.diffFail && !opts.diff) {
+    throw new Error("--diff-fail requires --diff.");
+  }
+}
+
 function parseLayoutAxis(value: string, flag: string): LayoutAxis {
   if (value === "auto" || value === "x" || value === "y") return value;
   throw new Error(`${flag} must be auto, x, or y (got: ${value})`);
@@ -1466,12 +1652,16 @@ function applyLayoutLintFailGates(
     results: T[] | undefined,
   ): void => {
     if (!enabled || !results) return;
-    const failed = results.filter((result) => !result.found || result.outcome === "fail");
+    const failed = results.filter(
+      (result) => !result.found || result.outcome === "fail" || result.outcome === "unknown",
+    );
     for (const result of failed) {
-      emit.log(
-        `check-${rule} FAIL ${result.selector}: ${result.found ? "rendered relation failed" : "element not found"}`,
-        "warn",
-      );
+      const reason = !result.found
+        ? "element not found"
+        : result.outcome === "unknown"
+          ? "result unknown"
+          : "rendered relation failed";
+      emit.log(`check-${rule} FAIL ${result.selector}: ${reason}`, "warn");
     }
     if (failed.length > 0) process.exitCode = 2;
   };
@@ -1602,8 +1792,13 @@ function applyContentFailGates(opts: BrowseOpts, content: ContentChecksResult |
     result: { found: boolean; outcome: string } | undefined,
   ): void => {
     if (!enabled || !result) return;
-    if (!result.found || result.outcome === "fail") {
-      emit.log(`check-${rule} FAIL: ${result.found ? "issues found" : "scope not found"}`, "warn");
+    if (!result.found || result.outcome !== "pass") {
+      const reason = !result.found
+        ? "scope not found"
+        : result.outcome === "unknown"
+          ? "result unknown"
+          : "issues found";
+      emit.log(`check-${rule} FAIL: ${reason}`, "warn");
       process.exitCode = 2;
     }
   };
@@ -1682,7 +1877,7 @@ function summarizeDiagnostics(diag: Diagnostics): Record<string, unknown> {
  *   2. HARNERY_BROWSER_ARGS env (whitespace-separated) — a machine-wide default.
  *   3. --browser-arg flags on this invocation (repeatable).
  */
-function resolveLaunchArgs(opts: BrowseOpts, headed: boolean): string[] {
+function resolveLaunchArgs(opts: BrowseOpts, headed: boolean, proxyEnabled: boolean): string[] {
   const args: string[] = [];
   if (headed && !process.env.HARNERY_BROWSER_NO_WSL_DEFAULTS) {
     args.push(...wslHeadedLaunchArgs());
@@ -1690,9 +1885,57 @@ function resolveLaunchArgs(opts: BrowseOpts, headed: boolean): string[] {
   const envArgs = process.env.HARNERY_BROWSER_ARGS?.trim();
   if (envArgs) args.push(...envArgs.split(/\s+/));
   if (opts.browserArg && opts.browserArg.length > 0) args.push(...opts.browserArg);
+  if (proxyEnabled) args.push(WEBRTC_PROXY_ONLY_ARG);
   return [...new Set(args)];
 }
 
+async function verifyBrowserProxyGate(
+  browser: Browser,
+  gate: { checkUrl: string; expectedIp: string },
+): Promise<void> {
+  const result = await browser.navigate(gate.checkUrl);
+  if (result.status === null || result.status < 200 || result.status >= 300) {
+    throw new Error(
+      `Browser proxy gate failed before target navigation (HTTP ${result.status ?? "unknown"}).`,
+    );
+  }
+  const body = await browser.evaluate<string>("document.body?.innerText ?? ''");
+  const observedIp = extractObservedIp(body);
+  if (observedIp !== gate.expectedIp) {
+    throw new Error(
+      `Browser proxy gate returned ${observedIp ?? "no IP"}; expected ${gate.expectedIp}. Target navigation was blocked.`,
+    );
+  }
+  emit.log(`browser proxy gate: ${observedIp} · expected IP confirmed`, "info");
+}
+
+async function waitForLoginCloseFile(path: string, signal?: AbortSignal): Promise<void> {
+  while (!existsSync(path) && !signal?.aborted) {
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  if (signal?.aborted) return;
+  unlinkSync(path);
+}
+
+async function waitForTerminalEnter(signal: AbortSignal): Promise<void> {
+  await new Promise<void>((resolveWait) => {
+    const onData = () => {
+      cleanup();
+      resolveWait();
+    };
+    const onAbort = () => {
+      cleanup();
+      resolveWait();
+    };
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      signal.removeEventListener("abort", onAbort);
+    };
+    process.stdin.once("data", onData);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
 function parseViewport(spec: string): { width: number; height: number } {
   const preset = VIEWPORT_PRESETS[spec.toLowerCase()];
   if (preset) return preset;

package/src/commands/checkpoint.ts

@@ -165,7 +165,7 @@ function resolveContinuityIdentity(
 }
 
 function adapterFromPlatform(platform: string | undefined): Adapter | null {
-  if (platform === "claude_code" || platform === "claude-code") return "claude-code";
+  if (platform === "claude-code") return "claude-code";
   if (platform === "cursor") return "cursor";
   if (platform === "codex") return "codex";
   return null;

package/src/commands/deinit.ts

@@ -34,8 +34,10 @@ import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { DEFAULT_BIN_NAME } from "../core/config.ts";
 import { ADAPTER_SPECS, type AdapterId } from "../core/hooks/adapter/events.ts";
+import type { SettingsFile } from "../core/hooks/adapter/wiring.ts";
 import { removeInstructions } from "../lib/instructions/apply.ts";
-import { type SettingsFile, unwireHooks } from "./init.ts";
+import { removeGitHooks } from "../lib/instructions/git-hooks.ts";
+import { unwireHooks } from "./init.ts";
 
 interface DeinitOpts {
   adapter: string;
@@ -138,6 +140,10 @@ export function registerDeinitCommand(program: Command, emit: EmitContext, binNa
       const removed = removeInstructions(projectRoot, { adapter, dryRun });
       actions.push(...removed.actions, ...removed.warnings.map((w) => `! ${w}`));
 
+      // ── 1c. git-hook managed regions ───────────────────────────────────────
+      const gitHooks = removeGitHooks(projectRoot, { dryRun });
+      actions.push(...gitHooks.actions, ...gitHooks.warnings.map((w) => `! ${w}`));
+
       // ── 2. coord root (opt-in; destructive) ────────────────────────────────
       if (purgeState) {
         if (!coordExists) {