pi-context 2.0.0-beta.0 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # Pi Context: Agentic Context Management for Pi
 
-An Agentic Context Management tool that helps AI agents proactively manage checkpoints, timeline inspection, and rewind-based context cleanup.
+An Agentic Context Management tool that helps AI agents keep long conversations focused by maintaining a clean working set: checkpoint useful anchors, inspect the active history structure, and compact noisy completed paths into state summaries.
 
 Inspired by kimi-cli d-mail, it brings lossless time travel to Pi's session tree.
 
@@ -13,9 +13,9 @@ Earlier versions used more Git-like names such as `context_tag`, `context_log`,
 Current versions intentionally use conversation-native names instead:
 - `context_checkpoint`
 - `context_timeline`
-- `context_rewind`
+- `context_compact`
 
-These tools manage **conversation history**, not repository state. They should not be treated as Git commands or as replacements for real `git tag`, `git log`, or `git checkout`.
+These tools manage **conversation history**, not repository state. They should not be treated as Git commands or as replacements for real `git tag`, `git log`, or `git checkout`. Context navigation does not modify or roll back files, running processes, browser state, tickets, databases, or remote services.
 
 ## Installation
 
@@ -43,13 +43,13 @@ Open a visual dashboard to inspect context-window usage and token distribution (
 
 ### For Agents
 
-This extension adds the `context-management` skill, which includes three core tools:
+This extension adds the `context-management` skill, which guides agents to keep the active conversation as the smallest sufficient working set for the next step. It includes three core tools:
 
-1. **🔖 Structure (`context_checkpoint`)**
-   Create named checkpoints to organize conversation history.
+1. **🔖 Anchor (`context_checkpoint`)**
+   Label a meaningful conversation node with a unique semantic checkpoint name, such as `parser-fix-start` or `timeout-investigation-search`.
 
-2. **📊 Monitor (`context_timeline`)**
-   Visualize conversation history, inspect token usage, and see where you are in the task tree.
+2. **📊 Inspect (`context_timeline`)**
+   View the active path as a structural map of checkpoints, summaries/compactions, branch points, user turns, and current position. Use it when orientation or compact target selection depends on history shape.
 
-3. **⏪ Compress (`context_rewind`)**
-   Return to an earlier checkpoint or anchor with a carryover summary so completed noisy work can be compacted into a cleaner continuation.
+3. **⏪ Compact (`context_compact`)**
+   Create a summarized continuation branch from an earlier checkpoint, history node, or `root`. The summary should restore the useful state after the target: current task, decisions, external side effects such as changed files or remote updates, validation state, source anchors, and the explicit next step.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-context",
-  "version": "2.0.0-beta.0",
+  "version": "2.0.0",
   "description": "Agentic Context Management for Pi",
   "files": [
     "src",

package/skills/context-management/SKILL.md

@@ -1,274 +1,215 @@
 ---
 name: context-management
-description: Read this skill for work that is likely to stretch across many turns or get messy if handled in one uninterrupted thread. Especially use it when the request sounds like first go search or read a lot, first look through logs/files/pages/results and come back with the real conclusion, this will probably take several rounds, there may be several approaches to try, first make a plan or todo list and then work through it, there will be many similar cases to handle, the user may interrupt with side tasks, or the thread is already getting messy and should be cleaned up before continuing. It teaches a working mode built around frequent checkpoints, periodic timeline review, and targeted rewinds as the task evolves. Usually skip it for one-shot reads, bounded summaries, direct rewrites, or deterministic scripts.
+description: Use this skill for work likely to span many turns, branches, retries, research, reading several files/webpages, plan-then-execute phases, repeated cases, debugging, or interrupted/messy threads. It guides agents to maintain a clean working set with checkpoints, timeline review, and compaction at useful continuation boundaries. Usually skip for one-shot reads, bounded summaries, direct rewrites, simple lookups, or deterministic scripts.
 ---
 
 # Context Management
 
-Use this skill to adopt an explicit conversation-management working mode.
+Use this skill to maintain the active conversation as a useful **working set** for the next step. The goal is not to archive more history or compress more aggressively; it is to keep raw only the context that still needs direct reasoning, and carry the rest as compact task state when that is more efficient.
 
-This mode is for tasks where the work may still be valid, but the thread carrying it is likely to become long, noisy, multi-phase, or hard to keep clean. The goal is to keep the work navigable: checkpoint early, review timeline when needed, and compact completed noisy phases back to clean anchors.
+Core rhythm:
+
+- **checkpoint before mess**
+- **review timeline when structure affects the next decision**
+- **compact when a state summary is a better working set than the raw trail**
+
+Use only these tools:
 
-Use only the current tool names:
 - `context_checkpoint`
 - `context_timeline`
-- `context_rewind`
+- `context_compact`
+
+## Working-set model
+
+Before choosing a tool, ask:
 
-## When to use this skill
+- What am I trying to do next?
+- What facts, constraints, or artifacts must stay raw for that next action?
+- What history is useful only as a conclusion or state update?
+- What history is just process noise or stale baggage?
 
-Read this skill when the task is likely to outgrow one clean thread and would benefit from explicit history management.
+Classify context into three forms:
 
-It should feel like a good fit when the user is effectively asking for one of these patterns:
+- **Raw context:** user intent, constraints, code/log/error details, evidence, or plan text that you expect to inspect directly soon.
+- **State summary:** decisions, findings, lessons, changed files, validation status, rejected leads, and next steps that can replace raw process.
+- **Discardable process:** repetitive searches, verbose logs, abandoned hypotheses, false starts, and unrelated turns whose useful value is already captured or no longer needed.
 
-### “First go look through a lot of stuff, then come back with the real conclusion.”
-Examples:
-- searching or researching first
-- web search or browser-driven information gathering
-- reading many files, logs, docs, webpages, or web results
-- review / comparison / audit-heavy reading across many sources
+If the active context is already small, coherent, and directly useful for the next step, do not manage it just to be tidy.
 
-### “This will probably take several rounds or several phases.”
-Examples:
+## When to use
+
+Use this mode when the user is asking for work that may outgrow one clean thread:
+
+- search, research, browser work, or reading many files/logs/pages/results
+- several links or low-density webpages where only conclusions and next actions should survive
 - investigate -> decide -> execute -> validate
 - plan -> implement -> verify
-- collect -> compare -> conclude
-- any task that will keep changing shape as it progresses
-
-### “We may need to try more than one route.”
-Examples:
-- A / B / C approaches
-- dead ends and retries
-- compare and choose
-- pivoting after a failed direction
-
-### “Start from a plan or todo list, then work through it.”
-Examples:
-- a formal implementation or migration plan
-- a roadmap with milestones
-- a lightweight todo list or checklist
-- staged execution that will be revisited across many turns
-
-### “There will be many similar cases, tickets, or items.”
-Examples:
-- repeated cases
-- repeated tickets
-- repeated checks
-- repeated reviews
-- repeated fix attempts on similar inputs
-
-### “I may interrupt you, or this thread is already getting messy.”
-Examples:
-- the user may insert side tasks
-- you need to pause one line of work and resume it later
-- the thread is already long, stale, or cluttered
-- finished noisy phases should be cleaned up before continuing
-
-### “This is code-facing work and may turn noisy while I debug or implement it.”
-Examples:
-- implementation
-- debugging
-- troubleshooting
-- refactoring
-- migration
-- code-facing review or fix work
-
-If one of these patterns clearly applies, take the first structural action now—usually a checkpoint—instead of only describing the intended workflow.
-
-If multiple approaches, failed branches, compare work, or pivots become central, also read `references/retry-branch-and-pivot.md` in addition to the main scenario reference.
-
-## When to skip it
-
-Usually skip this skill for:
-- one-shot reads
-- bounded summaries
-- direct rewrites with little exploration
-- simple fact lookup or concept explanation
-- deterministic scripts or fixed-rule automation
-- short tasks that can stay clean in one thread
-
-## Operating rhythm
-
-1. Before entering a noisy phase, create a checkpoint.
-2. If you feel disoriented or anchor choice is unclear, run `context_timeline`.
-3. Add more checkpoints at milestones, phase boundaries, risky branches, and interruptions.
-4. Do not rewind just because the skill triggered.
-5. Once a noisy phase is complete and summarizable, rewind to the best earlier clean anchor.
-6. Continue from the compacted state instead of dragging the full messy path forward.
-
-The key habit is: **checkpoint is the default move; rewind is the selective cleanup move.** Checkpointing alone is not the end state. Checkpoints create anchors so that completed noisy phases can later be compacted cleanly.
+- multiple approaches, retries, failed branches, or pivots
+- repeated similar cases, tickets, reviews, or batch items
+- a main task that may be interrupted by side tasks
+- a scattered thread that should be cleaned up before continuing from a clean point
+- debugging, troubleshooting, refactoring, migration, or other code-facing work that may get noisy
+
+If one of these clearly applies, take a structural action now, usually a checkpoint. Do not merely describe the workflow. If the user has not yet provided enough task details, still create a checkpoint for the workflow shape before asking clarifying questions, and name the detected mode briefly (search/reading, planning, repeated batch, task switching/cleanup, development retry).
+
+Usually skip this skill for one-shot reads, bounded summaries, direct rewrites, simple fact lookup, conceptual explanation, deterministic scripts, short tasks that can stay clean, or moments where the active context is already a good working set.
+
+## Start-of-turn check
+
+At the start of each new user message, classify it:
+
+- **Same task / next phase**: continue; if the previous phase is complete and noisy, compact before the next phase.
+- **Correction or follow-up on the last answer**: usually answer from recent context; do not compact yet.
+- **New unrelated task or direction shift**: if the previous task left a complete noisy segment, inspect the timeline first when multiple checkpoints or possible anchors exist, then compact to a continuation anchor that gives the new task a clean working set.
+
+Think of the tools as a phase pipeline: `context_checkpoint` marks useful anchors, work happens, `context_timeline` shows the structure when orientation or target choice is unclear, and `context_compact` creates a new branch from the chosen continuation anchor with a summary of what happened after it. The target is a working-set choice, not an age choice: keep raw context only when it will help the next action; summarize or drop raw process when it would distract.
+
+This prevents both premature cleanup after final answers and endless checkpoint-only behavior that lets stale work accumulate.
+
+## Main loop
+
+1. Before noisy work, create a semantic checkpoint as the first context-management action, even if the next visible step is asking for missing inputs. If the first job is orientation over existing history, run `context_timeline` before adding a new checkpoint.
+2. When the task shape is clear, read one matching scenario reference only if it will change tool timing, anchor choice, or summary content. Skip reference loading for obvious short applications where this main skill body is enough. Do not stop after checkpoint-only unless the prompt is intentionally lightweight.
+3. Add checkpoints at meaningful milestones: phase boundaries, risky attempts, reusable batch methods, and interruptions.
+4. Use `context_timeline` when the active path structure affects the next decision or compact target.
+5. At phase boundaries, run the compact gate before starting another phase. If the whole requested task is complete and only the final response remains, answer and wait; let the next user message determine whether cleanup is useful.
+6. After a successful compact, continue from the injected summary instead of dragging the full raw path forward.
+
+## Read the right reference
+
+Read **one primary reference** based on task shape when the scenario pattern will affect tool timing, anchor choice, or summary content:
+
+- search / research / reading-heavy work, especially web search, browser operation, or low-density webpages -> `references/search-research-and-reading.md`
+- development / debugging / troubleshooting / refactoring / migration -> `references/development-and-troubleshooting.md`
+- planning / staged execution / todo-driven work -> `references/planning-and-execution.md`
+- repeated similar items / batch work -> `references/repeated-items-and-batch-work.md`
+- task switching / pause-resume / interruptions to a mainline task / scattered-thread cleanup-and-continue -> `references/task-switching-and-cleanup.md`
+
+Also read `references/retry-branch-and-pivot.md` when multiple approaches, failed branches, comparisons, retries, or pivots become central. For code/debugging work with repeated attempts, use both `references/development-and-troubleshooting.md` and `references/retry-branch-and-pivot.md`.
 
 ## Tool policy
 
 ### `context_checkpoint`
-This is the default tool in this mode.
 
-Use it:
-- before noisy work
-- before a new phase
-- after a meaningful milestone
-- before a risky attempt
-- before switching to another subtask
+Default move. Use it before noisy work, a new phase, a risky attempt, switching subtasks, or after a meaningful milestone.
 
-Use semantic names so the timeline stays readable.
+Use semantic names so the timeline stays readable:
 
-Recommended patterns:
 - `<task>-start`
 - `<task>-<phase>`
 - `<task>-<attempt>`
 - `<task>-<milestone>`
 
-Examples:
-- `auth-oauth-start`
-- `timeout-analysis-search`
-- `db-migration-plan`
-- `parser-fix-attempt-2`
-- `vendor-review-milestone-1`
+Examples: `auth-oauth-start`, `timeout-analysis-search`, `db-migration-plan`, `parser-fix-attempt-2`.
 
 Avoid generic names like `start`, `checkpoint-1`, `phase-1`, or `retry`.
 
 ### `context_timeline`
-Use this tool to regain orientation.
-
-Use it:
-- when you feel lost or drifted
-- when several checkpoints or branches now exist
-- before choosing a rewind target
-- at major phase transitions if you need a quick map
-- when the thread feels cluttered and you want a structural view before acting
-
-When you inspect timeline, ask:
-- Where is the nearest clean anchor?
-- Has the current segment grown too long without a clean checkpoint?
-- Am I carrying a failed or stale branch forward?
-- Is there already a better checkpoint to rewind to?
-
-### `context_rewind`
-Use this tool to compact a path that should no longer stay active in full.
-
-Use it:
-- after a noisy investigation has produced a stable finding
-- after a failed attempt has produced a clear lesson
-- after a completed phase where the next step is clear
-- after a representative item or branch has already taught you what you need
-- when the current path is dragging too much stale or low-value context forward
-
-A successful use of this mode often ends with `context_rewind`, not just more checkpointing.
-
-## Rewind protocol
-
-### When to rewind
-Rewind when the current phase is ready to be compacted.
-
-Good reasons to rewind:
-- a phase produced a stable finding or conclusion
-- a failed path produced a clear dead-end lesson
-- a milestone was reached and you want a cleaner continuation
-- a representative item or branch has already taught you the reusable lesson
-- the thread is carrying more stale intermediate process than active value
-
-A phase is usually rewind-ready when you now have one of these:
-- a root cause or research conclusion
-- a clear failure reason for abandoning a branch
-- a completed implementation or troubleshooting phase
-- a reusable method learned from a representative item
-- a finished repeated-item segment whose raw path no longer needs to stay live
-
-Do **not** rewind yet when:
-- you are still in the middle of active exploration
-- the result is still unstable or incomplete
-- you only feel mild clutter and a checkpoint would be enough
-- you have not yet decided which earlier anchor you want to continue from
-
-When in doubt: checkpoint first, review timeline if needed, and rewind later once the phase boundary is clearer.
-
-### Choose the target and backup
-Choose the **best earlier clean anchor**, not just any earlier checkpoint.
-
-Usually prefer:
-- the start of the noisy phase you are compacting
-- the nearest clean phase-start before the current failed or completed path
-- the repeated-work anchor for repeated-item workflows
-- the last stable pre-branch checkpoint when abandoning an approach
 
-Avoid:
-- rewinding too far back when a nearer clean anchor exists
-- rewinding to a checkpoint that still includes the noise you want to leave behind
-- defaulting to `root` unless the whole active path should be reset
+Use it as the structural view of the active path, not only as a rescue tool:
+
+- when the current path shape affects the next decision
+- when several checkpoints, branches, or task switches exist
+- before choosing a compact target that is not obvious
+- when the thread feels cluttered and you need to distinguish useful context from baggage
+
+When reading the timeline, ask:
+
+- What is the current task and immediate next action?
+- Which prior raw messages are still needed for that next action?
+- Which completed, failed, or unrelated paths are now baggage?
+- Which anchor gives the smallest sufficient working set after summary injection?
+
+### `context_compact`
+
+Use it to replace raw history with a state summary when the next phase would benefit from a smaller working set.
+
+Typical compact boundaries: investigation -> execution, diagnosis -> fix, implementation -> validation, failed attempt -> next attempt, representative item -> remaining batch, completed noisy task -> new user task.
 
-If you are unsure which anchor is best, run `context_timeline` first.
+Do not compact while exploration is still active, when the result is unstable, just because the skill triggered, or just because the user-visible task ended.
 
-Use `backupCheckpoint` when:
-- the raw path may still be useful later
-- you are compacting a long investigation
-- you are abandoning a branch but may need its details again
-- you want a safe recovery point before a major rewind
+## Compact gate
 
-A backup checkpoint preserves the raw path you are compacting. If the summary later proves insufficient, return to that backup instead of redoing the whole investigation.
+Before calling `context_compact`, require all three:
 
-If the raw path is low value and unlikely to matter again, a backup is optional.
+1. The segment being left behind is noisy, stale, failed, low-value in raw form, or actively reducing focus.
+2. You can restore the useful task state in a clear summary.
+3. There is an immediate continuation that benefits from cleaner context.
 
-### Write the message
-A rewind message is the baton pass to future-you. It is not a throwaway comment.
+If the compact is prompted by a new user message, a direction shift, or several possible checkpoint targets, run `context_timeline` first and choose the target from the visible structure rather than from memory.
 
-At minimum, include:
-- the main result, lesson, or failure summary
-- why you are rewinding now
-- important changes, especially changed files if disk state changed
-- the next step after the rewind
+Condition 3 means the next action is a new phase, not just more of the same exploration. Examples: run the export, implement the fix, validate, process the next item, or try the chosen next approach.
 
-Useful shapes:
-- `[result] + [reason for rewind] + [next step]`
-- `[result] + [reason for rewind] + [important decision or change] + [next step]`
-- `[result] + [reason for rewind] + [important changes / changed files] + [next step]`
+If conditions 1 and 2 are true but the whole task is done and only the final answer remains, wait. Compact later only if the next user message makes it useful.
+
+## Choosing target and backup
+
+Choose the continuation anchor by designing the next working set:
+
+1. Name the immediate next action.
+2. Decide what must remain raw: active user intent, current constraints, still-open evidence or code context, an approved plan being executed, or details you expect to inspect directly next.
+3. Decide what can become state summary or disappear: completed searches, verbose logs, failed attempts, stale branches, earlier unrelated tasks, and process details whose useful value is already clear.
+4. Pick the anchor that leaves the new branch with the **smallest sufficient context** after summary injection.
+5. If an older anchor plus a stronger summary is cleaner than a recent anchor plus stale context, prefer the older anchor.
+
+The right target may be a recent phase-start, a plan-ready checkpoint, a pre-branch checkpoint, a repeated-work baseline, an older checkpoint, or `root`. `root` is appropriate when the old path no longer contributes raw context and the summary can carry the necessary state.
+
+Avoid targets that create a poor working set:
+
+- too late: the new branch still contains the clutter, failed path, or unrelated task you meant to leave behind
+- too early with a weak summary: the next phase loses constraints, decisions, evidence, or changed-file state it needs
+- semantically wrong: the anchor preserves a context frame that no longer matches the current task
+
+For bounded phases, choose by what should remain raw:
+
+- target `research-start` to summarize the whole research segment
+- target `research-end` to keep research raw and summarize only later clutter before follow-up research
+
+If there are several checkpoints, a task switch, or any uncertainty about the best working set, run `context_timeline` first.
+
+Use `backupCheckpoint` when the raw path may still matter later: long investigations, abandoned branches, risky compactions, or details that may be needed for recovery. A backup checkpoint is a recovery safety net, not a substitute for the summary; include details likely needed in the next phase because returning to backup is costly.
+
+## Compact summary contract
+
+The summary is not a transcript recap. It is the state needed to resume work from the chosen anchor; older or cleaner anchors require stronger summaries.
+
+Context tools change conversation state, not the outside world. Files, processes, browser state, tickets, databases, remote services, and other side effects stay current. If you compact to an anchor before those changes, the summary must bridge the gap between old conversation context and current external state.
+
+A compact summary must restore:
+
+1. **Task state:** current task, user intent, constraints, decisions, assumptions, and known result/progress/failure.
+2. **External state:** changed files, created/deleted artifacts, running/stopped processes, browser actions, tickets/records, deployments, remote changes.
+3. **Verification state:** commands already run, validation status, notable outputs, and remaining risks or open questions.
+4. **Navigation state:** source anchors/evidence when needed, rejected leads worth avoiding, backup checkpoint guidance, and the explicit next step.
+
+Include why compacting is appropriate only when it helps future orientation. Avoid vague summaries like `Done`, `Investigated`, `Switching context`, or `Going back`.
 
 Good examples:
-- `Found DB connection pool exhaustion as the likely root cause. Reason: investigation phase is complete and ready to compact. Next step: report findings and propose mitigation.`
-- `Parser fix is implemented and the debugging phase is complete. Reason: compacting implementation history before focused validation. Important changes: modified src/parser.ts and test/parser.test.ts. Next step: run targeted validation and summarize remaining edge cases.`
-- `WeakRef approach failed because objects were collected too early and cache hit rate collapsed. Reason: abandoning this attempt and returning to a clean anchor. Next step: try object pooling instead.`
-
-Avoid vague messages like:
-- `Done`
-- `Switching context`
-- `Investigated`
-- `Going back`
-
-Before using `context_rewind`, quickly check:
-- Is there already a stable result, lesson, or failure summary?
-- Do I know why this is the right moment to rewind?
-- If disk state changed, did I record the important changes or changed files?
-- Is the next step explicit?
-- Would future-me understand what changed just from this message?
-
-If not, keep working a bit longer or checkpoint first.
-
-### After rewind
-When `context_rewind` succeeds:
+
+- `Current task: plan mitigation for API timeouts. State: DB pool exhaustion is the likely root cause. Evidence: logs show pool wait timeouts during peak traffic; config has pool size 10; no network errors found. Rejected lead: API gateway timeout appears downstream of DB waits. Next step: propose mitigation and validation steps.`
+- `Current task: validate the parser fix. State: implementation is done. External state: changed files src/parser.ts and test/parser.test.ts. Validation not yet run after the final edit. Next step: run targeted parser tests and summarize remaining edge cases. Backup: parser-fix-debug-history if exact failed attempts are needed.`
+
+Before compacting, quickly check: stable state? real continuation? anchor gives the smallest sufficient working set? summary restores state after that anchor? external side effects and validation captured? explicit next step?
+
+## After compact
+
 1. Read the injected summary carefully.
 2. Treat it as the new active state.
-3. Execute the next step from that summary.
-4. Do not keep reasoning from the full old path unless you intentionally return to a backup checkpoint.
+3. Before continuing, verify it contains enough state for the next action.
+4. Remember that disk and external systems were not rolled back by the context move; if state matters, inspect the current files/tools/services rather than trusting the historical anchor.
+5. If a missing detail is cheap to reconstruct from disk, tools, or source anchors, retrieve it directly.
+6. Return to the backup checkpoint only when the missing raw context cannot be reconstructed cheaply.
 
 ## Common mistakes
 
 Avoid:
-- checkpointing constantly without phase meaning
-- rewinding blindly without checking timeline when anchor choice is unclear
-- carrying completed noisy phases forward instead of compacting them
-- writing vague rewind messages that future-you cannot act on
-
-## Read the right reference
 
-Read **one primary reference** based on the task shape:
-- search / research / reading-heavy work, especially web search, browser operation, or low-density webpage reading -> `references/search-research-and-reading.md`
-- development / debugging / troubleshooting / refactoring / migration -> `references/development-and-troubleshooting.md`
-- planning / staged execution / todo-driven work -> `references/planning-and-execution.md`
-- repeated similar items / batch work -> `references/repeated-items-and-batch-work.md`
-- task switching / pause-resume / cleanup-and-continue work -> `references/task-switching-and-cleanup.md`
-
-Then read the cross-cutting retry reference when needed:
-- multiple approaches, failed branches, compare, retry, or pivot behavior -> `references/retry-branch-and-pivot.md`
-
-Keep the mode simple:
-- checkpoint before mess
-- review timeline when orientation matters
-- rewind when a phase is ready to be compacted
+- checkpointing constantly without phase meaning
+- compacting blindly without timeline when anchor choice is unclear
+- preserving too much raw history because older anchors or `root` feel risky
+- using an old anchor or `root` with a weak summary that drops current task state
+- compacting immediately after a final deliverable when no next user intent is known
+- carrying completed noisy phases into a new task
+- writing summaries that recap history but fail to restore current task state
+- assuming compact or branch navigation reverts files, processes, browser state, or remote services
+- omitting decisions, constraints, external side effects, changed files, validation status, or next step

package/skills/context-management/references/development-and-troubleshooting.md

@@ -15,7 +15,7 @@ These tasks often stay cleaner when treated as stages with anchors, instead of o
 1. Create a checkpoint before starting serious work.
 2. Add checkpoints before risky edits, new approaches, or major phase changes.
 3. Review the timeline when you need to understand the current shape of the work.
-4. Rewind after a stable implementation milestone, a failed approach, or a completed troubleshooting phase.
+4. Compact after a stable implementation milestone, a failed approach, or a completed troubleshooting phase when there is another phase, attempt, validation step, or task switch that benefits from cleanup. If files, processes, or external systems changed, include those side effects in the summary because context navigation does not roll them back. If the completed phase is also the final user-visible deliverable, answer first and wait.
 
 ## Typical checkpoint moments
 
@@ -40,28 +40,28 @@ Run `context_timeline` when:
 - you are about to abandon one approach and restart from another anchor
 - you are unsure which checkpoint best represents the clean continuation point
 
-## Rewind patterns
+## Compact patterns
 
 ### After a failed attempt
 
-Use rewind when an attempt clearly failed and you have a crisp summary of why.
+Use compact when an attempt clearly failed and you have a crisp summary of why.
 
 ```javascript
-context_rewind({
+context_compact({
   target: "memory-leak-fix-start",
-  message: "WeakRef approach failed because objects were collected too early and cache hit rate collapsed. Reason: abandoning this attempt and returning to a clean anchor. Next step: try object pooling instead.",
+  summary: "Current task: continue the memory leak fix. State: WeakRef approach failed because objects were collected too early and cache hit rate collapsed. Decision: abandon WeakRef and try object pooling. Next step: implement the object-pooling approach.",
   backupCheckpoint: "memory-leak-weakref-raw-history"
 });
 ```
 
 ### After a completed phase
 
-Use rewind when a phase is done and you want to continue from a cleaner thread.
+Use compact when a phase is done and the next phase would work better from a focused state summary than from the raw implementation/debugging trail. Do not use this as a reflexive final step after delivering the finished work; use it before validation, the next phase, the next attempt, or the next user task.
 
 ```javascript
-context_rewind({
+context_compact({
   target: "parser-fix-start",
-  message: "Parser fix is implemented and the debugging phase is complete. Reason: compacting implementation history before focused validation. Next step: run targeted validation and summarize remaining edge cases.",
+  summary: "Current task: validate the parser fix. State: implementation is done and the debugging trail can be summarized. External state: parser implementation and related tests were changed on disk; context navigation did not revert them. Validation not yet run after final edit. Next step: run targeted validation and summarize remaining edge cases.",
   backupCheckpoint: "parser-fix-debug-history"
 });
 ```

package/skills/context-management/references/planning-and-execution.md

@@ -30,9 +30,10 @@ Both variants use the same context-management rhythm.
 2. Create a checkpoint for the clean plan-ready state.
 3. Execute one subtask or phase.
 4. If that subtask becomes noisy, let it get noisy locally.
-5. Once the subtask produces a stable takeaway, rewind back to the plan-ready or phase-start anchor.
-6. Continue with the next subtask from the clean anchor.
+5. Once the subtask produces a stable takeaway and another subtask or phase remains, compact to the anchor that gives the next subtask the cleanest sufficient working set, often the plan-ready or phase-start anchor.
+6. Continue with the next subtask from that focused working set.
 7. If the plan changes materially, checkpoint the updated plan state again.
+8. If the last subtask completes the user's whole request, give the final answer without an automatic compact; decide on cleanup at the next user message if the conversation continues.
 
 ## Useful anchors
 
@@ -49,16 +50,17 @@ Run `context_timeline` when:
 - several subtasks have already been executed
 - the plan has changed more than once
 - multiple branches now exist under the same plan
-- you are unsure whether to rewind to the overall plan anchor or the current phase-start anchor
+- you are unsure whether the next subtask needs the overall plan, the current phase context, or only a summary
 
-## When to rewind
+## When to compact
 
-Rewind when:
-- a subtask is complete and its raw execution path is no longer worth keeping active
+Compact when:
+- a subtask is complete, another subtask remains, and its raw execution path is no longer worth keeping active
 - a phase finished and the next phase should start from a cleaner state
 - the plan remains valid but the current execution segment has become noisy
+- a later user message starts a new task after the plan-driven task completed noisily
 
-Do not rewind just because a todo list exists. Rewind when a specific execution segment has already served its purpose and can be compacted.
+Do not compact just because a todo list exists. Compact when a specific execution segment has already served its purpose and can be compacted for an actual continuation. If the segment changed files, launched/stopped processes, or updated external systems, record those side effects in the summary; context navigation does not revert them.
 
 ## Replan
 
@@ -73,7 +75,7 @@ If the plan change is driven by failed branches or strategy shifts, also read `r
 ## Common mistakes
 
 Avoid:
-- keeping every finished subtask's raw reasoning active
-- rewinding too far back when the current plan-ready anchor is still valid
+- keeping every finished subtask's raw reasoning active instead of preserving only the reusable state
+- choosing an anchor that drops the current plan state without preserving it in the summary
 - failing to checkpoint the updated plan after a major replan
 - confusing repeated-item work with plan-driven work when the subtasks are actually different in nature

package/skills/context-management/references/repeated-items-and-batch-work.md

@@ -14,10 +14,10 @@ Use this reference when the items are similar enough that the same method should
 1. Create a checkpoint at the start of the overall repeated-item task.
 2. If item 1 teaches you a reusable approach, checkpoint again after that approach becomes clear.
 3. Work item by item.
-4. Rewind after each completed item or completed mini-phase when the raw path is no longer worth carrying forward.
+4. Compact after each completed item or completed mini-phase when another item remains and the raw path is no longer worth carrying forward.
 5. Use timeline occasionally to verify that the history still has a clean structure.
 
-For repeated-item work, the default completion move is not "keep carrying the last item's raw reasoning". Once an item is done and its takeaway is stable, rewind back to the repeated-work anchor.
+For repeated-item work, the default between-item move is not "keep carrying the last item's raw reasoning". Once an item is done, its takeaway is stable, and another item remains, compact to the repeated-work anchor or other baseline that preserves the reusable method without item-specific noise. If the last item completes the whole user request, deliver the final answer and wait for the next user message before deciding whether to compact.
 
 ## Useful anchors
 
@@ -31,16 +31,17 @@ Example checkpoint names:
 
 Run `context_timeline` when:
 - several items have already been processed
-- item-level work has created multiple branches or rewinds
+- item-level work has created multiple branches or compactions
 - you want to confirm that the overall pattern still looks clean
 - you are about to choose which anchor repeated work should keep returning to
 
-## When to rewind
+## When to compact
 
-Rewind after:
-- a representative item produced a reusable method
-- a single item is complete and the raw path should be compacted
+Compact after:
+- a representative item produced a reusable method and the batch will continue
+- a single item is complete, another item remains, and the raw path should be compacted
 - an item-specific dead end is understood and should not remain active in full
+- a new user message arrives after the batch completed, and the batch's raw path is stale baggage for the new task
 
 ## Example rhythm
 
@@ -53,16 +54,16 @@ context_checkpoint({ name: "vendor-review-method-clear" });
 
 // ... process another item ...
 
-context_rewind({
+context_compact({
   target: "vendor-review-method-clear",
-  message: "One more vendor review completed. Reason: compacting finished item work and returning to the clean repeated-item anchor. Next step: process the next vendor using the same method.",
+  summary: "Current task: continue the vendor review batch. State: one more vendor review is complete; item-specific reasoning no longer needs to stay raw. Reusable method remains the active baseline. Next step: process the next vendor using the same method.",
   backupCheckpoint: "vendor-review-item-7-history"
 });
 ```
 
 ## Warning signs
 
-Use stronger checkpoint/timeline/rewind discipline when:
+Use stronger checkpoint/timeline/compact discipline when:
 - each item creates lots of local reasoning
 - you are starting to confuse one item's path with another's
 - the repeated work is stretching across many turns

package/skills/context-management/references/retry-branch-and-pivot.md

@@ -5,7 +5,7 @@ Use this reference when multiple approaches are being tried and abandoned cleanl
 - failed branches that should not pollute the main line
 - compare-and-choose work
 - strategy pivots or goal shifts
-- restarting from a cleaner anchor after a dead end
+- restarting from a focused working set after a dead end
 
 This is a **cross-cutting pattern reference**. Read it alongside a primary reference such as search/research, development/troubleshooting, or planning/execution when branch behavior becomes central.
 
@@ -14,24 +14,24 @@ This is a **cross-cutting pattern reference**. Read it alongside a primary refer
 1. Checkpoint before opening a risky branch or alternative path.
 2. Explore or implement that branch.
 3. If anchor choice becomes unclear, inspect timeline.
-4. Once the branch produces a stable lesson, decision, or dead-end, rewind back to the best clean pre-branch anchor.
-5. Continue with the next branch or the chosen direction from that clean state.
+4. Once the branch produces a stable lesson, decision, or dead-end, compact to the anchor that removes branch noise while preserving the state needed for the next attempt.
+5. Continue with the next branch or the chosen direction from that focused state.
 
 ## When to review timeline
 
 Run `context_timeline` when:
 - multiple branches now exist
 - you are unsure which branch actually stayed useful
-- you need to choose the cleanest pre-branch anchor
+- you need to choose which pre-branch or older anchor gives the next attempt the best working set
 - the next direction is clear but the old branch still clutters active context
 
-## When to rewind
+## When to compact
 
-Rewind when:
+Compact when:
 - a branch clearly failed
 - a comparison is complete and one option won
 - the direction changed enough that the old path is now baggage
-- the next attempt should start from a cleaner base
+- the next attempt should start from a focused state rather than the raw failed branch
 
 ## Strategy pivot
 
@@ -44,7 +44,7 @@ Examples:
 
 In these cases:
 - summarize what still matters
-- rewind back to the best clean anchor before the stale branch
+- compact to the anchor that removes the stale branch while preserving current task state
 - continue under the new direction
 
 ## Example rhythm
@@ -54,9 +54,9 @@ context_checkpoint({ name: "oauth-fix-start" });
 
 // ... try cookie-based approach ...
 
-context_rewind({
+context_compact({
   target: "oauth-fix-start",
-  message: "Cookie-based approach is not viable because the callback flow loses session continuity. Reason: retrying from a clean anchor after a failed branch. Important decision: switch to signed state tokens. Next step: implement the signed-state approach.",
+  summary: "Current task: continue the OAuth fix with a new approach. State: cookie-based approach is not viable because the callback flow loses session continuity. Decision: switch to signed state tokens. Next step: implement the signed-state approach.",
   backupCheckpoint: "oauth-cookie-approach-history"
 });
 context_checkpoint({ name: "oauth-signed-state-start" });
@@ -67,5 +67,5 @@ context_checkpoint({ name: "oauth-signed-state-start" });
 Avoid:
 - opening alternative branches without a clean checkpoint first
 - dragging failed branches forward after their lesson is already clear
-- rewinding to a point that still includes the branch you meant to abandon
+- compacting to a point that still includes the branch you meant to abandon
 - treating every branch as equally worth preserving

package/skills/context-management/references/search-research-and-reading.md

@@ -17,10 +17,12 @@ This reference is for **input-heavy work where the process is much larger than t
 1. Create a checkpoint before a large search or reading loop.
 2. Search, browse, read, inspect, and follow leads normally.
 3. If you lose orientation, review the timeline.
-4. Once the investigation yields a stable finding, rewind to a cleaner anchor.
-5. Continue with the conclusion, recommendation, or next action instead of carrying the entire raw exploration forward.
+4. Once the investigation yields a stable finding and there is another step to take, compact to the anchor that gives the next step a focused working set.
+5. Continue with the conclusion, recommendation, or next action instead of carrying the entire raw exploration forward. If the finding is the final answer to the user's current request, answer first and wait; compact on the next user message if it starts new work.
 
-Do not stop at "I already made a checkpoint" if the investigation phase is actually complete. The cleanup move for completed research is usually a rewind back to the best earlier anchor.
+Do not stop at "I already made a checkpoint" if the investigation phase is complete and the conversation is continuing. The cleanup move for completed research is usually a compact to the anchor that preserves only the raw context the next step still needs.
+
+**Important:** “another step” includes the next phase of the same request. If you searched to find the right data source, previous task record, API shape, rule id, or query pattern, then the next execution step (running the real query/export, implementing, validating, etc.) is an immediate continuation. Compact before that execution step, not only before a future user message.
 
 ## When to checkpoint
 
@@ -44,17 +46,34 @@ Run `context_timeline` when:
 - the investigation has already produced multiple checkpoints
 - you are deciding which path should be compacted
 
-## When to rewind
+## When to compact
 
-Rewind after the investigation produces one of these:
+Compact after the investigation produces one of these and there is a continuation that benefits from cleanup:
 - a stable root cause
 - a stable comparison result
 - a dead-end conclusion
 - a shortlist of viable next actions
+- a located data source, old conversation, schema, rule id, query/API pattern, or other fact that unlocks execution
+
+If you already have one of these, the investigation phase is usually complete enough to compact. If the next step is to use the finding in another tool call, compact first. If there is no continuation yet because you are about to give the final answer, wait until the next user message before deciding.
+
+Do not compact in the middle of a still-open search loop just because the thread feels busy.
+
+## Message quality for research compactions
+
+Research compactions are especially sensitive to summary quality. The raw exploration may contain details that become important later, but returning to the backup branch is a context switch. Preserve the state needed to use the finding, not the whole journey.
 
-If you already have one of these, the investigation phase is usually complete enough to compact.
+Include:
+- **Current task/state:** what the research unlocked and how it will be used next
+- **Finding:** what is now known
+- **Source anchors:** key files, URLs, docs, sessions, commands, queries, or records used to reach the finding
+- **Evidence:** important numbers, errors, examples, IDs, or constraints that support the finding
+- **Rejected leads:** only expensive dead ends that future-you should not repeat
+- **Open questions:** what is still uncertain
+- **Next step:** what to do immediately after compact
+- **Backup pointer:** if `backupCheckpoint` is set, when to return to it
 
-Do not rewind in the middle of a still-open search loop just because the thread feels busy.
+Do not compress research to only “found the answer”. That forces future-you to either trust an unsupported conclusion or switch back to the backup for basic details.
 
 ## Typical rhythm
 
@@ -63,17 +82,19 @@ context_checkpoint({ name: "timeout-investigation-start" });
 
 // ... search logs, read code, compare docs, inspect outputs ...
 
+// Stable finding found and the next action is execution/validation, so compact before continuing.
 context_timeline();
 
-context_rewind({
+context_compact({
   target: "timeout-investigation-start",
-  message: "Found DB connection pool exhaustion as the likely root cause. Reason: investigation phase is complete and ready to compact. Next step: report findings and propose mitigation."
+  backupCheckpoint: "timeout-investigation-raw-history",
+  summary: "Current task: plan mitigation for API timeouts. State: DB connection pool exhaustion is the likely root cause. Evidence: logs show pool wait timeouts during peak traffic; config has pool size 10; no network errors found in the checked logs. Rejected lead: API gateway timeout was downstream of DB waits, not the origin. Backup: timeout-investigation-raw-history if exact log lines are needed. Next step: propose mitigation and validation steps."
 });
 ```
 
-## Good rewind outcomes
+## Good compact outcomes
 
-After rewinding, you should be able to continue with:
+After compacting, you should be able to continue with:
 - the finding
 - the recommendation
 - the next verification step

package/skills/context-management/references/task-switching-and-cleanup.md

@@ -2,29 +2,34 @@
 
 Use this reference when the main problem is not the task domain itself, but a change in thread state, such as:
 - the user inserts a temporary side task
+- the user starts a new task after a completed noisy task
 - you need to pause one line of work and resume it later
 - several active fronts now exist
 - the thread is already messy and needs cleanup before continuing
-- a finished noisy phase should be summarized and left behind
+- a finished noisy phase should be summarized and left behind before new work starts
 
 This reference is for **pause/resume, cleanup, and clean continuation**. It is not for repeated similar items or plan-driven execution.
 
-## Two common variants
+## Three common variants
 
 ### Interruption / task switch
 Use when you are actively switching away from one line of work and intend to come back.
 
+### Completed-task handoff
+Use when a previous task is complete, the user has now said something new, and the previous task's raw path is noisy enough that it should not be carried into the new work.
+
 ### Cleanup and continue
 Use when the thread is already stale or messy and you want to compress it now, even though context management is being adopted late.
 
 ## Working pattern
 
 1. Inspect timeline if anchor choice is unclear.
-2. Before switching away or compacting a noisy path, preserve the best clean anchor.
+2. Before switching away or compacting a noisy path, preserve or choose the anchor that will give the resumed/new task a clean working set.
 3. If needed, create a backup checkpoint for the current noisy branch.
-4. Handle the side task or cleanup move.
-5. Rewind away the stale path when the baton pass is clear.
-6. Resume from the paused anchor or continue from the compacted state.
+4. If the user has just started a new task after a completed noisy task, compact before doing the new task so the completed task becomes a compact summary rather than active baggage.
+5. Handle the side task or cleanup move.
+6. Compact away the stale path when the handoff summary is clear.
+7. Resume from the paused anchor or continue from the compacted state.
 
 ## Useful anchors
 
@@ -40,24 +45,28 @@ Run `context_timeline` when:
 - multiple interruptions happened
 - the pause lasted many turns
 - several side-task branches now exist
-- you are unsure which clean anchor should be resumed
+- you are unsure which anchor gives the resumed/new task the right working set
 - the thread is already messy and you need to find the right pre-noise checkpoint
 
-## When to rewind
+## When to compact
 
-Rewind when:
+Compact when:
 - the interruption created lots of noise
 - the side task is done and should not stay active in full
+- the user begins a new task after a completed noisy task and the previous raw path is no longer useful in full
 - a stale path is making current reasoning worse
 - the useful state is now much smaller than the accumulated process
-- you can express the baton pass clearly in a summary
+- you can express the handoff clearly in a summary
 
-If the interruption was tiny and clean, a rewind may be unnecessary. A checkpoint before switching away is still the key move.
+Do not compact at the instant you finish a user-visible task if there is no known continuation. In that moment, deliver the answer and wait. If the next user message starts a new task, that is the right time to compact the completed task before proceeding. If the completed task changed files, browser state, tickets, or remote services, include those side effects in the handoff summary because the context move does not undo them. If the interruption was tiny and clean, a compact may be unnecessary. A checkpoint before switching away is still the key move.
 
 ## Common mistakes
 
 Avoid:
 - switching away without a pause checkpoint
+- compacting immediately after a final answer just because the task completed
+- starting a new, unrelated user task while still carrying the previous task's full raw path
 - returning to the main line while still carrying the side task's full raw path
 - trying to clean up without first checking timeline when anchor choice is unclear
-- over-resetting and losing still-valid near-term context
+- resetting past still-valid near-term context without carrying it in the summary
+- forgetting that files and external systems remain in their latest state after context navigation

package/src/index.ts

@@ -3,6 +3,7 @@ import {
     type SessionManager,
     type SessionEntry,
     type ExtensionCommandContext,
+    type ContextUsage,
 } from "@earendil-works/pi-coding-agent";
 import {
     Type,
@@ -20,12 +21,21 @@ interface SessionTreeNode {
     label?: string;
 }
 
-const InternalTools = ["context_checkpoint", "context_timeline", "context_rewind"];
+const InternalTools = ["context_checkpoint", "context_timeline", "context_compact"];
 let CommandCtx: ExtensionCommandContext | null = null;
-let RewindParams: any = null;
+let CompactParams: any = null;
 
 const isInternal = (name: string) => InternalTools.includes(name);
 
+const formatContextUsage = (usage: ContextUsage | undefined, includeTokens = false): string => {
+    if (usage?.percent == null) return "Unknown";
+
+    const percent = `${usage.percent.toFixed(1)}%`;
+    if (!includeTokens || usage.tokens == null) return percent;
+
+    return `${percent} (${formatTokens(usage.tokens)}/${formatTokens(usage.contextWindow)})`;
+};
+
 const resolveTargetId = (sm: SessionManager, target: string): string => {
     if (target.toLowerCase() === "root") {
         const tree = sm.getTree();
@@ -47,20 +57,23 @@ const resolveTargetId = (sm: SessionManager, target: string): string => {
     return target;
 };
 
+const ContextTimelineDescription = "Inspect the active conversation path as a structural map: checkpoints, summaries/compactions, branch points, user turns, and current position. Use when orientation or compact target selection depends on the shape of history.";
 const ContextTimelineParams = Type.Object({
-    limit: Type.Optional(Type.Number({ description: "History limit for visible entries (default: 50)." })),
-    verbose: Type.Optional(Type.Boolean({ description: "If true, show all messages. If false (default), collapse intermediate AI steps and only show milestones, user messages, checkpoints, branch points, and summaries." })),
+    limit: Type.Optional(Type.Number({ description: "Maximum visible timeline entries (default: 50)." })),
+    verbose: Type.Optional(Type.Boolean({ description: "If true, show all messages including internal context-tool traffic. If false (default), collapse to structural milestones." })),
 });
 
-const ContextRewindParams = Type.Object({
-    target: Type.String({ description: "Where to rewind or compact to. Can be a checkpoint name, a history node ID, or root. This becomes the starting point for a fresh continuation of the conversation." }),
-    message: Type.String({ description: "The carryover summary for the fresh continuation. Summarize current progress, lessons, important file changes, and the next step so the agent can continue from a clean context. A good summary message includes status, reason, important changes, and next step." }),
-    backupCheckpoint: Type.Optional(Type.String({ description: "Optional checkpoint name to apply to the current conversation state before rewinding. Use this to preserve a named backup of the noisy path you are about to compact away." })),
+const ContextCompactDescription = "Create a summarized continuation branch from an earlier checkpoint or history node. The selected target is the branch point; the summary must restore the useful state from the compacted path after that target. This changes conversation history only; it does not modify or roll back disk files or external systems.";
+const ContextCompactParams = Type.Object({
+    target: Type.String({ description: "Checkpoint name, history node ID, or root to use as the branch point for the summarized continuation." }),
+    summary: Type.String({ description: "Handoff summary injected into the new continuation branch. Restore current task/state, decisions/constraints, important external side effects (changed files, processes, browser/tickets/remote state), validation status, source anchors/evidence/open questions likely needed soon, and explicit next step. Do not rely on backupCheckpoint for details needed in the next phase." }),
+    backupCheckpoint: Type.Optional(Type.String({ description: "Optional checkpoint name to label the current conversation state before branching. This is only a recovery pointer; the summary must still contain the state needed to continue." })),
 });
 
+const ContextCheckpointDescription = "Create a named anchor by labeling a conversation history node. This does not branch, summarize, or affect external state; it only makes the point easy to find later in timeline or compact target selection.";
 const ContextCheckpointParams = Type.Object({
-    name: Type.String({ description: "The checkpoint or milestone name. Use meaningful names." }),
-    target: Type.Optional(Type.String({ description: "Optional history node ID or checkpoint name to label. Defaults to the current conversation position." })),
+    name: Type.String({ description: "Unique semantic anchor name that encodes the task and phase/purpose, e.g. parser-fix-start or timeout-investigation-search. Avoid generic names like start, checkpoint-1, or retry." }),
+    target: Type.Optional(Type.String({ description: "Optional history node ID or checkpoint name to label. Defaults to the current meaningful position near the conversation head." })),
 });
 
 export default function (pi: ExtensionAPI) {
@@ -69,15 +82,8 @@ export default function (pi: ExtensionAPI) {
         handler: async (args, ctx) => {
             CommandCtx = ctx;
             ctx.ui.notify("Agentic Context Management enabled.", "info");
-            pi.sendMessage({
-                customType: "pi-context",
-                content: "use context-management skill",
-                display: false,
-            }, {
-                deliverAs: "followUp"
-            });
             if (args) {
-                pi.sendUserMessage(args)
+                pi.sendUserMessage(args, { deliverAs: "followUp" });
             }
         }
     });
@@ -102,7 +108,7 @@ export default function (pi: ExtensionAPI) {
     pi.registerTool({
         name: "context_checkpoint",
         label: "Context Checkpoint",
-        description: "Create a named checkpoint in the conversation history. Use this before risky work, before a long research pass, or whenever you reach a stable milestone.",
+        description: ContextCheckpointDescription,
         parameters: ContextCheckpointParams,
         async execute(_id, params: Static<typeof ContextCheckpointParams>, _signal, _onUpdate, ctx) {
             const sm = ctx.sessionManager as SessionManager;
@@ -157,14 +163,20 @@ export default function (pi: ExtensionAPI) {
             }
 
             pi.setLabel(id, params.name);
-            return { content: [{ type: "text", text: `Created checkpoint '${params.name}' at ${id}` }], details: {} };
+            return {
+                content: [{
+                    type: "text",
+                    text: `Created checkpoint '${params.name}' at ${id}.`
+                }],
+                details: {}
+            };
         },
     });
 
     pi.registerTool({
         name: "context_timeline",
         label: "Context Timeline",
-        description: "Show the conversation timeline, checkpoints, summaries, and current position. Use this to understand session structure, monitor drift, and choose a checkpoint to return to.",
+        description: ContextTimelineDescription,
         parameters: ContextTimelineParams,
         async execute(_id, params: Static<typeof ContextTimelineParams>, _signal, _onUpdate, ctx) {
             const sm = ctx.sessionManager as SessionManager;
@@ -342,11 +354,7 @@ export default function (pi: ExtensionAPI) {
             }
 
             // --- Context Dashboard (HUD) ---
-            const usage = await ctx.getContextUsage();
-            let usageStr = "Unknown";
-            if (usage?.percent != null && usage.tokens != null && usage.contextWindow != null) {
-                usageStr = `${usage.percent.toFixed(1)}% (${formatTokens(usage.tokens)}/${formatTokens(usage.contextWindow)})`;
-            }
+            const usageStr = formatContextUsage(ctx.getContextUsage(), true);
 
             // Find the distance to the nearest checkpoint
             let stepsSinceCheckpoint = 0;
@@ -361,10 +369,15 @@ export default function (pi: ExtensionAPI) {
                 stepsSinceCheckpoint++;
             }
 
+            const compactCue = nearestCheckpointName === "None"
+                ? "create a checkpoint before the next noisy phase"
+                : `if this segment has produced a stable result and another phase remains, compact to '${nearestCheckpointName}' with a handoff summary before continuing`;
+
             const hud = [
                 `[Context Dashboard]`,
                 `• Context Usage:    ${usageStr}`,
                 `• Segment Size:     ${stepsSinceCheckpoint} steps since last checkpoint '${nearestCheckpointName}'`,
+                `• Compact Cue:      ${compactCue}`,
                 `---------------------------------------------------`
             ].join("\n");
 
@@ -373,11 +386,11 @@ export default function (pi: ExtensionAPI) {
     });
 
     pi.registerTool({
-        name: "context_rewind",
-        label: "Conversation Rewind",
-        description: "Return to an earlier conversation checkpoint and start a fresh continuation with a carryover summary. This changes session history only and does not modify disk files. Always provide a detailed message.",
-        parameters: ContextRewindParams,
-        async execute(_id, params: Static<typeof ContextRewindParams>, _signal, _onUpdate, ctx) {
+        name: "context_compact",
+        label: "Context Compact",
+        description: ContextCompactDescription,
+        parameters: ContextCompactParams,
+        async execute(_id, params: Static<typeof ContextCompactParams>, _signal, _onUpdate, ctx) {
             if (!CommandCtx) {
                 ctx.ui.setEditorText(`/acm ${ctx.ui.getEditorText() || "continue"}`)
                 return {
@@ -389,6 +402,7 @@ export default function (pi: ExtensionAPI) {
                 };
             }
             const sm = ctx.sessionManager as SessionManager;
+            const usageBeforeText = formatContextUsage(ctx.getContextUsage());
 
             const tid = resolveTargetId(sm, params.target);
 
@@ -402,46 +416,69 @@ export default function (pi: ExtensionAPI) {
             const currentLabel = currentLeaf ? sm.getLabel(currentLeaf) : undefined;
             const origin = currentLabel ? `checkpoint: ${currentLabel}` : (currentLeaf || "unknown");
 
-            const enrichedMessage = `(summary from ${origin})\n${params.message}`;
+            const enrichedMessage = `(handoff summary from ${origin})\n${params.summary}`;
 
             const nid = await sm.branchWithSummary(tid, enrichedMessage);
-            RewindParams = params;
-            RewindParams.nid = nid;
-            RewindParams.tid = tid;
-            RewindParams.enrichedMessage = enrichedMessage;
+            CompactParams = params;
+            CompactParams.nid = nid;
+            CompactParams.tid = tid;
+            CompactParams.enrichedMessage = enrichedMessage;
+            CompactParams.usageBeforeText = usageBeforeText;
 
-            return { content: [{ type: "text", text: "rewind start" }], details: {} };
+            return { content: [{ type: "text", text: "compact start" }], details: {} };
         },
     });
 
     pi.on("turn_end", async (_event, ctx) => {
-        if (!RewindParams) {
+        if (!CompactParams) {
             return
         }
         ctx.abort()
     });
 
-    pi.on("agent_end", async (_event, ctx) => {
-        if (!RewindParams) {
+    pi.on("agent_end", async () => {
+        if (!CompactParams) {
             return
         }
         if (!CommandCtx) {
             return
         }
 
-        await CommandCtx.navigateTree(RewindParams.nid, {
-            summarize: false,
-        });
-
-        ctx.ui.notify(`Rewound to ${RewindParams.target}${RewindParams.target === RewindParams.tid ? "" : `(${RewindParams.tid})`}\nBackup checkpoint created: ${RewindParams.backupCheckpoint || "none"}\nmessage: ${RewindParams.enrichedMessage}`, "info");
-        RewindParams = null;
+        const compactParams = CompactParams;
+        const commandCtx = CommandCtx;
+        CompactParams = null;
+
+        // `agent_end` is emitted before the core Agent is actually idle. If we
+        // call pi.sendMessage({ triggerTurn: true }) inside this handler, pi still
+        // sees an active stream and queues the message as steering; after
+        // `agent_end` the loop has already stopped, so that queued message is not
+        // drained. Defer navigation + continuation until the current run settles.
+        setTimeout(async () => {
+            try {
+                await commandCtx.waitForIdle();
+                await commandCtx.navigateTree(compactParams.nid, {
+                    summarize: false,
+                });
 
-        pi.sendMessage({
-            customType: "pi-context",
-            content: "context_rewind complete. A summary of your previous conversation path was injected above. Read it to understand your new state. Execute the 'Next Step' from the summary",
-            display: false,
-        }, {
-            triggerTurn: true,
-        });
+                const usageAfter = commandCtx.getContextUsage();
+                commandCtx.ui.notify([
+                    `Compacted to ${compactParams.target}${compactParams.target === compactParams.tid ? "" : `(${compactParams.tid})`}`,
+                    `Context Usage: ${compactParams.usageBeforeText} -> ${formatContextUsage(usageAfter)}`,
+                    `Backup checkpoint created: ${compactParams.backupCheckpoint || "none"}`,
+                    `Summary: ${compactParams.enrichedMessage}`,
+                ].join("\n"), "info");
+
+                pi.sendMessage({
+                    customType: "pi-context",
+                    content: "context_compact complete. A handoff summary of your previous conversation path was injected above. Read it to understand your new state. Execute the Next Step from the summary",
+                    display: false,
+                }, {
+                    triggerTurn: true,
+                    deliverAs: "followUp",
+                });
+            } catch (err) {
+                commandCtx.ui.notify(`context_compact failed to continue: ${err instanceof Error ? err.message : String(err)}`, "error");
+            }
+        }, 0);
     });
 }