chainlesschain 0.162.178 → 0.162.180

package/src/commands/hub.js

@@ -60,6 +60,8 @@ function parsePositiveInt(raw) {
 
 const SYNC_ENTITY_KEYS = ["events", "persons", "places", "items", "topics"];
 const MAX_SYNC_COOKIE_BYTES = 64 * 1024;
+const MAX_SYNC_ACCESS_TOKEN_BYTES = 16 * 1024;
+const MAX_SYNC_APP_KEY_BYTES = 16 * 1024;
 
 function resolveSyncCookie(options = {}, env = process.env) {
   if (options.cookie && options.cookieFile) {
@@ -80,6 +82,113 @@ function resolveSyncCookie(options = {}, env = process.env) {
   return normalized || null;
 }
 
+function resolveSyncAccessToken(options = {}, env = process.env) {
+  if (options.accessToken && options.accessTokenFile) {
+    throw new Error(
+      "Use either --access-token or --access-token-file, not both",
+    );
+  }
+  let raw = options.accessToken || env.CC_PDH_ACCESS_TOKEN || null;
+  if (options.accessTokenFile) {
+    raw = readFileSync(String(options.accessTokenFile), "utf8");
+    if (Buffer.byteLength(raw, "utf8") > MAX_SYNC_ACCESS_TOKEN_BYTES) {
+      throw new Error(
+        `Access token file exceeds ${MAX_SYNC_ACCESS_TOKEN_BYTES} bytes`,
+      );
+    }
+  }
+  if (raw == null) return null;
+  const normalized = String(raw).trim();
+  if (Buffer.byteLength(normalized, "utf8") > MAX_SYNC_ACCESS_TOKEN_BYTES) {
+    throw new Error(
+      `Access token exceeds ${MAX_SYNC_ACCESS_TOKEN_BYTES} bytes`,
+    );
+  }
+  return normalized || null;
+}
+
+function resolveSyncAppKey(options = {}, env = process.env) {
+  if (options.appKey && options.appKeyFile) {
+    throw new Error("Use either --app-key or --app-key-file, not both");
+  }
+  let raw = options.appKey || env.CC_PDH_APP_KEY || null;
+  if (options.appKeyFile) {
+    raw = readFileSync(String(options.appKeyFile), "utf8");
+    if (Buffer.byteLength(raw, "utf8") > MAX_SYNC_APP_KEY_BYTES) {
+      throw new Error(`App key file exceeds ${MAX_SYNC_APP_KEY_BYTES} bytes`);
+    }
+  }
+  if (raw == null) return null;
+  const normalized = String(raw).trim();
+  if (Buffer.byteLength(normalized, "utf8") > MAX_SYNC_APP_KEY_BYTES) {
+    throw new Error(`App key exceeds ${MAX_SYNC_APP_KEY_BYTES} bytes`);
+  }
+  return normalized || null;
+}
+
+function collectSyncRoot(value, previous = []) {
+  const roots = Array.isArray(previous) ? previous : [];
+  return [...roots, String(value)];
+}
+
+/**
+ * Resolve local-files scan roots without interpreting path characters.
+ *
+ * `--root` is repeatable and preserves each argument byte-for-byte after the
+ * shell/Commander handoff. The deprecated `--roots` spelling remains safe for
+ * one exact path, but comma-containing values are inherently ambiguous (a
+ * legal filename versus the former comma-separated syntax), so they fail
+ * closed instead of scanning unintended directories.
+ */
+function resolveSyncRoots(options = {}) {
+  const roots = Array.isArray(options.root)
+    ? options.root.map((value) => String(value))
+    : options.root == null
+      ? []
+      : [String(options.root)];
+
+  if (options.roots != null) {
+    const legacyRoot = String(options.roots);
+    if (legacyRoot.includes(",")) {
+      throw new Error(
+        "--roots no longer accepts ambiguous comma-separated values; repeat --root <path> for each exact directory",
+      );
+    }
+    roots.push(legacyRoot);
+  }
+
+  if (roots.some((root) => root.length === 0)) {
+    throw new Error("--root requires a non-empty exact directory path");
+  }
+  return roots;
+}
+
+function applySyncSinceOverride(registry, name, options = {}) {
+  if (!Object.prototype.hasOwnProperty.call(options, "since")) return options;
+  const adapter =
+    registry && typeof registry.get === "function" ? registry.get(name) : null;
+  if (adapter?.watermarkStrategy !== "partitioned") {
+    options.sinceWatermark = options.since;
+    return options;
+  }
+
+  const targetKeys =
+    typeof adapter.targetWatermarkKeys === "function"
+      ? adapter.targetWatermarkKeys(options)
+      : adapter.watermarkStreams;
+  const keys = Array.isArray(targetKeys)
+    ? targetKeys.filter(
+        (key) => typeof key === "string" && key.trim().length > 0,
+      )
+    : [];
+  if (keys.length > 0) {
+    options.sinceWatermarks = Object.fromEntries(
+      keys.map((key) => [key, options.since]),
+    );
+  }
+  return options;
+}
+
 function syncCount(value) {
   return Number.isFinite(value) && value > 0 ? value : 0;
 }
@@ -756,7 +865,10 @@ async function cmdSyncAdapter(name, options) {
   try {
     const hub = await (options._getHub || getHub)();
     const opts = {};
-    if (options.since) opts.since = Number(options.since);
+    if (options.since) {
+      const sinceWatermark = Number(options.since);
+      opts.since = sinceWatermark;
+    }
     if (options.until) opts.until = Number(options.until);
     if (options.limit) opts.limit = Number(options.limit);
     // Plan A v0.1 — system-data-android needs a snapshot file path. Generic
@@ -779,23 +891,77 @@ async function cmdSyncAdapter(name, options) {
     // history and process listings. The value remains transient.
     const runtimeCookie = resolveSyncCookie(options);
     if (runtimeCookie) opts.cookie = runtimeCookie;
-    // Constructor-optional cookie collectors use a transient account identity
-    // to isolate watermarks without persisting the cookie or account id.
+    // Official OAuth collectors receive their token only for this invocation.
+    // File/env input is preferred so the secret stays out of shell history.
+    const runtimeAccessToken = resolveSyncAccessToken(options);
+    if (runtimeAccessToken) opts.accessToken = runtimeAccessToken;
+    const runtimeAppKey = resolveSyncAppKey(options);
+    if (runtimeAppKey) opts.appKey = runtimeAppKey;
+    const runtimeAppId = options.appId || process.env.CC_PDH_APP_ID;
+    if (runtimeAppId) opts.appId = String(runtimeAppId);
+    // Constructor-optional credential collectors use a transient account
+    // identity to isolate watermarks without persisting credentials or ids.
     const runtimeAccountId = options.accountId || process.env.CC_PDH_ACCOUNT_ID;
     if (runtimeAccountId) opts.accountId = String(runtimeAccountId);
+    const runtimeSourceUrl = options.sourceUrl || process.env.CC_PDH_SOURCE_URL;
+    if (runtimeSourceUrl) opts.sourceUrl = String(runtimeSourceUrl);
+    const runtimeDriveId = options.driveId || process.env.CC_PDH_DRIVE_ID;
+    if (runtimeDriveId) opts.driveId = String(runtimeDriveId);
+    if (options.parentId) opts.parentId = String(options.parentId);
+    if (options.shallow) opts.recursive = false;
+    if (options.dir) opts.dir = String(options.dir);
+    if (options.exportDir) opts.exportDir = String(options.exportDir);
+    if (options.profilePath) opts.profilePath = String(options.profilePath);
+    if (options.cursorHome) opts.cursorHome = String(options.cursorHome);
+    if (options.claudeHome) opts.claudeHome = String(options.claudeHome);
+    if (options.hbuilderxHome) {
+      opts.hbuilderxHome = String(options.hbuilderxHome);
+    }
+    if (options.sourceTimezone) {
+      opts.sourceTimezone = String(options.sourceTimezone);
+    }
+    if (options.sourceTimezoneOffsetMinutes != null) {
+      opts.sourceTimezoneOffsetMinutes = Number(
+        options.sourceTimezoneOffsetMinutes,
+      );
+    }
+    const include = {};
+    if (options.history === false) include.history = false;
+    if (options.bookmarks === false) include.bookmarks = false;
+    if (options.downloads === false) include.downloads = false;
+    if (options.localHistory === false) include.localHistory = false;
+    if (options.agentTranscripts === false) include.agentTranscripts = false;
+    if (options.aiTracking === false) include.aiTracking = false;
+    if (options.claudeSubagents === false) {
+      include.subagentTranscripts = false;
+    }
+    if (options.claudeStats === false) include.stats = false;
+    if (options.participants === false) include.participants = false;
+    if (options.artifacts === false) include.artifacts = false;
+    if (options.contacts === false) include.contacts = false;
+    if (options.apps === false) include.apps = false;
+    if (options.sms === false) include.sms = false;
+    if (options.calls === false) include.calls = false;
+    if (options.media === false) include.media = false;
+    if (Object.keys(include).length > 0) opts.include = include;
+    // Keep the legacy field while every shell converges on dataDisclosure's
+    // standard include map.
+    if (options.participants === false) opts.includeParticipants = false;
+    if (options.maxParticipants) {
+      opts.maxParticipants = Number(options.maxParticipants);
+    }
+    if (options.pageSize) opts.pageSize = Number(options.pageSize);
+    if (options.maxPages) opts.maxPages = Number(options.maxPages);
+    if (options.maxFiles) opts.maxFiles = Number(options.maxFiles);
     // Alipay bill ZIP exports may be password protected. Environment fallback
     // keeps the password out of shell history for automated collection.
     const zipPassword = options.zipPassword || process.env.CC_PDH_ZIP_PASSWORD;
     if (zipPassword) opts.zipPassword = String(zipPassword);
-    // L1 local files (module 101): the local-files adapter walks directories
-    // given via opts.roots (comma-separated dirs → array). Without this the
-    // adapter falls back to its default user-data dirs.
-    if (options.roots) {
-      opts.roots = String(options.roots)
-        .split(",")
-        .map((s) => s.trim())
-        .filter(Boolean);
-    }
+    // L1 local files (module 101): repeated --root values are exact paths.
+    // The deprecated --roots alias accepts one unambiguous exact path only.
+    const roots = resolveSyncRoots(options);
+    if (roots.length > 0) opts.roots = roots;
+    applySyncSinceOverride(hub.registry, name, opts);
     const report = await hub.registry.syncAdapter(name, opts);
     const analysis = analyzeSyncReport(report);
     // 2026-05-24 in-APK Android exit + flush-race fix. Real-device repro on
@@ -1460,6 +1626,25 @@ async function cmdSalvage(dumpfile, options) {
 // the messages, and ingests them. The Android CollectQqNativeTool su-reads the
 // DB + uid candidates, then invokes this. Same logic also runs on PC (USB).
 // Plaintext is written to a temp file only for parsing, then deleted.
+function ingestQqParsedBatch(vault, parsed, conflictResolver) {
+  if (!vault || typeof vault.putBatchResolved !== "function") {
+    throw new Error(
+      "collect-qq requires a vault with transactional putBatchResolved support",
+    );
+  }
+  if (typeof conflictResolver !== "function") {
+    throw new Error("collect-qq requires the QQ quality conflict resolver");
+  }
+  const batch = {
+    events: Array.isArray(parsed) ? parsed : parsed?.events || [],
+    persons: Array.isArray(parsed) ? [] : parsed?.persons || [],
+    places: [],
+    items: [],
+    topics: Array.isArray(parsed) ? [] : parsed?.topics || [],
+  };
+  return vault.putBatchResolved(batch, { conflictResolver });
+}
+
 async function cmdCollectQq(options) {
   const spinner = options.json
     ? null
@@ -1540,30 +1725,14 @@ async function cmdCollectQq(options) {
     const events = Array.isArray(parsed) ? parsed : parsed.events || [];
     const persons = Array.isArray(parsed) ? [] : parsed.persons || [];
     const topics = Array.isArray(parsed) ? [] : parsed.topics || [];
-
-    for (const p of persons) {
-      try {
-        vault.putPerson(p);
-      } catch {
-        /* dup / optional */
-      }
-    }
-    for (const t of topics) {
-      try {
-        if (typeof vault.putTopic === "function") vault.putTopic(t);
-      } catch {
-        /* dup / optional */
-      }
-    }
-    let ingested = 0;
-    for (const ev of events) {
-      try {
-        vault.putEvent(ev);
-        ingested++;
-      } catch {
-        /* skip dup/invalid */
-      }
-    }
+    const qualityModule =
+      options._qqQuality ||
+      (await importPdh("@chainlesschain/personal-data-hub"));
+    const conflictResolver =
+      qualityModule.mergeQqEntityConflict ||
+      qualityModule.default?.mergeQqEntityConflict;
+    const ingestResult = ingestQqParsedBatch(vault, parsed, conflictResolver);
+    const ingested = ingestResult.counts.events;
     const report = {
       ok: true,
       matchedUid: result.uid,
@@ -1572,6 +1741,8 @@ async function cmdCollectQq(options) {
       persons: persons.length,
       topics: topics.length,
       ingested,
+      entityCounts: ingestResult.counts,
+      resolvedConflicts: ingestResult.conflicts.length,
     };
     if (spinner) spinner.succeed(`collect-qq: ${ingested} QQ messages → vault`);
     if (options.json) {
@@ -3399,8 +3570,13 @@ export function registerHubCommand(program) {
       "Path to a snapshot file or local DB (system-data-android snapshot, douyin <uid>_im.db, wechat-pc MSG*.db, etc.)",
     )
     .option(
-      "--roots <dirs>",
-      "Comma-separated directories to scan (local-files adapter, e.g. /sdcard/Documents,/sdcard/Download)",
+      "--root <path>",
+      "Exact directory to scan with local-files; repeat for multiple roots (commas and surrounding spaces are preserved)",
+      collectSyncRoot,
+    )
+    .option(
+      "--roots <path>",
+      "Deprecated single exact directory alias; comma-containing values are rejected (use repeated --root)",
     )
     .option(
       "--db-path <path>",
@@ -3434,9 +3610,138 @@ export function registerHubCommand(program) {
       "--cookie-file <path>",
       "Read the login cookie from a local file (preferred over putting it in shell history)",
     )
+    .option(
+      "--access-token <token>",
+      "OAuth access token for supported official API collectors",
+    )
+    .option(
+      "--access-token-file <path>",
+      "Read an OAuth access token from a local file (preferred; or set CC_PDH_ACCESS_TOKEN)",
+    )
+    .option(
+      "--app-id <id>",
+      "OAuth application ID for collectors that require request signing (or set CC_PDH_APP_ID)",
+    )
+    .option("--app-key <key>", "OAuth application key for request signing")
+    .option(
+      "--app-key-file <path>",
+      "Read an OAuth application key from a local file (preferred; or set CC_PDH_APP_KEY)",
+    )
     .option(
       "--account-id <id>",
-      "Platform account identity (for example a Zhihu url_token; stored only as a hashed scope)",
+      "Stable local platform account identity; stored only as a hashed scope",
+    )
+    .option(
+      "--source-url <https-url>",
+      "One-shot HTTPS source endpoint for collectors that require an explicitly captured API URL (or set CC_PDH_SOURCE_URL)",
+    )
+    .option(
+      "--dir <path>",
+      "Baidu Netdisk application directory (required; /apps/{appname} or a subdirectory)",
+    )
+    .option(
+      "--export-dir <path>",
+      "Local directory containing files exported from Tencent Docs",
+    )
+    .option(
+      "--profile-path <path>",
+      "Local browser/app profile or scan directory (also accepts Tencent Meeting and local-files roots)",
+    )
+    .option(
+      "--cursor-home <path>",
+      "Cursor local data home containing projects/agent-transcripts and ai-tracking",
+    )
+    .option(
+      "--claude-home <path>",
+      "Claude Code local data home containing projects and stats-cache.json",
+    )
+    .option(
+      "--hbuilderx-home <path>",
+      "HBuilderX local data directory containing file-activity INI metadata",
+    )
+    .option(
+      "--source-timezone <iana-or-offset>",
+      "Timezone for local timestamps without an embedded offset (for example Asia/Shanghai or UTC+08:00)",
+    )
+    .option(
+      "--source-timezone-offset-minutes <minutes>",
+      "Fixed source timezone offset in minutes (-840 to 840)",
+    )
+    .option("--no-history", "Exclude browser visit history")
+    .option("--no-bookmarks", "Exclude browser bookmarks")
+    .option("--no-downloads", "Exclude browser download history")
+    .option("--no-local-history", "Exclude VS Code Local History save metadata")
+    .option(
+      "--no-agent-transcripts",
+      "Exclude Cursor local Agent prompt/response transcripts",
+    )
+    .option(
+      "--no-ai-tracking",
+      "Exclude Cursor AI conversation summaries and code-activity metadata",
+    )
+    .option(
+      "--no-claude-subagents",
+      "Exclude Claude Code local subagent transcripts",
+    )
+    .option(
+      "--no-claude-stats",
+      "Exclude Claude Code aggregate activity and model-token statistics",
+    )
+    .option(
+      "--no-participants",
+      "Exclude participant names from Tencent Meeting history collection",
+    )
+    .option(
+      "--no-artifacts",
+      "Exclude document, recording, AI-summary, and chat metadata from Tencent Meeting history collection",
+    )
+    .option(
+      "--no-contacts",
+      "Exclude Android contacts from system-data-android collection",
+    )
+    .option(
+      "--no-apps",
+      "Exclude installed Android apps from system-data-android collection",
+    )
+    .option(
+      "--no-sms",
+      "Exclude Android SMS messages from system-data-android collection",
+    )
+    .option(
+      "--no-calls",
+      "Exclude Android call history from system-data-android collection",
+    )
+    .option(
+      "--no-media",
+      "Exclude Android media file metadata from system-data-android collection",
+    )
+    .option(
+      "--max-participants <n>",
+      "Maximum participant records retained per Tencent Meeting (default 1000, max 10000)",
+    )
+    .option(
+      "--drive-id <id>",
+      "Cloud drive ID for collectors that require it (WPS OpenAPI)",
+    )
+    .option(
+      "--parent-id <id>",
+      "Parent folder ID for collectors that support it (WPS defaults to 0)",
+    )
+    .option(
+      "--shallow",
+      "Collect only direct children instead of recursively traversing folders (WPS, Baidu Netdisk, or Tencent Docs exports)",
+    )
+    .option(
+      "--page-size <n>",
+      "Source page size when supported (Baidu Netdisk: 1-1000; WPS: 1-500)",
+    )
+    .option(
+      "--max-pages <n>",
+      "Maximum source pages for this run; an incomplete scan keeps the old watermark",
+    )
+    .option(
+      "--max-files <n>",
+      "Maximum local export files to inspect; an incomplete scan keeps the old watermark",
     )
     .option(
       "--zip-password <password>",
@@ -4005,6 +4310,11 @@ export const _internal = {
   summarizeSyncReports,
   formatSyncReportLine,
   resolveSyncCookie,
+  resolveSyncAccessToken,
+  resolveSyncAppKey,
+  collectSyncRoot,
+  resolveSyncRoots,
+  applySyncSinceOverride,
   cmdSyncAdapter,
   cmdSyncAll,
   cmdAIChatList,
@@ -4033,4 +4343,5 @@ export const _internal = {
   importEventsInto,
   cmdExportEvents,
   cmdImportEvents,
+  ingestQqParsedBatch,
 };

package/src/data/changelog.json

@@ -1,6 +1,32 @@
 {
   "source": "CHANGELOG.md",
   "releases": [
+    {
+      "productVersion": null,
+      "cliVersion": "0.162.180",
+      "cliVersions": ["0.162.180"],
+      "date": "2026-07-26",
+      "title": "",
+      "sections": [
+        {
+          "heading": "Added — cc CLI 0.162.180 + PDH 0.4.56: transactional multi-source ingest",
+          "body": "> `chainlesschain` **0.162.180** bundles\n> `@chainlesschain/personal-data-hub` **0.4.56** (2026-07-26).\n\n- **Transactional identity resolution**: adapters can persist source aliases,\n  raw observations, and field-level conflict decisions in one transaction;\n  entity resolution, KG, and RAG sinks now consume the exact persisted IDs and\n  rewritten references.\n- **QQ NT evidence convergence**: direct database reads and Python sidecar\n  decoding share canonical message identities while retaining both raw\n  observations. Rich decoded text and mutable read state merge without losing\n  older evidence, and pre-upgrade rows are rekeyed instead of duplicated.\n- **Reliable bounded sync**: harden cancellation, checkpoint, lookback, and\n  resume boundaries for long-running sidecars plus Android and Windows\n  incremental collectors.\n- **Release validation**: 253 PDH test files / 4215 tests, the focused\n  multi-source ingest suite, and 110 Python bridge tests passed before release."
+        }
+      ]
+    },
+    {
+      "productVersion": null,
+      "cliVersion": "0.162.179",
+      "cliVersions": ["0.162.179"],
+      "date": "2026-07-25",
+      "title": "",
+      "sections": [
+        {
+          "heading": "Added — cc CLI 0.162.179 + PDH 0.4.55：跨端实时采集与输入安全收口",
+          "body": "> `chainlesschain` **0.162.179** 搭载\n> `@chainlesschain/personal-data-hub` **0.4.55**（2026-07-25）。\n\n- **跨端实时采集**：CLI、桌面端与 Web Panel 统一暴露实时采集控制和流式结果，\n  支持有界 cookie 运行时采集、临时 OAuth 输入及 Android ADB 数据桥接。\n- **可达性与失败闭合**：readiness 只报告当前可达的输入路径；缺失或无效的\n  cookie 来源页、采集输入和 WhatsApp 备份不再被误报为成功。\n- **采集可靠性**：支持带密钥的 WhatsApp ADB 同步，WeRead 源错误时保留游标，\n  并恢复 Bilibili Android 采集客户端。\n- **发布链安全**：npm 发布工作流启用 Trusted Publishing/OIDC 与 provenance，\n  同时保留 `NPM_TOKEN` 作为当前发布的备用通道。"
+        }
+      ]
+    },
     {
       "productVersion": null,
       "cliVersion": "0.162.178",
@@ -10,7 +36,7 @@
       "sections": [
         {
           "heading": "Fixed — cc CLI 0.162.178 + IDE provider 403 diagnosis hotfix",
-          "body": "- Preserve structured provider error codes/messages for failed LLM requests and\n  `cc llm test`, with credential-shaped text redacted before display.\n- Do not classify every HTTP 403 as an invalid API key: overdue accounts,\n  billing failures, and model-access denials now retain their real corrective\n  action in CLI, VS Code, and JetBrains.\n- Release VS Code 0.37.33 and JetBrains 0.4.70 with corrected setup guidance."
+          "body": "- Preserve structured provider error codes/messages for failed LLM requests and\n  `cc llm test`, with credential-shaped text redacted before display.\n- Do not classify every HTTP 403 as an invalid API key: overdue accounts,\n  billing failures, and model-access denials now retain their real corrective\n  action in CLI, VS Code, and JetBrains.\n- Release VS Code 0.37.33 and JetBrains 0.4.71 with corrected setup guidance;\n  JetBrains 0.4.70 was deleted during Marketplace review and superseded after\n  clearing the IntelliJ 2026.2 internal-API warning.\n- Prepare JetBrains 0.4.72 so `/status` and the other live-session slash\n  commands use the same routing, output, aliases, arguments, and help text as\n  the VS Code panel, including `/expand` reasoning-block toggling."
         }
       ]
     },

package/src/gateways/ws/personal-data-hub-protocol.js

@@ -49,6 +49,55 @@ async function ingestSystemDataAndroidSnapshot(hub, snapshot) {
   return _ingestSnapshotFn(hub, snapshot);
 }
 
+/**
+ * Adapters that must never consume an Android staging snapshot implicitly.
+ * They either have a richer live bridge or read desktop-local state directly.
+ * Exported as an immutable array so the transport contract can be guarded
+ * without exercising ADB in unit tests.
+ */
+export const ADB_AUTO_PULL_BYPASS_ADAPTERS = Object.freeze([
+  "system-data-android",
+  "browser-history-chrome",
+  "browser-history-edge",
+  "browser-history-brave",
+  "browser-history-opera",
+  "browser-history-vivaldi",
+  "browser-history-safari",
+  "browser-history-firefox",
+  "vscode",
+  "vscodium",
+  "cursor",
+  "claude-code",
+  "jetbrains-ide",
+  "hbuilderx",
+  "win-recent",
+  "git-activity",
+  "shell-history",
+  "local-files",
+  "meeting-tencent",
+]);
+
+const ADB_AUTO_PULL_BYPASS_SET = new Set(ADB_AUTO_PULL_BYPASS_ADAPTERS);
+const EXPLICIT_LIVE_SOURCE_OPTION_KEYS = Object.freeze([
+  "cookie",
+  "cookies",
+  "accessToken",
+  "appKey",
+  "apiKey",
+  "token",
+  "sourceUrl",
+]);
+
+export function hasExplicitLiveSourceOptions(options) {
+  if (!options || typeof options !== "object") return false;
+  return EXPLICIT_LIVE_SOURCE_OPTION_KEYS.some((key) => {
+    const value = options[key];
+    if (typeof value === "string") return value.trim().length > 0;
+    if (Array.isArray(value)) return value.length > 0;
+    return value != null && typeof value === "object";
+  });
+}
+
 /**
  * If the caller didn't pass `inputPath`, try to pull a snapshot for
  * this adapter off the attached Android phone via `adb shell run-as
@@ -70,7 +119,7 @@ async function ingestSystemDataAndroidSnapshot(hub, snapshot) {
  * return the original options unchanged so the adapter's normal error
  * path fires and the UI banner shows a meaningful message.
  */
-async function _tryAdbAutoPullInputPath(hub, name, options) {
+export async function _tryAdbAutoPullInputPath(hub, name, options) {
   if (
     options &&
     typeof options.inputPath === "string" &&
@@ -78,6 +127,13 @@ async function _tryAdbAutoPullInputPath(hub, name, options) {
   ) {
     return options; // caller already supplied a path
   }
+  // An explicit live credential or endpoint is a stronger user intent than
+  // an implicit, potentially stale Android staging snapshot. Every dual-mode
+  // adapter checks inputPath first, so adding an auto-pulled path here would
+  // silently turn a requested live sync into a snapshot import.
+  if (hasExplicitLiveSourceOptions(options)) {
+    return options;
+  }
   // Skip auto-pull for adapters that have a live bridge mode — pulling
   // a stale snapshot file would short-circuit the bridge path which
   // yields fresher / richer data (e.g. system-data-android's bridge
@@ -85,20 +141,11 @@ async function _tryAdbAutoPullInputPath(hub, name, options) {
   // an Android-collected snapshot only contains contacts + apps).
   // Keep this list in sync with adapters whose _syncViaBridge is
   // strictly richer than their snapshot output.
-  // browser-history-* and vscode read desktop-local files (browser History
-  // SQLite + Bookmarks JSON, or VS Code workspaceStorage + state.vscdb);
-  // ADB snapshot is meaningless for them.
-  const BRIDGE_PREFERRED = new Set([
-    "system-data-android",
-    "browser-history-chrome",
-    "browser-history-edge",
-    "vscode",
-    "win-recent",
-    "git-activity",
-    "shell-history",
-    "local-files",
-  ]);
-  if (BRIDGE_PREFERRED.has(name)) {
+  // browser-history-*, vscode/vscodium/cursor, claude-code, and
+  // jetbrains-ide read desktop-local files (browser profiles, editor/Agent
+  // state, Claude Code transcripts, or JetBrains recentProjects.xml);
+  // an ADB snapshot is meaningless for them.
+  if (ADB_AUTO_PULL_BYPASS_SET.has(name)) {
     return options || {};
   }
   try {
@@ -326,7 +373,9 @@ export const PERSONAL_DATA_HUB_HANDLERS = {
               unlinkSync(p);
               removed.push(p);
             }
-          } catch (_e) {}
+          } catch {
+            // Account files are removed on a best-effort basis.
+          }
         }
       }
       if (alsoWipeMasterKey) {
@@ -337,14 +386,20 @@ export const PERSONAL_DATA_HUB_HANDLERS = {
               try {
                 unlinkSync(join(keyDir, f));
                 removed.push(join(keyDir, f));
-              } catch (_e) {}
+              } catch {
+                // Key fragments are removed on a best-effort basis.
+              }
             }
           }
-        } catch (_e) {}
+        } catch {
+          // Key-directory cleanup is best-effort.
+        }
       }
       try {
         closeHub();
-      } catch (_e) {}
+      } catch {
+        // The hub may already be closed after a partial wipe.
+      }
       return { result: { ok: true, removed } };
     } catch (err) {
       return { error: err && err.message ? err.message : String(err) };
@@ -640,11 +695,15 @@ export const PERSONAL_DATA_HUB_STREAMING_HANDLERS = {
           type: "personal-data-hub.sync-adapter-stream.event",
           event: evt,
         });
-      } catch (_e) {}
+      } catch {
+        // Streaming clients may disconnect while collection continues.
+      }
       if (typeof original === "function") {
         try {
           original(evt);
-        } catch (_e) {}
+        } catch {
+          // A prior observer must not break collection telemetry.
+        }
       }
     };
     const options = await _tryAdbAutoPullInputPath(hub, msg.name, msg.options);
@@ -669,11 +728,15 @@ export const PERSONAL_DATA_HUB_STREAMING_HANDLERS = {
     hub.registry.onSyncEvent = (evt) => {
       try {
         sender({ type: "personal-data-hub.sync-all-stream.event", event: evt });
-      } catch (_e) {}
+      } catch {
+        // Streaming clients may disconnect while collection continues.
+      }
       if (typeof original === "function") {
         try {
           original(evt);
-        } catch (_e) {}
+        } catch {
+          // A prior observer must not break collection telemetry.
+        }
       }
     };
     try {