From 4f202ebefa0d10958c460bebc1bb642b902b4d86 Mon Sep 17 00:00:00 2001
From: lcy <admin@luchenyang.xyz>
Date: Tue, 22 Sep 2026 15:23:50 +0800
Subject: [PATCH 1/2] fix: run profile learning from any active instance under
 a cross-process lock
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Profile learning was gated on `webServer?.isServerOwner()`. Ownership tracks
whichever process bound the web-server port first and is only handed over when
that process becomes unreachable (web-server.ts:290) — it does not track which
instance the user is actually working in. Two consequences:

- With `webServerEnabled: false` there is no server and therefore no owner, so
  `webServer` stays null (index.ts:244) and automatic profile learning never
  ran at all.
- When the owner stays healthy but stops receiving sessions while another
  project is active, the prompt queue stalls indefinitely. Learning is
  scheduled from a `session.idle` event, and the health check only takes over
  ownership when the server is unreachable, so nothing hands the work over.

Any active instance may now learn. Retention cleanup stays owner-only, since it
is storage-wide maintenance with no reason to run once per instance.

Allowing concurrent learners requires real mutual exclusion. `isLearningRunning`
is a module-level boolean and only prevents re-entry within one process, while
prompt selection is a plain SELECT (user-prompt-manager.ts:270) whose batch is
marked only after the LLM responds. Without cross-process exclusion two
instances would analyze the same prompts and the slower writer would clobber the
faster one's profile update — `updateProfile` re-reads the current version at
write time, so its optimistic check does not detect a concurrent update that
landed while the LLM was running.

This adds a dedicated lock keyed to the shared storage path, held across the
whole learning flow. It deliberately does not reuse `.turso-operation.lock`:
that lock makes `assertNoTursoMigrationInProgress` reject ordinary memory
writes. Contention skips the round rather than waiting, because the next idle
event retries.

The lock also respects a write window before reclaiming an unparseable lock
file. `writeFileSync` is not atomic, so a reader can observe a file that was
created but not yet filled in; reclaiming it on sight would hand the lock to a
second process while the first believes it holds it.

Cold-buffer staleness had to be addressed for the same reason. The buffer is
read once per process and `saveColdBuffers` rewrites the whole file from that
in-memory map, so a process holding a stale map would erase entries a peer
persisted. The manager now reloads it when the file's mtime changes, keeping
the requirement inside the manager rather than relying on callers.

Tests run the real plugin in an isolated process (following
compaction-agent-preservation.test.ts) instead of string-slicing the handler out
of the transpiled source, and the lock is covered by two genuinely concurrent
processes synchronised on a start barrier. Both were verified to fail when the
corresponding protection is removed.
---
 src/index.ts                                  |  11 +-
 src/services/user-memory-learning.ts          |  14 +
 src/services/user-profile/learning-lock.ts    | 160 ++++++++++
 .../user-profile/user-profile-manager.ts      |  29 +-
 tests/profile-learning-idle.test.ts           | 209 +++++++++++++
 tests/profile-learning-lock.test.ts           | 280 ++++++++++++++++++
 6 files changed, 701 insertions(+), 2 deletions(-)
 create mode 100644 src/services/user-profile/learning-lock.ts
 create mode 100644 tests/profile-learning-idle.test.ts
 create mode 100644 tests/profile-learning-lock.test.ts

diff --git a/src/index.ts b/src/index.ts
index 5b56c708..854fc933 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -955,8 +955,17 @@ export const OpenCodeMemPlugin: Plugin = async (ctx: PluginInput) => {
           try {
             await performAutoCapture(ctx, sessionID, directory);
 
+            // Prompts are shared across projects, but web-server ownership tracks
+            // whoever bound the port first and is never handed over while that
+            // process stays reachable. Gating learning on it stalls the queue
+            // whenever the owner stops seeing sessions, and disables learning
+            // outright when the web server is off. Any active instance may learn;
+            // performUserProfileLearning holds a cross-process lock internally.
+            await performUserProfileLearning(ctx, directory);
+
+            // Retention cleanup stays owner-only: it is storage-wide maintenance
+            // that has no reason to run once per active instance.
             if (webServer?.isServerOwner()) {
-              await performUserProfileLearning(ctx, directory);
               const { cleanupService } = await import("./services/cleanup-service.js");
               if (await cleanupService.shouldRunCleanup()) await cleanupService.runCleanup();
             }
diff --git a/src/services/user-memory-learning.ts b/src/services/user-memory-learning.ts
index d09ac081..a1dc9f5e 100644
--- a/src/services/user-memory-learning.ts
+++ b/src/services/user-memory-learning.ts
@@ -8,6 +8,7 @@ import { userProfileManager } from "./user-profile/user-profile-manager.js";
 import { sortProfileItems } from "../utils/profile.js";
 import type { UserProfile, UserProfileData } from "./user-profile/types.js";
 import { loadOpencodeProvider } from "./ai/opencode-provider-loader.js";
+import { tryAcquireProfileLearningLock } from "./user-profile/learning-lock.js";
 
 let isLearningRunning = false;
 
@@ -66,6 +67,18 @@ export async function performUserProfileLearning(
     });
     return;
   }
+
+  // `isLearningRunning` only guards re-entry inside one process. Prompt selection
+  // is a plain SELECT and the batch is marked only after the LLM responds, so
+  // without cross-process exclusion two instances sharing this storage would
+  // analyze the same prompts and the slower writer would clobber the faster
+  // one's profile update. Contention skips this round; the next idle retries.
+  const releaseLearningLock = tryAcquireProfileLearningLock(directory);
+  if (!releaseLearningLock) {
+    log("user-profile-learning: skipped (another process holds the learning lock)");
+    return;
+  }
+
   isLearningRunning = true;
   try {
     const count = await userPromptManager.countUnanalyzedForUserLearning();
@@ -291,6 +304,7 @@ Rules:
     throw error;
   } finally {
     isLearningRunning = false;
+    releaseLearningLock();
   }
 }
 
diff --git a/src/services/user-profile/learning-lock.ts b/src/services/user-profile/learning-lock.ts
new file mode 100644
index 00000000..225bc2d3
--- /dev/null
+++ b/src/services/user-profile/learning-lock.ts
@@ -0,0 +1,160 @@
+import { mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG } from "../../config.js";
+import { log } from "../logger.js";
+
+const LEARNING_LOCK = ".profile-learning.lock";
+
+/**
+ * Upper bound on how long a lock may be held before other processes treat it as
+ * abandoned. Profile learning issues LLM requests, so this has to exceed a slow
+ * provider round trip; it only matters when a holder dies without releasing and
+ * its PID has already been reused by an unrelated process.
+ */
+const STALE_LOCK_MS = 30 * 60 * 1000;
+
+/**
+ * Grace period during which a lock file whose contents cannot be parsed is left
+ * alone. `writeFileSync` is not atomic, so a reader can observe a file that was
+ * created but not yet filled in. Deleting it on sight would hand the lock to a
+ * second process while the first believes it holds it.
+ */
+const WRITE_WINDOW_MS = 5_000;
+
+interface LearningLockState {
+  pid: number;
+  acquiredAt: number;
+  directory: string;
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function lockPath(): string {
+  return join(CONFIG.storagePath || "", LEARNING_LOCK);
+}
+
+function removeLock(path: string): void {
+  try {
+    unlinkSync(path);
+  } catch {
+    // Already gone (lost the cleanup race) or held open by the OS. Either way
+    // this process does not own it, so surface nothing.
+  }
+}
+
+/**
+ * Returns the state of a lock that is still held, or null when no live holder
+ * remains. A stale lock is removed as a side effect so the caller can retry.
+ */
+function readLiveLock(path: string): LearningLockState | null {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+
+  let state: LearningLockState;
+  try {
+    state = JSON.parse(raw) as LearningLockState;
+  } catch {
+    // Unparseable: either mid-write by a live acquirer, or genuinely corrupt.
+    // Respect the write window before reclaiming so we never steal a lock that
+    // another process is in the middle of taking.
+    let mtimeMs: number;
+    try {
+      mtimeMs = statSync(path).mtimeMs;
+    } catch {
+      return null;
+    }
+    if (Date.now() - mtimeMs < WRITE_WINDOW_MS) {
+      return { pid: -1, acquiredAt: mtimeMs, directory: "<initializing>" };
+    }
+    removeLock(path);
+    return null;
+  }
+
+  if (!Number.isInteger(state.pid) || state.pid <= 0) {
+    removeLock(path);
+    return null;
+  }
+
+  if (state.pid !== process.pid && !isProcessAlive(state.pid)) {
+    log("profile-learning lock: reclaiming lock from dead holder", { pid: state.pid });
+    removeLock(path);
+    return null;
+  }
+
+  const age = Date.now() - (state.acquiredAt ?? 0);
+  if (Number.isFinite(age) && age > STALE_LOCK_MS) {
+    log("profile-learning lock: reclaiming expired lock", { pid: state.pid, ageMs: age });
+    removeLock(path);
+    return null;
+  }
+
+  return state;
+}
+
+/**
+ * Serializes profile learning across every process sharing this storage path.
+ *
+ * Profile learning selects a batch of prompts with a plain SELECT, issues an LLM
+ * request, then writes the profile and marks the batch. None of that is atomic,
+ * so two processes running it concurrently would analyze the same prompts twice
+ * and the slower writer would clobber the faster one's profile update.
+ *
+ * Returns a release function, or null when another process holds the lock — in
+ * which case the caller must skip this round rather than wait, because the next
+ * idle event will retry.
+ */
+export function tryAcquireProfileLearningLock(directory: string): (() => void) | null {
+  const path = lockPath();
+
+  try {
+    mkdirSync(CONFIG.storagePath || "", { recursive: true });
+  } catch {
+    // Storage path already exists, or cannot be created — the write below fails
+    // loudly enough on its own.
+  }
+
+  const holder = readLiveLock(path);
+  if (holder) return null;
+
+  const state: LearningLockState = {
+    pid: process.pid,
+    acquiredAt: Date.now(),
+    directory,
+  };
+
+  try {
+    writeFileSync(path, JSON.stringify(state), { flag: "wx" });
+  } catch {
+    // Lost the race: another process created the file between our check and
+    // write. `wx` is what makes that detectable rather than silently shared.
+    return null;
+  }
+
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    try {
+      const current = JSON.parse(readFileSync(path, "utf-8")) as LearningLockState;
+      if (current.pid !== process.pid) return;
+    } catch {
+      return;
+    }
+    removeLock(path);
+  };
+}
+
+export function isProfileLearningLockHeld(): boolean {
+  return readLiveLock(lockPath()) !== null;
+}
diff --git a/src/services/user-profile/user-profile-manager.ts b/src/services/user-profile/user-profile-manager.ts
index 1a4232d4..91377467 100644
--- a/src/services/user-profile/user-profile-manager.ts
+++ b/src/services/user-profile/user-profile-manager.ts
@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { tursoConnectionManager } from "../turso/connection-manager.js";
 import type { TursoDb } from "../turso/turso-db.js";
 import { CONFIG } from "../../config.js";
@@ -78,6 +78,7 @@ export class UserProfileManager {
   // (COLD_BUFFER_DEFAULT_KEY) only holds items from merges that ran without a profileId.
   private coldBuffers: Map<string, { preferences: any[]; patterns: any[]; workflows: any[] }>;
   private coldBufferPath: string;
+  private coldBufferMtimeMs: number | null = null;
   private dedupCheckedCache: Set<string> = new Set();
 
   constructor() {
@@ -133,11 +134,34 @@ export class UserProfileManager {
     return { preferences: [], patterns: [], workflows: [] };
   }
 
+  /**
+   * Discards the cached cold buffer when another process has rewritten the file.
+   *
+   * The buffer is read once in the constructor and `saveColdBuffers` rewrites the
+   * whole file from this in-memory map. Now that more than one process can run
+   * profile learning, a process holding a stale map would erase entries a peer
+   * persisted in the meantime. Comparing the file's mtime keeps that correctness
+   * requirement inside the manager instead of relying on every caller to refresh.
+   */
+  private refreshColdBuffersIfChanged(): void {
+    let mtimeMs: number;
+    try {
+      mtimeMs = statSync(this.coldBufferPath).mtimeMs;
+    } catch {
+      // No file yet (or unreadable): nothing on disk can be newer than our map.
+      return;
+    }
+    if (this.coldBufferMtimeMs !== null && mtimeMs <= this.coldBufferMtimeMs) return;
+    this.coldBuffers = this.loadColdBuffers();
+    this.coldBufferMtimeMs = mtimeMs;
+  }
+
   private getColdBuffer(profileId?: string): {
     preferences: any[];
     patterns: any[];
     workflows: any[];
   } {
+    this.refreshColdBuffersIfChanged();
     const key = profileId || COLD_BUFFER_DEFAULT_KEY;
     let buf = this.coldBuffers.get(key);
     if (!buf) {
@@ -196,6 +220,9 @@ export class UserProfileManager {
         }
       }
       writeFileSync(this.coldBufferPath, JSON.stringify(obj), "utf-8");
+      // Record our own write so the next read does not mistake it for a peer's
+      // update and reload the map we just persisted.
+      this.coldBufferMtimeMs = statSync(this.coldBufferPath).mtimeMs;
     } catch {
       // Silently ignore disk-full / permission errors.
     }
diff --git a/tests/profile-learning-idle.test.ts b/tests/profile-learning-idle.test.ts
new file mode 100644
index 00000000..97d39a17
--- /dev/null
+++ b/tests/profile-learning-idle.test.ts
@@ -0,0 +1,209 @@
+import { afterAll, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const tempDirs: string[] = [];
+
+afterAll(() => {
+  for (const dir of tempDirs) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // Best-effort cleanup.
+    }
+  }
+});
+
+const indexUrl = new URL("../src/index.js", import.meta.url).href;
+const clientUrl = new URL("../src/services/client.js", import.meta.url).href;
+const configUrl = new URL("../src/config.js", import.meta.url).href;
+const tagsUrl = new URL("../src/services/tags.js", import.meta.url).href;
+const contextUrl = new URL("../src/services/context.js", import.meta.url).href;
+const privacyUrl = new URL("../src/services/privacy.js", import.meta.url).href;
+const autoCaptureUrl = new URL("../src/services/auto-capture.js", import.meta.url).href;
+const learningUrl = new URL("../src/services/user-memory-learning.js", import.meta.url).href;
+const cleanupUrl = new URL("../src/services/cleanup-service.js", import.meta.url).href;
+const promptManagerUrl = new URL(
+  "../src/services/user-prompt/user-prompt-manager.js",
+  import.meta.url
+).href;
+const webServerUrl = new URL("../src/services/web-server.js", import.meta.url).href;
+const loggerUrl = new URL("../src/services/logger.js", import.meta.url).href;
+const languageUrl = new URL("../src/services/language-detector.js", import.meta.url).href;
+const tursoReadyUrl = new URL("../src/services/turso/ready.js", import.meta.url).href;
+
+/**
+ * Drives the real plugin's `session.idle` handler in an isolated Bun process so
+ * the module mocks below cannot leak into sibling test files, then reports which
+ * background jobs the handler actually invoked.
+ */
+function runIdleScenario(opts: {
+  owner?: boolean;
+  webServerEnabled?: boolean;
+  internalSession?: boolean;
+  autoCaptureEnabled?: boolean;
+}) {
+  const owner = opts.owner ?? false;
+  const webServerEnabled = opts.webServerEnabled ?? true;
+  const internalSession = opts.internalSession ?? false;
+  const autoCaptureEnabled = opts.autoCaptureEnabled ?? true;
+
+  const dir = mkdtempSync(join(tmpdir(), "opencode-mem-profile-idle-"));
+  tempDirs.push(dir);
+  const scriptPath = join(dir, "scenario.mjs");
+
+  const script = `
+import { mock } from "bun:test";
+
+const calls = [];
+
+mock.module(${JSON.stringify(clientUrl)}, () => ({
+  memoryClient: {
+    warmup: async () => {},
+    isReady: async () => true,
+    close() {},
+  },
+}));
+
+mock.module(${JSON.stringify(configUrl)}, () => ({
+  CONFIG: {
+    autoCaptureEnabled: ${autoCaptureEnabled},
+    compaction: { enabled: false, memoryLimit: 10 },
+    chatMessage: { enabled: false },
+    webServerEnabled: ${webServerEnabled},
+    storagePath: ${JSON.stringify(dir)},
+    autoCaptureProviderStatus: { ready: true, issues: [] },
+  },
+  initConfig: () => {},
+  isConfigured: () => true,
+}));
+
+mock.module(${JSON.stringify(tagsUrl)}, () => ({
+  getTags: () => ({ project: { tag: "project-tag" }, user: { userEmail: "u@example.com" } }),
+}));
+mock.module(${JSON.stringify(contextUrl)}, () => ({ formatContextForPrompt: () => "" }));
+mock.module(${JSON.stringify(privacyUrl)}, () => ({
+  stripPrivateContent: (value) => value,
+  isFullyPrivate: () => false,
+}));
+mock.module(${JSON.stringify(promptManagerUrl)}, () => ({ userPromptManager: { savePrompt() {} } }));
+mock.module(${JSON.stringify(loggerUrl)}, () => ({ log: () => {} }));
+mock.module(${JSON.stringify(languageUrl)}, () => ({ getLanguageName: () => "English" }));
+// The web server only starts once the Turso readiness gate passes, and that
+// gate is what decides whether an owner exists at all.
+mock.module(${JSON.stringify(tursoReadyUrl)}, () => ({ ensureTursoReady: async () => {} }));
+// The internal-capture check lives inside src/index.ts and resolves the session
+// title through the client, so drive it the real way: report the reserved title.
+const INTERNAL_TITLE = "opencode-mem capture";
+
+mock.module(${JSON.stringify(autoCaptureUrl)}, () => ({
+  performAutoCapture: async () => { calls.push("capture"); },
+}));
+mock.module(${JSON.stringify(learningUrl)}, () => ({
+  performUserProfileLearning: async () => { calls.push("learn"); },
+}));
+mock.module(${JSON.stringify(cleanupUrl)}, () => ({
+  cleanupService: {
+    shouldRunCleanup: async () => true,
+    runCleanup: async () => { calls.push("cleanup"); },
+  },
+}));
+
+mock.module(${JSON.stringify(webServerUrl)}, () => ({
+  startWebServer: async () => (${webServerEnabled}
+    ? {
+        isServerOwner: () => ${owner},
+        getUrl: () => "http://127.0.0.1:4747",
+        setOnTakeoverCallback: () => {},
+        stop: async () => {},
+      }
+    : null),
+  WebServer: class {},
+}));
+
+const mockClient = {
+  session: {
+    get: async () => ({ data: ${internalSession} ? { title: INTERNAL_TITLE } : { title: "regular work" } }),
+    messages: async () => ({ data: [] }),
+  },
+  tui: { showToast: async () => ({}) },
+};
+
+const { OpenCodeMemPlugin } = await import(${JSON.stringify(indexUrl)});
+const plugin = await OpenCodeMemPlugin({ directory: "/active-project", client: mockClient });
+
+// Let the plugin's async web-server bootstrap settle before the idle event, so
+// ownership is resolved the same way it is at runtime.
+await new Promise((resolve) => setTimeout(resolve, 50));
+
+await plugin.event({
+  event: { type: "session.idle", properties: { sessionID: "user-session" } },
+});
+
+// The handler debounces idle work behind a 10s timer.
+await new Promise((resolve) => setTimeout(resolve, 10_600));
+
+console.log(JSON.stringify({ calls }));
+`;
+
+  writeFileSync(scriptPath, script);
+  const result = Bun.spawnSync({
+    cmd: [process.execPath, scriptPath],
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const stdout = Buffer.from(result.stdout).toString("utf8").trim();
+  return {
+    exitCode: result.exitCode,
+    stderr: Buffer.from(result.stderr).toString("utf8").trim(),
+    calls: stdout ? (JSON.parse(stdout).calls as string[]) : null,
+  };
+}
+
+describe("profile learning trigger on session.idle", () => {
+  it("learns from an active instance that does not own the web server", () => {
+    const result = runIdleScenario({ owner: false });
+
+    expect([result.exitCode, result.stderr]).toEqual([0, ""]);
+    expect(result.calls).toEqual(["capture", "learn"]);
+  }, 30_000);
+
+  it("learns when the web server is disabled entirely", () => {
+    // Regression guard: with no web server there is no owner at all, so gating
+    // learning on ownership disabled profile learning permanently.
+    const result = runIdleScenario({ webServerEnabled: false });
+
+    expect([result.exitCode, result.stderr]).toEqual([0, ""]);
+    expect(result.calls).toEqual(["capture", "learn"]);
+  }, 30_000);
+
+  it("keeps retention cleanup owner-only", () => {
+    const result = runIdleScenario({ owner: true });
+
+    expect([result.exitCode, result.stderr]).toEqual([0, ""]);
+    expect(result.calls).toEqual(["capture", "learn", "cleanup"]);
+  }, 30_000);
+
+  it("runs no cleanup on a non-owner", () => {
+    const result = runIdleScenario({ owner: false });
+
+    expect([result.exitCode, result.stderr]).toEqual([0, ""]);
+    expect(result.calls).not.toContain("cleanup");
+  }, 30_000);
+
+  it("skips the plugin's own internal capture sessions", () => {
+    const result = runIdleScenario({ internalSession: true });
+
+    expect([result.exitCode, result.stderr]).toEqual([0, ""]);
+    expect(result.calls).toEqual([]);
+  }, 30_000);
+
+  it("does nothing when auto-capture is disabled", () => {
+    const result = runIdleScenario({ autoCaptureEnabled: false });
+
+    expect([result.exitCode, result.stderr]).toEqual([0, ""]);
+    expect(result.calls).toEqual([]);
+  }, 30_000);
+});
diff --git a/tests/profile-learning-lock.test.ts b/tests/profile-learning-lock.test.ts
new file mode 100644
index 00000000..ca717755
--- /dev/null
+++ b/tests/profile-learning-lock.test.ts
@@ -0,0 +1,280 @@
+import { afterAll, describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const tempDirs: string[] = [];
+
+afterAll(() => {
+  for (const dir of tempDirs) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // Best-effort cleanup.
+    }
+  }
+});
+
+const lockUrl = new URL("../src/services/user-profile/learning-lock.js", import.meta.url).href;
+const configUrl = new URL("../src/config.js", import.meta.url).href;
+const loggerUrl = new URL("../src/services/logger.js", import.meta.url).href;
+
+const LOCK_FILE = ".profile-learning.lock";
+
+function storage(): string {
+  const dir = mkdtempSync(join(tmpdir(), "opencode-mem-learning-lock-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function preamble(storagePath: string): string {
+  return `
+import { mock } from "bun:test";
+mock.module(${JSON.stringify(configUrl)}, () => ({
+  CONFIG: { storagePath: ${JSON.stringify(storagePath)} },
+  initConfig: () => {},
+  isConfigured: () => true,
+}));
+mock.module(${JSON.stringify(loggerUrl)}, () => ({ log: () => {} }));
+const lock = await import(${JSON.stringify(lockUrl)});
+`;
+}
+
+function runScript(dir: string, name: string, body: string) {
+  const scriptPath = join(dir, name);
+  writeFileSync(scriptPath, body);
+  const result = Bun.spawnSync({
+    cmd: [process.execPath, scriptPath],
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const stdout = Buffer.from(result.stdout).toString("utf8").trim();
+  return {
+    exitCode: result.exitCode,
+    stderr: Buffer.from(result.stderr).toString("utf8").trim(),
+    stdout,
+    parsed: stdout ? JSON.parse(stdout) : null,
+  };
+}
+
+/**
+ * Spawns two real processes that contend for the lock at the same time.
+ *
+ * Both wait on a shared start barrier before acquiring, so the acquisitions
+ * genuinely overlap. Running two promises in one process would only exercise the
+ * in-process guard and would pass even with no cross-process lock at all.
+ */
+function runContention(storagePath: string, barrierPath: string) {
+  const worker = (label: string) => `
+${preamble(storagePath)}
+import { existsSync, writeFileSync, readFileSync } from "node:fs";
+
+writeFileSync(${JSON.stringify(barrierPath)} + ".${label}", "ready");
+const peers = ["a", "b"].map((p) => ${JSON.stringify(barrierPath)} + "." + p);
+const deadline = Date.now() + 10_000;
+while (Date.now() < deadline && !peers.every((p) => existsSync(p))) {
+  await new Promise((r) => setTimeout(r, 5));
+}
+
+const release = lock.tryAcquireProfileLearningLock("/project-${label}");
+if (release) {
+  // Hold the lock long enough that the peer's attempt provably overlaps.
+  await new Promise((r) => setTimeout(r, 600));
+  release();
+}
+console.log(JSON.stringify({ acquired: release !== null }));
+`;
+
+  const dir = storagePath;
+  writeFileSync(join(dir, "worker-a.mjs"), worker("a"));
+  writeFileSync(join(dir, "worker-b.mjs"), worker("b"));
+
+  const spawn = (file: string) =>
+    Bun.spawn({
+      cmd: [process.execPath, join(dir, file)],
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+  const a = spawn("worker-a.mjs");
+  const b = spawn("worker-b.mjs");
+  return Promise.all(
+    [a, b].map(async (proc) => {
+      const out = (await new Response(proc.stdout).text()).trim();
+      await proc.exited;
+      return out ? (JSON.parse(out) as { acquired: boolean }) : null;
+    })
+  );
+}
+
+describe("cross-process profile learning lock", () => {
+  it("grants the lock to exactly one of two concurrent processes", async () => {
+    const dir = storage();
+    const results = await runContention(dir, join(dir, "barrier"));
+
+    const granted = results.filter((r) => r?.acquired).length;
+    expect(results).toHaveLength(2);
+    expect(granted).toBe(1);
+  }, 45_000);
+
+  it("releases the lock so a later process can acquire it", () => {
+    const dir = storage();
+
+    const first = runScript(
+      dir,
+      "acquire-release.mjs",
+      `
+${preamble(dir)}
+const release = lock.tryAcquireProfileLearningLock("/project-a");
+release?.();
+const second = lock.tryAcquireProfileLearningLock("/project-a");
+console.log(JSON.stringify({ first: release !== null, second: second !== null }));
+second?.();
+`
+    );
+
+    expect(first.exitCode).toBe(0);
+    expect(first.parsed).toEqual({ first: true, second: true });
+    expect(existsSync(join(dir, LOCK_FILE))).toBe(false);
+  }, 20_000);
+
+  it("reclaims a lock whose holder process no longer exists", () => {
+    const dir = storage();
+    // PID 2^22 is above every Linux/macOS pid_max default, so it cannot be live.
+    writeFileSync(
+      join(dir, LOCK_FILE),
+      JSON.stringify({ pid: 4194304, acquiredAt: Date.now(), directory: "/dead" })
+    );
+
+    const result = runScript(
+      dir,
+      "reclaim-dead.mjs",
+      `
+${preamble(dir)}
+const release = lock.tryAcquireProfileLearningLock("/project-a");
+console.log(JSON.stringify({ acquired: release !== null }));
+release?.();
+`
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed).toEqual({ acquired: true });
+  }, 20_000);
+
+  it("reclaims a lock held past the staleness deadline", () => {
+    const dir = storage();
+    writeFileSync(
+      join(dir, LOCK_FILE),
+      JSON.stringify({
+        pid: process.pid,
+        acquiredAt: Date.now() - 31 * 60 * 1000,
+        directory: "/stalled",
+      })
+    );
+
+    const result = runScript(
+      dir,
+      "reclaim-stale.mjs",
+      `
+${preamble(dir)}
+const release = lock.tryAcquireProfileLearningLock("/project-a");
+console.log(JSON.stringify({ acquired: release !== null }));
+release?.();
+`
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed).toEqual({ acquired: true });
+  }, 20_000);
+
+  it("does not steal a lock file that is still being written", () => {
+    const dir = storage();
+    // A truncated file is what a reader can observe between the `wx` create and
+    // the content write. Reclaiming it immediately would hand the lock to a
+    // second process while the first believes it holds it.
+    writeFileSync(join(dir, LOCK_FILE), "{");
+
+    const result = runScript(
+      dir,
+      "write-window.mjs",
+      `
+${preamble(dir)}
+const release = lock.tryAcquireProfileLearningLock("/project-a");
+console.log(JSON.stringify({ acquired: release !== null }));
+release?.();
+`
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed).toEqual({ acquired: false });
+  }, 20_000);
+
+  it("reclaims a corrupt lock file once the write window has passed", () => {
+    const dir = storage();
+    const lockFile = join(dir, LOCK_FILE);
+    writeFileSync(lockFile, "{");
+    const stale = new Date(Date.now() - 60_000);
+    // Backdate past WRITE_WINDOW_MS so the file reads as corrupt, not mid-write.
+    utimesSync(lockFile, stale, stale);
+
+    const result = runScript(
+      dir,
+      "corrupt-expired.mjs",
+      `
+${preamble(dir)}
+const release = lock.tryAcquireProfileLearningLock("/project-a");
+console.log(JSON.stringify({ acquired: release !== null }));
+release?.();
+`
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed).toEqual({ acquired: true });
+  }, 20_000);
+
+  it("keeps a live holder's lock and records its identity", () => {
+    const dir = storage();
+
+    const result = runScript(
+      dir,
+      "held.mjs",
+      `
+${preamble(dir)}
+import { readFileSync } from "node:fs";
+const release = lock.tryAcquireProfileLearningLock("/project-a");
+console.log(JSON.stringify({
+  held: lock.isProfileLearningLockHeld(),
+  pid: JSON.parse(readFileSync(${JSON.stringify(join(dir, LOCK_FILE))}, "utf-8")).pid === process.pid,
+}));
+release?.();
+`
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed).toEqual({ held: true, pid: true });
+  }, 20_000);
+
+  it("does not release a lock that now belongs to another process", () => {
+    const dir = storage();
+    const lockFile = join(dir, LOCK_FILE);
+
+    const result = runScript(
+      dir,
+      "foreign-release.mjs",
+      `
+${preamble(dir)}
+import { writeFileSync } from "node:fs";
+const release = lock.tryAcquireProfileLearningLock("/project-a");
+// Simulate the lock having been reclaimed by a different live process.
+writeFileSync(${JSON.stringify(lockFile)}, JSON.stringify({
+  pid: 4194304, acquiredAt: Date.now(), directory: "/other",
+}));
+release?.();
+console.log(JSON.stringify({ stillPresent: true }));
+`
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(readFileSync(lockFile, "utf-8")).toContain("4194304");
+  }, 20_000);
+});

From 7e071c5914abd71c0d2836e632bd3f5ac97cb544 Mon Sep 17 00:00:00 2001
From: lcy <admin@luchenyang.xyz>
Date: Thu, 1 Oct 2026 01:44:21 +0800
Subject: [PATCH 2/2] fix: harden cross-process profile learning for real
 deployments

- Replace the FS lock with a standalone SQLite coordination DB: CAS token
  ownership, no TTL takeover, dead-owner reclaim via pid+boot_id+starttime
- Move the in-process guard before the first await; release in a nested
  finally so the flag stays raised while release is in flight
- Read the cold buffer as bytes with a zero-length guard and fail closed on
  blank/unexpected-schema files instead of treating them as empty
- Keep profile parse/merge failures outside the provider fallback catch so
  storage errors propagate instead of retrying a broken LLM path
- Add cross-process tests: real service lock (8), cold buffer (16), storage
  error (4), lock coordination (14); ordinary memory writes verified to
  proceed while the learning lock is held
- Fix lint: unused import/variable, require() imports -> ESM

Combined fork deployment QA: 542 pass / 0 fail / 4 skip.
---
 src/services/user-memory-learning.ts          |  54 +-
 src/services/user-profile/learning-lock.ts    | 460 ++++++++++++----
 .../user-profile/user-profile-manager.ts      | 287 +++++++---
 .../profile-cold-buffer-worker-preload.ts     |  51 ++
 .../profile-cold-buffer-worker-shortwrite.ts  |  69 +++
 .../fixtures/profile-learning-lock-worker.mts | 376 +++++++++++++
 .../profile-learning-memory-writer.mjs        | 132 +++++
 .../profile-learning-service-worker.mjs       | 226 ++++++++
 .../profile-learning-storage-error-worker.mjs | 321 +++++++++++
 .../profile-cold-buffer-cross-process.test.ts | 512 ++++++++++++++++++
 tests/profile-learning-lock.test.ts           | 511 ++++++++++-------
 tests/profile-learning-service-lock.test.ts   | 345 ++++++++++++
 tests/profile-learning-storage-error.test.ts  | 117 ++++
 tests/user-profile-learning-error.test.ts     |   6 +
 14 files changed, 3075 insertions(+), 392 deletions(-)
 create mode 100644 tests/fixtures/profile-cold-buffer-worker-preload.ts
 create mode 100644 tests/fixtures/profile-cold-buffer-worker-shortwrite.ts
 create mode 100644 tests/fixtures/profile-learning-lock-worker.mts
 create mode 100644 tests/fixtures/profile-learning-memory-writer.mjs
 create mode 100644 tests/fixtures/profile-learning-service-worker.mjs
 create mode 100644 tests/fixtures/profile-learning-storage-error-worker.mjs
 create mode 100644 tests/profile-cold-buffer-cross-process.test.ts
 create mode 100644 tests/profile-learning-service-lock.test.ts
 create mode 100644 tests/profile-learning-storage-error.test.ts

diff --git a/src/services/user-memory-learning.ts b/src/services/user-memory-learning.ts
index a1dc9f5e..9a5fd660 100644
--- a/src/services/user-memory-learning.ts
+++ b/src/services/user-memory-learning.ts
@@ -68,19 +68,23 @@ export async function performUserProfileLearning(
     return;
   }
 
+  // Set before the first await so a same-process re-entry bounces off the flag
+  // instead of queueing behind this run and running a second analysis.
+  //
   // `isLearningRunning` only guards re-entry inside one process. Prompt selection
   // is a plain SELECT and the batch is marked only after the LLM responds, so
   // without cross-process exclusion two instances sharing this storage would
   // analyze the same prompts and the slower writer would clobber the faster
   // one's profile update. Contention skips this round; the next idle retries.
-  const releaseLearningLock = tryAcquireProfileLearningLock(directory);
-  if (!releaseLearningLock) {
-    log("user-profile-learning: skipped (another process holds the learning lock)");
-    return;
-  }
-
   isLearningRunning = true;
+  let releaseLearningLock: (() => Promise<void> | void) | null = null;
   try {
+    releaseLearningLock = await tryAcquireProfileLearningLock(directory);
+    if (!releaseLearningLock) {
+      log("user-profile-learning: skipped (another process holds the learning lock)");
+      return;
+    }
+
     const count = await userPromptManager.countUnanalyzedForUserLearning();
     const threshold = CONFIG.userProfileAnalysisInterval;
 
@@ -303,8 +307,17 @@ Rules:
     log("user-profile-learning: aborted", { error: String(error) });
     throw error;
   } finally {
-    isLearningRunning = false;
-    releaseLearningLock();
+    // Release only when the lock was actually acquired (contention return,
+    // acquisition failure, and any throw before acquisition all leave it null).
+    // The flag resets in a nested finally so it stays raised while the release
+    // await is in flight — otherwise a same-process re-entry could slip in and
+    // find the cross-process lock already gone — and it still resets when the
+    // release itself rejects.
+    try {
+      await releaseLearningLock?.();
+    } finally {
+      isLearningRunning = false;
+    }
   }
 }
 
@@ -662,6 +675,14 @@ async function analyzeUserProfile(
   let opencodeProviderError: unknown;
   if (CONFIG.opencodeProvider && CONFIG.opencodeModel) {
     log("user-profile-learning: trying opencode provider");
+    // The try/catch boundary is the provider only: LLM client construction,
+    // the structured-output call, and schema binding. Stored-profile parsing
+    // and merging happen AFTER a successful LLM response and outside this
+    // try — a cold-storage read/parse/merge failure must propagate to the
+    // caller (logged + rethrown there), never be mistaken for a provider
+    // fault that silently falls back to the external API and then
+    // re-reads/re-merges the same broken storage.
+    let rawData: UserProfileData | null = null;
     try {
       const { generateStructuredOutput } = await loadOpencodeProvider();
       const { getOpenCodeClient } = await import("./ai/profile-llm-client.js");
@@ -708,8 +729,18 @@ Use the update_user_profile tool to save the ${existingProfile ? "updated" : "ne
         wfCount: result.workflows?.length,
       });
 
-      const rawData = result as unknown as UserProfileData;
+      rawData = result as unknown as UserProfileData;
+    } catch (e) {
+      opencodeProviderError = e;
+      log("user-profile-learning: opencode provider failed, falling back to external API", {
+        error: String(e),
+      });
+    }
 
+    // Stored-profile parse/merge runs only after a native success and is
+    // deliberately OUTSIDE the provider catch: storage faults here are not
+    // provider faults and must not trigger the external fallback.
+    if (rawData !== null) {
       if (existingProfile) {
         const existingData: UserProfileData = JSON.parse(existingProfile.profileData);
         const merged = await userProfileManager.mergeProfileData(
@@ -721,11 +752,6 @@ Use the update_user_profile tool to save the ${existingProfile ? "updated" : "ne
         return { raw: rawData, merged };
       }
       return { raw: rawData, merged: null };
-    } catch (e) {
-      opencodeProviderError = e;
-      log("user-profile-learning: opencode provider failed, falling back to external API", {
-        error: String(e),
-      });
     }
   }
 
diff --git a/src/services/user-profile/learning-lock.ts b/src/services/user-profile/learning-lock.ts
index 225bc2d3..c058ebd5 100644
--- a/src/services/user-profile/learning-lock.ts
+++ b/src/services/user-profile/learning-lock.ts
@@ -1,160 +1,412 @@
-import { mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { createClient, type Client } from "@libsql/client";
 import { CONFIG } from "../../config.js";
 import { log } from "../logger.js";
 
-const LEARNING_LOCK = ".profile-learning.lock";
-
 /**
- * Upper bound on how long a lock may be held before other processes treat it as
- * abandoned. Profile learning issues LLM requests, so this has to exceed a slow
- * provider round trip; it only matters when a holder dies without releasing and
- * its PID has already been reused by an unrelated process.
+ * Standalone coordination database (SQLite via @libsql/client) inside
+ * CONFIG.storagePath. It is deliberately separate from the memory database:
+ * every statement here is short and autonomous, and no transaction is ever
+ * held across the LLM round trip, so lock traffic cannot block normal memory
+ * database work.
  */
-const STALE_LOCK_MS = 30 * 60 * 1000;
+export const PROFILE_LEARNING_COORDINATION_DB = ".profile-learning-coordination.db";
 
-/**
- * Grace period during which a lock file whose contents cannot be parsed is left
- * alone. `writeFileSync` is not atomic, so a reader can observe a file that was
- * created but not yet filled in. Deleting it on sight would hand the lock to a
- * second process while the first believes it holds it.
- */
-const WRITE_WINDOW_MS = 5_000;
+/** Single logical lock — the table only ever holds this one row. */
+const LOCK_NAME = "profile-learning";
+
+/** Bounded wait so a contended coordination DB cannot hang an idle handler. */
+const BUSY_TIMEOUT_MS = 5_000;
 
-interface LearningLockState {
+interface ProcessIdentity {
   pid: number;
-  acquiredAt: number;
-  directory: string;
+  bootId: string | null;
+  starttime: string | null;
 }
 
-function isProcessAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
+interface ValidOwner {
+  ownerToken: string;
+  pid: number;
+  bootId: string | null;
+  starttime: string | null;
 }
 
-function lockPath(): string {
-  return join(CONFIG.storagePath || "", LEARNING_LOCK);
+type ProcStatResult =
+  { status: "ok"; starttime: string } | { status: "absent" } | { status: "unreadable" };
+
+/** Linux boot_id is a lowercase UUID printed by the kernel. */
+const BOOT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function coordinationDbPath(): string {
+  return resolve(CONFIG.storagePath || "", PROFILE_LEARNING_COORDINATION_DB);
 }
 
-function removeLock(path: string): void {
+/**
+ * Opens the coordination database, guarantees the lock table exists, runs the
+ * callback, and always closes the handle. One handle per operation; nothing is
+ * cached across the LLM round trip.
+ */
+async function withCoordinationDb<T>(fn: (client: Client) => Promise<T>): Promise<T> {
+  const dbPath = coordinationDbPath();
   try {
-    unlinkSync(path);
+    mkdirSync(dirname(dbPath), { recursive: true });
   } catch {
-    // Already gone (lost the cleanup race) or held open by the OS. Either way
-    // this process does not own it, so surface nothing.
+    // Already exists, or the statements below will fail loudly on their own.
+  }
+  const client = createClient({ url: `file:${dbPath}` });
+  try {
+    await client.execute(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+    await client.execute(`CREATE TABLE IF NOT EXISTS profile_learning_lock (
+      name TEXT PRIMARY KEY,
+      owner_token TEXT NOT NULL,
+      pid INTEGER NOT NULL,
+      boot_id TEXT,
+      starttime TEXT,
+      acquired_at INTEGER NOT NULL
+    )`);
+    return await fn(client);
+  } finally {
+    client.close();
   }
 }
 
+function rowsAffected(result: { rowsAffected?: number | bigint }): number {
+  return Number(result.rowsAffected ?? 0);
+}
+
 /**
- * Returns the state of a lock that is still held, or null when no live holder
- * remains. A stale lock is removed as a side effect so the caller can retry.
+ * Reads the machine's current boot id. The value is only used as a dead
+ * signal when it matches the strict kernel format; anything unreadable or
+ * malformed is treated as "unknown" and never participates in a dead
+ * decision.
  */
-function readLiveLock(path: string): LearningLockState | null {
-  let raw: string;
+function readBootId(): string | null {
   try {
-    raw = readFileSync(path, "utf-8");
+    const value = readFileSync("/proc/sys/kernel/random/boot_id", "utf-8").trim();
+    return BOOT_ID_PATTERN.test(value) ? value : null;
   } catch {
     return null;
   }
+}
 
-  let state: LearningLockState;
+/**
+ * Reads field 22 (starttime) of /proc/<pid>/stat. The comm field may contain
+ * spaces and parentheses, so parsing starts after the final ')' in the line;
+ * after that point field N lives at index N - 3 (state is field 3).
+ */
+function readProcStat(pid: number): ProcStatResult {
+  let stat: string;
   try {
-    state = JSON.parse(raw) as LearningLockState;
-  } catch {
-    // Unparseable: either mid-write by a live acquirer, or genuinely corrupt.
-    // Respect the write window before reclaiming so we never steal a lock that
-    // another process is in the middle of taking.
-    let mtimeMs: number;
-    try {
-      mtimeMs = statSync(path).mtimeMs;
-    } catch {
-      return null;
-    }
-    if (Date.now() - mtimeMs < WRITE_WINDOW_MS) {
-      return { pid: -1, acquiredAt: mtimeMs, directory: "<initializing>" };
-    }
-    removeLock(path);
-    return null;
+    stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+  } catch (error) {
+    return (error as NodeJS.ErrnoException)?.code === "ENOENT"
+      ? { status: "absent" }
+      : { status: "unreadable" };
+  }
+  const commEnd = stat.lastIndexOf(")");
+  if (commEnd === -1) {
+    return { status: "unreadable" };
   }
+  const fields = stat.slice(commEnd + 2).split(" ");
+  const starttime = fields[22 - 3];
+  return starttime && /^\d+$/.test(starttime)
+    ? { status: "ok", starttime }
+    : { status: "unreadable" };
+}
 
-  if (!Number.isInteger(state.pid) || state.pid <= 0) {
-    removeLock(path);
-    return null;
+function currentProcessIdentity(): ProcessIdentity {
+  const own = readProcStat(process.pid);
+  return {
+    pid: process.pid,
+    bootId: readBootId(),
+    starttime: own.status === "ok" ? own.starttime : null,
+  };
+}
+
+function coercePid(value: unknown): number | null {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+    return value;
   }
+  if (typeof value === "bigint" && value > 0n && Number.isSafeInteger(Number(value))) {
+    return Number(value);
+  }
+  if (typeof value === "string" && /^-?\d+$/.test(value)) {
+    const pid = Number(value);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  }
+  return null;
+}
 
-  if (state.pid !== process.pid && !isProcessAlive(state.pid)) {
-    log("profile-learning lock: reclaiming lock from dead holder", { pid: state.pid });
-    removeLock(path);
-    return null;
+function coerceOptionalString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * Boot id of a stored owner record. Three distinct states:
+ *  - "none"  — column is NULL: legitimately recorded on a platform without
+ *              /proc (conservative signal-probe fallback applies);
+ *  - "known" — a well-formed Linux boot id string;
+ *  - invalid — anything else (garbage string, number, object, …). Never
+ *              null-coerced: an owner whose boot id we cannot interpret is
+ *              an untrusted record and the lock is not acquired (fail-closed).
+ */
+type StoredBootId = { kind: "none" } | { kind: "known"; value: string };
+
+function parseStoredBootId(value: unknown): StoredBootId | null {
+  if (value === null) return { kind: "none" };
+  if (typeof value === "string" && BOOT_ID_PATTERN.test(value)) {
+    return { kind: "known", value };
   }
+  return null;
+}
 
-  const age = Date.now() - (state.acquiredAt ?? 0);
-  if (Number.isFinite(age) && age > STALE_LOCK_MS) {
-    log("profile-learning lock: reclaiming expired lock", { pid: state.pid, ageMs: age });
-    removeLock(path);
-    return null;
+/**
+ * Structural validation of the stored owner record. A malformed record is
+ * never treated as a free or reclaimable lock (fail-closed): the caller just
+ * skips this round instead of potentially stealing a live holder's lock.
+ */
+function parseOwnerRow(
+  row: Record<string, unknown>
+): { ok: true; owner: ValidOwner } | { ok: false; reason: string } {
+  const ownerToken = coerceOptionalString(row["owner_token"]);
+  if (!ownerToken) return { ok: false, reason: "owner_token missing/empty" };
+
+  const pid = coercePid(row["pid"]);
+  if (pid === null) return { ok: false, reason: `invalid pid: ${String(row["pid"])}` };
+
+  const storedBootId = parseStoredBootId(row["boot_id"]);
+  if (!storedBootId) return { ok: false, reason: `invalid boot_id: ${String(row["boot_id"])}` };
+  const bootId = storedBootId.kind === "known" ? storedBootId.value : null;
+
+  let starttime: string | null = null;
+  if (row["starttime"] !== null && row["starttime"] !== undefined) {
+    const raw = row["starttime"];
+    if (typeof raw !== "string" || !/^\d+$/.test(raw)) {
+      return { ok: false, reason: "invalid starttime" };
+    }
+    starttime = raw;
+  }
+
+  const acquiredAt = row["acquired_at"];
+  if (
+    typeof acquiredAt !== "number" &&
+    typeof acquiredAt !== "bigint" &&
+    !/^\d+$/.test(String(acquiredAt ?? ""))
+  ) {
+    return { ok: false, reason: "invalid acquired_at" };
   }
 
-  return state;
+  return { ok: true, owner: { ownerToken, pid, bootId, starttime } };
 }
 
 /**
- * Serializes profile learning across every process sharing this storage path.
+ * True only when the recorded owner is *definitively* gone from this
+ * machine's current PID namespace:
+ *  - its boot id is a valid UUID differing from this machine's current valid
+ *    boot id (the holder ran under a previous boot), or
+ *  - /proc/<pid>/stat is readable and starttime differs (PID reuse), or
+ *  - /proc/<pid>/stat is absent AND the signal-0 probe returns ESRCH —
+ *    hidepid=2 makes a live holder's /proc entry invisible, so ENOENT alone
+ *    is never proof of death, or
+ *  - (no startup identity recorded) signal 0 returns ESRCH.
  *
- * Profile learning selects a batch of prompts with a plain SELECT, issues an LLM
- * request, then writes the profile and marks the batch. None of that is atomic,
- * so two processes running it concurrently would analyze the same prompts twice
- * and the slower writer would clobber the faster one's profile update.
+ * EPERM means "alive under another uid" and counts as live; any other
+ * error means "unknown" and is never a dead signal. Identity we cannot
+ * establish is never guessed, and no TTL ever overrides this check.
  *
- * Returns a release function, or null when another process holds the lock — in
- * which case the caller must skip this round rather than wait, because the next
- * idle event will retry.
+ * Single-machine view: the coordination DB is expected to be shared only by
+ * processes on one host. A record written by a process in another PID
+ * namespace is beyond what local /proc can attest and conservatively reads
+ * as not-dead.
  */
-export function tryAcquireProfileLearningLock(directory: string): (() => void) | null {
-  const path = lockPath();
-
+/**
+ * Signal-0 liveness probe. ESRCH is the only "dead" outcome: EPERM means
+ * alive under another uid (hidepid=2 or another user), and any other error
+ * means "unknown", which is never a dead signal.
+ */
+/**
+ * Signal-0 liveness probe. ESRCH is the only "dead" outcome: EPERM means
+ * alive under another uid (hidepid=2 or another user), and any other error
+ * means "unknown", which is never a dead signal.
+ */
+function isPidGoneBySignal(pid: number): boolean {
   try {
-    mkdirSync(CONFIG.storagePath || "", { recursive: true });
-  } catch {
-    // Storage path already exists, or cannot be created — the write below fails
-    // loudly enough on its own.
+    process.kill(pid, 0);
+    return false;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException)?.code === "ESRCH";
   }
+}
 
-  const holder = readLiveLock(path);
-  if (holder) return null;
-
-  const state: LearningLockState = {
-    pid: process.pid,
-    acquiredAt: Date.now(),
-    directory,
-  };
+function ownerIsDefinitelyDead(owner: ValidOwner, self: ProcessIdentity): boolean {
+  if (self.bootId !== null && owner.bootId !== null && owner.bootId !== self.bootId) {
+    return true;
+  }
 
-  try {
-    writeFileSync(path, JSON.stringify(state), { flag: "wx" });
-  } catch {
-    // Lost the race: another process created the file between our check and
-    // write. `wx` is what makes that detectable rather than silently shared.
-    return null;
+  if (self.starttime !== null && owner.starttime !== null) {
+    const stat = readProcStat(owner.pid);
+    if (stat.status === "ok") {
+      return stat.starttime !== owner.starttime;
+    }
+    if (stat.status === "absent") {
+      // /proc may be hidden (hidepid=2): fall through to the signal probe
+      // instead of trusting ENOENT as proof of death.
+      return isPidGoneBySignal(owner.pid);
+    }
+    return false;
   }
 
+  return isPidGoneBySignal(owner.pid);
+}
+
+function releaseFn(ownerToken: string): () => Promise<void> {
   let released = false;
-  return () => {
+  return async () => {
     if (released) return;
     released = true;
     try {
-      const current = JSON.parse(readFileSync(path, "utf-8")) as LearningLockState;
-      if (current.pid !== process.pid) return;
-    } catch {
-      return;
+      await withCoordinationDb(async (client) => {
+        await client.execute({
+          sql: `DELETE FROM profile_learning_lock WHERE name = ? AND owner_token = ?`,
+          args: [LOCK_NAME, ownerToken],
+        });
+      });
+    } catch (error) {
+      // The owner row survives; after this process exits another process can
+      // reclaim it via the dead-owner CAS path. Never throw out of release.
+      log("profile-learning lock: release failed; row will be reclaimed after exit", {
+        error: String(error),
+      });
     }
-    removeLock(path);
   };
 }
 
-export function isProfileLearningLockHeld(): boolean {
-  return readLiveLock(lockPath()) !== null;
+/**
+ * Serializes profile learning across every process sharing this storage path.
+ *
+ * Ownership is a single row in a standalone SQLite coordination database:
+ *  - acquiring is one `INSERT ... ON CONFLICT DO NOTHING` (rowsAffected 1 wins);
+ *  - a conflicting row is only taken over with a conditional
+ *    `UPDATE ... WHERE owner_token = <old token>` (CAS) when the recorded
+ *    owner is provably dead or its original process identity is gone;
+ *  - release is `DELETE ... WHERE owner_token = <token>`, so a stale release
+ *    from a previous owner (even with a reused PID) can never drop someone
+ *    else's lock.
+ *
+ * Returns a release function, or null when another process holds the lock or
+ * the coordination state cannot be trusted (fail-closed) — in both cases the
+ * caller must skip this round rather than wait, because the next idle event
+ * retries.
+ *
+ * Service wiring note: this function is async and must be `await`ed by the
+ * caller, with the in-process `isLearningRunning` guard set before the first
+ * `await`.
+ */
+export async function tryAcquireProfileLearningLock(
+  directory: string
+): Promise<(() => Promise<void>) | null> {
+  const identity = currentProcessIdentity();
+  const ownerToken = randomUUID();
+
+  try {
+    return await withCoordinationDb(async (client) => {
+      const inserted = await client.execute({
+        sql: `INSERT INTO profile_learning_lock
+                (name, owner_token, pid, boot_id, starttime, acquired_at)
+              VALUES (?, ?, ?, ?, ?, ?)
+              ON CONFLICT (name) DO NOTHING`,
+        args: [
+          LOCK_NAME,
+          ownerToken,
+          identity.pid,
+          identity.bootId,
+          identity.starttime,
+          Date.now(),
+        ],
+      });
+      if (rowsAffected(inserted) === 1) {
+        return releaseFn(ownerToken);
+      }
+
+      const selected = await client.execute({
+        sql: `SELECT owner_token, pid, boot_id, starttime, acquired_at
+              FROM profile_learning_lock WHERE name = ?`,
+        args: [LOCK_NAME],
+      });
+      const row = selected.rows[0] as Record<string, unknown> | undefined;
+      if (!row) {
+        // Released between our failed INSERT and the SELECT. Treat as
+        // contention: skip this round, the next idle event retries.
+        return null;
+      }
+
+      const parsed = parseOwnerRow(row);
+      if (!parsed.ok) {
+        log("profile-learning lock: malformed coordination record, refusing to acquire", {
+          directory,
+          reason: parsed.reason,
+        });
+        return null;
+      }
+
+      if (!ownerIsDefinitelyDead(parsed.owner, identity)) {
+        // Live holder, EPERM, or uncertain identity: never reclaim, never
+        // guess, and no TTL is allowed to override this.
+        return null;
+      }
+
+      const claimed = await client.execute({
+        sql: `UPDATE profile_learning_lock
+              SET owner_token = ?, pid = ?, boot_id = ?, starttime = ?, acquired_at = ?
+              WHERE name = ? AND owner_token = ?`,
+        args: [
+          ownerToken,
+          identity.pid,
+          identity.bootId,
+          identity.starttime,
+          Date.now(),
+          LOCK_NAME,
+          parsed.owner.ownerToken,
+        ],
+      });
+      if (rowsAffected(claimed) === 1) {
+        log("profile-learning lock: reclaimed lock from dead owner", {
+          directory,
+          previousPid: parsed.owner.pid,
+        });
+        return releaseFn(ownerToken);
+      }
+      // Lost the CAS race to another reclaimer.
+      return null;
+    });
+  } catch (error) {
+    log("profile-learning lock: coordination database unavailable, refusing to acquire", {
+      directory,
+      error: String(error),
+    });
+    return null;
+  }
+}
+
+/**
+ * Whether a coordination record currently exists. Test/inspection helper; a
+ * database error is reported as "not held" but logged.
+ */
+export async function isProfileLearningLockHeld(): Promise<boolean> {
+  try {
+    return await withCoordinationDb(async (client) => {
+      const result = await client.execute({
+        sql: `SELECT 1 FROM profile_learning_lock WHERE name = ? LIMIT 1`,
+        args: [LOCK_NAME],
+      });
+      return result.rows.length > 0;
+    });
+  } catch (error) {
+    log("profile-learning lock: coordination database unavailable in isProfileLearningLockHeld", {
+      error: String(error),
+    });
+    return false;
+  }
 }
diff --git a/src/services/user-profile/user-profile-manager.ts b/src/services/user-profile/user-profile-manager.ts
index 91377467..8265861b 100644
--- a/src/services/user-profile/user-profile-manager.ts
+++ b/src/services/user-profile/user-profile-manager.ts
@@ -1,5 +1,6 @@
 import { join } from "node:path";
-import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { closeSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { tursoConnectionManager } from "../turso/connection-manager.js";
 import type { TursoDb } from "../turso/turso-db.js";
 import { CONFIG } from "../../config.js";
@@ -78,13 +79,20 @@ export class UserProfileManager {
   // (COLD_BUFFER_DEFAULT_KEY) only holds items from merges that ran without a profileId.
   private coldBuffers: Map<string, { preferences: any[]; patterns: any[]; workflows: any[] }>;
   private coldBufferPath: string;
-  private coldBufferMtimeMs: number | null = null;
+  /**
+   * Set when the last disk read of cold-buffer.json failed in a way that means
+   * "unknown on-disk state" (permission error, unparseable JSON, bad schema).
+   * A merge round must then fail closed instead of treating the data as empty
+   * and overwriting it. The constructor stays fail-safe: a non-critical cache
+   * read error must never crash the plugin import path, so it is only recorded.
+   */
+  private coldBufferLoadError: Error | null = null;
   private dedupCheckedCache: Set<string> = new Set();
 
   constructor() {
     this.dbPath = join(CONFIG.storagePath || "", USER_PROFILES_DB_NAME);
     this.coldBufferPath = join(CONFIG.storagePath || "", "cold-buffer.json");
-    this.coldBuffers = this.loadColdBuffers();
+    this.coldBuffers = this.loadColdBuffersFailSafe();
   }
 
   reset(): void {
@@ -92,6 +100,10 @@ export class UserProfileManager {
     this.initPromise = null;
     this.dbPath = join(CONFIG.storagePath || "", USER_PROFILES_DB_NAME);
     this.coldBufferPath = join(CONFIG.storagePath || "", "cold-buffer.json");
+    // The new storage starts from its own on-disk snapshot. Keeping the old
+    // map would resurrect the previous storage's buckets on the next save.
+    this.coldBuffers = this.loadColdBuffersFailSafe();
+    this.coldBufferLoadError = null;
   }
 
   private async initialize(): Promise<void> {
@@ -102,7 +114,13 @@ export class UserProfileManager {
     this.initPromise = (async () => {
       try {
         this.dbPath = join(CONFIG.storagePath || "", USER_PROFILES_DB_NAME);
-        this.coldBufferPath = join(CONFIG.storagePath || "", "cold-buffer.json");
+        const newColdBufferPath = join(CONFIG.storagePath || "", "cold-buffer.json");
+        if (newColdBufferPath !== this.coldBufferPath) {
+          // storagePath changed since construction — do not keep draining or
+          // saving the previous storage's buckets.
+          this.coldBufferPath = newColdBufferPath;
+          this.coldBuffers = this.loadColdBuffersFailSafe();
+        }
         this.db = await tursoConnectionManager.getConnection(this.dbPath);
         await this.initDatabase();
       } catch (error) {
@@ -135,25 +153,150 @@ export class UserProfileManager {
   }
 
   /**
-   * Discards the cached cold buffer when another process has rewritten the file.
+   * Fail-safe wrapper for the constructor / reset() path. A non-critical cache
+   * read error must not crash plugin import, so the error is recorded and an
+   * empty map is returned; the next merge round then fails closed.
+   */
+  private loadColdBuffersFailSafe(): Map<
+    string,
+    { preferences: any[]; patterns: any[]; workflows: any[] }
+  > {
+    try {
+      return this.loadColdBuffers();
+    } catch (e) {
+      this.coldBufferLoadError = e instanceof Error ? e : new Error(String(e));
+      return new Map();
+    }
+  }
+
+  /**
+   * Reads the complete cold-buffer snapshot from disk, strictly.
    *
-   * The buffer is read once in the constructor and `saveColdBuffers` rewrites the
-   * whole file from this in-memory map. Now that more than one process can run
-   * profile learning, a process holding a stale map would erase entries a peer
-   * persisted in the meantime. Comparing the file's mtime keeps that correctness
-   * requirement inside the manager instead of relying on every caller to refresh.
+   * A missing file (ENOENT) legitimately means "empty snapshot". Any other
+   * failure (permissions, unparseable JSON, malformed schema) means the
+   * on-disk state is unknown and MUST be thrown to the caller — treating it
+   * as empty would persist an empty snapshot over data we never read.
    */
-  private refreshColdBuffersIfChanged(): void {
-    let mtimeMs: number;
+  private loadColdBuffers(): Map<
+    string,
+    { preferences: any[]; patterns: any[]; workflows: any[] }
+  > {
+    const map = new Map<string, { preferences: any[]; patterns: any[]; workflows: any[] }>();
+    let raw: string;
+    try {
+      raw = readFileSync(this.coldBufferPath, "utf-8");
+    } catch (e: any) {
+      if (e?.code === "ENOENT") return map;
+      throw new Error(`profile cold buffer: unreadable (${this.coldBufferPath}): ${String(e)}`, {
+        cause: e,
+      });
+    }
+    let data: any;
     try {
-      mtimeMs = statSync(this.coldBufferPath).mtimeMs;
-    } catch {
-      // No file yet (or unreadable): nothing on disk can be newer than our map.
-      return;
+      data = JSON.parse(raw);
+    } catch (e) {
+      throw new Error(
+        `profile cold buffer: corrupt JSON, refusing to overwrite (${this.coldBufferPath}): ${String(e)}`,
+        { cause: e }
+      );
+    }
+
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+      throw new Error(
+        `profile cold buffer: unexpected schema, refusing to overwrite (${this.coldBufferPath})`
+      );
+    }
+
+    // Explicit legacy detection: the flat format is exactly the three category
+    // keys (each an array, at least one present) and nothing else. Anything
+    // else containing those keys is an unknown shape, not "legacy".
+    const legacyKeys = ["preferences", "patterns", "workflows"];
+    const presentLegacyKeys = legacyKeys.filter((k) => k in data);
+    if (presentLegacyKeys.length > 0) {
+      const onlyLegacyKeys = Object.keys(data).every((k) => legacyKeys.includes(k));
+      const allArrays = legacyKeys.every((k) => !(k in data) || Array.isArray(data[k]));
+      if (onlyLegacyKeys && allArrays) {
+        // Legacy flat format ({ preferences, patterns, workflows }) is
+        // cross-user contaminated and cannot be attributed to a profile, so
+        // it is dropped rather than replayed. This is the documented
+        // migration path, not a silent data loss: the format predates
+        // per-profile buckets.
+        log("profile cold buffer: dropping legacy unattributed buffer", {
+          keys: presentLegacyKeys,
+        });
+        return map;
+      }
+      throw new Error(
+        `profile cold buffer: legacy keys with unknown shape, refusing to overwrite (${this.coldBufferPath})`
+      );
+    }
+
+    // Per-profile buckets: every key must be a bucket whose category arrays
+    // hold real items. An invalid entry means the on-disk state is unknown —
+    // coercing it to [] would persist "known empty" over data we never read.
+    let loaded = 0;
+    for (const [pid, v] of Object.entries<any>(data)) {
+      if (v === null || typeof v !== "object" || Array.isArray(v)) {
+        throw new Error(
+          `profile cold buffer: bucket "${pid}" is not an object, refusing to overwrite (${this.coldBufferPath})`
+        );
+      }
+      const bucket: { preferences: any[]; patterns: any[]; workflows: any[] } = {
+        preferences: [],
+        patterns: [],
+        workflows: [],
+      };
+      for (const category of ["preferences", "patterns", "workflows"] as const) {
+        const items = v[category];
+        if (items === undefined) continue;
+        if (!Array.isArray(items)) {
+          throw new Error(
+            `profile cold buffer: bucket "${pid}.${category}" is not an array, refusing to overwrite (${this.coldBufferPath})`
+          );
+        }
+        for (const item of items) {
+          if (item === null || typeof item !== "object" || Array.isArray(item)) {
+            throw new Error(
+              `profile cold buffer: bucket "${pid}.${category}" holds a non-object item, refusing to overwrite (${this.coldBufferPath})`
+            );
+          }
+          if (typeof item.description !== "string") {
+            throw new Error(
+              `profile cold buffer: bucket "${pid}.${category}" holds an item without a string description, refusing to overwrite (${this.coldBufferPath})`
+            );
+          }
+        }
+        bucket[category] = items;
+      }
+      map.set(pid, bucket);
+      loaded++;
+    }
+    if (loaded > 0) {
+      log("profile cold buffer: loaded from disk", { profiles: loaded });
+    }
+    return map;
+  }
+
+  /**
+   * Starts a merge round from the freshest complete on-disk snapshot.
+   *
+   * Cooperative learners take the learning lock, then re-read the snapshot at
+   * the start of every merge round, so a peer's persisted buckets are never
+   * clobbered by a stale in-memory map (mtime comparison cannot be trusted:
+   * same-mtime writes and clock rollback both hide peer updates). The loaded
+   * map is fixed for the whole round: every buffer mutation and save in this
+   * round goes through the same reference, so pending unsaved increments are
+   * never dropped by a mid-round reference swap.
+   */
+  private beginColdBufferRound(): void {
+    try {
+      this.coldBuffers = this.loadColdBuffers();
+      this.coldBufferLoadError = null;
+    } catch (e) {
+      // Fail closed: the on-disk state is unknown, so no mutation may proceed.
+      this.coldBufferLoadError = e instanceof Error ? e : new Error(String(e));
+      throw this.coldBufferLoadError;
     }
-    if (this.coldBufferMtimeMs !== null && mtimeMs <= this.coldBufferMtimeMs) return;
-    this.coldBuffers = this.loadColdBuffers();
-    this.coldBufferMtimeMs = mtimeMs;
   }
 
   private getColdBuffer(profileId?: string): {
@@ -161,7 +304,6 @@ export class UserProfileManager {
     patterns: any[];
     workflows: any[];
   } {
-    this.refreshColdBuffersIfChanged();
     const key = profileId || COLD_BUFFER_DEFAULT_KEY;
     let buf = this.coldBuffers.get(key);
     if (!buf) {
@@ -171,60 +313,56 @@ export class UserProfileManager {
     return buf;
   }
 
-  private loadColdBuffers(): Map<
-    string,
-    { preferences: any[]; patterns: any[]; workflows: any[] }
-  > {
-    const map = new Map<string, { preferences: any[]; patterns: any[]; workflows: any[] }>();
-    try {
-      if (existsSync(this.coldBufferPath)) {
-        const raw = readFileSync(this.coldBufferPath, "utf-8");
-        const data = JSON.parse(raw);
-        // Legacy flat format ({ preferences, patterns, workflows }) is cross-user
-        // contaminated and cannot be attributed to a profile, so it is dropped rather
-        // than replayed. New format is keyed by profileId.
-        const isLegacyFlat =
-          data &&
-          typeof data === "object" &&
-          !Array.isArray(data) &&
-          ("preferences" in data || "patterns" in data || "workflows" in data);
-        if (data && typeof data === "object" && !Array.isArray(data) && !isLegacyFlat) {
-          let loaded = 0;
-          for (const [pid, v] of Object.entries<any>(data)) {
-            map.set(pid, {
-              preferences: Array.isArray(v?.preferences) ? v.preferences : [],
-              patterns: Array.isArray(v?.patterns) ? v.patterns : [],
-              workflows: Array.isArray(v?.workflows) ? v.workflows : [],
-            });
-            loaded++;
-          }
-          if (loaded > 0) {
-            log("profile cold buffer: loaded from disk", { profiles: loaded });
-          }
-        } else if (isLegacyFlat) {
-          log("profile cold buffer: dropping legacy unattributed buffer");
-        }
+  /**
+   * Persists the current snapshot atomically: write a unique tmp file with
+   * O_EXCL (wx) and mode 0600, then rename over the target. Failures are
+   * thrown to the caller — swallowing them would let a round that never
+   * reached disk be reported as a successful learning merge.
+   */
+  private saveColdBuffers(): void {
+    const obj: Record<string, { preferences: any[]; patterns: any[]; workflows: any[] }> = {};
+    for (const [pid, v] of this.coldBuffers.entries()) {
+      if (v.preferences.length || v.patterns.length || v.workflows.length) {
+        obj[pid] = v;
       }
-    } catch {
-      // Corrupt or missing file — start with an empty buffer set.
     }
-    return map;
-  }
-
-  private saveColdBuffers(): void {
+    const tmpPath = `${this.coldBufferPath}.${randomUUID()}.tmp`;
+    let fd: number | undefined;
     try {
-      const obj: Record<string, { preferences: any[]; patterns: any[]; workflows: any[] }> = {};
-      for (const [pid, v] of this.coldBuffers.entries()) {
-        if (v.preferences.length || v.patterns.length || v.workflows.length) {
-          obj[pid] = v;
+      fd = openSync(tmpPath, "wx", 0o600);
+      // Byte-accurate payload: the string overload's third arg is a file
+      // position, not a string offset, and payload.length counts UTF-16
+      // units — both would corrupt multi-byte content on short writes.
+      const payload = Buffer.from(JSON.stringify(obj), "utf8");
+      let written = 0;
+      while (written < payload.length) {
+        // Buffer overload: (fd, buffer, offset, length) — append at the
+        // current position; n <= 0 means no forward progress is possible.
+        const n = writeSync(fd!, payload, written, payload.length - written);
+        if (!(n > 0)) {
+          throw new Error(`profile cold buffer: write stalled after ${written} bytes`);
         }
+        written += n;
       }
-      writeFileSync(this.coldBufferPath, JSON.stringify(obj), "utf-8");
-      // Record our own write so the next read does not mistake it for a peer's
-      // update and reload the map we just persisted.
-      this.coldBufferMtimeMs = statSync(this.coldBufferPath).mtimeMs;
-    } catch {
-      // Silently ignore disk-full / permission errors.
+      closeSync(fd);
+      fd = undefined;
+      renameSync(tmpPath, this.coldBufferPath);
+    } catch (e) {
+      if (fd !== undefined) {
+        try {
+          closeSync(fd);
+        } catch {
+          // best effort — the rename below is the cleanup that matters
+        }
+      }
+      try {
+        unlinkSync(tmpPath);
+      } catch {
+        // tmp file may never have been created
+      }
+      throw new Error(`profile cold buffer: save failed (${this.coldBufferPath}): ${String(e)}`, {
+        cause: e,
+      });
     }
   }
 
@@ -515,6 +653,10 @@ export class UserProfileManager {
   async deleteProfile(profileId: string): Promise<void> {
     const db = await this.ready();
     await db.run(`DELETE FROM user_profiles WHERE id = ?`, [profileId]);
+    // Re-read the current on-disk snapshot before deleting the bucket: a
+    // stale in-memory map (peer wrote meanwhile) would resurrect the deleted
+    // profile's bucket in the very save that is supposed to remove it.
+    this.beginColdBufferRound();
     if (this.coldBuffers.delete(profileId)) {
       this.saveColdBuffers();
     }
@@ -567,6 +709,13 @@ export class UserProfileManager {
     embedService?: EmbeddingService,
     profileId?: string
   ): Promise<UserProfileData> {
+    // Cross-process safety: cooperative learners hold the learning lock and
+    // start every round from the freshest complete on-disk snapshot. Fails
+    // closed when the on-disk state is unknown (see beginColdBufferRound).
+    // The snapshot is fixed for the whole round — getColdBuffer/saveColdBuffers
+    // never swap the map mid-round, so pending unsaved increments survive.
+    this.beginColdBufferRound();
+
     const merged: UserProfileData = {
       preferences: this.ensureArray(existing?.preferences),
       patterns: this.ensureArray(existing?.patterns),
diff --git a/tests/fixtures/profile-cold-buffer-worker-preload.ts b/tests/fixtures/profile-cold-buffer-worker-preload.ts
new file mode 100644
index 00000000..02111ecf
--- /dev/null
+++ b/tests/fixtures/profile-cold-buffer-worker-preload.ts
@@ -0,0 +1,51 @@
+/**
+ * Bun --preload patch for short-write simulation (see
+ * profile-cold-buffer-worker-shortwrite.ts for the worker itself).
+ *
+ * Loaded via `bun --preload` so the patch applies before any ESM import
+ * binds writeSync. It only limits how many bytes a single low-level
+ * fs.writeSync call forwards — the production saveColdBuffers() code path,
+ * the real tmp+rename flow and the real fd bookkeeping all stay live.
+ *
+ * mode is read from argv[2] of the *worker* command line:
+ *   short-ascii | short-utf8 | zero | half
+ */
+// The CJS namespace is the only patchable surface: the ESM namespace binding
+// of node:fs is frozen (Object.defineProperty on it throws), while Bun's
+// --preload runs before ESM imports bind writeSync, so patching the CJS
+// module also intercepts the production ESM import below.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const fs = require("node:fs") as typeof import("node:fs");
+const real = fs.writeSync;
+const argv = process.argv as unknown as string[];
+const mode = argv.find((a) => a.startsWith("SWMODE="))?.slice("SWMODE=".length) ?? "";
+let callIndex = 0;
+
+(fs as any).writeSync = function (fd: number, ...rest: any[]) {
+  if (fd === 1 || fd === 2) {
+    return (real as any)(fd, ...rest);
+  }
+  callIndex++;
+  const buffer = rest[0] as Buffer;
+  if (mode === "zero") {
+    if (callIndex === 1) return 0;
+    return (real as any)(fd, ...rest);
+  }
+  if (mode === "half") {
+    // Call 1 writes half the payload; call 2 fails mid-payload with EIO so
+    // the cleanup path runs with real partial bytes in the tmp file.
+    if (callIndex === 1) {
+      const len = rest[2] as number;
+      return (real as any)(fd, buffer, rest[1], Math.max(0, Math.floor(len / 2)));
+    }
+    if (callIndex === 2) {
+      const err = new Error("simulated EIO mid-payload") as any;
+      err.code = "EIO";
+      throw err;
+    }
+    return (real as any)(fd, ...rest);
+  }
+  // short-ascii / short-utf8: one byte per call — multi-byte chars are sliced
+  // mid-codepoint across calls, proving the write loop is byte-accurate.
+  return (real as any)(fd, buffer, rest[1], 1);
+};
diff --git a/tests/fixtures/profile-cold-buffer-worker-shortwrite.ts b/tests/fixtures/profile-cold-buffer-worker-shortwrite.ts
new file mode 100644
index 00000000..0bd8070f
--- /dev/null
+++ b/tests/fixtures/profile-cold-buffer-worker-shortwrite.ts
@@ -0,0 +1,69 @@
+/**
+ * Child-process worker for short-write simulation in the cold-buffer tests.
+ * Pair with profile-cold-buffer-worker-preload.ts via `bun --preload`.
+ *
+ * The preload patch only limits how many bytes a single low-level
+ * fs.writeSync call forwards — the production saveColdBuffers() path, the
+ * real tmp+rename flow and the real fd bookkeeping all stay live.
+ *
+ * Args: dir profileId description preExisting(""=none)
+ * Env/argv: SWMODE=short-ascii|short-utf8|zero|half (read by the preload)
+ * Prints one JSON line: { ok, error, targetBytes, tmpLeft }
+ */
+import * as fs from "node:fs";
+import { join } from "node:path";
+
+// Drop non-positional flags (SWMODE=... is consumed by the preload).
+const args = process.argv.slice(2).filter((a) => !a.startsWith("SWMODE="));
+const dir = args[0]!;
+const profileId = args[1]!;
+const description = args[2]!;
+const preExisting = args[3]!;
+
+const coldBufferPath = join(dir, "cold-buffer.json");
+if (preExisting === "") {
+  try {
+    fs.unlinkSync(coldBufferPath);
+  } catch {
+    // no file yet
+  }
+} else {
+  fs.writeFileSync(coldBufferPath, preExisting, "utf-8");
+}
+
+const { CONFIG } = await import("../../src/config.js");
+CONFIG.storagePath = dir;
+CONFIG.userProfileEmbeddingMinDescriptionLength = 5;
+delete CONFIG.opencodeProvider;
+delete CONFIG.opencodeModel;
+delete CONFIG.memoryModel;
+delete CONFIG.memoryApiUrl;
+
+const { UserProfileManager } =
+  await import("../../src/services/user-profile/user-profile-manager.js");
+const coldEmbed = { isWarmedUp: false } as any;
+
+const mgr = new UserProfileManager();
+let ok = true;
+let error: string | null = null;
+try {
+  await mgr.mergeProfileData(
+    { preferences: [], patterns: [], workflows: [] },
+    { preferences: [{ category: "style", description }] },
+    coldEmbed,
+    profileId
+  );
+} catch (e) {
+  ok = false;
+  error = String(e);
+}
+
+let targetBytes: string | null;
+try {
+  targetBytes = fs.readFileSync(coldBufferPath, "utf-8");
+} catch {
+  targetBytes = null;
+}
+const tmpLeft = fs.readdirSync(dir).filter((f) => f.includes(".tmp")).length;
+
+console.log(JSON.stringify({ ok, error, targetBytes, tmpLeft }));
diff --git a/tests/fixtures/profile-learning-lock-worker.mts b/tests/fixtures/profile-learning-lock-worker.mts
new file mode 100644
index 00000000..b4a9f380
--- /dev/null
+++ b/tests/fixtures/profile-learning-lock-worker.mts
@@ -0,0 +1,376 @@
+/**
+ * Cross-process worker for tests/profile-learning-lock.test.ts.
+ *
+ * Runs in a real separate process with CONFIG.storagePath mocked to a temp
+ * directory, so it never touches the real memory database. All coordination
+ * with the test parent uses explicit barrier files under the storage dir —
+ * never sleeps — and every wait is bounded so a broken handshake fails fast
+ * instead of hanging the suite.
+ *
+ * Env contract:
+ *   PLL_STORAGE  temp storage path (also hosts the coordination DB + barriers)
+ *   PLL_MODE     one of the modes below
+ *
+ * Modes:
+ *   hold          acquire; signal hs.acquired; wait hs.release; release;
+ *                 report held-before/after-release
+ *   try           wait hs.acquired (winner confirmed holding), attempt acquire,
+ *                 release immediately if won, report outcome
+ *   hold-forever  acquire; signal hs.acquired; wait until killed (SIGKILL test)
+ *   probe         single acquire attempt (live/EPERM/backdated/reuse/malformed/
+ *                 db-error scenarios); release if acquired
+ *   proc-probe    plant owner with pid whose /proc is absent (2^22), then
+ *                 force kill(0) outcome via PLL_FORCE_KILL env (EPERM|OK|ESRCH);
+ *                 report acquire result. EPERM injected by stubbing
+ *                 process.kill in-process — NOT by relying on PID 1 as root.
+ *   boot-variants  plant owner rows one at a time (valid-null, invalid-string,
+ *                 number, object, same-as-host) and report acquire result for
+ *                 each, releasing between attempts.
+ *   cas-race      signal hs.ready.<label>; wait hs.go; attempt acquire
+ *   stale-release acquire; flip owner_token to a simulated same-PID new owner;
+ *                 call the OLD release; report whether the row survived
+ *   release-twice acquire; release; release again; report idempotency
+ */
+import { mock } from "bun:test";
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as importedFs from "node:fs";
+import * as importedLibsql from "@libsql/client";
+
+const storage = process.env.PLL_STORAGE;
+const mode = process.env.PLL_MODE;
+const label = process.env.PLL_LABEL ?? "x";
+if (!storage || !mode) {
+  console.error("PLL_STORAGE and PLL_MODE are required");
+  process.exit(2);
+}
+
+// Captured BEFORE any mock.module call: once "node:fs" / "@libsql/client"
+// are mocked, re-importing them inside a factory would resolve the mock and
+// recurse. These constants pin the real live bindings for the wrappers.
+const realReadFileSync = importedFs.readFileSync;
+const realCreateClient = importedLibsql.createClient;
+
+const configUrl = new URL("../../src/config.js", import.meta.url).href;
+const loggerUrl = new URL("../../src/services/logger.js", import.meta.url).href;
+const lockUrl = new URL("../../src/services/user-profile/learning-lock.js", import.meta.url).href;
+
+mock.module(configUrl, () => ({
+  CONFIG: { storagePath: storage },
+  initConfig: () => {},
+  isConfigured: () => true,
+}));
+mock.module(loggerUrl, () => ({ log: () => {} }));
+
+// current-boot-invalid: the LOCAL machine's boot_id file reads as garbage.
+// The implementation must treat the local boot id as "unknown" and never use
+// it as a dead signal, even against a well-formed foreign boot id. node:fs
+// must be mocked before learning-lock.js is imported.
+if (mode === "current-boot-invalid") {
+  mock.module("node:fs", () => ({
+    ...importedFs,
+    readFileSync: (path: any, options: any) =>
+      path === "/proc/sys/kernel/random/boot_id"
+        ? "not-a-boot-id"
+        : realReadFileSync(path, options),
+  }));
+}
+// cas-race: wrap the REAL @libsql/client so both competitors provably act
+// on the same stale SELECT snapshot. The wrapper records the owner_token
+// each side's SELECT observed, and parks each side's UPDATE (the CAS)
+// behind a parent-controlled file gate. SQL execution stays 100% real;
+// only the interleaving is staged. Registered before learning-lock.js is
+// imported so the module under test picks up the wrapped client.
+let casSeenToken: string | null = null;
+let casLabel = "";
+if (mode === "cas-race") {
+  casLabel = label;
+  mock.module("@libsql/client", () => ({
+    ...importedLibsql,
+    createClient: (opts: any) => {
+      const client = realCreateClient(opts);
+      return {
+        ...client,
+        execute: async (stmt: any) => {
+          const sql: string = typeof stmt === "string" ? stmt : stmt.sql;
+          if (/^UPDATE\s+profile_learning_lock/i.test(sql)) {
+            // Both sides have read the same stale row; announce it and
+            // wait for the parent's gate before the CAS fires.
+            signal(barrier(`seen.${casLabel}`));
+            await waitFile(barrier("go.update"));
+          }
+          const result = await client.execute(stmt);
+          const after: string = typeof stmt === "string" ? stmt : stmt.sql;
+          if (/^SELECT\s+owner_token/i.test(after)) {
+            const row = result.rows[0] as Record<string, unknown> | undefined;
+            casSeenToken = row ? String(row["owner_token"]) : null;
+            writeFileSync(barrier(`token.${casLabel}`), casSeenToken ?? "none");
+          }
+          return result;
+        },
+        close: () => client.close(),
+      };
+    },
+  }));
+}
+const lock = await import(lockUrl);
+
+const barrier = (name: string) => join(storage, `hs.${name}`);
+const WAIT_MS = 30_000;
+
+async function waitFile(path: string): Promise<void> {
+  const deadline = Date.now() + WAIT_MS;
+  while (!existsSync(path)) {
+    if (Date.now() > deadline) throw new Error(`barrier timeout: ${path}`);
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+function signal(path: string): void {
+  writeFileSync(path, "ready");
+}
+
+function out(payload: Record<string, unknown>): void {
+  console.log(JSON.stringify(payload));
+}
+
+async function openDb() {
+  const client = realCreateClient({
+    url: `file:${join(storage, ".profile-learning-coordination.db")}`,
+  });
+  await client.execute("PRAGMA busy_timeout = 5000");
+  return client;
+}
+
+try {
+  switch (mode) {
+    case "hold": {
+      const release = await lock.tryAcquireProfileLearningLock("/project-hold");
+      if (!release) {
+        out({ acquired: false });
+        break;
+      }
+      const heldBefore = await lock.isProfileLearningLockHeld();
+      signal(barrier("acquired"));
+      await waitFile(barrier("release"));
+      await release();
+      const heldAfter = await lock.isProfileLearningLockHeld();
+      out({ acquired: true, heldBefore, heldAfter });
+      break;
+    }
+
+    case "try": {
+      // Do not attempt until the winner has confirmed it is holding; the
+      // parent only writes hs.release after this process exits, so the
+      // attempts provably overlap the winner's hold.
+      await waitFile(barrier("acquired"));
+      const release = await lock.tryAcquireProfileLearningLock("/project-try");
+      out({ acquired: release !== null });
+      if (release) await release();
+      break;
+    }
+
+    case "hold-forever": {
+      const release = await lock.tryAcquireProfileLearningLock("/project-forever");
+      if (!release) {
+        out({ acquired: false });
+        break;
+      }
+      signal(barrier("acquired"));
+      // Hold until the parent SIGKILLs this process; never release.
+      await waitFile(barrier("never"));
+      await release();
+      break;
+    }
+
+    case "probe": {
+      const release = await lock.tryAcquireProfileLearningLock("/project-probe");
+      out({ acquired: release !== null });
+      if (release) await release();
+      break;
+    }
+
+    case "cas-race": {
+      signal(barrier(`ready.${label}`));
+      await waitFile(barrier("go"));
+      // Inside acquire (wrapped @libsql/client): INSERT fails → SELECT reads
+      // the stale row (wrapper writes token.<label>) → UPDATE parks on the
+      // parent's go.update gate, so both CAS attempts are provably against
+      // the same observed stale token before either fires.
+      const release = await lock.tryAcquireProfileLearningLock("/project-race");
+      signal(barrier(`attempted.${label}`));
+      out({ acquired: release !== null });
+      if (release) {
+        const peer = label === "a" ? "b" : "a";
+        await waitFile(barrier(`attempted.${peer}`));
+        await release();
+      }
+      break;
+    }
+
+    case "proc-probe": {
+      // Owner pid is 2^22 (above every default pid_max → /proc absent). The
+      // kill(0) outcome is forced via PLL_LABEL (EPERM | OK | ESRCH),
+      // stubbed in-process — never by relying on PID 1 as root.
+      const forced = label;
+      if (forced === "EPERM" || forced === "OK" || forced === "ESRCH") {
+        const realKill = process.kill.bind(process);
+        process.kill = ((pid: number, signal?: number | string) => {
+          if (pid === 4194304) {
+            if (forced === "EPERM") {
+              const e = new Error(`kill EPERM`) as NodeJS.ErrnoException;
+              e.code = "EPERM";
+              throw e;
+            }
+            if (forced === "ESRCH") {
+              const e = new Error(`kill ESRCH`) as NodeJS.ErrnoException;
+              e.code = "ESRCH";
+              throw e;
+            }
+            return;
+          }
+          return realKill(pid, signal);
+        }) as typeof process.kill;
+      }
+      const release = await lock.tryAcquireProfileLearningLock("/project-probe");
+      out({ forced, acquired: release !== null });
+      if (release) await release();
+      break;
+    }
+
+    case "boot-variants": {
+      // For each variant: plant the owner row, attempt acquire, release if
+      // won. Verifies malformed boot_id fails closed while valid-null and
+      // same-as-host remain live (no reclaim), all with starttime set to
+      // this process's real starttime (a live, identity-verifiable owner).
+      const stat = realReadFileSync(`/proc/self/stat`, "utf-8");
+      const ownStarttime = String(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[22 - 3]);
+      const bootFile = realReadFileSync("/proc/sys/kernel/random/boot_id", "utf-8").trim();
+      const variants: Array<{ name: string; bootId: unknown; useRawSql?: string }> = [
+        { name: "validNull", bootId: null },
+        { name: "invalidString", bootId: "not-a-boot-id" },
+        { name: "number", bootId: 12345 },
+        // A non-string, non-null value cannot arrive via bind parameters, so
+        // plant it as a BLOB: it reads back as a byte array, exercising the
+        // "object-like" non-string branch of the validator.
+        {
+          name: "object",
+          bootId: null,
+          useRawSql: 'CAST(\'{"v":"x"}\' AS BLOB)',
+        },
+        { name: "sameAsHost", bootId: bootFile },
+      ];
+      const results: Record<string, boolean> = {};
+      for (const v of variants) {
+        const db = await openDb();
+        try {
+          await db.execute(`CREATE TABLE IF NOT EXISTS profile_learning_lock (
+            name TEXT PRIMARY KEY,
+            owner_token TEXT NOT NULL,
+            pid INTEGER NOT NULL,
+            boot_id TEXT,
+            starttime TEXT,
+            acquired_at INTEGER NOT NULL
+          )`);
+          // This worker process IS alive with a verifiable identity, so any
+          // no-reclaim outcome proves the live check worked rather than a
+          // parse refusal.
+          if (v.useRawSql !== undefined) {
+            await db.execute(`INSERT OR REPLACE INTO profile_learning_lock
+                    (name, owner_token, pid, boot_id, starttime, acquired_at)
+                  VALUES ('profile-learning', 'planted-${v.name}', ${process.pid}, ${v.useRawSql}, '${ownStarttime}', ${Date.now()})`);
+          } else {
+            await db.execute({
+              sql: `INSERT OR REPLACE INTO profile_learning_lock
+                    (name, owner_token, pid, boot_id, starttime, acquired_at)
+                  VALUES ('profile-learning', 'planted-${v.name}', ?, ?, ?, ?)`,
+              args: [process.pid, v.bootId, ownStarttime, Date.now()],
+            });
+          }
+        } finally {
+          db.close();
+        }
+        const release = await lock.tryAcquireProfileLearningLock("/project-boot");
+        results[v.name] = release !== null;
+        if (release) await release();
+      }
+      out({ variants: results });
+      break;
+    }
+
+    case "current-boot-invalid": {
+      // node:fs was mocked at module top (mode === "current-boot-invalid")
+      // so the LOCAL boot_id reads as garbage. The planted owner is THIS
+      // live worker (signal-probe OK), with a well-formed FOREIGN boot id
+      // and no starttime — boot comparison is the only possible dead
+      // signal, and an untrusted local boot id must never fire it.
+      const db = await openDb();
+      try {
+        await db.execute(`CREATE TABLE IF NOT EXISTS profile_learning_lock (
+          name TEXT PRIMARY KEY,
+          owner_token TEXT NOT NULL,
+          pid INTEGER NOT NULL,
+          boot_id TEXT,
+          starttime TEXT,
+          acquired_at INTEGER NOT NULL
+        )`);
+        await db.execute({
+          sql: `INSERT OR REPLACE INTO profile_learning_lock
+                  (name, owner_token, pid, boot_id, starttime, acquired_at)
+                VALUES ('profile-learning', 'planted-other-boot', ?, '11111111-2222-3333-4444-555555555555', NULL, ?)`,
+          args: [process.pid, Date.now()],
+        });
+      } finally {
+        db.close();
+      }
+      const release = await lock.tryAcquireProfileLearningLock("/project-boot");
+      out({ acquired: release !== null });
+      if (release) await release();
+      break;
+    }
+
+    case "stale-release": {
+      const release = await lock.tryAcquireProfileLearningLock("/project-stale");
+      if (!release) {
+        out({ acquired: false, stillHeld: null });
+        break;
+      }
+      // Simulate ownership having moved on with the SAME pid but a fresh
+      // token (e.g. re-claim after our death followed by pid reuse, or a
+      // supervisor respawning us). The old release must not drop that row.
+      const db = await openDb();
+      try {
+        await db.execute({
+          sql: `UPDATE profile_learning_lock SET owner_token = 'simulated-new-owner-token'
+                WHERE name = 'profile-learning'`,
+        });
+      } finally {
+        db.close();
+      }
+      await release();
+      const stillHeld = await lock.isProfileLearningLockHeld();
+      out({ acquired: true, stillHeld });
+      break;
+    }
+
+    case "release-twice": {
+      const release = await lock.tryAcquireProfileLearningLock("/project-twice");
+      if (!release) {
+        out({ acquired: false });
+        break;
+      }
+      await release();
+      await release(); // Must be a no-op, not an error.
+      out({ acquired: true, heldAfter: await lock.isProfileLearningLockHeld() });
+      break;
+    }
+
+    default: {
+      console.error(`unknown PLL_MODE: ${mode}`);
+      process.exit(2);
+    }
+  }
+} catch (error) {
+  out({ error: String(error) });
+  process.exit(1);
+}
diff --git a/tests/fixtures/profile-learning-memory-writer.mjs b/tests/fixtures/profile-learning-memory-writer.mjs
new file mode 100644
index 00000000..96c8cea3
--- /dev/null
+++ b/tests/fixtures/profile-learning-memory-writer.mjs
@@ -0,0 +1,132 @@
+//
+// Drives the REAL normal memory path — memoryClient.addMemory /
+// searchMemories / listMemories — in an isolated Bun child process against a
+// real temp storage tree, while another process (the profile-learning winner)
+// provably holds the profile-learning coordination lock.
+//
+// Mocked: only the external embedding service (fixed small vectors — no model
+// download, no paid API). NOT mocked: memoryClient, ensureTursoReady, the
+// turso shard/connection managers, scope write locks, or the SQLite writes
+// themselves — so this exercises the real gate the deployment cares about,
+// including the .turso-operation.lock path.
+//
+// Plain JavaScript on purpose: executed by `bun <file>.mjs`, not imported by
+// the test runner.
+//
+import { mock } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
+
+const cfgPath = process.argv[2];
+if (!cfgPath) {
+  console.error("usage: bun profile-learning-memory-writer.mjs <config.json>");
+  process.exit(2);
+}
+const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+
+const DIM = cfg.embeddingDim ?? 8;
+
+/** Fixed pseudo-random unit vector per text — deterministic, no model. */
+function fixedVector(text) {
+  const v = new Array(DIM);
+  let h = 2166136261;
+  for (const c of text) {
+    h ^= c.charCodeAt(0);
+    h = Math.imul(h, 16777619);
+  }
+  for (let i = 0; i < DIM; i++) {
+    h ^= h << 13;
+    h ^= h >>> 7;
+    h ^= h << 17;
+    v[i] = (((h >>> 0) % 2000) - 1000) / 1000;
+  }
+  const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0)) || 1;
+  return new Float32Array(v.map((x) => x / norm));
+}
+
+// Only the external embedding boundary is mocked. The service object shape
+// mirrors src/services/embedding.ts so client.ts keeps using its real logic.
+mock.module(new URL("../../src/services/embedding.js", import.meta.url).href, () => ({
+  embeddingService: {
+    embedWithTimeout: async (text) => fixedVector(text ?? ""),
+    warmup: async () => {},
+    isWarmedUp: true,
+    initError: null,
+  },
+}));
+
+const configUrl = new URL("../../src/config.js", import.meta.url).href;
+mock.module(configUrl, () => ({
+  CONFIG: {
+    storagePath: cfg.storagePath,
+    maxMemories: 100,
+    similarityThreshold: 0.0,
+    memoryDbShardSize: 1000,
+    // Must match the fixed vectors above so the real shard schema accepts them.
+    embeddingDimensions: DIM,
+    embeddingModel: "mock-fixed-vector",
+    maxVectorsPerShard: 1000,
+  },
+  initConfig: () => {},
+  isConfigured: () => true,
+}));
+
+const loggerUrl = new URL("../../src/services/logger.js", import.meta.url).href;
+mock.module(loggerUrl, () => ({ log: () => {} }));
+
+const counts = { add: 0, readback: 0, search: 0, list: 0 };
+let addedId = null;
+
+async function waitFile(path, timeoutMs = 30_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline && !existsSync(path)) {
+    await sleep(20);
+  }
+  if (!existsSync(path)) throw new Error(`writer: handshake file never appeared: ${path}`);
+}
+
+try {
+  const { memoryClient } = await import(
+    new URL("../../src/services/client.js", import.meta.url).href
+  );
+
+  // Block until the parent confirms the winner is provably holding the
+  // profile-learning lock, so the write below happens strictly inside the
+  // holding window — no sleep-based inference.
+  if (cfg.holdingFile) await waitFile(cfg.holdingFile);
+
+  const content = `ordinary memory ${cfg.marker ?? "writer"} ${Date.now()}`;
+  // Real format: {prefix}_{user|project}_{16hex} — validated by the real path.
+  const containerTag = `opencode_project_${cfg.projectHash ?? "0123456789abcdef"}`;
+
+  const add = await memoryClient.addMemory(content, containerTag, {
+    type: "preference",
+    source: "manual",
+    tags: ["service-lock-test"],
+    projectPath: cfg.projectPath ?? "/workspace",
+  });
+  if (add?.success) counts.add += 1;
+  addedId = add?.id ?? null;
+  // Read-back via the real search path (real SQLite read + vector search).
+  const search = await memoryClient.searchMemories(content, containerTag, "project");
+  if (search?.success) counts.search += 1;
+  if (search?.success && search.results?.some((r) => r.id === addedId)) counts.readback += 1;
+
+  const list = await memoryClient.listMemories(containerTag, 50, "project");
+  if (list?.success && list.memories?.some((m) => m.id === addedId)) counts.list += 1;
+
+  console.log(
+    JSON.stringify({
+      ok: true,
+      holdingObserved: Boolean(cfg.holdingFile),
+      addedId,
+      addError: add?.success ? undefined : (add?.error ?? "no id"),
+      counts,
+      searchTotal: search?.total ?? null,
+    })
+  );
+} catch (e) {
+  console.log(JSON.stringify({ fatal: e?.message ?? String(e), counts }));
+  process.exit(1);
+}
+process.exit(0);
diff --git a/tests/fixtures/profile-learning-service-worker.mjs b/tests/fixtures/profile-learning-service-worker.mjs
new file mode 100644
index 00000000..b759d6a5
--- /dev/null
+++ b/tests/fixtures/profile-learning-service-worker.mjs
@@ -0,0 +1,226 @@
+//
+// Runs the real performUserProfileLearning in an isolated Bun child process
+// against the real cross-process learning lock (real coordination storage via
+// CONFIG.storagePath). Only the provider/IO boundaries are mocked: the learning
+// service, the lock module, and the profile utils are the real compiled
+// sources. Driven by tests/profile-learning-service-lock.test.ts via a JSON
+// config file path in argv[2]; call events are appended as single-line JSON to
+// cfg.eventsFile so the parent can assert ordering across processes.
+//
+// Plain JavaScript on purpose: this file is executed by `bun <file>.mjs`, not
+// imported by the test runner.
+//
+import { mock } from "bun:test";
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
+
+const cfgPath = process.argv[2];
+if (!cfgPath) {
+  console.error("usage: bun profile-learning-service-worker.mjs <config.json>");
+  process.exit(2);
+}
+const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+
+function event(ev, data) {
+  appendFileSync(cfg.eventsFile, JSON.stringify({ ev, data: data ?? null }) + "\n");
+}
+
+/** Handshake wait for a file the parent creates — never a fixed sleep. */
+async function waitFile(path, timeoutMs = 30_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline && !existsSync(path)) {
+    await sleep(20);
+  }
+  if (!existsSync(path)) throw new Error(`worker: handshake file never appeared: ${path}`);
+}
+
+const learningUrl = new URL("../../src/services/user-memory-learning.js", import.meta.url).href;
+const configUrl = new URL("../../src/config.js", import.meta.url).href;
+const tagsUrl = new URL("../../src/services/tags.js", import.meta.url).href;
+const loggerUrl = new URL("../../src/services/logger.js", import.meta.url).href;
+const promptManagerUrl = new URL(
+  "../../src/services/user-prompt/user-prompt-manager.js",
+  import.meta.url
+).href;
+const profileManagerUrl = new URL(
+  "../../src/services/user-profile/user-profile-manager.js",
+  import.meta.url
+).href;
+const providerLoaderUrl = new URL(
+  "../../src/services/ai/opencode-provider-loader.js",
+  import.meta.url
+).href;
+const llmClientUrl = new URL("../../src/services/ai/profile-llm-client.js", import.meta.url).href;
+
+const promptCount = cfg.promptCount ?? 10;
+const prompts = Array.from({ length: promptCount }, (_, i) => ({
+  id: `prompt-${i}`,
+  sessionId: "session-1",
+  messageId: `msg-${i}`,
+  projectPath: cfg.projectPath ?? "/workspace",
+  content: `Implement feature ${i} with tests`,
+  createdAt: i + 1,
+  captured: true,
+  user_learning_captured: false,
+  capture_attempts: 0,
+}));
+
+const marked = new Set();
+
+mock.module(configUrl, () => ({
+  CONFIG: {
+    autoCaptureProviderStatus:
+      cfg.providerReady === false
+        ? { ready: false, issues: ["provider offline"] }
+        : { ready: true, mode: "opencode", issues: [] },
+    userProfileAnalysisInterval: cfg.threshold ?? 5,
+    opencodeProvider: "opencode-mock",
+    opencodeModel: "mock-model",
+    showUserProfileToasts: false,
+    userProfileValidationEnabled: false,
+    storagePath: cfg.storagePath,
+  },
+  initConfig: () => {},
+  isConfigured: () => true,
+}));
+
+mock.module(tagsUrl, () => ({
+  getTags: () => ({
+    user: {
+      tag: "opencode_user_test",
+      displayName: "Test User",
+      userName: "tester",
+      userEmail: "test@example.com",
+    },
+  }),
+}));
+
+// Route every log line into the event stream: the "skipped (another process
+// holds the learning lock)" label is how the parent proves the loser bounced
+// off the lock rather than silently doing nothing.
+mock.module(loggerUrl, () => ({
+  log: (label, data) => event("log", { label, data }),
+}));
+
+mock.module(promptManagerUrl, () => ({
+  userPromptManager: {
+    countUnanalyzedForUserLearning: async () => {
+      event("count");
+      return prompts.filter((p) => !marked.has(p.id)).length;
+    },
+    getPromptsForUserLearning: async (n) => {
+      event("select");
+      if (cfg.selectEmpty) return [];
+      return prompts.filter((p) => !marked.has(p.id)).slice(0, n);
+    },
+    markMultipleAsUserLearningCaptured: async (ids) => {
+      event("mark", { ids: [...ids] });
+      for (const id of ids) marked.add(id);
+    },
+  },
+}));
+
+mock.module(profileManagerUrl, () => ({
+  userProfileManager: {
+    getActiveProfile: async () => null,
+    createProfile: async (userId) => {
+      event("profile-write", { userId });
+      return { id: "profile-1", userId };
+    },
+    mergeProfileData: async (_existing, incoming) => incoming,
+    updateProfile: async () => true,
+    decayInMemory: (d) => ({ data: d }),
+    syncConfidence: () => {},
+    getProfileById: async () => null,
+    evolveAndUpdate: async () => {},
+  },
+}));
+
+mock.module(providerLoaderUrl, () => ({
+  loadOpencodeProvider: async () => ({
+    generateStructuredOutput: async () => {
+      event("llm-entered");
+      if (cfg.llmError) {
+        event("llm-error");
+        throw new Error("provider rejected: simulated refusal");
+      }
+      if (cfg.blockOnLlm) await waitFile(cfg.releaseFile);
+      event("llm-exit");
+      return {
+        preferences: [
+          {
+            category: "style",
+            description: "Prefers concise answers",
+            confidence: 0.5,
+            evidence: ["keep it short"],
+          },
+        ],
+        patterns: [],
+        workflows: [],
+      };
+    },
+  }),
+}));
+
+mock.module(llmClientUrl, () => ({
+  getOpenCodeClient: async () => ({}),
+}));
+
+const ctx = {};
+const directory = cfg.projectPath ?? "/workspace";
+
+async function runOnce() {
+  const { performUserProfileLearning } = await import(learningUrl);
+  await performUserProfileLearning(ctx, directory);
+}
+
+try {
+  switch (cfg.scenario) {
+    case "full":
+    case "early":
+    case "empty":
+    case "not-ready":
+      await runOnce();
+      console.log(JSON.stringify({ ok: true }));
+      break;
+    case "llm-error": {
+      let error = null;
+      try {
+        await runOnce();
+      } catch (e) {
+        error = e?.message ?? String(e);
+      }
+      console.log(JSON.stringify({ propagated: error !== null, error }));
+      break;
+    }
+    case "inproc-race": {
+      const { performUserProfileLearning } = await import(learningUrl);
+      const runs = await Promise.allSettled([
+        performUserProfileLearning(ctx, directory),
+        performUserProfileLearning(ctx, directory),
+      ]);
+      console.log(JSON.stringify({ ok: true, statuses: runs.map((r) => r.status) }));
+      break;
+    }
+    case "error-then-retry": {
+      const { performUserProfileLearning } = await import(learningUrl);
+      cfg.llmError = true; // first pass fails inside the LLM
+      let firstError = null;
+      try {
+        await performUserProfileLearning(ctx, directory);
+      } catch (e) {
+        firstError = e?.message ?? String(e);
+      }
+      cfg.llmError = false; // second run in the same process must succeed
+      await performUserProfileLearning(ctx, directory);
+      console.log(JSON.stringify({ ok: true, firstError }));
+      break;
+    }
+    default:
+      throw new Error(`worker: unknown scenario ${cfg.scenario}`);
+  }
+} catch (e) {
+  console.log(JSON.stringify({ fatal: e?.message ?? String(e) }));
+  process.exit(1);
+}
+process.exit(0);
diff --git a/tests/fixtures/profile-learning-storage-error-worker.mjs b/tests/fixtures/profile-learning-storage-error-worker.mjs
new file mode 100644
index 00000000..19c460b5
--- /dev/null
+++ b/tests/fixtures/profile-learning-storage-error-worker.mjs
@@ -0,0 +1,321 @@
+//
+// Storage-error worker for tests/profile-learning-storage-error.test.ts.
+//
+// Runs the REAL performUserProfileLearning in an isolated Bun child process
+// against the REAL cross-process learning lock (real coordination DB via
+// CONFIG.storagePath in a temp dir). Only external boundaries are mocked:
+// the LLM providers (native opencode + external AIProviderFactory) and the
+// profile manager. The learning service, the lock module, and the lock's
+// SQL are the real compiled sources.
+//
+// Driven by a JSON config path in argv[2]; events are appended as
+// single-line JSON to cfg.eventsFile so the parent can assert exact call
+// counts (externalCalls/update/mark) across processes.
+//
+// Plain JavaScript on purpose: executed by `bun <file>.mjs`, not imported
+// by the test runner.
+//
+import { mock } from "bun:test";
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
+
+const cfgPath = process.argv[2];
+if (!cfgPath) {
+  console.error("usage: bun profile-learning-storage-error-worker.mjs <config.json>");
+  process.exit(2);
+}
+const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+
+function event(ev, data) {
+  appendFileSync(cfg.eventsFile, JSON.stringify({ ev, data: data ?? null }) + "\n");
+}
+
+async function waitFile(path, timeoutMs = 30_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline && !existsSync(path)) {
+    await sleep(20);
+  }
+  if (!existsSync(path)) throw new Error(`worker: handshake file never appeared: ${path}`);
+}
+
+const learningUrl = new URL("../../src/services/user-memory-learning.js", import.meta.url).href;
+const configUrl = new URL("../../src/config.js", import.meta.url).href;
+const tagsUrl = new URL("../../src/services/tags.js", import.meta.url).href;
+const loggerUrl = new URL("../../src/services/logger.js", import.meta.url).href;
+const promptManagerUrl = new URL(
+  "../../src/services/user-prompt/user-prompt-manager.js",
+  import.meta.url
+).href;
+const profileManagerUrl = new URL(
+  "../../src/services/user-profile/user-profile-manager.js",
+  import.meta.url
+).href;
+const providerLoaderUrl = new URL(
+  "../../src/services/ai/opencode-provider-loader.js",
+  import.meta.url
+).href;
+const llmClientUrl = new URL("../../src/services/ai/profile-llm-client.js", import.meta.url).href;
+const providerFactoryUrl = new URL("../../src/services/ai/ai-provider-factory.js", import.meta.url)
+  .href;
+const providerConfigUrl = new URL("../../src/services/ai/provider-config.js", import.meta.url).href;
+
+const promptCount = cfg.promptCount ?? 10;
+const prompts = Array.from({ length: promptCount }, (_, i) => ({
+  id: `prompt-${i}`,
+  sessionId: "session-1",
+  messageId: `msg-${i}`,
+  projectPath: cfg.projectPath ?? "/workspace",
+  content: `Implement feature ${i} with tests`,
+  createdAt: i + 1,
+  captured: true,
+  user_learning_captured: false,
+  capture_attempts: 0,
+}));
+
+const marked = new Set();
+
+// A well-formed stored profile: every consumer between lock acquisition and
+// analyzeUserProfile's merge (decay, category summary, change summary)
+// JSON.parses profileData, so it must be valid with the three arrays.
+const VALID_STORED_PROFILE = {
+  id: "stored-profile-1",
+  userId: "test@example.com",
+  profileData: JSON.stringify({
+    preferences: [
+      {
+        category: "style",
+        description: "Prefers concise answers",
+        confidence: 0.7,
+        evidence: ["keep it short"],
+      },
+    ],
+    patterns: [],
+    workflows: [],
+  }),
+  totalPromptsAnalyzed: 5,
+};
+
+mock.module(configUrl, () => ({
+  CONFIG: {
+    autoCaptureProviderStatus: { ready: true, mode: "opencode", issues: [] },
+    userProfileAnalysisInterval: cfg.threshold ?? 5,
+    opencodeProvider: "opencode-mock",
+    opencodeModel: "mock-model",
+    showUserProfileToasts: false,
+    userProfileValidationEnabled: false,
+    // external fallback configured so the fallback path is REACHABLE — the
+    // point of these scenarios is that storage errors must NOT reach it.
+    memoryModel: "external-mock",
+    memoryApiUrl: "https://external.invalid/v1",
+    memoryProvider: "openai-chat",
+    storagePath: cfg.storagePath,
+  },
+  initConfig: () => {},
+  isConfigured: () => true,
+}));
+
+mock.module(tagsUrl, () => ({
+  getTags: () => ({
+    user: {
+      tag: "opencode_user_test",
+      displayName: "Test User",
+      userName: "tester",
+      userEmail: "test@example.com",
+    },
+  }),
+}));
+
+mock.module(loggerUrl, () => ({
+  log: (label, data) => event("log", { label, data }),
+}));
+
+mock.module(promptManagerUrl, () => ({
+  userPromptManager: {
+    countUnanalyzedForUserLearning: async () => {
+      event("count");
+      return prompts.filter((p) => !marked.has(p.id)).length;
+    },
+    getPromptsForUserLearning: async (n) => {
+      event("select");
+      return prompts.filter((p) => !marked.has(p.id)).slice(0, n);
+    },
+    markMultipleAsUserLearningCaptured: async (ids) => {
+      event("mark", { ids: [...ids] });
+      for (const id of ids) marked.add(id);
+    },
+  },
+}));
+
+const PROFILE_READ_ERROR = new Error("storage read failed: simulated cold DB fault");
+const PROFILE_MERGE_ERROR = new Error("storage merge failed: simulated cold DB fault");
+
+mock.module(profileManagerUrl, () => ({
+  userProfileManager: {
+    getActiveProfile: async () => {
+      event("get-active-profile");
+      if (cfg.getProfileError) throw PROFILE_READ_ERROR;
+      if (cfg.existingProfile === false) return null;
+      if (cfg.corruptProfileData) {
+        return { ...VALID_STORED_PROFILE, profileData: "{not valid json" };
+      }
+      return VALID_STORED_PROFILE;
+    },
+    createProfile: async (userId) => {
+      event("profile-write", { userId });
+      return { id: "profile-1", userId };
+    },
+    mergeProfileData: async (...args) => {
+      event("merge");
+      if (cfg.mergeError) throw PROFILE_MERGE_ERROR;
+      return args[1];
+    },
+    updateProfile: async (profileId, data, promptCountArg, summary) => {
+      event("update", { profileId, promptCount: promptCountArg, summary });
+      return true;
+    },
+    decayInMemory: (d) => ({ data: d }),
+    syncConfidence: () => {},
+    getProfileById: async () => null,
+    evolveAndUpdate: async () => {},
+  },
+}));
+
+mock.module(providerLoaderUrl, () => ({
+  loadOpencodeProvider: async () => ({
+    generateStructuredOutput: async () => {
+      event("native-llm");
+      if (cfg.nativeError) {
+        event("native-llm-error");
+        throw new Error("provider rejected: simulated native refusal");
+      }
+      if (cfg.blockOnLlm) await waitFile(cfg.releaseFile);
+      return {
+        preferences: [
+          {
+            category: "style",
+            description: "Prefers concise answers",
+            confidence: 0.5,
+            evidence: ["keep it short"],
+          },
+        ],
+        patterns: [],
+        workflows: [],
+      };
+    },
+  }),
+}));
+
+mock.module(llmClientUrl, () => ({
+  getOpenCodeClient: async () => ({}),
+}));
+
+// External fallback boundary: if the production bug were still present, a
+// storage error would be misread as a provider fault and land HERE.
+mock.module(providerFactoryUrl, () => ({
+  AIProviderFactory: {
+    createProvider: () => ({
+      executeToolCall: async () => {
+        event("external-llm");
+        if (cfg.externalError) {
+          return { success: false, error: "external provider failed" };
+        }
+        return {
+          success: true,
+          data: {
+            preferences: [
+              {
+                category: "style",
+                description: "Prefers verbose answers",
+                confidence: 0.5,
+                evidence: ["explain more"],
+              },
+            ],
+            patterns: [],
+            workflows: [],
+          },
+        };
+      },
+    }),
+  },
+}));
+
+mock.module(providerConfigUrl, () => ({
+  buildMemoryProviderConfig: () => ({}),
+}));
+
+const ctx = {};
+const directory = cfg.projectPath ?? "/workspace";
+
+function eventsOf(list, ev) {
+  return list.filter((e) => e.ev === ev);
+}
+
+async function collectEvents() {
+  if (!existsSync(cfg.eventsFile)) return [];
+  return readFileSync(cfg.eventsFile, "utf8")
+    .split("\n")
+    .filter((l) => l.trim().length > 0)
+    .map((l) => JSON.parse(l));
+}
+
+try {
+  const { performUserProfileLearning } = await import(learningUrl);
+  const { tryAcquireProfileLearningLock } =
+    await import("../../src/services/user-profile/learning-lock.js");
+
+  let error = null;
+  try {
+    await performUserProfileLearning(ctx, directory);
+  } catch (e) {
+    error = e?.message ?? String(e);
+  }
+
+  const events = await collectEvents();
+
+  if (cfg.holdLockFirst) {
+    // Prove the release completed: after performUserProfileLearning returns
+    // (or throws), the coordination lock must be acquirable again, and a
+    // second run in the SAME process must be allowed to proceed.
+    const release = await tryAcquireProfileLearningLock(directory);
+    const reacquired = release !== null;
+    if (release) await release();
+    let secondRunError = null;
+    try {
+      cfg.mergeError = false;
+      cfg.getProfileError = false;
+      cfg.nativeError = false;
+      await performUserProfileLearning(ctx, directory);
+    } catch (e) {
+      secondRunError = e?.message ?? String(e);
+    }
+    const after = await collectEvents();
+    console.log(
+      JSON.stringify({
+        error,
+        reacquired,
+        secondRunError,
+        externalCalls: eventsOf(events, "external-llm").length,
+        updates: eventsOf(events, "update").length,
+        marks: eventsOf(events, "mark").length,
+        merges: eventsOf(events, "merge").length,
+        nativeCalls: eventsOf(events, "native-llm").length,
+        secondRunMarks: eventsOf(after, "mark").length - eventsOf(events, "mark").length,
+      })
+    );
+  } else {
+    console.log(
+      JSON.stringify({
+        error,
+        externalCalls: eventsOf(events, "external-llm").length,
+        updates: eventsOf(events, "update").length,
+        marks: eventsOf(events, "mark").length,
+        merges: eventsOf(events, "merge").length,
+        nativeCalls: eventsOf(events, "native-llm").length,
+      })
+    );
+  }
+} catch (e) {
+  console.log(JSON.stringify({ fatal: e?.message ?? String(e) }));
+  process.exit(1);
+}
+process.exit(0);
diff --git a/tests/profile-cold-buffer-cross-process.test.ts b/tests/profile-cold-buffer-cross-process.test.ts
new file mode 100644
index 00000000..8eddd629
--- /dev/null
+++ b/tests/profile-cold-buffer-cross-process.test.ts
@@ -0,0 +1,512 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import {
+  chmodSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  unlinkSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { tursoConnectionManager } from "../src/services/turso/connection-manager.js";
+
+// Cross-process cold-buffer safety: two real, independent UserProfileManager
+// instances over one shared storagePath simulate peer learning processes. All
+// assertions go through the public mergeProfileData / deleteProfile surface and
+// use a mocked embedding boundary (no real model download, no network LLM).
+//
+// Every case that should prove persistence actually triggers a save on disk —
+// a merge with empty incoming arrays would never write and would pass even
+// with the refresh fix removed (forbidden false coverage).
+
+let tmpDir: string;
+let coldBufferFile: string;
+const extraDirs: string[] = [];
+
+async function makeManager(dir: string = tmpDir) {
+  const { CONFIG } = await import("../src/config.js");
+  // Keep LLM-backed dedup/conflict checks inert (no provider configured).
+  delete CONFIG.opencodeProvider;
+  delete CONFIG.opencodeModel;
+  delete CONFIG.memoryModel;
+  delete CONFIG.memoryApiUrl;
+  CONFIG.storagePath = dir;
+  CONFIG.userProfileEmbeddingMinDescriptionLength = 5;
+  const { UserProfileManager } =
+    await import("../src/services/user-profile/user-profile-manager.js");
+  return new UserProfileManager();
+}
+
+// Embedding not warmed up -> non-explicit items are buffered (cold start).
+const coldEmbed = { isWarmedUp: false } as any;
+// Warmed up -> buffered items drain into the merge.
+const warmEmbed = {
+  isWarmedUp: true,
+  embed: async () => new Float32Array(8).fill(0.25),
+} as any;
+
+const empty = () => ({ preferences: [], patterns: [], workflows: [] });
+const pref = (description: string) => ({ category: "style", description });
+const readDisk = () => JSON.parse(readFileSync(coldBufferFile, "utf-8"));
+const descs = (bucket: any) => bucket.preferences.map((p: any) => p.description);
+
+async function coldPush(mgr: any, profileId: string, description: string) {
+  // Real public merge that buffers a non-explicit item and persists it.
+  await mgr.mergeProfileData(empty(), { preferences: [pref(description)] }, coldEmbed, profileId);
+}
+
+describe("cold buffer cross-process safety", () => {
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "opencode-mem-coldbuf-xproc-"));
+    coldBufferFile = join(tmpDir, "cold-buffer.json");
+  });
+
+  afterEach(async () => {
+    await tursoConnectionManager.closeAll();
+    await new Promise((r) => setTimeout(r, 50));
+    // Restore permissions first in case a failure left a read-only dir behind.
+    try {
+      chmodSync(tmpDir, 0o700);
+    } catch {
+      // ignore
+    }
+    for (const dir of extraDirs.splice(0)) {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // ignore leftover test files
+      }
+    }
+    try {
+      rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      // ignore leftover test files
+    }
+  });
+
+  it("sees a peer's bucket when the file mtime is held fixed (no mtime-based refresh)", async () => {
+    const a = await makeManager(); // peer process
+    const b = await makeManager(); // this process
+
+    // b persists its own bucket first, so an mtime-guarded implementation
+    // would cache a "newer than the peer's write" mtime.
+    await coldPush(b, "profile_B", "b own observation");
+    expect(readDisk()["profile_B"].preferences).toHaveLength(1);
+
+    // Peer writes its bucket; the file mtime is then pinned to a fixed past
+    // timestamp (same-mtime / stalled-clock world).
+    await coldPush(a, "profile_A", "a peer observation");
+    utimesSync(coldBufferFile, 1_000_000, 1_000_000);
+
+    // b's next merge must start from the on-disk snapshot: pushing a new
+    // bucket persists the whole snapshot, so A's bucket must survive it.
+    await coldPush(b, "profile_C", "c later observation");
+
+    const disk = readDisk();
+    expect(descs(disk["profile_A"])).toContain("a peer observation");
+    expect(descs(disk["profile_B"])).toContain("b own observation");
+    expect(descs(disk["profile_C"])).toContain("c later observation");
+  });
+
+  it("still reads peer updates when the file mtime goes backwards", async () => {
+    const a = await makeManager();
+    const b = await makeManager();
+
+    await coldPush(b, "profile_B", "b first observation");
+    await coldPush(a, "profile_A", "a peer observation after rollback");
+    // Clock rollback: file now looks "older" than b's cached write.
+    utimesSync(coldBufferFile, 1, 1);
+
+    await coldPush(b, "profile_B", "b second observation");
+
+    const disk = readDisk();
+    expect(descs(disk["profile_A"])).toContain("a peer observation after rollback");
+    expect(descs(disk["profile_B"])).toHaveLength(2);
+  });
+
+  it("does not resurrect a deleted cold-buffer file from a stale in-memory map", async () => {
+    const b = await makeManager();
+    await coldPush(b, "profile_GONE", "stale bucket entry that must not resurrect");
+    expect(readDisk()["profile_GONE"]).toBeDefined();
+
+    // File removed underneath us (peer cleanup / storage reset).
+    unlinkSync(coldBufferFile);
+
+    await coldPush(b, "profile_NEW", "fresh after delete");
+
+    const disk = readDisk();
+    expect(disk["profile_GONE"]).toBeUndefined();
+    expect(descs(disk["profile_NEW"])).toContain("fresh after delete");
+  });
+
+  it("fails closed on a corrupt cold-buffer file instead of overwriting it", async () => {
+    const b = await makeManager();
+    const corrupt = "{not valid json";
+    writeFileSync(coldBufferFile, corrupt, "utf-8");
+
+    // Constructing a manager over a corrupt cache must not crash (plugin
+    // import path stays fail-safe)...
+    const { UserProfileManager } =
+      await import("../src/services/user-profile/user-profile-manager.js");
+    expect(() => new UserProfileManager()).not.toThrow();
+
+    // ...but a merge round must refuse to treat unknown data as empty.
+    await expect(
+      b.mergeProfileData(
+        empty(),
+        { preferences: [pref("must not be persisted over unknown data")] },
+        coldEmbed,
+        "profile_X"
+      )
+    ).rejects.toThrow();
+    expect(readFileSync(coldBufferFile, "utf-8")).toBe(corrupt);
+  });
+
+  it("fails closed on an empty or whitespace-only cold-buffer file", async () => {
+    for (const raw of ["", "   ", "\n\t"]) {
+      tmpDir = mkdtempSync(join(tmpdir(), "opencode-mem-coldbuf-xproc-"));
+      coldBufferFile = join(tmpDir, "cold-buffer.json");
+      writeFileSync(coldBufferFile, raw, "utf-8");
+      try {
+        const b = await makeManager();
+        await expect(
+          b.mergeProfileData(
+            empty(),
+            { preferences: [pref("never persisted")] },
+            coldEmbed,
+            "profile_BLANK"
+          )
+        ).rejects.toThrow();
+        expect(readFileSync(coldBufferFile, "utf-8")).toBe(raw);
+      } finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+      }
+    }
+    // Recreate the beforeEach dir so afterEach cleanup stays balanced.
+    tmpDir = mkdtempSync(join(tmpdir(), "opencode-mem-coldbuf-xproc-"));
+    coldBufferFile = join(tmpDir, "cold-buffer.json");
+  });
+
+  it("fails closed on invalid bucket shapes without touching the file bytes", async () => {
+    const invalid: Array<{ name: string; raw: string }> = [
+      { name: "bucket null", raw: JSON.stringify({ profile_N: null }) },
+      { name: "bucket scalar", raw: JSON.stringify({ profile_N: "oops" }) },
+      {
+        name: "category not an array",
+        raw: JSON.stringify({ profile_N: { preferences: "nope" } }),
+      },
+      { name: "item null", raw: JSON.stringify({ profile_N: { preferences: [null] } }) },
+      { name: "item not an object", raw: JSON.stringify({ profile_N: { patterns: [42] } }) },
+      {
+        name: "item without string description",
+        raw: JSON.stringify({ profile_N: { workflows: [{ category: "x" }] } }),
+      },
+      {
+        name: "legacy keys mixed with profile buckets",
+        raw: JSON.stringify({ preferences: [], profile_N: { patterns: [] } }),
+      },
+      {
+        name: "legacy category not an array",
+        raw: JSON.stringify({ preferences: "not-an-array" }),
+      },
+    ];
+
+    for (const { name, raw } of invalid) {
+      tmpDir = mkdtempSync(join(tmpdir(), "opencode-mem-coldbuf-xproc-"));
+      coldBufferFile = join(tmpDir, "cold-buffer.json");
+      writeFileSync(coldBufferFile, raw, "utf-8");
+      try {
+        const b = await makeManager();
+        let err: unknown;
+        try {
+          await b.mergeProfileData(
+            empty(),
+            { preferences: [pref("never persisted")] },
+            coldEmbed,
+            "profile_BADSHAPE"
+          );
+        } catch (e) {
+          err = e;
+        }
+        expect(err).toBeInstanceOf(Error);
+        expect(readFileSync(coldBufferFile, "utf-8")).toBe(raw);
+        // No tmp leftovers from a failed round.
+        expect(readdirSync(tmpDir).filter((f) => f.includes(".tmp"))).toHaveLength(0);
+        void name;
+      } finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+      }
+    }
+    tmpDir = mkdtempSync(join(tmpdir(), "opencode-mem-coldbuf-xproc-"));
+    coldBufferFile = join(tmpDir, "cold-buffer.json");
+  });
+
+  it("accepts a valid snapshot and a valid legacy flat file", async () => {
+    // Valid per-profile snapshot loads, merges and persists without loss.
+    writeFileSync(
+      coldBufferFile,
+      JSON.stringify({
+        profile_KEEP: {
+          preferences: [pref("snapshot item kept")],
+          patterns: [],
+          workflows: [],
+        },
+      }),
+      "utf-8"
+    );
+    const b = await makeManager();
+    await coldPush(b, "profile_KEEP", "second snapshot item");
+    const disk = readDisk();
+    expect(descs(disk["profile_KEEP"])).toContain("snapshot item kept");
+    expect(descs(disk["profile_KEEP"])).toContain("second snapshot item");
+
+    // Valid legacy flat file: accepted (dropped by documented policy), and a
+    // subsequent merge persists a fresh per-profile snapshot — not rejected.
+    rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = mkdtempSync(join(tmpdir(), "opencode-mem-coldbuf-xproc-"));
+    coldBufferFile = join(tmpDir, "cold-buffer.json");
+    writeFileSync(
+      coldBufferFile,
+      JSON.stringify({ preferences: [pref("legacy item")], patterns: [], workflows: [] }),
+      "utf-8"
+    );
+    const c = await makeManager();
+    await coldPush(c, "profile_AFTER_LEGACY", "after legacy drop");
+    const disk2 = readDisk();
+    expect(descs(disk2["profile_AFTER_LEGACY"])).toContain("after legacy drop");
+  });
+
+  it("completes a save across byte-granular short writes (ascii + multibyte)", async () => {
+    const run = (mode: string, dir: string, desc: string, preExisting: string) => {
+      const result = Bun.spawnSync({
+        cmd: [
+          process.execPath,
+          "--preload",
+          join(import.meta.dir, "fixtures", "profile-cold-buffer-worker-preload.ts"),
+          join(import.meta.dir, "fixtures", "profile-cold-buffer-worker-shortwrite.ts"),
+          "SWMODE=" + mode,
+          dir,
+          "profile_SW",
+          desc,
+          preExisting,
+        ],
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      const stdout = Buffer.from(result.stdout).toString("utf8").trim();
+      const stderr = Buffer.from(result.stderr).toString("utf8").trim();
+      const jsonLine = stdout
+        .split("\n")
+        .reverse()
+        .find((line) => line.trim().startsWith("{"));
+      if (!jsonLine) throw new Error(`worker produced no JSON: ${stderr}`);
+      return { ...JSON.parse(jsonLine), stderr, exitCode: result.exitCode };
+    };
+
+    for (const mode of ["short-ascii", "short-utf8"] as const) {
+      const desc =
+        mode === "short-utf8" ? "用户偏好：简洁中文回答并附带代码示例" : "plain ascii observation";
+      const dir = mkdtempSync(join(tmpdir(), "opencode-mem-coldbuf-sw-"));
+      extraDirs.push(dir);
+      const r = run(mode, dir, desc, "");
+      expect(r.ok).toBe(true);
+      expect(r.tmpLeft).toBe(0);
+      // The persisted bytes must parse and round-trip the exact description —
+      // a byte-offset bug would slice multi-byte chars into invalid sequences.
+      const parsed = JSON.parse(r.targetBytes as string);
+      expect(parsed["profile_SW"].preferences[0].description).toBe(desc);
+    }
+  });
+
+  it("throws on write() returning 0 and leaves the previous target bytes intact", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "opencode-mem-coldbuf-sw-"));
+    extraDirs.push(dir);
+    const preExisting = JSON.stringify({
+      profile_PRE: { preferences: [pref("previous entry")], patterns: [], workflows: [] },
+    });
+    const result = Bun.spawnSync({
+      cmd: [
+        process.execPath,
+        "--preload",
+        join(import.meta.dir, "fixtures", "profile-cold-buffer-worker-preload.ts"),
+        join(import.meta.dir, "fixtures", "profile-cold-buffer-worker-shortwrite.ts"),
+        "SWMODE=zero",
+        dir,
+        "profile_SW",
+        "entry that cannot be written",
+        preExisting,
+      ],
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const stdout = Buffer.from(result.stdout).toString("utf8").trim();
+    const jsonLine = stdout
+      .split("\n")
+      .reverse()
+      .find((line) => line.trim().startsWith("{"));
+    if (!jsonLine) throw new Error(Buffer.from(result.stderr).toString("utf8"));
+    const r = JSON.parse(jsonLine);
+    expect(r.ok).toBe(false);
+    expect(r.error).toContain("write stalled");
+    expect(r.targetBytes).toBe(preExisting);
+    expect(r.tmpLeft).toBe(0);
+  });
+
+  it("throws on a mid-payload write error and leaves the previous target bytes intact", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "opencode-mem-coldbuf-sw-"));
+    extraDirs.push(dir);
+    const preExisting = JSON.stringify({
+      profile_PRE: { preferences: [pref("previous entry")], patterns: [], workflows: [] },
+    });
+    const result = Bun.spawnSync({
+      cmd: [
+        process.execPath,
+        "--preload",
+        join(import.meta.dir, "fixtures", "profile-cold-buffer-worker-preload.ts"),
+        join(import.meta.dir, "fixtures", "profile-cold-buffer-worker-shortwrite.ts"),
+        "SWMODE=half",
+        dir,
+        "profile_SW",
+        "entry that fails halfway through the payload",
+        preExisting,
+      ],
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const stdout = Buffer.from(result.stdout).toString("utf8").trim();
+    const jsonLine = stdout
+      .split("\n")
+      .reverse()
+      .find((line) => line.trim().startsWith("{"));
+    if (!jsonLine) throw new Error(Buffer.from(result.stderr).toString("utf8"));
+    const r = JSON.parse(jsonLine);
+    expect(r.ok).toBe(false);
+    expect(r.targetBytes).toBe(preExisting);
+    expect(r.tmpLeft).toBe(0);
+  });
+
+  it.skipIf(process.getuid?.() === 0)(
+    "fails closed when the cold-buffer file is unreadable and leaves it untouched",
+    async () => {
+      const b = await makeManager();
+      await coldPush(b, "profile_P", "existing peer data");
+      chmodSync(coldBufferFile, 0o000);
+      try {
+        await expect(
+          b.mergeProfileData(
+            empty(),
+            { preferences: [pref("must not overwrite")] },
+            coldEmbed,
+            "profile_Q"
+          )
+        ).rejects.toThrow();
+      } finally {
+        chmodSync(coldBufferFile, 0o600);
+      }
+
+      const disk = readDisk();
+      expect(descs(disk["profile_P"])).toContain("existing peer data");
+      expect(disk["profile_Q"]).toBeUndefined();
+    }
+  );
+
+  it.skipIf(process.getuid?.() === 0)(
+    "propagates save failures without corrupting the existing file",
+    async () => {
+      const b = await makeManager();
+      await coldPush(b, "profile_S", "already persisted entry");
+      const before = readFileSync(coldBufferFile, "utf-8");
+
+      chmodSync(tmpDir, 0o500); // dir readable but not writable -> tmp create fails
+      let err: unknown;
+      try {
+        err = await b
+          .mergeProfileData(
+            empty(),
+            { preferences: [pref("entry that cannot be saved")] },
+            coldEmbed,
+            "profile_T"
+          )
+          .catch((e) => e);
+      } finally {
+        chmodSync(tmpDir, 0o700);
+      }
+
+      expect(err).toBeInstanceOf(Error);
+      // Atomic write: the failed round leaves the previous content intact.
+      expect(readFileSync(coldBufferFile, "utf-8")).toBe(before);
+      // A later successful round persists new data without losing the old.
+      await coldPush(b, "profile_T", "retry entry");
+      const disk = readDisk();
+      expect(descs(disk["profile_T"])).toContain("retry entry");
+      expect(descs(disk["profile_S"])).toContain("already persisted entry");
+    }
+  );
+
+  it("keeps every pending buffer mutation from one merge round on disk", async () => {
+    const b = await makeManager();
+    await b.mergeProfileData(
+      empty(),
+      {
+        preferences: [pref("pref observation")],
+        patterns: [{ category: "style", description: "pattern observation" }],
+        workflows: [{ category: "style", description: "workflow observation" }],
+      },
+      coldEmbed,
+      "profile_MULTI"
+    );
+
+    const bucket = readDisk()["profile_MULTI"];
+    expect(bucket.preferences).toHaveLength(1);
+    expect(bucket.patterns).toHaveLength(1);
+    expect(bucket.workflows).toHaveLength(1);
+  });
+
+  it("reset() drops the previous storage's buckets instead of writing them to the new storage", async () => {
+    const { CONFIG } = await import("../src/config.js");
+    const dir2 = mkdtempSync(join(tmpdir(), "opencode-mem-coldbuf-xproc-2-"));
+    extraDirs.push(dir2);
+
+    const b = await makeManager(tmpDir);
+    await coldPush(b, "profile_OLD", "belongs to the old storage");
+    expect(readFileSync(join(tmpDir, "cold-buffer.json"), "utf-8")).toContain("profile_OLD");
+
+    CONFIG.storagePath = dir2;
+    b.reset();
+    await coldPush(b, "profile_NEW", "belongs to the new storage");
+
+    const disk2 = JSON.parse(readFileSync(join(dir2, "cold-buffer.json"), "utf-8"));
+    expect(descs(disk2["profile_NEW"])).toContain("belongs to the new storage");
+    expect(disk2["profile_OLD"]).toBeUndefined();
+  });
+
+  it("deleteProfile removes the bucket from the current on-disk snapshot", async () => {
+    const a = await makeManager();
+    const b = await makeManager(); // constructed before any file exists
+    await coldPush(a, "profile_KEEP", "kept bucket");
+    await coldPush(a, "profile_DOOM", "doomed bucket");
+
+    await b.deleteProfile("profile_DOOM");
+
+    const disk = readDisk();
+    expect(disk["profile_DOOM"]).toBeUndefined();
+    expect(descs(disk["profile_KEEP"])).toContain("kept bucket");
+  });
+
+  it("a warm merge drains a peer-buffered bucket through the real merge path", async () => {
+    const a = await makeManager(); // peer buffers while its embedding is cold
+    const b = await makeManager();
+
+    await coldPush(a, "profile_W", "peer buffered a warm-drainable observation");
+    // Peer file mtime pinned in the past must not hide the bucket from b.
+    utimesSync(coldBufferFile, 1_000_000, 1_000_000);
+
+    const merged = await b.mergeProfileData(empty(), { preferences: [] }, warmEmbed, "profile_W");
+    expect(descs(merged)).toContain("peer buffered a warm-drainable observation");
+    // Drained bucket is empty when persisted -> omitted from disk, not resurrected.
+    expect(readDisk()["profile_W"]).toBeUndefined();
+  });
+});
diff --git a/tests/profile-learning-lock.test.ts b/tests/profile-learning-lock.test.ts
index ca717755..1bfc8509 100644
--- a/tests/profile-learning-lock.test.ts
+++ b/tests/profile-learning-lock.test.ts
@@ -1,7 +1,9 @@
 import { afterAll, describe, expect, it } from "bun:test";
-import { existsSync, mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { createClient } from "@libsql/client";
+import { PROFILE_LEARNING_COORDINATION_DB } from "../src/services/user-profile/learning-lock.js";
 
 const tempDirs: string[] = [];
 
@@ -15,11 +17,9 @@ afterAll(() => {
   }
 });
 
-const lockUrl = new URL("../src/services/user-profile/learning-lock.js", import.meta.url).href;
-const configUrl = new URL("../src/config.js", import.meta.url).href;
-const loggerUrl = new URL("../src/services/logger.js", import.meta.url).href;
-
-const LOCK_FILE = ".profile-learning.lock";
+const WORKER = join(import.meta.dir, "fixtures", "profile-learning-lock-worker.mts");
+const HAS_PROC = existsSync("/proc/self/stat");
+const HAS_BOOT_ID = existsSync("/proc/sys/kernel/random/boot_id");
 
 function storage(): string {
   const dir = mkdtempSync(join(tmpdir(), "opencode-mem-learning-lock-"));
@@ -27,254 +27,355 @@ function storage(): string {
   return dir;
 }
 
-function preamble(storagePath: string): string {
-  return `
-import { mock } from "bun:test";
-mock.module(${JSON.stringify(configUrl)}, () => ({
-  CONFIG: { storagePath: ${JSON.stringify(storagePath)} },
-  initConfig: () => {},
-  isConfigured: () => true,
-}));
-mock.module(${JSON.stringify(loggerUrl)}, () => ({ log: () => {} }));
-const lock = await import(${JSON.stringify(lockUrl)});
-`;
+function barrierPath(dir: string, name: string): string {
+  return join(dir, `hs.${name}`);
+}
+
+async function waitBarrier(dir: string, name: string, timeoutMs = 30_000): Promise<void> {
+  const path = barrierPath(dir, name);
+  const deadline = Date.now() + timeoutMs;
+  while (!existsSync(path)) {
+    if (Date.now() > deadline) throw new Error(`barrier timeout: ${path}`);
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+interface WorkerResult {
+  exitCode: number | null;
+  stderr: string;
+  parsed: Record<string, unknown> | null;
+}
+
+interface WorkerProc {
+  result: Promise<WorkerResult>;
+  kill: (signal?: number | string) => void;
+  exited: Promise<number>;
 }
 
-function runScript(dir: string, name: string, body: string) {
-  const scriptPath = join(dir, name);
-  writeFileSync(scriptPath, body);
-  const result = Bun.spawnSync({
-    cmd: [process.execPath, scriptPath],
+function spawnWorker(dir: string, mode: string, label = "x"): WorkerProc {
+  const proc = Bun.spawn({
+    cmd: [process.execPath, WORKER],
+    env: { ...process.env, PLL_STORAGE: dir, PLL_MODE: mode, PLL_LABEL: label },
     stdout: "pipe",
     stderr: "pipe",
   });
-  const stdout = Buffer.from(result.stdout).toString("utf8").trim();
+  const result = (async (): Promise<WorkerResult> => {
+    const stdout = (await new Response(proc.stdout).text()).trim();
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    const exitCode = await proc.exited;
+    let parsed: Record<string, unknown> | null = null;
+    const lines = stdout.split("\n").filter((l) => l.trim().length > 0);
+    const last = lines[lines.length - 1];
+    if (last) {
+      try {
+        parsed = JSON.parse(last) as Record<string, unknown>;
+      } catch {
+        parsed = null;
+      }
+    }
+    return { exitCode, stderr, parsed };
+  })();
   return {
-    exitCode: result.exitCode,
-    stderr: Buffer.from(result.stderr).toString("utf8").trim(),
-    stdout,
-    parsed: stdout ? JSON.parse(stdout) : null,
+    result,
+    kill: (signal?: number | string) => proc.kill(signal ?? ("SIGKILL" as const)),
+    exited: proc.exited,
   };
 }
 
-/**
- * Spawns two real processes that contend for the lock at the same time.
- *
- * Both wait on a shared start barrier before acquiring, so the acquisitions
- * genuinely overlap. Running two promises in one process would only exercise the
- * in-process guard and would pass even with no cross-process lock at all.
- */
-function runContention(storagePath: string, barrierPath: string) {
-  const worker = (label: string) => `
-${preamble(storagePath)}
-import { existsSync, writeFileSync, readFileSync } from "node:fs";
-
-writeFileSync(${JSON.stringify(barrierPath)} + ".${label}", "ready");
-const peers = ["a", "b"].map((p) => ${JSON.stringify(barrierPath)} + "." + p);
-const deadline = Date.now() + 10_000;
-while (Date.now() < deadline && !peers.every((p) => existsSync(p))) {
-  await new Promise((r) => setTimeout(r, 5));
+async function runProbe(dir: string): Promise<WorkerResult> {
+  const worker = spawnWorker(dir, "probe");
+  return worker.result;
 }
 
-const release = lock.tryAcquireProfileLearningLock("/project-${label}");
-if (release) {
-  // Hold the lock long enough that the peer's attempt provably overlaps.
-  await new Promise((r) => setTimeout(r, 600));
-  release();
+/** Opens the coordination DB directly (fixture setup / assertions). */
+async function withDb<T>(
+  dir: string,
+  fn: (db: ReturnType<typeof createClient>) => Promise<T>
+): Promise<T> {
+  const db = createClient({ url: `file:${join(dir, PROFILE_LEARNING_COORDINATION_DB)}` });
+  try {
+    await db.execute("PRAGMA busy_timeout = 5000");
+    return await fn(db);
+  } finally {
+    db.close();
+  }
 }
-console.log(JSON.stringify({ acquired: release !== null }));
-`;
-
-  const dir = storagePath;
-  writeFileSync(join(dir, "worker-a.mjs"), worker("a"));
-  writeFileSync(join(dir, "worker-b.mjs"), worker("b"));
-
-  const spawn = (file: string) =>
-    Bun.spawn({
-      cmd: [process.execPath, join(dir, file)],
-      stdout: "pipe",
-      stderr: "pipe",
+
+interface PlantedOwner {
+  ownerToken?: string;
+  pid: number;
+  bootId?: string | null;
+  starttime?: string | null;
+  acquiredAt?: number;
+}
+
+async function plantOwner(dir: string, owner: PlantedOwner): Promise<void> {
+  await withDb(dir, async (db) => {
+    await db.execute(`CREATE TABLE IF NOT EXISTS profile_learning_lock (
+      name TEXT PRIMARY KEY,
+      owner_token TEXT NOT NULL,
+      pid INTEGER NOT NULL,
+      boot_id TEXT,
+      starttime TEXT,
+      acquired_at INTEGER NOT NULL
+    )`);
+    await db.execute({
+      sql: `INSERT OR REPLACE INTO profile_learning_lock
+              (name, owner_token, pid, boot_id, starttime, acquired_at)
+            VALUES ('profile-learning', ?, ?, ?, ?, ?)`,
+      args: [
+        owner.ownerToken ?? "planted-owner-token",
+        owner.pid,
+        owner.bootId ?? null,
+        owner.starttime ?? null,
+        owner.acquiredAt ?? Date.now(),
+      ],
     });
+  });
+}
+
+function readBootId(): string {
+  return readFileSync("/proc/sys/kernel/random/boot_id", "utf-8").trim();
+}
 
-  const a = spawn("worker-a.mjs");
-  const b = spawn("worker-b.mjs");
-  return Promise.all(
-    [a, b].map(async (proc) => {
-      const out = (await new Response(proc.stdout).text()).trim();
-      await proc.exited;
-      return out ? (JSON.parse(out) as { acquired: boolean }) : null;
-    })
-  );
+/** Field 22 of /proc/<pid>/stat (comm may contain spaces/parens). */
+function readStarttime(pid: number): string {
+  const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+  const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+  return String(fields[22 - 3]);
+}
+
+async function currentOwnerToken(dir: string): Promise<string | null> {
+  return withDb(dir, async (db) => {
+    const result = await db.execute(
+      `SELECT owner_token FROM profile_learning_lock WHERE name = 'profile-learning'`
+    );
+    const row = result.rows[0] as Record<string, unknown> | undefined;
+    return row ? String(row["owner_token"]) : null;
+  });
 }
 
-describe("cross-process profile learning lock", () => {
-  it("grants the lock to exactly one of two concurrent processes", async () => {
+describe("cross-process profile learning lock (SQL coordination DB)", () => {
+  it("grants the lock to exactly one process and release frees it for the next", async () => {
     const dir = storage();
-    const results = await runContention(dir, join(dir, "barrier"));
 
-    const granted = results.filter((r) => r?.acquired).length;
-    expect(results).toHaveLength(2);
-    expect(granted).toBe(1);
+    const winner = spawnWorker(dir, "hold");
+    // Only attempt once the winner has confirmed it is holding.
+    await waitBarrier(dir, "acquired");
+
+    const loser = spawnWorker(dir, "try");
+    // The loser's attempt fully completes (process exits) before release.
+    const loserResult = await loser.result;
+    expect(loserResult.exitCode).toBe(0);
+    expect(loserResult.parsed).toEqual({ acquired: false });
+
+    writeFileSync(barrierPath(dir, "release"), "ready");
+    const winnerResult = await winner.result;
+    expect(winnerResult.exitCode).toBe(0);
+    // held before release, not held after — and heldBefore is the winner's
+    // own row, not a leftover from a previous owner.
+    expect(winnerResult.parsed).toEqual({ acquired: true, heldBefore: true, heldAfter: false });
+
+    // The freed lock is acquirable again.
+    const again = await runProbe(dir);
+    expect(again.parsed).toEqual({ acquired: true });
   }, 45_000);
 
-  it("releases the lock so a later process can acquire it", () => {
+  it("release is idempotent", async () => {
     const dir = storage();
+    const result = await spawnWorker(dir, "release-twice").result;
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed).toEqual({ acquired: true, heldAfter: false });
+  }, 30_000);
 
-    const first = runScript(
-      dir,
-      "acquire-release.mjs",
-      `
-${preamble(dir)}
-const release = lock.tryAcquireProfileLearningLock("/project-a");
-release?.();
-const second = lock.tryAcquireProfileLearningLock("/project-a");
-console.log(JSON.stringify({ first: release !== null, second: second !== null }));
-second?.();
-`
-    );
+  it("never steals a live lock, even held past 30 minutes", async () => {
+    const dir = storage();
+    // This test process is alive and its identity is fully verifiable, so
+    // the lock is live under any reading. The age must play no role.
+    await plantOwner(dir, {
+      pid: process.pid,
+      bootId: HAS_BOOT_ID ? readBootId() : null,
+      starttime: HAS_PROC ? readStarttime(process.pid) : null,
+      acquiredAt: Date.now() - 31 * 60 * 1000,
+    });
 
-    expect(first.exitCode).toBe(0);
-    expect(first.parsed).toEqual({ first: true, second: true });
-    expect(existsSync(join(dir, LOCK_FILE))).toBe(false);
-  }, 20_000);
+    const result = await runProbe(dir);
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed).toEqual({ acquired: false });
+    // The live owner's row is untouched.
+    expect(await currentOwnerToken(dir)).toBe("planted-owner-token");
+  }, 30_000);
 
-  it("reclaims a lock whose holder process no longer exists", () => {
+  it("never steals a lock owned by a process we cannot signal (EPERM)", async () => {
     const dir = storage();
-    // PID 2^22 is above every Linux/macOS pid_max default, so it cannot be live.
-    writeFileSync(
-      join(dir, LOCK_FILE),
-      JSON.stringify({ pid: 4194304, acquiredAt: Date.now(), directory: "/dead" })
-    );
-
-    const result = runScript(
-      dir,
-      "reclaim-dead.mjs",
-      `
-${preamble(dir)}
-const release = lock.tryAcquireProfileLearningLock("/project-a");
-console.log(JSON.stringify({ acquired: release !== null }));
-release?.();
-`
-    );
+    // PID 1 is alive and owned by root; kill(1, 0) yields EPERM for a
+    // non-root caller. No startup identity is recorded, so the
+    // implementation must fall back to the signal probe and treat EPERM
+    // as "alive, not reclaimable".
+    await plantOwner(dir, { pid: 1, starttime: null, acquiredAt: Date.now() });
 
+    const result = await runProbe(dir);
     expect(result.exitCode).toBe(0);
-    expect(result.parsed).toEqual({ acquired: true });
-  }, 20_000);
+    expect(result.parsed).toEqual({ acquired: false });
+    expect(await currentOwnerToken(dir)).toBe("planted-owner-token");
+  }, 30_000);
 
-  it("reclaims a lock held past the staleness deadline", () => {
+  it("exactly one of two competitors CAS-reclaims the same dead owner", async () => {
     const dir = storage();
-    writeFileSync(
-      join(dir, LOCK_FILE),
-      JSON.stringify({
-        pid: process.pid,
-        acquiredAt: Date.now() - 31 * 60 * 1000,
-        directory: "/stalled",
-      })
-    );
+    // 2^22 exceeds every default Linux pid_max, so it can never be live.
+    await plantOwner(dir, { pid: 4194304, acquiredAt: Date.now() });
+
+    const a = spawnWorker(dir, "cas-race", "a");
+    const b = spawnWorker(dir, "cas-race", "b");
+    await waitBarrier(dir, "ready.a");
+    await waitBarrier(dir, "ready.b");
+    writeFileSync(barrierPath(dir, "go"), "ready");
+
+    // Both sides must have observed the SAME stale owner token before
+    // either CAS fires; the wrapped client parks each UPDATE until
+    // go.update, making the shared-snapshot precondition deterministic.
+    await waitBarrier(dir, "seen.a");
+    await waitBarrier(dir, "seen.b");
+    const tokenA = readFileSync(barrierPath(dir, "token.a"), "utf-8");
+    const tokenB = readFileSync(barrierPath(dir, "token.b"), "utf-8");
+    expect(tokenA).toBe(tokenB);
+    expect(tokenA).toBe("planted-owner-token");
+    writeFileSync(barrierPath(dir, "go.update"), "ready");
+
+    const [ra, rb] = await Promise.all([a.result, b.result]);
+    expect(ra.exitCode).toBe(0);
+    expect(rb.exitCode).toBe(0);
+    // CAS on the same observed old owner_token: exactly one UPDATE wins.
+    const acquired = [ra.parsed?.["acquired"], rb.parsed?.["acquired"]].filter(Boolean);
+    expect(acquired).toHaveLength(1);
+    // The winner released on exit, so the lock is free again.
+    expect(await currentOwnerToken(dir)).toBeNull();
+  }, 60_000);
+
+  it("a stale release cannot drop a new owner's row, even with the same PID", async () => {
+    const dir = storage();
+    const result = await spawnWorker(dir, "stale-release").result;
+    expect(result.exitCode).toBe(0);
+    // acquired:true means the old token was valid at release time, and
+    // stillHeld:true means the simulated new owner's row survived the old
+    // release (DELETE is conditional on the owner token).
+    expect(result.parsed).toEqual({ acquired: true, stillHeld: true });
+    expect(await currentOwnerToken(dir)).toBe("simulated-new-owner-token");
+  }, 30_000);
+
+  it("recovers the lock after the holder is SIGKILLed without releasing", async () => {
+    const dir = storage();
+    const holder = spawnWorker(dir, "hold-forever");
+    await waitBarrier(dir, "acquired");
 
-    const result = runScript(
-      dir,
-      "reclaim-stale.mjs",
-      `
-${preamble(dir)}
-const release = lock.tryAcquireProfileLearningLock("/project-a");
-console.log(JSON.stringify({ acquired: release !== null }));
-release?.();
-`
-    );
+    holder.kill("SIGKILL");
+    await holder.exited;
 
+    // The killed process is provably gone (/proc/<pid> absent), so a new
+    // process must be able to take over.
+    const result = await runProbe(dir);
     expect(result.exitCode).toBe(0);
     expect(result.parsed).toEqual({ acquired: true });
-  }, 20_000);
+  }, 45_000);
 
-  it("does not steal a lock file that is still being written", () => {
+  it("reclaims a live PID only when the startup identity differs (PID reuse)", async () => {
     const dir = storage();
-    // A truncated file is what a reader can observe between the `wx` create and
-    // the content write. Reclaiming it immediately would hand the lock to a
-    // second process while the first believes it holds it.
-    writeFileSync(join(dir, LOCK_FILE), "{");
-
-    const result = runScript(
-      dir,
-      "write-window.mjs",
-      `
-${preamble(dir)}
-const release = lock.tryAcquireProfileLearningLock("/project-a");
-console.log(JSON.stringify({ acquired: release !== null }));
-release?.();
-`
-    );
+    // This test process is alive, but the recorded starttime belongs to a
+    // previous inhabitant of this PID — reuse must be detected by identity,
+    // not by age (acquired_at is fresh).
+    await plantOwner(dir, {
+      pid: process.pid,
+      bootId: HAS_BOOT_ID ? readBootId() : null,
+      starttime: "1",
+      acquiredAt: Date.now(),
+    });
 
+    const result = await runProbe(dir);
     expect(result.exitCode).toBe(0);
-    expect(result.parsed).toEqual({ acquired: false });
-  }, 20_000);
+    expect(result.parsed).toEqual({ acquired: true });
+    expect(await currentOwnerToken(dir)).toBeNull();
+  }, 30_000);
 
-  it("reclaims a corrupt lock file once the write window has passed", () => {
+  it("reclaims an owner from a previous boot even though its PID is alive now", async () => {
     const dir = storage();
-    const lockFile = join(dir, LOCK_FILE);
-    writeFileSync(lockFile, "{");
-    const stale = new Date(Date.now() - 60_000);
-    // Backdate past WRITE_WINDOW_MS so the file reads as corrupt, not mid-write.
-    utimesSync(lockFile, stale, stale);
-
-    const result = runScript(
-      dir,
-      "corrupt-expired.mjs",
-      `
-${preamble(dir)}
-const release = lock.tryAcquireProfileLearningLock("/project-a");
-console.log(JSON.stringify({ acquired: release !== null }));
-release?.();
-`
-    );
+    await plantOwner(dir, {
+      pid: process.pid,
+      bootId: "00000000-0000-0000-0000-000000000000",
+      starttime: HAS_PROC ? readStarttime(process.pid) : null,
+      acquiredAt: Date.now(),
+    });
 
+    const result = await runProbe(dir);
     expect(result.exitCode).toBe(0);
     expect(result.parsed).toEqual({ acquired: true });
-  }, 20_000);
+  }, 30_000);
 
-  it("keeps a live holder's lock and records its identity", () => {
+  it("fails closed on malformed coordination state", async () => {
     const dir = storage();
+    // pid 0 can never identify a process; the record is structurally
+    // invalid and must be treated as untrustworthy, not as a free lock.
+    await plantOwner(dir, { pid: 0, acquiredAt: Date.now() });
 
-    const result = runScript(
-      dir,
-      "held.mjs",
-      `
-${preamble(dir)}
-import { readFileSync } from "node:fs";
-const release = lock.tryAcquireProfileLearningLock("/project-a");
-console.log(JSON.stringify({
-  held: lock.isProfileLearningLockHeld(),
-  pid: JSON.parse(readFileSync(${JSON.stringify(join(dir, LOCK_FILE))}, "utf-8")).pid === process.pid,
-}));
-release?.();
-`
-    );
+    const result = await runProbe(dir);
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed).toEqual({ acquired: false });
+    expect(await currentOwnerToken(dir)).toBe("planted-owner-token");
+  }, 30_000);
+
+  it("proc ENOENT alone never kills; only the kill probe decides", async () => {
+    // Owner pid 4194304 → /proc/<pid>/stat absent in every environment.
+    // A non-null starttime makes the checker take the proc-stat branch and
+    // hit the absent → kill-probe fallthrough for real (a null starttime
+    // would take the direct signal-probe path instead).
+    // PLL_LABEL injects the exact kill(0) outcome in-process:
+    //   EPERM (hidepid=2 live holder) → false
+    //   OK    (live)                   → false
+    //   ESRCH (dead)                   → true (reclaimed)
+    const outcomes: Record<string, boolean> = {};
+    for (const forced of ["EPERM", "OK", "ESRCH"] as const) {
+      const caseDir = storage();
+      await plantOwner(caseDir, {
+        pid: 4194304,
+        starttime: "999999",
+        acquiredAt: Date.now(),
+      });
+      const worker = spawnWorker(caseDir, "proc-probe", forced);
+      const result = await worker.result;
+      expect(result.exitCode).toBe(0);
+      expect(result.parsed).toEqual({ forced, acquired: forced === "ESRCH" });
+      outcomes[forced] = Boolean(result.parsed?.["acquired"]);
+    }
+    expect(outcomes).toEqual({ EPERM: false, OK: false, ESRCH: true });
+  }, 60_000);
+
+  it("boot_id variants: malformed fails closed; valid-null and same-as-host stay live", async () => {
+    const dir = storage();
+    const result = await spawnWorker(dir, "boot-variants").result;
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed?.["variants"]).toEqual({
+      validNull: false,
+      invalidString: false,
+      number: false,
+      object: false,
+      sameAsHost: false,
+    });
+  }, 60_000);
 
+  it("an untrusted local boot_id never acts as a dead signal", async () => {
+    const dir = storage();
+    const result = await spawnWorker(dir, "current-boot-invalid").result;
     expect(result.exitCode).toBe(0);
-    expect(result.parsed).toEqual({ held: true, pid: true });
-  }, 20_000);
+    expect(result.parsed).toEqual({ acquired: false });
+  }, 30_000);
 
-  it("does not release a lock that now belongs to another process", () => {
+  it("fails closed when the coordination database cannot be opened", async () => {
     const dir = storage();
-    const lockFile = join(dir, LOCK_FILE);
-
-    const result = runScript(
-      dir,
-      "foreign-release.mjs",
-      `
-${preamble(dir)}
-import { writeFileSync } from "node:fs";
-const release = lock.tryAcquireProfileLearningLock("/project-a");
-// Simulate the lock having been reclaimed by a different live process.
-writeFileSync(${JSON.stringify(lockFile)}, JSON.stringify({
-  pid: 4194304, acquiredAt: Date.now(), directory: "/other",
-}));
-release?.();
-console.log(JSON.stringify({ stillPresent: true }));
-`
-    );
+    // A directory where the DB file should be makes every statement fail;
+    // acquisition must degrade to null (skip this round), not throw.
+    mkdirSync(join(dir, PROFILE_LEARNING_COORDINATION_DB));
 
+    const result = await runProbe(dir);
     expect(result.exitCode).toBe(0);
-    expect(readFileSync(lockFile, "utf-8")).toContain("4194304");
-  }, 20_000);
+    expect(result.parsed).toEqual({ acquired: false });
+  }, 30_000);
 });
diff --git a/tests/profile-learning-service-lock.test.ts b/tests/profile-learning-service-lock.test.ts
new file mode 100644
index 00000000..c09e5a73
--- /dev/null
+++ b/tests/profile-learning-service-lock.test.ts
@@ -0,0 +1,345 @@
+import { afterAll, describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Real two-process concurrency test for performUserProfileLearning.
+ *
+ * Both children run the REAL learning service and the REAL cross-process lock
+ * (real coordination storage under CONFIG.storagePath — the same mechanism the
+ * deployed plugin uses). Only provider/IO boundaries are mocked (LLM provider,
+ * prompt manager, profile manager). Neither the service nor the lock is ever
+ * mocked.
+ *
+ * The winner blocks inside the LLM call on a parent-created handshake file, so
+ * the lock is provably held across a real await; no fixed sleep keeps it alive.
+ */
+const tempDirs: string[] = [];
+
+afterAll(() => {
+  for (const dir of tempDirs) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // Best-effort cleanup.
+    }
+  }
+});
+
+const WORKER = new URL("./fixtures/profile-learning-service-worker.mjs", import.meta.url).pathname;
+const MEMORY_WRITER = new URL("./fixtures/profile-learning-memory-writer.mjs", import.meta.url)
+  .pathname;
+
+interface WorkerEvent {
+  ev: string;
+  data: any;
+}
+
+interface WorkerResult {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  events: WorkerEvent[];
+  eventsFile: string;
+}
+
+function readEvents(path: string): WorkerEvent[] {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf8")
+    .split("\n")
+    .filter((l) => l.trim().startsWith("{"))
+    .map((l) => JSON.parse(l) as WorkerEvent);
+}
+
+function tmpDir(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+}
+
+let spawnSeq = 0;
+
+/**
+ * Spawns one worker. `dir` doubles as the shared lock storage (CONFIG.storagePath)
+ * and the scratch space for that worker's config + private event log, so every
+ * event is attributable to exactly one process and one run.
+ */
+function spawnWorker(
+  dir: string,
+  name: string,
+  cfg: Record<string, unknown>
+): { done: Promise<WorkerResult>; eventsFile: string } {
+  const workerName = `${name}-${++spawnSeq}`;
+  const eventsFile = join(dir, `events-${workerName}.ndjson`);
+  const cfgPath = join(dir, `worker-${name}.json`);
+  writeFileSync(cfgPath, JSON.stringify({ ...cfg, eventsFile }));
+  const proc = Bun.spawn({
+    cmd: [process.execPath, WORKER, cfgPath],
+    stdout: "pipe",
+    stderr: "pipe",
+    // Isolate HOME so no child can touch the real ~/.opencode-mem even if some
+    // transitive import resolves a path outside CONFIG.storagePath.
+    env: { ...process.env, HOME: dir, XDG_DATA_HOME: join(dir, "xdg-data") },
+  });
+  const done = (async (): Promise<WorkerResult> => {
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const exitCode = await proc.exited;
+    return {
+      exitCode,
+      stdout: stdout.trim(),
+      stderr: stderr.trim(),
+      events: readEvents(eventsFile),
+      eventsFile,
+    };
+  })();
+  return { done, eventsFile };
+}
+
+async function runScenario(
+  scenario: string,
+  overrides: Record<string, unknown> = {},
+  dir?: string
+): Promise<WorkerResult & { dir: string }> {
+  const base = dir ?? tmpDir("opencode-mem-service-lock-");
+  const { done } = spawnWorker(base, "solo", { scenario, storagePath: base, ...overrides });
+  const r = await done;
+  return { ...r, dir: base };
+}
+
+function countEv(r: { events: WorkerEvent[] }, ev: string): number {
+  return r.events.filter((e) => e.ev === ev).length;
+}
+
+function findLog(r: { events: WorkerEvent[] }, needle: string): WorkerEvent | undefined {
+  return r.events.find((e) => e.ev === "log" && String(e.data?.label ?? "").includes(needle));
+}
+
+/** Polls a worker's private event log until `ev` appears — handshake, not sleep. */
+async function waitForEvent(eventsFile: string, ev: string, timeoutMs = 30_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (readEvents(eventsFile).some((e) => e.ev === ev)) return true;
+    await new Promise((r) => setTimeout(r, 20));
+  }
+  return false;
+}
+
+/** Runs one .mjs fixture (worker or memory-writer) with a JSON config. */
+function runFixture(
+  fixturePath: string,
+  dir: string,
+  name: string,
+  cfg: Record<string, unknown>
+): {
+  done: Promise<{ exitCode: number | null; stdout: string; stderr: string }>;
+  eventsFile: string;
+} {
+  const eventsFile = join(dir, `events-${name}.ndjson`);
+  const cfgPath = join(dir, `${name}.json`);
+  writeFileSync(cfgPath, JSON.stringify({ ...cfg, eventsFile }));
+  const proc = Bun.spawn({
+    cmd: [process.execPath, fixturePath, cfgPath],
+    stdout: "pipe",
+    stderr: "pipe",
+    // Isolate HOME so no child can touch the real ~/.opencode-mem even if some
+    // transitive import resolves a path outside CONFIG.storagePath.
+    env: { ...process.env, HOME: dir, XDG_DATA_HOME: join(dir, "xdg-data") },
+  });
+  const done = (async () => {
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const exitCode = await proc.exited;
+    return { exitCode, stdout: stdout.trim(), stderr: stderr.trim() };
+  })();
+  return { done, eventsFile };
+}
+
+describe("performUserProfileLearning cross-process service lock", () => {
+  it("serializes two real learning runs: loser touches no SELECT/LLM/write/mark", async () => {
+    const dir = tmpDir("opencode-mem-service-lock-2p-");
+    const releaseFile = join(dir, "release");
+
+    // Winner: blocks inside the LLM handshake until the parent releases it.
+    const winner = spawnWorker(dir, "winner", {
+      scenario: "full",
+      storagePath: dir,
+      blockOnLlm: true,
+      releaseFile,
+    });
+
+    // Wait until the winner is provably holding the lock (it entered the LLM,
+    // which only happens under the lock) before starting the loser.
+    expect(await waitForEvent(winner.eventsFile, "llm-entered")).toBe(true);
+
+    const loser = spawnWorker(dir, "loser", { scenario: "full", storagePath: dir });
+    const loserResult = await loser.done;
+
+    // Only after the loser has finished its attempt may the winner be released.
+    writeFileSync(releaseFile, "go");
+    const winnerResult = await winner.done;
+
+    expect(winnerResult.exitCode).toBe(0);
+    expect(loserResult.exitCode).toBe(0);
+    expect(loserResult.stderr).toBe("");
+    expect(winnerResult.stderr).toBe("");
+
+    // The loser must have bounced off the lock — never into the pipeline.
+    expect(findLog(loserResult, "another process holds")).toBeDefined();
+    expect(countEv(loserResult, "count")).toBe(0);
+    expect(countEv(loserResult, "select")).toBe(0);
+    expect(countEv(loserResult, "llm-entered")).toBe(0);
+    expect(countEv(loserResult, "profile-write")).toBe(0);
+    expect(countEv(loserResult, "mark")).toBe(0);
+
+    // Across both processes the pipeline ran exactly once end-to-end.
+    const all = [...winnerResult.events, ...loserResult.events];
+    const total = (ev: string) => all.filter((e) => e.ev === ev).length;
+    expect(total("llm-entered")).toBe(1);
+    expect(total("llm-exit")).toBe(1);
+    expect(total("profile-write")).toBe(1);
+    expect(total("mark")).toBe(1);
+  }, 120_000);
+
+  it("releases the lock on the below-threshold early return", async () => {
+    const dir = tmpDir("opencode-mem-service-lock-th-");
+    const r1 = await runScenario("early", { threshold: 100, promptCount: 10 }, dir);
+    expect(r1.exitCode).toBe(0);
+    expect(r1.stderr).toBe("");
+    expect(countEv(r1, "count")).toBe(1);
+    expect(countEv(r1, "llm-entered")).toBe(0);
+
+    // Same storage, fresh process: the lock must be acquirable (released, not leaked).
+    const r2 = await runScenario("full", {}, dir);
+    expect(r2.exitCode).toBe(0);
+    expect(findLog(r2, "another process holds")).toBeUndefined();
+    expect(countEv(r2, "count")).toBe(1);
+    expect(countEv(r2, "llm-entered")).toBe(1);
+  }, 60_000);
+
+  it("releases the lock when the prompt batch comes back empty", async () => {
+    const dir = tmpDir("opencode-mem-service-lock-empty-");
+    const r1 = await runScenario("empty", { selectEmpty: true }, dir);
+    expect(r1.exitCode).toBe(0);
+    expect(r1.stderr).toBe("");
+    expect(countEv(r1, "count")).toBe(1);
+    expect(countEv(r1, "select")).toBe(1);
+    // Empty batch: early return after select, before the LLM.
+    expect(countEv(r1, "llm-entered")).toBe(0);
+    expect(countEv(r1, "mark")).toBe(0);
+
+    const r2 = await runScenario("full", {}, dir);
+    expect(r2.exitCode).toBe(0);
+    expect(findLog(r2, "another process holds")).toBeUndefined();
+    expect(countEv(r2, "llm-entered")).toBe(1);
+  }, 60_000);
+
+  it("releases the lock when the provider is not ready", async () => {
+    const dir = tmpDir("opencode-mem-service-lock-nr-");
+    const r1 = await runScenario("not-ready", { providerReady: false }, dir);
+    expect(r1.exitCode).toBe(0);
+    expect(r1.stderr).toBe("");
+    expect(findLog(r1, "provider not ready")).toBeDefined();
+    expect(countEv(r1, "count")).toBe(0);
+
+    // The guard fires before acquisition, but the next process must sail through.
+    const r2 = await runScenario("full", {}, dir);
+    expect(r2.exitCode).toBe(0);
+    expect(countEv(r2, "llm-entered")).toBe(1);
+  }, 60_000);
+
+  it("propagates a provider LLM error and the lock is acquirable again", async () => {
+    const dir = tmpDir("opencode-mem-service-lock-err-");
+    const r1 = await runScenario("llm-error", { llmError: true }, dir);
+    expect(r1.exitCode).toBe(0);
+    expect(r1.stderr).toBe("");
+    const out = JSON.parse(r1.stdout);
+    expect(out.propagated).toBe(true);
+    expect(out.error).toContain("provider rejected");
+    expect(countEv(r1, "llm-entered")).toBe(1);
+    expect(countEv(r1, "mark")).toBe(0);
+
+    // Fresh process must be able to take the lock — the error path released it.
+    const r2 = await runScenario("full", {}, dir);
+    expect(r2.exitCode).toBe(0);
+    expect(findLog(r2, "another process holds")).toBeUndefined();
+    expect(countEv(r2, "llm-entered")).toBe(1);
+    expect(countEv(r2, "mark")).toBe(1);
+  }, 60_000);
+
+  it("runs once when the same process calls concurrently (flag set before first await)", async () => {
+    const r = await runScenario("inproc-race");
+    expect(r.exitCode).toBe(0);
+    expect(r.stderr).toBe("");
+    const out = JSON.parse(r.stdout);
+    expect(out.statuses).toEqual(["fulfilled", "fulfilled"]);
+    // Exactly one run entered the pipeline; the second bounced off the flag.
+    expect(countEv(r, "count")).toBe(1);
+    expect(countEv(r, "llm-entered")).toBe(1);
+    expect(countEv(r, "mark")).toBe(1);
+  }, 60_000);
+
+  it("recovers the in-process flag after a failed run and succeeds on retry", async () => {
+    const r = await runScenario("error-then-retry");
+    expect(r.exitCode).toBe(0);
+    expect(r.stderr).toBe("");
+    const out = JSON.parse(r.stdout);
+    expect(out.firstError).toContain("provider rejected");
+    // Second run in the same process proves isLearningRunning was reset.
+    expect(countEv(r, "llm-entered")).toBe(2);
+    expect(countEv(r, "llm-error")).toBe(1);
+    expect(countEv(r, "mark")).toBe(1);
+    expect(countEv(r, "profile-write")).toBe(1);
+  }, 60_000);
+
+  it("ordinary memory writes complete while profile learning holds its lock", async () => {
+    const dir = tmpDir("opencode-mem-service-lock-mem-");
+    const releaseFile = join(dir, "release");
+    const holdingFile = join(dir, "holding");
+
+    // Winner: real learning run that blocks inside the LLM handshake, holding
+    // the profile-learning coordination lock the whole time.
+    const winner = spawnWorker(dir, "winner", {
+      scenario: "full",
+      storagePath: dir,
+      blockOnLlm: true,
+      releaseFile,
+    });
+    expect(await waitForEvent(winner.eventsFile, "llm-entered")).toBe(true);
+    // The winner is now provably inside the LLM under the lock.
+    writeFileSync(holdingFile, "held");
+
+    // Independent child drives the REAL memoryClient path (real shards, real
+    // SQLite, real scope/operation locks) against an independent temp storage.
+    // Only the external embedding service is mocked (fixed vectors).
+    const writer = runFixture(MEMORY_WRITER, dir, "memory-writer", {
+      storagePath: dir,
+      holdingFile,
+      marker: "during-learning-lock",
+    });
+    const w = await writer.done;
+
+    // Only after the writer has completed may the winner be released.
+    writeFileSync(releaseFile, "go");
+    const winnerResult = await winner.done;
+
+    expect(winnerResult.exitCode).toBe(0);
+    expect(w.exitCode).toBe(0);
+    expect(w.stderr).toBe("");
+    const out = JSON.parse(w.stdout);
+    // The write path succeeded end-to-end while the learning lock was held.
+    expect(out.holdingObserved).toBe(true);
+    expect(out.counts).toEqual({ add: 1, readback: 1, search: 1, list: 1 });
+    expect(typeof out.addedId).toBe("string");
+    expect(out.searchTotal).toBe(1);
+    // And the learning run itself still finished exactly once.
+    const winnerEvents = readEvents(winner.eventsFile);
+    expect(winnerEvents.filter((e) => e.ev === "llm-entered")).toHaveLength(1);
+    expect(winnerEvents.filter((e) => e.ev === "mark")).toHaveLength(1);
+  }, 120_000);
+});
diff --git a/tests/profile-learning-storage-error.test.ts b/tests/profile-learning-storage-error.test.ts
new file mode 100644
index 00000000..6660f8ad
--- /dev/null
+++ b/tests/profile-learning-storage-error.test.ts
@@ -0,0 +1,117 @@
+import { afterAll, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * B3 regression: storage faults during stored-profile parse/merge must never
+ * be mistaken for provider faults. Runs the REAL performUserProfileLearning
+ * and the REAL cross-process lock in real child processes against temp
+ * storage; only the external AI boundaries and the profile manager are
+ * mocked. The old service fixture pinned getActiveProfile to null, so this
+ * path (existing profile → native LLM success → merge) was never covered.
+ */
+const tempDirs: string[] = [];
+
+afterAll(() => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+const WORKER = new URL("./fixtures/profile-learning-storage-error-worker.mjs", import.meta.url)
+  .pathname;
+
+interface RunResult {
+  exitCode: number | null;
+  stderr: string;
+  parsed: Record<string, unknown> | null;
+}
+
+function tempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "opencode-mem-storage-error-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function runWorker(cfg: Record<string, unknown>): RunResult {
+  const dir = tempDir();
+  const cfgPath = join(dir, "cfg.json");
+  const eventsFile = join(dir, "events.jsonl");
+  writeFileSync(cfgPath, JSON.stringify({ ...cfg, storagePath: dir, eventsFile }));
+
+  const result = Bun.spawnSync({
+    cmd: [process.execPath, WORKER, cfgPath],
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const stdout = Buffer.from(result.stdout).toString("utf8").trim();
+  const stderr = Buffer.from(result.stderr).toString("utf8").trim();
+  const jsonLine = stdout
+    .split("\n")
+    .reverse()
+    .find((line) => line.trim().startsWith("{"));
+
+  return {
+    exitCode: result.exitCode,
+    stderr,
+    parsed: jsonLine ? JSON.parse(jsonLine) : null,
+  };
+}
+
+describe("profile learning storage errors are not provider faults (B3)", () => {
+  it("native LLM success + merge storage error: no external fallback, no update/mark, error propagates", () => {
+    const result = runWorker({ mergeError: true });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe("");
+    expect(result.parsed?.["error"]).toBe("storage merge failed: simulated cold DB fault");
+    // The merge fault must NOT be treated as a provider fault: the external
+    // LLM is configured and reachable, yet is never called.
+    expect(result.parsed?.["externalCalls"]).toBe(0);
+    expect(result.parsed?.["updates"]).toBe(0);
+    expect(result.parsed?.["marks"]).toBe(0);
+    // The native provider DID succeed before the merge fault.
+    expect(result.parsed?.["nativeCalls"]).toBe(1);
+    expect(result.parsed?.["merges"]).toBeGreaterThanOrEqual(1);
+  });
+
+  it("stored-profile parse failure (corrupt profileData) propagates, no fallback", () => {
+    // Corrupt stored profileData: analyzeUserProfile's JSON.parse throws
+    // after a native success — outside the provider catch by design.
+    const result = runWorker({ corruptProfileData: true });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed?.["error"]).toBeTruthy();
+    expect(result.parsed?.["externalCalls"]).toBe(0);
+    expect(result.parsed?.["updates"]).toBe(0);
+    expect(result.parsed?.["marks"]).toBe(0);
+  });
+
+  it("native provider failure falls back to external; merge/update/mark proceed", () => {
+    const result = runWorker({ nativeError: true });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe("");
+    expect(result.parsed?.["error"]).toBe(null);
+    expect(result.parsed?.["nativeCalls"]).toBe(1);
+    expect(result.parsed?.["externalCalls"]).toBe(1);
+    expect(result.parsed?.["updates"]).toBe(1);
+    expect(result.parsed?.["marks"]).toBe(1);
+  });
+
+  it("release completes after a propagated storage error; same process can run again", () => {
+    const result = runWorker({ mergeError: true, holdLockFirst: true });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe("");
+    // First run propagated the storage error...
+    expect(result.parsed?.["error"]).toBe("storage merge failed: simulated cold DB fault");
+    // ...yet the lock is acquirable again immediately...
+    expect(result.parsed?.["reacquired"]).toBe(true);
+    // ...and a second run in the same process completes cleanly.
+    expect(result.parsed?.["secondRunError"]).toBe(null);
+    expect(result.parsed?.["secondRunMarks"]).toBe(1);
+  });
+});
diff --git a/tests/user-profile-learning-error.test.ts b/tests/user-profile-learning-error.test.ts
index 46e31b08..96b9198c 100644
--- a/tests/user-profile-learning-error.test.ts
+++ b/tests/user-profile-learning-error.test.ts
@@ -50,6 +50,12 @@ mock.module(${JSON.stringify(configUrl)}, () => ({
     opencodeProvider: "opencode-go",
     opencodeModel: "deepseek-v4-flash",
     showUserProfileToasts: false,
+    // The learning service now takes the cross-process lock before analysis.
+    // Without a storagePath the lock would coordinate through the process cwd
+    // (old FS lock) or fail to place its coordination DB (new @libsql lock).
+    // A temp dir keeps this scenario hermetic; the error assertions below are
+    // unchanged.
+    storagePath: ${JSON.stringify(dir)},
   },
 }));