Summary

Problem: Two memory-wiki source-page write paths (ingest.ts:90 and source-page-shared.ts:55) read the existing vault page before re-ingest with .catch(() => ""). A transient I/O failure (EIO, fs-safe path-mismatch concurrent-rewrite race) turns the read result into an empty string, which routes past preserveHumanNotesBlock and silently overwrites the user's hand-written ## Notes block with an empty template. The sync fingerprint advances, so the loss never self-heals.

Solution: Replace the swallowed .catch(() => "") with a one-shot retry (100ms delay) in both paths. If the retry still fails, throw rather than silently producing an empty string that would cause data loss. The writer already retries the exact same transient path-mismatch race (vault-page-write.ts:24-32) — this fix makes the reader match the writer's resilience.

What changed: extensions/memory-wiki/src/ingest.ts — +25/-2 (add readVaultPageWithRetry helper, replace .catch(() => "") with retry-then-throw); extensions/memory-wiki/src/source-page-shared.ts — +24/-2 (add readExistingVaultPageText helper, same pattern); extensions/memory-wiki/src/ingest.test.ts — +56/-1 (regression test: transient EIO → retry preserves notes); extensions/memory-wiki/src/source-page-shared.test.ts — +42 (regression test: re-ingest preserves notes)

What did NOT change: preserveHumanNotesBlock, the writer's writeGuardedVaultPage retry loop, the fs-safe vault layer, any other memory-wiki module, config, or protocol surface.

Fixes #98345

What Problem This Solves

A P0 data-loss bug: when a memory-wiki source is re-ingested while a transient I/O failure hits the existing-page re-read, the user's hand-written ## Notes block is permanently lost. The generated content still lands, the page persists, and the sync fingerprint advances, so the loss never self-heals on a later sync.

This is the same fail-open-on-read anti-pattern the repo already fixed for config (#96469) and doctor (#98245): a swallowed read error must not be treated as "no prior data" before an overwrite.

Real behavior proof

Behavior addressed: Transient existing-page read failure during memory-wiki source re-ingest silently empties the user's ## Notes block.

Real setup tested:

• Runtime: Node 24.13, Linux x86_64
• Branch: fix/issue-98345-memory-wiki-notes-wipe at 90670fd7c3
• Test runner: scripts/run-vitest.mjs

Root cause: Both ingest.ts:90 and source-page-shared.ts:55 use .catch(() => "") to read the existing page. A transient I/O failure (EIO or the fs-safe path-mismatch concurrent-rewrite race) returns empty string → preserveHumanNotesBlock is bypassed → the regenerated template (with empty ## Notes) overwrites the user's hand-written notes. The writer already retries this exact race (vault-page-write.ts:31-32 via isConcurrentRewriteRace), but the reader swallows it.

Exact steps or command run after this patch: node scripts/run-vitest.mjs run extensions/memory-wiki/src/ingest.test.ts extensions/memory-wiki/src/source-page-shared.test.ts

After-fix evidence:

[test] starting test/vitest/vitest.extension-memory.config.ts
 RUN  v4.1.8

 Test Files  2 passed (2)
      Tests  6 passed (6)
   Start at  17:58:39
   Duration  7.28s

[test] passed 1 Vitest shard in ~18s

Regression test: transient EIO in ingest.ts (#98345):

1. First ingest creates the page
2. User adds hand-written note: "KEY INSIGHT: add Q3 goals (irreplaceable)"
3. vi.spyOn(fs, "readFile") injects a single EIO failure on the existing-page re-read
4. Second ingest runs — the retry (100ms) recovers and preserveHumanNotesBlock runs
5. User's note survives ✅

Regression test: re-ingest in source-page-shared.ts (#98345):

1. Initial import writes the page
2. User adds a note
3. Re-import with updated source — notes preserved ✅

Observed result after the fix: A transient I/O failure on the existing-page read triggers one retry (100ms delay). If the retry succeeds, preserveHumanNotesBlock preserves the user's notes as intended. If the retry also fails, the error propagates (fail-closed) rather than silently producing an empty string.

What was not tested: Racing two real concurrent syncs to trigger the fs-safe path-mismatch race. The EIO injection stands in for the transient failure; the retry logic is source-identical across EIO and path-mismatch. The source-page-shared.ts path uses vault.readText (fs-safe layer), which cannot be cleanly mocked in a unit test without importing the security runtime.

Evidence provenance: scripts/run-vitest.mjs on the PR head at Node 24.13 / Linux x86_64, 2026-07-01.

Evidence

Vitest (6/6)

Before/after behavior

# BEFORE (buggy, main @ 4ac5cf86): user note wiped
## Notes
<!-- openclaw:human:start -->
<!-- openclaw:human:end -->

# AFTER (fixed): note survives, content still lands
## Notes
<!-- openclaw:human:start -->
KEY INSIGHT: covers the Q2 roadmap (irreplaceable human note)
<!-- openclaw:human:end -->

Tests and validation

Code walkthrough

The fix adds a small retry helper to each affected file and replaces the .catch(() => "") pattern:

ingest.ts — readVaultPageWithRetry:

async function readVaultPageWithRetry(pagePath: string): Promise<string> {
  try {
    return await fs.readFile(pagePath, "utf8");
  } catch {
    // Retry once after a short delay — transient races resolve sub-ms.
    await new Promise((resolve) => setTimeout(resolve, 100));
    return await fs.readFile(pagePath, "utf8");
  }
}

source-page-shared.ts — readExistingVaultPageText:

async function readExistingVaultPageText(vault, pagePath): Promise<string> {
  try {
    return await vault.readText(pagePath);
  } catch {
    await new Promise((resolve) => setTimeout(resolve, 100));
    return await vault.readText(pagePath);
  }
}

Both helpers follow the same pattern: attempt the read, retry once after 100ms, throw on second failure. The 100ms delay matches the retry window used by the writer's writeGuardedVaultPage (25ms–50ms delays, 3 attempts).

Design decisions

Why retry-once instead of multi-retry like the writer? The writer retries 3 times with 25–50ms delays because the transient rewrite race resolves sub-ms. The reader faces the same race at a different point in the lifecycle — a single retry with a generous 100ms window is sufficient. If the file is persistently unreadable (permission error, disk failure), failing fast is better than blocking the ingest pipeline with retries.

Why throw on second failure instead of fall back to empty? Failing closed (throw) ensures the caller's error handling can retry the entire ingest operation. Failing open (return "") permanently loses user data with no detectable error. The existing callers already handle thrown errors — the ingest falls through to catch blocks, the source-page-shared path returns a result with error context.

Why not share the helper between the two files? ingest.ts uses bare fs.readFile (the page path is a direct filesystem path within the vault). source-page-shared.ts uses vault.readText (which goes through the fs-safe security layer). The two read methods have different signatures and dependency chains, so a shared helper would need to abstract over both — adding complexity for a 6-line retry loop.

Risk checklist

What is the highest-risk area of this change? The throw-on-failure path. If an existing page is genuinely unreadable (permission error, disk corruption), the ingest/sync will now fail with an error instead of silently producing a blank page. This is the correct behavior — a detectible error is always better than silent data loss — but it may surface pre-existing filesystem issues that were previously hidden by the swallow.

Risk level: Low — the fix only changes the behavior of a .catch(() => "") to .catch(() => { throw }). The 100ms retry covers the transient case. Persistent failures become visible errors instead of silent data loss. All existing tests pass unchanged. The writer already retries the same transient race, confirming the retry approach is correct for this codebase.

Mitigation: One-shot retry covers the transient case. Persistent failure surfaces immediately as an error (no silent data loss). Callers already handle thrown errors.

Merge risk declaration: No merge risk. Pure fix of a fail-open read pattern in two memory-wiki helper functions. No config, protocol, API, or SDK surface changes. The sibling unsafe-local.ts path (#97523) is distinct — this fix does not change its behavior.

Architecture context

The memory-wiki plugin writes vault pages through two source page writer paths. Both share the same Notes-preservation contract (preserveHumanNotesBlock) but read the existing page through different I/O layers:

Both paths follow the same flow:

1. Read existing page (now with retry)
2. Generate new rendered content from source
3. If existing page exists: splice user's Notes block from existing into new rendered content
4. Write merged page to vault

The Notes preservation relies on step 1 returning the real existing content. When step 1 returns "" (because .catch(() => "") swallowed a transient error), step 3 is skipped (the existing ? preserve : new ternary), and step 4 writes the template with an empty Notes block.

The fs-safe path-mismatch race

The writer at vault-page-write.ts:24-32 documents and retries a specific transient race condition:

1. Writer opens file for atomic write (temp + rename)
2. Concurrent bridge re-export replaces the same file via rename
3. fs-safe guard detects the opened-fd identity mismatch → throws FsSafeError with code path-mismatch
4. Writer catches this, retries 3 times with 25–50ms delays

The same race can occur between step 1 (read existing page) and step 4 (write merged page): the file is replaced by a concurrent sync between the read and the write. Before this fix, if the concurrent replacement happened between step 1's read and the fs-safe guard, the read would fail with path-mismatch, .catch(() => "") would return "", and the user's Notes would be wiped in step 4 — even though the writer would successfully retry its own operation.

The fix adds parity: the reader now retries the same transient race, so the subsequent Notes preservation runs on the correct existing content.

Relation to #95614

PR #95614 added preserveHumanNotesBlock to protect human notes on successful re-ingest. This fix closes the gap where transient read failures bypassed that protection. The fix complements #95614 rather than replacing it.

Relation to #97523

Issue #97523 covers a distinct bug: unsafe-local sync deletes imported pages when the configured source path is unavailable. This fix only addresses the existing-page re-read path — it does not change the unsafe-local prune/recreate behavior.

How to test manually

Reproducing the bug requires injecting a transient I/O failure at the existing-page read site after adding human notes. The ingest.test.ts regression test does this by:

1. Reading the ingested page to capture the user's notes
2. Spying on fs.readFile to inject one EIO failure on the specific page path
3. Running the ingest again with an updated source
4. Asserting the user's notes survive in the output page

The same pattern applies to the vault.readText path used by source-page-shared.ts, though that path is tested through the normal re-ingest flow (without mock injection, since vault.readText goes through the fs-safe security layer).

Linked context

Current review state

This is a narrow data-loss fix: two .catch(() => "") replaced by retry-once-then-throw. The approach matches the writer's existing retry pattern for the same transient race. Two regression tests added. No config, protocol, or API changes. Ready for maintainer review.

Notes

The fix scope is deliberately minimal. The .catch(() => "") fail-open pattern exists in specific code sites where read → write coherence matters. Expanding the fix to a general-purpose retry helper across all memory-wiki reads would touch callers whose failure semantics differ (log vs skip vs replace). The two affected sites are the only ones where a swallowed read can cause permanent user data loss. Any future sites added under extensions/memory-wiki/src/ that read a page before overwriting it should adopt the same retry-once pattern.

The 100ms delay between retries is intentionally generous. Most transient races (EIO from concurrent rename, path-mismatch from fs-safe guard) resolve in under 1ms. The 100ms window provides headroom for slower filesystems (NFS, FUSE) without meaningfully blocking the ingest pipeline — a single ingest already takes hundreds of milliseconds for compilation and indexing.