From 3cc0e9b6122e6af242ac12786749fa2efa7d09ec Mon Sep 17 00:00:00 2001
From: wassname <1103714+wassname@users.noreply.github.com>
Date: Thu, 16 Apr 2026 13:29:09 +0800
Subject: [PATCH] docs: clarify 'DCP summary blocks' not message blocks, note
 message counting reset

---
 README.md | 9 ++++++++-
 config.ts | 6 +++---
 index.ts  | 6 +++---
 3 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index c327573..51b3a09 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@ Automatically reduces token usage in Pi coding agent sessions by managing conver
 - **Manual mode** — disable autonomous compression nudges; trigger compression only via `/dcp compress` or explicit user request
 - **Session persistence** — compression blocks and pruning state survive session restarts
 - **`/dcp` commands** — inspect context usage, view stats, sweep tool outputs, and manage compression blocks interactively
+- **Auto-compaction** — triggers pi's built-in compaction when DCP summary blocks exceed a configurable fraction of context, preventing indefinite block accumulation
 
 ## Installation
 
@@ -81,7 +82,13 @@ DCP uses a layered configuration system (later layers override earlier ones):
   // Glob patterns — matching file paths are never pruned
   "protectedFilePatterns": [],
   // "off" | "minimal" | "detailed"
-  "pruneNotification": "detailed"
+  "pruneNotification": "detailed",
+  // Auto-compaction: trigger pi's built-in compaction when DCP summary blocks
+  // occupy >= this fraction of context tokens (0 = disabled).
+  // Compaction deactivates all DCP blocks and resets message counting.
+  // "compact": {
+  //   "autoCompactThreshold": 0.5
+  // }
 }
 ```
 
diff --git a/config.ts b/config.ts
index e8209ac..29e7a68 100644
--- a/config.ts
+++ b/config.ts
@@ -24,7 +24,7 @@ export interface DcpConfig {
     protectUserMessages: boolean
   }
   compact: {
-    autoCompactThreshold: number // 0-1, fraction of context that DCP blocks must occupy before triggering compaction (0 = disabled)
+    autoCompactThreshold: number // 0-1, fraction of context that DCP summary blocks must occupy before triggering compaction (0 = disabled). Compaction deactivates all DCP blocks and resets message counting.
   }
   strategies: {
     deduplication: {
@@ -62,7 +62,7 @@ const DEFAULT_CONFIG: DcpConfig = {
     protectUserMessages: false,
   },
   compact: {
-    autoCompactThreshold: 0.5, // trigger compaction when DCP blocks occupy >= 50% of context tokens
+    autoCompactThreshold: 0.5, // trigger compaction when DCP summary blocks occupy >= 50% of context tokens. Resets message counting.
   },
   strategies: {
     deduplication: {
@@ -109,7 +109,7 @@ const DEFAULT_CONFIG_FILE_CONTENT = `{
   // "protectedFilePatterns": [],
   // "pruneNotification": "detailed",
   // "compact": {
-  //   "autoCompactThreshold": 0.5  // trigger pi compaction when DCP blocks >= 50% of context (0 = disabled)
+  //   "autoCompactThreshold": 0.5  // trigger pi compaction when DCP summary blocks >= 50% of context (0 = disabled). Resets message counting.
   // }
 }
 `
diff --git a/index.ts b/index.ts
index c7dbe4c..06952cd 100644
--- a/index.ts
+++ b/index.ts
@@ -202,7 +202,7 @@ export default function (pi: ExtensionAPI) {
     // automaticStrategies is on) but skip autonomous nudge injection.
     const usage = ctx.getContextUsage()
     if (usage && usage.tokens !== null) {
-      // ── Auto-compaction: if DCP blocks exceed threshold, trigger pi compaction ──
+      // ── Auto-compaction: if DCP summary blocks exceed threshold, trigger pi compaction ──
       if (!state.manualMode && config.compact.autoCompactThreshold > 0) {
         const activeBlocks = state.compressionBlocks.filter((b) => b.active)
         const dcpBlockTokens = activeBlocks.reduce((sum, b) => sum + b.summaryTokenEstimate, 0)
@@ -263,10 +263,10 @@ export default function (pi: ExtensionAPI) {
     return { messages: prunedMessages }
   })
 
-  // ── 11. session_compact: deactivate all DCP blocks ───────────────────────
+  // ── 11. session_compact: deactivate all DCP summary blocks and reset message counting ───────────────────────
   // When pi's built-in compaction runs, it folds all prior context (including
   // DCP summary blocks) into a single compaction summary. All active DCP
-  // blocks are now redundant — deactivate them.
+  // blocks are now redundant — deactivate them and reset message counting.
   pi.on("session_compact", async (_event, _ctx) => {
     const activeBlocks = state.compressionBlocks.filter((b) => b.active)
     if (activeBlocks.length > 0) {