@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/btw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/btw",
-  "version": "3.0.0-alpha.2",
+  "version": "3.0.0-alpha.21",
   "description": "A pi extension for parallel side conversations with /unipi:btw — part of the Unipi suite",
   "type": "module",
   "main": "extensions/btw.ts",
@@ -37,7 +37,7 @@
     "@earendil-works/pi-tui": "^0.87.1"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.2"
+    "@pi-unipi/core": "3.0.0-alpha.21"
   },
   "pi": {
     "extensions": [
@@ -48,5 +48,8 @@
     ],
     "prompts": [],
     "themes": []
+  },
+  "scripts": {
+    "test": "npx tsx --test tests/*.test.ts"
   }
 }

package/packages/btw/skills/btw/SKILL.md

@@ -1,151 +1,15 @@
 ---
 name: btw
-description: Helps you use the /unipi:btw side-conversation workflow effectively. Use when you want to think in parallel, ask side questions without interrupting ongoing work, or inject a side thread back into the main agent.
+description: Ask side questions in an inline panel without interrupting the main agent — read-only, one-shot, invisible to the main session.
 ---
 
 # BTW
 
-Use this skill when the user wants to work in parallel with the main agent instead of derailing the current turn.
+`/unipi:btw <question>` opens an inline panel and answers a side question from a fresh read-only session seeded with the main session's current context.
 
-BTW side sessions are read-only: they can read and search files with `read`, `grep`, `find`, and `ls`, but cannot run commands or modify files. Send requested changes to the main session with `/unipi:btw-inject` or `/unipi:btw-summarize`.
+Rules the panel enforces:
+- Read-only tools (`read`, `grep`, `find`, `ls`) — no commands or edits; changes belong in the main conversation.
+- No memory between btw questions, and nothing reaches the main agent.
+- Nothing is persisted — page history dies with the pi session.
 
-## When to use BTW
-
-Prefer the BTW workflow when the user wants to:
-
-- ask a side question while the main agent keeps working
-- brainstorm or compare options without interrupting the current run
-- prepare a plan or summary before handing it back to the main agent
-- keep exploratory discussion out of the main transcript/context
-
-## Commands
-
-Use these commands in your guidance to the user:
-
-```text
-/unipi:btw <question>
-/unipi:btw --save <question>
-/unipi:btw-new [question]
-/unipi:btw-tangent <question>
-/unipi:btw-tangent --save <question>
-/unipi:btw-clear
-/unipi:btw-inject [instructions]
-/unipi:btw-summarize [instructions]
-```
-
-## How to guide the user
-
-### For a quick side question
-
-Recommend:
-
-```text
-/unipi:btw <question>
-```
-
-Use this when the user wants an immediate aside and does not need a visible saved note.
-
-### For a saved one-off note
-
-Recommend:
-
-```text
-/unipi:btw --save <question>
-```
-
-Use this when the user wants the exchange to appear as a visible BTW note in the session transcript.
-
-### For a fresh side thread
-
-Recommend:
-
-```text
-/unipi:btw-new
-```
-
-or
-
-```text
-/unipi:btw-new <question>
-```
-
-Use this when the previous BTW discussion is no longer relevant, but you still want the new side thread to inherit the current main-session context.
-
-### For a contextless tangent thread
-
-Recommend:
-
-```text
-/unipi:btw-tangent <question>
-```
-
-or
-
-```text
-/unipi:btw-tangent --save <question>
-```
-
-Use this when the user wants a side conversation that does not include the current main-session context.
-
-### To hand the full thread back to the main agent
-
-Recommend:
-
-```text
-/unipi:btw-inject <instructions>
-```
-
-Use this when the exact discussion matters and the user wants the main agent to act on it.
-
-### To hand back a condensed version
-
-Recommend:
-
-```text
-/unipi:btw-summarize <instructions>
-```
-
-Use this when the thread is long and only the distilled outcome should go back into the main agent.
-
-## Recommendation rules
-
-- Prefer `/unipi:btw` over normal chat when the user explicitly wants a side conversation.
-- Prefer `/unipi:btw-tangent` when the user wants that side conversation to be contextless.
-- Prefer `/unipi:btw-summarize` over `/unipi:btw-inject` for long exploratory threads.
-- Prefer `/unipi:btw-inject` when precise wording, detailed tradeoffs, or a full plan matters.
-- Suggest `/unipi:btw-new` before starting a totally unrelated side topic when main-session context is still useful.
-- Suggest `/unipi:btw-clear` when the widget/thread should be dismissed.
-
-## Response style
-
-When helping the user use BTW:
-
-- give the exact slash command to run
-- explain briefly why that command fits
-- keep the guidance short and operational
-
-## Examples
-
-### Example: brainstorm while coding continues
-
-```text
-/unipi:btw what are the risks of switching this to optimistic updates?
-```
-
-### Example: create a clean new thread
-
-```text
-/unipi:btw-new sketch a safer migration plan
-```
-
-### Example: start a contextless tangent
-
-```text
-/unipi:btw-tangent think through this from first principles without using the current chat context
-```
-
-### Example: send the result back
-
-```text
-/unipi:btw-summarize implement the recommended migration plan
-```
+When to suggest it: quick clarifications, "what is X doing" checks, reading files, thinking out loud — anything that shouldn't derail or pollute the main turn.

package/packages/compactor/README.md

@@ -1,318 +1,87 @@
 # @pi-unipi/compactor
 
-Deterministic context management for Pi/UniPi. The compactor keeps long coding sessions usable by replacing large conversation history with a structured, zero-LLM summary, while preserving session recall, continuity snapshots, stats, sandbox helpers, and safer tool display.
+Compaction for Pi that keeps work going. When the context fills up, the compactor replaces older messages with a summary. The full history stays in the session file, so nothing is lost and anything can be recalled.
 
-## What it does
+## Methods
 
-- **Zero-LLM compaction:** Pi asks for compaction; UniPi builds the summary locally instead of spending model tokens on a summarization call.
-- **Session continuity:** important goals, changed files, commits, blockers, preferences, and a recent transcript survive compaction.
-- **Optional percentage trigger:** UniPi can compact at a configured context percentage before Pi's fixed reserve-token safety net fires.
-- **Recall:** agents can search the append-only session branch, including messages that no longer fit in live LLM context.
-- **Runtime helpers:** sandbox execution, context budget checks, diagnostics, and stats.
-- **Display guards:** tool output/diff rendering is clamped and summarized to avoid noisy or terminal-breaking output.
-
-The compaction pipeline is deterministic and runs locally. It does not call an LLM during compaction.
-
----
-
-## Quick start
-
-```text
-/unipi:settings (Compactor)
-```
-
-1. Choose a preset in **Presets**.
-2. Optionally enable **Auto → Percentage Trigger**.
-3. Press **Enter** to save.
-4. Use `/unipi:lossless-compact` when you want to compact immediately.
-
-Config files:
-
-| Scope | Path | Notes |
-|---|---|---|
-| Global | `~/.unipi/config/compactor/config.json` | Used by default |
-| Per project | `<project>/.unipi/config/compactor.json` | Enabled from settings with **Project Override** |
-
-Per-project config is merged over global config when the current project directory is known.
-
----
-
-## User-facing slash commands
-
-| Command | What it does | Notes |
+| Method | What it does | Cost |
 |---|---|---|
-| `/unipi:lossless-compact` | Immediately calls Pi compaction with UniPi's zero-LLM sentinel. | Main manual compaction command. |
-| `/unipi:compact` | Deprecated alias for `/unipi:lossless-compact`. | Kept for backward compatibility. |
-| `/unipi:session-recall <query>` | Searches current session history with BM25/regex recall. | Uses the append-only session branch when available, so pre-compaction messages can still be found. |
-| `/unipi:compact-recall <query>` | Deprecated alias for `/unipi:session-recall`. | Kept for backward compatibility. |
-| `/unipi:compact-stats` | Shows session events, compaction count, token savings, sandbox runs, and search counts. | Stats are DB-backed with runtime fallbacks. |
-| `/unipi:compact-doctor` | Runs diagnostics for config, SQLite/session DB, and runtimes. | Useful when stats/recall/sandbox look broken. |
-| `/unipi:settings (Compactor)` | Opens the TUI settings overlay. | Tabs: Presets, Strategies, Auto, Pipeline. |
-| `/unipi:settings (Compactor › Presets) <name>` | Applies a preset globally. | Names: `precise`, `balanced`, `thorough`, `lean`. Old names map to new ones: `opencode→precise`, `verbose→thorough`, `minimal→lean`. |
-| `/unipi:compact-help` | Shows compact help inside Pi. | Quick command reference. |
+| **Lossless** (default) | Builds a structured summary without a model call, in milliseconds. | Free |
+| **Model summary** | Pi's own model-written summary, with the active-work block added on top. | One model call |
 
-Content/project indexing is not part of this package. Use `read`/`bash` (rg) for project search.
+### The lossless summary
 
----
+It is rebuilt from the **full** session history on every compaction, never merged onto the previous summary, so it cannot drift or grow over time. Sections, in the order a resuming model needs them:
 
-## User-facing settings
+1. **Active Work**: the goal, ralph loop or kanboard task in flight, supplied by those modules from their own state.
+2. **Your Requests**: the user's own messages and answers to agent questions (`ask_user`: "question → answer"). Text that extensions send with the user role (loop prompts, nudges, notifications) is excluded.
+3. **Latest State**: the most recent step and the last full progress report.
+4. **Decisions & Constraints**: the user's instructions ("keep the orange theme"), corrections ("I did not ask for this"), and answers to agent questions. Half the room goes to the most recent ones, the rest to standing rules from anywhere in the session ("always…", "never…", "by default…"). Bug reports, pasted text and code blocks are left out.
+5. **Files**: modified, created and read files, as relative paths.
+6. **Project Knowledge**: what the agent learned that no message states: project notes it wrote or read (SKILL.md, AGENTS.md, DESIGN.md, docs), build/test/deploy commands it ran more than once, and the hosts it worked against. Switched with the Files section.
+7. **Commits**: hash and subject.
+8. **Open Errors**: recent failures that were not followed by a success.
+9. **Recent Transcript**: a ranked slice of recent work.
 
-Open settings with `/unipi:settings (Compactor)`.
+Each section has its own share of a hard budget (auto: 1.5k–4k tokens, scaling with session size). Credentials (typed passwords, API keys, bearer tokens) are redacted before anything is clipped; `session_recall` still has them. A closing line points the model to `session_recall`.
 
-Keyboard:
+## In the TUI
 
-| Key | Action |
-|---|---|
-| `Tab` | Switch tabs |
-| `↑/↓` | Move selection |
-| `Space` | Cycle/toggle selected value |
-| `/` | Search inside the Strategies tab |
-| `Enter` | Save and close |
-| `Esc` | Cancel |
-
-### Presets tab
-
-Presets are profiles that set strategies, the implemented Auto Injection pipeline behavior, and sandbox mode.
-
-| Preset | Intended use | Important effects |
-|---|---|---|
-| `precise` | Code-heavy work, minimal waste | Full compaction sections, sandbox enabled, Auto Injection off. |
-| `balanced` | Daily/default profile | Compact transcript, sandbox enabled, Auto Injection on. |
-| `thorough` | Debug/audit sessions | Full transcript, sandbox enabled, Auto Injection on. |
-| `lean` | Quick fixes or short sessions | Brief/minimal compaction sections, no sandbox, no session continuity, Auto Injection off. |
+- **Compaction card:** one line under Pi's own `[compaction]` block, e.g. `▌ Compacted 7.9k → 2.2k tokens · lossless · at 3%`. ctrl+o expands it: method, trigger, what was kept verbatim, summary sections. It is a custom entry: shown, never sent to the model.
+- **Footer strip** (under the input): `5 compactions · 47k→15k · just now`, hidden until the first compaction. With the glance frame off, the `compactions` segment shows the same (`cmp 5× 47k→15k · 1m`).
+- **Info screen** (`/unipi:info` → Compactor): method and trigger settings, compactions by method, tokens before → after, the last compaction.
 
-The **Project Override** row controls where settings are saved:
+## When it compacts
 
-- `disabled` → save global config.
-- `enabled` → save `<project>/.unipi/config/compactor.json` for only this project.
+- **Pi's context limit** (default): Pi decides when, using its own compaction settings (`compaction.reserveTokens`, per-model overrides). The compactor decides what the summary contains. Pi continues the run after compacting.
+- **At a percentage**: compacts once context use reaches the set percentage. This happens at a turn boundary, so running goal, ralph and kanboard loops are not interrupted.
 
-### Strategies tab
+## Settings
 
-These settings control what is extracted into compaction summaries or how related compactor features behave.
+`/unipi:settings → Compactor`
 
-| Setting | Values | Meaning |
+| Setting | Default | |
 |---|---|---|
-| `Verbose Debug` | `on`, `off` | Enables internal debug state. Console debug output is intentionally muted to avoid TUI rendering issues. |
-| `Session Goals` | `full`, `brief`, `off` | Extracts the user's active goals/request history into `[Session Goal]`. |
-| `Files & Changes` | `all`, `modified-only`, `off` | Tracks read, created, edited, and written files in `[Files And Changes]`. |
-| `Commits` | `full`, `brief`, `off` | Captures git commit hashes/messages detected in the conversation. |
-| `Outstanding Context` | `full`, `critical-only`, `off` | Keeps blockers, TODOs, pending decisions, and follow-ups. |
-| `User Preferences` | `all`, `recent-only`, `off` | Preserves user preferences learned during the session. |
-| `Brief Transcript` | `full`, `compact`, `minimal`, `off` | Keeps a rolling recent transcript after the structured sections. |
-| `Session Continuity` | `full`, `off` | Controls XML-style resume snapshots. Off prevents snapshot creation and injection; Pi’s normal compaction summary still remains. |
-| `Sandbox Execution` | `all`, `off` | Controls sandbox tool registration. Changes require a session reload. Allowed languages and output limit are enforced from config. |
-
-Config-only legacy field: `fts5Index` remains in the schema for compatibility. It is hidden from Compactor settings and presets. Legacy `sessionContinuity.mode: "essential-only"`, `eventCategories`, and `sandboxExecution.mode: "safe-only"` values remain loadable; essential-only behaves as full and safe-only behaves as enabled/all until explicit filtering/security policies are designed. Legacy `toolDisplay` and `showTruncationHints` fields also remain loadable but are deprecated and ignored; their profile names were never mapped to runtime renderer modes. Narrow-terminal diff clamping remains active as independent safety behavior.
-
-### Auto tab
-
-These settings control UniPi-managed percentage auto-compaction. They are separate from Pi core's own `compaction.reserveTokens` behavior.
-
-**Prefix-cache policy:** every compaction replaces provider-visible history and starts a new cache epoch. UniPi therefore keeps this second percentage trigger **off by default** and does not compact repeatedly merely to shorten a cache-hit request. Pi core remains the default safety trigger: with its documented defaults it compacts when estimated context exceeds `contextWindow - 16,384` reserved response tokens, while keeping about 20,000 recent tokens. If you deliberately enable the UniPi percentage trigger, 80% is an earlier explicit boundary and the cooldown/growth guards prevent loops. UniPi's compiler is deterministic and zero-LLM; it does not issue a second summarizer request.
-
-| Setting | Default | Meaning |
-|---|---:|---|
-| `Percentage Trigger` | `off` | When on, UniPi checks context usage at `agent_end` (after the agent run settles) and can call compaction when the threshold is reached. Disabled by default for backward compatibility. |
-| `Threshold` | `80%` | Trigger point using Pi's live `ctx.getContextUsage().percent`. |
-| `Cooldown` | `60s` | Minimum time between UniPi-triggered compaction attempts. Prevents loops. |
-| `Repeat Growth` | `4k` | If usage is still above threshold after compaction, require this many new tokens before triggering again. |
-| `Notifications` | `on` | Shows user-visible notifications for UniPi-triggered compaction attempts/results. |
-
-Example config:
-
-```json
-{
-  "autoCompaction": {
-    "enabled": true,
-    "thresholdPercent": 80,
-    "cooldownMs": 60000,
-    "repeatMinGrowthTokens": 4000,
-    "notify": true
-  }
-}
-```
-
-### Pipeline tab
-
-The Pipeline tab exposes only behavior implemented by the current runtime.
-
-| Setting | Preset behavior | Current effect |
-|---|---|---|
-| `Auto Injection` | On in `balanced`, `thorough`; off in `precise`, `lean` | Adds behavioral/session state to the one-shot resume context after compaction. |
-
-Deprecated config-only compatibility fields are still accepted so existing files load without migration failures, but they are ignored and no longer controlled or advertised by presets: `ttlCache`, `mmapPragma`, `proximityReranking`, `timelineSort`, and `progressiveThrottling`.
-
-Other config-only pipeline field:
-
-| Field | Meaning |
-|---|---|
-| `customNoisePatterns` | Extra regex/string patterns used by session recall filtering to remove noisy user blocks. |
-
----
+| Method | lossless | lossless · model summary |
+| Pi's /compact | same as Method | What Pi's built-in `/compact` does |
+| When | Pi's context limit | Or: at a percentage |
+| Percentage | 80 | Used when When = at a percentage |
+| Notifications | on | The compaction card after automatic compactions (commands always show it); failures still notify |
 
-## What the agent gets
+**Advanced compaction** (collapsed): smart keep tail, summary budget, per-section toggles, percentage cooldown and repeat growth, extra instructions for model summaries, debug output.
 
-### Agent tools
+Configs from before the rework are translated automatically: `overrideDefaultCompaction: false` becomes Method = model summary, and `autoCompaction.enabled` becomes When = at a percentage.
 
-The extension registers tools during `session_start` after the session DB is initialized.
+## Commands
 
-| Tool | Purpose |
+| Command | |
 |---|---|
-| `compact` | Agent-facing compaction request; supports `dryRun: true` preview. Slash command `/unipi:lossless-compact` is the user-facing immediate compaction path. |
-| `session_recall` | Search current session history with BM25 or regex. Defaults to 10 hits, hard-caps pages at 50, and caps expanded hit text at 16 KiB. |
-| `vcc_recall` | Deprecated alias for `session_recall`. |
-| `sandbox` | Run code in a sandboxed environment. Languages: JavaScript, TypeScript, Python, shell, Ruby, Go, Rust, PHP, Perl, R, Elixir. |
-| `sandbox_file` | Execute a file with its content injected as `FILE_CONTENT`. |
-| `sandbox_batch` | Run multiple sandbox execution items in one atomic response. |
-| `ctx_execute` | Deprecated alias for `sandbox`. |
-| `ctx_execute_file` | Deprecated alias for `sandbox_file`. |
-| `ctx_batch_execute` | Deprecated alias for `sandbox_batch`. |
-| `compactor_stats` | Agent-readable stats dashboard. |
-| `ctx_stats` | Deprecated alias for `compactor_stats`. |
-| `compactor_doctor` | Agent-readable diagnostics. |
-| `ctx_doctor` | Deprecated alias for `compactor_doctor`. |
-| `context_budget` | Uses live Pi context usage when available and returns compaction guidance. |
+| `/unipi:compact-vcc [keep:N]` | Lossless compaction now; `keep:N` keeps the last N user turns |
+| `/unipi:compact-by-llm [focus]` | Model-summary compaction now; optional text focuses the summary |
+| `/unipi:session-recall <query>` | Search the full session history (`scope:all`, `page:N`) |
+| `/unipi:compact-stats` | This session's compactions and savings |
+| `/unipi:compact-doctor` | Check settings, Pi's compaction switch, leftovers |
+| `/unipi:compact-help` | Command summary |
 
-### Agent skills
+Removed: `/unipi:compact` and `/unipi:lossless-compact` (use `/unipi:compact-vcc`), `/unipi:compact-recall` (use `/unipi:session-recall`), `/unipi:compact-jev` and the jev method (a saved `method: "jev"` behaves as lossless).
 
-| Skill | Purpose |
-|---|---|
-| `compactor` | Small always-loadable routing skill: when to compact, recall, check budget, or use sandbox. |
-| `compactor-detail` | On-demand full tool reference and workflow guidance. |
-| `compactor-stats` | Help interpreting compactor stats. |
-| `compactor-doctor` | Help diagnosing config/DB/runtime issues. |
-
----
-
-## How the system works
-
-### Chronological hook flow
-
-Typical session order:
-
-1. **Extension load**
-   - Registers compaction hooks immediately with lazy dependencies.
-   - Creates in-memory runtime counters/state.
-
-2. **`session_start`**
-   - Scaffolds config if needed.
-   - Initializes `SessionDB` and sandbox executor.
-   - Computes the current session ID, including worktree suffix.
-   - Registers agent tools and slash commands.
-   - Registers the info-screen Compactor group.
-   - Emits UniPi `MODULE_READY`.
-
-3. **`before_agent_start`**
-   - Reloads config for the active project.
-   - Applies runtime `autoDetect` behavior, such as disabling commit extraction outside git repos.
-   - Rebuilds cached recall blocks from Pi's append-only session branch.
-   - If a resume snapshot exists from a prior compaction, injects it into session context and marks it consumed.
-
-4. **`input`**
-   - Performs advisory security checks for shell/network/file patterns.
-   - Can block some known-dangerous network shell commands.
-
-5. **Tool execution → `tool_result`**
-   - Extracts file/change/search/sandbox events into the session DB.
-   - Updates runtime byte/tool counters.
-   - Applies display overrides and width-safe diff clamping before output reaches the TUI.
-
-6. **`agent_end`**
-   - If percentage auto-compaction is enabled, reads `ctx.getContextUsage()`.
-   - Runs cooldown/repeat-growth safeguards.
-   - Calls `ctx.compact({ customInstructions: COMPACTOR_INSTRUCTION })` when eligible.
-   - Fires only after the agent run settles: `ctx.compact()` aborts any active operation first, so triggering mid-run (e.g. at `turn_end`) would kill the next provider request.
-
-7. **Pi decides to compact**
-   - This can be from `/unipi:lossless-compact`, UniPi percentage auto-compaction, or Pi core's reserve-token fallback.
-
-8. **`session_before_compact`**
-   - Pi provides `preparation`, `branchEntries`, and optional custom instructions.
-   - If compactor should handle it, UniPi:
-     1. chooses the safe cut point (`buildOwnCut`),
-     2. converts messages to LLM-like input,
-     3. runs the zero-LLM compile pipeline,
-     4. persists stats/snapshots,
-     5. returns `{ compaction: { summary, details, tokensBefore, firstKeptEntryId } }` to Pi.
-
-9. **`session_compact`**
-   - Pi commits the compaction entry.
-   - UniPi increments compaction counters and persists token/character savings.
-
-10. **Next `before_agent_start` after compaction**
-    - UniPi injects the resume snapshot so the agent gets continuity without needing the full old transcript in context.
-
-11. **`session_shutdown`**
-    - Cleans old sessions.
-    - Cleans sandbox/background processes.
-    - Closes DB handles.
-
-### Zero-LLM compile pipeline
-
-When UniPi handles `session_before_compact`, it transforms old messages through these deterministic stages:
+## Tools
 
-1. **Normalize** — flatten user/assistant/tool/thinking messages into normalized blocks.
-2. **Filter** — remove noise and apply `customNoisePatterns`.
-3. **Build sections** — extract goals, files, commits, outstanding context, preferences, and transcript entries.
-4. **Brief** — cap and condense transcript lines.
-5. **Format** — emit a structured markdown summary.
-6. **Merge** — merge with the previous summary when Pi provides one.
+- `session_recall`: keyword/regex search over the session branch, including compacted-away messages. `expand` returns full entries by index (the `#N` refs in summaries); `mode: "touched"` lists files.
+- `context_budget`: how full the context is.
 
-The resulting summary is optimized for continuity, not for perfect archival fidelity. Use `session_recall` when the agent needs details from the raw session branch. Recall is deliberately paginated: request another offset page or narrow the query instead of injecting an unbounded result set. Even with `expand: true`, each hit is capped at 16 KiB to prevent a single historical message or tool result from dominating future cold-cache requests.
+## For other modules
 
----
+Register an active-work provider so summaries lead with your state:
 
-## Benchmarks
-
-Synthetic compile-only benchmark, run on this repository with Node 24 using `compile()` directly. Token counts use the common `chars / 4` estimate. Real compaction also keeps a recent live tail, so final live-context size can be larger than the summary-only number below.
-
-| Synthetic session | Input chars | Approx input tokens | Summary chars | Approx summary tokens | Reduction | Compile time |
-|---:|---:|---:|---:|---:|---:|---:|
-| 100 turns / 400 messages | 356,913 | 89,228 | 36,451 | 9,113 | 89.8% | 12.5 ms |
-| 250 turns / 1,000 messages | 894,063 | 223,516 | 36,585 | 9,146 | 95.9% | 16.6 ms |
-| 500 turns / 2,000 messages | 1,789,313 | 447,328 | 36,605 | 9,151 | 98.0% | 35.8 ms |
-
-Practical interpretation:
-
-- Larger sessions compress better because the structured summary has fixed caps.
-- Runtime is local and usually small relative to model/tool latency.
-- Actual savings reported to users should come from `/unipi:compact-stats`, because Pi supplies real `tokensBefore` during compaction when available.
-
----
-
-## Troubleshooting
-
-### "Whatever preset I choose, Pipeline is always off"
-
-That means preset application is not updating `config.pipeline`. The intended behavior is:
-
-- `precise`: Auto Injection off.
-- `balanced`: Auto Injection on.
-- `thorough`: Auto Injection on.
-- `lean`: Auto Injection off.
-
-The five deprecated compatibility fields remain off in every preset.
-
-Make sure you are running a version with the preset pipeline fix, select the preset, and press **Enter** to save.
-
-### "Compaction did not happen"
-
-- For immediate user-triggered compaction, use `/unipi:lossless-compact`.
-- For automatic percentage compaction, enable **Auto → Percentage Trigger**.
-- Pi core still has its own reserve-token fallback; UniPi's percentage trigger is optional and disabled by default.
-
-### "Stats show zero"
-
-- Stats only increase after compaction or after tracked sandbox/search events.
-- Run `/unipi:compact-doctor` to check DB/config health.
-- Long sessions may show all-time DB fallbacks if current in-memory counters are zero.
-
-### "Recall cannot find something"
+```ts
+import { registerCompactionContext } from "@pi-unipi/core";
+registerCompactionContext("my-module", () => (running ? "Task X is in progress — …" : null));
+```
 
-- Use specific terms with `/unipi:session-recall <query>`.
-- The recall path prefers Pi's append-only branch and falls back to cached normalized blocks.
-- Extra noise filtering can be added with `pipeline.customNoisePatterns`.
+Compactions applied at a turn boundary (percentage trigger) do not fire Pi's `session_compact`; listen to `UNIPI_EVENTS.COMPACTOR_COMPACTED` to react to every compaction.
 
-## License
+## Removed in 3.0
 
-MIT
+- **Session continuity**: the SQLite event log and the hidden snapshot restored after compaction. It logged every session under one shared ID, so snapshots mixed projects and grew to ~60k tokens. The summary now derives files, errors and commits from the session itself. `/unipi:compact-doctor` reports the old `~/.unipi/db/compactor` directory, which can be deleted.
+- **Sandbox tools** (`sandbox`, `sandbox_file`, `sandbox_batch`), the `compact` tool (it never compacted), `compactor_stats` / `compactor_doctor` tools (use the commands), presets, and the inert strategy modes.

package/packages/compactor/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/compactor",
-  "version": "3.0.0-alpha.2",
-  "description": "Context engine for Pi — zero-LLM compaction, session continuity, sandbox execution, and tool display optimization",
+  "version": "3.0.0-alpha.21",
+  "description": "Compaction for Pi — lossless zero-LLM or model summaries, rebuilt from full history, with session recall",
   "type": "module",
   "main": "src/index.ts",
   "license": "MIT",
@@ -18,8 +18,7 @@
     "unipi",
     "compactor",
     "context",
-    "sandbox",
-    "fts5"
+    "compaction"
   ],
   "scripts": {
     "test": "npx bun test tests"
@@ -34,8 +33,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.2",
-    "@pi-unipi/info-screen": "3.0.0-alpha.2",
+    "@pi-unipi/core": "3.0.0-alpha.21",
+    "@pi-unipi/info-screen": "3.0.0-alpha.21",
     "@earendil-works/pi-agent-core": "^0.87.1"
   },
   "peerDependencies": {
@@ -47,9 +46,6 @@
     "@types/node": "^25.6.0",
     "typescript": "^6.0.0"
   },
-  "optionalDependencies": {
-    "better-sqlite3": ">=11.0.0"
-  },
   "pi": {
     "extensions": [
       "./index.ts"

package/packages/compactor/skills/compactor/SKILL.md

@@ -1,29 +1,22 @@
 ---
 name: compactor
-description: Context management — compact session, recall history, run code, search content.
+description: Session recall and compaction — use when earlier parts of this session are missing from context, or after a compaction summary.
 ---
 
-# Compactor — Context Management
+# Compactor
 
-## When Context Is Tight
-- `context_budget` → check % full. `compact` → free tokens (zero-LLM, 98%+ reduction).
-  Compact BEFORE complex work. `compact(dryRun: true)` to preview without compacting.
-- `compactor_stats` → check savings. `compactor_doctor` → diagnose.
+Compaction is automatic: when the context fills, it is replaced by a summary and the work carries on. Keep working through it.
 
-## Finding Past Work
-- `session_recall(query)` → search this session (BM25 or regex), including raw messages that may no longer be in live context after compaction.
-- For project/file search, use `read`/`bash` (rg) directly; content indexing is not part of compactor.
+## After a compaction
 
-## Running Code
-- `sandbox(lang, code)` → single script. `sandbox_batch(items)` → atomic.
-  `sandbox_file(lang, path)` → run file. Only stdout enters context.
+The summary opens with **Active Work** (the goal, ralph loop or kanboard task in flight) — treat it as authoritative and continue that work. Then come the user's requests, the latest state, decisions, files, commits and open errors.
 
-## Complex Multi-Step Tasks
-⚠ When the task spans many operations, PREFER Ralph loops
-   (`the implementation step`, `ralph_start`) if available — they manage
-   context pressure better than monolithic runs.
+## Recall
 
-## Critical Rules
-- Compact BEFORE starting, not when full.
-- `session_recall` instead of scrolling history.
-- Index project files early if you'll search often.
+The full session history is kept. Reach for `session_recall` whenever a detail is missing:
+
+- `session_recall(query: "redis cache decision")` — plain keywords work best.
+- `#123`-style refs in the summary are entry indices: `session_recall(expand: [123])` returns the full content.
+- `mode: "touched"` lists the files worked on; `scope: "all"` also covers edited or retried turns.
+
+`context_budget` reports how full the context is.