smartcompact 0.1.6 → 0.1.8

package/README.md

@@ -14,9 +14,9 @@
 Every request re-reads the whole context, so a long context makes every step expensive. Native auto-compaction waits until the context is nearly full (close to 1M tokens in Claude Code, up to 800k in Codex if configured), and it ignores timing, so it often lands in the middle of a task. SmartCompact works with Claude Code (CLI and desktop app), [Pi](https://github.com/earendil-works/pi) and the Codex CLI:
 
 - **Compact at a good moment.** Once the context passes the **allow line** (200k tokens by default), it compacts when a turn ends, if a piece of work has been finished since the last compaction (a commit, tests passing, a task completed) and no file has been changed since.
-- **Never in the middle of work.** It only decides when a turn ends, never mid-turn, and it waits while tests or the build are failing or errors keep repeating.
+- **Never in the middle of work.** It only decides when a turn ends, never mid-turn, and it waits while tests or the build are failing or errors keep repeating. It also waits until you have been idle for 3 minutes, so a back-and-forth discussion is not cut off.
 - **No limit of its own.** If no piece of work gets finished, the agent is usually deep in one large task, which is when a large context pays off. SmartCompact leaves it alone, and the platform's native compaction applies as it would without the plugin.
-- **A progress ledger bridges the gap.** Files changed, the latest commit and test result, and decisions the agent recorded are handed back to the model after compaction.
+- **A progress ledger bridges the gap.** Files changed, the latest commit and test result, the user requirements and decisions the agent recorded, and the agent's last reply are handed back to the model after compaction.
 - **No pointless compactions.** It skips compaction when it would not free enough space.
 
 ## Results
@@ -68,21 +68,22 @@ Codex hooks cannot postpone a compaction in the middle of a turn, so SmartCompac
 |---|---|---|
 | Allow line | 200000 | Above it, compact when a turn ends once a piece of work has been finished |
 | Minimum freed | 60000 | Skip compaction if it is expected to free less than this |
+| Idle wait | 180 | After deciding to compact, wait until you have been idle this many seconds; a new message or command cancels it |
 
-- Claude Code: the plugin options `allowLineTokens` and `minFreedTokens`; leave them empty for the defaults.
-- Pi: the flags `--smartcompact-allow-line` and `--smartcompact-min-freed`.
-- Codex: the environment variables `SMARTCOMPACT_ALLOW_LINE` and `SMARTCOMPACT_MIN_FREED`.
+- Claude Code: the plugin options `allowLineTokens`, `minFreedTokens` and `compactIdleSeconds`; leave them empty for the defaults.
+- Pi: the flags `--smartcompact-allow-line`, `--smartcompact-min-freed` and `--smartcompact-idle-seconds`.
+- Codex: the environment variables `SMARTCOMPACT_ALLOW_LINE`, `SMARTCOMPACT_MIN_FREED` and `SMARTCOMPACT_IDLE_SECONDS`.
 
 ## Seeing what it did
 
-- Claude Code and Pi: `/smartcompact` (or `/smartcompact report`) shows the allow line, the native compaction point, the finished-work signals it saw and a cost estimate; `/smartcompact pause` and `resume` turn it off and on for the session. The model can also call a `checkpoint` tool to record decisions, which come back with the ledger after compaction.
+- Claude Code and Pi: `/smartcompact` (or `/smartcompact report`) shows the allow line, the native compaction point, the finished-work signals it saw and a cost estimate; `/smartcompact pause` and `resume` turn it off and on for the session. The model can also call a `checkpoint` tool to record the user's requirements and decisions, which come back with the ledger after compaction.
 - Codex: `node ~/.codex/plugins/cache/smartcompact/smartcompact/<version>/adapters/codex/report.ts <session ID>` (Node.js 22.18+); records are kept in `~/.codex/smartcompact/`.
 
 ## FAQ
 
 **How does it know a piece of work is finished?** From the commands the agent runs. Any finished piece of work since the last compaction counts, not only one in the current turn: the end of a turn is already a pause, so waiting for the next commit would mostly just cost more. Once files are changed again after it, the next piece of work has started, and SmartCompact waits for that one to finish. A commit counts if `git commit` actually ran and the tool call did not fail. A test command piped into something else (`| tail`) without `pipefail` does not count, since its exit code cannot be trusted.
 
-**Will the model forget things after compaction?** Sometimes, for details mentioned in passing. The ledger only records files, commits, tests and decisions the model chose to record. Details the user mentions in passing are kept by asking the compaction summary to keep every specific fact the user stated. On Pi this clearly reduced losses, but it is not a guarantee.
+**Will the model forget things after compaction?** Sometimes, for details mentioned in passing. The ledger only records files, commits, tests and the requirements and decisions the model chose to record; user requirements have their own section, so later notes do not push them out, and only the oldest are dropped once there are more than 30. Details the user mentions in passing are kept by asking the compaction summary to keep every specific fact the user stated. On Pi this clearly reduced losses, but it is not a guarantee.
 
 **Does it change Claude Code's own settings?** No. Native auto-compaction stays where it is (close to 1M). Versions up to 0.1.2 moved it to about 260k by setting `CLAUDE_CODE_AUTO_COMPACT_WINDOW` in the session (which child processes inherited) and also compacted there without a finished piece of work. 0.1.3 removed both: a long task is no longer cut off at a fixed size. A session opened on 0.1.2 or earlier keeps the old setting until you start a new one.
 

package/README.zh-CN.md

@@ -14,9 +14,9 @@
 agent 每发一次请求，都要把整段上下文重新读一遍，上下文越长，每一步越贵。原生的自动压缩要等到快满了才触发（Claude Code 接近 100 万，Codex 可以配到 80 万），而且不看时机，常常发生在一件事做到一半的时候。SmartCompact 支持 Claude Code（终端和桌面 App）、[Pi](https://github.com/earendil-works/pi) 和 Codex 命令行：
 
 - **挑对时机压缩。** 上下文超过**允许压缩线**（默认 20 万）以后，只要上次压缩以来做完过一件事（一次提交、测试通过、任务完成），之后又没开始改文件，就在这一轮结束时压缩。
-- **不在做到一半时压缩。** 只在一轮结束时判断，从不在一轮中间主动压缩；测试失败、构建失败或连续报错时先等着。
+- **不在做到一半时压缩。** 只在一轮结束时判断，从不在一轮中间主动压缩；测试失败、构建失败或连续报错时先等着。还要等你空闲 3 分钟没发消息才压，来回讨论时不会被打断。
 - **不设自己的上限。** 一直没做完一件事，多半是在干一件大活，这时正需要大上下文。插件不去打断，压缩按平台原生规则来，和没装插件时一样。
-- **用进度笔记接上。** 改过的文件、最近的提交和测试结果、记下的决定，压缩后补回给模型。
+- **用进度笔记接上。** 改过的文件、最近的提交和测试结果、记下的用户要求和决定，以及模型最后一条回复，压缩后补回给模型。
 - **不做白费的压缩。** 预计腾不出足够空间时不压缩，避免刚压缩完又压缩。
 
 ## 实验结果
@@ -68,21 +68,22 @@ Codex 的 hook 不能推迟一轮中间的压缩，所以插件在一轮结束
 |---|---|---|
 | 允许压缩线 | 200000 | 超过它、做完过一件事后，在一轮结束时压缩 |
 | 最少腾出空间 | 60000 | 预计腾出的空间少于它时不压缩 |
+| 空闲等待 | 180 | 决定压缩后，等你空闲这么多秒才压；期间发了消息或命令就取消 |
 
-- Claude Code：插件配置项 `allowLineTokens`、`minFreedTokens`，留空用默认值。
-- Pi：命令行开关 `--smartcompact-allow-line`、`--smartcompact-min-freed`。
-- Codex：环境变量 `SMARTCOMPACT_ALLOW_LINE`、`SMARTCOMPACT_MIN_FREED`。
+- Claude Code：插件配置项 `allowLineTokens`、`minFreedTokens`、`compactIdleSeconds`，留空用默认值。
+- Pi：命令行开关 `--smartcompact-allow-line`、`--smartcompact-min-freed`、`--smartcompact-idle-seconds`。
+- Codex：环境变量 `SMARTCOMPACT_ALLOW_LINE`、`SMARTCOMPACT_MIN_FREED`、`SMARTCOMPACT_IDLE_SECONDS`。
 
 ## 查看效果
 
-- Claude Code 和 Pi：`/smartcompact`（或 `/smartcompact report`）查看允许压缩线、原生压缩点、识别到的阶段节点和成本估算；`/smartcompact pause` / `resume` 暂停或恢复当前会话。模型还可以调用 `checkpoint` 工具记下决定，压缩后和进度笔记一起补回。
+- Claude Code 和 Pi：`/smartcompact`（或 `/smartcompact report`）查看允许压缩线、原生压缩点、识别到的阶段节点和成本估算；`/smartcompact pause` / `resume` 暂停或恢复当前会话。模型还可以调用 `checkpoint` 工具记下用户的要求和决定，压缩后和进度笔记一起补回。
 - Codex：`node ~/.codex/plugins/cache/smartcompact/smartcompact/<版本>/adapters/codex/report.ts <会话 ID>`（Node.js 22.18 及以上），记录在 `~/.codex/smartcompact/`。
 
 ## 常见问题
 
 **怎么判断"做完一件事"？** 靠识别 agent 执行的命令。看的是上次压缩以来有没有做完过一件事，不要求正好在这一轮：一轮结束本身就是停顿点，非要等下一次提交，多半只是多花钱。但做完之后又开始改文件，就算在做下一件事，要等它做完。提交只要真的执行了 `git commit` 且工具调用没报错就算；测试命令接了管道（`| tail`）又没开 `pipefail` 时退出码不可信，不算测试结果。
 
-**压缩后模型会不会忘事？** 随口提到的细节有时会丢。进度笔记只记文件、提交、测试和模型主动记下的决定。用户在对话里随口交代的细节，靠压缩时要求摘要原样保留用户说过的具体信息。Pi 上这样做明显减少了丢失，但不能保证不丢。
+**压缩后模型会不会忘事？** 随口提到的细节有时会丢。进度笔记只记文件、提交、测试和模型主动记下的要求和决定；用户要求单独一栏，不会因为后来记的内容多了被挤掉，超过 30 条才丢最旧的。用户在对话里随口交代的细节，靠压缩时要求摘要原样保留用户说过的具体信息。Pi 上这样做明显减少了丢失，但不能保证不丢。
 
 **会改 Claude Code 自己的设置吗？** 不会，原生自动压缩点保持原样（接近 100 万）。0.1.2 及以前的版本会在会话里设置 `CLAUDE_CODE_AUTO_COMPACT_WINDOW`，把原生压缩点挪到约 26 万（子进程也会继承），并且到了那里不等做完一件事也压缩。0.1.3 去掉了这两点：大活不会再在固定大小处被打断。升级前就开着的会话还留着旧设置，新开一个会话就没有了。
 

package/adapters/pi/index.ts

@@ -6,12 +6,23 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import { SettingsManager } from '@earendil-works/pi-coding-agent'
 import { Type } from 'typebox'
-import { decideAtTurnEnd, decideMidTurn, shouldNudge } from '../../plugin/src/core/decide.ts'
-import { applyCheckpoint, COMPACT_INSTRUCTIONS, parseCheckpoint, renderLedger } from '../../plugin/src/core/ledger.ts'
+import { decideAtTurnEnd, decideMidTurn } from '../../plugin/src/core/decide.ts'
+import {
+  applyCheckpoint,
+  CHECKPOINT_DESCRIPTION,
+  CHECKPOINT_INPUT_SCHEMA,
+  COMPACT_INSTRUCTIONS,
+  parseCheckpoint,
+  recordLastReply,
+  renderLedger,
+} from '../../plugin/src/core/ledger.ts'
 import type { Lines } from '../../plugin/src/core/lines.ts'
 import { resolveParams } from '../../plugin/src/core/params.ts'
+import { planCompaction, staleCompaction } from '../../plugin/src/core/pending.ts'
+import { promptReminder } from '../../plugin/src/core/reminder.ts'
 import { countDecisions, renderReport } from '../../plugin/src/core/report.ts'
 import {
+  checkpointLog,
   cycleReads,
   type DecisionLogEntry,
   expectedAfterTokens,
@@ -30,25 +41,31 @@ import { recognizePi } from './recognize.ts'
 const STATE_ENTRY = 'smartcompact-state'
 const LOG_ENTRY = 'smartcompact-log'
 const LEDGER_MESSAGE = 'smartcompact-ledger'
-const NUDGE_MESSAGE = 'smartcompact-nudge'
+const REMINDER_MESSAGE = 'smartcompact-reminder'
 const CHECKPOINT_TOOL = 'smartcompact_checkpoint'
 /** pi 内置的默认 reserveTokens，即不配置时原生压缩点离满窗的距离 */
 const PI_DEFAULT_RESERVE = 16_384
 /** 压缩后除了保留的最近内容，还有系统提示、工具和摘要，粗估这么多 */
 const PI_AFTER_OVERHEAD = 10_000
 
-const nudgeText = (tokens: number): string =>
-  `SmartCompact: the context is at about ${Math.round(tokens / 1000)}k tokens and will be compacted at the next finished piece of work. ` +
-  `If decisions or progress are not yet recorded, call ${CHECKPOINT_TOOL} briefly. If the user is waiting for an answer, answer first.`
+const field = CHECKPOINT_INPUT_SCHEMA.properties
+
+/** 没设置时用默认值；0 也是合法的设置。 */
+const flagNumber = (value: unknown): number | undefined => (typeof value === 'string' && value.trim() ? Number(value) : undefined)
 
 export default function smartCompact(pi: ExtensionAPI) {
   pi.registerFlag('smartcompact-allow-line', { description: 'SmartCompact 允许压缩线（token）', type: 'string' })
   pi.registerFlag('smartcompact-min-freed', { description: 'SmartCompact 最少腾出空间（token）', type: 'string' })
+  pi.registerFlag('smartcompact-idle-seconds', { description: 'SmartCompact 决定压缩后等用户空闲多少秒', type: 'string' })
 
   let state: SessionState = INITIAL_SESSION_STATE
   let saved = ''
   /** 插件自己发起的压缩在 pi 里同样是 manual，据此和用户的 /compact 区分。 */
   let ours = false
+  /** 这次运行给用户的最后一段文字；运行正常结束时记进笔记，压缩后原样带回。 */
+  let lastReply = ''
+  /** 一轮结束后等用户空闲再执行的压缩；用户发新消息、换会话或退出时作废，到点时再核对会话现状。 */
+  let idleCompaction: ReturnType<typeof setTimeout> | undefined
   /** 当前模型的 reserveTokens 和 keepRecentTokens；读设置文件有开销，按会话和模型缓存。 */
   let compaction: { reserve: number; keepRecent: number } | undefined
 
@@ -64,8 +81,9 @@ export default function smartCompact(pi: ExtensionAPI) {
   // pi 的基础占用比 Claude 小得多：压缩后的大小按 pi 保留的最近内容估算，而不是用 core 的默认值。
   const params = (ctx: ExtensionContext) =>
     resolveParams({
-      allowLineTokens: Number(pi.getFlag('smartcompact-allow-line')) || undefined,
-      minFreedTokens: Number(pi.getFlag('smartcompact-min-freed')) || undefined,
+      allowLineTokens: flagNumber(pi.getFlag('smartcompact-allow-line')),
+      minFreedTokens: flagNumber(pi.getFlag('smartcompact-min-freed')),
+      compactIdleSeconds: flagNumber(pi.getFlag('smartcompact-idle-seconds')),
       defaultAfterTokens: compactionSettings(ctx).keepRecent + PI_AFTER_OVERHEAD,
     })
 
@@ -97,6 +115,14 @@ export default function smartCompact(pi: ExtensionAPI) {
 
   const log = (entry: Omit<DecisionLogEntry, 'at' | 'session'>) => pi.appendEntry(LOG_ENTRY, { at: new Date().toISOString(), ...entry })
 
+  /** 撤销还在等用户空闲的压缩；返回是否真的撤销了。 */
+  const cancelIdleCompaction = (): boolean => {
+    if (!idleCompaction) return false
+    clearTimeout(idleCompaction)
+    idleCompaction = undefined
+    return true
+  }
+
   const report = (ctx: ExtensionContext): string => {
     const current = lines(ctx)
     if (!current) return 'SmartCompact 尚未读到上下文用量。'
@@ -116,6 +142,7 @@ export default function smartCompact(pi: ExtensionAPI) {
     saved = JSON.stringify(state)
     ours = false
     compaction = undefined
+    cancelIdleCompaction()
   })
 
   pi.on('model_select', async () => {
@@ -125,24 +152,22 @@ export default function smartCompact(pi: ExtensionAPI) {
   pi.registerTool({
     name: CHECKPOINT_TOOL,
     label: 'Checkpoint',
-    description:
-      'Record a short progress note that survives context compaction: the goal, decisions made, where the work stands, and what is next. ' +
-      'Call it after finishing a piece of work (set milestone: true) or after an important decision. Keep it brief; do not call it for trivial steps.',
+    description: CHECKPOINT_DESCRIPTION,
     parameters: Type.Object({
-      goal: Type.Optional(Type.String({ description: 'The overall goal of the current work.' })),
-      decisions: Type.Optional(Type.Array(Type.String(), { description: 'Decisions made since the last checkpoint.' })),
-      next: Type.Optional(Type.String({ description: 'What to do next.' })),
-      current: Type.Optional(Type.String({ description: 'Where the work stands right now.' })),
-      milestone: Type.Optional(Type.Boolean({ description: 'True when a piece of work was just finished.' })),
+      goal: Type.Optional(Type.String({ description: field.goal.description })),
+      requirements: Type.Optional(Type.Array(Type.String(), { description: field.requirements.description })),
+      decisions: Type.Optional(Type.Array(Type.String(), { description: field.decisions.description })),
+      next: Type.Optional(Type.String({ description: field.next.description })),
+      current: Type.Optional(Type.String({ description: field.current.description })),
+      milestone: Type.Optional(Type.Boolean({ description: field.milestone.description })),
     }),
     async execute(_toolCallId, input) {
       const parsed = parseCheckpoint(input)
       if (!parsed.ok) return { content: [{ type: 'text', text: `Not recorded: ${parsed.error}` }], details: {} }
-      state = withSignals({ ...state, ledger: applyCheckpoint(state.ledger, parsed.value), notesUpdated: true }, [
-        { kind: 'checkpoint', milestone: parsed.value.milestone === true },
-      ])
+      const ledger = applyCheckpoint(state.ledger, parsed.value)
+      state = withSignals({ ...state, ledger, notesUpdated: true }, [{ kind: 'checkpoint', milestone: parsed.value.milestone === true }])
       persist()
-      log({ event: 'checkpoint', action: parsed.value.milestone ? 'milestone' : 'note' })
+      log(checkpointLog(parsed.value, ledger))
       return { content: [{ type: 'text', text: 'Recorded. Continue with the work.' }], details: {} }
     },
   })
@@ -171,17 +196,34 @@ export default function smartCompact(pi: ExtensionAPI) {
   })
 
   pi.on('before_agent_start', async (_event, ctx) => {
+    // 等待期间来了新消息，说明还在进行，这次不压，等下一次停顿。
+    if (cancelIdleCompaction()) log({ event: 'compacted', action: 'cancelled', reason: 'new-turn', trigger: 'plugin' })
     const current = lines(ctx)
-    const tokens = tokensOf(ctx)
-    if (!current || !shouldNudge({ tokens, lines: current, notesUpdated: state.notesUpdated, nudged: state.nudged, paused: state.paused }, params(ctx))) return
-    state = { ...state, nudged: true }
-    return { message: { customType: NUDGE_MESSAGE, content: nudgeText(tokens ?? 0), display: false } }
+    const reminder = current && promptReminder(state, tokensOf(ctx), current, params(ctx), CHECKPOINT_TOOL)
+    if (!reminder) return
+    state = reminder.state
+    persist()
+    log(reminder.log)
+    return { message: { customType: REMINDER_MESSAGE, content: reminder.text, display: false } }
+  })
+
+  pi.on('agent_end', async event => {
+    const reply = event.messages.findLast(message => message.role === 'assistant')
+    lastReply =
+      reply && 'content' in reply && Array.isArray(reply.content)
+        ? reply.content.flatMap(block => (block.type === 'text' ? [block.text] : [])).join('\n')
+        : ''
   })
 
-  // agent_settled：pi 不会再自动继续，此时压缩不会打断工作。
-  pi.on('agent_settled', async (_event, ctx) => {
+  // agent_settled：pi 不会再自动继续，此时压缩不会打断工作。被用户打断的运行不压缩，也不记回复。
+  pi.on('agent_settled', async (event, ctx) => {
+    if (event.aborted) return
+    state = { ...state, ledger: recordLastReply(state.ledger, lastReply) }
     const current = lines(ctx)
-    if (!current) return
+    if (!current) {
+      persist()
+      return
+    }
     const tokens = sample(ctx, current)
     persist()
     const decision = decideAtTurnEnd(
@@ -190,15 +232,35 @@ export default function smartCompact(pi: ExtensionAPI) {
     )
     const sinceMilestoneTokens = decision.action === 'compact' ? growthSinceMilestone(state.work, tokens) : undefined
     if (decision.action !== 'none') log({ event: 'turn-end', action: decision.action, reason: decision.reason, tokens, sinceMilestoneTokens })
-    if (decision.action !== 'compact' || !ctx.isIdle() || ctx.hasPendingMessages()) return
-    ours = true
-    ctx.compact({
-      customInstructions: COMPACT_INSTRUCTIONS,
-      onError: error => {
-        ours = false
-        log({ event: 'compacted', action: 'failed', trigger: 'plugin', detail: error.message })
-      },
-    })
+    if (decision.action !== 'compact') return
+    // 等用户空闲一会儿再压：还在讨论时不打断，用户也不用等压缩完才得到回复。
+    cancelIdleCompaction()
+    const pending = planCompaction(ctx.sessionManager.getSessionId(), state, Date.now(), params(ctx))
+    idleCompaction = setTimeout(() => {
+      idleCompaction = undefined
+      // 新的运行会先经过 before_agent_start 撤销；到点还不空闲的是 pi 自己在重试、恢复或处理排队的消息，这次不压，下一次停顿时重新判断。
+      // 等待期间用户可能自己 /compact、原生压缩过或暂停了插件，这些也都不经过 before_agent_start。
+      const stale = !ctx.isIdle() || ctx.hasPendingMessages() ? 'busy' : staleCompaction(pending, state, ctx.sessionManager.getSessionId())
+      if (stale) {
+        log({ event: 'compacted', action: 'skipped', reason: stale, trigger: 'plugin' })
+        return
+      }
+      ours = true
+      ctx.compact({
+        customInstructions: COMPACT_INSTRUCTIONS,
+        onError: error => {
+          ours = false
+          log({ event: 'compacted', action: 'failed', trigger: 'plugin', detail: error.message })
+        },
+      })
+    }, pending.notBefore - Date.now())
+    // 等待中的压缩不拦着 pi 退出（比如 -p 模式跑完就该结束）。
+    idleCompaction.unref?.()
+  })
+
+  // 计时器拿着旧会话的 ctx，换会话或退出时必须清掉。
+  pi.on('session_shutdown', async () => {
+    cancelIdleCompaction()
   })
 
   pi.on('session_before_compact', async (event, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smartcompact",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "type": "module",
   "description": "Compact long agent sessions earlier, at a finished piece of work, to cut cost without losing results (Claude Code, pi, Codex)",
   "license": "MIT",

package/plugin/README.md

@@ -1,6 +1,6 @@
 # SmartCompact for Claude Code
 
-SmartCompact compacts long Claude Code sessions earlier, at a pause after a piece of work is finished, so every later request re-reads a smaller context. Once the context passes 200k tokens, it compacts at the end of a turn if a commit, passing tests or a completed task happened since the last compaction. It waits while tests or the build are failing or errors repeat. It sets no limit of its own: if no piece of work gets finished, the session keeps its context and Claude Code's native auto-compaction applies as usual. A short progress ledger (files changed, latest commit and test result, recorded decisions) is handed back to the model after compaction.
+SmartCompact compacts long Claude Code sessions earlier, at a pause after a piece of work is finished, so every later request re-reads a smaller context. Once the context passes 200k tokens, it decides at the end of a turn to compact if a commit, passing tests or a completed task happened since the last compaction, then waits until you have been idle for 3 minutes so a discussion is not cut off; a new turn cancels it. It waits while tests or the build are failing or errors repeat. It sets no limit of its own: if no piece of work gets finished, the session keeps its context and Claude Code's native auto-compaction applies as usual. A short progress ledger (files changed, latest commit and test result, recorded user requirements and decisions) and the model's last reply are handed back after compaction.
 
 In a 60-task A/B run on Claude Haiku it cut estimated cost by 44% with no loss in hidden acceptance tests; the model missed 6 of 180 recall questions about details mentioned in passing long before. Method and data: [docs/EVALUATION.md](https://github.com/coffeecoproject/SmartCompact/blob/main/docs/EVALUATION.md).
 
@@ -8,8 +8,8 @@ In a 60-task A/B run on Claude Haiku it cut estimated cost by 44% with no loss i
 
 Everything runs locally inside Claude Code. **The plugin makes no network requests, starts no processes, and does not read or change environment variables or Claude Code's settings.**
 
-- **Reads**: the session's token usage; the tool name, input and success of each tool call, to recognize work: file paths from Edit/Write, Bash command text (to recognize `git commit` and test or build commands, and whether they failed), the `[branch hash] message` line from a commit's output, TodoWrite items and task events. It reads no credentials or tokens and no file contents, and nothing it reads leaves the machine.
-- **Writes**: only the plugin's own storage (`$.store`): per-session state and the progress ledger (file paths, the latest commit line, the latest test command and result, in-progress task names, notes recorded with the `checkpoint` tool) and a short decision log. Old session records are pruned automatically.
+- **Reads**: the session's token usage; the tool name, input and success of each tool call, to recognize work: file paths from Edit/Write, file paths from Read (to count files re-read after a compaction), Bash command text (to recognize `git commit` and test or build commands, and whether they failed), the `[branch hash] message` line from a commit's output, TodoWrite items and task events, and the text of the model's final reply each turn (to hand it back after a compaction). It reads no credentials or tokens and no file contents, and nothing it reads leaves the machine.
+- **Writes**: only the plugin's own storage (`$.store`): per-session state and the progress ledger (file paths, the latest commit line, the latest test command and result, in-progress task names, notes recorded with the `checkpoint` tool, the model's latest reply up to 3,000 characters), the paths of files read before and since the last compaction, and a short decision log. Old session records are pruned automatically.
 
 ### What each hook does
 
@@ -19,15 +19,16 @@ All hooks live in one module, `hooks/register.ts`.
 - **`/smartcompact` command**: answers only its own command (`report`, `pause`, `resume`).
 - **Tool calls**: answers calls to its own `checkpoint` tool by recording the note. For every other tool it only looks at the result to recognize commits, tests, builds and edited files, and passes the result through unchanged.
 - **Task created / completed**: keeps the list of in-progress task names for the ledger.
-- **Prompt submit**: adds context to the turn, never changes the user's message. After a compaction it adds the progress ledger; once per cycle, when the context nears the allow line, it adds a one-line reminder to record progress with `checkpoint`.
-- **Turn complete**: decides whether to compact. When it should, it compacts the session. Where a session cannot compact directly (headless sessions such as the desktop app), it runs the `/compact` command itself with SmartCompact's compaction instructions; it runs no other commands.
+- **Prompt submit**: adds context to the turn, never changes the user's message. After a compaction it adds the progress ledger; once per cycle, when the context nears the allow line, it adds a one-line reminder to record progress with `checkpoint`; past the allow line, while it waits for a finished piece of work, it reminds the model to mark each finished step with `checkpoint`, again every further 100k tokens.
+- **Turn start**: cancels a compaction still waiting for the user to go idle; any new turn counts, including one started by a slash command.
+- **Turn complete**: keeps the model's final reply and decides whether to compact. When it should, it waits until the user has been idle for 3 minutes (a new turn cancels it) and then compacts the session; the reply is handed back with the ledger. Where a session cannot compact directly (headless sessions such as the desktop app), it runs the `/compact` command itself with SmartCompact's compaction instructions; it runs no other commands.
 - **Compaction**: never blocks or changes a compaction itself. After any compaction of the main session it appends the progress ledger to the compacted context. Subagent compactions are left alone.
 
 ## Use
 
 - Install: `/plugin marketplace add coffeecoproject/SmartCompact`, then `/plugin install smartcompact@smartcompact`. It takes effect in new sessions.
 - `/smartcompact` (or `/smartcompact report`) shows the lines, recognized milestones and a cost estimate; `/smartcompact pause` and `/smartcompact resume` turn it off and on for the session.
-- Settings (optional, empty means default): `allowLineTokens` (200000), `minFreedTokens` (60000).
+- Settings (optional, empty means default): `allowLineTokens` (200000), `minFreedTokens` (60000), `compactIdleSeconds` (180).
 - Remove: `/plugin uninstall smartcompact@smartcompact`.
 
 Full documentation, Pi and Codex versions: https://github.com/coffeecoproject/SmartCompact

package/plugin/src/core/decide.ts

@@ -1,4 +1,5 @@
 // 两个决策函数：一轮结束时要不要主动压缩；一轮进行中原生自动压缩来问时放不放行（只有原生压缩点能提前的平台用到，目前是 pi）。
+// 另有两个判断供 reminder.ts 用：要不要提醒记笔记、要不要提醒标完成。
 // 读不到用量时一律不干预，按原生行为来。
 
 import type { Lines } from './lines.ts'
@@ -52,6 +53,18 @@ export function shouldNudge(
   return input.tokens >= input.lines.allow * params.nudgeAtShare
 }
 
+/** 超过允许线、因为还没做完一件事在等时，提醒模型做完一步就标完成；上下文每涨 remindEveryTokens 才再提醒一次。 */
+export function shouldRemindMilestone(
+  decision: TurnEndDecision,
+  tokens: number,
+  remindedAtTokens: number | undefined,
+  params: Params,
+): boolean {
+  if (decision.action !== 'wait') return false
+  if (decision.reason !== 'changed-since-milestone' && decision.reason !== 'waiting-for-milestone') return false
+  return remindedAtTokens === undefined || tokens - remindedAtTokens >= params.remindEveryTokens
+}
+
 export function decideMidTurn(input: DecisionInput, params: Params): MidTurnDecision {
   const { tokens, lines, work } = input
   if (input.paused) return { action: 'allow', reason: 'paused' }

package/plugin/src/core/ledger.ts

@@ -7,10 +7,14 @@ export type LedgerFacts = {
   lastBuild?: { command: string; passed: boolean }
   lastCommit?: { summary: string }
   tasksInProgress: string[]
+  /** 模型最近一轮给用户的回复，压缩后原样带回；用户的下一句话常常是在回答它 */
+  lastReply?: string
 }
 
 export type LedgerNotes = {
   goal?: string
+  /** 用户交代的要求和具体信息；单独存、只追加，再记一次的挪到最后，超过上限才丢最旧的。旧版本存下的笔记没有这一项 */
+  requirements?: string[]
   decisions: string[]
   next?: string
   current?: string
@@ -37,8 +41,13 @@ export const COMPACT_INSTRUCTIONS =
   'A SmartCompact progress ledger is attached after the summary; do not restate it.'
 
 const MAX_FILES = 30
-const MAX_DECISIONS = 20
+const MAX_DECISIONS = 30
 const MAX_FIELD_CHARS = 1_000
+/** 用户要求只追加，超过这么多条才丢最旧的 */
+const MAX_REQUIREMENTS = 30
+/** 带回的最后一条回复最多这么长，单独计算，不占笔记的长度；超长时留结尾，提问和待确认的提议通常在最后 */
+const MAX_REPLY_CHARS = 3_000
+const REPLY_CUT = '…(earlier part omitted)\n'
 
 export function recordFileChanged(ledger: Ledger, path: string): Ledger {
   const files = [...ledger.facts.filesChanged.filter(file => file !== path), path].slice(-MAX_FILES)
@@ -57,12 +66,20 @@ export function recordCommit(ledger: Ledger, summary: string): Ledger {
   return { ...ledger, facts: { ...ledger.facts, lastCommit: { summary } } }
 }
 
+export function recordLastReply(ledger: Ledger, reply: string): Ledger {
+  const text = reply.trim()
+  if (!text) return ledger
+  const kept = text.length <= MAX_REPLY_CHARS ? text : `${REPLY_CUT}${text.slice(-(MAX_REPLY_CHARS - REPLY_CUT.length))}`
+  return { ...ledger, facts: { ...ledger.facts, lastReply: kept } }
+}
+
 export function recordTasksInProgress(ledger: Ledger, tasks: readonly string[]): Ledger {
   return { ...ledger, facts: { ...ledger.facts, tasksInProgress: [...tasks] } }
 }
 
 export type CheckpointInput = {
   goal?: string
+  requirements?: string[]
   decisions?: string[]
   next?: string
   current?: string
@@ -70,11 +87,28 @@ export type CheckpointInput = {
   milestone?: boolean
 }
 
+/** checkpoint 工具的说明，适配层注册工具时使用。 */
+export const CHECKPOINT_DESCRIPTION =
+  'Record a short progress note that survives context compaction: the goal, requirements and specific facts the user stated, decisions made, ' +
+  'where the work stands, and what is next. ' +
+  'Call it after finishing a piece of work (set milestone: true), after an important decision, or when the user states a requirement or a specific fact. ' +
+  'Keep it brief; do not call it for trivial steps.'
+
 /** checkpoint 工具的输入 schema，适配层注册工具时使用。 */
 export const CHECKPOINT_INPUT_SCHEMA = {
   type: 'object',
   properties: {
     goal: { type: 'string', description: 'The overall goal of the current work.' },
+    requirements: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'Facts and requirements the user stated for this session: names of people and customers, dates, ticket or ID numbers, constraints, ' +
+        'things to avoid. One per item, with the context needed to use it later (such as which task it belongs to), in the user\'s words ' +
+        'where possible; record them when the user states them. Not for progress, task status or commit IDs; those go in current and decisions. ' +
+        'Items are added to the list and only the oldest are dropped when it gets long. If the user changes one, record the new version; ' +
+        'the later one wins. Long-term preferences belong in your own memory, not here.',
+    },
     decisions: { type: 'array', items: { type: 'string' }, description: 'Decisions made since the last checkpoint.' },
     next: { type: 'string', description: 'What to do next.' },
     current: { type: 'string', description: 'Where the work stands right now.' },
@@ -98,29 +132,32 @@ export function parseCheckpoint(raw: unknown): CheckpointParse {
     if (!text(field)) return { ok: false, error: `${key} must be a non-empty string` }
     value[key] = clip(field)
   }
-  const { decisions, milestone } = input
-  if (decisions !== undefined) {
-    if (!Array.isArray(decisions) || !decisions.every(text)) {
-      return { ok: false, error: 'decisions must be an array of non-empty strings' }
-    }
-    value.decisions = decisions.map(clip)
+  for (const key of ['requirements', 'decisions'] as const) {
+    const field = input[key]
+    if (field === undefined) continue
+    if (!Array.isArray(field) || !field.every(text)) return { ok: false, error: `${key} must be an array of non-empty strings` }
+    value[key] = field.map(clip)
   }
-  if (milestone !== undefined) {
-    if (typeof milestone !== 'boolean') return { ok: false, error: 'milestone must be a boolean' }
-    value.milestone = milestone
+  if (input.milestone !== undefined) {
+    if (typeof input.milestone !== 'boolean') return { ok: false, error: 'milestone must be a boolean' }
+    value.milestone = input.milestone
   }
-  if (!value.goal && !value.next && !value.current && !value.decisions?.length) {
-    return { ok: false, error: 'record at least one of goal, decisions, next, current' }
+  if (!value.goal && !value.next && !value.current && !value.decisions?.length && !value.requirements?.length) {
+    return { ok: false, error: 'record at least one of goal, requirements, decisions, next, current' }
   }
   return { ok: true, value }
 }
 
 export function applyCheckpoint(ledger: Ledger, input: CheckpointInput): Ledger {
   const decisions = [...ledger.notes.decisions, ...(input.decisions ?? [])]
+  // 再记一次的要求挪到最后：用户刚重申过，不该因为最早写进去而先被丢掉。
+  const added = input.requirements ?? []
+  const requirements = [...(ledger.notes.requirements ?? []).filter(requirement => !added.includes(requirement)), ...added]
   return {
     ...ledger,
     notes: {
       goal: input.goal ?? ledger.notes.goal,
+      requirements: [...new Set(requirements)].slice(-MAX_REQUIREMENTS),
       next: input.next ?? ledger.notes.next,
       current: input.current ?? ledger.notes.current,
       decisions: [...new Set(decisions)].slice(-MAX_DECISIONS),
@@ -128,20 +165,31 @@ export function applyCheckpoint(ledger: Ledger, input: CheckpointInput): Ledger
   }
 }
 
-/** 排版成补回上下文的文本，超长时先丢最旧的决定、再丢最早改过的文件，仍超长才截断。 */
+type Kept = { requirements: readonly string[]; decisions: readonly string[]; files: readonly string[] }
+
+/**
+ * 排版成补回上下文的文本，超长时先丢最旧的决定、再丢最早改过的文件、最后才丢最旧的用户要求，仍超长才截断。
+ * 最后一条回复放在末尾，不算在 maxChars 里。
+ */
 export function renderLedger(ledger: Ledger, maxChars: number): string {
-  let decisions = ledger.notes.decisions
-  let files = ledger.facts.filesChanged
-  let rendered = layoutLedger(ledger, decisions, files)
-  while (rendered.length > maxChars && (decisions.length || files.length)) {
-    if (decisions.length) decisions = decisions.slice(1)
-    else files = files.slice(1)
-    rendered = layoutLedger(ledger, decisions, files)
+  const reply = ledger.facts.lastReply
+  const notes = renderNotes(ledger, maxChars)
+  return reply ? `${notes}\n\n## Your last reply before compaction\nVerbatim; the user's next message may answer it.\n\n${reply}` : notes
+}
+
+function renderNotes(ledger: Ledger, maxChars: number): string {
+  let kept: Kept = { requirements: ledger.notes.requirements ?? [], decisions: ledger.notes.decisions, files: ledger.facts.filesChanged }
+  let rendered = layoutLedger(ledger, kept)
+  while (rendered.length > maxChars) {
+    const key = (['decisions', 'files', 'requirements'] as const).find(k => kept[k].length)
+    if (!key) break
+    kept = { ...kept, [key]: kept[key].slice(1) }
+    rendered = layoutLedger(ledger, kept)
   }
   return rendered.length <= maxChars ? rendered : `${rendered.slice(0, maxChars - 20)}\n…(truncated)`
 }
 
-function layoutLedger({ facts, notes }: Ledger, decisions: readonly string[], files: readonly string[]): string {
+function layoutLedger({ facts, notes }: Ledger, { requirements, decisions, files }: Kept): string {
   const lines = [
     LEDGER_MARKER,
     'Generated by the SmartCompact plugin to keep continuity across compaction. It is not a message from the user.',
@@ -152,6 +200,10 @@ function layoutLedger({ facts, notes }: Ledger, decisions: readonly string[], fi
   }
   const omitted = (dropped: number, what: string) => (dropped ? `- …(${dropped} earlier ${what} omitted)` : undefined)
   section('Goal', [notes.goal])
+  section('User requirements', [
+    omitted((notes.requirements?.length ?? 0) - requirements.length, 'requirements'),
+    ...requirements.map(requirement => `- ${requirement}`),
+  ])
   section('Current state', [notes.current])
   section('Next', [notes.next])
   section('Latest results', [

package/plugin/src/core/params.ts

@@ -17,6 +17,10 @@ export type Params = {
   ledgerMaxChars: number
   /** 用量到 L × 这个比例、笔记又没更新时，提醒模型记一下 */
   nudgeAtShare: number
+  /** 超过 L、在等做完一件事时，上下文每涨这么多提醒一次模型做完一步就标完成 */
+  remindEveryTokens: number
+  /** 一轮结束、决定压缩后，用户空闲这么多秒没发消息才压缩；期间发了消息就取消，等下一次停顿 */
+  compactIdleSeconds: number
 }
 
 export const DEFAULT_PARAMS: Params = Object.freeze({
@@ -28,6 +32,8 @@ export const DEFAULT_PARAMS: Params = Object.freeze({
   errorStreakLimit: 3,
   ledgerMaxChars: 6_000,
   nudgeAtShare: 0.85,
+  remindEveryTokens: 100_000,
+  compactIdleSeconds: 180,
 })
 
 const MINIMUMS: Record<keyof Params, number> = {
@@ -39,6 +45,8 @@ const MINIMUMS: Record<keyof Params, number> = {
   errorStreakLimit: 1,
   ledgerMaxChars: 200,
   nudgeAtShare: 0,
+  remindEveryTokens: 1,
+  compactIdleSeconds: 0,
 }
 
 /** 用户覆盖的值逐项校验，不合法的项沿用默认值。 */

package/plugin/src/core/pending.ts

@@ -0,0 +1,30 @@
+// 一轮结束时决定压缩后，等用户空闲一会儿再执行。等待期间会话可能已经变了，到点时用这里的核对决定还压不压；
+// 三个平台都用它，不再逐个事件去撤销。用户发新消息时撤销是另一回事（还在讨论），由适配层在收到消息时处理。
+
+import type { Params } from './params.ts'
+import type { SessionState } from './state.ts'
+
+export type PendingCompaction = {
+  /** 决定压缩时的会话 ID */
+  session: string
+  /** 决定压缩时已经压缩过的次数；到点时变了，说明期间已经压缩过 */
+  compactions: number
+  /** 不早于这个时间（毫秒）执行 */
+  notBefore: number
+}
+
+export type StaleReason = 'session-changed' | 'compacted-meanwhile' | 'paused'
+
+export const planCompaction = (session: string, state: SessionState, now: number, params: Params): PendingCompaction => ({
+  session,
+  compactions: state.compactions,
+  notBefore: now + params.compactIdleSeconds * 1_000,
+})
+
+/** 到点时核对：换了会话（如 /clear）、期间已经压缩过（用户的 /compact 或原生压缩）、或暂停了，这次就不压。 */
+export function staleCompaction(pending: PendingCompaction, state: SessionState, session: string): StaleReason | undefined {
+  if (session !== pending.session) return 'session-changed'
+  if (state.compactions !== pending.compactions) return 'compacted-meanwhile'
+  if (state.paused) return 'paused'
+  return undefined
+}

package/plugin/src/core/reminder.ts

@@ -0,0 +1,54 @@
+// 用户发消息前要不要附一句用户看不到的提醒。两种提醒的文字、判断、状态和日志都在这里，适配层只负责注入。
+
+import { decideAtTurnEnd, shouldNudge, shouldRemindMilestone } from './decide.ts'
+import type { Lines } from './lines.ts'
+import type { Params } from './params.ts'
+import { type DecisionLogEntry, expectedAfterTokens, type SessionState } from './state.ts'
+
+/** 快到允许压缩线时提醒模型更新笔记。 */
+export const checkpointNudge = (tokens: number, tool: string): string =>
+  `SmartCompact: the context is at about ${Math.round(tokens / 1000)}k tokens and will be compacted at the next finished piece of work. ` +
+  `If decisions, user requirements or progress are not yet recorded, call ${tool} briefly; if a piece of work was just finished, set milestone: true. ` +
+  'If the user is waiting for an answer, answer first.'
+
+/** 超过允许线、在等做完一件事时，提醒模型做完一步就标完成。 */
+export const milestoneReminder = (tokens: number, tool: string): string =>
+  `SmartCompact: the context is at about ${Math.round(tokens / 1000)}k tokens and will be compacted once a piece of work is finished. ` +
+  `When you finish a step (a fix, a subtask, a passing test run), call ${tool} with milestone: true, even without a commit; ` +
+  'do not mark unfinished work as done. If the user is waiting for an answer, answer first.'
+
+export type PromptReminder = { text: string; state: SessionState; log: Omit<DecisionLogEntry, 'at' | 'session'> }
+
+/**
+ * 超过允许线、在等做完一件事时，提醒模型做完一步就标完成；否则快到允许线、笔记没更新时，提醒记笔记。
+ * 两种都算本周期提醒过，不重复提醒记笔记。不需要提醒时返回 undefined。
+ */
+export function promptReminder(
+  state: SessionState,
+  tokens: number | undefined,
+  lines: Lines,
+  params: Params,
+  tool: string,
+): PromptReminder | undefined {
+  if (tokens === undefined) return undefined
+  // 用户发下一条消息前状态没变，判断和上一轮结束时一样。
+  const waiting = decideAtTurnEnd(
+    { tokens, lines, work: state.work, expectedAfterTokens: expectedAfterTokens(state, params.defaultAfterTokens), paused: state.paused },
+    params,
+  )
+  if (shouldRemindMilestone(waiting, tokens, state.remindedAtTokens, params)) {
+    return {
+      text: milestoneReminder(tokens, tool),
+      state: { ...state, nudged: true, remindedAtTokens: tokens },
+      log: { event: 'reminder', action: 'milestone', reason: waiting.reason, tokens },
+    }
+  }
+  if (shouldNudge({ tokens, lines, notesUpdated: state.notesUpdated, nudged: state.nudged, paused: state.paused }, params)) {
+    return {
+      text: checkpointNudge(tokens, tool),
+      state: { ...state, nudged: true },
+      log: { event: 'reminder', action: 'nudge', reason: 'notes-not-updated', tokens },
+    }
+  }
+  return undefined
+}

package/plugin/src/core/report.ts

@@ -35,7 +35,7 @@ export function renderReport(input: {
     `SmartCompact${state.paused ? '（已暂停）' : ''}`,
     `- 当前用量 ${k(tokens)}；允许压缩线 ${k(lines.allow)}，原生压缩点 ${k(lines.ceiling)}`,
     `- 本会话压缩 ${state.compactions} 次；最近一次压缩后约 ${k(state.measuredAfterTokens)}`,
-    `- 本会话决策：插件压缩 ${(counts['compacted:plugin'] ?? 0) + (counts['compacted:plugin-queued'] ?? 0)}，自动压缩放行 ${counts['compacted:auto'] ?? 0}，手动压缩 ${counts['compacted:manual'] ?? 0}，轮中否决 ${counts['mid-turn:veto'] ?? 0}，轮末等待 ${counts['turn-end:wait'] ?? 0}`,
+    `- 本会话决策：插件压缩 ${(counts['compacted:plugin'] ?? 0) + (counts['compacted:plugin-queued'] ?? 0)}，自动压缩放行 ${counts['compacted:auto'] ?? 0}，手动压缩 ${counts['compacted:manual'] ?? 0}，轮中否决 ${counts['mid-turn:veto'] ?? 0}，轮末等待 ${counts['turn-end:wait'] ?? 0}，提醒记笔记 ${counts['reminder:nudge'] ?? 0}，提醒标完成 ${counts['reminder:milestone'] ?? 0}`,
     `- 信号：提交 ${seen.commit}，测试通过 ${seen['tests-passed']}，任务完成 ${seen['task-completed']}，checkpoint 完成 ${seen.checkpoint}`,
     `- 当前状态：${milestoneStatus(state.work)}${state.work.testsFailing ? '，测试失败中' : ''}${state.work.buildFailing ? '，构建失败中' : ''}`,
     ratio === undefined

package/plugin/src/core/state.ts

@@ -1,6 +1,6 @@
 // 会话状态与决策日志的数据格式。读写由适配层负责，core 只定义格式。
 
-import { EMPTY_LEDGER, type Ledger } from './ledger.ts'
+import { type CheckpointInput, EMPTY_LEDGER, type Ledger } from './ledger.ts'
 import { afterCompaction, applySignal, INITIAL_WORK_STATE, milestoneOf, type MilestoneSource, type Signal, type WorkState } from './signals.ts'
 import { EMPTY_TALLY, type Prices, recordCompaction, recordSample, type UsageTally } from './usage.ts'
 
@@ -15,8 +15,10 @@ export type SessionState = {
   paused: boolean
   /** 自上次压缩以来，模型是否通过 checkpoint 更新过笔记 */
   notesUpdated: boolean
-  /** 自上次压缩以来，是否提醒过模型更新笔记 */
+  /** 自上次压缩以来，是否提醒过模型（记笔记或标完成）；提醒过就不再提醒记笔记 */
   nudged: boolean
+  /** 本周期最近一次提醒模型标完成时的用量 */
+  remindedAtTokens?: number
   /** 各种信号出现过的次数，用于确认识别是否生效 */
   seen: SignalsSeen
   usage: UsageTally
@@ -102,6 +104,7 @@ export function withCompaction(state: SessionState, before: number, summary: num
     compactions: state.compactions + 1,
     notesUpdated: false,
     nudged: false,
+    remindedAtTokens: undefined,
     usage: attributed ? recordCompaction(state.usage, before, summary) : state.usage,
   }
 }
@@ -125,11 +128,21 @@ export function cycleReads(state: SessionState): Pick<DecisionLogEntry, 'reads'
   return state.reads ? { reads: state.reads.reads, rereads: state.reads.rereads } : {}
 }
 
+/** checkpoint 的日志：有没有标完成、用户要求有几条。 */
+export function checkpointLog(input: CheckpointInput, ledger: Ledger): Omit<DecisionLogEntry, 'at' | 'session'> {
+  const requirements = ledger.notes.requirements?.length ?? 0
+  return {
+    event: 'checkpoint',
+    action: input.milestone ? 'milestone' : 'note',
+    ...(requirements ? { requirements } : {}),
+  }
+}
+
 export type DecisionLogEntry = {
   at: string
   /** 会话 ID，报告据此只统计当前会话 */
   session?: string
-  event: 'setup' | 'turn-end' | 'mid-turn' | 'compacted' | 'checkpoint' | 'error'
+  event: 'setup' | 'turn-end' | 'mid-turn' | 'compacted' | 'checkpoint' | 'reminder' | 'error'
   action?: string
   reason?: string
   tokens?: number
@@ -140,6 +153,8 @@ export type DecisionLogEntry = {
   /** 压缩时：上次压缩以来读文件的次数，以及其中重读压缩前看过的文件的次数 */
   reads?: number
   rereads?: number
+  /** checkpoint 之后用户要求的条数 */
+  requirements?: number
   trigger?: string
   detail?: string
 }