harnery 0.41.0 → 0.42.0

package/src/commands/browse.ts

@@ -7,6 +7,7 @@ import { chromium } from "playwright";
 import { PNG } from "pngjs";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { resolveBinName } from "../core/config.ts";
+import { splitBatchSteps } from "../lib/browser/batch-steps.ts";
 import {
   CAPTURE_FIDELITY_MISMATCH_THRESHOLD,
   compareBand,
@@ -15,6 +16,22 @@ import {
   type FidelityProbe,
   pngDimensions,
 } from "../lib/browser/capture-fidelity.ts";
+import {
+  type CollectLimits,
+  createPageDriver,
+  createRng,
+  DEFAULT_COLLECT_LIMITS,
+  PACING_LIMITS,
+  parseProbability,
+  parseRange,
+  presetNames,
+  type ResolvedCollectSpec,
+  randomSeed,
+  resolveCollectSpec,
+  runCollect,
+  type ScrollPacing,
+  scrollPacingFromEnv,
+} from "../lib/browser/collect/index.ts";
 import {
   type AssertResult,
   Browser,
@@ -50,6 +67,7 @@ import {
   writeNetscapeCookieFile,
   wslHeadedLaunchArgs,
 } from "../lib/browser/index.ts";
+import { isWSL } from "../lib/browser/launch-args.ts";
 import {
   allocateTileBudget,
   validatePageReviewAllocation,
@@ -113,7 +131,16 @@ import {
   type SaveBaselineResult,
   saveBaseline,
 } from "../lib/browser/visual-diff.ts";
-import { applyExtraCookies, CookieJar } from "../lib/cookies/index.ts";
+import {
+  harvestDomain,
+  harvestWindowsChromeCookies,
+  stopWindowsChromeProfile,
+  windowsChromePath,
+  windowsLocalAppData,
+  windowsPlainProfile,
+  wslPathToWindows,
+} from "../lib/browser/windows-chrome.ts";
+import { applyExtraCookies, CookieJar, mergeCookies } from "../lib/cookies/index.ts";
 import { commandPaceGate } from "../lib/pace/index.ts";
 
 /**
@@ -167,9 +194,28 @@ interface BrowseOpts {
   evaluate?: string;
   captureEvaluate?: string;
   batch?: string;
+  // Scroll-and-collect mode (--collect [preset])
+  collect?: string | boolean;
+  collectItem?: string;
+  collectKey?: string;
+  collectKeyPattern?: string;
+  collectField?: string[];
+  collectExpand?: string | boolean;
+  collectMaxItems?: string;
+  collectMaxScrolls?: string;
+  collectMaxSeconds?: string;
+  collectIdle?: string;
+  collectStep?: string;
+  collectPause?: string;
+  collectReadChance?: string;
+  collectReadPause?: string;
+  collectBackChance?: string;
+  collectSeed?: string;
+  collectFormat?: string;
+  collectOut?: string;
   networkHar?: string;
   login?: boolean;
-  plain?: boolean;
+  attached?: boolean;
   loginCloseFile?: string;
   controlFile?: string;
   headed?: boolean;
@@ -345,8 +391,69 @@ export function registerBrowseCommand(
       "--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: string, previous: string[] = []) => [...previous, value],
+      [] as string[],
+    )
+    .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>",
@@ -358,14 +465,18 @@ export function registerBrowseCommand(
         "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.",
+      "--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>",
@@ -373,9 +484,12 @@ export function registerBrowseCommand(
     )
     .option(
       "--control-file <path>",
-      "With --login, publish an owner-only descriptor for repeated browse-session control",
+      "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("--headed", "Headed mode for one-off (no auth-flow framing)")
     .option(
       "--browser-channel <name>",
       "Browser to launch: chrome | chrome-beta | msedge | chromium. Headed launches (--login, --headed) " +
@@ -893,7 +1007,8 @@ async function runBrowse(
       ? null
       : 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) {
@@ -925,12 +1040,6 @@ async function runBrowse(
   }
   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(
@@ -938,14 +1047,10 @@ async function runBrowse(
     );
   }
 
+  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,
@@ -953,6 +1058,10 @@ async function runBrowse(
       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;
   }
@@ -1030,6 +1139,11 @@ async function runBrowse(
       batchResult = await runBatch(browser, opts.batch, Number.parseInt(opts.timeout, 10));
     }
 
+    if (collectPlan) {
+      await runCollectMode(browser, collectPlan);
+      return;
+    }
+
     let evalResult: unknown;
     if (opts.evaluate) {
       evalResult = await browser.evaluate<unknown>(opts.evaluate);
@@ -1484,13 +1598,13 @@ async function runBrowse(
       const closeWaits: Promise<void>[] = [];
       if (loginCloseFile) {
         emit.log(
-          `[--login] Headed Chromium is open. Drive the visible window now. Create ${loginCloseFile} to close cleanly.`,
+          `[--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.",
+          "[--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));
@@ -1687,9 +1801,161 @@ async function runBrowse(
 }
 
 // ---------------------------------------------------------------------------
-// Batch mode parser. Each step is `<verb> <args>`; verbs are click, fill,
-// press, wait, eval. Steps are separated by `;` (escape with `\;` if a value
-// genuinely contains a semicolon, rare for the supported verbs).
+// Scroll-and-collect mode (--collect). Extends browse rather than adding a
+// sibling command so it reuses the exact session path: persistent profile,
+// cookie jar, browser channel, user agent, proxy, page-load pace gate,
+// --wait-for and --batch setup steps.
+// ---------------------------------------------------------------------------
+
+interface CollectPlan {
+  spec: ResolvedCollectSpec;
+  limits: CollectLimits;
+  pacing: ScrollPacing;
+  seed: number;
+  format: "json" | "jsonl";
+  out: string | null;
+}
+
+function parsePositiveInt(raw: string, flag: string): number {
+  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: BrowseOpts): CollectPlan {
+  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: CollectLimits = {
+    ...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: Browser, plan: CollectPlan): Promise<void> {
+  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: Awaited<ReturnType<typeof runCollect>>;
+  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;
+}
+
+// ---------------------------------------------------------------------------
+// Batch mode runner. Each step is `<verb> <args>`; see splitBatchSteps for
+// the separator rule (eval steps keep semicolons inside JS quotes and
+// brackets; `\;` is always a literal semicolon).
 // ---------------------------------------------------------------------------
 
 interface BatchResult {
@@ -1769,27 +2035,6 @@ async function runBatch(
   return result;
 }
 
-function splitBatchSteps(input: string): string[] {
-  const steps: string[] = [];
-  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
 // ---------------------------------------------------------------------------
@@ -3123,7 +3368,28 @@ async function verifyBrowserProxyGate(
 }
 
 /**
- * `--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: Pick<BrowseOpts, "login" | "attached" | "controlFile" | "loginCloseFile">,
+): "none" | "plain" | "attached" {
+  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.
@@ -3141,7 +3407,8 @@ async function runPlainLogin(
   const executable = installedChromePath();
   if (!executable) {
     throw new Error(
-      "--plain needs an installed Google Chrome at a standard path; none was found on this machine.",
+      "--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 });
@@ -3164,13 +3431,13 @@ async function runPlainLogin(
   const waits: Promise<void>[] = [exited];
   if (loginCloseFile) {
     emit.log(
-      `[--login --plain] Plain Google Chrome is open with nothing attached. Sign in, then close the window or create ${loginCloseFile}.`,
+      `[--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.",
+      "[--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));
@@ -3181,7 +3448,83 @@ async function runPlainLogin(
     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(): boolean {
+  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: string,
+  storePath: string,
+  loginCloseFile: string | null,
+  emit: { log: (message: string, level: "info" | "warn" | "error" | "debug") => void },
+): Promise<void> {
+  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<void>((resolveExit) => {
+    child.once("exit", () => resolveExit());
+    child.once("error", () => resolveExit());
+  });
+  const lifecycleAbort = new AbortController();
+  const waits: Promise<void>[] = [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: string, signal?: AbortSignal): Promise<void> {

package/src/commands/claude-desktop.ts

@@ -8,6 +8,13 @@ import {
   planMirror,
   readCliAccount,
 } from "../lib/claude-desktop.ts";
+import {
+  applyShare,
+  defaultShareDir,
+  planShare,
+  shareSummary,
+} from "../lib/claude-desktop-share.ts";
+import { resolveMachineLabel } from "../lib/machine.ts";
 
 /**
  * `claude-desktop`: make Claude desktop-app sessions survive account
@@ -186,6 +193,60 @@ export function registerClaudeDesktopCommand(
         }
       },
     );
+
+  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: { dir?: string; days: string; dataDir?: string; yes?: boolean }) => {
+      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 as string,
+        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: string, previous: string[]): string[] {