fix(memory-core): skip zero-hit forced sync for one-shot CLI managers

esqandil · esqandil · commit 66e35e855c9c · 2026-06-20T17:30:25.000Z
The bounded zero-hit forced sync prevents a slow/stuck sync from hanging the interactive memory_search deadline for long-lived (gateway) managers. But one-shot CLI runs (oneShotCliRun -> purpose=cli) tear the manager down in the tool's finally block, and close() awaits any in-flight sync UNBOUNDED (manager.ts awaitCurrentSync / qmd-manager pendingUpdate). That relocated the exact hang the bound prevents into cleanup. Skip the optional forced refresh entirely for purpose=cli: a one-shot run has no 'next call' to benefit from a warmed index, and search() already force-syncs a cold index inline + schedules a background sync, so nothing is lost. Addresses the ClawSweeper P1 on PR #94564. Adds a regression test: a one-shot run with a never-settling sync returns an available empty result, never starts the sync, and closes once.
diff --git a/extensions/memory-core/src/tools.test.ts b/extensions/memory-core/src/tools.test.ts
@@ -399,6 +399,41 @@ describe("memory_search unavailable payloads", () => {
     }
   });
 
+  it("skips the zero-hit forced sync for one-shot CLI runs so cleanup cannot hang", async () => {
+    // Regression: bounding the forced-sync wait in the tool body is not enough
+    // for one-shot CLI runs, because the `finally` tears the manager down and
+    // close() awaits any in-flight sync UNBOUNDED — relocating the hang to
+    // cleanup. The fix skips the optional forced sync entirely for purpose=cli,
+    // so a slow/stuck sync is never even started on that path.
+    let searchCalls = 0;
+    setMemorySearchImpl(async () => {
+      searchCalls += 1;
+      return [];
+    });
+    // If this sync were ever awaited (directly or via close()), the test would
+    // hang forever rather than fail — which is exactly the bug under guard.
+    setMemorySyncImpl(() => new Promise<void>(() => {}));
+
+    const tool = createMemorySearchToolOrThrow({
+      config: {
+        agents: { list: [{ id: "main", default: true }] },
+        memory: { citations: "off" },
+      },
+      oneShotCliRun: true,
+    });
+    const result = await tool.execute("one-shot-zero-hit", { query: "hidden thread codename" });
+
+    // Available, empty result — NOT an unavailable/timeout payload.
+    const details = result.details as { results?: unknown[]; disabled?: boolean };
+    expect(details.disabled).toBeUndefined();
+    expect(details.results).toEqual([]);
+    // The optional forced sync was skipped (never started) and only the initial
+    // search ran; the one-shot manager was still closed exactly once.
+    expect(searchCalls).toBe(1);
+    expect(getMemorySyncMockCalls()).toBe(0);
+    expect(getMemoryCloseMockCalls()).toBe(1);
+  });
+
   it("surfaces an honest timeout message instead of blaming the embedding provider", async () => {
     vi.useFakeTimers();
     try {
diff --git a/extensions/memory-core/src/tools.ts b/extensions/memory-core/src/tools.ts
@@ -605,14 +605,25 @@ export function createMemorySearchTool(options: {
                   if (pausedIndexIdentityReason) {
                     return;
                   }
-                  if (rawResults.length === 0 && activeMemory.manager.sync) {
+                  if (
+                    rawResults.length === 0 &&
+                    activeMemory.manager.sync &&
+                    memoryManagerPurpose !== "cli"
+                  ) {
                     // A zero-hit query against a populated index triggers a
                     // one-shot forced refresh in case the index is stale. Bound
                     // that refresh so a slow/degraded sync cannot consume the
                     // whole interactive budget (and falsely trip the
                     // provider-error cooldown). If the sync outruns its budget
                     // we keep our current results and let the background sync
                     // already scheduled by search() catch up the next call.
+                    //
+                    // One-shot CLI managers are intentionally excluded: they are
+                    // torn down in the `finally` below, and close() awaits any
+                    // in-flight sync *unbounded* — which would re-introduce the
+                    // exact hang this bound prevents, just relocated to cleanup.
+                    // A one-shot run also has no "next call" to benefit from a
+                    // warmed index, so skipping the optional refresh is a pure win.
                     const forcedSync = activeMemory.manager.sync({
                       reason: "search",
                       force: true,
