pi-context 2.0.0 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-context",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Agentic Context Management for Pi",
   "files": [
     "src",
@@ -15,18 +15,19 @@
     "pi-package",
     "context-management",
     "context-optimization",
+    "context-compact",
     "time-travel",
     "checkpoint",
     "pi-skill"
   ],
   "type": "module",
-  "author": "",
+  "author": "ttttmr",
   "license": "MIT",
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.75.4",
-    "@earendil-works/pi-coding-agent": "^0.75.4",
-    "@earendil-works/pi-tui": "^0.75.4",
-    "typescript": "^5.7.2"
+    "@earendil-works/pi-ai": "^0.80.6",
+    "@earendil-works/pi-coding-agent": "^0.80.6",
+    "@earendil-works/pi-tui": "^0.80.6",
+    "typescript": "^5.9.3"
   },
   "pi": {
     "extensions": [

package/skills/context-management/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: context-management
-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.
+description: "Use this skill for multi-turn, phased, or noisy work: research/reading, debugging, plan-then-execute, retries/pivots, background or asynchronous work, handoffs, user decisions, task switching, repeated items, or repeated progress checks. It keeps the conversation as a clean working set with checkpoints, timeline review, and compaction at continuation boundaries. Always use when resuming after context compaction or when a long phase reaches a decision, handoff, validation, or task-switch boundary. Usually skip simple one-shot tasks."
 ---
 
 # Context Management
 
-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.
+Use this skill to keep the active conversation as a useful **working set** for the next step. Keep raw only the context that still needs direct reasoning; carry the rest as compact task state when that is more efficient.
 
 Core rhythm:
 
@@ -25,100 +25,95 @@ Before choosing a tool, ask:
 
 - 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?
+- What important data has a reliable external source I can re-check instead of carrying raw?
+- What history is useful only as a conclusion, pointer, or state update?
+- What history is process noise or stale baggage?
 
-Classify context into three forms:
+Classify context into:
 
-- **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.
+- **Raw context:** user intent, constraints, code/log/error details, evidence, or plan text you expect to inspect directly soon.
+- **State summary:** decisions, findings, lessons, changed files, validation status, source pointers, 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 gone.
 
 If the active context is already small, coherent, and directly useful for the next step, do not manage it just to be tidy.
 
 ## When to use
 
-Use this mode when the user is asking for work that may outgrow one clean thread:
+Use this mode when the work 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
-- multiple approaches, retries, failed branches, or pivots
+- background or asynchronous work, handoffs, user decisions, or delayed results
+- multiple approaches, retries, failed branches, comparisons, 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
+- repeated progress/status checks that indicate active state is hard to track
+- scattered threads that need cleanup before continuing
+- debugging, troubleshooting, refactoring, migration, or 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).
+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 provided enough task details, still checkpoint the workflow shape before asking clarifying questions.
 
-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.
+Usually skip this skill for one-shot reads, bounded summaries, direct rewrites, simple lookups, 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.
+- **Same task / next phase:** continue; if the previous phase is complete and noisy, compact before the next phase.
+- **Correction or follow-up:** usually answer from recent context; do not compact yet.
+- **New task or direction shift:** if the previous task left a complete noisy segment, inspect timeline when anchors are unclear, 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.
+Think of the tools as a phase pipeline: checkpoint marks anchors, work happens, timeline shows structure, and 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.
 
 ## 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.
+1. Before noisy work, create a semantic checkpoint as the first context-management action. 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.
 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.
+5. At continuation 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.
 6. After a successful compact, continue from the injected summary instead of dragging the full raw path forward.
 
+## Continuation boundaries
+
+A continuation boundary is a point where the current phase has produced a stable result and the next action will use that result to start a different phase. It is not necessarily the end of the user's whole task.
+
+Examples: investigation -> decision/plan/implementation, implementation -> validation, failed validation -> next approach, delayed result -> routing/action, user decision -> execution, rejected branch -> replacement direction, side request -> pause/summarize mainline before switching.
+
+Do not ask only "is the whole task done?" Ask "will the next action start a new phase using the stable result of this phase?" If yes, this is often a compaction boundary.
+
+Handoffs are not final answers: if a response transfers control to the user, another actor/process, later validation, or a queued phase, compact when the prior phase was noisy and the next action needs only stable state.
+
 ## 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:
+Read **one primary reference** only 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`
+- search / research / reading-heavy work -> `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`
+- task switching / pause-resume / interruptions / cleanup-and-continue -> `references/task-switching-and-cleanup.md`
+- interleaved async work / overlapping fronts / background results / user decisions -> `references/interleaved-async-work.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`.
+Also read `references/retry-branch-and-pivot.md` when multiple approaches, failed branches, comparisons, retries, or pivots become central.
 
 ## Tool policy
 
 ### `context_checkpoint`
 
-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:
-
-- `<task>-start`
-- `<task>-<phase>`
-- `<task>-<attempt>`
-- `<task>-<milestone>`
-
-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`.
+Use before noisy work, a new phase, a risky attempt, switching subtasks, or after a meaningful milestone. Use semantic names such as `<task>-start`, `<task>-<phase>`, `<task>-<attempt>`, or `<task>-<milestone>`. Avoid generic names like `start`, `checkpoint-1`, or `retry`.
 
 ### `context_timeline`
 
-Use it as the structural view of the active path, not only as a rescue tool:
+Use it as the structural view of the active path:
 
 - 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
+- before choosing a non-obvious compact target
 - 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?
+When reading the timeline, ask which raw messages are still needed for the immediate next action, which paths are now baggage, and which anchor gives the smallest sufficient working set after summary injection.
 
 ### `context_compact`
 
@@ -126,6 +121,16 @@ Use it to replace raw history with a state summary when the next phase would ben
 
 Typical compact boundaries: investigation -> execution, diagnosis -> fix, implementation -> validation, failed attempt -> next attempt, representative item -> remaining batch, completed noisy task -> new user task.
 
+Strong signals to consider compaction:
+
+- repeated progress/status checks
+- inability to summarize current state, next action, and open risks in one short paragraph
+- rejected, abandoned, or superseded branches
+- stable result after many tool calls or long output
+- returned background/asynchronous/delegated result
+- material plan or approach change
+- side question arriving while stale process history is active
+
 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.
 
 ## Compact gate
@@ -136,38 +141,25 @@ Before calling `context_compact`, require all three:
 2. You can restore the useful task state in a clear summary.
 3. There is an immediate continuation that benefits from cleaner context.
 
-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.
+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 visible structure rather than memory.
 
-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.
+If the whole task is done and only the final answer remains, wait. Compact later only if the next user message makes it useful.
 
-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.
+Checkpoint-only failure mode: a checkpoint is useful because it gives you a clean anchor to compact back to later. After any checkpointed phase produces a stable result, ask what the phase settled, whether the next step is different, and whether a summary can replace the raw trail. If yes, compact; do not keep accumulating raw history just because the overall task is still active.
 
 ## 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.
+2. Decide what must remain raw: active user intent, current constraints, still-open evidence/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, externally recoverable data, and clear process details.
 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:
+5. If an older anchor plus a stronger summary is cleaner than a recent anchor plus stale context, prefer the older anchor. When completed fronts fill the middle of the thread, it can be correct to compact to a much older anchor or even `root` if the summary restores the active front and source pointers.
 
-- 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
+Avoid targets that are too late, too early with a weak summary, or semantically wrong. If there are several checkpoints, a task switch, or uncertainty about the best working set, run `context_timeline` first.
 
-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.
+Use `backupCheckpoint` when raw history may still matter later. A backup is a recovery safety net, not a substitute for the summary.
 
 ## Compact summary contract
 
@@ -180,36 +172,34 @@ 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`.
+4. **Navigation state:** source anchors/evidence when needed, rejected leads worth avoiding, backup checkpoint guidance, and explicit next step.
 
-Good examples:
+If important data has a reliable external source, preserve the pointer and retrieval method rather than copying the raw data. Examples: file path and line/query, database table/query, task/job id, log path, URL, record id, branch/commit, or command to inspect status. Include raw values only when they are small, unstable, hard to retrieve, or needed for immediate reasoning.
 
-- `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.`
+For long-running work, shape the summary as a state capsule: goal, stable result, decisions, rejected paths, current artifacts/source pointers, active work, pending input, risks/open questions, and next action. Include why compacting is appropriate only when it helps future orientation. Avoid vague summaries like `Done`, `Investigated`, `Switching context`, or `Going back`.
 
-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?
+Before compacting, quickly check: stable state? real continuation? smallest sufficient working set? summary restores state after the anchor? externally recoverable data represented by pointers? 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. 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.
+1. Read the injected summary carefully and treat it as the new active state.
+2. Verify it contains enough state for the next action.
+3. Remember that disk and external systems were not rolled back; inspect current files/tools/services when state matters.
+4. If a missing detail is cheap to reconstruct from disk, tools, or source anchors, retrieve it directly.
+5. Return to the backup checkpoint only when the missing raw context cannot be reconstructed cheaply.
 
 ## Common mistakes
 
 Avoid:
 
 - checkpointing constantly without phase meaning
+- checkpointing early but never compacting after a stable phase result
 - 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
+- using an old anchor or `root` with a weak summary
 - compacting immediately after a final deliverable when no next user intent is known
 - carrying completed noisy phases into a new task
+- treating handoff or decision prompts as final answers when a continuation is expected
 - 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/interleaved-async-work.md

@@ -0,0 +1,143 @@
+# Interleaved Async Work
+
+Use this reference when the hard part is **not** the external worker itself, but the current agent carrying several overlapping lines of work in one conversation.
+
+Common examples:
+
+- a main task continues while background jobs, subagents, reviewers, or tools may return later
+- the user asks side questions while another front is still active
+- progress updates, returned results, decisions, and new work are interleaved in the same thread
+- several pending fronts have different next actions, and raw history starts making the current state hard to see
+
+This is context management for the current agent. It is not a subagent-management policy. The goal is to keep the current working set clear enough to answer: **what am I doing now, what is parked, what just returned, and what raw context is still needed?**
+
+## Mental model: fronts
+
+Treat each overlapping line of work as a **front**.
+
+A front may be:
+
+- the current user-facing task
+- a paused mainline task
+- a background command or long-running job
+- a subagent/reviewer/collaborator result that may return later
+- a pending user decision
+- a side request that should be answered before resuming the mainline
+
+For each front, keep only one of these in the active working set:
+
+- **Active raw front:** the thing you are reasoning about right now; keep necessary raw details.
+- **Parked state capsule:** a paused or waiting front summarized by goal, current state, source pointers, next action, and blockers.
+- **Stale process:** old logs, retries, status chatter, and abandoned paths whose lesson has already been captured.
+
+The mistake to avoid is carrying every front raw at once.
+
+## Working pattern
+
+1. Identify the active front before each substantial reply or tool call.
+2. If another front is still pending, keep it as a small state capsule rather than raw history.
+3. When a result returns, capture it into the relevant front before responding.
+4. If the returned result does not become the active front immediately, park it as state and preserve the user's current focus.
+5. Before switching fronts, compact if the old front's raw process is now stale and the next front can continue from a summary.
+6. If several fronts are tangled, run `context_timeline` to find the clean anchor and separate active, parked, completed, and stale paths.
+
+## What to record per parked front
+
+Use a short capsule:
+
+- Front: short name for this line of work
+- Goal: what this front is trying to accomplish
+- State: waiting / running / returned / blocked / ready for next phase
+- Latest stable result: what is known now
+- Source pointers: files, links, task ids, log paths, branches, records, queries, or commands that identify where to re-check details
+- Decisions and constraints: choices already made that still matter
+- Rejected paths: approaches that should not be repeated
+- Pending input or trigger: what would make this front active again
+- Next action: what to do when resuming this front
+
+This capsule is for future-you, not for the external worker. It should be enough to resume without rereading the interleaved raw thread.
+
+If a front's detailed state is available from a reliable external source, keep the pointer, not the dump. For example, store the task id plus the command/log path to inspect it, not pages of status output; store the database query or record id, not every row; store the file path and relevant section, not the whole file. Copy raw details only when they are small, volatile, hard to retrieve, or needed for immediate reasoning.
+
+## When to compact
+
+Compact when interleaving has made raw context a worse working set:
+
+- you are switching from one front to another after a noisy phase
+- a side request arrives while the mainline is noisy but resumable from a capsule
+- a background/subagent/reviewer/tool result returned and its raw logs are no longer needed
+- the user has asked for status more than once and you cannot state all active fronts briefly
+- a front was rejected, superseded, completed, or parked indefinitely
+- the next action belongs to a different front than the recent raw history
+- the active front started much earlier, and the middle of the thread is mostly completed or unrelated fronts
+
+Do **not** compact just because async work exists. Compact when a front can safely be represented as state while another front becomes active.
+
+## Choosing how far back to compact
+
+Interleaved work often makes recent anchors poor targets: they may preserve the completed fronts that happened after the active front was launched. Be willing to compact aggressively when the summary can restore state.
+
+A compact to an old anchor or even `root` is appropriate when:
+
+- the active front can be described by a concise capsule
+- completed fronts between the anchor and now no longer need raw context
+- important details are recoverable from reliable source pointers
+- the next action does not require inspecting the interleaved raw discussion
+- you can name what remains active, what is parked, and what is done
+
+Use a backup checkpoint for safety when the interleaved raw path may still matter, but do not keep it active just because it is long.
+
+Before a deep compact, ask:
+
+```text
+Active now: which front am I resuming?
+Parked: which fronts still wait for input/result?
+Done: which fronts can be summarized or omitted?
+Pointers: where can I re-check authoritative details?
+Next: what is the immediate action after compacting?
+```
+
+## Handling returned results
+
+When a delayed result appears in the middle of another thread:
+
+1. **Capture:** identify which front it belongs to and summarize its result.
+2. **Classify:** progress, stable completion, failure, decision needed, or noise.
+3. **Choose focus:** decide whether this result should interrupt the current active front. If not, park it.
+4. **Compact if needed:** if switching to it or away from it would drag stale logs/retries forward, compact first.
+5. **Continue:** resume the chosen active front from a clean working set.
+
+## Example capsules
+
+```text
+Front: import-test-flake
+Goal: fix flaky import tests.
+State: reviewer returned findings.
+Latest stable result: fixed sleeps were rejected; signed retry strategy is still viable.
+Source pointers: branch retry-import-tests, log tmp/import-flake.log.
+Pending input or trigger: decide whether to implement bounded retries.
+Next action: if accepted, implement bounded retry and rerun targeted tests.
+```
+
+```text
+Front: docs-build
+Goal: validate generated documentation before publishing.
+State: background build running.
+Latest stable result: source edits complete; validation not yet known.
+Source pointers: task docs-build, output dist/docs/.
+Pending input or trigger: build exit status.
+Next action: on success, summarize validation; on failure, inspect first build/link error.
+```
+
+## Common mistakes
+
+Avoid:
+
+- treating async/subagent management as the goal instead of keeping the current agent's working set clear
+- carrying several fronts raw at once
+- copying externally recoverable status dumps instead of preserving reliable source pointers
+- letting a returned result overwrite the user's current active request without deciding focus
+- reporting status repeatedly while the real problem is that fronts are not summarized
+- compacting away a front without preserving how to resume it
+- avoiding a deep compact even though source pointers and capsules can restore the active state
+- resuming from memory when a small front capsule would be safer

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

@@ -33,6 +33,14 @@ Compact when:
 - the direction changed enough that the old path is now baggage
 - the next attempt should start from a focused state rather than the raw failed branch
 
+When compacting after an abandoned branch, preserve:
+
+- what was tried
+- why it failed or was rejected
+- what should not be repeated
+- what remains valid
+- the chosen next approach
+
 ## Strategy pivot
 
 Use this pattern when the old direction no longer makes sense even though the task is still continuing.
@@ -56,7 +64,7 @@ context_checkpoint({ name: "oauth-fix-start" });
 
 context_compact({
   target: "oauth-fix-start",
-  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.",
+  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. Rejected path: do not repeat cookie-based continuity for this flow. Still valid: callback validation and provider config findings. 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 +75,6 @@ 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
+- omitting the rejected path, failure reason, or chosen replacement from the compact summary
 - 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/task-switching-and-cleanup.md

@@ -27,9 +27,10 @@ Use when the thread is already stale or messy and you want to compress it now, e
 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. 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.
+5. If the user asks a concrete side question while noisy mainline work is active, pause or summarize the active work, compact if the raw mainline history is no longer needed for the side question, answer the side question, and preserve how to resume the paused work.
+6. Handle the side task or cleanup move.
+7. Compact away the stale path when the handoff summary is clear.
+8. Resume from the paused anchor or continue from the compacted state.
 
 ## Useful anchors
 

package/src/index.ts

@@ -22,6 +22,8 @@ interface SessionTreeNode {
 }
 
 const InternalTools = ["context_checkpoint", "context_timeline", "context_compact"];
+const PiContextCustomMessageType = "pi-context";
+const AcmEnableFollowUp = "Agentic context management is now enabled";
 let CommandCtx: ExtensionCommandContext | null = null;
 let CompactParams: any = null;
 
@@ -392,7 +394,11 @@ export default function (pi: ExtensionAPI) {
         parameters: ContextCompactParams,
         async execute(_id, params: Static<typeof ContextCompactParams>, _signal, _onUpdate, ctx) {
             if (!CommandCtx) {
-                ctx.ui.setEditorText(`/acm ${ctx.ui.getEditorText() || "continue"}`)
+                const editorText = ctx.ui.getEditorText();
+                const followUp = editorText
+                    ? `${AcmEnableFollowUp}\n${editorText}`
+                    : AcmEnableFollowUp;
+                ctx.ui.setEditorText(`/acm ${followUp}`)
                 return {
                     content: [{
                         type: "text",
@@ -418,9 +424,7 @@ export default function (pi: ExtensionAPI) {
 
             const enrichedMessage = `(handoff summary from ${origin})\n${params.summary}`;
 
-            const nid = await sm.branchWithSummary(tid, enrichedMessage);
             CompactParams = params;
-            CompactParams.nid = nid;
             CompactParams.tid = tid;
             CompactParams.enrichedMessage = enrichedMessage;
             CompactParams.usageBeforeText = usageBeforeText;
@@ -436,7 +440,7 @@ export default function (pi: ExtensionAPI) {
         ctx.abort()
     });
 
-    pi.on("agent_end", async () => {
+    pi.on("agent_end", async (_event, ctx) => {
         if (!CompactParams) {
             return
         }
@@ -444,9 +448,11 @@ export default function (pi: ExtensionAPI) {
             return
         }
 
+        const sm = ctx.sessionManager as SessionManager;
         const compactParams = CompactParams;
         const commandCtx = CommandCtx;
         CompactParams = null;
+        const compactTurnLeaf = sm.getLeafId();
 
         // `agent_end` is emitted before the core Agent is actually idle. If we
         // call pi.sendMessage({ triggerTurn: true }) inside this handler, pi still
@@ -456,6 +462,30 @@ export default function (pi: ExtensionAPI) {
         setTimeout(async () => {
             try {
                 await commandCtx.waitForIdle();
+
+                const currentLeaf = sm.getLeafId();
+                if (currentLeaf !== compactTurnLeaf) {
+                    commandCtx.ui.notify("context_compact cancelled: conversation advanced before compaction completed.", "warning");
+                    pi.sendMessage({
+                        customType: PiContextCustomMessageType,
+                        content: [
+                            "context_compact cancelled: conversation advanced before the summary branch was created.",
+                            "No compaction was applied; continue from the current path. If still useful, inspect timeline and retry with an updated summary.",
+                        ].join("\n"),
+                        display: false,
+                    }, {
+                        triggerTurn: true,
+                        deliverAs: "followUp",
+                    });
+                    return;
+                }
+
+                const nid = sm.branchWithSummary(compactParams.tid, compactParams.enrichedMessage);
+                compactParams.nid = nid;
+                // branchWithSummary advances the leaf to the summary entry. Reset
+                // it so navigateTree(nid) can rebuild agent state instead of
+                // returning early as a no-op.
+                sm.branch(compactParams.tid);
                 await commandCtx.navigateTree(compactParams.nid, {
                     summarize: false,
                 });
@@ -469,7 +499,7 @@ export default function (pi: ExtensionAPI) {
                 ].join("\n"), "info");
 
                 pi.sendMessage({
-                    customType: "pi-context",
+                    customType: PiContextCustomMessageType,
                     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,
                 }, {
@@ -477,7 +507,19 @@ export default function (pi: ExtensionAPI) {
                     deliverAs: "followUp",
                 });
             } catch (err) {
-                commandCtx.ui.notify(`context_compact failed to continue: ${err instanceof Error ? err.message : String(err)}`, "error");
+                const message = err instanceof Error ? err.message : String(err);
+                commandCtx.ui.notify(`context_compact failed: ${message}`, "error");
+                pi.sendMessage({
+                    customType: PiContextCustomMessageType,
+                    content: [
+                        `context_compact failed: ${message}`,
+                        "No compaction was applied; continue from the current path. Retry only with a fresh timeline/summary.",
+                    ].join("\n"),
+                    display: false,
+                }, {
+                    triggerTurn: true,
+                    deliverAs: "followUp",
+                });
             }
         }, 0);
     });