Summary

• Problem: memory sync and wiki compile paths still surfaced raw transient Unknown system error -11 / FileProvider-style read failures from memory-host reads, session transcript reads, and wiki page reads.
• Solution: add one shared bounded retry helper in memory-host-sdk, route the affected memory-core and memory-wiki read paths through it, and preserve existing missing-file behavior.
• What changed: retried workspace memory reads, memory indexing reads, session transcript reads, session delta newline reads, and wiki compile page reads; added focused regression coverage and updated the Plugin SDK API baseline for the exported helper.
• What did NOT change (scope boundary): no new config knob, no broad filesystem detection, no retry for unrelated non-memory reads, and no behavior change for permanent read errors or missing files.

Motivation

• iCloud / FileProvider-backed memory stores can return transient read errnos during gateway warm-up or wiki compile windows. The issue report and ClawSweeper comment both showed that current main and the latest shipped release still propagate those failures directly, which can abort memory sync or break librarian wiki compile.
• The right fix is narrow and shared: reuse one bounded retry policy across the memory-host reads that back memory-core and memory-wiki instead of sprinkling ad hoc loops at each call site.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes memory-core sync emits raw EAGAIN (errno -11) on iCloud/FileProvider-backed reads instead of retry-with-backoff #85252
• Related readPageSummaries: no concurrency limit on fs.readFile, triggers EDEADLK on iCloud/FileProvider-backed vaults #68738
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior addressed: transient FileProvider-style errno -11 read failures no longer abort workspace memory reads, session transcript indexing, or wiki compile page reads.
• Real environment tested: local macOS source checkout on May 22, 2026 using direct OpenClaw runtime modules via node --import tsx --input-type=module.
• Exact steps or command run after this patch:

node --import tsx --input-type=module <<'EOF'
import fs from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import { readMemoryFile } from './packages/memory-host-sdk/src/engine-storage.ts';
import { buildSessionEntry } from './packages/memory-host-sdk/src/host/session-files.ts';
import { compileMemoryWikiVault } from './extensions/memory-wiki/src/compile.ts';
import { resolveMemoryWikiConfig } from './extensions/memory-wiki/src/config.ts';
import { renderWikiMarkdown } from './extensions/memory-wiki/src/markdown.ts';

const root = await fs.mkdtemp(path.join(os.tmpdir(), 'issue-85252-proof-'));
const workspaceDir = path.join(root, 'workspace');
const memoryPath = path.join(workspaceDir, 'memory', 'retry.md');
const sessionPath = path.join(workspaceDir, '.openclaw', 'sessions', 'session.jsonl');
const vaultDir = path.join(root, 'wiki');
const wikiPagePath = path.join(vaultDir, 'sources', 'alpha.md');
await fs.mkdir(path.dirname(memoryPath), { recursive: true });
await fs.mkdir(path.dirname(sessionPath), { recursive: true });
await fs.mkdir(path.dirname(wikiPagePath), { recursive: true });
await fs.writeFile(memoryPath, 'alpha\nbeta', 'utf8');
await fs.writeFile(
  sessionPath,
  `${JSON.stringify({ type: 'message', message: { role: 'user', content: [{ type: 'text', text: 'hello' }] } })}\n`,
  'utf8',
);
await fs.writeFile(
  wikiPagePath,
  renderWikiMarkdown({
    frontmatter: {
      pageType: 'source',
      id: 'source.alpha',
      title: 'Alpha',
      claims: [
        {
          id: 'claim.alpha.doc',
          text: 'Alpha is the canonical source page.',
          status: 'supported',
          evidence: [{ sourceId: 'source.alpha', lines: '1-3' }],
        },
      ],
    },
    body: '# Alpha\n',
  }),
  'utf8',
);
const wikiConfig = resolveMemoryWikiConfig({ vault: { path: vaultDir } }, { homedir: os.homedir() });

const realOpen = fs.open.bind(fs);
const realReadFile = fs.readFile.bind(fs);
let memoryOpen = 0;
let sessionOpen = 0;
let wikiReadFile = 0;
fs.open = async (...args) => {
  const [target] = args;
  if (typeof target === 'string') {
    const resolved = path.resolve(target);
    if (resolved === memoryPath) {
      memoryOpen += 1;
      if (memoryOpen === 1) {
        const err = new Error('Unknown system error -11: Unknown system error -11, open');
        err.code = 'UNKNOWN';
        err.errno = -11;
        throw err;
      }
    }
    if (resolved === sessionPath) {
      sessionOpen += 1;
      if (sessionOpen === 1) {
        const err = new Error('Unknown system error -11: Unknown system error -11, open');
        err.code = 'UNKNOWN';
        err.errno = -11;
        throw err;
      }
    }
  }
  return await realOpen(...args);
};
fs.readFile = async (...args) => {
  const [target] = args;
  if (typeof target === 'string' && path.resolve(target) === wikiPagePath) {
    wikiReadFile += 1;
    if (wikiReadFile <= 3) {
      const err = new Error('Unknown system error -11: Unknown system error -11, read');
      err.code = 'UNKNOWN';
      err.errno = -11;
      throw err;
    }
  }
  return await realReadFile(...args);
};

try {
  const memoryResult = await readMemoryFile({ workspaceDir, extraPaths: [], relPath: 'memory/retry.md' });
  const sessionEntry = await buildSessionEntry(sessionPath);
  const compiled = await compileMemoryWikiVault(wikiConfig);
  console.log(JSON.stringify({
    attempts: { memoryOpen, sessionOpen, wikiReadFile },
    memoryResult,
    sessionLineMapLength: sessionEntry?.lineMap.length ?? null,
    sessionContent: sessionEntry?.content ?? null,
    compiledSourceCount: compiled.pageCounts.source,
    updatedFiles: compiled.updatedFiles.map((filePath) => path.relative(vaultDir, filePath)).sort(),
  }, null, 2));
} finally {
  fs.open = realOpen;
  fs.readFile = realReadFile;
  await fs.rm(root, { recursive: true, force: true });
}
EOF

• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output):

{
  "attempts": {
    "memoryOpen": 2,
    "sessionOpen": 2,
    "wikiReadFile": 6
  },
  "memoryResult": {
    "text": "alpha\nbeta",
    "path": "memory/retry.md",
    "from": 1,
    "lines": 2
  },
  "sessionLineMapLength": 1,
  "sessionContent": "User: hello",
  "compiledSourceCount": 1,
  "updatedFiles": [
    ".openclaw-wiki/cache/agent-digest.json",
    ".openclaw-wiki/cache/claims.jsonl",
    "concepts/index.md",
    "entities/index.md",
    "index.md",
    "reports/claim-health.md",
    "reports/contradictions.md",
    "reports/index.md",
    "reports/low-confidence.md",
    "reports/open-questions.md",
    "reports/person-agent-directory.md",
    "reports/privacy-review.md",
    "reports/provenance-coverage.md",
    "reports/relationship-graph.md",
    "reports/stale-pages.md",
    "sources/alpha.md",
    "sources/index.md",
    "syntheses/index.md"
  ]
}

• Observed result after fix: the first transient workspace open and session open both retried and succeeded on the second attempt, the wiki page read recovered after three injected -11 failures, and the real runtime modules returned the expected memory content, session transcript content, and compiled wiki output instead of surfacing a raw read error.
• What was not tested: live iCloud / FileProvider reproduction on a real synced vault in this run; the proof uses injected transient errnos against the real runtime modules rather than a live macOS FileProvider race.
• Before evidence (optional but encouraged): on main, injecting the same transient NodeJS.ErrnoException into these read paths propagates the raw failure through memory sync / compile instead of recovering.

Root Cause (if applicable)

• Root cause: the affected memory-host, memory-core, and memory-wiki paths treated transient FileProvider-style read errnos as terminal failures instead of the short-lived filesystem contention they are on macOS / iCloud-backed storage.
• Missing detection / guardrail: there was no shared memory read retry helper and no regression coverage for transient errno -11 / EAGAIN / EWOULDBLOCK / EDEADLK behavior across the affected read surfaces.
• Contributing context (if known): the issue comment and ClawSweeper review both pointed out that current main and the shipped release still exposed these raw failures from session sync and wiki compile paths, with related FileProvider behavior already noted in readPageSummaries: no concurrency limit on fs.readFile, triggers EDEADLK on iCloud/FileProvider-backed vaults #68738.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: packages/memory-host-sdk/src/host/read-file.test.ts, packages/memory-host-sdk/src/host/internal.test.ts, extensions/memory-core/src/memory/manager.read-file.test.ts, extensions/memory-core/src/memory/manager-sync-ops.startup-catchup.test.ts, extensions/memory-wiki/src/compile.test.ts
• Scenario the test should lock in: one-shot transient -11 / EAGAIN-family failures on memory file reads, session transcript reads, session delta newline reads, and wiki page reads recover inside the shared helper without changing missing-file behavior.
• Why this is the smallest reliable guardrail: the bug sits at the filesystem-read seam, so injected transient read failures on the real call paths give precise coverage without requiring a flaky live iCloud harness.
• Existing test that already covers this (if any): none; existing coverage handled missing files and unrelated retry surfaces.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

Memory sync and wiki compile now retry transient FileProvider-style read failures instead of surfacing raw Unknown system error -11 failures immediately. Missing files still behave exactly as before, and permanent read errors still propagate.

Diagram (if applicable)

Before:
[iCloud/FileProvider transient read errno -11] -> [memory read path] -> [raw error surfaces] -> [sync or compile aborts]

After:
[iCloud/FileProvider transient read errno -11] -> [shared bounded retry helper] -> [read succeeds] -> [sync or compile continues]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local source checkout, Node 22+/repo toolchain
• Model/provider: N/A
• Integration/channel (if any): memory-core, memory-wiki, memory-host-sdk
• Relevant config (redacted): default local repo config; synthetic temporary workspace/session/wiki dirs for injected proof

Steps

1. Run node scripts/run-vitest.mjs packages/memory-host-sdk/src/host/read-file.test.ts packages/memory-host-sdk/src/host/internal.test.ts extensions/memory-core/src/memory/manager.read-file.test.ts extensions/memory-core/src/memory/manager-sync-ops.startup-catchup.test.ts extensions/memory-wiki/src/compile.test.ts
2. Run pnpm check:changed
3. Run pnpm plugin-sdk:api:gen
4. Run node --max-old-space-size=8192 --import tsx scripts/generate-plugin-sdk-api-baseline.ts --check
5. Run the real behavior proof command above

Expected

• Transient FileProvider-style read failures recover inside the affected memory read paths.
• Focused regression tests and changed checks pass.
• The Plugin SDK baseline matches the intentional export change.

Actual

• All focused tests passed.
• pnpm check:changed passed.
• node --max-old-space-size=8192 --import tsx scripts/generate-plugin-sdk-api-baseline.ts --check passed after regenerating the baseline hash.
• The real behavior proof command showed successful retries and successful runtime results.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: direct runtime proof for readMemoryFile, buildSessionEntry, and compileMemoryWikiVault; focused regression suite; changed checks; Plugin SDK API baseline check.
• Edge cases checked: missing-file behavior remained on the existing code paths, session delta newline reads retry separately from session transcript full reads, and wiki compile retries the page-summary read path that re-reads pages after updates.
• What you did not verify: a live iCloud-backed vault reproducer during an actual FileProvider sync race.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: retrying too broadly could mask permanent filesystem errors.
  • Mitigation: the helper retries only known transient -11 / EAGAIN-family signatures with a short bounded backoff and still rethrows permanent errors.
• Risk: SDK export drift could break boundary checks if left untracked.
  • Mitigation: the PR updates src/plugin-sdk/memory-core-host-engine-storage.ts intentionally and regenerates docs/.generated/plugin-sdk-api-baseline.sha256.