harnery 0.41.0 → 0.42.0

package/dist/commands/browse.js

@@ -5,8 +5,11 @@ import { dirname, isAbsolute, resolve } from "node:path";
 import { chromium } from "playwright";
 import { PNG } from "pngjs";
 import { resolveBinName } from "../core/config.js";
+import { splitBatchSteps } from "../lib/browser/batch-steps.js";
 import { CAPTURE_FIDELITY_MISMATCH_THRESHOLD, compareBand, cropNativePng, decideFidelity, pngDimensions, } from "../lib/browser/capture-fidelity.js";
+import { createPageDriver, createRng, DEFAULT_COLLECT_LIMITS, PACING_LIMITS, parseProbability, parseRange, presetNames, randomSeed, resolveCollectSpec, runCollect, scrollPacingFromEnv, } from "../lib/browser/collect/index.js";
 import { Browser, browserProxyFromEnv, browserProxyGateFromEnv, captureDevOverlay, chromeMajorFromExecutable, DEFAULT_CRITIQUE_RUBRIC, extractObservedIp, installedChromeChannel, installedChromePath, parseAssertSpec, resolveUserAgent, runCritique, tilesFromFullPage, WEBRTC_PROXY_ONLY_ARG, writeNetscapeCookieFile, wslHeadedLaunchArgs, } from "../lib/browser/index.js";
+import { isWSL } from "../lib/browser/launch-args.js";
 import { allocateTileBudget, validatePageReviewAllocation, } from "../lib/browser/page-review-budget.js";
 import { PAGE_REVIEW_CAPTURE_PLAN_SCHEMA, } from "../lib/browser/page-review-contracts.js";
 import { findPackTile, gateHitsFromEnvelope, readPackContext, tileId, writePackContext, writePackExpandedTile, } from "../lib/browser/page-review-pack.js";
@@ -19,7 +22,8 @@ import { startBrowserSessionServer, } from "../lib/browser/session-control.js";
 import { captureThumbnailFingerprint, registerCaptureThumbnail, } from "../lib/browser/thumbnail-association.js";
 import { reviewCandidateRects } from "../lib/browser/tiling.js";
 import { diffAgainstBaseline, saveBaseline, } from "../lib/browser/visual-diff.js";
-import { applyExtraCookies, CookieJar } from "../lib/cookies/index.js";
+import { harvestDomain, harvestWindowsChromeCookies, stopWindowsChromeProfile, windowsChromePath, windowsLocalAppData, windowsPlainProfile, wslPathToWindows, } from "../lib/browser/windows-chrome.js";
+import { applyExtraCookies, CookieJar, mergeCookies } from "../lib/cookies/index.js";
 import { commandPaceGate } from "../lib/pace/index.js";
 /**
  * `harn browse <url>`: Playwright-backed page navigation with shared
@@ -73,21 +77,46 @@ export function registerBrowseCommand(program, emitParam, context, binName = res
         .option("--capture-evaluate <js>", "In trio mode, evaluate JS inside the exact screenshot viewport immediately before capture; result is written as captureEval")
         .option("--batch <steps>", "Run multiple steps in one session, semicolon-separated. Each step is one of: " +
         "`click <selector>`, `fill <selector=>value>`, `press <key>`, `wait <selector|ms>`, `eval <js>`, `reload`. " +
-        'Example: `--batch "click button; wait 1500; reload; wait 3000"`. `reload` preserves sessionStorage + cookies, which is how to repro sessionStorage-restored UI state.')
+        'Example: `--batch "click button; wait 1500; reload; wait 3000"`. `reload` preserves sessionStorage + cookies, which is how to repro sessionStorage-restored UI state. ' +
+        "An `eval` step keeps semicolons inside JS quotes and (), [], {}; `\\;` is always a literal semicolon.")
+        .option("--collect [preset]", "Scroll an infinite feed like a reader and collect every item that passes through the DOM, " +
+        `de-duplicated, as JSON. Presets: ${presetNames().join(", ")} (default generic). ` +
+        "Skips the trio, checks and --evaluate; runs after --wait-for and --batch.")
+        .option("--collect-item <css>", "Item selector (overrides the preset's).")
+        .option("--collect-key <extractor>", "Dedupe key extractor, <selector>[@attr] inside the item. Default: the preset key, else the " +
+        "first permalink-like link, else a hash of the item text.")
+        .option("--collect-key-pattern <regex>", "Regex a link must match to count as a permalink key.")
+        .option("--collect-field <name=extractor>", "Add or override a field: name=<selector>[@attr]. name[]= collects every match. Empty selector " +
+        "or :scope is the item itself; no @attr reads visible text (repeatable).", (value, previous = []) => [...previous, value], [])
+        .option("--collect-expand [selector]", "Click 'show more' buttons inside visible items before harvesting (preset selector by default). " +
+        "At most 3 per step and 50 per run; links and action buttons are never clicked.")
+        .option("--collect-max-items <n>", "Stop after this many unique items.")
+        .option("--collect-max-scrolls <n>", "Stop after this many scroll steps (default 60).", "60")
+        .option("--collect-max-seconds <n>", "Stop after this much wall time (default 300).", "300")
+        .option("--collect-idle <n>", "Stop after this many steps with no new items and no page growth (default 5).", "5")
+        .option("--collect-step <min-max>", "Scroll distance per step as a viewport fraction (default 0.6-1.1; env HARNERY_COLLECT_STEP).")
+        .option("--collect-pause <min-max>", "Pause after each step in ms (default 1200-3500; env HARNERY_COLLECT_PAUSE_MS).")
+        .option("--collect-read-chance <p>", "Chance of a longer reading pause per step (default 0.12).")
+        .option("--collect-read-pause <min-max>", "Reading pause in ms (default 4000-9000).")
+        .option("--collect-back-chance <p>", "Chance a step starts with a small scroll back up (default 0.08).")
+        .option("--collect-seed <n>", "Seed for the scroll schedule; the envelope reports the seed used.")
+        .option("--collect-format <format>", "json (envelope, default) or jsonl (one item per line).", "json")
+        .option("--collect-out <path>", "Write the collection to this file instead of stdout.")
         .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'. Default: real window in headed mode, desktop in headless mode")
         .option("--color-scheme <scheme>", "Emulate prefers-color-scheme for the whole session: light | dark. " +
         "Renders theme-aware pages in that scheme without page-specific toggles. " +
         "Absent = browser default (unchanged behavior).")
-        .option("--login", "Headed mode for one-time auth flow (cookies persist in profile)")
-        .option("--plain", "With --login: open the URL in the installed Google Chrome with nothing attached (no DevTools " +
-        "protocol, no Playwright) on the same persistent profile. Use it for sign-in flows whose " +
-        "verification step detects automation itself (X does). Sign in, then close the window or " +
-        "create the --login-close-file; later browse and browse-session runs reuse the profile's cookies. " +
-        "Not compatible with --control-file, because nothing is attached to drive.")
+        .option("--login", "Open the URL in the installed Google Chrome with nothing attached (no DevTools protocol, no " +
+        "Playwright) so a person can sign in; under WSL this is the Windows host's Chrome. Sign in, then " +
+        "close the window or create the --login-close-file; later browse and browse-session runs reuse " +
+        "the cookies. Sites cannot tell this window from the person's own browser.")
+        .option("--attached", "With --login: open an automation-controlled Chrome that this process and --control-file can drive. " +
+        "Sites can detect it and may lock the account, so use it only for agent-driven headed sessions on " +
+        "sites you own. Never use it to sign in to a third-party account.")
         .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("--control-file <path>", "With --login --attached, publish an owner-only descriptor for repeated browse-session control")
+        .option("--headed", "Automation-controlled headed window for one-off visual checks. Not for signing in; use --login.")
         .option("--browser-channel <name>", "Browser to launch: chrome | chrome-beta | msedge | chromium. Headed launches (--login, --headed) " +
         "default to the installed Google Chrome with the automation signals removed, because the bundled " +
         '"Chrome for Testing" build advertises itself and sign-in flows refuse clicks; chromium forces the ' +
@@ -314,7 +343,8 @@ async function runBrowse(url, opts, context) {
         : new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "harn-browse" });
     if (jar)
         applyExtraCookies(url, jar, context?.extraCookies);
-    const headed = opts.login || opts.headed;
+    const loginMode = resolveLoginMode(opts);
+    const headed = loginMode === "attached" || opts.headed;
     const viewport = parseViewport(opts.viewport ?? "desktop");
     const deviceScaleFactor = parseDeviceScaleFactor(opts.deviceScaleFactor);
     if (opts.reviewPackAllocation && !opts.reviewPack) {
@@ -340,23 +370,13 @@ async function runBrowse(url, opts, context) {
     }
     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 collectPlan = opts.collect ? buildCollectPlan(opts) : null;
     const pace = commandPaceGate(opts.pace !== false, (message) => emit.log(message, "info"));
-    if (opts.plain) {
-        if (!opts.login)
-            throw new Error("--plain requires --login.");
-        if (opts.controlFile) {
-            throw new Error("--plain cannot take --control-file: nothing is attached to drive the window.");
-        }
+    if (loginMode === "plain") {
         const plainExecutable = installedChromePath();
         const plainUa = resolveUserAgent({
             requested: opts.userAgent,
@@ -364,6 +384,10 @@ async function runBrowse(url, opts, context) {
             chromeMajor: plainExecutable ? chromeMajorFromExecutable(plainExecutable) : undefined,
         });
         await pace?.before(url);
+        if (useWindowsPlainLogin()) {
+            await runWindowsPlainLogin(url, opts.store ?? DEFAULT_STORE, loginCloseFile, emit);
+            return;
+        }
         await runPlainLogin(url, opts.profile ?? DEFAULT_PROFILE, loginCloseFile, plainUa, emit);
         return;
     }
@@ -434,6 +458,10 @@ async function runBrowse(url, opts, context) {
         if (opts.batch) {
             batchResult = await runBatch(browser, opts.batch, Number.parseInt(opts.timeout, 10));
         }
+        if (collectPlan) {
+            await runCollectMode(browser, collectPlan);
+            return;
+        }
         let evalResult;
         if (opts.evaluate) {
             evalResult = await browser.evaluate(opts.evaluate);
@@ -824,11 +852,11 @@ async function runBrowse(url, opts, context) {
             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");
+                emit.log(`[--login --attached] Automation-controlled Chrome 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");
+                emit.log("[--login --attached] Automation-controlled Chrome is open. Drive the visible window now. Press Enter here to close + persist cookies into the profile.", "info");
                 closeWaits.push(waitForTerminalEnter(lifecycleAbort.signal));
             }
             if (controlServer) {
@@ -964,6 +992,137 @@ async function runBrowse(url, opts, context) {
             process.exitCode = receivedSignal === "SIGINT" ? 130 : 143;
     }
 }
+function parsePositiveInt(raw, flag) {
+    if (!/^\d+$/.test(raw.trim()) || Number.parseInt(raw, 10) < 1) {
+        throw new Error(`${flag} must be a positive integer (got "${raw}").`);
+    }
+    return Number.parseInt(raw, 10);
+}
+function buildCollectPlan(opts) {
+    if (opts.login)
+        throw new Error("--collect cannot run with --login.");
+    if (opts.snapshot || opts.html || opts.json) {
+        throw new Error("--collect prints its own JSON; drop --snapshot, --html and --json.");
+    }
+    const presetName = typeof opts.collect === "string" ? opts.collect : "generic";
+    const spec = resolveCollectSpec(presetName, {
+        item: opts.collectItem,
+        key: opts.collectKey,
+        keyPattern: opts.collectKeyPattern,
+        fields: opts.collectField,
+        expand: opts.collectExpand,
+    });
+    const limits = {
+        ...DEFAULT_COLLECT_LIMITS,
+        maxItems: opts.collectMaxItems === undefined
+            ? null
+            : parsePositiveInt(opts.collectMaxItems, "--collect-max-items"),
+        maxScrolls: parsePositiveInt(opts.collectMaxScrolls ?? "60", "--collect-max-scrolls"),
+        maxMs: parsePositiveInt(opts.collectMaxSeconds ?? "300", "--collect-max-seconds") * 1_000,
+        idleSteps: parsePositiveInt(opts.collectIdle ?? "5", "--collect-idle"),
+        expandPerStep: spec.expand ? 3 : 0,
+    };
+    const pacing = scrollPacingFromEnv();
+    const msBounds = { min: 0, max: PACING_LIMITS.maxPauseMs };
+    if (opts.collectStep) {
+        pacing.step = parseRange(opts.collectStep, "--collect-step", {
+            min: 0.05,
+            max: PACING_LIMITS.maxStepFraction,
+        });
+    }
+    if (opts.collectPause)
+        pacing.pauseMs = parseRange(opts.collectPause, "--collect-pause", msBounds);
+    if (opts.collectReadPause) {
+        pacing.readPauseMs = parseRange(opts.collectReadPause, "--collect-read-pause", msBounds);
+    }
+    if (opts.collectReadChance !== undefined) {
+        pacing.readChance = parseProbability(opts.collectReadChance, "--collect-read-chance");
+    }
+    if (opts.collectBackChance !== undefined) {
+        pacing.backChance = parseProbability(opts.collectBackChance, "--collect-back-chance");
+    }
+    let seed = randomSeed();
+    if (opts.collectSeed !== undefined) {
+        if (!/^\d+$/.test(opts.collectSeed.trim())) {
+            throw new Error(`--collect-seed must be a non-negative integer (got "${opts.collectSeed}").`);
+        }
+        seed = Number(BigInt(opts.collectSeed.trim()) % 4294967296n);
+    }
+    const format = opts.collectFormat ?? "json";
+    if (format !== "json" && format !== "jsonl") {
+        throw new Error(`--collect-format must be json or jsonl (got "${format}").`);
+    }
+    return {
+        spec,
+        limits,
+        pacing,
+        seed,
+        format,
+        out: opts.collectOut ? resolve(opts.collectOut) : null,
+    };
+}
+async function runCollectMode(browser, plan) {
+    const page = browser.currentPage;
+    const rng = createRng(plan.seed);
+    let interrupted = false;
+    const onSignal = () => {
+        interrupted = true;
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    let result;
+    try {
+        emit.log(`collect: preset ${plan.spec.preset}, item ${plan.spec.item}, seed ${plan.seed}`, "info");
+        const driver = createPageDriver(page, plan.spec, {
+            rng,
+            log: (message) => emit.log(message, "warn"),
+        });
+        result = await runCollect(driver, {
+            limits: plan.limits,
+            pacing: plan.pacing,
+            rng,
+            shouldStop: () => interrupted,
+            onStep: ({ step, items, added }) => emit.log(`collect: step ${step}, ${items} items (+${added})`, "debug"),
+        });
+    }
+    finally {
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+    }
+    const { items, stats } = result;
+    emit.log(`collect: ${items.length} items in ${stats.steps} steps, stopped on ${stats.stopReason}` +
+        (stats.stopDetail ? ` (${stats.stopDetail})` : ""), "info");
+    const envelope = {
+        url: page.url(),
+        preset: plan.spec.preset,
+        itemSelector: plan.spec.item,
+        seed: plan.seed,
+        stopReason: stats.stopReason,
+        stats,
+        items,
+    };
+    if (plan.format === "jsonl") {
+        const body = items.map((item) => JSON.stringify(item)).join("\n");
+        if (plan.out) {
+            mkdirSync(dirname(plan.out), { recursive: true });
+            writeFileSync(plan.out, body ? `${body}\n` : "");
+            emit.file(plan.out, { items: items.length, stopReason: stats.stopReason, stats });
+        }
+        else if (body) {
+            process.stdout.write(`${body}\n`);
+        }
+    }
+    else if (plan.out) {
+        mkdirSync(dirname(plan.out), { recursive: true });
+        writeFileSync(plan.out, `${JSON.stringify(envelope, null, 2)}\n`);
+        emit.file(plan.out, { items: items.length, stopReason: stats.stopReason, stats });
+    }
+    else {
+        emit.data(envelope);
+    }
+    if (interrupted)
+        process.exitCode = 130;
+}
 async function runBatch(browser, batch, defaultTimeoutMs) {
     const result = { clipboardReads: [] };
     const steps = splitBatchSteps(batch);
@@ -1034,27 +1193,6 @@ async function runBatch(browser, batch, defaultTimeoutMs) {
     }
     return result;
 }
-function splitBatchSteps(input) {
-    const steps = [];
-    let buf = "";
-    for (let i = 0; i < input.length; i++) {
-        const ch = input[i];
-        if (ch === "\\" && input[i + 1] === ";") {
-            buf += ";";
-            i++;
-            continue;
-        }
-        if (ch === ";") {
-            steps.push(buf);
-            buf = "";
-            continue;
-        }
-        buf += ch;
-    }
-    if (buf.trim())
-        steps.push(buf);
-    return steps;
-}
 // ---------------------------------------------------------------------------
 // Print mode (--snapshot / --html / --json): stdout, no file writes
 // ---------------------------------------------------------------------------
@@ -2155,7 +2293,26 @@ async function verifyBrowserProxyGate(browser, gate) {
     emit.log(`browser proxy gate: ${observedIp} · expected IP confirmed`, "info");
 }
 /**
- * `--login --plain`: spawn the installed Google Chrome directly on the shared
+ * How a `browse` run handles sign-in. `--login` opens the installed Google
+ * Chrome with nothing attached, because sites can detect an
+ * automation-controlled browser and disable the account that signed in with
+ * it. The attached window is reachable only through an explicit `--attached`.
+ */
+export function resolveLoginMode(opts) {
+    if (opts.attached && !opts.login)
+        throw new Error("--attached requires --login.");
+    if (opts.loginCloseFile && !opts.login)
+        throw new Error("--login-close-file requires --login.");
+    if (opts.controlFile && !(opts.login && opts.attached)) {
+        throw new Error("--control-file requires --login --attached. A sign-in to a third-party account uses plain " +
+            "--login, which nothing can drive.");
+    }
+    if (!opts.login)
+        return "none";
+    return opts.attached ? "attached" : "plain";
+}
+/**
+ * `--login`: spawn the installed Google Chrome directly on the shared
  * persistent profile, with no DevTools protocol attached. Playwright enables
  * its runtime hooks in every frame it drives, and sign-in verification vendors
  * (X's is the reported case) detect that and fail the flow with no explanation.
@@ -2166,7 +2323,8 @@ async function verifyBrowserProxyGate(browser, gate) {
 async function runPlainLogin(url, profileDir, loginCloseFile, userAgent, emit) {
     const executable = installedChromePath();
     if (!executable) {
-        throw new Error("--plain needs an installed Google Chrome at a standard path; none was found on this machine.");
+        throw new Error("--login needs an installed Google Chrome at a standard path; none was found on this machine. " +
+            "Install Google Chrome; do not fall back to --attached for a third-party sign-in.");
     }
     mkdirSync(profileDir, { recursive: true });
     const child = spawn(executable, [
@@ -2183,11 +2341,11 @@ async function runPlainLogin(url, profileDir, loginCloseFile, userAgent, emit) {
     const lifecycleAbort = new AbortController();
     const waits = [exited];
     if (loginCloseFile) {
-        emit.log(`[--login --plain] Plain Google Chrome is open with nothing attached. Sign in, then close the window or create ${loginCloseFile}.`, "info");
+        emit.log(`[--login] Plain Google Chrome is open with nothing attached. Sign in, then close the window or create ${loginCloseFile}.`, "info");
         waits.push(waitForLoginCloseFile(loginCloseFile, lifecycleAbort.signal));
     }
     else {
-        emit.log("[--login --plain] Plain Google Chrome is open with nothing attached. Sign in, then close the window or press Enter here.", "info");
+        emit.log("[--login] Plain Google Chrome is open with nothing attached. Sign in, then close the window or press Enter here.", "info");
         waits.push(waitForTerminalEnter(lifecycleAbort.signal));
     }
     await Promise.race(waits);
@@ -2196,7 +2354,61 @@ async function runPlainLogin(url, profileDir, loginCloseFile, userAgent, emit) {
         child.kill("SIGTERM");
         await Promise.race([exited, new Promise((r) => setTimeout(r, 5000))]);
     }
-    emit.log(`[--login --plain] Chrome closed; cookies persisted in ${profileDir}.`, "info");
+    emit.log(`[--login] Chrome closed; cookies persisted in ${profileDir}.`, "info");
+}
+/**
+ * Under WSL, `--login` opens the Windows host's Google Chrome when one
+ * is installed. Some sign-in flows reject every browser running inside WSL,
+ * even a plain Linux Chrome, while the Windows desktop Chrome signs in
+ * normally. `HARNERY_BROWSER_WSL_PLAIN=linux` keeps the Linux Chrome.
+ */
+function useWindowsPlainLogin() {
+    if (!isWSL())
+        return false;
+    if ((process.env.HARNERY_BROWSER_WSL_PLAIN ?? "").toLowerCase() === "linux")
+        return false;
+    return windowsChromePath() !== undefined;
+}
+/**
+ * The WSL form of `--login`: the person signs in through the Windows
+ * Chrome on a dedicated Windows profile with nothing attached. When the window
+ * closes, the profile's cookies for the sign-in site are read and merged into
+ * the shared cookie store, which later `browse` runs attach.
+ */
+async function runWindowsPlainLogin(url, storePath, loginCloseFile, emit) {
+    const chromeLinux = windowsChromePath();
+    const localAppData = windowsLocalAppData();
+    if (!chromeLinux || !localAppData) {
+        throw new Error("--login under WSL needs the Windows Google Chrome and %LOCALAPPDATA%; neither was readable.");
+    }
+    const chromeWindows = wslPathToWindows(chromeLinux);
+    const profileWindows = windowsPlainProfile(localAppData);
+    const child = spawn(chromeLinux, [`--user-data-dir=${profileWindows}`, "--no-first-run", "--no-default-browser-check", url], { stdio: "ignore" });
+    const exited = new Promise((resolveExit) => {
+        child.once("exit", () => resolveExit());
+        child.once("error", () => resolveExit());
+    });
+    const lifecycleAbort = new AbortController();
+    const waits = [exited];
+    const how = loginCloseFile ? `create ${loginCloseFile}` : "press Enter here";
+    emit.log(`[--login] Windows Google Chrome is open with nothing attached (profile ${profileWindows}). Sign in, then close the window or ${how}.`, "info");
+    waits.push(loginCloseFile
+        ? waitForLoginCloseFile(loginCloseFile, lifecycleAbort.signal)
+        : waitForTerminalEnter(lifecycleAbort.signal));
+    await Promise.race(waits);
+    lifecycleAbort.abort();
+    stopWindowsChromeProfile(profileWindows);
+    await Promise.race([exited, new Promise((r) => setTimeout(r, 5000))]);
+    const domain = harvestDomain(url);
+    const cookies = harvestWindowsChromeCookies({ chromeWindows, profileWindows, domain });
+    if (cookies.length === 0) {
+        emit.log(`[--login] No ${domain} cookies were found in the Windows profile; the sign-in may not have completed.`, "warn");
+        return;
+    }
+    const jar = new CookieJar({ path: storePath, source: "harn-browse" });
+    jar.save(mergeCookies(jar.load(), cookies));
+    const names = [...new Set(cookies.map((cookie) => cookie.name))].sort().join(", ");
+    emit.log(`[--login] Copied ${cookies.length} ${domain} cookies into ${storePath}: ${names}.`, "info");
 }
 async function waitForLoginCloseFile(path, signal) {
     while (!existsSync(path) && !signal?.aborted) {

package/dist/commands/claude-desktop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-desktop.d.ts","sourceRoot":"","sources":["../../src/commands/claude-desktop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAU1E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,IAAI,CA8JN"}
+{"version":3,"file":"claude-desktop.d.ts","sourceRoot":"","sources":["../../src/commands/claude-desktop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiB1E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,IAAI,CAoNN"}

package/dist/commands/claude-desktop.js

@@ -1,4 +1,6 @@
 import { applyMirror, findDesktopDataDirs, listAccounts, planMirror, readCliAccount, } from "../lib/claude-desktop.js";
+import { applyShare, defaultShareDir, planShare, shareSummary, } from "../lib/claude-desktop-share.js";
+import { resolveMachineLabel } from "../lib/machine.js";
 /**
  * `claude-desktop`: make Claude desktop-app sessions survive account
  * switches.
@@ -141,6 +143,56 @@ export function registerClaudeDesktopCommand(program, emit, _context) {
             });
         }
     });
+    cmd
+        .command("share")
+        .description("Share sessions with your other computers through a synced folder (iCloud Drive by default): " +
+        "publish this machine's recent sessions and list + resume every other machine's here. " +
+        "Dry-run by default; --yes applies. Restart the desktop app afterward to see new entries.")
+        .option("--dir <path>", "Shared folder (default: iCloud Drive/Harnery/claude-sessions)")
+        .option("--days <n>", "Only sessions active in the last N days", "14")
+        .option("--data-dir <path>", "Explicit desktop-app data directory")
+        .option("--yes", "Apply the plan (default is dry-run)")
+        .action((opts) => {
+        const shareDir = opts.dir ?? process.env.HARNERY_SESSION_SHARE_DIR ?? defaultShareDir();
+        if (!shareDir) {
+            emit.error({
+                code: "no_share_dir",
+                message: "no shared folder: pass --dir <path> or set HARNERY_SESSION_SHARE_DIR",
+            });
+            process.exit(2);
+        }
+        const cli = readCliAccount();
+        if (!cli) {
+            emit.error({
+                code: "no_account",
+                message: "cannot read the signed-in account from ~/.claude.json",
+            });
+            process.exit(2);
+        }
+        const [dataDir] = requireDataDirs(emit, opts.dataDir);
+        const shareOpts = {
+            shareDir,
+            machine: resolveMachineLabel(),
+            days: Number(opts.days) || 14,
+            dataDir: dataDir,
+            targetAccountUuid: cli.accountUuid,
+        };
+        const plan = planShare(shareOpts);
+        const summary = { share_dir: shareDir, machine: shareOpts.machine, ...shareSummary(plan) };
+        if (!opts.yes) {
+            emit.data({ dry_run: true, ...summary, hint: "re-run with --yes to apply" });
+            return;
+        }
+        const result = applyShare(plan, shareOpts);
+        emit.data({
+            dry_run: false,
+            ...summary,
+            ...result,
+            hint: result.imported > 0
+                ? "quit the Claude desktop app fully (Cmd+Q) and reopen it to see the new sessions"
+                : "sidebar already current",
+        });
+    });
 }
 function collect(value, previous) {
     return previous.concat([value]);

package/dist/commands/disk.d.ts

@@ -0,0 +1,6 @@
+import { type Command } from "commander";
+import type { EmitContext } from "../commander.js";
+import { type DiskReport } from "../lib/disk-usage.js";
+export declare function registerDiskCommand(program: Command, emit: EmitContext): void;
+export declare function renderDiskUsage(report: DiskReport): string;
+//# sourceMappingURL=disk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disk.d.ts","sourceRoot":"","sources":["../../src/commands/disk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAwB,MAAM,WAAW,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAGL,KAAK,UAAU,EAGhB,MAAM,sBAAsB,CAAC;AAQ9B,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA+C7E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAgD1D"}

package/dist/commands/disk.js

@@ -0,0 +1,80 @@
+import { InvalidArgumentError } from "commander";
+import { diskUsage, parseDiskSize, } from "../lib/disk-usage.js";
+function positive(value) {
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < 1)
+        throw new InvalidArgumentError("requires a positive integer");
+    return Number(value);
+}
+export function registerDiskCommand(program, emit) {
+    program
+        .command("disk [path]")
+        .description("Measure checkout disk usage, including nested repositories and ignored files")
+        .option("--git <states>", "Filter: tracked, untracked, ignored, git-metadata, non-repository, unknown (comma-separated)")
+        .option("--type <types>", "File extensions or video, audio, image, media, archive (comma-separated)")
+        .option("--exclude <paths>", "Skip directory names at any depth or root-relative paths; repeatable, comma-separated", (value, previous) => [...previous, value], [])
+        .option("--group <by>", "Group by directory, repository, extension, git, or files", "directory")
+        .option("--depth <n>", "Directory grouping depth; does not limit the scan", positive, 1)
+        .option("--top <n>", "Maximum groups and largest files to display", positive, 20)
+        .option("--min-size <size>", "Include individual files at least this size (e.g. 10MB, 1GiB)", parseDiskSize)
+        .option("--apparent", "Rank and filter by file lengths instead of allocated blocks")
+        .option("--json", "Emit the versioned disk usage report")
+        .action((path, options) => {
+        try {
+            const { json, ...filters } = options;
+            const report = diskUsage(path, filters);
+            if (json) {
+                emit.config({ format: "json" });
+                emit.data(report);
+            }
+            else
+                emit.text(renderDiskUsage(report));
+            if (!report.complete)
+                emit.setExitCode(1);
+        }
+        catch (error) {
+            emit.error({
+                code: "disk_usage_failed",
+                message: error instanceof Error ? error.message : String(error),
+            });
+            emit.setExitCode(1);
+        }
+    });
+}
+export function renderDiskUsage(report) {
+    const bytes = (value) => value >= 1e9
+        ? `${(value / 1e9).toFixed(2)} GB`
+        : value >= 1e6
+            ? `${(value / 1e6).toFixed(2)} MB`
+            : value >= 1e3
+                ? `${(value / 1e3).toFixed(2)} KB`
+                : `${value} B`;
+    const size = (row) => bytes(report.measurement === "allocated"
+        ? (row.allocated_bytes ?? row.apparent_bytes)
+        : row.apparent_bytes);
+    const lines = [
+        `Disk usage: ${report.root}`,
+        `${size(report.totals)} in ${report.totals.files.toLocaleString()} regular files (${report.measurement})`,
+        `File lengths: ${bytes(report.totals.apparent_bytes)}. Directory metadata and symlinks are excluded.`,
+        "",
+        "Git state:",
+    ];
+    for (const [state, totals] of Object.entries(report.git))
+        if (totals.files)
+            lines.push(`${size(totals).padStart(12)}  ${String(totals.files).padStart(8)} files  ${state}`);
+    lines.push("", `Largest ${report.filters.group} groups (${report.groups.length} of ${report.group_count}):`);
+    for (const row of report.groups)
+        lines.push(`${size(row).padStart(12)}  ${String(row.files).padStart(8)} files  ${row.path}`);
+    if (report.filters.group !== "files") {
+        lines.push("", "Largest files:");
+        for (const row of report.largest_files)
+            lines.push(`${size(row).padStart(12)}  ${row.git.padEnd(14)}  ${row.path}`);
+    }
+    if (report.skipped.symlinks || report.skipped.special_files || report.skipped.excluded)
+        lines.push("", `Skipped: ${report.skipped.symlinks} symlinks, ${report.skipped.special_files} special files, ${report.skipped.excluded} excluded entries.`);
+    if (report.issues.length) {
+        lines.push("", "Incomplete scan:");
+        for (const issue of report.issues)
+            lines.push(`${issue.path}: ${issue.message}`);
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/commands/doctor.d.ts

@@ -24,6 +24,14 @@ export interface Check {
 export declare function registerDoctorCommand(program: Command, emit: EmitContext): void;
 export declare function runChecks(): Promise<Check[]>;
 export declare function codexWslBridgeCheck(status: CodexWslBridgeStatus | null, recentMidFlightCount?: number): Check | null;
+/**
+ * Hook runs that started but never finished (ADR 0197). Codex kills a hook at
+ * its timeout and the tool proceeds without that hook's checks; the start
+ * marker is the only trace such a run leaves.
+ */
+export declare function codexHookRunsCheck(coordRoot: string | null, nowMs?: number, isAlive?: (pid: number) => boolean): Check | null;
+/** Report the per-project Windows bridge opt-in, or an invalid value init ignored. */
+export declare function codexWindowsBridgeCheck(coordRoot: string | null): Check | null;
 /** Count bounded, privacy-safe recovery diagnostics so a healthy environment
  * now does not hide an intermittent Codex-to-WSL identity drop. */
 export declare function countRecentCodexMidFlightOnboardings(coordRoot: string, nowMs?: number, windowMs?: number): number;

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;AASnD,OAAO,EACL,KAAK,4BAA4B,EAElC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,mCAAmC,CAAC;AAW3C,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,MAAM,WAAW,KAAK;IACpB,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,wBAAsB,SAAS,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CA2BlD;AAgCD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,oBAAoB,GAAG,IAAI,EACnC,oBAAoB,SAAI,GACvB,KAAK,GAAG,IAAI,CAed;AAID;mEACmE;AACnE,wBAAgB,oCAAoC,CAClD,SAAS,EAAE,MAAM,EACjB,KAAK,SAAa,EAClB,QAAQ,SAAqC,GAC5C,MAAM,CA0CR;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,GAAG,KAAK,CAoBnF"}
+{"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;AASnD,OAAO,EACL,KAAK,4BAA4B,EAElC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,mCAAmC,CAAC;AAY3C,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,MAAM,WAAW,KAAK;IACpB,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,wBAAsB,SAAS,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CA+BlD;AAgCD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,oBAAoB,GAAG,IAAI,EACnC,oBAAoB,SAAI,GACvB,KAAK,GAAG,IAAI,CAed;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,KAAK,SAAa,EAClB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GACjC,KAAK,GAAG,IAAI,CAad;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,CAmB9E;AAID;mEACmE;AACnE,wBAAgB,oCAAoC,CAClD,SAAS,EAAE,MAAM,EACjB,KAAK,SAAa,EAClB,QAAQ,SAAqC,GAC5C,MAAM,CA0CR;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,GAAG,KAAK,CAoBnF"}