fix(memory): warn after startup watcher pressure check

[RomneyDa]

Summary

• add a shared memory watcher-pressure warning helper for built-in memory and QMD watchers
• warn only from runtime watcher state, not from config validation or a recursive startup scan
• keep the warning one-shot per manager and avoid continuous watcher polling
• cover built-in chokidar, Linux native directory watcher, and QMD watcher pressure paths with focused tests

How the warning works

• Chokidar-backed memory watchers warn on ready, after Chokidar has populated its initial watched state.
• Built-in memory watching also schedules one startup pressure sample 10 seconds after watcher setup finishes, then stops.
• Linux native directory watching uses that startup sample to aggregate directory watcher pressure across watched roots.
• Runtime native-to-chokidar fallback still restores coverage. A newly-created fallback watcher warns on its own ready; extending an already-ready watcher is not continuously polled.
• QMD collection watching uses the same watched-entry counter and warning helper, but samples from its own Chokidar ready callback.

Related

• Replaces the warning behavior reverted by Revert "fix(memory): warn on gateway watcher FD risk" #89246.
• Follow-up to fix(memory): warn on gateway watcher FD risk #89185, but now self-contained because fix(memory): warn on gateway watcher FD risk #89185 was reverted.
• Refs [Bug]: Every memory_search call leaks ~N FDs (one per .md file in workspace memory tree) on macOS; long-lived gateways degrade toward FD exhaustion #86613, where FD pressure was reproduced with large watched memory trees.

Verification

• node scripts/run-vitest.mjs extensions/memory-core/src/memory/manager.watcher-config.test.ts extensions/memory-core/src/memory/qmd-manager.test.ts
• pnpm exec oxlint extensions/memory-core/src/memory/manager-sync-ops.ts extensions/memory-core/src/memory/qmd-manager.ts extensions/memory-core/src/memory/watch-pressure.ts extensions/memory-core/src/memory/manager.watcher-config.test.ts extensions/memory-core/src/memory/qmd-manager.test.ts --deny-warnings
• git diff --check origin/main...HEAD

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 3, 2026, 2:55 PM ET / 18:55 UTC.

Summary
The PR adds shared runtime memory watcher-pressure warning logic for built-in memory and QMD watchers, clears the new startup timer on close, and adds focused watcher tests.

PR surface: Source +113, Tests +72. Total +185 across 6 files.

Reproducibility: yes. from source inspection for the missing warning path: current main starts the relevant watchers without a high-pressure warning, and the linked FD-pressure issue documents large watched memory trees. I did not run a live large-tree gateway reproduction in this read-only review.

Review metrics: 1 noteworthy metric.

• Config/default surfaces: 0 added, 0 changed, 0 removed. The reverted predecessor used config-validation warnings; this branch keeps the mitigation runtime-only and does not change upgrade defaults.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Risk before merge

• [P1] This is intentionally diagnostic-only: it warns about high watcher pressure but does not reduce watcher counts or eliminate the underlying FD-pressure failure mode.

Maintainer options:

1. Decide the mitigation before merge
   Land the runtime warning if maintainers accept warning-only mitigation, and track deeper adaptive watcher or FD-reduction work separately if needed.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] Protected maintainer/member PR with no narrow automated repair; the next action is maintainer judgment on warning-only mitigation plus normal merge validation.

Security
Cleared: No concrete security or supply-chain concern found; the diff is limited to memory-core TypeScript and tests with no dependency, workflow, lockfile, permission, or secret-handling changes.

Review details

Best possible solution:

Land the runtime warning if maintainers accept warning-only mitigation, and track deeper adaptive watcher or FD-reduction work separately if needed.

Do we have a high-confidence way to reproduce the issue?

Yes from source inspection for the missing warning path: current main starts the relevant watchers without a high-pressure warning, and the linked FD-pressure issue documents large watched memory trees. I did not run a live large-tree gateway reproduction in this read-only review.

Is this the best way to solve the issue?

Yes as a bounded mitigation, but not as a complete FD-pressure fix: the PR moves warning policy to actual watcher state and leaves config/default behavior intact. Maintainers still need to decide whether warning-only behavior is sufficient for this FD-pressure family.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 892602eaba07.

Label changes

Label justifications:

• P2: The PR addresses a real memory watcher FD-pressure diagnostic with bounded plugin-runtime impact, not an emergency outage or security issue.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The PR is maintainer/member-authored, so the external-contributor real behavior proof gate does not apply; the PR body lists focused test, lint, and diff-check commands.

Evidence reviewed

PR surface:

Source +113, Tests +72. Total +185 across 6 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	4	135	22	+113
Tests	2	82	10	+72
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	6	217	32	+185

Acceptance criteria:

• [P1] node scripts/run-vitest.mjs extensions/memory-core/src/memory/manager.watcher-config.test.ts extensions/memory-core/src/memory/qmd-manager.test.ts.
• [P1] pnpm exec oxlint extensions/memory-core/src/memory/manager-sync-ops.ts extensions/memory-core/src/memory/qmd-manager.ts extensions/memory-core/src/memory/watch-pressure.ts extensions/memory-core/src/memory/manager.watcher-config.test.ts extensions/memory-core/src/memory/qmd-manager.test.ts --deny-warnings.
• [P1] git diff --check origin/main...HEAD.

What I checked:

• Repository policy: Read the full root policy and scoped extensions policy; the touched files stay within the bundled memory-core plugin boundary and do not expand public SDK or config surfaces. (AGENTS.md:1, 892602eaba07)
• Current main built-in watcher path: Current main initializes built-in memory native/chokidar watchers without a pressure warning on Chokidar ready or a delayed startup pressure sample. (extensions/memory-core/src/memory/manager-sync-ops.ts:528, 892602eaba07)
• Current main QMD watcher path: Current main creates the QMD Chokidar watcher and logs ready without counting watched entries or warning on high watcher pressure. (extensions/memory-core/src/memory/qmd-manager.ts:1590, 892602eaba07)
• PR built-in watcher path: PR head adds Chokidar ready sampling and one delayed startup pressure sample that counts Chokidar paths first, then Linux native directory watchers if no warning was already shown. (extensions/memory-core/src/memory/manager-sync-ops.ts:624, 54e3bc26d84e)
• PR close path: PR head clears the new memory watch pressure startup timer during manager close before closing watcher resources. (extensions/memory-core/src/memory/manager.ts:1124, 54e3bc26d84e)
• PR QMD watcher path: PR head counts Chokidar watched entries from QMD's ready callback before logging watcher readiness. (extensions/memory-core/src/memory/qmd-manager.ts:1627, 54e3bc26d84e)

Likely related people:

• RomneyDa: They authored the merged gateway watcher warning PR and the follow-up revert referenced by this PR, so they are connected to the warning-policy history beyond only opening this branch. (role: recent warning-flow contributor; confidence: high; commits: 2405bbcbafa6, 0904f3e5539d; files: extensions/memory-core/src/memory/qmd-manager.ts, extensions/memory-core/src/memory/qmd-manager.test.ts, src/config/validation.ts)
• Vincent Koc: git blame attributes the current built-in and QMD watcher setup lines to commit eddf1c7 in this checkout. (role: current-main line owner; confidence: medium; commits: eddf1c776dd2; files: extensions/memory-core/src/memory/manager-sync-ops.ts, extensions/memory-core/src/memory/qmd-manager.ts)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[byungskers]

Bounded scan makes sense, but I wanted to flag one edge case: returning false after MEMORY_WATCH_FD_WARNING_SCAN_ENTRY_LIMIT means a very large tree can avoid the warning entirely if the first 20k entries don't push markdownFiles past the threshold yet.

Maybe that tradeoff is intentional, but if so I'd love a short comment near the early return explaining that this is a best-effort heuristic and can under-warn on huge trees. That would help future readers avoid treating the warning as exhaustive.

[RomneyDa]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26800560582
• Updated: 2026-06-02T05:40:40.623Z

[RomneyDa]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26803164683
• Updated: 2026-06-02T06:48:57.815Z

[RomneyDa]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26803830914
• Updated: 2026-06-02T07:08:33.360Z

[RomneyDa]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26905275345
• Updated: 2026-06-03T18:44:01.740Z