@cad0p/pi-tree-navigator 0.1.1 → 0.1.2-20260824.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.2] - 2026-08-20
+
+<!-- USER-EDITABLE SECTION START -->
+Patch release: fixes rewind summarization for custom-api providers and eliminates 3 of the 5 reflection points via public APIs.
+
+**Rewind summarization for custom providers (#13):** `rewind` failed with `No API provider registered for api: <custom-id>` for any provider registered via `pi.registerProvider(name, { api: <custom-id>, streamSimple })` (e.g. pi-commandcode-provider 0.5.x with `api: "commandcode-custom"`). The summarizer now routes through the composed provider's `streamSimple`, obtained via the public `ctx.modelRegistry.getProvider(providerId)` API (pi ≥0.81.0) — the same routing pi's own `branchWithSummary` uses. Peer floor bumped to `>=0.81.0`; `null` header-deletion markers stripped (pi 0.84+ `ProviderHeaders`).
+
+**Reflection surface five → two (#14):** the per-turn in-loop context refresh no longer reads `agent.state.systemPrompt` / `agent.state.tools` or wraps `agent.prepareNextTurnWithContext` / `agent.prepareNextTurn`. Instead a `pi.on("context")` handler (the public `context` extension event, fired via `Agent.transformContext` before every LLM call) returns the session-tree projection `sessionManager.buildContextEntries().flatMap(sessionEntryToContextMessages)`. Pi's own `_installAgentNextTurnRefresh` keeps systemPrompt/tools/model/thinkingLevel fresh per turn. Remaining reflection points: `AgentSession.prototype.prompt` (session capture) and `agent.state.messages` (post-rewind refresh so the next prompt snapshots the rewound chain) — neither is eliminable via public APIs.
+
+Verified live on pi 0.84.2 (tmux TUI, commandcode provider): a 580KB file read (22.6% of 400k) rewound mid-loop to 1.0% of 400k with the very next LLM call at the rewound cache prefix (cacheRead 90,368 → 2,944). 125 tests pass; CI green.
+<!-- USER-EDITABLE SECTION END -->
+
+### 🐛 Bug Fixes
+
+- *(rewind)* Route summarization through provider streamSimple (public API) (closes #13)
+
+### 🚜 Refactor
+
+- Eliminate 3 of 5 reflection points via public context event (closes #14)
+
+### 📚 Documentation
+
+- Update reflection field count/versions and dev commands for v0.1.1 reality ([#9](https://github.com/cad0p/pi-tree-navigator/pull/9))
+- Port AGENTS.md bootstrap instructions from pi-napkin ([#11](https://github.com/cad0p/pi-tree-navigator/pull/11))
+
+
 ## [0.1.1] - 2026-07-31
 
 <!-- USER-EDITABLE SECTION START -->

package/README.md

@@ -34,12 +34,12 @@ This repo uses [`cad0p/semver-calver-release`](https://github.com/cad0p/semver-c
 
 ### Requirements
 
-- **pi 0.74+** with at least one model provider configured.
+- **pi 0.81+** (node ≥22.19, which pi 0.81+ itself requires) with at least one model provider configured.
 - Peer dependencies (the source of truth is `package.json` `peerDependencies`):
-  - `@earendil-works/pi-coding-agent >=0.74.0`
-  - `@earendil-works/pi-agent-core >=0.74.0`
+  - `@earendil-works/pi-coding-agent >=0.81.0`
+  - `@earendil-works/pi-agent-core >=0.81.0`
   - `typebox ^1.0.0` (used to declare the tool's parameter schema; bundled with pi but listed explicitly so a standalone install resolves correctly).
-- The reflection bootstrap depends on five plain (not `#`-private) internal pi/agent fields: `AgentSession.prototype.prompt`, `agent.state.messages`, `agent.state.systemPrompt`, `agent.state.tools`, and `agent.prepareNextTurn`. Verified against pi 0.75.x.
+- The reflection bootstrap depends on two plain (not `#`-private) internal pi/agent fields: `AgentSession.prototype.prompt` (patched for session capture) and `agent.state.messages` (refreshed after a rewind so the next prompt snapshots the rewound chain). Per-turn in-loop context refresh runs through the **public** `context` extension event (see “In-loop context refresh” below) — no `agent.prepareNextTurn*` reflection. Verified against pi 0.81.0 / 0.83.0 / 0.84.2.
 
 ## What you get
 
@@ -81,7 +81,7 @@ Why this is more involved than just calling pi's `branchWithSummary`:
 
 1. **Anthropic's tool_use ↔ tool_result pairing.** When a tool call rewinds the session tree, the tool's own `tool_use` lives in the assistant message that issued it — which `branchWithSummary` puts on the abandoned branch. Pi unconditionally writes the tool's `tool_result` to the new branch, leaving the result orphaned. Anthropic 400s the next API call with `Improperly formed request`. The fix is to inject a synthetic assistant message whose single `tool_call` has the same id as the in-flight call, *after* `branchWithSummary` but *before* the tool returns. Pi then writes the real `tool_result` as a child of that synthetic assistant — and the chain stays structurally valid.
 
-2. **In-loop context refresh.** Pi's `Agent` class snapshots `state.messages` once at the start of `prompt()` and pushes new messages onto its own array. A rewind issued mid-loop wouldn't reduce the next API call's size until the user sent a fresh prompt. We wire `agent.prepareNextTurn` from a prototype patch on `AgentSession.prototype.prompt`, returning a fresh context built from `sessionManager.buildSessionContext()` between every turn boundary. After a rewind, the very next assistant turn within the same `prompt()` sees the rewound chain.
+2. **In-loop context refresh.** Pi's `Agent` class snapshots `state.messages` once at the start of `prompt()` and pushes new messages onto its own array. A rewind issued mid-loop wouldn't reduce the next API call's size until the user sent a fresh prompt. We register a handler on pi's **public `context` extension event** — fired via `Agent.transformContext` → `runner.emitContext` before *every* LLM call, including the turn right after a mid-loop rewind — that replaces the wire messages with the session-tree projection (`sessionManager.buildContextEntries()` → `sessionEntryToContextMessages`). After a rewind, the very next assistant turn within the same `prompt()` sees the rewound chain. (This replaced the earlier `agent.prepareNextTurnWithContext` reflection wrapper.)
 
 3. **Reflection bootstrap.** Pi's slash-command `navigateTree` has access to `commandCtx.navigateTree`, which mutates `agent.state.messages`. Tool executes don't get that ctx, so we capture every `AgentSession` instance via the prompt patch and replicate the mutation manually. Without it, the on-disk leaf moves but `agent.state.messages` stays stale.
 
@@ -93,10 +93,14 @@ The synthetic assistant we inject after each rewind carries the **post-rewind ch
 
 ## Limitations
 
-- **Brittle to pi version bumps.** The fix uses five independent reflection points on internals that aren't part of pi's public API: `AgentSession.prototype.prompt`, `agent.state.messages`, `agent.state.systemPrompt`, `agent.state.tools`, and `agent.prepareNextTurn`. If a future pi release renames any of these, switches them to private (`#`) fields, or restructures the class hierarchy, this breaks. The extension fails loudly: `anchor` still works, `rewind` reports `⚠ reflection bootstrap missing — the rewind landed on disk but the next assistant turn may still see the pre-rewind context. Run \`/reload\` (or restart pi) to recover.`, and you'd see context corruption return on the next prompt.
+- **Brittle to pi version bumps.** The fix uses two independent reflection points on internals that aren't part of pi's public API: `AgentSession.prototype.prompt` (session capture) and `agent.state.messages` (refreshed after a rewind). A third reflection point (`agent.prepareNextTurn*`) was eliminated in v0.2.0 via the public `context` extension event; the per-turn systemPrompt/tools/model/thinkingLevel refreshes come from pi's own `_installAgentNextTurnRefresh` (construction-installed since 0.80.3). If a future pi release renames the two remaining fields, switches them to private (`#`) fields, or restructures the class hierarchy, this breaks. The extension fails loudly: `anchor` still works, `rewind` reports `⚠ reflection bootstrap missing — the rewind landed on disk but the next assistant turn may still see the pre-rewind context. Run \`/reload\` (or restart pi) to recover.`, and you'd see context corruption return on the next prompt.
+
+  **Audited against pi 0.81.0 / 0.83.0 / 0.84.2 (2026-08):** three of the five reflection points have been eliminated — `agent.state.systemPrompt` and `agent.state.tools` reads (deleted with the `prepareNextTurn` double-wrap; no longer needed since pi's own per-turn wrapper and the public `ctx.getSystemPrompt()` / `pi.getAllTools()` cover them) and `agent.prepareNextTurnWithContext` (replaced by the public `context` extension event, which fires via `transformContext` before **every** LLM call). The remaining two are NOT eliminable for the tool-based design: `AgentSession.prototype.prompt` (no public per-prompt hook for tool executes — the `context` event fires too late to install hooks before `createLoopConfig`) and `agent.state.messages` (pi's own `navigateTree` refresh is only reachable via `ctx.navigateTree()`, which exists solely on `ExtensionCommandContext`, not the `ExtensionContext` a `tool.execute` receives).
 
 - **Anchor early in the turn.** Whatever's in `agent.state.messages` *before* the `anchor` tool call stays in the kept chain. Everything after gets summarized. Anchor at the *start* of a stage for maximum context savings.
 
+- **Tiny rewinds are rejected by a minimum-savings floor.** A `rewind` whose measured savings falls below an internal floor (~4k tokens of apparent context freed) is refused with guidance listing the active anchors instead of executing — collapsing a near-empty segment burns a summarizer LLM call and can even grow live context once the summary and its synthetic assistant land on the kept chain. This pairs with anchoring early: anchor at the start of a stage, then rewind only once real work has accumulated above the anchor.
+
 - **Abandoned branches grow the JSONL forever.** Each rewind preserves the abandoned subtree on disk. Session files get bigger over time even as live context shrinks. For very long autonomous runs (days), session files can hit hundreds of MB.
 
 - **Tested against Anthropic and Kiro providers.** The synthetic-tool_use trick is specifically for Anthropic's strict tool_use/tool_result pairing; the synthetic's `stopReason: "toolUse"` survives Kiro's `normalizeMessages` filter. Other providers may have different validation rules — untested.
@@ -110,13 +114,13 @@ The synthetic assistant we inject after each rewind carries the **post-rewind ch
 ## Development
 
 ```bash
-bun install
-bun test          # helpers + dispatch / reflection bootstrap / salvage path
-bunx biome check extensions/
-bunx tsc --noEmit
+pnpm install
+pnpm test          # helpers + dispatch / reflection bootstrap / salvage path
+pnpm run lint      # biome check extensions/
+pnpm run typecheck # tsc --noEmit
 ```
 
-Tests cover `extensions/navigate-tree/helpers.ts` (pure helpers in `helpers.test.ts`) and `extensions/navigate-tree/index.ts` (action dispatch, schema shape, synthetic-assistant injection, reflection bootstrap, salvage path — in `index.test.ts`). The `summarize` factory option injects a stub for `generateBranchSummary` so no real LLM call fires during rewind tests. Additional manual e2e validation against pi 0.75.x is recommended for any pi version bump (the reflection bootstrap depends on internal field shapes).
+Tests cover `extensions/navigate-tree/helpers.ts` (pure helpers in `helpers.test.ts`) and `extensions/navigate-tree/index.ts` (action dispatch, schema shape, synthetic-assistant injection, context-event projection, reflection bootstrap, salvage path — in `index.test.ts`). The `summarize` factory option injects a stub for `generateBranchSummary` so no real LLM call fires during rewind tests. Additional manual e2e validation against the current pi release (0.84.x at time of writing) is recommended for any pi version bump (the reflection bootstrap depends on `AgentSession.prototype.prompt` / `agent.state.messages` field shapes).
 
 ## License
 

package/extensions/navigate-tree/index.ts

@@ -22,10 +22,8 @@
  *   this.agent.state.messages = this.sessionManager.buildSessionContext().messages;
  *
  * Risks of the reflection approach:
- *   • If pi switches any of the six fields this extension reads —
- *     `AgentSession.prototype.prompt`, `agent.state.messages`,
- *     `agent.state.systemPrompt`, `agent.state.tools`,
- *     `agent.prepareNextTurn`, or `agent.prepareNextTurnWithContext` —
+ *   • If pi switches either of the two fields this extension reads —
+ *     `AgentSession.prototype.prompt` or `agent.state.messages` —
  *     to ES `#` private fields, this breaks fundamentally.
  *   • If pi renames or restructures any of these fields, this breaks.
  *   • Patches `AgentSession.prototype.prompt` globally on import; not
@@ -33,20 +31,25 @@
  *     the pi process, including sessions that never call
  *     `navigate_tree`.
  *
- * Verified against pi 0.75.5 (`prepareNextTurn` path) and pi 0.83.0
- * (`prepareNextTurnWithContext` path — required since pi 0.80.3, see
- * `installPrepareNextTurn`).
+ * Verified against pi 0.81.0 / 0.83.0 / 0.84.2. In-loop context
+ * refresh runs through the public `context` extension event (see
+ * `buildContextMessages`), not `agent.prepareNextTurn*` reflection.
  */
 
-import { estimateContextTokens } from "@earendil-works/pi-agent-core";
+import {
+  estimateContextTokens,
+  type StreamFn,
+} from "@earendil-works/pi-agent-core";
 import {
   AgentSession,
   buildSessionContext,
   collectEntriesForBranchSummary,
   type ExtensionAPI,
   generateBranchSummary,
+  type ModelRegistry,
   type SessionEntry,
   type SessionManager,
+  sessionEntryToContextMessages,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import {
@@ -64,7 +67,8 @@ const LABEL_PREFIX = "anchor:";
 
 // ---------------------------------------------------------------------------
 // Exported boundary constants below (MAX_SESSION_REFS, MAX_HINT_WALK_DEPTH,
-// MIN_SUMMARY_FOCUS_LENGTH, MAX_SYNTHETIC_FOCUS_LENGTH).
+// MIN_SUMMARY_FOCUS_LENGTH, MIN_REWIND_SAVINGS_TOKENS,
+// MAX_SYNTHETIC_FOCUS_LENGTH).
 //
 // Stability: these are internal tunables. Exported only so the test suite
 // can pin boundary cases by constant rather than literal. Re-tuning is
@@ -92,6 +96,19 @@ export const MAX_HINT_WALK_DEPTH = 50;
 // reliably loses continuity — raising it forces more useful focus text
 // without inviting verbosity.
 export const MIN_SUMMARY_FOCUS_LENGTH = 20;
+// Floor on the *apparent* token savings (`beforeTokens − tokensAtTarget`) a
+// `rewind` must clear to execute. Absolute threshold, deliberately NOT
+// window-relative: % semantics drift with window size, so a fixed token bar
+// is the only stable shape. Every rewind carries ≈350–900 tokens of fixed
+// overhead (the branch_summary adds ~300–800 permanent tokens on the kept
+// chain; the synthetic assistant re-emits ~50 on every subsequent turn), so
+// apparent savings OVERSTATES true freed context. Empirically the degenerate
+// anchor→immediate-rewind case measures ~100 apparent tokens while a healthy
+// stage measures ~20k — 4k separates them cleanly (~200×) and roughly equals
+// one 300-line source-file read (~5.9k tokens measured). Below the floor a
+// rewind burns a summarizer LLM call, forks a junk branch_summary, consumes
+// a milestone label, and GROWS live context.
+export const MIN_REWIND_SAVINGS_TOKENS = 4000;
 // Cap on the `summaryFocus` length stored in the synthetic assistant's
 // arguments. The full focus is passed live to `generateBranchSummary`, so
 // the summarizer always sees the original; we only need a trimmed copy in
@@ -117,8 +134,6 @@ const LIST_PCT_COL_WIDTH = 5;
 // is 40, but the typical kebab-case name is 8–20 chars; 28 keeps the
 // hint column visible without truncating common names.
 const LIST_LABEL_COL_WIDTH = 28;
-const PNT_MARKER = Symbol.for("navigate-tree.pnt-installed");
-const PNTWC_MARKER = Symbol.for("navigate-tree.pntwc-installed");
 const ORIG_PROMPT_KEY = Symbol.for("navigate-tree.orig-prompt");
 
 // Two warnings: list-site (read-only path; warns about the next turn's
@@ -142,15 +157,8 @@ const REFLECTION_BOOTSTRAP_WARNING_REWIND =
 interface PiInternals {
   agent: {
     state: {
-      systemPrompt: string;
       messages: unknown[];
-      tools: unknown[];
     };
-    prepareNextTurn?: unknown;
-    // Preferred over `prepareNextTurn` by `Agent.createLoopConfig`
-    // when set; pi's own AgentSession always sets it (via
-    // `_installAgentNextTurnRefresh`) since pi-coding-agent 0.80.3.
-    prepareNextTurnWithContext?: unknown;
   };
   sessionManager: SessionManager;
 }
@@ -159,34 +167,6 @@ function asInternals(session: AgentSession): PiInternals {
   return session as unknown as PiInternals;
 }
 
-type PntResult = {
-  context?: {
-    systemPrompt?: unknown;
-    messages?: unknown[];
-    tools?: unknown[];
-    [k: string]: unknown;
-  };
-  model?: unknown;
-  thinkingLevel?: unknown;
-};
-// pi 0.75.5 invokes `agent.prepareNextTurn(signal)` from
-// `Agent.createLoopConfig` — a single AbortSignal argument. Since pi
-// 0.80.3 the loop instead invokes
-// `agent.prepareNextTurnWithContext(nextTurnContext, signal)` (and only
-// falls back to `prepareNextTurn` when the WithContext field is unset).
-// Both differ from the documented
-// `AgentLoopConfig.prepareNextTurn(context: PrepareNextTurnContext)`
-// shape, which `Agent` is bridging. We accept whatever pi passes and
-// forward it verbatim to the prior wrapper so we don't fight a future
-// signature alignment. Verified against pi-coding-agent 0.75.5 and
-// 0.83.0; revisit if the call site changes.
-type PntFn = (...args: unknown[]) => Promise<PntResult> | PntResult;
-type MarkedPntFn = PntFn & {
-  [PNT_MARKER]?: boolean;
-  [PNTWC_MARKER]?: boolean;
-  __prior?: PntFn;
-};
-
 // =============================================================================
 // Reflection bootstrap & in-loop refresh
 // =============================================================================
@@ -226,126 +206,11 @@ function patchAgentSessionPrototype(): void {
   // module and reflection finds nothing.
   const patched = function (this: AgentSession, ...args: unknown[]) {
     captureSession(this);
-    installPrepareNextTurn(this);
     return orig.apply(this, args);
   };
   proto.prompt = patched;
 }
 
-/**
- * Wire the in-flight agent loop to refresh its context from sessionManager
- * between turns within the same prompt() call. Without this, the loop
- * snapshots agent.state.messages once at prompt start and pushes new
- * messages onto its own array — a rewind issued mid-loop doesn't reduce
- * the next API call's size until the user sends a new prompt.
- *
- * Two hook fields, by pi version:
- *   • pi ≤0.80.2: `Agent.createLoopConfig` reads `agent.prepareNextTurn`.
- *   • pi ≥0.80.3: AgentSession's constructor installs its own
- *     `agent.prepareNextTurnWithContext` (`_installAgentNextTurnRefresh`),
- *     and `createLoopConfig` prefers that field over `prepareNextTurn`.
- *     Pi's wrapper refreshes systemPrompt/tools/model/thinkingLevel per
- *     turn but leaves `messages` stale — so wrapping only
- *     `prepareNextTurn` silently dead-ends (footer % and the wire context
- *     stay pre-rewind for the rest of the loop).
- *
- * We install on BOTH fields, each with the same marker/__prior chaining
- * discipline: on new pi the WithContext wrapper chains pi's own (keeping
- * its per-turn refreshes) and overrides only `messages`; on old pi the
- * WithContext field is never read and `prepareNextTurn` does the work.
- *
- * The Agent class's `createLoopConfig` dereferences both fields at the
- * closure call site, so the values here are read at every turn boundary.
- * But it gates the closure on either field being truthy at config
- * creation — so we have to set this BEFORE prompt() runs, hence wiring
- * it from inside the prompt patch.
- */
-function installPrepareNextTurn(session: AgentSession): void {
-  const internals = asInternals(session);
-  const agent = internals.agent;
-  if (!agent) return;
-
-  const sm = internals.sessionManager;
-
-  // If the existing hooks were installed by a previous load of THIS
-  // extension, recover the chains they captured (their `__prior`) so we
-  // don't strand other extensions' closures across /reload. Preserve any
-  // other extension's (or pi's own) hooks so we compose with them.
-  const existing = agent.prepareNextTurn as MarkedPntFn | undefined;
-  const prior: PntFn | undefined =
-    typeof existing === "function" && existing[PNT_MARKER]
-      ? existing.__prior
-      : (existing as PntFn | undefined);
-  const existingWc = agent.prepareNextTurnWithContext as
-    | MarkedPntFn
-    | undefined;
-  const priorWc: PntFn | undefined =
-    typeof existingWc === "function" && existingWc[PNTWC_MARKER]
-      ? existingWc.__prior
-      : (existingWc as PntFn | undefined);
-
-  const next: MarkedPntFn = async (...args: unknown[]) => {
-    let priorResult: PntResult | undefined;
-    if (typeof prior === "function") {
-      priorResult = await prior(...args);
-    }
-    // Pi's loop replaces context wholesale (`currentContext = ctx ??
-    // currentContext`), not field-merges — a prior wrapper that returns
-    // a partial context (e.g. only systemPrompt) would silently drop
-    // tools. Spread the prior first so its fields survive, then fall
-    // back to `agent.state` for any field the prior left undefined.
-    // `messages` is owned by this wrapper.
-    const priorContext = priorResult?.context;
-    return {
-      context: {
-        ...priorContext,
-        systemPrompt: priorContext?.systemPrompt ?? agent.state.systemPrompt,
-        tools: priorContext?.tools ?? agent.state.tools,
-        messages: sm.buildSessionContext().messages,
-      },
-      model: priorResult?.model,
-      thinkingLevel: priorResult?.thinkingLevel,
-    };
-  };
-  next[PNT_MARKER] = true;
-  next.__prior = prior;
-  agent.prepareNextTurn = next;
-
-  const nextWc: MarkedPntFn = async (...args: unknown[]) => {
-    // On pi ≥0.80.3 the loop calls this as (nextTurnContext, signal),
-    // where nextTurnContext = { message, toolResults, context,
-    // newMessages }. Forward args verbatim to the prior (pi's own
-    // wrapper expects exactly this shape).
-    const turn = args[0] as { context?: PntResult["context"] } | undefined;
-    let priorResult: PntResult | undefined;
-    if (typeof priorWc === "function") {
-      priorResult = await priorWc(...args);
-    }
-    // Same wholesale-replacement rationale as the prepareNextTurn
-    // wrapper above. When no prior result exists, fall back to the
-    // turn's live context (mirrors pi's own wrapper, which does
-    // `previousSnapshot?.context ?? turn.context`) so systemPrompt and
-    // tools are never dropped. `messages` is owned by this wrapper —
-    // this override is the entire point of the hook on pi ≥0.80.3, whose
-    // own wrapper refreshes every other field but leaves messages stale.
-    const priorContext = priorResult?.context ?? turn?.context;
-    return {
-      ...priorResult,
-      context: {
-        ...priorContext,
-        systemPrompt: priorContext?.systemPrompt ?? agent.state.systemPrompt,
-        tools: priorContext?.tools ?? agent.state.tools,
-        messages: sm.buildSessionContext().messages,
-      },
-      model: priorResult?.model,
-      thinkingLevel: priorResult?.thinkingLevel,
-    };
-  };
-  nextWc[PNTWC_MARKER] = true;
-  nextWc.__prior = priorWc;
-  agent.prepareNextTurnWithContext = nextWc;
-}
-
 function findOwningSession(sm: SessionManager): AgentSession | null {
   for (const ref of sessionInstances) {
     const s = ref.deref();
@@ -356,6 +221,78 @@ function findOwningSession(sm: SessionManager): AgentSession | null {
   return null;
 }
 
+/**
+ * Resolve the provider's `streamSimple` for summarization routing via the
+ * PUBLIC modelRegistry API (no reflection).
+ *
+ * Custom providers registered via `pi.registerProvider(name, { api:
+ * <custom-id>, streamSimple })` are composed into the ModelRuntime provider
+ * returned by `ctx.modelRegistry.getProvider(...)` — its `streamSimple`
+ * dispatches to the extension handler (provider-composer `streamWith`).
+ * Without passing it as `streamFn` to `generateBranchSummary`,
+ * completeSummarization falls back to the pi-ai compat registry (builtin
+ * apis only) and throws "No API provider registered for api: <custom-id>".
+ */
+function resolveProviderStreamFn(
+  modelRegistry: ModelRegistry,
+  providerId: string,
+): { streamFn: StreamFn } | undefined {
+  try {
+    const provider = modelRegistry.getProvider(providerId);
+    return provider?.streamSimple
+      ? { streamFn: provider.streamSimple as StreamFn }
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Drop `null` header-deletion markers (pi 0.84+ `ProviderHeaders` can carry
+ * `string | null` values). Mirrors pi's own `withoutDeletedHeaders` in
+ * agent-session.js — `generateBranchSummary` expects `Record<string, string>`.
+ */
+function stripNullHeaders(
+  headers: Record<string, string | null> | undefined,
+): Record<string, string> | undefined {
+  if (!headers) return undefined;
+  const entries = Object.entries(headers).filter((entry) => entry[1] !== null);
+  return entries.length > 0
+    ? (Object.fromEntries(entries) as Record<string, string>)
+    : undefined;
+}
+
+/**
+ * Project the session tree's active branch into the messages the next LLM
+ * call should see — the public-API replacement for the deleted
+ * `prepareNextTurn` double-wrap (which rebuilt `messages` from
+ * `sessionManager.buildSessionContext()` between every turn).
+ *
+ * Registered as a `context` extension handler: pi fires the `context` event
+ * inside `streamAssistantResponse` before EVERY LLM call (wired through
+ * `Agent.transformContext` → `runner.emitContext`), so this projection is
+ * applied at the wire boundary itself rather than at a turn-boundary
+ * snapshot. The loop's own `currentContext.messages` is never mutated — the
+ * handler only replaces the clone that `convertToLlm` consumes.
+ *
+ * We always replace (no leaf-gating): every `appendMessage` advances the
+ * session leaf, so a "leaf changed since last turn" heuristic would fire on
+ * essentially every call anyway — and always-replace is byte-for-byte the
+ * behavior of the old wrapper (per-turn rebuild from the tree).
+ *
+ * The parameter is typed structurally because `ReadonlySessionManager` is
+ * NOT re-exported from the package barrel (only `SessionManager` and
+ * `sessionEntryToContextMessages` are public); `ctx.sessionManager` at the
+ * event site is `ReadonlySessionManager`, which has `buildContextEntries()`.
+ */
+export function buildContextMessages(sm: {
+  buildContextEntries(): SessionEntry[];
+}): ReturnType<typeof sessionEntryToContextMessages> {
+  return sm
+    .buildContextEntries()
+    .flatMap((entry) => sessionEntryToContextMessages(entry));
+}
+
 function refreshAgentMessages(sm: SessionManager): boolean {
   // Manually replicate the agent-state refresh that pi's
   // commandCtx.navigateTree does after branchWithSummary. Returns true on
@@ -404,6 +341,49 @@ function estimateAtEntry(
   ).tokens;
 }
 
+/**
+ * Rejection copy for the rewind min-savings floor (#21). Reports the
+ * apparent savings plus every active anchor — chronological root→leaf,
+ * same walk order as `list`, including labelStart itself — with its
+ * cumulative context percentage, so the agent can pick a genuinely earlier
+ * anchor or keep working. Move-on-collision means the tool itself never
+ * creates duplicate anchor names; a manual `/label anchor:x` CAN put the
+ * same name on two entries — duplicates print twice here, exactly as
+ * `list` prints them today.
+ *
+ * Deliberately does NOT print the floor value anywhere: an agent-visible
+ * numeric bar invites grinding up to it instead of doing real work.
+ */
+function buildMinSavingsRejection(
+  labelStart: string,
+  labelEnd: string,
+  apparentSavings: number,
+  sm: SessionManager,
+  cw: number,
+  allEntries: SessionEntry[],
+  byId: Map<string, SessionEntry>,
+): string {
+  const anchors: string[] = [];
+  let oldestAnchorName: string | null = null;
+  for (const e of sm.getBranch()) {
+    const lbl = sm.getLabel(e.id);
+    if (!lbl?.startsWith(LABEL_PREFIX)) continue;
+    const name = lbl.slice(LABEL_PREFIX.length);
+    if (!oldestAnchorName) oldestAnchorName = name;
+    anchors.push(
+      `'${name}' ${formatPct1(estimateAtEntry(allEntries, e.id, byId), cw)}`,
+    );
+  }
+  // cw=0 → percents fall back to formatPct1's k-format and the window
+  // suffix is omitted, mirroring `list`'s header behavior.
+  const suffix = cw > 0 ? ` of ${formatWindow(cw)}` : "";
+  const guidance =
+    oldestAnchorName === labelStart
+      ? "No earlier anchors — keep working and rewind later once more has accumulated above it."
+      : "Rewind further back to actually free context, or keep working.";
+  return `Rewinding '${labelStart}' → '${labelEnd}' would free only ~${formatPct1(apparentSavings, 0)} tokens. ${guidance} Active anchors: ${anchors.join(" · ")}${suffix}`;
+}
+
 /**
  * Walk parentId chain back from `fromId` and return a one-line preview of
  * the first entry that has meaningful text content. Branch summaries are
@@ -518,12 +498,26 @@ export default function (
   const summarize = opts?.summarize ?? generateBranchSummary;
   patchAgentSessionPrototype();
 
+  // Public context event: replace the wire messages with the session-tree
+  // projection before every LLM call. This is the public-API replacement for
+  // the deleted `agent.prepareNextTurnWithContext` per-turn refresh — it
+  // fires inside `streamAssistantResponse` (via `Agent.transformContext` →
+  // `runner.emitContext`), before EVERY LLM call including the turn right
+  // after a mid-loop rewind, so the rewound chain (branch_summary +
+  // synthetic assistant + tool_result) reaches the next API call.
+  pi.on("context", (_event, ctx) => ({
+    messages: buildContextMessages(ctx.sessionManager),
+  }));
+
   pi.registerTool({
     name: "navigate_tree",
     label: "Navigate Tree",
     // Stateful: every action mutates SessionManager; concurrent calls would
     // race on `leafId` / `labelsById` and produce an undefined tree.
     executionMode: "sequential",
+    promptGuidelines: [
+      "navigate_tree: the further back you rewind, the more you free but the more collapses into the summary; pick the earliest anchor that still preserves what you need next.",
+    ],
     description: `Long-session context management via the pi session tree. Anchor named milestones, then collapse work between them into a model-generated summary while preserving the full history on a sibling branch. Despite the verb, \`rewind\` does not restore prior state — it forks a sibling branch from the anchor and continues forward from a model-generated summary; the abandoned subtree is preserved on disk but no longer on the active path.
 
 Operations (set the \`action\` parameter):
@@ -661,7 +655,7 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
               type: "text",
               text:
                 `[anchor '${p.name}'] set at ${positionLine}${hintLine}\n\n` +
-                `When you finish this stage, call: navigate_tree(action='rewind', labelStart='${p.name}', labelEnd='<milestone-name>', summaryFocus='<≥${MIN_SUMMARY_FOCUS_LENGTH}-char focus: latest user instruction + done + remaining>').`,
+                `Once real work has accumulated after this anchor, collapse it into a summary with: navigate_tree(action='rewind', labelStart='${p.name}', labelEnd='<milestone-name>', summaryFocus='<≥${MIN_SUMMARY_FOCUS_LENGTH}-char focus: latest user instruction + done + remaining>').`,
             },
           ],
           details: {
@@ -713,15 +707,13 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
         );
       }
 
-      if (!ctx.model) {
-        return toolError("No model configured for summarization.");
-      }
-
-      const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
-      if (!auth.ok) {
-        return toolError(`Auth resolution failed: ${auth.error}`);
-      }
-
+      // Token math hoisted ABOVE the model check / auth await (#21): these
+      // are pure SessionManager reads, and the min-savings floor below must
+      // be evaluable — and able to reject — before any auth resolution.
+      // `allEntries`/`byId` are hoisted out of the parented-assistant branch
+      // because the floor rejection copy reports per-anchor percentages from
+      // the same maps.
+      //
       // The leaf at execute time is the assistant that just streamed the
       // rewind tool call. Its `usage.input` is the *minimum* of recent API
       // calls in this turn, so estimating from it understates what the
@@ -729,6 +721,9 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
       // assistant's usage as baseline) so beforeTokens matches the value
       // `list` would have reported on the previous turn.
       const oldLeafEntry = sm.getEntry(oldLeaf);
+      const allEntries = sm.getEntries();
+      const byId = new Map<string, SessionEntry>();
+      for (const e of allEntries) byId.set(e.id, e);
       let beforeTokens: number;
       if (
         oldLeafEntry &&
@@ -736,14 +731,12 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
         oldLeafEntry.message.role === "assistant" &&
         oldLeafEntry.parentId
       ) {
-        const allEntries = sm.getEntries();
-        const byId = new Map<string, SessionEntry>();
-        for (const e of allEntries) byId.set(e.id, e);
         beforeTokens = estimateAtEntry(allEntries, oldLeafEntry.parentId, byId);
       } else {
         beforeTokens = estimateActiveBranchTokens(sm);
       }
-      const contextWindow = ctx.model.contextWindow ?? 0;
+      const tokensAtTarget = estimateAtEntry(allEntries, target, byId);
+      const contextWindow = ctx.model?.contextWindow ?? 0;
 
       const { entries } = collectEntriesForBranchSummary(sm, oldLeaf, target);
       if (entries.length === 0) {
@@ -786,12 +779,61 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
         }
       }
 
+      // Minimum-savings floor (#21): refuse rewinds whose apparent savings
+      // is below MIN_REWIND_SAVINGS_TOKENS — collapsing a near-empty segment
+      // burns a summarizer LLM call, forks a junk branch_summary, consumes
+      // a milestone label, and grows live context. Placed AFTER the
+      // synthetic-boundary guard so the chained rewind-with-no-turns case
+      // keeps its specific diagnostic, and BEFORE the model/auth checks so
+      // the rejection fires without touching provider config.
+      const apparentSavings = beforeTokens - tokensAtTarget;
+      if (apparentSavings < MIN_REWIND_SAVINGS_TOKENS) {
+        return toolError(
+          buildMinSavingsRejection(
+            p.labelStart,
+            p.labelEnd,
+            apparentSavings,
+            sm,
+            contextWindow,
+            allEntries,
+            byId,
+          ),
+          { rejected: "min-savings", apparentSavings },
+        );
+      }
+
+      if (!ctx.model) {
+        return toolError("No model configured for summarization.");
+      }
+
+      const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+      if (!auth.ok) {
+        return toolError(`Auth resolution failed: ${auth.error}`);
+      }
+
       const result = await summarize(entries, {
-        model: ctx.model,
+        // `auth.baseUrl` (OAuth/credential-derived endpoint, e.g.
+        // githubCopilotOAuth) must be applied to the model, mirroring pi's
+        // own `_getSummarizationRequestAuth` (`result.auth.baseUrl ?
+        // { ...model, baseUrl: result.auth.baseUrl } : model`).
+        model: auth.baseUrl
+          ? { ...ctx.model, baseUrl: auth.baseUrl }
+          : ctx.model,
         apiKey: auth.apiKey ?? "",
-        headers: auth.headers,
+        headers: stripNullHeaders(auth.headers),
+        ...(auth.env ? { env: auth.env } : {}),
         signal: signal ?? new AbortController().signal,
         customInstructions: p.summaryFocus,
+        // Route through the composed provider's `streamSimple` (public
+        // modelRegistry API) instead of the pi-ai compat registry.
+        // Custom providers registered via `pi.registerProvider(name,
+        // { api: <custom-id>, streamSimple })` are NOT visible to the
+        // compat registry (which only knows builtin apis) — without this,
+        // rewind fails with "No API provider registered for api:
+        // <custom-id>" for any custom-api provider (e.g. commandcode 0.5.x
+        // with api "commandcode-custom").
+        ...(resolveProviderStreamFn(ctx.modelRegistry, ctx.model.provider) ??
+          {}),
       });
       if (result.aborted) {
         return toolError("Summarization aborted.");
@@ -1002,14 +1044,9 @@ export const __testHooks = {
   buildSyntheticAssistant,
   findLabelHint,
   findLabeledEntry,
-  installPrepareNextTurn,
+  buildContextMessages,
   refreshAgentMessages,
   captureSession,
-  /** Symbols used to mark the wrappers installed by `installPrepareNextTurn`
-   * (`PNT_MARKER` on `agent.prepareNextTurn`, `PNTWC_MARKER` on
-   * `agent.prepareNextTurnWithContext` — the field pi ≥0.80.3 prefers). */
-  PNT_MARKER,
-  PNTWC_MARKER,
   /** Read-only view of captured-session ref count for reaping assertions. */
   sessionRefCount(): number {
     return sessionInstances.length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cad0p/pi-tree-navigator",
-  "version": "0.1.1",
+  "version": "0.1.2-20260824.0",
   "description": "agent-callable session tree navigation for pi: anchor named milestones, rewind work into a branch summary, free up context for long autonomous sessions",
   "publishConfig": {
     "access": "public",
@@ -47,8 +47,8 @@
     "typescript": "^5.8.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.74.0",
-    "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "@earendil-works/pi-agent-core": ">=0.81.0",
+    "@earendil-works/pi-coding-agent": ">=0.81.0",
     "typebox": "^1.0.0"
   },
   "license": "MIT"