billion-context-dsh 0.1.3 → 0.1.5

package/README.en.md

@@ -3,7 +3,7 @@
 [English](./README.en.md) | [中文](./README.md)
 
 > **⚠️ Beta notice — not for production use**
-> This project (**v0.1.3**) is a work-in-progress beta. The [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) itself is also in **public beta**. **Do not use either in engineering / production environments** — expect breaking changes and rough edges.
+> This project (**v0.1.5**) is a work-in-progress beta. The [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) itself is also in **public beta**. **Do not use either in engineering / production environments** — expect breaking changes and rough edges.
 
 <p align="center">
 <strong>Built with gratitude on top of these projects</strong> — please give them a ⭐:
@@ -50,6 +50,8 @@ This is the DeepSeek Harness port of [billion-context-pi](https://github.com/ran
 
 ## Install
 
+> 💡 **Want DeepSeek Harness to install it for you?** This repo itself runs on DSH: hand [docs/INSTALL.md](docs/INSTALL.md) to an agent in a session and it will read the guide, inspect your profile, wire the composition, and verify the mount. Two preconditions: ① the config lives under `~/.dsh`, so you approve one file-permission prompt; ② afterwards ask it to call `acp_status` as proof.
+
 ```bash
 npm install billion-context-dsh
 ```
@@ -103,6 +105,7 @@ DSH derives every model request from its append-only session log (the *surface*)
 | `search_context` | scores block summaries + originals rebuilt from the log |
 | `acp_status` | block ledger + context pressure |
 | block state | in-memory kernel state + **log-rebuilt ledger** (no sidecar files) |
+| tiered distillation (T2/T3) | re-compressing a block's summary node distills that block (tier 2); distilling a tier-2 block yields tier 3. Tier + kernel block ids are persisted to the log, so kernel state rehydrates from the log after a restart and stays distillable |
 
 The load-bearing compression guidance (tools, philosophy, summary rules) is registered as a one-time system-prompt section, so nudges stay short. There is deliberately **no automatic summarization**: automatic policy only nudges the model (`compactIfNeeded` returns null).
 
@@ -116,7 +119,7 @@ A walkthrough of the ACP philosophy this project inherits — how active context
 
 | Tool | What it does |
 | --- | --- |
-| `compress` | Replace a seq range with a dense summary you write (edges auto-balanced to tool-pair boundaries) |
+| `compress` | Replace a seq range with a dense summary you write (edges auto-balanced to tool-pair boundaries); re-compressing a block's summary node distills it (tier 2/3) |
 | `decompress` | Restore a previously compressed block's original content (read-only) |
 | `search_context` | Search compressed block summaries and originals by keyword |
 | `acp_status` | Context usage, compressed blocks, compressible ranges |

package/README.md

@@ -3,7 +3,7 @@
 [中文](./README.md) | [English](./README.en.md)
 
 > **⚠️ 测试版声明——请勿用于生产环境**
-> 本项目（**v0.1.3**）仍处于开发中的测试版。[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 本身也处于**公开测试版**阶段。**请勿将两者用于工程化 / 生产环境**——预期会有破坏性变更与粗糙之处。
+> 本项目（**v0.1.5**）仍处于开发中的测试版。[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 本身也处于**公开测试版**阶段。**请勿将两者用于工程化 / 生产环境**——预期会有破坏性变更与粗糙之处。
 
 <p align="center">
 <strong>衷心感谢以下项目——请给它们一个 ⭐：</strong>
@@ -50,6 +50,11 @@
 
 ## 安装
 
+> 💡 **想让 DeepSeek Harness 帮你装？** 本仓库本身就运行在 DSH 上：把
+> [docs/INSTALL.md](docs/INSTALL.md) 交给会话里的 agent，它会读取指南、解析
+> 你的 profile、编辑组合配置并验证挂载。前提：① 配置写在 `~/.dsh` 下，需要
+> 你批准一次文件权限；② 装完让它调用 `acp_status` 自证。
+
 ```bash
 npm install billion-context-dsh
 ```
@@ -102,6 +107,7 @@ DSH 的每个模型请求都派生自其 append-only 会话日志（*surface*）
 | `search_context` | 对从日志重建的块摘要与原文打分 |
 | `acp_status` | 块账本与上下文压力 |
 | 块状态 | 内存内核状态 + **日志重建账本**（无旁车文件） |
+| 分层蒸馏（T2/T3） | 再次压缩某块的摘要节点 = 蒸馏该块（tier 2），蒸馏 tier-2 块得 tier 3；tier 与内核块 id 持久化进日志，重启后内核状态从日志再水合、可继续蒸馏 |
 
 承载性的压缩指引（工具、哲学、摘要规则）注册为一次性系统提示段，因此 nudge 保持简短。刻意**不做自动摘要**：自动策略只 nudge 模型（`compactIfNeeded` 返回 null）。
 
@@ -115,7 +121,7 @@ DSH 的每个模型请求都派生自其 append-only 会话日志（*surface*）
 
 | 工具 | 作用 |
 | --- | --- |
-| `compress` | 用你书写的紧凑摘要替换 seq 范围（边界自动平衡到 tool-call/result 配对点） |
+| `compress` | 用你书写的紧凑摘要替换 seq 范围（边界自动平衡到 tool-call/result 配对点）；对某块的摘要节点再次压缩 = 分层蒸馏（tier 2/3） |
 | `decompress` | 恢复已压缩块的原始内容（只读） |
 | `search_context` | 按关键词搜索压缩块摘要与原文 |
 | `acp_status` | 上下文占用、压缩块、可压缩范围 |

package/dist/index.d.ts

@@ -35,7 +35,7 @@ export { ACP_SYSTEM_PROMPT, ACP_SYSTEM_PROMPT_ORDER } from './system-prompt.ts';
 export { makeTools, type ToolEnvironment } from './tools.ts';
 export { acpCommand } from './commands.ts';
 export { buildNudge, type NudgeEnvironment, type NudgeOutcome } from './nudge.ts';
-export { rebuildBlockLedger, resolveSurfaceRange, runCompactionTransaction, shadowedSeqsOf, findOpenTurn, assertNoActiveCompaction, type AcpBlockLedgerEntry, type CompactionTransactionInput, } from './region.ts';
+export { rebuildBlockLedger, resolveSurfaceRange, runCompactionTransaction, shadowedSeqsOf, findOpenTurn, assertNoActiveCompaction, blockRegistry, blockRefForSummarySeq, compactionIdsOfKernelBlocks, summarySeqOfKernelBlock, expandShadowedSeqs, type AcpBlockLedgerEntry, type CompactionTransactionInput, } from './region.ts';
 export { eventsToCoreMessages, projectEvent, surfaceEventsOf, extractEventText } from './messages.ts';
 export interface AcpConfig {
     /** The context window used for pressure decisions. Default 128000. */

package/dist/index.js

@@ -7,42 +7,6 @@ import { createCore } from "acp-kernel";
 
 // src/state.ts
 import { createInitialState } from "acp-kernel";
-var AcpStateStore = class {
-  states = /* @__PURE__ */ new Map();
-  /** Kernel state for one session, initialised on first access. */
-  stateFor(session) {
-    const id = session.id;
-    const existing = this.states.get(id);
-    if (existing !== void 0) return existing;
-    const state = createInitialState();
-    this.states.set(id, state);
-    return state;
-  }
-  set(session, state) {
-    this.states.set(session.id, state);
-  }
-  delete(session) {
-    this.states.delete(session.id);
-  }
-};
-
-// src/tools.ts
-import { defineTool } from "@deepseek-ai/dsh-tools";
-import { defaultCountTokens as defaultCountTokens2 } from "acp-kernel";
-
-// src/config.ts
-import { defaultConfig } from "acp-kernel";
-function kernelConfigFor(input) {
-  const nudgePatch = {};
-  if (input.nudgeMinContextLimitPct !== void 0) nudgePatch.minContextLimitPct = input.nudgeMinContextLimitPct;
-  if (input.nudgeMaxContextLimitPct !== void 0) nudgePatch.maxContextLimitPct = input.nudgeMaxContextLimitPct;
-  if (input.nudgeEmergencyThresholdPct !== void 0) nudgePatch.emergencyThresholdPct = input.nudgeEmergencyThresholdPct;
-  const overrides = { ...input.coreOverrides };
-  if (Object.keys(nudgePatch).length > 0) {
-    overrides.nudge = { ...defaultConfig(input.modelContextLimit).nudge, ...nudgePatch };
-  }
-  return defaultConfig(input.modelContextLimit, overrides);
-}
 
 // src/region.ts
 import { randomUUID } from "crypto";
@@ -145,6 +109,9 @@ function eventsToCoreMessages(events) {
 function surfaceEventsOf(session) {
   return session.surface.nodes.map((seq) => session.events[seq]).filter((event) => event !== void 0);
 }
+function allLogMessages(session) {
+  return eventsToCoreMessages(session.events);
+}
 function extractEventText(event) {
   switch (event.type) {
     case "user/message":
@@ -245,6 +212,9 @@ function shadowedSeqsOf(session, start, end) {
   const endIdx = nodes.indexOf(end);
   return nodes.slice(startIdx, endIdx + 1);
 }
+function readCompactionSummary(event) {
+  return event.data;
+}
 function runCompactionTransaction(session, input) {
   assertNoActiveCompaction(session.events);
   const turn = findOpenTurn(session.events);
@@ -258,7 +228,12 @@ function runCompactionTransaction(session, input) {
     shadowedSeqs: [...input.shadowedSeqs],
     shadowedTokenCount: input.shadowedTokenCount,
     provider: input.provider,
-    model: input.model
+    model: input.model,
+    tier: input.tier ?? 1,
+    ...input.kernelBlockId === void 0 ? {} : { kernelBlockId: input.kernelBlockId },
+    ...input.parentBlockIds === void 0 || input.parentBlockIds.length === 0 ? {} : { parentBlockIds: [...input.parentBlockIds] },
+    ...input.directMessageIds === void 0 ? {} : { directMessageIds: [...input.directMessageIds] },
+    ...input.effectiveMessageIds === void 0 ? {} : { effectiveMessageIds: [...input.effectiveMessageIds] }
   }).seq);
   const message = createUserMessage({
     content: input.summary,
@@ -271,11 +246,19 @@ function runCompactionTransaction(session, input) {
   seqs.push(session.append("compaction/end", { compactionId, turn }).seq);
   return { compactionId, seqs };
 }
+function summarySeqOfCompaction(events, compactionId) {
+  for (const event of events) {
+    if (event.type !== "user/message") continue;
+    const source = event.data.source;
+    if (source?.plugin === "compact" && source.compactionId === compactionId) return event.seq;
+  }
+  return null;
+}
 function rebuildBlockLedger(events) {
   const ledger = [];
   for (const event of events) {
     if (event.type !== "compaction/summary") continue;
-    const data = event.data;
+    const data = readCompactionSummary(event);
     let shadowedTokenCount = data.shadowedTokenCount;
     if (shadowedTokenCount === 0) {
       shadowedTokenCount = 0;
@@ -284,13 +267,25 @@ function rebuildBlockLedger(events) {
         if (original !== void 0) shadowedTokenCount += defaultCountTokens(extractEventText(original));
       }
     }
+    const tier = data.tier === 2 || data.tier === 3 ? data.tier : 1;
+    const parentBlockIds = Array.isArray(data.parentBlockIds) ? [...data.parentBlockIds] : [];
+    const directMessageIds = Array.isArray(data.directMessageIds) ? [...data.directMessageIds] : void 0;
+    const effectiveMessageIds = Array.isArray(data.effectiveMessageIds) ? [...data.effectiveMessageIds] : void 0;
+    const summarySeq = summarySeqOfCompaction(events, data.compactionId);
     ledger.push({
       blockId: data.compactionId,
       summary: extractText(data.summary),
       shadowedSeqs: [...data.shadowedSeqs],
       shadowedTokenCount,
       start: data.shadowedRange.start,
-      end: data.shadowedRange.end
+      end: data.shadowedRange.end,
+      tier,
+      parentBlockIds,
+      ...typeof data.kernelBlockId === "string" ? { kernelBlockId: data.kernelBlockId } : {},
+      ...summarySeq === null ? {} : { summarySeq },
+      ...directMessageIds === void 0 ? {} : { directMessageIds },
+      ...effectiveMessageIds === void 0 ? {} : { effectiveMessageIds },
+      createdAt: event.time
     });
   }
   return ledger;
@@ -354,6 +349,184 @@ function surfaceSummary(session) {
   const last = nodes[nodes.length - 1];
   return `${nodes.length} nodes, seqs ${first}..${last}`;
 }
+function blockRegistry(session) {
+  const ledger = rebuildBlockLedger(session.events);
+  const kernelIdOf = /* @__PURE__ */ new Map();
+  const raw = [];
+  let next = 1;
+  for (const entry of ledger) {
+    let kernelBlockId;
+    if (entry.kernelBlockId !== void 0 && /^b\d+$/.test(entry.kernelBlockId)) {
+      kernelBlockId = entry.kernelBlockId;
+      const num = Number(kernelBlockId.slice(1));
+      if (Number.isInteger(num)) next = Math.max(next, num + 1);
+    } else {
+      kernelBlockId = `b${next}`;
+      next += 1;
+    }
+    kernelIdOf.set(entry.blockId, kernelBlockId);
+    raw.push({
+      blockId: entry.blockId,
+      kernelBlockId,
+      tier: entry.tier,
+      summarySeq: entry.summarySeq ?? null,
+      active: true,
+      parentBlockIds: [...entry.parentBlockIds]
+    });
+  }
+  const consumed = /* @__PURE__ */ new Set();
+  for (const entry of raw) {
+    for (const parent of entry.parentBlockIds) consumed.add(parent);
+  }
+  return raw.map((entry) => ({
+    ...entry,
+    active: !consumed.has(entry.blockId)
+  }));
+}
+function blockRefForSummarySeq(session, seq) {
+  const event = session.events[seq];
+  if (event?.type !== "user/message") return null;
+  const source = event.data.source;
+  if (source?.plugin !== "compact" || source.compactionId === void 0) return null;
+  const entry = blockRegistry(session).find((r) => r.blockId === source.compactionId);
+  if (entry === void 0) return null;
+  return entry.kernelBlockId;
+}
+function compactionIdsOfKernelBlocks(session, kernelBlockIds) {
+  if (kernelBlockIds.length === 0) return [];
+  const byKernel = new Map(blockRegistry(session).map((r) => [r.kernelBlockId, r.blockId]));
+  return kernelBlockIds.map((id) => byKernel.get(id)).filter((id) => id !== void 0);
+}
+function summarySeqOfKernelBlock(session, kernelBlockId) {
+  const entry = blockRegistry(session).find((r) => r.kernelBlockId === kernelBlockId);
+  return entry?.active ? entry.summarySeq : null;
+}
+function checkpointBlockIdOf(events, seq) {
+  const event = events[seq];
+  if (event?.type !== "user/message") return null;
+  const source = event.data.source;
+  if (source?.plugin !== "compact" || source.compactionId === void 0) return null;
+  return source.compactionId;
+}
+function expandShadowedSeqs(session, blockId) {
+  const ledger = rebuildBlockLedger(session.events);
+  const byId = new Map(ledger.map((entry) => [entry.blockId, entry]));
+  const root = byId.get(blockId);
+  if (root === void 0) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (entry) => {
+    if (seen.has(entry.blockId)) return;
+    seen.add(entry.blockId);
+    for (const seq of entry.shadowedSeqs) {
+      const childId = checkpointBlockIdOf(session.events, seq);
+      const child = childId === null ? void 0 : byId.get(childId);
+      if (child !== void 0) visit(child);
+      else out.push(seq);
+    }
+  };
+  visit(root);
+  return out;
+}
+
+// src/state.ts
+function rebuildKernelBlocks(events) {
+  const ledger = rebuildBlockLedger(events);
+  if (ledger.length === 0) return [];
+  const kernelIdOf = /* @__PURE__ */ new Map();
+  const parentKernelIds = /* @__PURE__ */ new Map();
+  let next = 1;
+  for (const entry of ledger) {
+    let kernelBlockId;
+    if (entry.kernelBlockId !== void 0 && /^b\d+$/.test(entry.kernelBlockId)) {
+      kernelBlockId = entry.kernelBlockId;
+      const num = Number(kernelBlockId.slice(1));
+      if (Number.isInteger(num)) next = Math.max(next, num + 1);
+    } else {
+      kernelBlockId = `b${next}`;
+      next += 1;
+    }
+    kernelIdOf.set(entry.blockId, kernelBlockId);
+    parentKernelIds.set(
+      entry.blockId,
+      entry.parentBlockIds.map((parent) => kernelIdOf.get(parent)).filter((id) => id !== void 0)
+    );
+  }
+  const consumed = /* @__PURE__ */ new Set();
+  for (const entry of ledger) {
+    for (const parent of entry.parentBlockIds) consumed.add(parent);
+  }
+  const blocks = [];
+  for (const entry of ledger) {
+    const blockId = kernelIdOf.get(entry.blockId);
+    const direct = entry.directMessageIds ?? [...entry.shadowedSeqs.map(String)];
+    const effective = entry.effectiveMessageIds ?? (entry.tier > 1 ? entry.summarySeq === void 0 ? [...entry.shadowedSeqs.map(String)] : [String(entry.summarySeq)] : [...entry.shadowedSeqs.map(String)]);
+    blocks.push({
+      blockId,
+      runId: `r${blocks.length + 1}`,
+      tier: entry.tier,
+      summary: entry.summary,
+      directMessageIds: [...direct],
+      effectiveMessageIds: [...effective],
+      directBlockIds: parentKernelIds.get(entry.blockId) ?? [],
+      compressedTokens: entry.shadowedTokenCount,
+      createdAt: entry.createdAt,
+      survivedCount: 0,
+      generation: "young",
+      active: !consumed.has(entry.blockId)
+    });
+  }
+  return blocks;
+}
+function nextBlockIdAfter(events) {
+  const blocks = rebuildKernelBlocks(events);
+  let max = 0;
+  for (const block of blocks) {
+    const num = Number(block.blockId.slice(1));
+    if (Number.isInteger(num)) max = Math.max(max, num);
+  }
+  return max + 1;
+}
+var AcpStateStore = class {
+  states = /* @__PURE__ */ new Map();
+  /** Kernel state for one session, initialised on first access. */
+  stateFor(session) {
+    const id = session.id;
+    const existing = this.states.get(id);
+    if (existing !== void 0) return existing;
+    const state = createInitialState();
+    if (session.events.some((event) => event.type === "compaction/summary")) {
+      state.blocks = rebuildKernelBlocks(session.events);
+      state.nextBlockId = nextBlockIdAfter(session.events);
+    }
+    this.states.set(id, state);
+    return state;
+  }
+  set(session, state) {
+    this.states.set(session.id, state);
+  }
+  delete(session) {
+    this.states.delete(session.id);
+  }
+};
+
+// src/tools.ts
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { defaultCountTokens as defaultCountTokens2 } from "acp-kernel";
+
+// src/config.ts
+import { defaultConfig } from "acp-kernel";
+function kernelConfigFor(input) {
+  const nudgePatch = {};
+  if (input.nudgeMinContextLimitPct !== void 0) nudgePatch.minContextLimitPct = input.nudgeMinContextLimitPct;
+  if (input.nudgeMaxContextLimitPct !== void 0) nudgePatch.maxContextLimitPct = input.nudgeMaxContextLimitPct;
+  if (input.nudgeEmergencyThresholdPct !== void 0) nudgePatch.emergencyThresholdPct = input.nudgeEmergencyThresholdPct;
+  const overrides = { ...input.coreOverrides };
+  if (Object.keys(nudgePatch).length > 0) {
+    overrides.nudge = { ...defaultConfig(input.modelContextLimit).nudge, ...nudgePatch };
+  }
+  return defaultConfig(input.modelContextLimit, overrides);
+}
 
 // src/tools.ts
 function textOutput() {
@@ -412,8 +585,9 @@ async function handleCompress(env, args, exec) {
   const agent = requireAgent(exec);
   const session = agent.session;
   const state = env.store.stateFor(session);
-  const coreMessages = eventsToCoreMessages(surfaceEventsOf(session));
-  const tokenCount = coreMessages.reduce((sum, message) => sum + defaultCountTokens2(message.text ?? ""), 0);
+  const coreMessages = allLogMessages(session);
+  const surfaceMessages = eventsToCoreMessages(surfaceEventsOf(session));
+  const tokenCount = surfaceMessages.reduce((sum, message) => sum + defaultCountTokens2(message.text ?? ""), 0);
   const config = kernelConfigFor(env);
   const turn = env.kernel.processTurn({ messages: coreMessages, state, config, tokenCount });
   env.store.set(session, turn.state);
@@ -422,8 +596,10 @@ async function handleCompress(env, args, exec) {
     const startSeq = parseSeq(range.startSeq);
     const endSeq = parseSeq(range.endSeq);
     const { start, end } = resolveSurfaceRange(session, startSeq, endSeq);
-    const startRef = byRaw[String(start)];
-    const endRef = byRaw[String(end)];
+    const startBlockRef = blockRefForSummarySeq(session, start);
+    const endBlockRef = blockRefForSummarySeq(session, end);
+    const startRef = startBlockRef ?? byRaw[String(start)];
+    const endRef = endBlockRef ?? byRaw[String(end)];
     if (startRef === void 0 || endRef === void 0) {
       throw new Error(
         `billion-context-dsh: seq ${start}..${end} has no assigned ref \u2014 the range must be on the current surface (run acp_status for the live seq list)`
@@ -445,15 +621,44 @@ async function handleCompress(env, args, exec) {
     messages: coreMessages,
     state: turn.state,
     config
+    // Deliberately NOT overriding protectedMessageIds: with the full log the
+    // kernel's recent/last-user protection is computed over the same
+    // non-block-covered messages as the visible feed, so default behavior is
+    // preserved. Any 'Excluded N protected message(s)' warning is surfaced.
   });
   if (applied.result.errors.length > 0) {
     return { text: `compress failed: ${applied.result.errors.join("; ")}` };
   }
   env.store.set(session, applied.state);
+  const previousIds = new Set(turn.state.blocks.map((block) => block.blockId));
+  const newBlocks = applied.state.blocks.filter((block) => !previousIds.has(block.blockId));
+  const blockByRangeKey = new Map(newBlocks.map((block) => [`${block.startRef}::${block.endRef}`, block]));
+  const warningByRangeKey = /* @__PURE__ */ new Map();
+  const freeWarnings = [];
+  for (const warning of applied.result.warnings) {
+    const match = /^Skipped range \((.+?)\.\.(.+?)\)/.exec(warning);
+    if (match !== null) {
+      const key = `${match[1]}::${match[2]}`;
+      const list = warningByRangeKey.get(key) ?? [];
+      list.push(warning);
+      warningByRangeKey.set(key, list);
+    } else {
+      freeWarnings.push(warning);
+    }
+  }
   const lines = [];
+  let skippedRanges = 0;
   for (let index = 0; index < ranges.length; index += 1) {
     const range = ranges[index];
     const original = args.content[index];
+    const key = `${range.startRef}::${range.endRef}`;
+    const block = blockByRangeKey.get(key);
+    if (block === void 0) {
+      skippedRanges += 1;
+      const warnings = warningByRangeKey.get(key) ?? [];
+      for (const warning of warnings) lines.push(`  ${warning}`);
+      continue;
+    }
     const { start, end } = range;
     const shadowed = shadowedSeqsOf(session, start, end);
     let shadowedTokens = 0;
@@ -461,6 +666,8 @@ async function handleCompress(env, args, exec) {
       const event = session.events[seq];
       if (event !== void 0) shadowedTokens += defaultCountTokens2(extractEventText(event));
     }
+    const tier = block.tier === 2 || block.tier === 3 ? block.tier : 1;
+    const parentBlockIds = compactionIdsOfKernelBlocks(session, block.directBlockIds);
     const { compactionId } = runCompactionTransaction(session, {
       start,
       end,
@@ -468,17 +675,27 @@ async function handleCompress(env, args, exec) {
       summary: [{ type: "text", text: original.summary }],
       shadowedTokenCount: shadowedTokens,
       provider: agent.options.provider ?? "",
-      model: agent.options.model ?? ""
+      model: agent.options.model ?? "",
+      tier,
+      kernelBlockId: block.blockId,
+      ...parentBlockIds.length === 0 ? {} : { parentBlockIds },
+      // Record the kernel block's raw coverage so a restarted engine
+      // rehydrates the SAME effective messages (a tier-2 block's coverage is
+      // its parents' originals, not the checkpoint node).
+      directMessageIds: block.directMessageIds,
+      effectiveMessageIds: block.effectiveMessageIds
     });
     const adjusted = start !== range.startSeq || end !== range.endSeq;
+    const tierLabel = tier === 1 ? "" : `, tier ${tier}`;
     lines.push(
-      `  block ${compactionId.slice(0, 8)}: seqs ${start}..${end}, ${shadowed.length} messages shadowed` + (adjusted ? ` (adjusted from ${range.startSeq}..${range.endSeq} to balanced edges)` : "")
+      `  block ${compactionId.slice(0, 8)}: seqs ${start}..${end}, ${shadowed.length} messages shadowed${tierLabel}` + (adjusted ? ` (adjusted from ${range.startSeq}..${range.endSeq} to balanced edges)` : "")
     );
   }
-  return {
-    text: `Compressed ${applied.result.blocksCreated} block(s), ~${applied.result.tokensCompressed} tokens reclaimed.
-${lines.join("\n")}`
-  };
+  const summaryLine = `Compressed ${applied.result.blocksCreated} block(s), ~${applied.result.tokensCompressed} tokens reclaimed.`;
+  const warningLines = [...freeWarnings.map((warning) => `  ${warning}`), ...lines];
+  const footer = skippedRanges > 0 ? `  (${skippedRanges} range(s) skipped \u2014 see warnings above)` : "";
+  return { text: `${summaryLine}
+${[...warningLines, footer].filter((line) => line !== "").join("\n")}` };
 }
 var decompressParameters = {
   blockId: { type: "string", required: true, description: "Block id from acp_status or search_context (the compaction id)." }
@@ -491,13 +708,14 @@ function handleDecompress(_env, args, exec) {
     return { text: `decompress: block "${args.blockId}" not found (see acp_status for the block list)` };
   }
   const parts = [];
-  for (const seq of block.shadowedSeqs) {
+  for (const seq of expandShadowedSeqs(session, block.blockId)) {
     const event = session.events[seq];
     const text = event === void 0 ? "" : extractEventText(event);
     if (text.length > 0) parts.push(`[seq ${seq}] ${text}`);
   }
+  const tierNote = block.tier > 1 ? ` (tier ${block.tier}, distills ${block.parentBlockIds.length} block(s))` : "";
   return {
-    text: `Block ${block.blockId} \u2014 ${block.summary}
+    text: `Block ${block.blockId} \u2014 ${block.summary}${tierNote}
 
 ${parts.join("\n\n") || "(no recoverable content)"}`
   };
@@ -551,7 +769,7 @@ function makeTools(env) {
   return [
     defineTool({
       name: "compress",
-      description: "Replace older conversation ranges with dense summaries you write. Each message seq is a surface reference. Single range: compress({ content: [{ startSeq, endSeq, summary }] }). Batch multiple unrelated ranges in one call. Never compress content the current step is actively using.",
+      description: "Replace older conversation ranges with dense summaries you write. Each message seq is a surface reference. Single range: compress({ content: [{ startSeq, endSeq, summary }] }). Batch multiple unrelated ranges in one call (each content entry becomes its own block); keep ranges disjoint. Never compress content the current step is actively using.",
       parameters: compressParameters,
       output: textOutput(),
       async execute(args, exec) {
@@ -604,7 +822,8 @@ function statusText(env, agent) {
     `  estimated context: ${estimated} / ${limit} (${Math.round(estimated / limit * 100)}%)`
   ];
   for (const block of ledger.slice(0, 10)) {
-    lines.push(`  - ${block.blockId.slice(0, 8)}: seqs ${block.start}..${block.end} \u2014 ${block.summary.slice(0, 80)}`);
+    const tier = block.tier > 1 ? ` [T${block.tier}]` : "";
+    lines.push(`  - ${block.blockId.slice(0, 8)}${tier}: seqs ${block.start}..${block.end} \u2014 ${block.summary.slice(0, 80)}`);
   }
   return lines.join("\n");
 }
@@ -620,6 +839,9 @@ function compressText(env, agent, args) {
   }
   const session = agent.session;
   const { start, end } = resolveSurfaceRange(session, startSeq, endSeq);
+  if (blockRefForSummarySeq(session, start) !== null || blockRefForSummarySeq(session, end) !== null) {
+    return "/acp compress: the range touches a compressed block summary node \u2014 distill it with the compress tool (seq-based batch), not /acp compress";
+  }
   const shadowed = shadowedSeqsOf(session, startSeq, endSeq);
   let shadowedTokens = 0;
   for (const seq of shadowed) {
@@ -643,7 +865,7 @@ function decompressText(_env, agent, args) {
   const ledger = rebuildBlockLedger(session.events);
   const block = ledger.find((entry) => entry.blockId.startsWith(args[0]));
   if (block === void 0) return `block "${args[0]}" not found (see /acp status)`;
-  const parts = block.shadowedSeqs.map((seq) => extractEventText(session.events[seq])).filter((text) => text.length > 0);
+  const parts = expandShadowedSeqs(session, block.blockId).map((seq) => extractEventText(session.events[seq])).filter((text) => text.length > 0);
   return `Block ${block.blockId} \u2014 ${block.summary}
 
 ${parts.join("\n\n") || "(no recoverable content)"}`;
@@ -680,9 +902,9 @@ function rangeTable(session) {
   return [
     "",
     `Surface: ${surfaceSummary(session)}`,
-    "Compressible ranges (refs are surface seqs):",
+    "Compressible ranges (suggestions only \u2014 compress any consumed span; refs are surface seqs):",
     ...lines,
-    "Compress with: compress({ content: [{ startSeq, endSeq, summary }] })"
+    "Compress with: compress({ content: [{ startSeq, endSeq, summary }] }) \u2014 content is an array: batch multiple unrelated segments in one call, each entry its own block. Keep ranges disjoint."
   ].join("\n");
 }
 function measuredTokenCount(agent, coreMessages) {
@@ -694,8 +916,9 @@ function measuredTokenCount(agent, coreMessages) {
 function buildNudge(agent, env, lastNudgeTurn) {
   const session = agent.session;
   const state = env.store.stateFor(session);
-  const coreMessages = eventsToCoreMessages(surfaceEventsOf(session));
-  const tokenCount = measuredTokenCount(agent, coreMessages);
+  const coreMessages = allLogMessages(session);
+  const surfaceMessages = eventsToCoreMessages(surfaceEventsOf(session));
+  const tokenCount = measuredTokenCount(agent, surfaceMessages);
   const config = kernelConfigFor(env);
   const turn = env.kernel.processTurn({ messages: coreMessages, state, config, tokenCount });
   env.store.set(session, turn.state);
@@ -717,7 +940,18 @@ function buildNudgeText(nudge, emergency, session) {
   const pct = Math.round(Math.min(nudge.contextUsage, 1) * 100);
   const frame = emergency ? `\u26A0\uFE0F Context usage is at ${pct}% of the window \u2014 nearly full. Consider compressing consumed ranges soon so working context stays available; the choice and timing are yours.` : `Context usage is at ${pct}%. This is a suggestion, not a requirement \u2014 you decide whether and when to compress.`;
   const guidance = "Compress by need, not by percentage: replace only ranges you have genuinely consumed, with dense self-contained summaries.";
-  return [frame, "", guidance, rangeTable(session)].join("\n");
+  const parts = [frame, "", guidance];
+  if ((nudge.tier === 2 || nudge.tier === 3) && (nudge.tierTargetBlocks?.length ?? 0) > 0) {
+    const targets = nudge.tierTargetBlocks;
+    const summarySeqs = targets.map((block) => summarySeqOfKernelBlock(session, block.blockId)).filter((seq) => seq !== null);
+    const pending = nudge.tier === 2 ? nudge.breakdown?.pendingT2 : nudge.breakdown?.pendingT3;
+    const tokens = typeof pending === "number" ? pending : 0;
+    parts.push(
+      `Tier ${nudge.tier}: ${targets.length} tier-${nudge.tier - 1} block(s) distillable (${tokens} tokens) \u2014 compress their summary node(s) [seqs ${summarySeqs.join(", ")}] to reclaim the original messages.`
+    );
+  }
+  parts.push(rangeTable(session));
+  return parts.join("\n");
 }
 
 // src/system-prompt.ts
@@ -729,11 +963,13 @@ YOU decide whether and when to compress context. Nothing forces you: the injecte
 ${COMPRESS_PHILOSOPHY}
 
 Compression tools (refs are SURFACE SEQS, not ids):
-- compress: replace a seq range with your dense self-contained summary. compress({ content: [{ startSeq, endSeq, summary }] }). Edges are auto-balanced to tool-call/result boundaries; a trailing #callId fragment in a seq is ignored. Ranges must be on the current surface \u2014 stale seqs fail with guidance.
+- compress: replace one or more seq ranges, each with your own dense summary. Single range: compress({ content: [{ startSeq, endSeq, summary }] }). Batch multiple unrelated segments in one call (each entry becomes its own block): compress({ content: [{ startSeq: 1, endSeq: 5, summary: '...' }, { startSeq: 12, endSeq: 18, summary: '...' }] }). Keep ranges disjoint \u2014 overlapping entries in one batch are skipped. Edges are auto-balanced to tool-call/result boundaries; a trailing #callId fragment in a seq is ignored. Ranges must be on the current surface \u2014 stale seqs fail with guidance.
 - decompress: recover a compressed block's original content, read-only. decompress({ blockId }).
 - search_context: find information inside compressed blocks BEFORE decompressing. search_context({ query }).
 - acp_status: current context usage and the live compressible-range list. Run it before compressing when in doubt.
 
+Tiered compression: each compressed block appears on the surface as one summary node. Compressing that node again DISTILLS the block (tier 2): the parent summary folds into your new summary and the original messages are freed. Distilling a tier-2 block yields tier 3. Distill when a summary itself is consumed \u2014 decompress on the tier-2 block recovers the full originals.
+
 When you write a summary, it becomes the ONLY record of that range: keep file paths, signatures, exact values, decisions, and error strings verbatim so a later reader (or you, after decompress) can continue without the original. Never reuse historical seqs \u2014 the surface moves as messages land and compress; verify with acp_status.`;
 var ACP_SYSTEM_PROMPT_ORDER = 150;
 
@@ -850,9 +1086,13 @@ export {
   AcpStateStore,
   acpCommand,
   assertNoActiveCompaction,
+  blockRefForSummarySeq,
+  blockRegistry,
   buildNudge,
+  compactionIdsOfKernelBlocks,
   index_default as default,
   eventsToCoreMessages,
+  expandShadowedSeqs,
   extractEventText,
   findOpenTurn,
   kernelConfigFor,
@@ -863,6 +1103,7 @@ export {
   resolveSurfaceRange,
   runCompactionTransaction,
   shadowedSeqsOf,
+  summarySeqOfKernelBlock,
   surfaceEventsOf
 };
 //# sourceMappingURL=index.js.map