feat(FN-828): lock in compaction behavior with comments and regression tests

- Add explicit comments to pi.ts documenting auto-compaction behavior during agent context management
- Add regression tests verifying compaction triggers correctly and preserves conversation integrity
- Document auto-compaction behavior in README under AI Engine section

README.md

@@ -244,6 +244,7 @@ Each pi agent session gets:
 - Custom system prompt for its role (triage specifier vs task executor)
 - Tools scoped to the correct directory (`createCodingTools(cwd)`)
 - In-memory sessions (no persistence needed)
+- Auto-compaction enabled to automatically summarize conversation history when context fills up, preventing context-window overflow in long-running agent conversations
 - The user's existing pi auth (API keys from `~/.pi/agent/auth.json`)
 
 ### Error Recovery

packages/engine/src/pi-create-kb-agent.test.ts

@@ -13,6 +13,7 @@ const findMock = vi.fn();
 const registerProviderMock = vi.fn();
 const refreshMock = vi.fn();
 const settingsManagerCreateMock = vi.fn(() => ({ kind: "settings-manager-create" }));
+const settingsManagerInMemoryMock = vi.fn(() => ({ kind: "settings-manager" }));
 const setFallbackResolverMock = vi.fn();
 const reloadMock = vi.fn(async () => {});
 
@@ -54,7 +55,7 @@ vi.mock("@mariozechner/pi-coding-agent", () => ({
   },
   SettingsManager: {
     create: settingsManagerCreateMock,
-    inMemory: () => ({ kind: "settings-manager" }),
+    inMemory: settingsManagerInMemoryMock,
   },
 }));
 
@@ -179,4 +180,40 @@ describe("createKbAgent", () => {
       model: { provider: "openai-codex", id: "gpt-5.4" },
     });
   });
+
+  it("enables auto-compaction to prevent context-window overflow", async () => {
+    const { createKbAgent } = await import("./pi.js");
+
+    await createKbAgent({
+      cwd: "/tmp",
+      systemPrompt: "test",
+      tools: "coding",
+    });
+
+    expect(settingsManagerInMemoryMock).toHaveBeenCalledTimes(1);
+    expect(settingsManagerInMemoryMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        compaction: { enabled: true },
+      }),
+    );
+  });
+
+  it("passes compaction enabled alongside retry settings", async () => {
+    const { createKbAgent } = await import("./pi.js");
+
+    await createKbAgent({
+      cwd: "/tmp",
+      systemPrompt: "test",
+      tools: "readonly",
+      defaultProvider: "anthropic",
+      defaultModelId: "claude-sonnet-4-5",
+    });
+
+    expect(settingsManagerInMemoryMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        compaction: { enabled: true },
+        retry: { enabled: true, maxRetries: 3 },
+      }),
+    );
+  });
 });

packages/engine/src/pi.ts

@@ -196,6 +196,11 @@ export async function createKbAgent(options: AgentOptions): Promise<AgentResult>
       ? createReadOnlyTools(options.cwd)
       : createCodingTools(options.cwd);
 
+  // Compaction is explicitly enabled to prevent context-window overflow during
+  // long-running agent conversations (triage, execution, review, merge).
+  // When the context fills up, pi auto-compacts the conversation history to
+  // keep the session alive without manual intervention. This must remain enabled
+  // as a reliability safeguard — disabling it would cause overflow failures.
   const settingsManager = SettingsManager.inMemory({
     compaction: { enabled: true },
     retry: { enabled: true, maxRetries: 3 },