@pi-unipi/unipi 3.0.0-alpha.3 → 3.0.0-alpha.4

package/CHANGELOG.md

@@ -6,6 +6,39 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [3.0.0-alpha.4] — 2026-09-28
+
+### Breaking Changes
+
+- **BREAKING: compactor reworked.** Session continuity (the SQLite event log and the snapshot restored after compaction) is removed: it logged every session under one shared ID, so restored snapshots mixed projects and reached ~60k tokens. Also removed: the sandbox tools (`sandbox`, `sandbox_file`, `sandbox_batch`), the `compact` tool (it never compacted), the `compactor_stats`/`compactor_doctor` tools, presets, and the strategy modes that had no effect. **Migration path:** `/unipi:compact` and `/unipi:lossless-compact` still work but are deprecated. Use `/unipi:compact-vcc`, `/unipi:compact-jev` or `/unipi:compact-by-llm`. Old configs are translated: `overrideDefaultCompaction: false` becomes Method = model summary, and `autoCompaction.enabled` becomes When = at a percentage. `~/.unipi/db/compactor` is no longer used and can be deleted.
+
+### Added
+
+- `compactor`: the lossless summary is rebuilt from the full session history on every compaction, so it can no longer grow from one compaction to the next (a real session went 15k → 236k → 248k characters). It puts the current state first: Active Work, Your Requests, Latest State, Decisions & Constraints, Files, Commits, Open Errors, Recent Transcript. Each section has a hard budget.
+  - Text that extensions inject with the user role (loop prompts, nudges, notifications) is recognised and left out of Your Requests; extension-sent messages are also marked when they are sent.
+  - `ask_user` answers are kept as "question → answer" decisions.
+  - Typed credentials are redacted.
+- `compactor`: **lossless + jev** method (`/unipi:compact-jev`). jev, the Decision model, drops items that are no longer in force, such as finished one-off requests, reversed decisions and fixed errors, at per-kind confidence thresholds. If jev is unavailable, the plain lossless summary is used.
+- `compactor`: the settings screen shows 5 main settings (Method, Pi's /compact, When, Percentage, Notifications); everything else is under **Advanced compaction**.
+- `core`: `registerCompactionContext()`. long-horizon (goal, ralph) and kanboard register their live state, and every compaction summary leads with it.
+- `scripts/compactor-eval.mts` replays the compactor at real compaction points of recorded sessions and shows what happened next, for review. `scripts/compactor-continue.mts` writes resumable A/B session files (old vs new compaction) for a blind "continue from here" test with `pi --fork … -nt -p`.
+- **Decision Model settings** (`/unipi:settings → Decision Model`): the jev provider, model, base URL, key and timeout now live in one shared `decision-model` namespace instead of long-horizon's judge. Every module that uses it (long-horizon routing, permission auto mode, skill exposure, watchdog, kanboard strategy, compactor pruning) has a **Decision model** block that inherits the shared model by default or switches to a custom one; empty custom fields fall back to the shared value. Existing `long-horizon.judge.*` transport settings are migrated once.
+- `compactor`: user corrections ("restore the background… I did not request this change") are kept as decisions.
+- `compactor`: **Lessons** section: lessons the agent wrote down itself (memory notes, `# Confirmed: …` comments in its commands, diagnosis sentences), kept verbatim. **Project Knowledge** section: notes it wrote or read, repeated build/test/deploy commands, hosts. Decisions keep early standing rules ("always…", "never…") instead of only the most recent ones.
+- `compactor`: jev asks short, local questions it can answer precisely: "durable lesson or one-off note?" and "does this later item replace that earlier one?" on items about the same subject. A reversal in the recent messages removes the stale lesson it replaces.
+- `compactor`: **compaction card** in the transcript under Pi's `[compaction]` block: one line (`Compacted 7.9k → 2.2k tokens · lossless + jev · 1 stale dropped · at 3%`), ctrl+o for method, trigger, kept tail, sections and jev drops. Never sent to the model; replaces the compaction toasts.
+- `footer`: the stats strip under the input shows `5 compactions · 47k→15k · just now` once the session has compacted. The five compactor segments are now one icon-free `compactions` segment.
+- `compactor`: the info-screen Compactor tab shows the method and trigger settings, compactions by method, tokens before → after, and the last compaction.
+
+### Fixed
+
+- `compactor`: the percentage trigger compacts at the `turn_end` boundary instead of calling `ctx.compact()`, which aborted the run and left goal, ralph and kanboard loops waiting. The "auto-continue" message is removed; Pi 0.87 continues after automatic compaction on its own, so it only added empty extra turns.
+- `compactor`: stats come from the session's own compaction entries instead of a fixed "12% kept" guess (also in the footer segments).
+- `compactor`: the kept tail is sized to the model's context window (recut above 40%, `keep:N` included) and the summary is capped at 8% of it, so compaction can no longer overflow small-context models.
+- `compactor`: secrets are redacted before summary items are clipped (a clipped quote could leak a password).
+- `compactor`: `/unipi:compact-doctor` no longer calls the jev method "model summary"; `/unipi:compact-stats` counts jev separately; a manual compaction with nothing to compact no longer repeats Pi's error.
+- `kanboard` tests wrote a fake judge key (`"k"`) into the real `~/.unipi/config/long-horizon/config.json`, which silently disabled the jev judge. They now use project scope.
+
 ## [3.0.0-alpha.3] — 2026-09-27
 
 ### Breaking Changes

package/README.md

@@ -21,7 +21,7 @@ pi install npm:@pi-unipi/unipi
 
 **[Memory](./packages/memory/README.md)** — Markdown files + [MemPalace](https://github.com/mempalace/mempalace) semantic search share a memory palace across pi, Devin, and zcode. Facts, preferences, and decisions persist across sessions; v2 data converts via `/unipi:memory migrate`.
 
-**[Compactor](./packages/compactor/README.md)** — Zero-LLM context engine. 6-stage pipeline hits 95%+ token reduction at zero API cost. Session continuity, percentage auto-compaction, session recall, and sandbox execution.
+**[Compactor](./packages/compactor/README.md)** — Compaction that keeps work going. Lossless zero-LLM summaries (or Pi's model summary), rebuilt from the full session history, led by the live goal/ralph/kanboard state; the full history stays searchable with session recall.
 
 **[Prefix-cache architecture](./docs/prefix-cache-architecture.md)** — Append-only request discipline, explicit cache epochs, deterministic tools, privacy-safe diagnostics, provider limitations, and bounded cold-epoch output.
 
@@ -92,7 +92,7 @@ Coexists triggers enhance behavior when packages are installed together. Workflo
 | Kanboard | `/unipi:` | kanboard (board: capture, work runner, web UI) |
 | Long-Horizon | `/unipi:goal`, `/unipi:ralph`, `/unipi:swarm`, `/unipi:graph` | <prompt>, start, stop, status, resume, clear |
 | Memory | `/unipi:memory-` | process, search, consolidate, forget |
-| Compactor | `/unipi:` | lossless-compact, session-recall, compact-stats, compact-preset, compact-help |
+| Compactor | `/unipi:` | compact-vcc, compact-by-llm, session-recall, compact-stats, compact-doctor, compact-help |
 | Notify | `/unipi:notify-` | settings, test, set-tg, set-ntfy |
 | MCP | `/unipi:mcp-` | add, settings, sync, status |
 | Web | `/unipi:web-` | settings, cache-clear |
@@ -121,7 +121,7 @@ Coexists triggers enhance behavior when packages are installed together. Workflo
 | `sidekick` / `read_subagent` | fusion | Delegate to the persistent sidekick and collect its report |
 | `bg_run` / `bg_status` / `bg_logs` / `bg_kill` / `bg_delegate` / `bg_result` | background-tasks | Long-running commands and background delegate agents |
 | `ask_user` | ask-user | User input |
-| `compact` / `session_recall` / `sandbox` | compactor | Context management |
+| `session_recall` / `context_budget` | compactor | Context management |
 | `ctx_env` | utility | Environment info |
 | `set_session_name` | utility | Session name for badge |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "3.0.0-alpha.3",
+  "version": "3.0.0-alpha.4",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -84,27 +84,27 @@
     "typebox": "^1.1.38"
   },
   "dependencies": {
-    "@pi-unipi/ask-user": "3.0.0-alpha.3",
-    "@pi-unipi/background-tasks": "3.0.0-alpha.3",
-    "@pi-unipi/btw": "3.0.0-alpha.3",
-    "@pi-unipi/command-enchantment": "3.0.0-alpha.3",
-    "@pi-unipi/compactor": "3.0.0-alpha.3",
-    "@pi-unipi/core": "3.0.0-alpha.3",
-    "@pi-unipi/footer": "3.0.0-alpha.3",
-    "@pi-unipi/image": "3.0.0-alpha.3",
-    "@pi-unipi/fusion": "3.0.0-alpha.3",
-    "@pi-unipi/info-screen": "3.0.0-alpha.3",
-    "@pi-unipi/input-shortcuts": "3.0.0-alpha.3",
-    "@pi-unipi/kanboard": "3.0.0-alpha.3",
-    "@pi-unipi/mcp": "3.0.0-alpha.3",
-    "@pi-unipi/memory": "3.0.0-alpha.3",
-    "@pi-unipi/notify": "3.0.0-alpha.3",
-    "@pi-unipi/skill-registry": "3.0.0-alpha.3",
-    "@pi-unipi/subagents": "3.0.0-alpha.3",
-    "@pi-unipi/updater": "3.0.0-alpha.3",
-    "@pi-unipi/utility": "3.0.0-alpha.3",
-    "@pi-unipi/web-api": "3.0.0-alpha.3",
-    "@pi-unipi/workflow": "3.0.0-alpha.3"
+    "@pi-unipi/ask-user": "3.0.0-alpha.4",
+    "@pi-unipi/background-tasks": "3.0.0-alpha.4",
+    "@pi-unipi/btw": "3.0.0-alpha.4",
+    "@pi-unipi/command-enchantment": "3.0.0-alpha.4",
+    "@pi-unipi/compactor": "3.0.0-alpha.4",
+    "@pi-unipi/core": "3.0.0-alpha.4",
+    "@pi-unipi/footer": "3.0.0-alpha.4",
+    "@pi-unipi/image": "3.0.0-alpha.4",
+    "@pi-unipi/fusion": "3.0.0-alpha.4",
+    "@pi-unipi/info-screen": "3.0.0-alpha.4",
+    "@pi-unipi/input-shortcuts": "3.0.0-alpha.4",
+    "@pi-unipi/kanboard": "3.0.0-alpha.4",
+    "@pi-unipi/mcp": "3.0.0-alpha.4",
+    "@pi-unipi/memory": "3.0.0-alpha.4",
+    "@pi-unipi/notify": "3.0.0-alpha.4",
+    "@pi-unipi/skill-registry": "3.0.0-alpha.4",
+    "@pi-unipi/subagents": "3.0.0-alpha.4",
+    "@pi-unipi/updater": "3.0.0-alpha.4",
+    "@pi-unipi/utility": "3.0.0-alpha.4",
+    "@pi-unipi/web-api": "3.0.0-alpha.4",
+    "@pi-unipi/workflow": "3.0.0-alpha.4"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.87.1",

package/packages/ask-user/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "3.0.0-alpha.3",
+  "version": "3.0.0-alpha.4",
   "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
   "type": "module",
   "main": "index.ts",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.3"
+    "@pi-unipi/core": "3.0.0-alpha.4"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/packages/autocomplete/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/command-enchantment",
-  "version": "3.0.0-alpha.3",
+  "version": "3.0.0-alpha.4",
   "description": "Enhanced TUI autocomplete for /unipi:* commands — colored, sorted, and grouped by package",
   "type": "module",
   "main": "src/index.ts",

package/packages/autocomplete/src/constants.ts

@@ -97,6 +97,9 @@ export const COMMAND_REGISTRY: Record<string, string> = {
   // web-api (2 commands)
 
   // compact (9 commands)
+  "unipi:compact-vcc":      "compact",
+  "unipi:compact-jev":      "compact",
+  "unipi:compact-by-llm":   "compact",
   "unipi:lossless-compact": "compact",
   "unipi:compact":         "compact",
   "unipi:session-recall":  "compact",
@@ -169,12 +172,15 @@ export const COMMAND_DESCRIPTIONS: Record<string, string> = {
   "unipi:info":          "Show system information",
 
 
-  "unipi:lossless-compact": "Immediate zero-LLM compaction",
-  "unipi:compact":          "(DEPRECATED) Use /unipi:lossless-compact instead",
+  "unipi:compact-vcc":      "Lossless compaction now — no model call (keep:N)",
+  "unipi:compact-jev":      "Lossless compaction, pruned by jev of what is no longer in force",
+  "unipi:compact-by-llm":   "Compact now with a model-written summary",
+  "unipi:lossless-compact": "(DEPRECATED) Use /unipi:compact-vcc instead",
+  "unipi:compact":          "(DEPRECATED) Use /unipi:compact-vcc instead",
   "unipi:session-recall":   "Search session history, including compacted-away messages",
   "unipi:compact-recall":   "(DEPRECATED) Use /unipi:session-recall instead",
-  "unipi:compact-stats":    "Show compaction statistics",
-  "unipi:compact-doctor":   "Diagnose compaction issues",
+  "unipi:compact-stats":    "Show this session's compaction savings",
+  "unipi:compact-doctor":   "Check compaction settings",
   "unipi:compact-help":     "Show compactor command help",
   "unipi:notify-event":     "Toggle a notify event without the TUI: <event> <on|off>",
 

package/packages/background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/background-tasks",
-  "version": "3.0.0-alpha.3",
+  "version": "3.0.0-alpha.4",
   "description": "Background tasks for UniPi — durable shell jobs and delegated background agents with a footer dock",
   "type": "module",
   "main": "src/index.ts",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-ai": "^0.87.1",
-    "@pi-unipi/core": "3.0.0-alpha.3",
+    "@pi-unipi/core": "3.0.0-alpha.4",
     "turndown": "^7.2.4"
   },
   "devDependencies": {

package/packages/btw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/btw",
-  "version": "3.0.0-alpha.3",
+  "version": "3.0.0-alpha.4",
   "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.3"
+    "@pi-unipi/core": "3.0.0-alpha.4"
   },
   "pi": {
     "extensions": [

package/packages/compactor/README.md

@@ -1,318 +1,91 @@
 # @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 |
+| **Lossless + jev** | The lossless summary, then jev (the Decision model, TypeSafe jev) drops items no longer in force: completed one-off requests, reversed decisions, fixed errors, an outdated report. Their room goes to other items. | ~0.5–2 s, fractions of a cent |
+| **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.
+jev only drops what it is confident about: decisions (including your answers to agent questions) need ≥92% certainty, one-off requests ≥80%, errors ≥75%. Your first and latest requests are never dropped. With no jev key or on timeout it falls back to the plain lossless summary. It uses the shared Decision Model (`/unipi:settings → Decision Model`); `Compactor → jev pruning — Decision model` can switch it to a custom one for the compactor only.
 
----
+### The lossless summary
 
-## User-facing settings
+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:
 
-Open settings with `/unipi:settings (Compactor)`.
+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.
 
-Keyboard:
+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`.
 
-| Key | Action |
-|---|---|
-| `Tab` | Switch tabs |
-| `↑/↓` | Move selection |
-| `Space` | Cycle/toggle selected value |
-| `/` | Search inside the Strategies tab |
-| `Enter` | Save and close |
-| `Esc` | Cancel |
+## In the TUI
 
-### Presets tab
+- **Compaction card:** one line under Pi's own `[compaction]` block, e.g. `▌ Compacted 7.9k → 2.2k tokens · lossless + jev · 1 stale dropped · at 3%`. ctrl+o expands it: method, trigger, what was kept verbatim, summary sections, what jev dropped. 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.
 
-Presets are profiles that set strategies, the implemented Auto Injection pipeline behavior, and sandbox mode.
+## When it compacts
 
-| 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. |
-
-The **Project Override** row controls where settings are saved:
+- **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.
 
-- `disabled` → save global config.
-- `enabled` → save `<project>/.unipi/config/compactor.json` for only this project.
+## Settings
 
-### Strategies tab
+`/unipi:settings → Compactor`
 
-These settings control what is extracted into compaction summaries or how related compactor features behave.
-
-| 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.
+| Method | lossless | lossless · lossless + jev · 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 |
 
-### Auto tab
+**Advanced compaction** (collapsed): smart keep tail, summary budget, per-section toggles, percentage cooldown and repeat growth, extra instructions for model summaries, debug output.
 
-These settings control UniPi-managed percentage auto-compaction. They are separate from Pi core's own `compaction.reserveTokens` behavior.
+Configs from before the rework are translated automatically: `overrideDefaultCompaction: false` becomes Method = model summary, and `autoCompaction.enabled` becomes When = at a percentage.
 
-**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.
+## Commands
 
-| 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. |
-
----
-
-## What the agent gets
-
-### Agent tools
-
-The extension registers tools during `session_start` after the session DB is initialized.
-
-| 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-jev [keep:N]` | Lossless compaction pruned by jev |
+| `/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
+Deprecated: `/unipi:compact` and `/unipi:lossless-compact` (use `/unipi:compact-vcc`), `/unipi:compact-recall` (use `/unipi:session-recall`).
 
-| 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. |
+## Tools
 
----
+- `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.
 
-## How the system works
+## For other modules
 
-### Chronological hook flow
+Register an active-work provider so summaries lead with your state:
 
-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:
-
-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.
-
-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.
-
----
-
-## 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.