@lincoln504/pi-research 1.1.2 → 1.3.0

package/src/infrastructure/process-lifecycle-service.ts

@@ -11,6 +11,39 @@ import type { IProcessLifecycle } from '../core/interfaces/process-interfaces.ts
 import { ServiceLifecycle } from '../core/service-registry.ts';
 import { ServiceNames } from '../core/interfaces/service-names.ts';
 
+/**
+ * Parse the POSIX `ps -o etime=` elapsed-time format into whole seconds.
+ * Accepted shapes: `MM:SS`, `HH:MM:SS`, `DD-HH:MM:SS`. Returns null if it does
+ * not parse, so a caller degrades to "unknown" rather than to a bogus number.
+ */
+export function parseEtime(value: string): number | null {
+  const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(value.trim());
+  if (!m) return null;
+  const days = m[1] ? parseInt(m[1], 10) : 0;
+  const hours = m[2] ? parseInt(m[2], 10) : 0;
+  const minutes = parseInt(m[3]!, 10);
+  const seconds = parseInt(m[4]!, 10);
+  if ([days, hours, minutes, seconds].some((n) => isNaN(n))) return null;
+  return days * 86400 + hours * 3600 + minutes * 60 + seconds;
+}
+
+/**
+ * Does this `process.kill(pid, 0)` failure mean the process is GONE?
+ *
+ * Only `ESRCH` does. `EPERM` (POSIX) and `EACCES` — which is what libuv surfaces
+ * on Windows when `OpenProcess` returns ERROR_ACCESS_DENIED — both mean the
+ * process EXISTS but is not ours to signal: another user on a shared host, a CI
+ * side-car, a different Windows session. Reporting those as dead lets a caller
+ * reclaim a live lock, run slot or leader out from under its owner, which is how
+ * two writers end up racing the state file. The orphan guard and the browser
+ * sweep already get this right; this is the same rule.
+ */
+function isDefinitelyGone(err: unknown): boolean {
+  const code = (err as NodeJS.ErrnoException | undefined)?.code;
+  if (code === 'EPERM' || code === 'EACCES') return false;
+  return true;
+}
+
 /**
  * Process Lifecycle Service
  *
@@ -22,6 +55,17 @@ export class ProcessLifecycleService implements IProcessLifecycle {
 
   private cachedStartTime: number | null = null;
 
+  // Short-TTL memo for SUBPROCESS-backed start-time lookups (macOS `ps`, Windows
+  // powershell — Linux reads /proc and stays uncached). A queued run-slot waiter
+  // sweeps every 250ms and builds a fresh FileLockService per attempt, so without
+  // a cross-attempt memo each live owner costs up to two `ps` spawns per sweep —
+  // ~48 subprocess spawns/second sustained on macOS while queued. A live PID's
+  // start time never changes; the only staleness is a PID recycled within the
+  // TTL reading as its dead predecessor, which merely delays a stale-owner steal
+  // by up to the TTL (well under every staleness threshold in use).
+  private static readonly START_TIME_TTL_MS = 5000;
+  private startTimeMemo = new Map<number, { value: number | null; at: number }>();
+
   async initialize(): Promise<void> {
     this.lifecycle = ServiceLifecycle.INITIALIZED;
   }
@@ -54,6 +98,18 @@ export class ProcessLifecycleService implements IProcessLifecycle {
       }
     }
 
+    const memoized = this.startTimeMemo.get(pid);
+    if (memoized && Date.now() - memoized.at < ProcessLifecycleService.START_TIME_TTL_MS) {
+      return memoized.value;
+    }
+    const memoize = (value: number | null): number | null => {
+      // Bound the map: sweeps interrogate a handful of owners; anything beyond a
+      // few hundred distinct PIDs inside one TTL window means leaked entries.
+      if (this.startTimeMemo.size > 256) this.startTimeMemo.clear();
+      this.startTimeMemo.set(pid, { value, at: Date.now() });
+      return value;
+    };
+
     // Windows: use powershell to get process creation time
     if (process.platform === 'win32') {
       try {
@@ -66,31 +122,59 @@ export class ProcessLifecycleService implements IProcessLifecycle {
           );
           child.unref?.();
         });
-        if (!output || !output.trim()) return null;
+        if (!output || !output.trim()) return memoize(null);
         const startTime = parseInt(output.trim(), 10);
-        return isNaN(startTime) ? null : startTime;
+        return memoize(isNaN(startTime) ? null : startTime);
       } catch {
-        return null;
+        return memoize(null);
       }
     }
 
-    // Cross-platform fallback (macOS/Unix): `ps -o etimes=` returns elapsed seconds.
-    try {
-      const output = await new Promise<string>((resolve, reject) => {
-        const child = execFile(
-          'ps', ['-o', 'etimes=', '-p', String(pid)],
-          { encoding: 'utf8', timeout: 3000 },
-          (err, stdout) => err ? reject(err) : resolve(stdout),
-        );
-        child.unref?.();
-      });
-      if (!output || !output.trim()) return null;
-      const elapsedSec = parseInt(output.trim(), 10);
-      if (isNaN(elapsedSec)) return null;
-      return Math.floor(Date.now() / 1000) - elapsedSec;
-    } catch {
-      return null;
+    // Cross-platform fallback (macOS/BSD): derive start time from elapsed time.
+    //
+    // `etimes` (elapsed WHOLE SECONDS) is a procps-ng/FreeBSD extension. Apple's
+    // ps (adv_cmds) does not implement it — it has only the POSIX `etime`
+    // ([[dd-]hh:]mm:ss). Asking for an unsupported keyword does not fail loudly:
+    // procps-ng writes an error to stderr and still exits 0 with EMPTY stdout,
+    // BSD ps exits non-zero. Both collapse to `null` here, which meant every
+    // PID+start-time guard on macOS silently degraded to a bare signal-0 check —
+    // the file lock, the run-slot semaphore, the GPU lock and both leader
+    // elections all advertise PID-reuse safety they were not actually getting.
+    //
+    // So: try `etimes`, and fall back to parsing POSIX `etime` when it yields
+    // nothing. `etime` is mandated by POSIX, so the fallback works everywhere.
+    const elapsedSec = await this.readElapsedSeconds(pid);
+    if (elapsedSec === null) return memoize(null);
+    return memoize(Math.floor(Date.now() / 1000) - elapsedSec);
+  }
+
+  /** Elapsed seconds for `pid` via ps, or null. Tries `etimes`, then POSIX `etime`. */
+  private async readElapsedSeconds(pid: number): Promise<number | null> {
+    const run = async (fmt: string): Promise<string | null> => {
+      try {
+        return await new Promise<string>((resolve, reject) => {
+          const child = execFile(
+            'ps', ['-o', fmt, '-p', String(pid)],
+            { encoding: 'utf8', timeout: 3000 },
+            (err, stdout) => err ? reject(err) : resolve(stdout),
+          );
+          child.unref?.();
+        });
+      } catch {
+        return null;
+      }
+    };
+
+    const etimes = await run('etimes=');
+    if (etimes && etimes.trim()) {
+      const n = parseInt(etimes.trim(), 10);
+      if (!isNaN(n)) return n;
     }
+
+    const etime = await run('etime=');
+    if (etime && etime.trim()) return parseEtime(etime.trim());
+
+    return null;
   }
 
   /**
@@ -111,11 +195,20 @@ export class ProcessLifecycleService implements IProcessLifecycle {
    * @returns true if process is alive (and matches start time if provided)
    */
   async isProcessAlive(pid: number, expectedStartTime?: number | null): Promise<boolean> {
+    // 1. EXISTENCE. Separate from identity (step 2) on purpose: a permission error
+    //    means the process exists but is not ours to signal, which must NOT
+    //    short-circuit the start-time comparison — a PID-reuse impostor owned by
+    //    another user would otherwise read as a live owner and deadlock the lock,
+    //    run slot or leadership it forged.
     try {
-      // 1. Basic liveness check via signal 0
       process.kill(pid, 0);
-      
-      // 2. If start time verification requested, check it
+    } catch (err) {
+      if (isDefinitelyGone(err)) return false;
+      // EPERM/EACCES: exists, not signalable by us — continue to the identity check.
+    }
+
+    try {
+      // 2. IDENTITY. If start time verification requested, check it.
       if (expectedStartTime !== undefined && expectedStartTime !== null) {
         const actualStartTime = await this.getProcessStartTime(pid);
         if (actualStartTime === null) {
@@ -132,14 +225,18 @@ export class ProcessLifecycleService implements IProcessLifecycle {
           // caller — a live lock/leader/run-cap owner is reclaimed from under it
           // → two writers collide (lost update) or the run-cap admits extra
           // concurrent runs (the flaky duplicate-slot/cap-breach we saw on Windows
-          // CI). So re-confirm liveness instead of guessing: if signal(0) STILL
-          // succeeds the process is alive → return true; if it now throws it died
-          // between the two probes and the outer catch returns false. A genuine
-          // death is therefore still detected within one poll tick (~100ms); the
-          // only behavioural change is that a confirmed-alive PID is never again
-          // misreported as dead on a transient start-time lookup failure.
-          process.kill(pid, 0); // re-confirm; a throw (process died) → outer catch → false
-          return true;
+          // CI). So re-confirm existence instead of guessing: if the PID is STILL
+          // there the process is alive → true; if it has gone it died between the
+          // two probes → false. A genuine death is therefore still detected within
+          // one poll tick (~100ms); the only behavioural change is that a
+          // confirmed-alive PID is never again misreported as dead on a transient
+          // start-time lookup failure.
+          try {
+            process.kill(pid, 0);
+            return true;
+          } catch (reconfirmErr) {
+            return !isDefinitelyGone(reconfirmErr);
+          }
         }
         // Allow ±1s slack. The macOS/BSD fallback derives start time as
         // floor(Date.now()/1000) - `ps etimes` (elapsed whole seconds); both terms are
@@ -149,10 +246,13 @@ export class ProcessLifecycleService implements IProcessLifecycle {
         // within a 1s window at the identical PID is not a realistic false-match.
         return Math.abs(actualStartTime - expectedStartTime) <= 1;
       }
-      
+
       return true;
     } catch {
-      return false;
+      // The start-time lookup itself blew up (not a signal error — those are
+      // handled above). Existence was already established, so treat it as alive:
+      // reclaiming a confirmed-present owner is the worse failure.
+      return true;
     }
   }
 
@@ -163,8 +263,8 @@ export class ProcessLifecycleService implements IProcessLifecycle {
     try {
       process.kill(pid, 0);
       return true;
-    } catch {
-      return false;
+    } catch (err) {
+      return !isDefinitelyGone(err);
     }
   }
 

package/src/infrastructure/research-run-semaphore.ts

@@ -195,7 +195,18 @@ export class ResearchRunSemaphore implements IService {
     try {
       await slot.initialize(); // resolves own startTime (cached) + startup stale cleanup
       await slot.acquireLock(); // try-take: wins, reclaims a dead owner, or throws fast
-    } catch {
+    } catch (err) {
+      // Contention and breakage are different outcomes and must not be conflated.
+      // FileLockService synthesizes its own Errors (no errno code) for the two
+      // contention shapes a try-take produces — a live-contended slot ("timeout
+      // after 0ms", cause EEXIST) and a lost reclaim race ("after N retries") —
+      // and those genuinely mean "slot busy". A real I/O failure (ENOENT/EACCES/
+      // ENOSPC: the slot file is uncreatable; both mkdirs are warn-only) instead
+      // propagates the raw errno error. Swallowing that as "busy" would poll out
+      // the whole acquire window and reject with a FALSE ResearchRunCapacityError,
+      // making the documented fail-open contract (research proceeds when the
+      // semaphore is broken) unreachable. Rethrow so acquire() can tell them apart.
+      if (typeof (err as NodeJS.ErrnoException | null)?.code === 'string') throw err;
       return null; // busy (live owner) or lost a reclaim race — try the next slot
     }
     return {
@@ -246,16 +257,39 @@ export class ResearchRunSemaphore implements IService {
       // Round-robin from a rotating start so contending processes don't synchronize on slot 0.
       const start = this.nextStartIndex;
       this.nextStartIndex = (this.nextStartIndex + 1) % this.maxSlots;
+      // Slot BREAKAGE (I/O error) is tracked separately from contention within
+      // this sweep — a broken slot must never be reported as a busy one.
+      let brokenSlots = 0;
+      let firstBreakage: unknown = null;
       for (let offset = 0; offset < this.maxSlots; offset++) {
         const i = (start + offset) % this.maxSlots;
-        const got = await this.trySlot(i);
+        let got: RunSlotAcquisition | null;
+        try {
+          got = await this.trySlot(i);
+        } catch (err) {
+          // This slot is broken, not busy. Keep sweeping — another slot may still
+          // be acquirable (mixed case: slot 0 uncreatable, slot 1 free).
+          brokenSlots++;
+          firstBreakage ??= err;
+          logger.debug(`[ResearchRunSemaphore] Slot ${i} errored (broken, not busy): ${err instanceof Error ? err.message : String(err)}`);
+          continue;
+        }
         if (got) {
           metrics.setGauge('research_run_slots_held', 1, { slot: String(i) });
           metrics.increment('research_run_acquire_total', 1, { status: 'acquired' });
           return got;
         }
       }
-      // Every slot is held by a live process.
+      // EVERY slot errored: the semaphore itself is broken, not at capacity.
+      // Waiting cannot help — nothing is held that could free up — and a
+      // ResearchRunCapacityError here would misclassify breakage as retryable
+      // contention while the caller's fail-open path (research proceeds without
+      // the cap) stays unreachable. Rethrow the I/O error instead.
+      if (brokenSlots === this.maxSlots) {
+        metrics.increment('research_run_acquire_total', 1, { status: 'error' });
+        throw firstBreakage;
+      }
+      // Every remaining slot is held by a live process.
       if (Date.now() >= deadline) {
         metrics.increment('research_run_acquire_total', 1, { status: 'exhausted' });
         throw new ResearchRunCapacityError(this.maxSlots, maxWaitMs);

package/src/infrastructure/state/state-backup-manager.ts

@@ -8,6 +8,7 @@ import * as fs from 'node:fs/promises';
 import * as crypto from 'node:crypto';
 import * as path from 'node:path';
 import { logger } from '../../logger.ts';
+import { replaceFile } from '../../utils/atomic-replace.ts';
 import type { IService } from '../../core/service-registry.ts';
 import { ServiceLifecycle } from '../../core/service-registry.ts';
 import { ServiceNames } from '../../core/interfaces/service-names.ts';
@@ -253,15 +254,12 @@ export class StateBackupManager implements IService {
       await fh.close();
     }
     try {
-      await fs.rename(tempPath, this.stateFilePath);
-    } catch (renameErr) {
-      if (process.platform === 'win32') {
-        await fs.copyFile(tempPath, this.stateFilePath);
-        await fs.unlink(tempPath).catch(() => { /* best-effort cleanup */ });
-      } else {
+      if (await replaceFile(tempPath, this.stateFilePath) === 'copied') {
         await fs.unlink(tempPath).catch(() => { /* best-effort cleanup */ });
-        throw renameErr;
       }
+    } catch (renameErr) {
+      await fs.unlink(tempPath).catch(() => { /* best-effort cleanup */ });
+      throw renameErr;
     }
   }
 

package/src/infrastructure/state/state-browser-api.ts

@@ -50,12 +50,15 @@ export class StateBrowserApi {
   /**
    * Clear the browser server information
    * @param updateState Function to update state atomically
+   * @param expected Optional expected-owner identity forwarded to the CAS check
+   *   in StateBrowserManager.clearBrowserServer.
    */
   async clearBrowserServer(
-    updateState: (updater: (state: SingletonState) => SingletonState | Promise<SingletonState>) => Promise<void>
+    updateState: (updater: (state: SingletonState) => SingletonState | Promise<SingletonState>) => Promise<void>,
+    expected?: { pid?: number; schedulerId?: string }
   ): Promise<void> {
     await updateState((state) => {
-      return this.browserManager.clearBrowserServer(state);
+      return this.browserManager.clearBrowserServer(state, expected);
     });
   }
 

package/src/infrastructure/state/state-browser-manager.ts

@@ -47,9 +47,23 @@ export class StateBrowserManager implements IService {
   /**
    * Clear the browser server information
    * @param state The current state
+   * @param expected Optional identity the caller believes is currently registered.
+   *   When supplied, this is a compare-and-delete: the entry is only removed if it
+   *   still matches (mirrors StateManager.clearEmbeddingServer). browserServer is
+   *   shared cross-process state, and an unconditional delete lets a caller who
+   *   decided the *previous* leader was dead deregister a DIFFERENT process's
+   *   fresh, live registration that claimed the slot in the meantime — that new
+   *   leader then runs undiscoverable (state shows no browserServer), so the next
+   *   getScheduler() caller elects a second, redundant leader. A mismatch means
+   *   someone else already claimed the slot, and the clear must no-op.
    * @returns Updated state without browser server info
    */
-  clearBrowserServer(state: SingletonState): SingletonState {
+  clearBrowserServer(state: SingletonState, expected?: { pid?: number; schedulerId?: string }): SingletonState {
+    const entry = state.browserServer;
+    if (entry && expected !== undefined) {
+      if (expected.schedulerId !== undefined && entry.schedulerId !== expected.schedulerId) return state;
+      if (expected.pid !== undefined && entry.pid !== expected.pid) return state;
+    }
     delete state.browserServer;
     return state;
   }

package/src/infrastructure/state/state-manager-service.ts

@@ -188,22 +188,22 @@ export class StateManagerService implements IStateManager {
   /**
    * Clear the browser server information
    */
-  async clearBrowserServer(): Promise<void> {
-    return this.getStateManager().clearBrowserServer();
+  async clearBrowserServer(expected?: { pid?: number; schedulerId?: string }): Promise<void> {
+    return this.getStateManager().clearBrowserServer(expected);
   }
 
   /**
    * Get the current embedding server information
    */
-  async getEmbeddingServer(): Promise<{ port: number; pid: number; startTime?: number; serverId: string; model?: string } | null> {
+  async getEmbeddingServer(): Promise<{ port: number; pid: number; startTime?: number; serverId: string; model?: string; authSecret?: string } | null> {
     return this.getStateManager().getEmbeddingServer();
   }
 
   /**
    * Clear the embedding server information
    */
-  async clearEmbeddingServer(): Promise<void> {
-    return this.getStateManager().clearEmbeddingServer();
+  async clearEmbeddingServer(expected?: { pid?: number; serverId?: string }): Promise<void> {
+    return this.getStateManager().clearEmbeddingServer(expected);
   }
 
   /**

package/src/infrastructure/state/state-manager.ts

@@ -23,6 +23,7 @@ import * as crypto from 'node:crypto';
 import process from 'node:process';
 import { getGlobalConfigDir } from '../../config.ts';
 import { logger } from '../../logger.ts';
+import { replaceFile } from '../../utils/atomic-replace.ts';
 import { metrics } from '../../utils/metrics.ts';
 import type { IProcessLifecycle } from '../../core/interfaces/process-interfaces.ts';
 import type {
@@ -350,25 +351,23 @@ export class StateManager {
       } finally {
         await fh.close();
       }
-      try {
-        await fs.rename(tempFilePath, this.stateFilePath);
-      } catch (renameErr) {
-        // fs.rename fails on Windows if target exists (NTFS). Fall back to copy+delete.
-        if (process.platform === 'win32') {
-          await fs.copyFile(tempFilePath, this.stateFilePath);
-          // copyFile succeeded → the state IS persisted. Make the temp-file removal
-          // best-effort: a transient AV lock on the temp would otherwise throw here and
-          // fall through to the catch below, reporting "Failed to write state" (status:
-          // error) for a write that actually succeeded — a caller that retries/aborts on
-          // the false failure would act wrongly.
-          const tmp = tempFilePath;
-          tempFilePath = null;
-          await fs.unlink(tmp).catch((err) => {
-            logger.warn('[StateManager] Failed to remove temp file after copy fallback (write succeeded):', err);
-          });
-        } else {
-          throw renameErr;
-        }
+      // Atomic where the platform allows; on Windows a third-party lock on the target
+      // is retried before conceding to a non-atomic copy (see replaceFile).
+      const outcome = await replaceFile(tempFilePath, this.stateFilePath);
+      if (outcome === 'copied') {
+        logger.warn(
+          '[StateManager] State written via non-atomic copy: the rename was blocked by another ' +
+          'process holding the state file. A concurrent reader may observe a partial file.',
+        );
+        metrics.increment('state_write_non_atomic_total', 1);
+        // The state IS persisted, so removing the temp is best-effort: a transient AV lock
+        // on the temp would otherwise throw and report "Failed to write state" for a write
+        // that actually succeeded — a caller retrying or aborting on that would act wrongly.
+        const tmp = tempFilePath;
+        tempFilePath = null;
+        await fs.unlink(tmp).catch((err) => {
+          logger.warn('[StateManager] Failed to remove temp file after copy fallback (write succeeded):', err);
+        });
       }
       tempFilePath = null;
       await this.backupManager.cleanupOldBackups();
@@ -447,19 +446,31 @@ export class StateManager {
     );
   }
 
-  public async clearBrowserServer(): Promise<void> {
-    await this.browserApi.clearBrowserServer(this.updateState.bind(this));
+  public async clearBrowserServer(expected?: { pid?: number; schedulerId?: string }): Promise<void> {
+    await this.browserApi.clearBrowserServer(this.updateState.bind(this), expected);
   }
 
   // ==================== Embedding Server API ====================
 
-  public async getEmbeddingServer(): Promise<{ port: number; pid: number; startTime?: number; serverId: string; model?: string } | null> {
+  public async getEmbeddingServer(): Promise<{ port: number; pid: number; startTime?: number; serverId: string; model?: string; authSecret?: string } | null> {
     const state = await this.readState();
     return state.embeddingServer ?? null;
   }
 
-  public async clearEmbeddingServer(): Promise<void> {
+  public async clearEmbeddingServer(expected?: { pid?: number; serverId?: string }): Promise<void> {
     await this.updateState((state) => {
+      // Compare-and-delete: the registration is shared cross-process state, and an
+      // unconditional delete lets a follower's shutdown (or a waiter acting on a
+      // stale snapshot) deregister a DIFFERENT process's live leader — which then
+      // never re-registers (its leadership check treats an absent entry as benign),
+      // so a fresh caller elects a second GPU model instance alongside the invisible
+      // one. Callers pass the identity they believe they are clearing; a mismatch
+      // means someone else already claimed the slot, and the clear must no-op.
+      const entry = state.embeddingServer;
+      if (entry && expected !== undefined) {
+        if (expected.serverId !== undefined && entry.serverId !== expected.serverId) return state;
+        if (expected.pid !== undefined && entry.pid !== expected.pid) return state;
+      }
       delete state.embeddingServer;
       return state;
     });

package/src/infrastructure/types/state-types.ts

@@ -79,6 +79,15 @@ export const SingletonStateSchema = Type.Object({
     // in-process embedder instead. Optional for entries written by older
     // processes, which are tolerated as matching.
     model: Type.Optional(Type.String()),
+    // Shared secret a follower must present on every embed request. Mirrors
+    // browserServer.authSecret: the server listens on loopback, but loopback is
+    // not an authorization boundary — any local process could otherwise enqueue
+    // embedding work, and because the serial queue steps the leader down when
+    // poisoned, sustained abuse denies the knowledge store rather than merely
+    // burning GPU. Optional so an entry written by an older leader still parses;
+    // a client that finds none simply sends no header, and such a leader does not
+    // check one either.
+    authSecret: Type.Optional(Type.String()),
   })),
 });
 

package/src/knowledge/chunker.ts

@@ -42,6 +42,7 @@ export class Chunker {
     let spaceExtensions = 0;
 
     while (start < text.length) {
+      const iterationStart = start;
       let end = start + this.targetSize;
       
       if (end < text.length) {
@@ -118,6 +119,55 @@ export class Chunker {
 
       if (end <= start) end = Math.min(start + this.targetSize, text.length);
 
+      // Forward-progress invariant: every chunk after the first must end past the
+      // previous chunk's end. When the overlap step plants `start` inside a code
+      // block whose closing fence terminated the PREVIOUS chunk, the in-block
+      // re-extension above clamps `end` back onto that same fence — a chunk that
+      // re-covers only overlap content, and (via the 1-char anti-regression step
+      // below) one such sliver per character until `start` clears the fence.
+      // Covering fresh text is worth splitting the fence: the previous chunk
+      // already carries the block's tail intact.
+      if (chunks.length > 0 && end <= prevEnd) {
+        end = Math.min(start + this.targetSize, text.length);
+      }
+
+      // UTF-16 surrogate-pair safety: `end` is a raw code-unit index, and every
+      // adjustment above (code-block/heading/sentence/newline/space, plus the
+      // forward-progress guard) operates purely in code-unit space — none of
+      // them are aware of astral characters (emoji, rare CJK Extension B+),
+      // which are a HIGH surrogate (0xD800-0xDBFF) followed by a LOW surrogate
+      // (0xDC00-0xDFFF). If `end` lands between the two halves, slicing here
+      // emits a lone high surrogate. Node's UTF-16->UTF-8 conversion (JSON
+      // serialization, HTTP bodies, N-API marshalling into the LanceDB/Arrow
+      // layer) silently substitutes U+FFFD for that rather than throwing —
+      // silent corruption of text that gets embedded and stored. Mirrors the
+      // backoff in truncateWithMarker (src/utils/text-utils.ts). Applied last,
+      // right before the slice, and only shrinks `end` when doing so can't
+      // undo the forward-progress guard just above or produce an empty chunk.
+      if (end < text.length) {
+        const code = text.charCodeAt(end - 1);
+        if (code >= 0xd800 && code <= 0xdbff) {
+          const candidate = end - 1;
+          const staysPastPrev = chunks.length === 0 || candidate > prevEnd;
+          if (candidate > start && staysPastPrev) {
+            end = candidate;
+          } else {
+            // Backing off would violate the forward-progress guard above (or empty
+            // the chunk) — this happens when targetSize and overlap sit within one
+            // code unit of each other. Grow past the low surrogate instead: taking
+            // the full pair into THIS chunk only ever increases `end`, so it can
+            // never re-collide with the guard it just failed, and it still avoids
+            // splitting the pair (the alternative — leaving `end` right after the
+            // lone high surrogate — is the silent corruption this block exists to
+            // prevent).
+            const low = text.charCodeAt(end);
+            if (low >= 0xdc00 && low <= 0xdfff) {
+              end = Math.min(end + 1, text.length);
+            }
+          }
+        }
+      }
+
       const chunkText = text.slice(start, end);
       const actual_overlap = chunks.length === 0 ? 0 : Math.max(0, Math.min(chunkText.length, prevEnd - start));
       
@@ -131,7 +181,44 @@ export class Chunker {
         start = end - Math.min(this.overlap, chunkText.length - 1);
       }
       if (start < 0) start = 0;
-      if (start >= end) start = end - 1; 
+      if (start >= end) start = end - 1;
+
+      // Forward-progress invariant, start side: the constructor rejects
+      // overlap >= targetSize specifically "to prevent infinite loops," but that
+      // guarantee only holds for the raw arithmetic above — it says nothing about
+      // the end-side forward-progress guard earlier in this loop reusing the same
+      // `end` two iterations in a row, which can leave `start` no greater than the
+      // value this same iteration started with, reproducing an identical chunk
+      // forever (observed: OOM from an unbounded chunks array on a small
+      // targetSize/overlap gap plus a boundary emoji). Guarantee real progress
+      // independent of every heuristic above, mirroring the `end`-side guard.
+      // Applied BEFORE the surrogate-pair check below so that check always
+      // adjusts an already-safe value instead of being able to undo this guard.
+      if (start <= iterationStart) start = iterationStart + 1;
+
+      // Surrogate-pair safety, read side: `start` (end - overlap, further
+      // clamped above) is an independent raw code-unit index — it is not
+      // derived from any of the textual heuristics that picked `end` above,
+      // so the fix to `end` does not cover it. It can separately bisect an
+      // unrelated pair and produce a next chunk that OPENS with a lone low
+      // surrogate. The pair's high half is already inside the chunk just
+      // pushed (it sits before `end`), so pulling `start` back one unit only
+      // widens that chunk's overlap by one code unit — it never drops text.
+      // Only pull back when doing so keeps the forward-progress guard above
+      // satisfied; otherwise push forward past the low surrogate instead — the
+      // pair's high half is guaranteed already present in the chunk just
+      // pushed, so skipping the low half here loses nothing, it just narrows
+      // this chunk's overlap by one code unit instead of widening it.
+      if (start > 0) {
+        const code = text.charCodeAt(start);
+        if (code >= 0xdc00 && code <= 0xdfff) {
+          if (start - 1 > iterationStart) {
+            start -= 1;
+          } else if (start + 1 < end) {
+            start += 1;
+          }
+        }
+      }
     }
 
     const duration = Date.now() - startTime;

package/src/knowledge/embedder-init.ts

@@ -252,7 +252,7 @@ export async function purgeModelCache(model: string): Promise<void> {
       logger.warn(`[embedder] Refusing to purge unsafe model-cache path for model id ${JSON.stringify(model)}`);
       return;
     }
-    await rm(modelDir, { recursive: true, force: true });
+    await rm(modelDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
     logger.warn(`[embedder] Purged corrupt model cache at ${modelDir}`);
   } catch (err) {
     logger.warn('[embedder] Failed to purge model cache:', err);