@pi-unipi/unipi 2.5.0 → 2.6.1

package/CHANGELOG.md

@@ -6,6 +6,49 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [2.6.1] — 2026-08-20
+
+This release fixes the notify settings overlay and recap model selector in terminals using the kitty keyboard protocol (Ghostty under Herdr), and makes the model selector reflect Pi's live model registry.
+
+### Fixed
+
+- `notify`: settings overlay and recap model selector match Up/Down/Escape/Enter/Tab/Space/Backspace via `matchesKey()` from `@earendil-works/pi-tui` instead of raw byte comparison — under the kitty keyboard protocol Escape arrives as `\x1b[27u` (Ctrl+C as `\x1b[99;5u`), so arrows/Escape silently did nothing and the selector could trap the user (issue #27).
+- `notify`: Ctrl+C now always closes both overlays, even mid-filter.
+- `notify`: recap model selector lists models injected from Pi's live `ctx.modelRegistry` instead of relying solely on `~/.unipi/config/models-cache.json`; when neither source has models it shows an actionable hint instead of a bare "No models found".
+- `core`: model-cache paths are resolved per call (respects `HOME` changes; enables isolated tests).
+
+### Added
+
+- `/unipi:notify-event <event> <on|off>` — toggle a notify event without the TUI (escape hatch for terminals with overlay input problems); reports the resulting value and reminds that `/reload` re-registers listeners.
+
+### Changed
+
+- `notify`: arrows navigate inside selector filter mode without leaving it; `m` and `M` both open the model selector from the Recap tab.
+
+## [2.6.0] — 2026-08-14
+
+This release completes UniPi's provider prefix-cache preservation rollout, making model-visible state append-only within explicit cache epochs while adding privacy-safe diagnostics and bounded external results.
+
+### Added
+
+- **Provider-native prefix regression tests:** keyless tests capture real `pi-ai` OpenAI-compatible payloads before network I/O and verify ordinary turns plus Ralph, Memory, Milestone, Workflow, and Compactor snapshots extend the exact prior message prefix.
+- **Privacy-safe cache diagnostics:** `/unipi:prefix-cache` reports session-local request/envelope HMAC fingerprints, structural prefix transitions, explicit epochs, and provider-reported cache-read/cache-write tokens without retaining raw prompts, arguments, schemas, or payloads.
+- **Bounded result artifacts:** MCP and helper text has a hard 64 KiB model-visible ceiling. Raw results up to 16 MiB spill to private local artifacts with selective-read references and seven-day cleanup integration.
+- **Prefix-cache architecture guide:** documents the append-only invariant, superseding snapshot semantics, cache-reset events, Pi/provider ownership boundaries, DeepSeek expectations, and compaction behavior.
+
+### Changed
+
+- **Deterministic tool lifecycle:** Ralph and CocoIndex tools register at extension construction time; custom subagent types and filesystem discovery use locale-independent deterministic ordering.
+- **Compaction continuity is byte-stable:** resume snapshots no longer include wall-clock generation text, and UniPi's optional percentage compaction trigger remains disabled by default.
+- **Ralph reminders are superseding snapshots:** unchanged reminders deduplicate within an epoch and reappear once after compaction.
+- **Search output is bounded:** CocoIndex and session recall default to 10 results and hard-cap pages at 50; expanded recall hits are capped at 16 KiB.
+
+### Fixed
+
+- **Helper isolation recognizes current tool names:** child agents cannot recursively invoke `spawn_helper` or `get_helper_result` through stale exclusions.
+- **Oversized external output no longer inflates every later cold request:** bounded previews retain useful head/tail context and fail safely if private artifact creation is unavailable.
+- **Cache usage accounting counts distinct identical responses correctly** while deduplicating repeated active-context message objects.
+
 ## [2.5.0] — 2026-08-14
 
 This release makes persistent memory migration reliable across standalone and all-in-one installs, while stabilizing workflow tool schemas and MCP registration.

package/README.md

@@ -17,6 +17,8 @@ pi install npm:@pi-unipi/unipi
 
 **[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.
 
+**[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.
+
 **[CocoIndex](./packages/cocoindex/README.md)** — Project indexing and semantic code search backed by CocoIndex and LanceDB. Agent tools and slash commands for status, init, update, and search.
 
 **[Subagents](./packages/subagents/README.md)** — Parallel execution with file locking. Spawn background agents to research, fix, or build while the main agent keeps going.

package/docs/prefix-cache-architecture.md

@@ -0,0 +1,89 @@
+# Provider Prefix-Cache Architecture
+
+UniPi treats provider prefix caching as a request-shape invariant, not as a local cache. Within one **cache epoch**, each provider request must preserve the preceding request's model-visible prefix and add only new tail messages.
+
+```text
+stable system prompt
++ stable ordered tool definitions
++ immutable prior messages
++ newly appended messages
+```
+
+A cache epoch is the period in which the provider, model, inference settings, system prompt, tool definitions and ordering, and already-serialized messages remain unchanged. UniPi cannot force a provider to retain or reuse its server-side cache, but it can avoid needlessly invalidating that cache.
+
+## Rules
+
+1. Dynamic operational state is appended as a persisted custom message. It does not rewrite the system prompt or an earlier message.
+2. A newer state snapshot explicitly supersedes older snapshots. Older snapshots stay immutable until compaction.
+3. Unchanged snapshots are not appended repeatedly.
+4. Tool definitions and registration order are deterministic for a fixed configuration.
+5. Execution policy is enforced when a tool is called rather than by changing the visible tool list mid-session.
+6. Model-visible content excludes avoidable clocks, random identifiers, and unstable filesystem or locale ordering unless they are genuine new results.
+7. Compaction is an explicit cache boundary. Post-compaction continuity extends the new compacted context; it does not pretend the old provider prefix survived.
+8. Large external results must have a bounded model-visible representation. Full output may be retained outside provider serialization when the host offers a safe durable channel.
+
+`display: false` only hides a custom message in Pi's transcript UI. It does **not** hide it from the model. Prefix safety comes from append-only placement, not display state.
+
+## Gap matrix
+
+This matrix reflects UniPi source and Pi 0.84.1 APIs as audited for the v2.5.x rollout.
+
+| Surface | Status | Ownership and behavior |
+|---|---|---|
+| Ralph iteration state | Fixed | Hidden `unipi-ralph-loop-reminder` tail snapshots; no system-prompt mutation. |
+| Milestone state | Fixed | Workspace-qualified, compaction-aware `unipi-milestone-snapshot` messages append only when state changes. |
+| Workflow sandbox | Fixed | Stable tool schemas; `tool_call` blocks disallowed execution; active/inactive snapshots supersede prior state. |
+| Memory reminders | Fixed | First-turn and retrospective reminders are tail messages. |
+| Compactor resume | Fixed | One-shot hidden resume context extends the post-compaction epoch. Snapshot rendering is deterministic for fixed stored events. |
+| Utility continuation | Fixed | `/continue` sends a hidden tail message. |
+| BTW visible notes | Fixed | The `context` filter excludes the custom note type from its first provider projection onward; side threads use independent sessions. |
+| MCP discovery and tool order | Fixed | Discovery is barriered and final names are sorted with locale-independent code-unit ordering before registration. |
+| MCP JSON schemas | Fixed | Object keys and semantically unordered `required` members are canonicalized; order-sensitive literal arrays are preserved. |
+| Subagent type descriptions | Fixed | Built-in, configured, and filesystem-discovered type names are code-unit sorted before entering tool descriptions. |
+| Dynamic tool catalogs | Intentional boundary | MCP catalog changes and tool-enable settings require a new/restarted session when definitions change. Runtime removal is refused when Pi cannot unregister truthfully. |
+| Compaction and branch summarization | Intentional boundary | History is replaced by a summary and retained tail. Pi uses separate one-shot routing behavior for summarization. |
+| New/resume/fork/tree/reload | Intentional boundary | Session branch, resources, tools, or prompt inputs can change. A resumed process may reuse cache only if the provider still has an identical prefix; UniPi does not assume that. |
+| Provider/model/thinking/sampling changes | Intentional boundary | These alter the request envelope and start a new epoch. Model and thinking changes are persisted by Pi. |
+| Workspace/cwd and project instructions | Intentional boundary | Pi includes cwd and loaded resources in its base prompt. Switching or reloading them changes the epoch. |
+| Helper and BTW sessions | Intentional boundary | Each is an independent model session with its own system prompt, tools, and cache lineage. |
+| Base system prompt and cwd footer | Host-owned | Pi constructs these. UniPi avoids adding changing per-turn text to them. |
+| Global extension/tool ordering | Host-owned | Pi owns extension loading and the combined registry. UniPi makes its own dynamic registration deterministic. |
+| Session tree projection | Host-owned | Pi reconstructs the selected branch and compaction surface. |
+| Provider-native conversion and wire serialization | Host-owned | `before_provider_request` exposes an untyped provider-native object before transport; later extensions and SDK serialization may still transform it. |
+| Provider cache retention/hits | Provider-owned | Prefix identity is necessary, not sufficient. TTL, routing, load, and provider policy still determine reuse. |
+| Request envelope observability | Fixed | Utility observes provider-native payloads without mutation, retains only session-local keyed HMAC fingerprints/counters, classifies structural transitions, and exposes provider-reported cache usage through `/unipi:prefix-cache`. |
+| Oversized MCP/helper output | Fixed | MCP and helper results have a hard 64 KiB model-visible ceiling. Raw text up to 16 MiB is retained in random mode-0600 artifacts under an enforced mode-0700 directory and retrieved selectively with `read`; larger or failed spills return a non-retention warning. |
+| Oversized paginated search/recall output | Fixed | CocoIndex and session recall default to 10 and hard-cap pages at 50 even when host validation is bypassed. CocoIndex renders 300-character excerpts; expanded recall hits are capped at 16 KiB and direct the model to narrow its query. |
+
+## Explicit cache boundaries
+
+The following events are expected to lose all or part of prefix reuse:
+
+- compaction or branch summarization;
+- provider or model selection changes;
+- thinking level, sampling parameters, stop sequences, or output-limit changes;
+- a real system-prompt/resource/skill/project-instruction change;
+- a meaningful tool definition, tool order, or active-tool change;
+- workspace/cwd changes represented in Pi's base prompt;
+- new, resumed, forked, or navigated session branches;
+- independent helper, BTW, or other one-shot model sessions.
+
+A boundary is not necessarily a defect. An unrecorded or avoidable boundary is.
+
+## Pi API boundary
+
+The closest extension hook to a provider-native request body is `before_provider_request`. It is useful for structural tests and opt-in diagnostics, but it has important limits:
+
+- `event.payload` is `unknown` and provider-specific;
+- the event has no request ID, retry index, or purpose classification;
+- later-loaded extensions can replace the payload afterward;
+- final HTTP headers and transport serialization are separate;
+- compaction and normal requests are not intrinsically distinguished.
+
+Direct pi-ai `onPayload(payload, model)` is stronger for adapter-level tests. Exact wire correlation requires a custom provider, transport, or proxy. Parsed `cacheRead` and `cacheWrite` counters are available on final assistant or compaction usage when the provider reports them; a zero may also mean that the provider does not expose the metric.
+
+UniPi's `/unipi:prefix-cache` diagnostic observes this provider-native boundary without replacing payloads. It classifies first request, identical retry, exact sequence extension, envelope change, payload-shape change, and history rewrite. Request and envelope fingerprints are HMAC-SHA-256 values truncated for display and keyed with a random process-memory secret. No raw payload is retained, persisted, or logged, and fingerprints intentionally cannot be correlated after reload. Model/thinking, compaction, and tree events mark explicit boundaries; subsequent payloads supply the canonical structural classification. Provider-reported cache read/write totals are deduplicated from successful assistant messages.
+
+## Compaction
+
+UniPi currently performs deterministic, zero-LLM compaction. Therefore it does not issue a second summarizer request whose prefix needs warming. UniPi's additional percentage trigger is disabled by default; Pi core's reserve-token safety trigger remains active unless the user changes Pi settings. With Pi 0.84.1 defaults, core compaction triggers above `contextWindow - 16,384` estimated tokens and retains approximately 20,000 recent tokens. Enabling UniPi's optional 80% trigger intentionally trades earlier epoch resets for more headroom, with cooldown and minimum-growth guards against repeat compaction. If LLM summarization is introduced, the summarization call must replay the current conversation's exact system prompt, ordered tools, and leading messages, then append the compaction instruction as the final user message. Replacing the system prompt with a special summarizer prompt would throw away the warm prefix at the most expensive point in the session.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -32,6 +32,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "docs/prefix-cache-architecture.md",
     "packages/*/package.json",
     "packages/*/*.ts",
     "packages/*/src/**/*.ts",
@@ -76,26 +77,26 @@
     "typebox": "^1.1.38"
   },
   "dependencies": {
-    "@pi-unipi/ask-user": "2.5.0",
-    "@pi-unipi/btw": "2.5.0",
-    "@pi-unipi/compactor": "2.5.0",
-    "@pi-unipi/notify": "2.5.0",
-    "@pi-unipi/command-enchantment": "2.5.0",
-    "@pi-unipi/core": "2.5.0",
-    "@pi-unipi/info-screen": "2.5.0",
-    "@pi-unipi/mcp": "2.5.0",
-    "@pi-unipi/memory": "2.5.0",
-    "@pi-unipi/ralph": "2.5.0",
-    "@pi-unipi/subagents": "2.5.0",
-    "@pi-unipi/utility": "2.5.0",
-    "@pi-unipi/milestone": "2.5.0",
-    "@pi-unipi/kanboard": "2.5.0",
-    "@pi-unipi/web-api": "2.5.0",
-    "@pi-unipi/workflow": "2.5.0",
-    "@pi-unipi/footer": "2.5.0",
-    "@pi-unipi/updater": "2.5.0",
-    "@pi-unipi/input-shortcuts": "2.5.0",
-    "@pi-unipi/cocoindex": "2.5.0"
+    "@pi-unipi/ask-user": "2.6.1",
+    "@pi-unipi/btw": "2.6.1",
+    "@pi-unipi/compactor": "2.6.1",
+    "@pi-unipi/notify": "2.6.1",
+    "@pi-unipi/command-enchantment": "2.6.1",
+    "@pi-unipi/core": "2.6.1",
+    "@pi-unipi/info-screen": "2.6.1",
+    "@pi-unipi/mcp": "2.6.1",
+    "@pi-unipi/memory": "2.6.1",
+    "@pi-unipi/ralph": "2.6.1",
+    "@pi-unipi/subagents": "2.6.1",
+    "@pi-unipi/utility": "2.6.1",
+    "@pi-unipi/milestone": "2.6.1",
+    "@pi-unipi/kanboard": "2.6.1",
+    "@pi-unipi/web-api": "2.6.1",
+    "@pi-unipi/workflow": "2.6.1",
+    "@pi-unipi/footer": "2.6.1",
+    "@pi-unipi/updater": "2.6.1",
+    "@pi-unipi/input-shortcuts": "2.6.1",
+    "@pi-unipi/cocoindex": "2.6.1"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.80.0",

package/packages/ask-user/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "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": "2.5.0"
+    "@pi-unipi/core": "2.6.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/autocomplete/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/command-enchantment",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "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

@@ -73,6 +73,7 @@ export const COMMAND_REGISTRY: Record<string, string> = {
   "unipi:worktree-list":  "workflow",
   "unipi:worktree-merge": "workflow",
   "unipi:consultant":     "workflow",
+  "unipi:prefix-cache":   "utility",
   "unipi:quick-work":     "workflow",
   "unipi:gather-context": "workflow",
   "unipi:document":       "workflow",
@@ -168,6 +169,7 @@ export const COMMAND_REGISTRY: Record<string, string> = {
   "unipi:notify-set-ntfy":  "notify",
   "unipi:notify-test":      "notify",
   "unipi:notify-recap-model": "notify",
+  "unipi:notify-event":     "notify",
 
   // kanboard (2 commands)
   "unipi:kanboard":          "kanboard",
@@ -199,6 +201,7 @@ export const COMMAND_DESCRIPTIONS: Record<string, string> = {
   "unipi:worktree-list":  "List all unipi worktrees",
   "unipi:worktree-merge": "Merge worktree branches back to main",
   "unipi:consultant":     "Expert consultation — advisory analysis",
+  "unipi:prefix-cache":   "Show privacy-safe provider prefix-cache diagnostics",
   "unipi:quick-work":     "Fast single-task execution — one shot",
   "unipi:gather-context": "Research codebase — surface patterns",
   "unipi:document":       "Generate documentation — README, API docs",
@@ -280,6 +283,7 @@ export const COMMAND_DESCRIPTIONS: Record<string, string> = {
   "unipi:notify-set-ntfy":  "Set up ntfy push notifications",
   "unipi:notify-test":      "Test all enabled notification platforms",
   "unipi:notify-recap-model": "Select model for notification recaps",
+  "unipi:notify-event":     "Toggle a notify event without the TUI: <event> <on|off>",
 
   "unipi:milestone-onboard": "Create MILESTONES.md from existing workflow docs",
   "unipi:milestone-update":  "Sync MILESTONES.md with completed work",

package/packages/btw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/btw",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "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.80.0"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.5.0"
+    "@pi-unipi/core": "2.6.1"
   },
   "pi": {
     "extensions": [],

package/packages/cocoindex/README.md

@@ -58,7 +58,7 @@ Uses cocoindex v1.0+ App/fn/mount API with:
 
 | Tool | Description |
 |------|-------------|
-| `cocoindex_search` | Search indexed content (semantic vector when available, LanceDB FTS when available, lexical fallback for text-only indexes) |
+| `cocoindex_search` | Search indexed content (semantic vector when available, LanceDB FTS when available, lexical fallback for text-only indexes); defaults to 10 results and hard-caps each page at 50 |
 | `cocoindex_status` | Check indexing status, freshness, doc count |
 
 ## Commands
@@ -76,6 +76,7 @@ Uses cocoindex v1.0+ App/fn/mount API with:
 - **Data store**: `.unipi/cocoindex/.lancedb/`
 - **Embeddings**: `~/.unipi/memory/config.json` (shared with memory package)
 - **Search fallback**: Existing text-only LanceDB tables remain searchable through a lexical scan fallback when no vector column or FTS index exists
+- **Provider context bound**: Search pages are limited to 50 results, each rendered with a 300-character excerpt. Request another offset page instead of placing an unbounded result set into conversation history.
 
 ## What Changed from FTS5
 

package/packages/cocoindex/index.ts

@@ -15,22 +15,15 @@ import { registerCocoindexCommands } from "./commands.js";
 import * as bridge from "./bridge.js";
 
 export default function cocoindexExtension(pi: ExtensionAPI): void {
-  // Register commands at extension load time (synchronous).
-  // Commands resolve projectDir from ctx.cwd at handler invocation time.
+  // Register commands and static tool definitions at extension load. Tool
+  // executors resolve ctx.cwd per call, so session_start never changes schemas.
   registerCocoindexCommands(pi);
+  registerCocoindexTools(pi, {
+    getProjectDir: (ctx) => ctx.cwd ?? process.cwd(),
+  });
 
   pi.on("session_start", async (_event, ctx) => {
-    const projectDir = (ctx as any).cwd ?? process.cwd();
-
-    // Register tools — these need projectDir for search context
-    const pipelineDir = bridge.getPipelineDir(projectDir);
-    const initialized = await bridge.isPipelineInitialized(pipelineDir);
-
-    registerCocoindexTools(pi, {
-      projectDir,
-      pipelineDir,
-      initialized,
-    });
+    const projectDir = ctx.cwd ?? process.cwd();
 
     emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
       name: MODULES.COCOINDEX,

package/packages/cocoindex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/cocoindex",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "CocoIndex integration for Pi — AST-aware content indexing, semantic vector search, and incremental pipeline management",
   "type": "module",
   "main": "index.ts",
@@ -16,7 +16,8 @@
     "vector-search"
   ],
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "npx tsx --test tools.test.ts"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",
@@ -25,7 +26,7 @@
     "typebox": "^1.1.38"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.5.0"
+    "@pi-unipi/core": "2.6.1"
   },
   "optionalDependencies": {
     "@lancedb/lancedb": "^0.21.0"

package/packages/cocoindex/tools.ts

@@ -7,18 +7,36 @@
  */
 
 import { Type } from "typebox";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { COCOINDEX_PACKAGE_SPEC, COCOINDEX_TOOLS } from "@pi-unipi/core";
 import * as bridge from "./bridge.js";
-import type { CocoindexDeps } from "./bridge.js";
+
+export interface CocoindexToolDeps {
+  getProjectDir(ctx: ExtensionContext): string;
+}
 
 // ─────────────────────────────────────────────────────────
 // Schemas
 // ─────────────────────────────────────────────────────────
 
+export const MAX_SEARCH_RESULTS = 50;
+
+export function normalizeSearchPage(limit?: number, offset?: number): { limit: number; offset: number } {
+  const requestedLimit = Number.isFinite(limit) ? Math.floor(limit!) : 10;
+  const requestedOffset = Number.isFinite(offset) ? Math.floor(offset!) : 0;
+  return {
+    limit: Math.min(MAX_SEARCH_RESULTS, Math.max(1, requestedLimit)),
+    offset: Math.max(0, requestedOffset),
+  };
+}
+
 const SearchParams = Type.Object({
   query: Type.String({ description: "Search query against indexed content" }),
-  limit: Type.Optional(Type.Number({ description: "Max results (default 10)", minimum: 1 })),
+  limit: Type.Optional(Type.Number({
+    description: `Max results (default 10, hard cap ${MAX_SEARCH_RESULTS})`,
+    minimum: 1,
+    maximum: MAX_SEARCH_RESULTS,
+  })),
   offset: Type.Optional(Type.Number({ description: "Pagination offset", minimum: 0 })),
 });
 
@@ -39,7 +57,7 @@ function textResult(text: string, details?: Record<string, unknown>): any {
 // Registration
 // ─────────────────────────────────────────────────────────
 
-export function registerCocoindexTools(pi: ExtensionAPI, deps: CocoindexDeps): void {
+export function registerCocoindexTools(pi: ExtensionAPI, deps: CocoindexToolDeps): void {
   // cocoindex_search — search indexed content via LanceDB
   pi.registerTool({
     name: COCOINDEX_TOOLS.SEARCH,
@@ -49,7 +67,13 @@ export function registerCocoindexTools(pi: ExtensionAPI, deps: CocoindexDeps): v
       "Diagnostic/search only: this tool never installs CocoIndex. " +
       "Use /unipi:cocoindex-init to set up/install, then /unipi:cocoindex-update to index.",
     parameters: SearchParams,
-    async execute(_toolCallId: string, params: any): Promise<any> {
+    async execute(
+      _toolCallId: string,
+      params: any,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      ctx: ExtensionContext,
+    ): Promise<any> {
       try {
         const available = await bridge.isAvailable();
         if (!available) {
@@ -61,9 +85,12 @@ export function registerCocoindexTools(pi: ExtensionAPI, deps: CocoindexDeps): v
           );
         }
 
-        const results = await bridge.search(deps.projectDir, params.query, {
-          limit: params.limit,
-          offset: params.offset,
+        // Clamp in execution as well as schema validation: Pi extensions may
+        // mutate tool inputs after validation and custom hosts may skip it.
+        const { limit, offset } = normalizeSearchPage(params.limit, params.offset);
+        const results = await bridge.search(deps.getProjectDir(ctx), params.query, {
+          limit,
+          offset,
         });
 
         if (results.length === 0) {
@@ -79,7 +106,8 @@ export function registerCocoindexTools(pi: ExtensionAPI, deps: CocoindexDeps): v
         );
         return textResult(
           `Found ${results.length} results for "${params.query}":\n\n${lines.join("\n\n")}`,
-          { results } as unknown as Record<string, unknown>,
+          // Avoid duplicating full result content in model-visible details.
+          { count: results.length, query: params.query, limit, offset },
         );
       } catch (err) {
         return textResult(`CocoIndex search error: ${err}`, { error: true });
@@ -93,9 +121,15 @@ export function registerCocoindexTools(pi: ExtensionAPI, deps: CocoindexDeps): v
     label: "CocoIndex Status",
     description: "Check CocoIndex indexing status. Diagnostic only; use commands for interactive install/update.",
     parameters: StatusParams,
-    async execute(): Promise<any> {
+    async execute(
+      _toolCallId: string,
+      _params: Record<string, never>,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      ctx: ExtensionContext,
+    ): Promise<any> {
       try {
-        const info = await bridge.status(deps.projectDir);
+        const info = await bridge.status(deps.getProjectDir(ctx));
         const lines = [
           `📦 CocoIndex Status`,
           `CLI available: ${info.cliAvailable ? "✅" : "❌"}`,

package/packages/compactor/README.md

@@ -108,6 +108,8 @@ Config-only legacy field: `fts5Index` remains in the schema for compatibility, b
 
 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 `turn_end` and can call compaction when the threshold is reached. Disabled by default for backward compatibility. |
@@ -157,7 +159,7 @@ The extension registers tools during `session_start` after the session DB is ini
 | Tool | Purpose |
 |---|---|
 | `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. |
+| `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`. |
@@ -255,7 +257,7 @@ When UniPi handles `session_before_compact`, it transforms old messages through
 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.
+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.
 
 ---
 

package/packages/compactor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/compactor",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "Context engine for Pi — zero-LLM compaction, session continuity, sandbox execution, and tool display optimization",
   "type": "module",
   "main": "src/index.ts",
@@ -34,8 +34,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.5.0",
-    "@pi-unipi/info-screen": "2.5.0",
+    "@pi-unipi/core": "2.6.1",
+    "@pi-unipi/info-screen": "2.6.1",
     "@earendil-works/pi-agent-core": "^0.80.0"
   },
   "peerDependencies": {

package/packages/compactor/src/session/snapshot.ts

@@ -257,7 +257,6 @@ export function buildResumeSnapshot(
 ): string {
   const compactCount = opts?.compactCount ?? 1;
   const searchTool = opts?.searchTool ?? "ctx_search";
-  const now = new Date().toISOString();
 
   const fileEvents: StoredEvent[] = [];
   const taskEvents: StoredEvent[] = [];
@@ -316,7 +315,9 @@ export function buildResumeSnapshot(
   const intent = buildIntentSection(intentEvents);
   if (intent) sections.push(intent);
 
-  const header = `<session_resume events="${events.length}" compact_count="${compactCount}" generated_at="${now}">`;
+  // Deliberately omit wall-clock time. This snapshot is model-visible on the
+  // first post-compaction request and must be reproducible from stored events.
+  const header = `<session_resume events="${events.length}" compact_count="${compactCount}">`;
   const footer = `</session_resume>`;
   const body = sections.join("\n\n");
   if (body) {

package/packages/compactor/src/tools/register.ts

@@ -16,7 +16,7 @@
 import { Type } from "typebox";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { compactTool } from "./compact.js";
-import { vccRecall, type RecallInput } from "./vcc-recall.js";
+import { MAX_RECALL_RESULTS, vccRecall, type RecallInput } from "./vcc-recall.js";
 import { ctxExecute, type CtxExecuteInput } from "./ctx-execute.js";
 import { ctxExecuteFile, type CtxExecuteFileInput } from "./ctx-execute-file.js";
 import { ctxBatchExecute, type BatchItem } from "./ctx-batch-execute.js";
@@ -55,7 +55,11 @@ const RecallParams = Type.Object({
   mode: Type.Optional(Type.Union([Type.Literal("bm25"), Type.Literal("regex")], {
     description: "Search mode: bm25 (default) or regex fallback",
   })),
-  limit: Type.Optional(Type.Number({ description: "Max results to return (default 10)", minimum: 1 })),
+  limit: Type.Optional(Type.Number({
+    description: `Max results to return (default 10, hard cap ${MAX_RECALL_RESULTS})`,
+    minimum: 1,
+    maximum: MAX_RECALL_RESULTS,
+  })),
   offset: Type.Optional(Type.Number({ description: "Pagination offset", minimum: 0 })),
   expand: Type.Optional(Type.Boolean({ description: "Return full message content for hits" })),
 });

package/packages/compactor/src/tools/vcc-recall.ts

@@ -5,6 +5,9 @@
 import type { NormalizedBlock } from "../types.js";
 import { searchEntries } from "../compaction/search-entries.js";
 
+export const MAX_RECALL_RESULTS = 50;
+export const MAX_EXPANDED_HIT_BYTES = 16 * 1024;
+
 export interface RecallInput {
   query: string;
   mode?: "bm25" | "regex";
@@ -13,6 +16,14 @@ export interface RecallInput {
   expand?: boolean;
 }
 
+function truncateExpandedHit(text: string): string {
+  const bytes = Buffer.from(text, "utf8");
+  if (bytes.byteLength <= MAX_EXPANDED_HIT_BYTES) return text;
+  const omitted = bytes.byteLength - MAX_EXPANDED_HIT_BYTES;
+  const visible = bytes.subarray(0, MAX_EXPANDED_HIT_BYTES).toString("utf8").replace(/\uFFFD+$/u, "");
+  return `${visible}\n… ${omitted} bytes omitted from this hit; narrow the query to inspect more specific context …`;
+}
+
 export interface RecallResult {
   hits: Array<{
     index: number;
@@ -28,7 +39,11 @@ export function vccRecall(
   blocks: NormalizedBlock[],
   input: RecallInput,
 ): RecallResult {
-  const { query, mode = "bm25", limit = 10, offset = 0, expand = false } = input;
+  const { query, mode = "bm25", expand = false } = input;
+  const requestedLimit = Number.isFinite(input.limit) ? Math.floor(input.limit!) : 10;
+  const requestedOffset = Number.isFinite(input.offset) ? Math.floor(input.offset!) : 0;
+  const limit = Math.min(MAX_RECALL_RESULTS, Math.max(1, requestedLimit));
+  const offset = Math.max(0, requestedOffset);
 
   let hits: Array<{ index: number; score: number; text: string; kind: string }> = [];
 
@@ -37,7 +52,7 @@ export function vccRecall(
     hits = results.map((r, i) => ({
       index: r.docId,
       score: r.score,
-      text: expand ? r.text : r.text.slice(0, 200),
+      text: expand ? truncateExpandedHit(r.text) : r.text.slice(0, 200),
       kind: r.kind,
     }));
   } else {
@@ -50,7 +65,7 @@ export function vccRecall(
         hits.push({
           index: i,
           score: 1,
-          text: expand ? text : text.slice(0, 200),
+          text: expand ? truncateExpandedHit(text) : text.slice(0, 200),
           kind: b.kind,
         });
       }