@remnic/core 9.3.771 → 9.4.1

package/src/qmd.ts

@@ -18,6 +18,33 @@ import {
 } from "./search/port.js";
 import { launchProcess, type CommandChildProcess } from "./runtime/child-process.js";
 import { mergeEnv } from "./runtime/env.js";
+import {
+  classifyProbeFailure,
+  compareQmdVersions,
+  getQmdPostInstallProbeTargets,
+  parseQmdVersion,
+  parseQmdVersionOutput,
+  QMD_PROBE_RETRY_BACKOFF_MS,
+  QMD_PROBE_TIMEOUT_MS,
+  QMD_SUPPORTED_VERSION,
+  qmdVersionToString,
+  resolveQmdCapabilities,
+  shouldAutoUpgradeQmd,
+  versionAtLeast,
+  type QmdProbeFailureKind,
+} from "./qmd-preflight.js";
+// Re-export version-check / probe-preflight helpers (moved to qmd-preflight.ts,
+// issue #1841) so existing imports from "./qmd.js" keep resolving.
+export {
+  compareQmdVersions,
+  getQmdPostInstallProbeTargets,
+  parseQmdVersion,
+  parseQmdVersionOutput,
+  QMD_SUPPORTED_VERSION,
+  resolveQmdCapabilities,
+  shouldAutoUpgradeQmd,
+  versionAtLeast,
+};
 
 export interface QmdClientOptions {
   slowLog?: { enabled: boolean; thresholdMs: number };
@@ -133,11 +160,9 @@ const QMD_TIMEOUT_MS = 30_000;
 // `qmdDaemonTimeoutMs` config knob (issue #1335), e.g. to give CPU-only HyDE
 // queries more headroom. The effective value lives in `this.daemonTimeoutMs`.
 const QMD_DAEMON_TIMEOUT_MS = 8_000;
-const QMD_PROBE_TIMEOUT_MS = 8_000;
 const QMD_UPDATE_BACKOFF_MS = 15 * 60 * 1000; // 15m
 const QMD_EMBED_BACKOFF_MS = 60 * 60 * 1000; // 60m
 const QMD_CLI_WARN_THROTTLE_MS = 15 * 60 * 1000; // 15m
-export const QMD_SUPPORTED_VERSION = "2.5.3";
 const QMD_PACKAGE_NAME = "@tobilu/qmd";
 const QMD_AUTO_UPGRADE_TIMEOUT_MS = 120_000;
 const QMD_AUTO_UPGRADE_CHECK_INTERVAL_MS = 24 * 60 * 60_000;
@@ -269,118 +294,6 @@ function isVectorDimensionMismatchError(err: unknown): boolean {
   );
 }
 
-export function parseQmdVersion(version: string | null): QmdVersionTuple | null {
-  if (!version) return null;
-  const match = version.match(/v?(\d{1,10})\.(\d{1,10})\.(\d{1,10})/i);
-  if (!match) return null;
-  return [
-    Number.parseInt(match[1] ?? "0", 10),
-    Number.parseInt(match[2] ?? "0", 10),
-    Number.parseInt(match[3] ?? "0", 10),
-  ];
-}
-
-export function parseQmdVersionOutput(stdout: string, stderr: string): string | null {
-  const lines = `${stdout}\n${stderr}`
-    .split("\n")
-    .map((s) => s.trim())
-    .filter((s) => s.length > 0);
-  if (lines.length === 0) return null;
-  const semanticLines = lines.filter((line) => parseQmdVersion(line) !== null);
-  if (semanticLines.length === 0) return lines[0] ?? null;
-  return semanticLines.find((line) => /\bqmd\b/i.test(line)) ?? semanticLines[0] ?? null;
-}
-
-export function compareQmdVersions(
-  left: QmdVersionTuple | null,
-  right: QmdVersionTuple | null,
-): number {
-  if (!left && !right) return 0;
-  if (!left) return -1;
-  if (!right) return 1;
-  for (let i = 0; i < 3; i += 1) {
-    if ((left[i] ?? 0) > (right[i] ?? 0)) return 1;
-    if ((left[i] ?? 0) < (right[i] ?? 0)) return -1;
-  }
-  return 0;
-}
-
-export function versionAtLeast(
-  current: QmdVersionTuple | null,
-  target: QmdVersionTuple,
-): boolean {
-  return compareQmdVersions(current, target) >= 0;
-}
-
-export function resolveQmdCapabilities(version: string | null): QmdCapabilities {
-  const parsedVersion = parseQmdVersion(version);
-  const atLeast = (target: QmdVersionTuple): boolean => versionAtLeast(parsedVersion, target);
-  return {
-    version,
-    parsedVersion,
-    stableSdk: atLeast([2, 0, 0]),
-    unifiedSearch: atLeast([2, 0, 0]),
-    getDocumentBody: atLeast([2, 0, 0]),
-    maintenanceApi: atLeast([2, 0, 0]),
-    legacySkillInstall: atLeast([2, 0, 1]),
-    intentHints: atLeast([1, 1, 5]),
-    explainTraces: atLeast([1, 1, 2]),
-    candidateLimit: atLeast([1, 1, 2]),
-    v2McpQueryTool: atLeast([2, 0, 0]),
-    structuredSearches: atLeast([2, 0, 0]),
-    queryRerankToggle: atLeast([2, 1, 0]),
-    chunkStrategy: atLeast([2, 1, 0]),
-    qmdBench: atLeast([2, 1, 0]),
-    perCollectionModels: atLeast([2, 1, 0]),
-    jsonLineNumbers: atLeast([2, 1, 0]),
-    editorLinks: atLeast([2, 1, 0]),
-    doctor: atLeast([2, 5, 0]),
-    versionedSkills: atLeast([2, 5, 0]),
-    absoluteSnippetLines: atLeast([2, 5, 0]),
-    fullQueryOutput: atLeast([2, 5, 0]),
-    forceCpu: atLeast([2, 5, 0]),
-    gpuBackendOverride: atLeast([2, 5, 0]),
-    embedParallelism: atLeast([2, 5, 0]),
-    modelEnvConsistency: atLeast([2, 5, 0]),
-    scopedEmbed: atLeast([2, 5, 0]),
-    safeStatusDeviceProbe: atLeast([2, 5, 0]),
-    mcpIndexSelection: atLeast([2, 5, 0]),
-    outputFormatFlag: atLeast([2, 5, 3]),
-  };
-}
-
-export function shouldAutoUpgradeQmd(
-  installedVersion: string | null,
-  supportedVersion: string = QMD_SUPPORTED_VERSION,
-): boolean {
-  const installed = parseQmdVersion(installedVersion);
-  const supported = parseQmdVersion(supportedVersion);
-  if (!installed || !supported) return false;
-  return compareQmdVersions(installed, supported) < 0;
-}
-
-export function getQmdPostInstallProbeTargets(
-  qmdPath: string,
-  qmdPathSource: "configured" | "auto-path" | "auto-fallback",
-): Array<{ qmdPath: string; source: "auto-path" | "auto-fallback" }> {
-  const targets: Array<{ qmdPath: string; source: "auto-path" | "auto-fallback" }> = [
-    { qmdPath: "qmd", source: "auto-path" },
-  ];
-  const normalizedPath = qmdPath.trim();
-  if (
-    qmdPathSource === "auto-fallback" &&
-    normalizedPath.length > 0 &&
-    normalizedPath !== "qmd"
-  ) {
-    targets.push({ qmdPath: normalizedPath, source: "auto-fallback" });
-  }
-  return targets;
-}
-
-function qmdVersionToString(version: QmdVersionTuple): string {
-  return `${version[0]}.${version[1]}.${version[2]}`;
-}
-
 function normalizeSearchOptions(options?: SearchQueryOptions): SearchQueryOptions | undefined {
   if (!options) return undefined;
   const intent = typeof options.intent === "string" ? options.intent.trim() : "";
@@ -671,7 +584,13 @@ function runCommandWithTimeout(
       settled = true;
       cleanup();
       child.kill("SIGKILL");
-      reject(new Error(`${label} timed out after ${options.timeoutMs}ms`));
+      // Flag the deadline breach so classifyProbeFailure can tell a genuine
+      // timeout from a non-zero-exit error whose message merely embeds stderr.
+      reject(
+        Object.assign(new Error(`${label} timed out after ${options.timeoutMs}ms`), {
+          timedOut: true as const,
+        }),
+      );
     }, options.timeoutMs);
     const onAbort = () => {
       if (settled) return;
@@ -1437,6 +1356,18 @@ export class QmdClient implements SearchBackend {
     }
   }
 
+  /**
+   * Run a single `qmd --version` probe against `qmdPath`. Extracted as its own
+   * method so tests can inject a fake probe runner that exercises the preflight
+   * retry/classification paths without spawning a real qmd binary. Issue #1841.
+   */
+  private runVersionProbe(
+    qmdPath: string,
+    signal?: AbortSignal,
+  ): Promise<{ stdout: string; stderr: string }> {
+    return runQmd(["--version"], QMD_PROBE_TIMEOUT_MS, qmdPath, signal, this.qmdRuntimeEnv);
+  }
+
   private async probeCli(
     options: {
       allowAutoUpgrade?: boolean;
@@ -1490,24 +1421,79 @@ export class QmdClient implements SearchBackend {
     };
 
     if (this.configuredQmdPath) {
-      try {
-        const result = await runQmd(["--version"], QMD_PROBE_TIMEOUT_MS, this.configuredQmdPath, options.signal, this.qmdRuntimeEnv);
-        await recordProbeSuccess(result, this.configuredQmdPath, "configured");
-        return true;
-      } catch (err) {
-        markProbeFailure(err);
-        configuredProbeFailure = this.lastCliProbeError;
-        // Do not hard-fail here: fall through to PATH/fallback probing.
-        // This keeps recall healthy even when configured path is stale.
-        this.logCliProbeWarning(
-          `QMD: configured qmdPath failed (${this.configuredQmdPath}): ${this.lastCliProbeError}`,
-        );
+      const configuredPath = this.configuredQmdPath;
+      // Retry only TRANSIENT (timeout/abort) probes of the configured path: a
+      // binary that resolved and ran before is more likely slow under load than
+      // gone. ENOENT/EACCES is a hard misconfiguration and must fail fast.
+      // Issue #1841.
+      let failureKind: QmdProbeFailureKind = "other";
+      let retries = 0;
+      let callerCancelled = false;
+      for (let attempt = 0; attempt <= QMD_PROBE_RETRY_BACKOFF_MS.length; attempt += 1) {
+        try {
+          const result = await this.runVersionProbe(configuredPath, options.signal);
+          await recordProbeSuccess(result, configuredPath, "configured");
+          return true;
+        } catch (err) {
+          markProbeFailure(err);
+          configuredProbeFailure = this.lastCliProbeError;
+          // Detect CALLER cancellation FIRST: an aborted signal / AbortError is
+          // non-actionable noise — the caller chose to stop. Other QMD paths
+          // treat it via `isCallerCancellation`; do the same here so a cancelled
+          // probe never reads as a transient host-load failure. Issue #1841.
+          if (isCallerCancellation(err, options.signal)) {
+            callerCancelled = true;
+            break;
+          }
+          failureKind = classifyProbeFailure(err);
+          // Never retry a hard misconfiguration (missing/not-executable) — only
+          // transient slowness. (Caller cancellation is handled above.)
+          if (
+            failureKind === "transient" &&
+            attempt < QMD_PROBE_RETRY_BACKOFF_MS.length
+          ) {
+            try {
+              await sleepWithSignal(
+                QMD_PROBE_RETRY_BACKOFF_MS[attempt] ?? 500,
+                options.signal,
+              );
+            } catch {
+              // Aborted mid-backoff: caller cancelled — stop, emit no warning.
+              callerCancelled = true;
+              break;
+            }
+            retries += 1;
+            continue;
+          }
+          break;
+        }
+      }
+      // Distinct operator-facing warnings so a slow binary is not mistaken for
+      // a misconfiguration (and vice versa). Do not hard-fail here: fall through
+      // to PATH/fallback probing so recall stays healthy when config is stale.
+      // Caller cancellation is silent noise (issue #1841): suppress all warnings
+      // for it exactly as the other QMD paths do.
+      if (!callerCancelled) {
+        if (failureKind === "transient") {
+          this.logCliProbeWarning(
+            `QMD: qmdPath ${configuredPath} version check timed out (host may be under load); retried ${retries} time${retries === 1 ? "" : "s"}`,
+          );
+        } else if (failureKind === "missing") {
+          this.logCliProbeWarning(
+            `QMD: configured qmdPath not found or not executable (${configuredPath}): ${this.lastCliProbeError}`,
+          );
+        } else {
+          // Preserve the historical generic message for exit-code/other failures.
+          this.logCliProbeWarning(
+            `QMD: configured qmdPath failed (${configuredPath}): ${this.lastCliProbeError}`,
+          );
+        }
       }
     }
 
     // Try PATH first
     try {
-      const result = await runQmd(["--version"], QMD_PROBE_TIMEOUT_MS, "qmd", options.signal, this.qmdRuntimeEnv);
+      const result = await this.runVersionProbe("qmd", options.signal);
       await recordProbeSuccess(result, "qmd", "auto-path");
       return true;
     } catch (err) {
@@ -1515,7 +1501,7 @@ export class QmdClient implements SearchBackend {
       // Try fallback paths
       for (const fallbackPath of this.qmdFallbackPaths) {
         try {
-          const result = await runQmd(["--version"], QMD_PROBE_TIMEOUT_MS, fallbackPath, options.signal, this.qmdRuntimeEnv);
+          const result = await this.runVersionProbe(fallbackPath, options.signal);
           await recordProbeSuccess(result, fallbackPath, "auto-fallback");
           log.info(`QMD: found at ${fallbackPath}`);
           return true;

package/src/runtime/better-sqlite.test.ts

@@ -4,6 +4,7 @@ import {
   displayErrorDetail,
   isLikelyBetterSqlite3NativeBindingError,
   openBetterSqlite3,
+  probeBetterSqlite3Driver,
 } from "./better-sqlite.js";
 
 test("isLikelyBetterSqlite3NativeBindingError recognizes missing and mismatched native bindings", () => {
@@ -22,6 +23,50 @@ test("isLikelyBetterSqlite3NativeBindingError recognizes missing and mismatched
   assert.equal(isLikelyBetterSqlite3NativeBindingError(new Error("SQLITE_BUSY: database is locked")), false);
 });
 
+test("isLikelyBetterSqlite3NativeBindingError walks the cause chain of a sanitized wrapper (issue #1848)", () => {
+  // Production path: loadBetterSqlite3() catches the ABI error and re-throws a
+  // sanitized unavailableError WRAPPER whose message drops the ABI markers. The
+  // original error survives only on .cause — the classifier must walk it, or
+  // the startup probe / projection doctor / browse warn all MISS the hint.
+  const abiCause = new Error(
+    "The module was compiled against a different Node.js version using NODE_MODULE_VERSION 127",
+  );
+  const wrapper = new Error(
+    "better-sqlite3 is unavailable. Remnic attempted to load the native SQLite binding and could not.",
+    { cause: abiCause },
+  );
+  assert.equal(isLikelyBetterSqlite3NativeBindingError(wrapper), true);
+
+  // Deeply nested wrapper (wrapper.cause.cause = ABI error) is still found.
+  const deepWrapper = new Error("outer sanitized layer", { cause: wrapper });
+  assert.equal(isLikelyBetterSqlite3NativeBindingError(deepWrapper), true);
+
+  // A wrapper whose cause is NOT a native-binding failure stays negative.
+  const benignWrapper = new Error("better-sqlite3 is unavailable.", {
+    cause: new Error("SQLITE_BUSY: database is locked"),
+  });
+  assert.equal(isLikelyBetterSqlite3NativeBindingError(benignWrapper), false);
+});
+
+test("isLikelyBetterSqlite3NativeBindingError inspects AggregateError.errors siblings", () => {
+  // Module loaders can surface failures as an AggregateError; the ABI mismatch
+  // may live in a sibling rather than the aggregate's own message.
+  const agg = new AggregateError([
+    new Error("some unrelated loader step"),
+    new Error("Could not locate the bindings file. Tried: better_sqlite3.node"),
+  ]);
+  assert.equal(isLikelyBetterSqlite3NativeBindingError(agg), true);
+
+  const benignAgg = new AggregateError([new Error("unrelated"), new Error("SQLITE_BUSY")]);
+  assert.equal(isLikelyBetterSqlite3NativeBindingError(benignAgg), false);
+});
+
+test("isLikelyBetterSqlite3NativeBindingError is cycle-safe on a self-referential cause", () => {
+  const cyclic = new Error("SQLITE_BUSY: database is locked");
+  cyclic.cause = cyclic; // would loop forever without a visited set
+  assert.equal(isLikelyBetterSqlite3NativeBindingError(cyclic), false);
+});
+
 test("displayErrorDetail surfaces only error class + code, never the raw message (CodeQL js/stack-trace-exposure)", () => {
   // MODULE_NOT_FOUND messages embed an absolute "Require stack:" path block.
   const moduleNotFound = Object.assign(
@@ -59,3 +104,12 @@ test("openBetterSqlite3 can open an in-memory database after install verificatio
     db.close();
   }
 });
+
+test("probeBetterSqlite3Driver succeeds (ok=true) under the verified process and warms the ctor cache", () => {
+  const probe = probeBetterSqlite3Driver();
+  assert.equal(probe.ok, true);
+  assert.equal(probe.detail, "");
+  assert.equal(probe.nativeBindingMismatch, false);
+  // A second probe reuses the warmed cache (no re-load); still ok.
+  assert.equal(probeBetterSqlite3Driver().ok, true);
+});

package/src/runtime/better-sqlite.ts

@@ -28,6 +28,35 @@ export function openBetterSqlite3(
   return new Database(file, options);
 }
 
+export interface BetterSqlite3DriverProbe {
+  /** true when the native binding loaded successfully under this process. */
+  ok: boolean;
+  /** Path-free detail string (class + code) from `displayErrorDetail`; "" when ok. */
+  detail: string;
+  /** true when the failure is classified as a native-binding ABI mismatch. */
+  nativeBindingMismatch: boolean;
+}
+
+/**
+ * Attempt to load the better-sqlite3 native driver under the running process
+ * WITHOUT opening a database. Used by the server startup check (issue #1829)
+ * to surface a wrong-ABI build loudly instead of letting each memory browse
+ * silently fall back to a full-corpus scan. Never throws — callers log the
+ * result. A successful probe also warms the ctor cache for later opens.
+ */
+export function probeBetterSqlite3Driver(): BetterSqlite3DriverProbe {
+  try {
+    loadBetterSqlite3();
+    return { ok: true, detail: "", nativeBindingMismatch: false };
+  } catch (error) {
+    return {
+      ok: false,
+      detail: displayErrorDetail(error),
+      nativeBindingMismatch: isLikelyBetterSqlite3NativeBindingError(error),
+    };
+  }
+}
+
 function requireBetterSqlite3Ctor(require: RuntimeRequire): BetterSqlite3Ctor {
   const loaded = require("better-sqlite3") as
     | BetterSqlite3Ctor
@@ -50,9 +79,49 @@ function rawErrorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error ?? "");
 }
 
-export function isLikelyBetterSqlite3NativeBindingError(error: unknown): boolean {
-  // Classify on the RAW message so redaction can't strip detection markers
-  // (e.g. the path containing "better_sqlite3.node").
+/**
+ * Iterate an error and every node reachable along its `cause` chain and any
+ * `AggregateError.errors` siblings (depth-first), cycle-safe via a visited set.
+ *
+ * Native-binding failures thrown from openBetterSqlite3 /
+ * probeBetterSqlite3Driver are caught and re-thrown as a sanitized
+ * `unavailableError` WRAPPER: the wrapper's message drops the ABI markers
+ * (NODE_MODULE_VERSION, better_sqlite3.node, …) that live on the ORIGINAL
+ * error. So classification must walk `.cause` (and aggregate siblings) instead
+ * of inspecting only the top wrapper's message — otherwise startup logs, browse
+ * warnings, and the memory_projection doctor check all MISS the native-binding
+ * hint (issue #1848).
+ */
+function* errorChain(error: unknown): Generator<unknown> {
+  const seen = new Set<unknown>();
+  const stack: unknown[] = [error];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (node === null || node === undefined) continue;
+    if (typeof node !== "object") continue;
+    if (seen.has(node)) continue;
+    seen.add(node);
+    yield node;
+    // Narrow with `in` (not a cast) so the property access is compiler-checked.
+    if ("cause" in node) {
+      const cause = node.cause;
+      if (cause !== null && cause !== undefined) stack.push(cause);
+    }
+    if ("errors" in node) {
+      const errors = node.errors;
+      if (Array.isArray(errors)) {
+        for (const member of errors) {
+          if (member !== null && member !== undefined) stack.push(member);
+        }
+      }
+    }
+  }
+}
+
+// True when a single error's RAW message carries a native-binding ABI marker.
+// Raw (not displayErrorDetail) so redaction can't strip detection markers
+// (e.g. the loader path containing "better_sqlite3.node").
+function messageHasNativeBindingMarker(error: unknown): boolean {
   const detail = rawErrorMessage(error);
   return (
     detail.includes("Could not locate the bindings file") ||
@@ -63,6 +132,17 @@ export function isLikelyBetterSqlite3NativeBindingError(error: unknown): boolean
   );
 }
 
+export function isLikelyBetterSqlite3NativeBindingError(error: unknown): boolean {
+  // Walk the full cause / aggregate chain so a SANITIZED wrapper
+  // (unavailableError) — whose message drops the ABI markers that live on the
+  // original error — is still classified. Inspecting only the top-level message
+  // misses the real mismatch when the failure was wrapped (issue #1848).
+  for (const node of errorChain(error)) {
+    if (messageHasNativeBindingMarker(node)) return true;
+  }
+  return false;
+}
+
 function unavailableError(error: unknown): Error {
   const detail = displayErrorDetail(error);
   const nativeBindingHint = isLikelyBetterSqlite3NativeBindingError(error)

package/src/wearables/cleanup.test.ts

@@ -132,3 +132,59 @@ test("input conversation is not mutated", () => {
   cleanConversation(input, ALL_ON);
   assert.equal(JSON.stringify(input), before);
 });
+
+
+test("merges consecutive same-speaker runs across diarized speakers", () => {
+  const result = cleanConversation(
+    conversation([
+      { speakerKey: "0", text: "Hello there.", startIso: "2026-06-10T10:00:00Z", endIso: "2026-06-10T10:00:03Z" },
+      { speakerKey: "0", text: "How are you?", startIso: "2026-06-10T10:00:04Z", endIso: "2026-06-10T10:00:07Z" },
+      { speakerKey: "1", text: "Good, thanks.", startIso: "2026-06-10T10:00:08Z", endIso: "2026-06-10T10:00:11Z" },
+      { speakerKey: "1", text: "And you?", startIso: "2026-06-10T10:00:12Z", endIso: "2026-06-10T10:00:14Z" },
+      { speakerKey: "0", text: "Busy day.", startIso: "2026-06-10T10:00:15Z", endIso: "2026-06-10T10:00:18Z" },
+    ]),
+    ALL_ON,
+  );
+  // Three runs: 0+0, 1+1, 0. Generic-label protection is off here, so
+  // diarized same-speaker adjacency merges within the gap.
+  assert.equal(result.conversation.segments.length, 3);
+  assert.equal(result.conversation.segments[0].text, "Hello there. How are you?");
+  assert.equal(result.conversation.segments[1].text, "Good, thanks. And you?");
+  assert.equal(result.conversation.segments[2].text, "Busy day.");
+  assert.equal(result.mergedSegments, 2);
+});
+
+test("preserveUtteranceBoundaries keeps generic-labeled utterances distinct (#1811)", () => {
+  const settings: WearableCleanupSettings = { ...ALL_ON, preserveUtteranceBoundaries: true };
+  const result = cleanConversation(
+    conversation([
+      { speakerKey: "unknown", text: "First.", startIso: "2026-06-10T10:00:00Z", endIso: "2026-06-10T10:00:02Z" },
+      { speakerKey: "unknown", text: "Second.", startIso: "2026-06-10T10:00:03Z", endIso: "2026-06-10T10:00:05Z" },
+      { speakerKey: "Unknown", text: "Third.", startIso: "2026-06-10T10:00:06Z", endIso: "2026-06-10T10:00:08Z" },
+      { speakerKey: "0", text: "Diarized A.", startIso: "2026-06-10T10:00:09Z", endIso: "2026-06-10T10:00:11Z" },
+      { speakerKey: "0", text: "Diarized B.", startIso: "2026-06-10T10:00:12Z", endIso: "2026-06-10T10:00:14Z" },
+    ]),
+    settings,
+  );
+  // Generic "unknown"/"Unknown" utterances are NOT merged into one block.
+  assert.equal(result.conversation.segments.length, 4);
+  assert.deepEqual(
+    result.conversation.segments.map((segment) => segment.text),
+    ["First.", "Second.", "Third.", "Diarized A. Diarized B."],
+  );
+  assert.equal(result.mergedSegments, 1);
+});
+
+test("preserveUtteranceBoundaries default (off) still collapses generic labels", () => {
+  // The flag is opt-in: without it the legacy merge-everything behavior
+  // is unchanged for sources that never set it.
+  const result = cleanConversation(
+    conversation([
+      { speakerKey: "unknown", text: "First.", startIso: "2026-06-10T10:00:00Z", endIso: "2026-06-10T10:00:02Z" },
+      { speakerKey: "unknown", text: "Second.", startIso: "2026-06-10T10:00:03Z", endIso: "2026-06-10T10:00:05Z" },
+    ]),
+    ALL_ON,
+  );
+  assert.equal(result.conversation.segments.length, 1);
+  assert.equal(result.conversation.segments[0].text, "First. Second.");
+});

package/src/wearables/cleanup.ts

@@ -24,6 +24,14 @@ export interface CleanupResult {
 /** Merge consecutive same-speaker segments when gaps are below this. */
 const MERGE_GAP_MS = 30_000;
 
+/**
+ * Speaker labels that carry no real diarization signal. Bee (and other
+ * providers that fall back to a placeholder) emit "Unknown"/"unknown"
+ * or an empty string when diarization is unavailable; merging on such a
+ * label would collapse an entire conversation into one segment (issue #1811).
+ */
+const GENERIC_SPEAKER_PATTERN = /^unknown$/i;
+
 /**
  * Standalone filler tokens stripped when `stripFillers` is on. Matched
  * case-insensitively on word boundaries, only as whole tokens — "um"
@@ -47,6 +55,9 @@ export function cleanConversation(
   let segments = conversation.segments.map((segment) => ({ ...segment }));
   let droppedSegments = 0;
   let mergedSegments = 0;
+  // Optional on the type so other connectors keep the legacy no-op
+  // default; absent means "off" (unchanged merge behavior).
+  const preserveBoundaries = settings.preserveUtteranceBoundaries === true;
 
   if (settings.stripFillers) {
     for (const segment of segments) {
@@ -86,7 +97,7 @@ export function cleanConversation(
     const merged: WearableTranscriptSegment[] = [];
     for (const segment of segments) {
       const previous = merged[merged.length - 1];
-      if (previous && canMerge(previous, segment)) {
+      if (previous && canMerge(previous, segment, preserveBoundaries)) {
         previous.text = `${previous.text} ${segment.text}`.trim();
         if (segment.endIso) previous.endIso = segment.endIso;
         mergedSegments += 1;
@@ -107,8 +118,18 @@ export function cleanConversation(
 function canMerge(
   previous: WearableTranscriptSegment,
   next: WearableTranscriptSegment,
+  preserveUtteranceBoundaries: boolean,
 ): boolean {
   if (previous.speakerKey !== next.speakerKey) return false;
+  // A generic/low-confidence speaker label ("Unknown", empty) carries no
+  // real diarization: merging on it collapses unrelated utterances. When
+  // the source opts into boundary preservation, refuse to merge across
+  // such a label (issue #1811). The keys are equal here, so checking one
+  // suffices; diarized labels still merge normally.
+  if (preserveUtteranceBoundaries) {
+    const label = previous.speakerKey.trim();
+    if (label.length === 0 || GENERIC_SPEAKER_PATTERN.test(label)) return false;
+  }
   const previousEnd = previous.endIso ? Date.parse(previous.endIso) : NaN;
   const nextStart = next.startIso ? Date.parse(next.startIso) : NaN;
   // Without timestamps, adjacency is the only signal — still merge.

package/src/wearables/config.test.ts

@@ -44,9 +44,34 @@ test("source settings default to the fully-automated smart pipeline", () => {
     stripFillers: true,
     collapseRepeats: true,
     dropLowQuality: true,
+    // Opt-in for Bee only; limitless keeps the legacy default (issue #1811).
+    preserveUtteranceBoundaries: false,
   });
 });
 
+test("bee source defaults to preserving utterance boundaries (#1811)", () => {
+  const parsed = parseWearablesConfig({
+    enabled: true,
+    sources: { bee: { enabled: true } },
+  });
+  assert.equal(parsed.sources.bee.cleanup.preserveUtteranceBoundaries, true);
+});
+
+test("cleanup.preserveUtteranceBoundaries is parsed and overrides the source default", () => {
+  const parsed = parseWearablesConfig({
+    enabled: true,
+    sources: { bee: { enabled: true, cleanup: { preserveUtteranceBoundaries: false } } },
+  });
+  assert.equal(parsed.sources.bee.cleanup.preserveUtteranceBoundaries, false);
+  assert.throws(
+    () =>
+      parseWearablesConfig({
+        sources: { bee: { cleanup: { preserveUtteranceBoundaries: "maybe" } } },
+      }),
+    /cleanup.preserveUtteranceBoundaries/,
+  );
+});
+
 test("top-level defaults are full-featured: digest and off-the-record on", () => {
   const parsed = parseWearablesConfig({});
   assert.equal(parsed.digestEnabled, true);