pi-smart-compact 10.2.0 → 10.2.1

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [10.2.1] - 2026-10-05
+
+### Release approval
+
+- The release owner approved `10.2.1` as a stable patch with a version-specific
+  canary exception. Publication remains gated on the deterministic checks for
+  this exact candidate. No version-specific applied-canary cohort or live
+  provider/signature test exists; offline regressions do not establish cache-hit
+  savings or a `PROMOTE` result.
+
+### Fixed
+
+- **Native compaction prefix.** Reuse Pi's complete system/tool transcript
+  instead of prepending the current prompt and loadout a second time. Legacy
+  histories without an initial system message retain their fallback. Real-adapter
+  regressions cover initial and repeated native compaction; provider-side
+  thinking-signature acceptance is not claimed by these offline tests.
+- **Context attention follows execution gates.** Do not recommend trimming over
+  prepared compaction. Recompute prompt-start guidance instead of parking stale
+  pressure in `nextTurn`, and describe settled, background and native-hook
+  strategies separately. History guidance remains available with navigation off;
+  checkpoints no longer promise that a later rewind will be safe. Anchor advice
+  does not guarantee cleanup or cache hits, and manual-mode compaction advice
+  distinguishes staging from applying. A real offline Pi lifecycle regression
+  covers compaction between a completed high-pressure turn and the next prompt.
+
 ## [10.2.0] - 2026-10-05
 
 ### Release approval

package/dist/app/context-attention.d.ts

@@ -5,21 +5,23 @@
  * Pressure used to reach the model only through the human status line and
  * `smart_context status` results, so the navigation, history and compaction
  * tools sat idle until a person asked for them. The note rides along with the
- * next tool batch (steer) during a turn; when a turn ends in the cleanup band
- * it waits for the next prompt instead. One note per band per session,
- * re-armed once pressure clears (compaction, trim, rewind). The note is a
- * tail custom message, so the cached prefix is untouched.
+ * next tool batch (steer) during a turn. Prompt-start notes are computed then,
+ * never parked in nextTurn where compaction or permissions can make them stale.
+ * One note per band per session, re-armed once pressure clears or the session
+ * changes. Notes append to history; they never rewrite the prompt prefix.
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { CompactConfig } from "../types.ts";
 export declare const ATTENTION_CUSTOM_TYPE = "smart-compact-attention";
-type AttentionConfig = Pick<CompactConfig, "contextNavigationEnabled" | "contextGuidanceEnabled" | "toolLoading" | "autoTrigger" | "minContextPercent" | "prepareContextPercent" | "maxContextTokens">;
+type AttentionConfig = Pick<CompactConfig, "contextNavigationEnabled" | "contextGuidanceEnabled" | "toolLoading" | "autoTrigger" | "autoTriggerStrategy" | "minContextPercent" | "prepareContextPercent" | "maxContextTokens">;
 export interface ContextAttentionDeps {
     config: () => AttentionConfig;
     /** Agent-driven context changes are permitted and nothing (pivot, running compaction) takes priority. */
     canAgentAct: (ctx: ExtensionContext) => boolean;
+    /** The same maintenance gate used by history cleanup; prepared work takes priority. */
+    canCleanup: (ctx: ExtensionContext) => boolean;
     /** A lazy group can still be loaded through `smart_tools`. */
-    reachable: (group: "navigation" | "history") => boolean;
+    reachable: (group: "navigation" | "history" | "compaction") => boolean;
 }
 export declare function registerContextAttention(pi: Pick<ExtensionAPI, "on" | "sendMessage" | "getActiveTools">, deps: ContextAttentionDeps): void;
 export {};

package/dist/app/context-attention.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-attention.d.ts","sourceRoot":"","sources":["../../src/app/context-attention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAEtF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAKjD,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAK/D,KAAK,eAAe,GAAG,IAAI,CAAC,aAAa,EACvC,0BAA0B,GAAG,wBAAwB,GAAG,aAAa,GAAG,aAAa,GACnF,mBAAmB,GAAG,uBAAuB,GAAG,kBAAkB,CAAC,CAAC;AAExE,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,eAAe,CAAC;IAC9B,yGAAyG;IACzG,WAAW,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IAChD,8DAA8D;IAC9D,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,KAAK,OAAO,CAAC;CACzD;AAED,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,aAAa,GAAG,gBAAgB,CAAC,EAC/D,IAAI,EAAE,oBAAoB,GACzB,IAAI,CAoCN"}
+{"version":3,"file":"context-attention.d.ts","sourceRoot":"","sources":["../../src/app/context-attention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAEtF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAKjD,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAM/D,KAAK,eAAe,GAAG,IAAI,CAAC,aAAa,EACvC,0BAA0B,GAAG,wBAAwB,GAAG,aAAa,GAAG,aAAa,GAAG,qBAAqB,GAC3G,mBAAmB,GAAG,uBAAuB,GAAG,kBAAkB,CAAC,CAAC;AAExE,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,eAAe,CAAC;IAC9B,yGAAyG;IACzG,WAAW,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IAChD,uFAAuF;IACvF,UAAU,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IAC/C,8DAA8D;IAC9D,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,YAAY,KAAK,OAAO,CAAC;CACxE;AAED,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,aAAa,GAAG,gBAAgB,CAAC,EAC/D,IAAI,EAAE,oBAAoB,GACzB,IAAI,CA2CN"}

package/dist/app/native-compaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-compaction.d.ts","sourceRoot":"","sources":["../../src/app/native-compaction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"native-compaction.d.ts","sourceRoot":"","sources":["../../src/app/native-compaction.ts"],"names":[],"mappings":"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"}

package/dist/constants.d.ts

@@ -8,7 +8,7 @@ import type { CompressionProfile, ProfileConfig } from "./types.ts";
  * `package.json#version`. Do not hand-edit this line for releases; bump
  * package.json and run `bun run sync-version`.
  */
-export declare const VERSION = "10.2.0";
+export declare const VERSION = "10.2.1";
 /**
  * Opt-in components that are not installed with the extension: optional peer
  * dependencies in package.json, pinned to the versions the release audit

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAEN,KAAK,YAAY,EAEjB,MAAM,iCAAiC,CAAC;AAmEzC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAyDtE,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAAC,EAAE,EAAE,YAAY,QAomB7D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAEN,KAAK,YAAY,EAEjB,MAAM,iCAAiC,CAAC;AAmEzC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAyDtE,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAAC,EAAE,EAAE,YAAY,QAumB7D"}

package/dist/index.js

@@ -5,7 +5,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 
 // src/constants.ts
-var VERSION = "10.2.0";
+var VERSION = "10.2.1";
 var OPTIONAL_COMPONENTS = {
   mnemopi: { name: "@oh-my-pi/pi-mnemopi", version: "18.3.1", enables: "Mnemopi memory store" },
   bun: { name: "bun", version: "1.4.2", enables: "Mnemopi worker runtime when no Bun 1.3.14+ is on PATH" },
@@ -9304,6 +9304,7 @@ async function attemptNativeCompaction(rc, priorAttempts) {
     };
   }
   const prefix = rc.msgs.slice(0, cut);
+  const messages = prefix.map((entry) => entry.message);
   const prefixTokens = prefix.reduce((sum, entry) => sum + rc.estimator.message(entry.message), 0);
   const totalEstimate = rc.msgs.reduce((sum, entry) => sum + rc.estimator.message(entry.message), 0);
   const retainedTailTokens = Math.max(0, totalEstimate - prefixTokens);
@@ -9337,9 +9338,11 @@ async function attemptNativeCompaction(rc, priorAttempts) {
   nestedRequests++;
   try {
     const stream = rc.ctx.modelRegistry.streamSimple(model, {
-      systemPrompt: rc.ctx.getSystemPrompt(),
-      messages: prefix.map((entry) => entry.message),
-      tools: toolSource()
+      messages,
+      ...messages[0]?.role === "system" ? {} : {
+        systemPrompt: rc.ctx.getSystemPrompt(),
+        tools: toolSource()
+      }
     }, {
       signal: rc.cancellation.signal,
       fetch: wrapper.fetch,
@@ -16810,6 +16813,7 @@ function createSettledAutoTrigger(options = {}) {
 // src/app/context-attention.ts
 var ATTENTION_CUSTOM_TYPE = "smart-compact-attention";
 var CONTEXT_TOOL_NAME = "smart_context";
+var COMPACTION_TOOL_NAME = "smart_compact";
 var LOADER_TOOL_NAME = "smart_tools";
 function registerContextAttention(pi, deps) {
   let noted = null;
@@ -16820,12 +16824,12 @@ function registerContextAttention(pi, deps) {
   pi.on("session_before_switch", clear);
   pi.on("session_before_fork", clear);
   pi.on("session_tree", clear);
-  pi.on("message_end", (event, ctx) => {
-    const message = event.message;
-    if (message.role !== "assistant")
-      return;
+  pi.on("session_compact", clear);
+  pi.on("model_select", clear);
+  pi.on("session_shutdown", clear);
+  const attention = (ctx) => {
     const settings = deps.config();
-    if (!settings.contextNavigationEnabled || !settings.contextGuidanceEnabled || settings.toolLoading === "off")
+    if (!settings.contextGuidanceEnabled || settings.toolLoading === "off")
       return;
     const sessionId = resolveSessionId(ctx);
     const pressure = contextPressure(ctx, settings);
@@ -16837,51 +16841,74 @@ function registerContextAttention(pi, deps) {
     }
     if (noted?.sessionId === sessionId && (noted.band === band || noted.band === "compaction"))
       return;
-    if (message.content.some((block) => block.type === "toolCall" && (block.name === NAVIGATION_TOOL_NAME || block.name === CONTEXT_TOOL_NAME)))
-      return;
-    const midTurn = message.stopReason === "toolUse";
-    if (!midTurn && band === "compaction" && settings.autoTrigger)
-      return;
     if (!deps.canAgentAct(ctx))
       return;
     const active = new Set(pi.getActiveTools());
-    const content = renderAttention(band, pressure.percent, settings, ctx, active, deps.reachable);
+    const content = renderAttention(band, pressure.percent, settings, ctx, active, deps.reachable, deps.canCleanup(ctx));
     if (!content)
       return;
     noted = { sessionId, band };
-    pi.sendMessage({ customType: ATTENTION_CUSTOM_TYPE, content, display: true, details: { band, percent: pressure.percent } }, { deliverAs: midTurn ? "steer" : "nextTurn" });
+    return { customType: ATTENTION_CUSTOM_TYPE, content, display: true, details: { band, percent: pressure.percent } };
+  };
+  pi.on("before_agent_start", (_event, ctx) => {
+    const message = attention(ctx);
+    if (message)
+      return { message };
+  });
+  pi.on("message_end", (event, ctx) => {
+    const message = event.message;
+    if (message.role !== "assistant" || message.stopReason !== "toolUse")
+      return;
+    if (message.content.some((block) => block.type === "toolCall" && [NAVIGATION_TOOL_NAME, CONTEXT_TOOL_NAME, COMPACTION_TOOL_NAME].includes(block.name)))
+      return;
+    const note = attention(ctx);
+    if (note)
+      pi.sendMessage(note, { deliverAs: "steer" });
   });
 }
-function renderAttention(band, percent, settings, ctx, active, reachable) {
+function renderAttention(band, percent, settings, ctx, active, reachable, canCleanup) {
   const lines = [];
   const load = (group, tool) => active.has(tool) ? "" : reachable(group) && active.has(LOADER_TOOL_NAME) ? ` Load it first: ${LOADER_TOOL_NAME} load ${group}.` : null;
-  const navigation = load("navigation", NAVIGATION_TOOL_NAME);
+  const navigation = settings.contextNavigationEnabled ? load("navigation", NAVIGATION_TOOL_NAME) : null;
   const history = load("history", CONTEXT_TOOL_NAME);
   if (navigation !== null) {
-    lines.push((band === "compaction" ? `- Anchor now: ${NAVIGATION_TOOL_NAME} anchor with a name and a concise handoff (done / in progress / next step). The summary starts from it and the prompt cache stays warm up to it.` : `- Finishing a unit of work? ${NAVIGATION_TOOL_NAME} anchor with a concise handoff; safe cleanup is queued automatically and the prefix up to the anchor stays cached.`) + navigation);
+    lines.push(`- Finishing a unit of work? ${NAVIGATION_TOOL_NAME} anchor with a concise handoff (done / in progress / next step). An anchor alone does not reduce context; cleanup depends on safety and preparation gates.${navigation}`);
   }
   if (history !== null) {
-    const branch = ctx.sessionManager.getBranch();
     let trimmable = 0;
-    let blocked = false;
-    try {
-      const plan = planContextTrim(branch, inspectContext(branch, resolveSessionId(ctx)).checkpoint?.originId, { readerApi: ctx.model?.api });
-      blocked = Boolean(plan.blockedReason);
-      trimmable = plan.entries.filter((entry) => entry.type === "context_edit").length;
-    } catch {
-      blocked = true;
-    }
-    if (!blocked) {
-      if (trimmable > 0)
-        lines.push(`- ${CONTEXT_TOOL_NAME} trim: ${trimmable} archived tool output${trimmable === 1 ? "" : "s"} eligible now.${history}`);
-      lines.push(`- Starting a large read-only detour? ${CONTEXT_TOOL_NAME} checkpoint first, then rewind(report) when done keeps the findings and drops the research.${trimmable > 0 ? "" : history}`);
+    if (canCleanup) {
+      try {
+        const branch = ctx.sessionManager.getBranch();
+        const plan = planContextTrim(branch, inspectContext(branch, resolveSessionId(ctx)).checkpoint?.originId, { readerApi: ctx.model?.api });
+        if (!plan.blockedReason)
+          trimmable = plan.entries.filter((entry) => entry.type === "context_edit").length;
+      } catch {}
     }
+    if (trimmable > 0)
+      lines.push(`- ${CONTEXT_TOOL_NAME} trim: ${trimmable} archived tool output${trimmable === 1 ? "" : "s"} eligible now.${history}`);
+    lines.push(`- Starting a large read-only detour? ${CONTEXT_TOOL_NAME} checkpoint first; rewind(report) afterward only when status permits. Keep findings and evidence in the report.${trimmable > 0 ? "" : history}`);
+  }
+  if (band === "compaction" && !settings.autoTrigger) {
+    const compaction = load("compaction", COMPACTION_TOOL_NAME);
+    if (compaction !== null)
+      lines.push(`- ${COMPACTION_TOOL_NAME} stages a summary (or reports an existing one); the user runs /compact within its staging TTL to apply it. Staging does not shrink context.${compaction}`);
   }
   if (!lines.length)
     return null;
   const where = percent === null ? "" : ` ${Math.round(percent)}% of the policy window`;
-  const head = band === "compaction" ? `Context attention:${where} (compaction band). ` + (settings.autoTrigger ? "Compaction prepares now and applies when the turn settles." : "Automatic compaction is off here; the user runs /smart-compact.") : `Context attention:${where} (cleanup band). ` + (settings.autoTrigger ? `Automatic compaction prepares at ${settings.minContextPercent}%.` : "Automatic compaction is off here.");
-  return `${head}
+  let automatic;
+  if (!settings.autoTrigger)
+    automatic = "Automatic compaction is off here; the user can run /smart-compact.";
+  else if (settings.autoTriggerStrategy === "native-hook")
+    automatic = "Preparation runs when Pi requests compaction; this strategy has no settled trigger.";
+  else if (band === "compaction")
+    automatic = "Automatic compaction is requested when the turn settles if pressure remains.";
+  else {
+    automatic = `Automatic compaction is requested at ${settings.minContextPercent}% when the turn settles.`;
+    if (settings.autoTriggerStrategy === "background")
+      automatic = "Background preparation can start in the cleanup band. " + automatic;
+  }
+  return `Context attention:${where} (${band} band). ${automatic}
 ${lines.join(`
 `)}`;
 }
@@ -25090,11 +25117,12 @@ function smartCompactExtension(pi) {
     onContextEdit: (_ctx, kind) => hostCache.noteContextEdit(kind)
   });
   registerArtifactOffload(pi, automaticConfig, () => toolExposure.reachable("history"));
+  const canAutoTrim = (ctx) => toolExposure.reachable("history") && !background.hasWork() && !pendingRef.isPresent(resolveSessionId(ctx)) && !isRunning.isSessionActive(resolveSessionId(ctx));
   const smartContext = registerSmartContextTool(pi, {
     config: automaticConfig,
     isPaused: pivotQueued,
     canAgentMutate: () => policy.snapshot().agentToolAccess !== "disabled",
-    canAutoTrim: (ctx) => toolExposure.reachable("history") && !background.hasWork() && !pendingRef.isPresent(resolveSessionId(ctx)) && !isRunning.isSessionActive(resolveSessionId(ctx)),
+    canAutoTrim,
     onContextChange: (ctx) => invalidatePreparation(ctx, "branch"),
     onContextEdit: (_ctx, kind) => hostCache.noteContextEdit(kind),
     onCacheWarm: (ctx, at) => {
@@ -25105,6 +25133,7 @@ function smartCompactExtension(pi) {
   registerContextAttention(pi, {
     config: automaticConfig,
     canAgentAct: (ctx) => policy.snapshot().agentToolAccess !== "disabled" && !pivotQueued(ctx) && !isRunning.isSessionActive(resolveSessionId(ctx)),
+    canCleanup: canAutoTrim,
     reachable: (group) => toolExposure.reachable(group)
   });
   registerSmartCompactCommand(pi, {

package/dist/rtk.js

@@ -198,7 +198,7 @@ class SecretScrubber {
 }
 
 // src/constants.ts
-var VERSION = "10.2.0";
+var VERSION = "10.2.1";
 var OPTIONAL_COMPONENTS = {
   mnemopi: { name: "@oh-my-pi/pi-mnemopi", version: "18.3.1", enables: "Mnemopi memory store" },
   bun: { name: "bun", version: "1.4.2", enables: "Mnemopi worker runtime when no Bun 1.3.14+ is on PATH" },

package/docs/configuration.md

@@ -454,7 +454,7 @@ Settings → **Agent tools & navigation**.
 | `contextPivotEnabled` | `Return to an anchor` | `true` | Returning to an anchor on a new branch with a required carryover. |
 | `contextAnchorCacheEnabled` | `Anchor prompt cache` | `true` | Anthropic models: keeps a prompt-cache marker on the newest anchor. |
 | `contextAnchorStatusEnabled` | `Anchor status` | `true` | Shows the newest anchor on this branch in Pi's footer; display only. |
-| `contextGuidanceEnabled` | `Navigation guide` | `true` | Lets you or the agent open the navigation guide on request; it is never added to a request otherwise. Also enables context attention: one short note to the model when context usage enters the cleanup band and again at the compaction band, naming only the context tools available right now (anchor; checkpoint/rewind and trim when history edits are possible). Re-armed once pressure clears. |
+| `contextGuidanceEnabled` | `Navigation guide` | `true` | Lets you or the agent open the navigation guide on request; the full guide is never injected automatically. Also enables one short context-attention note per pressure band. Prompt-start advice uses current usage and permissions, not a parked `nextTurn` note. It names reachable tools, shares cleanup's preparation gate, and distinguishes automatic strategies and staging from applying. Checkpoint metadata can remain available when trim/rewind is blocked. Navigation off does not disable history guidance. Re-armed when pressure clears, compaction occurs or the session/model changes. |
 
 Group permissions apply in both `lazy` and `eager` modes: `compaction` follows
 `agentToolAccess`, `memory` needs `contextGraphEnabled` or a non-local

package/docs/guide.md

@@ -459,8 +459,9 @@ Settings → **Agent tools & navigation** has the switches: **Session
 navigation** (off hides the panel and the agent tool; recorded anchors and the
 other switches are kept), **Search other sessions**, **Return to an anchor**,
 **Anchor prompt cache** (Anthropic models: keeps a prompt-cache marker on the
-newest anchor, so the context before it is read from cache while later turns
-change), **Anchor status** (footer, display only) and **Navigation guide**.
+newest anchor so an unchanged prefix can be reused while later turns change;
+hits still depend on provider caching and expiry), **Anchor status** (footer,
+display only) and **Navigation guide**.
 
 Legacy `context` tool anchors recorded in earlier sessions stay readable in
 browse and search.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-smart-compact",
-	"version": "10.2.0",
+	"version": "10.2.1",
 	"description": "Pi Continuity — context hygiene and session continuity for Pi Coding Agent: recoverable cleanup, checkpoints, memory and verified compaction.",
 	"type": "module",
 	"packageManager": "bun@1.4.2",