fix(agents): defer bootstrap context-engine maintenance to background

dripsmvcp · dripsmvcp · commit b2dadefb5336 · 2026-06-04T15:24:38.000+09:00
Bootstrap/reconcile context-engine maintenance runs foreground, where deferred compaction debt cannot execute (allowDeferredCompactionExecution is background-only) and no background follow-up is scheduled — only turns defer. So debt created when bootstrap imports tail messages past the leaf trigger is stranded, leaving sessions repeating "deferred compaction still needed" (issue #67716, Case 1). Extend the deferred-maintenance gate so reason="bootstrap" also schedules the existing background debt consumer for engines that opt into background maintenance (turnMaintenanceMode === "background"). Foreground bootstrap is unchanged for engines without background maintenance, and the plugin-owned hot-cache sticky-debt path (Case 2) is intentionally left out of scope. Closes #67716
diff --git a/src/agents/embedded-agent-runner/context-engine-maintenance.test.ts b/src/agents/embedded-agent-runner/context-engine-maintenance.test.ts
@@ -674,6 +674,67 @@ describe("runContextEngineMaintenance", () => {
     });
   });
 
+  it("defers bootstrap maintenance to a background debt consumer for background-mode engines", async () => {
+    await withStateDirEnv("openclaw-bootstrap-maintenance-", async () => {
+      resetCommandQueueStateForTest();
+      resetTaskRegistryForTests({ persist: false });
+      resetTaskFlowRegistryForTests({ persist: false });
+
+      const sessionKey = "agent:main:bootstrap-1";
+      const maintain = vi.fn(async () => ({
+        changed: false,
+        bytesFreed: 0,
+        rewrittenEntries: 0,
+      }));
+      const backgroundEngine = {
+        info: {
+          id: "test",
+          name: "Test Engine",
+          turnMaintenanceMode: "background" as const,
+        },
+        ingest: async () => ({ ingested: true }),
+        assemble: async ({ messages }: { messages: unknown[] }) => ({
+          messages,
+          estimatedTokens: 0,
+        }),
+        compact: async () => ({ ok: true, compacted: false }),
+        maintain,
+      } as NonNullable<Parameters<typeof runContextEngineMaintenance>[0]["contextEngine"]>;
+
+      let deferred: Promise<void> | undefined;
+      const result = await runContextEngineMaintenance({
+        contextEngine: backgroundEngine,
+        sessionId: "bootstrap-1",
+        sessionKey,
+        sessionFile: "/tmp/session.jsonl",
+        reason: "bootstrap",
+        runtimeContext: {
+          workspaceDir: "/tmp/workspace",
+          tokenBudget: 2048,
+          currentTokenCount: 1536,
+        },
+        onDeferredMaintenance: (promise) => {
+          deferred = promise;
+        },
+      });
+
+      // Foreground bootstrap maintenance cannot pay deferred compaction debt, so
+      // a background consumer must be scheduled instead of running inline.
+      expect(result).toBeUndefined();
+      const queuedTasks = listTasksForOwnerKey(sessionKey).filter(
+        (task) => task.taskKind === TURN_MAINTENANCE_TASK_KIND,
+      );
+      expect(queuedTasks).toHaveLength(1);
+
+      await deferred;
+      expect(maintain).toHaveBeenCalledTimes(1);
+      const maintainParams = firstMaintainParams(maintain);
+      expectRecordFields(requireRecord(maintainParams.runtimeContext, "runtime context"), {
+        allowDeferredCompactionExecution: true,
+      });
+    });
+  });
+
   it("coalesces repeated requests into one active run plus one follow-up run for the same session", async () => {
     await withStateDirEnv("openclaw-turn-maintenance-", async () => {
       vi.useFakeTimers();
diff --git a/src/agents/embedded-agent-runner/context-engine-maintenance.ts b/src/agents/embedded-agent-runner/context-engine-maintenance.ts
@@ -711,8 +711,12 @@ export async function runContextEngineMaintenance(params: {
   }
 
   const executionMode = params.executionMode ?? "foreground";
+  // Bootstrap/reconcile runs foreground, where deferred compaction debt cannot
+  // execute (allowDeferredCompactionExecution is background-only). For engines
+  // that opt into background maintenance, schedule the same background debt
+  // consumer as turns so bootstrap-created debt is not stranded (issue #67716).
   const shouldDefer =
-    params.reason === "turn" &&
+    (params.reason === "turn" || params.reason === "bootstrap") &&
     executionMode !== "background" &&
     params.contextEngine.info.turnMaintenanceMode === "background";
 
