@remnic/core 1.1.31 → 9.3.515

package/src/spaces/index.ts

@@ -124,6 +124,10 @@ export interface AuditEntry {
 
 const MANIFEST_VERSION = 1;
 
+function normalizeSpaceMemoryDir(memoryDir: string): string {
+  return path.resolve(memoryDir);
+}
+
 export function getSpacesDir(baseDir?: string): string {
   const homeDir = baseDir ?? resolveHomeDir();
   return path.join(homeDir, ".config", "engram", "spaces");
@@ -160,14 +164,16 @@ export function saveManifest(manifest: SpaceManifest, baseDir?: string): void {
 
 function createPersonalSpace(baseDir?: string, memoryDirOverride?: string): Space {
   const homeDir = baseDir ?? resolveHomeDir();
-  // Priority: override > env var > existing standalone dir > existing OpenClaw dir > new standalone dir
+  // Priority: override > REMNIC_MEMORY_DIR > ENGRAM_MEMORY_DIR > existing standalone dir > existing OpenClaw dir > new standalone dir
   const standalonePath = path.join(homeDir, ".engram", "memory");
   const openclawPath = path.join(homeDir, ".openclaw", "workspace", "memory", "local");
   const memoryDir = memoryDirOverride
+    ?? readEnvVar("REMNIC_MEMORY_DIR")
     ?? readEnvVar("ENGRAM_MEMORY_DIR")
     ?? (fs.existsSync(standalonePath) ? standalonePath
       : fs.existsSync(openclawPath) ? openclawPath
       : standalonePath);
+  const normalizedMemoryDir = normalizeSpaceMemoryDir(memoryDir);
   const now = new Date().toISOString();
 
   return {
@@ -175,7 +181,7 @@ function createPersonalSpace(baseDir?: string, memoryDirOverride?: string): Spac
     name: "Personal",
     kind: "personal",
     description: "Default personal memory space",
-    memoryDir,
+    memoryDir: normalizedMemoryDir,
     createdAt: now,
     updatedAt: now,
     owner: readEnvVar("USER"),
@@ -217,10 +223,12 @@ export function createSpace(options: {
   }
 
   const now = new Date().toISOString();
-  const memoryDir = options.memoryDir ?? path.join(
-    getSpacesDir(options.baseDir),
-    id,
-    "memory",
+  const memoryDir = normalizeSpaceMemoryDir(
+    options.memoryDir ?? path.join(
+      getSpacesDir(options.baseDir),
+      id,
+      "memory",
+    ),
   );
 
   const space: Space = {
@@ -534,13 +542,29 @@ function copyMemories(
     return { merged: 0, conflicts: [], skipped: 0 };
   }
 
+  const sourceRoot = fs.realpathSync(sourceDir);
   fs.mkdirSync(targetDir, { recursive: true });
+  const targetRoot = fs.realpathSync(targetDir);
 
-  const sourceFiles = walkMd(sourceDir);
+  const sourceFiles = walkMd(sourceRoot);
   for (const sourcePath of sourceFiles) {
+    const sourceRealPath = safeRealpath(sourcePath);
+    if (!sourceRealPath || !isPathInsideRoot(sourceRealPath, sourceRoot)) {
+      skipped++;
+      continue;
+    }
+    const sourceStat = safeLstat(sourcePath);
+    if (!sourceStat?.isFile()) {
+      skipped++;
+      continue;
+    }
     const content = fs.readFileSync(sourcePath, "utf8");
-    const relativePath = path.relative(sourceDir, sourcePath);
-    const targetPath = path.join(targetDir, relativePath);
+    const relativePath = path.relative(sourceRoot, sourceRealPath);
+    const targetPath = path.resolve(targetRoot, relativePath);
+    if (!isPathInsideRoot(targetPath, targetRoot)) {
+      skipped++;
+      continue;
+    }
 
     const sourceHash = hashContent(content);
 
@@ -554,6 +578,19 @@ function copyMemories(
     }
 
     // Check for conflict
+    if (fs.existsSync(targetPath)) {
+      const targetStat = safeLstat(targetPath);
+      if (!targetStat?.isFile() || targetStat.isSymbolicLink()) {
+        skipped++;
+        continue;
+      }
+      const targetRealPath = safeRealpath(targetPath);
+      if (!targetRealPath || !isPathInsideRoot(targetRealPath, targetRoot)) {
+        skipped++;
+        continue;
+      }
+    }
+
     if (fs.existsSync(targetPath) && !options?.force) {
       const targetContent = fs.readFileSync(targetPath, "utf8");
       const targetHash = hashContent(targetContent);
@@ -577,6 +614,11 @@ function copyMemories(
 
     // Copy file
     fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    const targetParentRealPath = safeRealpath(path.dirname(targetPath));
+    if (!targetParentRealPath || !isPathInsideRoot(targetParentRealPath, targetRoot)) {
+      skipped++;
+      continue;
+    }
     fs.writeFileSync(targetPath, content);
     merged++;
   }
@@ -594,6 +636,9 @@ function walkMd(dir: string): string[] {
   function walk(d: string): void {
     for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
       const fullPath = path.join(d, entry.name);
+      if (entry.isSymbolicLink()) {
+        continue;
+      }
       if (entry.isDirectory()) {
         walk(fullPath);
       } else if (entry.name.endsWith(".md")) {
@@ -606,6 +651,27 @@ function walkMd(dir: string): string[] {
   return results;
 }
 
+function safeLstat(filePath: string): fs.Stats | null {
+  try {
+    return fs.lstatSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function safeRealpath(filePath: string): string | null {
+  try {
+    return fs.realpathSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function isPathInsideRoot(candidatePath: string, rootPath: string): boolean {
+  const relative = path.relative(rootPath, candidatePath);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
 interface SimpleFrontmatter {
   id?: string;
   [key: string]: string | undefined;

package/src/storage.ts

@@ -2483,6 +2483,15 @@ export class StorageManager {
   private get entitiesDir(): string {
     return path.join(this.baseDir, "entities");
   }
+  private resolveEntityFilePath(name: string): string | null {
+    if (typeof name !== "string") return null;
+    const filePath = path.resolve(this.entitiesDir, `${name}.md`);
+    const relative = path.relative(this.entitiesDir, filePath);
+    if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) {
+      return null;
+    }
+    return filePath;
+  }
   private readStorageSecureFile(filePath: string): Promise<string> {
     return readMaybeEncryptedFile(filePath, this._secureStoreKey, this.baseDir);
   }
@@ -4177,8 +4186,12 @@ export class StorageManager {
   }
 
   async readEntity(name: string): Promise<string> {
+    const filePath = this.resolveEntityFilePath(name);
+    if (filePath === null) {
+      return "";
+    }
     try {
-      return await this.readStorageSecureFile(path.join(this.entitiesDir, `${name}.md`));
+      return await this.readStorageSecureFile(filePath);
     } catch (err) {
       if (err instanceof SecureStoreLockedError) throw err;
       if (!isErrnoCode(err, "ENOENT")) throw err;

package/src/store-contract.test.ts

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { assertIsoRecordedAt, recordStoreDay } from "./store-contract.js";
+
+test("assertIsoRecordedAt accepts valid complete ISO timestamps with timezones", () => {
+  assert.equal(
+    assertIsoRecordedAt("2026-05-21T12:34:56.789Z"),
+    "2026-05-21T12:34:56.789Z",
+  );
+  assert.equal(
+    assertIsoRecordedAt("2026-05-21T12:34:56-05:00"),
+    "2026-05-21T12:34:56-05:00",
+  );
+});
+
+test("assertIsoRecordedAt rejects impossible, incomplete, and overflow timestamps", () => {
+  for (const value of [
+    "2026-99-99Tnot-a-date",
+    "2026-02-30T00:00:00Z",
+    "2026-05-21",
+    "2026-05-21T12:34:56",
+    "2026-05-21T24:00:00Z",
+    "2026-05-21T12:60:00Z",
+    "2026-05-21T12:34:60Z",
+    "999999999999-01-01T00:00:00Z",
+  ]) {
+    assert.throws(() => assertIsoRecordedAt(value), /recordedAt must be an ISO timestamp/);
+    assert.throws(() => recordStoreDay(value), /recordedAt must be an ISO timestamp/);
+  }
+});
+
+test("recordStoreDay returns the validated source date prefix", () => {
+  assert.equal(recordStoreDay("2026-05-21T23:30:00-05:00"), "2026-05-21");
+});

package/src/store-contract.ts

@@ -22,18 +22,52 @@ export function assertSafePathSegment(value: string, field: string): string {
 }
 
 export function assertIsoRecordedAt(value: string, field = "recordedAt"): string {
-  if (!/^\d{4}-\d{2}-\d{2}T/.test(value)) {
+  const parsed = parseIsoRecordedAt(value);
+  if (!parsed) {
     throw new Error(`${field} must be an ISO timestamp`);
   }
   return value;
 }
 
 export function recordStoreDay(recordedAt: string): string {
-  const day = recordedAt.slice(0, 10);
-  if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) {
-    throw new Error("recordedAt must start with a valid YYYY-MM-DD date");
+  assertIsoRecordedAt(recordedAt);
+  return recordedAt.slice(0, 10);
+}
+
+const ISO_RECORDED_AT_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+function parseIsoRecordedAt(value: string): boolean {
+  const match = value.match(ISO_RECORDED_AT_RE);
+  if (!match) {
+    return false;
+  }
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const hour = Number(match[4]);
+  const minute = Number(match[5]);
+  const second = Number(match[6]);
+  if (
+    !Number.isInteger(year) ||
+    month < 1 ||
+    month > 12 ||
+    day < 1 ||
+    day > 31 ||
+    hour > 23 ||
+    minute > 59 ||
+    second > 59
+  ) {
+    return false;
+  }
+  const calendarDate = new Date(Date.UTC(year, month - 1, day));
+  if (
+    calendarDate.getUTCFullYear() !== year ||
+    calendarDate.getUTCMonth() !== month - 1 ||
+    calendarDate.getUTCDate() !== day
+  ) {
+    return false;
   }
-  return day;
+  return Number.isFinite(Date.parse(value));
 }
 
 export function optionalStringArray(value: unknown, field: string): string[] | undefined {

package/src/summarizer.ts

@@ -3,7 +3,7 @@ import path from "node:path";
 import { z } from "zod";
 import { log } from "./logger.js";
 import { LocalLlmClient } from "./local-llm.js";
-import { FallbackLlmClient } from "./fallback-llm.js";
+import { FallbackLlmClient, fallbackLlmRuntimeContextFromConfig } from "./fallback-llm.js";
 import { ModelRegistry } from "./model-registry.js";
 import { extractJsonCandidates } from "./json-extract.js";
 import type { HourlySummary, TranscriptEntry, PluginConfig, GatewayConfig } from "./types.js";
@@ -20,7 +20,8 @@ import {
 // Schema for LLM summary output
 const HourlySummarySchema = z.object({
   bullets: z
-    .array(z.string())
+    .array(z.string().trim().min(1))
+    .min(1)
     .describe("3-5 bullet points summarizing the hour's activity"),
 });
 
@@ -42,6 +43,10 @@ type HourlySummaryExtendedMeta = {
   toolCounts: Record<string, number>;
 };
 
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 export class HourlySummarizer {
   private summariesDir: string;
   private config: PluginConfig;
@@ -60,9 +65,10 @@ export class HourlySummarizer {
     this.localLlm = new LocalLlmClient(config, this.modelRegistry);
 
     // Initialize fallback client with gateway config
-    this.fallbackLlm = new FallbackLlmClient(gatewayConfig, {
-      workspaceDir: config.workspaceDir,
-    });
+    this.fallbackLlm = new FallbackLlmClient(
+      gatewayConfig,
+      fallbackLlmRuntimeContextFromConfig(config),
+    );
 
     if (!gatewayConfig?.agents?.defaults?.model?.primary && !config.localLlmEnabled && config.modelSource !== "gateway") {
       log.warn("no gateway default AI and local LLM disabled — hourly summarization disabled");
@@ -380,9 +386,7 @@ Respond with valid JSON matching this schema:
       for (const candidate of extractJsonCandidates(content)) {
         try {
           const parsed = JSON.parse(candidate);
-          return {
-            bullets: Array.isArray((parsed as any).bullets) ? (parsed as any).bullets : [],
-          };
+          return HourlySummarySchema.parse(parsed);
         } catch {
           // keep trying candidates
         }
@@ -421,17 +425,19 @@ Respond with valid JSON matching this schema:
     const hourHeader = `## ${hourStr}:00`;
     if (existingContent.includes(hourHeader)) {
       // Replace existing hour section
-      const beforeHour = existingContent.split(hourHeader)[0];
-      const afterMatch = existingContent.split(hourHeader)[1];
-      const afterHour = afterMatch ? afterMatch.split("\n## ")[1] : undefined;
-
+      const headerMatch = new RegExp(`(^|\\n)${escapeRegExp(hourHeader)}\\n`).exec(existingContent);
+      const sectionStart = headerMatch
+        ? headerMatch.index + headerMatch[1].length
+        : existingContent.indexOf(hourHeader);
+      const nextHeaderPattern = /\n## \d{2}:00\n/g;
+      nextHeaderPattern.lastIndex = sectionStart + hourHeader.length;
+      const nextHeader = nextHeaderPattern.exec(existingContent);
+      const beforeHour = existingContent.slice(0, sectionStart);
+      const afterHour = nextHeader
+        ? existingContent.slice(nextHeader.index + 1)
+        : "";
       const newSection = this.formatHourSection(summary, hourHeader);
-
-      if (afterHour) {
-        existingContent = beforeHour + newSection + "\n## " + afterHour;
-      } else {
-        existingContent = beforeHour + newSection;
-      }
+      existingContent = beforeHour + newSection.trimEnd() + (afterHour ? "\n\n" + afterHour : "\n");
 
       await writeFile(filePath, existingContent, "utf-8");
       log.debug(`updated hourly summary for ${summary.sessionKey} at ${hourStr}:00`);

package/src/summary-snapshot.test.ts

@@ -263,6 +263,83 @@ test("saveSummary encodes slash-containing session keys before writing markdown"
   await assert.rejects(readFile(legacyPath, "utf-8"), /ENOENT/);
 });
 
+test("generateSummary falls back when local LLM returns schema-invalid bullets", async () => {
+  const memoryDir = await mkdtemp(
+    path.join(os.tmpdir(), "engram-summary-local-schema-fallback-"),
+  );
+  const summarizer = new HourlySummarizer({
+    ...makeConfig(memoryDir),
+    localLlmEnabled: true,
+    localLlmFallback: true,
+  });
+  await summarizer.initialize();
+
+  (summarizer as any).localLlm.chatCompletion = async () => ({
+    content: JSON.stringify({ bullets: [] }),
+  });
+  let fallbackCalls = 0;
+  (summarizer as any).fallbackLlm.parseWithSchema = async () => {
+    fallbackCalls += 1;
+    return { bullets: ["gateway fallback bullet"] };
+  };
+
+  const summary = await summarizer.generateSummary(
+    "session-local-invalid",
+    new Date("2026-03-26T08:00:00.000Z"),
+    [
+      {
+        role: "user",
+        content: "Please summarize this work.",
+        timestamp: "2026-03-26T08:00:00.000Z",
+        sessionKey: "session-local-invalid",
+        turnId: "turn-1",
+      },
+    ],
+  );
+
+  assert.deepEqual(summary?.bullets, ["gateway fallback bullet"]);
+  assert.equal(fallbackCalls, 1);
+});
+
+test("saveSummary updates an early hour without dropping later sections", async () => {
+  const memoryDir = await mkdtemp(
+    path.join(os.tmpdir(), "engram-summary-preserve-later-hours-"),
+  );
+  const summarizer = new HourlySummarizer(makeConfig(memoryDir));
+  await summarizer.initialize();
+
+  const sessionKey = "session-preserve-later-hours";
+  const dateStr = "2026-03-26";
+  const summary = (hour: string, bullet: string) => ({
+    hour: `${dateStr}T${hour}:00:00.000Z`,
+    sessionKey,
+    bullets: [bullet],
+    turnCount: 1,
+    generatedAt: "2026-03-26T08:15:00.000Z",
+  });
+
+  await summarizer.saveSummary(summary("08", "original first hour"));
+  await summarizer.saveSummary(summary("09", "second hour"));
+  await summarizer.saveSummary(summary("10", "third hour"));
+  await summarizer.saveSummary(summary("08", "updated first hour"));
+
+  const markdownPath = path.join(
+    memoryDir,
+    "summaries",
+    "hourly",
+    encodeStoragePathSegment(sessionKey, "session"),
+    `${dateStr}.md`,
+  );
+  const markdown = await readFile(markdownPath, "utf-8");
+
+  assert.match(markdown, /updated first hour/);
+  assert.doesNotMatch(markdown, /original first hour/);
+  assert.match(markdown, /second hour/);
+  assert.match(markdown, /third hour/);
+  assert.equal(markdown.indexOf("## 08:00") < markdown.indexOf("## 09:00"), true);
+  assert.equal(markdown.indexOf("## 09:00") < markdown.indexOf("## 10:00"), true);
+});
+
 test("readRecent backfills a summary snapshot from the full parsed markdown history", async () => {
   const memoryDir = await mkdtemp(
     path.join(os.tmpdir(), "engram-summary-backfill-"),

package/src/surfaces/dreams.test.ts

@@ -120,6 +120,43 @@ test("dreams surface append migrates legacy heading entries into the diary marke
   assert.equal(reread[2]?.title, "A useful reflective note");
 });
 
+test("dreams surface preserves legacy in-body dividers through append migration", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-dreams-legacy-body-divider-"));
+  const dreamsPath = path.join(root, "dreams.md");
+  await writeFile(
+    dreamsPath,
+    [
+      "# Dreams",
+      "",
+      "## 2026-04-11T03:22:14Z",
+      "",
+      "first",
+      "",
+      "---",
+      "",
+      "second",
+    ].join("\n"),
+    "utf8",
+  );
+
+  const surface = createDreamsSurface();
+  const entries = await surface.read(dreamsPath);
+
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0]?.body, ["first", "", "---", "", "second"].join("\n"));
+
+  await surface.append(dreamsPath, {
+    timestamp: "2026-04-12T15:00:00Z",
+    title: "Migrating without loss",
+    body: "new entry",
+    tags: [],
+  });
+
+  const migrated = await surface.read(dreamsPath);
+  assert.equal(migrated.length, 2);
+  assert.equal(migrated[0]?.body, ["first", "", "---", "", "second"].join("\n"));
+});
+
 test("dreams surface appends a new OpenClaw diary entry and round-trips cleanly", async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), "remnic-dreams-append-"));
   const dreamsPath = path.join(root, "DREAMS.md");
@@ -145,6 +182,42 @@ test("dreams surface appends a new OpenClaw diary entry and round-trips cleanly"
   assert.deepEqual(reread[0]?.tags, ["reflection", "verification"]);
 });
 
+test("dreams surface serializes concurrent appends to preserve every entry", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-dreams-concurrent-"));
+  const dreamsPath = path.join(root, "DREAMS.md");
+  const surface = createDreamsSurface();
+
+  await surface.append(dreamsPath, {
+    timestamp: "2026-04-12T15:00:00Z",
+    title: "Seed",
+    body: "existing entry",
+    tags: [],
+  });
+
+  await Promise.all([
+    surface.append(dreamsPath, {
+      timestamp: "2026-04-12T16:00:00Z",
+      title: "Concurrent A",
+      body: "first concurrent entry",
+      tags: [],
+    }),
+    surface.append(dreamsPath, {
+      timestamp: "2026-04-12T17:00:00Z",
+      title: "Concurrent B",
+      body: "second concurrent entry",
+      tags: [],
+    }),
+  ]);
+
+  const reread = await surface.read(dreamsPath);
+  assert.equal(reread.length, 3);
+  assert.deepEqual(reread.map((entry) => entry.title).sort(), [
+    "Concurrent A",
+    "Concurrent B",
+    "Seed",
+  ]);
+});
+
 test("dream surface keeps entry ids stable when title, body, or tags are edited in place", async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), "remnic-dreams-stable-id-"));
   const dreamsPath = path.join(root, "DREAMS.md");

package/src/surfaces/dreams.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { statSync, watch, type FSWatcher } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 
 export interface DreamEntry {
@@ -23,6 +23,7 @@ export interface DreamsSurface {
 
 const DIARY_START_MARKER = "<!-- openclaw:dreaming:diary:start -->";
 const DIARY_END_MARKER = "<!-- openclaw:dreaming:diary:end -->";
+const appendQueues = new Map<string, Promise<void>>();
 
 function stableDreamId(params: {
   timestamp: string;
@@ -140,7 +141,7 @@ function parseLegacyHeadingEntries(content: string): ParsedDreamEntry[] {
     const end = index + 1 < matches.length ? (matches[index + 1]?.index ?? content.length) : content.length;
     const heading = match[1]?.trim() ?? "";
     const body = content.slice(start + match[0].length, end).replace(/^\s+/, "");
-    const dividerTrimmed = body.replace(/\n---\s*$/m, "").trim();
+    const dividerTrimmed = body.replace(/\n---\s*$/, "").trim();
     const bodyLines = dividerTrimmed.split("\n");
     const tags = bodyLines.length > 0 ? parseTagsLine(bodyLines[bodyLines.length - 1] ?? "") : [];
     const contentLines =
@@ -221,6 +222,36 @@ function renderAppendBlock(entry: Omit<DreamEntry, "id" | "sourceOffset">): stri
   return `---\n\n*${entry.timestamp}${titlePart}*\n\n${entry.body.trim()}${tagsPart}\n`;
 }
 
+function serializeAppend<T>(filePath: string, operation: () => Promise<T>): Promise<T> {
+  const key = path.resolve(filePath);
+  const previous = appendQueues.get(key) ?? Promise.resolve();
+  const current = previous.catch(() => undefined).then(operation);
+  const next = current.then(
+    () => undefined,
+    () => undefined,
+  );
+  appendQueues.set(key, next);
+  next.finally(() => {
+    if (appendQueues.get(key) === next) appendQueues.delete(key);
+  });
+  return current;
+}
+
+async function atomicWriteUtf8(filePath: string, content: string): Promise<void> {
+  const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  try {
+    await writeFile(tmpPath, content, { encoding: "utf8", flag: "wx" });
+    await rename(tmpPath, filePath);
+  } catch (error) {
+    try {
+      await unlink(tmpPath);
+    } catch {
+      // Best-effort cleanup; the original file remains untouched if rename failed.
+    }
+    throw error;
+  }
+}
+
 export function createDreamsSurface(): DreamsSurface {
   return {
     async read(filePath: string): Promise<DreamEntry[]> {
@@ -239,23 +270,26 @@ export function createDreamsSurface(): DreamsSurface {
       filePath: string,
       entry: Omit<DreamEntry, "id" | "sourceOffset">,
     ): Promise<DreamEntry> {
-      await mkdir(path.dirname(filePath), { recursive: true });
-      let content = "";
-      try {
-        content = await readFile(filePath, "utf8");
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-      }
-      const ensured = ensureDiary(content);
-      const endIndex = ensured.indexOf(DIARY_END_MARKER);
-      const block = renderAppendBlock(entry);
-      const updated =
-        endIndex >= 0
-          ? `${ensured.slice(0, endIndex)}${block}\n${ensured.slice(endIndex)}`
-          : `${ensureDiary("")}${block}`;
-      await writeFile(filePath, updated.endsWith("\n") ? updated : `${updated}\n`, "utf8");
-      const entries = parseDreamEntries(updated);
-      return entries[entries.length - 1]!;
+      return serializeAppend(filePath, async () => {
+        await mkdir(path.dirname(filePath), { recursive: true });
+        let content = "";
+        try {
+          content = await readFile(filePath, "utf8");
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+        }
+        const ensured = ensureDiary(content);
+        const endIndex = ensured.indexOf(DIARY_END_MARKER);
+        const block = renderAppendBlock(entry);
+        const updated =
+          endIndex >= 0
+            ? `${ensured.slice(0, endIndex)}${block}\n${ensured.slice(endIndex)}`
+            : `${ensureDiary("")}${block}`;
+        const normalized = updated.endsWith("\n") ? updated : `${updated}\n`;
+        await atomicWriteUtf8(filePath, normalized);
+        const entries = parseDreamEntries(normalized);
+        return entries[entries.length - 1]!;
+      });
     },
 
     watch(filePath: string, onChange: (entries: DreamEntry[]) => void): () => void {