harnery 0.31.5 → 0.32.0

package/dist/commands/browse.js

@@ -1,8 +1,9 @@
-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 { resolveBinName } from "../core/config.js";
-import { Browser, captureDevOverlay, DEFAULT_CRITIQUE_RUBRIC, parseAssertSpec, runCritique, tilesFromFullPage, wslHeadedLaunchArgs, } from "../lib/browser/index.js";
+import { Browser, browserProxyFromEnv, browserProxyGateFromEnv, captureDevOverlay, DEFAULT_CRITIQUE_RUBRIC, extractObservedIp, parseAssertSpec, runCritique, tilesFromFullPage, WEBRTC_PROXY_ONLY_ARG, writeNetscapeCookieFile, wslHeadedLaunchArgs, } from "../lib/browser/index.js";
+import { startBrowserSessionServer, } from "../lib/browser/session-control.js";
 import { diffAgainstBaseline, saveBaseline, } from "../lib/browser/visual-diff.js";
 import { CookieJar } from "../lib/cookies/index.js";
 /**
@@ -44,7 +45,6 @@ export function registerBrowseCommand(program, emitParam, context) {
         .description("Headless Chromium with persistent profile + cookie jar. Default writes a trio of files (last.png, last.html, last.json) for the LLM iteration loop; --snapshot/--html/--json switch to stdout-print mode.")
         .option("--out <prefix>", "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("--html", `Print raw outer HTML to stdout (skips file writes; pair with \`${resolveBinName()} read -\`)`)
@@ -62,15 +62,22 @@ export function registerBrowseCommand(program, emitParam, context) {
         .option("--network-har <path>", "Record network traffic to a HAR file (finalized on close)")
         .option("--viewport <preset|WxH>", "Viewport: mobile (390x844), tablet (820x1180), desktop (1280x800), hd (1920x1080), or explicit '1920x1080'", "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>", "Extra Chromium launch flag, passed straight to the browser (repeatable). " +
         "e.g. --browser-arg --disable-gpu. Also settable machine-wide via the " +
         "HARNERY_BROWSER_ARGS env var (whitespace-separated). Under WSL, headed " +
         "launches auto-add --disable-gpu to fix blank-window paint; opt out with " +
         "HARNERY_BROWSER_NO_WSL_DEFAULTS=1.", (value, prev = []) => [...prev, value], [])
+        .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", "load")
         .option("--timeout <ms>", "Navigation timeout in milliseconds", "30000")
         .option("--check-visible <selector>", "Run an occlusion check on this selector after navigation + batch. " +
@@ -96,7 +103,7 @@ export function registerBrowseCommand(program, emitParam, context) {
         .option("--check-overflow", "Assert the document has no horizontal overflow (document.scrollWidth <= window.innerWidth). " +
         "Surfaces protruding elements in the JSON envelope and annotates them on the screenshot. " +
         "Catches the class of mobile-layout bug where a nav/table overflows the viewport edge.")
-        .option("--check-overflow-fail", "Exit non-zero if --check-overflow detects horizontal overflow.")
+        .option("--check-overflow-fail", "Run --check-overflow and exit 2 if horizontal overflow is detected.")
         .option("--no-check-overflow-annotate", "Skip drawing overflow annotations on the screenshot (JSON still emitted).")
         .option("--check-runts [selector]", "Scan text blocks for runts (a single word alone on a block's last visual line) " +
         "by counting words on the last line via per-word Range rects — width thresholds " +
@@ -104,26 +111,27 @@ export function registerBrowseCommand(program, emitParam, context) {
         "Atomic tokens (URLs, emails, phone numbers) are excluded. Reports hits in the JSON " +
         "envelope under `runts` and annotates them on the screenshot.")
         .option("--check-runts-min-chars <n>", "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).")
         .option("--check-align <selector>", "Check rendered child-content alignment inside this container (repeatable).", (value, previous = []) => [...previous, value], [])
         .option("--check-align-axis <axis>", "Alignment axis: auto | x | y (default auto).", "auto")
         .option("--check-align-threshold <px>", "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>", "Check adjacent rendered gaps inside this container (repeatable).", (value, previous = []) => [...previous, value], [])
         .option("--check-gap-axis <axis>", "Gap axis: auto | x | y (default auto).", "auto")
         .option("--check-gap-expected <px>", "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).", (value, previous = []) => [...previous, value], [])
+        .option("--check-clip <selector>", "Check every matching container for descendant boxes or text paint leaving its " +
+        "rectangular clipping chain or nearest block parent (repeatable).", (value, previous = []) => [...previous, value], [])
         .option("--check-clip-threshold <px>", "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>", "Check measurable in-flow siblings for unintended overlap (repeatable).", (value, previous = []) => [...previous, value], [])
         .option("--check-overlap-threshold <px>", "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>", "Flag adjacent card panels (full border, modest corner radius, or box-shadow) " +
         "that touch or nearly touch. Also treats wrappers that contain panels as " +
@@ -134,7 +142,7 @@ export function registerBrowseCommand(program, emitParam, context) {
         "uneven spacing, so a uniformly-flush stack passes). Repeatable.", (value, previous = []) => [...previous, value], [])
         .option("--check-crowd-min <px>", "Minimum acceptable edge gap between adjacent panel faces in CSS px (default 6). " +
         "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]", "Scan rendered text for unrendered template tokens and bound-value tells: " +
         "JS template literals, `{{x}}` handlebars, `[object Object]`, `Invalid Date`, " +
@@ -142,26 +150,26 @@ export function registerBrowseCommand(program, emitParam, context) {
         "scopes the sweep (default: whole body). Catches the most common generation " +
         "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]", "Audit <img> elements for load + aspect health: a failed load (naturalWidth 0), " +
         "a still-loading image, or a stretched image (rendered aspect ratio far from the " +
         "intrinsic one, with an object-fit that does not correct it). Optional selector " +
         "scopes the sweep (default: whole body).")
         .option("--check-images-tolerance <ratio>", "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]", "Flag text actively cut off by an ellipsis or -webkit-line-clamp — the author asked " +
         "to truncate AND the content overflows. High precision: it does not flag plain " +
         "overflow:hidden clips. Optional selector scopes the sweep (default: whole body).")
         .option("--check-truncation-tolerance <px>", "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]", "Flag rendered text below the WCAG AA contrast ratio (4.5:1 normal, 3:1 large) against " +
         "its effective background. Runs at whatever theme the page is in, so toggle the theme " +
         "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]", "Hand the rendered page to a vision model for a visual-defect review, tile by " +
         "tile. Catches the long tail heuristic checks can't enumerate. Default tiling " +
@@ -173,18 +181,18 @@ export function registerBrowseCommand(program, emitParam, context) {
         .option("--check-critique-overlap <px>", "Vertical overlap between bands so a finding at a seam stays visible (default 120).", "120")
         .option("--check-critique-max-tiles <n>", "Cap on tiles sent to the model, to bound cost (default 24).", "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 " +
         "text (trimmed text equals), contains (text includes), matches (text matches a regex), " +
         "count (match count vs a number or >=/<=/>/< comparator), exists / absent (no => needed). " +
         "e.g. --assert 'text h1 => Welcome' --assert 'count .card => >=3' --assert 'absent .error'.", (value, previous = []) => [...previous, value], [])
-        .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).", (value, previous = []) => [
         ...previous,
         typeof value === "string" ? value : null,
     ], [])
         .option("--check-hit-profile <profile>", "Target profile: wcag-aa (24px) | comfortable (44px).", "wcag-aa")
-        .option("--check-hit-fail", "Exit 2 when target sizing fails, is incomplete, or a scope is missing.")
+        .option("--check-hit-fail", "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("--baseline <name>", "Save the captured screenshot as a named baseline at " +
         "~/.cache/harnery/visual-baselines/<name>.png. Use --diff <name> later to " +
@@ -194,7 +202,7 @@ export function registerBrowseCommand(program, emitParam, context) {
         "similarity in the JSON envelope.")
         .option("--diff-threshold <ratio>", "mismatchRatio (mismatchedPixels / totalPixels) below which the diff is " +
         "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`.")
         .action(async (url, opts) => {
         try {
@@ -208,6 +216,7 @@ export function registerBrowseCommand(program, emitParam, context) {
     });
 }
 async function runBrowse(url, opts, context) {
+    normalizeCheckFailOptions(opts);
     const alignAxis = parseLayoutAxis(opts.checkAlignAxis ?? "auto", "--check-align-axis");
     const gapAxis = parseLayoutAxis(opts.checkGapAxis ?? "auto", "--check-gap-axis");
     const alignThreshold = parseNonNegativeNumber(opts.checkAlignThreshold ?? "2", "--check-align-threshold");
@@ -225,6 +234,18 @@ async function runBrowse(url, opts, context) {
         : 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,
         headed,
@@ -234,12 +255,27 @@ async function runBrowse(url, opts, context) {
         waitUntil: opts.waitUntil,
         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 = null;
+    let receivedSignal = null;
+    let resolveSignal = null;
+    const signalPromise = new Promise((resolveSignalPromise) => {
+        resolveSignal = resolveSignalPromise;
+    });
+    const handleSignal = (signal) => {
+        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) {
             const sep = opts.fill.indexOf("=>");
@@ -408,11 +444,35 @@ async function runBrowse(url, opts, context) {
         if (contentBoxes.length > 0) {
             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((res) => {
+            const lifecycleAbort = new AbortController();
+            const closeWaits = [];
+            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.
         // Cheap no-op when no <nextjs-portal> shadow host is present (non-Next.js page).
@@ -485,9 +545,17 @@ async function runBrowse(url, opts, context) {
                 process.exitCode = 2;
             }
         }
-        if (opts.checkRuntsFail && runts && runts.runts.length > 0) {
-            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");
+        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 ${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;
         }
@@ -501,9 +569,11 @@ async function runBrowse(url, opts, context) {
         }
         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) {
@@ -516,7 +586,12 @@ async function runBrowse(url, opts, context) {
         }
     }
     finally {
+        process.removeListener("SIGINT", handleSigint);
+        process.removeListener("SIGTERM", handleSigterm);
+        await controlServer?.cleanup();
         await browser.close();
+        if (receivedSignal)
+            process.exitCode = receivedSignal === "SIGINT" ? 130 : 143;
     }
 }
 async function runBatch(browser, batch, defaultTimeoutMs) {
@@ -684,7 +759,7 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
     const prefix = resolveOutPrefix(opts.out);
     mkdirSync(dirname(prefix), { recursive: true });
     const written = [];
-    const skipScreenshot = opts.screenshot === false || opts.domOnly === true;
+    const skipScreenshot = opts.screenshot === false;
     let pngPath;
     let pngBytes;
     let captureEvalResult;
@@ -707,7 +782,7 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
         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`;
     const html = await browser.htmlContent(opts.selector);
@@ -770,7 +845,7 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
     let savedBaseline;
     let diff;
     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);
@@ -847,6 +922,9 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
                 : ""}`;
         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);
     }
@@ -902,6 +980,46 @@ function parseNonNegativeNumber(value, flag) {
     }
     return parsed;
 }
+function normalizeCheckFailOptions(opts) {
+    // 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, targets, failFlag, checkFlag) => {
+        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, flag) {
     if (value === "auto" || value === "x" || value === "y")
         return value;
@@ -943,9 +1061,14 @@ function applyLayoutLintFailGates(opts, layoutLint, hit) {
     const gate = (enabled, rule, results) => {
         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;
@@ -1057,8 +1180,13 @@ function applyContentFailGates(opts, content) {
     const gate = (enabled, rule, result) => {
         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;
         }
     };
@@ -1122,7 +1250,7 @@ function summarizeDiagnostics(diag) {
  *   2. HARNERY_BROWSER_ARGS env (whitespace-separated) — a machine-wide default.
  *   3. --browser-arg flags on this invocation (repeatable).
  */
-function resolveLaunchArgs(opts, headed) {
+function resolveLaunchArgs(opts, headed, proxyEnabled) {
     const args = [];
     if (headed && !process.env.HARNERY_BROWSER_NO_WSL_DEFAULTS) {
         args.push(...wslHeadedLaunchArgs());
@@ -1132,8 +1260,48 @@ function resolveLaunchArgs(opts, headed) {
         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, gate) {
+    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("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, signal) {
+    while (!existsSync(path) && !signal?.aborted) {
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    if (signal?.aborted)
+        return;
+    unlinkSync(path);
+}
+async function waitForTerminalEnter(signal) {
+    await new Promise((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) {
     const preset = VIEWPORT_PRESETS[spec.toLowerCase()];
     if (preset)

package/dist/commands/checkpoint.js

@@ -134,7 +134,7 @@ function resolveContinuityIdentity(context, opts) {
     return { coordRoot, instanceId, sessionId, adapter };
 }
 function adapterFromPlatform(platform) {
-    if (platform === "claude_code" || platform === "claude-code")
+    if (platform === "claude-code")
         return "claude-code";
     if (platform === "cursor")
         return "cursor";

package/dist/commands/deinit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deinit.d.ts","sourceRoot":"","sources":["../../src/commands/deinit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAanD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CA+GjG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE;IACtC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAEV;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C"}
+{"version":3,"file":"deinit.d.ts","sourceRoot":"","sources":["../../src/commands/deinit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAenD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAmHjG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE;IACtC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAEV;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C"}

package/dist/commands/deinit.js

@@ -32,6 +32,7 @@ import { createInterface } from "node:readline";
 import { DEFAULT_BIN_NAME } from "../core/config.js";
 import { ADAPTER_SPECS } from "../core/hooks/adapter/events.js";
 import { removeInstructions } from "../lib/instructions/apply.js";
+import { removeGitHooks } from "../lib/instructions/git-hooks.js";
 import { unwireHooks } from "./init.js";
 export function registerDeinitCommand(program, emit, binName) {
     // The interactive prompt + engine-removal hint are standalone-harn niceties.
@@ -117,6 +118,9 @@ export function registerDeinitCommand(program, emit, binName) {
         // ── 1b. agent-facing instructions block + skills ───────────────────────
         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) {

package/dist/commands/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/commands/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiC1E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA8GN"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/commands/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAmC1E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA0IN"}

package/dist/commands/docs.js

@@ -1,6 +1,7 @@
 import { initDocsContext as initDocs, scanDocs } from "../lib/docs.js";
 import { initDocsMigrationContext, runFrontmatterMigration, } from "../lib/docs-frontmatter-migrate.js";
 import { initDocsContext as initDocsIndex, runIndex } from "../lib/docs-index.js";
+import { initDocsContext as initDocsLinks, runLinks } from "../lib/docs-links.js";
 import { initDocsContext as initDocsLint, runLint } from "../lib/docs-lint.js";
 import { readDocsMetadata, readDocsMetadataKey } from "../lib/docs-meta.js";
 import { countColdHandoffs, initDocsContext as initDocsSweep, runSweep, } from "../lib/docs-sweep.js";
@@ -17,6 +18,7 @@ function ensureContext(context) {
         extraExcludedPrefixes: context.extraDocsExcludedPrefixes,
         docsRootAllowlist: context.docsRootAllowlist,
     });
+    initDocsLinks({ ...opts, extraExcludedPrefixes: context.extraDocsExcludedPrefixes });
     initDocsSweep(opts);
 }
 let emit;
@@ -89,6 +91,25 @@ export function registerDocsCommand(program, emitParam, context) {
             emit.error({ code: "docs_error", message: msg });
         }
     });
+    docs
+        .command("links")
+        .description("Check internal Markdown link targets and heading fragments")
+        .option("--repo <name>", "Limit to one submodule or '.' for parent")
+        .option("--no-fragments", "Check target existence only; skip heading-fragment validation")
+        .option("--strict", "Report findings in archive/audit/changelog docs as errors, not warnings")
+        .option("--check-escapes", "Also flag links that resolve outside their own repo root")
+        .option("--fail", "Exit non-zero when errors are found (advisory by default)")
+        .option("--format <type>", "Output format: human, json", "human")
+        .action(async (opts) => {
+        try {
+            ensureContext(context);
+            await handleLinks(opts);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            emit.error({ code: "docs_error", message: msg });
+        }
+    });
     docs
         .command("sweep")
         .description("Surface stalled lifecycle states: stalled plans, cold issues, unverified runbooks")
@@ -185,6 +206,25 @@ async function handleLint(opts) {
     if (errors.length > 0)
         emit.setExitCode(1);
 }
+// --- `harn docs links` ---
+/**
+ * Advisory by default: a clean exit code even with findings, because turning
+ * link health into a gate is an enforcement policy decision for the host, not
+ * something this command should assume. `--fail` is the opt-in for CI or a hook.
+ */
+async function handleLinks(opts) {
+    if (opts.format === "json")
+        emit.config({ format: "json" });
+    const report = await runLinks({
+        repo: opts.repo,
+        noFragments: opts.fragments === false,
+        strict: opts.strict,
+        checkEscapes: opts.checkEscapes,
+    });
+    emit.data({ ...report, advisory: !opts.fail });
+    if (opts.fail && report.error_count > 0)
+        emit.setExitCode(1);
+}
 // --- `harn docs sweep` ---
 async function handleSweep(opts) {
     if (opts.format === "json")

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAanD,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAOD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAmD/E;AAED,wBAAgB,SAAS,IAAI,KAAK,EAAE,CAcnC"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAgBnD,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAOD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAmD/E;AAED,wBAAgB,SAAS,IAAI,KAAK,EAAE,CAsBnC"}