@cad0p/pi-tree-navigator 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-05-25
+
+<!-- USER-EDITABLE SECTION START -->
+
+Initial release.
+
+`navigate_tree` is an agent-callable pi tool with three actions:
+
+- `anchor` — label the current point in the conversation as a milestone.
+- `rewind` — collapse work between an anchor and the current leaf into a model-generated `branch_summary`, freeing context.
+- `list` — show all anchors on the active branch with cumulative context %.
+
+Designed for long autonomous sessions where the agent itself decides when to summarize. Survives mid-loop rewinds (the next assistant turn within the same `prompt()` call sees the reduced context) and produces structurally valid Anthropic chains by injecting a synthetic `tool_use` to pair with the rewind's `tool_result`.
+
+User-visible specifics worth knowing on day one:
+
+- Anchor names are kebab-case (lowercase alphanumeric segments separated by single hyphens; max 40 chars). Re-anchoring with a name already on the active branch moves the prior label to the new leaf rather than duplicating it; the same move-on-collision applies to `rewind`'s `labelEnd`.
+- `rewind` requires a `summaryFocus` of ≥20 chars after trim; the rejection message lists what the focus should preserve so the agent can self-correct without user intervention.
+- The `branch_summary` boilerplate strip in `list` hints is sentinel-anchored — a user-authored doc whose first H2 happens to be `## Goal` is preserved untouched.
+- If the `AgentSession.prototype` patch isn't installed (typically only after a pi internals shape change), `list` and `rewind` surface a `⚠ reflection bootstrap missing` warning. The hint suggests `/reload` first (lighter — re-runs the prototype patch on the current process) and `Restart pi` as the heavier-handed alternative.
+
+<!-- USER-EDITABLE SECTION END -->

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pier Carlo Cadoppi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# pi-tree-navigator
+
+🌳 Agent-callable session tree navigation for [pi](https://github.com/badlogic/pi-mono).
+
+Lets a pi agent anchor named milestones in its own conversation, then collapse work between them into a model-generated `branch_summary` to free up context — without tripping Anthropic's `tool_use` ↔ `tool_result` validation, and with the freed context immediately available to the next assistant turn (even within the same `prompt()` call).
+
+## Install
+
+```bash
+pi install git:github.com/cad0p/pi-tree-navigator
+```
+
+> **Status:** v0.1.0 is not yet on the npm registry (pending OIDC trusted-publisher setup). Install from the git source for now.
+
+<details>
+<summary>Once published / pre-release installs</summary>
+
+- Stable (once published to npm):
+
+  ```bash
+  pi install npm:@cad0p/pi-tree-navigator
+  ```
+
+- Pre-release (calver snapshots from `main`, published to npm `@next` on every push):
+
+  ```bash
+  pi install npm:@cad0p/pi-tree-navigator@next
+  ```
+
+</details>
+
+### Requirements
+
+- **pi 0.74+** 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`
+  - `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.
+
+## What you get
+
+A single agent-callable tool, `navigate_tree`, with three actions:
+
+| action | params | effect |
+|---|---|---|
+| `anchor` | `name` | Label the current point in the conversation as a milestone. |
+| `rewind` | `labelStart`, `labelEnd`, `summaryFocus` | Collapse work between `labelStart` and the current leaf into a `branch_summary` entry. The summary is itself labeled with `labelEnd`, so you can chain rewinds. `summaryFocus` is required (non-trivial focus required; floor enforced at runtime by `MIN_SUMMARY_FOCUS_LENGTH`). Despite the verb, `rewind` does not restore prior state — it forks a sibling branch from `labelStart` and continues forward from a model-generated summary; the original subtree is preserved on disk but no longer on the active path. |
+| `list` | — | Show all anchors on the active branch with cumulative context %. |
+
+`name` (written by `anchor`) and `labelEnd` (written by `rewind`) both share the reserved `anchor:` label prefix; `labelStart` resolves against that same namespace. Every label written by `anchor` and every `labelEnd` written by `rewind` is referenceable by any subsequent `rewind`'s `labelStart`, and `list` shows all of them.
+
+## How it works
+
+A typical autonomous-loop pattern:
+
+```
+agent: navigate_tree(action="anchor", name="impl-start")
+  → [anchor 'impl-start'] set at 1.9% of 1.0M (after: “implement the parser”)
+
+agent: ...does work, runs tools, accumulates context to 30%...
+
+agent: navigate_tree(action="rewind", labelStart="impl-start", labelEnd="impl-end",
+                     summaryFocus="record only the public API of the parser
+                                   and the open issue with edge case X")
+  → [rewind 'impl-start' → 'impl-end'] · context 30.4% → 4.1% of 1.0M
+  → A branch_summary recording the work just collapsed has been appended
+    to your context. Items under '### Done' are complete. ...
+
+agent: ...continues with the freed context, the next API call is back at ~4%...
+```
+
+The freed context is available to the **next assistant turn within the same `prompt()` call**, not just on the next user prompt. This is the key feature — autonomous agents don't have to wait for a user round-trip to benefit from a rewind.
+
+## Implementation notes
+
+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.
+
+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.
+
+4. **`summaryFocus` is mandatory.** The summary is the only thing the agent will see of the collapsed work. The first time the agent uses `rewind`, blanket prompts produce vague summaries; subsequent rewinds are weaker. Forcing the agent to articulate `summaryFocus` (passed to pi's `generateBranchSummary` as `customInstructions`) measurably improves what survives.
+
+### Synthetic assistant token bias
+
+The synthetic assistant we inject after each rewind carries the **post-rewind chain estimate** in `usage.totalTokens` (so `estimateContextTokens` reads a sensible baseline immediately after the move). The synthetic itself adds a ~50-token toolCall block re-emitted on every subsequent turn until the next rewind — that overhead is **not** reflected in any `usage.*` field, so future `estimateContextTokens` calls understate the chain by ~50 tokens until the next assistant turn writes a fresh usage block. Negligible at typical anchor cadence; mention if you're benchmarking exact token deltas, ignore otherwise.
+
+## 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.
+
+- **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.
+
+- **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.
+
+- **Loading the extension monkey-patches `AgentSession.prototype.prompt` globally.** Every session in the host pi process picks up the patch on import, including sessions that never call `navigate_tree`. The patch is install-on-import and not reversible within a running pi process; restart pi to fully unload it.
+
+- **`anchor:` is a reserved label prefix.** Any label written via pi's `/label` command or by another extension that begins with `anchor:` will be picked up by `list` and addressable by `rewind`'s `labelStart` / `labelEnd`. Avoid the prefix in manually-set labels.
+
+- **Disk-fault during `rewind` (rare).** Pi's `branchWithSummary` advances the in-memory leaf before persisting the new entry to disk. If pi's session-write fails mid-call (full disk, FS error on a persisted session), the in-memory leaf has already moved past the original assistant turn but the synthetic-assistant injection in this extension never runs — pi's tool-result then lands without a matching tool_use, surfacing as the same `context_length_exceeded` 400 the synthetic exists to prevent. Production risk: low (in-memory tests don't reach this case; pi's session-write is robust on POSIX disk). Tracked for an additional salvage layer wrapping `branchWithSummary` itself in v0.2.0.
+
+## Development
+
+```bash
+bun install
+bun test          # helpers + dispatch / reflection bootstrap / salvage path
+bunx biome check extensions/
+bunx 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).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/extensions/navigate-tree/helpers.ts

@@ -0,0 +1,135 @@
+/**
+ * Pure helpers for the navigate-tree extension.
+ *
+ * Imported by `./index.ts` and `./helpers.test.ts`. Pi's extension loader
+ * loads `./index.ts` and ignores everything else in this directory unless
+ * referenced from there — so this file isn't loaded as a separate extension.
+ *
+ * No pi runtime imports — these are pure functions over plain JS values.
+ */
+
+// ---------------------------------------------------------------------------
+// Exported boundary constants below (MAX_NAME_LENGTH, MAX_BOILERPLATE_LEAD_IN).
+//
+// Stability: these are internal tunables. Exported only so the test suite
+// can pin boundary cases by constant rather than literal. Re-tuning is
+// NOT a semver-breaking change for this package — production callers
+// should rely on the registered `navigate_tree` tool surface, not import
+// these constants directly.
+// ---------------------------------------------------------------------------
+
+// Hard cap on label-name length. 40 chars accommodates descriptive names
+// (e.g. 'parser-edge-case-investigation', 31 chars) while keeping list
+// output column-friendly under common terminal widths and preventing a
+// runaway label string from poisoning the JSONL on disk.
+export const MAX_NAME_LENGTH = 40;
+/**
+ * Kebab-case anchor name: lowercase alphanumeric segments separated by
+ * single hyphens. No leading / trailing / double hyphens (the `isValidName`
+ * test suite enforces these rejections). Mirrors the pattern documented in
+ * the tool description and README — if this regex relaxes, both surfaces
+ * need the same update.
+ */
+const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+// Maximum lead-in distance for pi's branch-summary boilerplate marker.
+// Pi's standard prelude ("The user explored a different conversation
+// branch...") fits in the first ~150 chars; 200 is a generous upper bound.
+// A "## Goal" found later than this is treated as in-content prose, not
+// the boilerplate marker, and the strip is a no-op.
+export const MAX_BOILERPLATE_LEAD_IN = 200;
+
+// Sentinel that pi's branch-summary prelude always starts with. Gating
+// the strip on this prefix makes the helper a no-op for any non-
+// boilerplate text that happens to contain `## Goal` early (e.g. a
+// user-authored markdown doc whose first H2 is "Goal"). Verified
+// against pi 0.75.5's `dist/core/compaction/branch-summarization.js`;
+// if pi reworks the prelude wording, the strip falls back to a no-op
+// (`findLabelHint` shows the unmodified prelude). Verify when bumping
+// the peer-dep floor.
+const BRANCH_SUMMARY_SENTINEL =
+  "The user explored a different conversation branch";
+
+// Pi 0.75.5's branch-summary boilerplate places `## Goal` after the prelude
+// (verified against `dist/core/compaction/branch-summarization.js`). Used to
+// anchor the strip cut-point in `stripBranchSummaryBoilerplate` — a single
+// constant so the indexOf probe and the slice-length advance can't drift.
+const GOAL_HEADER = "## Goal";
+
+/** Validate a kebab-case name suitable for use as a navigate-tree label. */
+export function isValidName(s: unknown): s is string {
+  return (
+    typeof s === "string" &&
+    s.length > 0 &&
+    s.length <= MAX_NAME_LENGTH &&
+    NAME_RE.test(s)
+  );
+}
+
+/** Truncate text to a one-line preview, collapsing whitespace. */
+export function toOneLine(text: string, maxLen: number): string | null {
+  const t = text.replace(/\s+/g, " ").trim();
+  if (t.length === 0) return null;
+  if (maxLen <= 1) return t.length > 0 ? "…" : null;
+  return t.length > maxLen ? `${t.slice(0, maxLen - 1)}…` : t;
+}
+
+/**
+ * Format token count as a percentage with one decimal, or as `Nk` if no window.
+ */
+export function formatPct1(tokens: number, contextWindow: number): string {
+  if (contextWindow <= 0) return `${(tokens / 1000).toFixed(1)}k`;
+  return `${((tokens / contextWindow) * 100).toFixed(1)}%`;
+}
+
+/** Format a context window size as `1.0M` or `200k`. Empty string when unknown. */
+export function formatWindow(contextWindow: number): string {
+  if (contextWindow <= 0) return "";
+  if (contextWindow >= 1_000_000)
+    return `${(contextWindow / 1_000_000).toFixed(1)}M`;
+  return `${(contextWindow / 1000).toFixed(0)}k`;
+}
+
+export function formatContextDelta(
+  beforeTokens: number,
+  afterTokens: number,
+  contextWindow: number,
+): string {
+  if (contextWindow > 0) {
+    return `context ${formatPct1(beforeTokens, contextWindow)} → ${formatPct1(afterTokens, contextWindow)} of ${formatWindow(contextWindow)}`;
+  }
+  return `tokens ${beforeTokens} → ${afterTokens}`;
+}
+
+/**
+ * Strip pi's standard branch-summary boilerplate ("The user explored a
+ * different conversation branch...") so the hint shows the actual content.
+ */
+export function stripBranchSummaryBoilerplate(text: string): string {
+  if (!text.startsWith(BRANCH_SUMMARY_SENTINEL)) return text;
+  const goalIdx = text.indexOf(GOAL_HEADER);
+  if (goalIdx > 0 && goalIdx < MAX_BOILERPLATE_LEAD_IN) {
+    return text.slice(goalIdx + GOAL_HEADER.length);
+  }
+  return text;
+}
+
+/**
+ * Extract a string from a message-like content field. Handles both the
+ * legacy string shape and the modern array-of-blocks shape, joining all
+ * text blocks with spaces.
+ */
+export function extractTextContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(
+      (c): c is { type: "text"; text: string } =>
+        typeof c === "object" &&
+        c !== null &&
+        (c as { type?: string }).type === "text" &&
+        typeof (c as { text?: unknown }).text === "string",
+    )
+    .map((c) => c.text)
+    .join(" ");
+}

package/extensions/navigate-tree/index.ts

@@ -0,0 +1,952 @@
+/**
+ * navigate-tree — agent-callable session tree navigation.
+ *
+ * See README “Implementation notes” for the user-facing narrative
+ * (Anthropic tool_use↔tool_result pairing, same-loop context refresh,
+ * reflection bootstrap). This file-level JSDoc carries only
+ * source-internal facts the README doesn't.
+ *
+ * `/tree`-visible artifacts (empirical):
+ *   • Synthetic assistant message right after each `branch_summary`,
+ *     with one tool_call sharing the in-flight `toolCallId`.
+ *   • Dangling tool_use on the anchor entry whose original
+ *     tool_results were cut off by the rewind. Anthropic accepts this
+ *     — the dangling tool_use is buffered behind the branch_summary's
+ *     user-text rendering and the API doesn't reject it. No walk-up
+ *     logic at anchor time.
+ *
+ * Reflection bootstrap replicates pi's own slash-command line
+ * verbatim (kept symmetric so a pi rename here surfaces as the
+ * runtime warning rather than silently drifting):
+ *
+ *   this.agent.state.messages = this.sessionManager.buildSessionContext().messages;
+ *
+ * Risks of the reflection approach:
+ *   • If pi switches any of the five fields this extension reads —
+ *     `AgentSession.prototype.prompt`, `agent.state.messages`,
+ *     `agent.state.systemPrompt`, `agent.state.tools`, or
+ *     `agent.prepareNextTurn` — 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
+ *     reversible without a process restart; affects every session in
+ *     the pi process, including sessions that never call
+ *     `navigate_tree`.
+ *
+ * Verified against pi 0.75.5.
+ */
+
+import { estimateContextTokens } from "@earendil-works/pi-agent-core";
+import {
+  AgentSession,
+  buildSessionContext,
+  collectEntriesForBranchSummary,
+  type ExtensionAPI,
+  generateBranchSummary,
+  type SessionEntry,
+  type SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+  extractTextContent,
+  formatContextDelta,
+  formatPct1,
+  formatWindow,
+  isValidName,
+  MAX_NAME_LENGTH,
+  stripBranchSummaryBoilerplate,
+  toOneLine,
+} from "./helpers.ts";
+
+const LABEL_PREFIX = "anchor:";
+
+// ---------------------------------------------------------------------------
+// Exported boundary constants below (MAX_SESSION_REFS, MAX_HINT_WALK_DEPTH,
+// MIN_SUMMARY_FOCUS_LENGTH, 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
+// NOT a semver-breaking change for this package — production callers
+// should rely on the registered `navigate_tree` tool surface, not import
+// these constants directly. The `__testHooks` JSDoc carries the same
+// caveat for module-internal helpers.
+// ---------------------------------------------------------------------------
+
+// Cap on captured AgentSession refs across /new + /resume + /reload cycles.
+// Worst case is ~one ref per long-lived session before reaping dead WeakRefs;
+// 16 leaves headroom for the deepest session-fanout pattern observed (a few
+// /resume cycles on top of a couple of /new cycles) without prematurely
+// reaping a still-live session. Bump if the reaper fires while a session
+// is still live.
+export const MAX_SESSION_REFS = 16;
+// Cap on parentId chain walks in `findLabelHint` (UX preview only;
+// no need to walk to the root for a 50-char snippet).
+export const MAX_HINT_WALK_DEPTH = 50;
+// Floor on `summaryFocus` length (after trim) for `rewind`. The user's most
+// recent instruction lives on the chain about to be collapsed; if the focus
+// is shorter than this, it almost always elides that instruction (a terse
+// "finish parser fix" is 17 chars and conveys nothing the next turn can
+// act on). 20 is the empirical threshold below which the post-rewind turn
+// reliably loses continuity — raising it forces more useful focus text
+// without inviting verbosity.
+export const MIN_SUMMARY_FOCUS_LENGTH = 20;
+// 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
+// the synthetic's args because pi's `convertToLlm` re-emits the synthetic's
+// toolCall block (including its arguments) on every subsequent turn until
+// another rewind. Without a cap, a 100K-char focus inflates every later
+// turn's input by ~100K chars indefinitely. 1024 chars is generous — well
+// above empirically useful focus length, and the agent already saw the
+// full focus string when it issued the rewind.
+export const MAX_SYNTHETIC_FOCUS_LENGTH = 1024;
+// Hint length cap for the per-row hint shown in `list` output. 50 chars
+// fits one terminal column without wrapping in typical 80-column TUIs.
+const LIST_HINT_MAX_LENGTH = 50;
+// Hint length cap for the hint shown in the `anchor` response. The anchor
+// response is a single block of prose (not a column-aligned table) so it
+// can afford a longer hint than `list`'s per-row preview.
+const ANCHOR_HINT_MAX_LENGTH = 60;
+// padStart width for the percentage column in `list` output. The longest
+// percent label is "100.0%" = 6 chars; "99.9%" = 5 chars covers the
+// realistic worst case and keeps the column tight.
+const LIST_PCT_COL_WIDTH = 5;
+// padEnd width for the anchor-name column in `list` output. MAX_NAME_LENGTH
+// 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 ORIG_PROMPT_KEY = Symbol.for("navigate-tree.orig-prompt");
+
+// Two warnings: list-site (read-only path; warns about the next turn's
+// context view) and rewind-site (wrote to disk; leads with that). Both
+// suggest /reload first, then restart pi, in that order.
+const REFLECTION_BOOTSTRAP_WARNING_LIST =
+  "⚠ reflection bootstrap missing — anchors and rewinds still work, but the next assistant turn may snapshot pre-bootstrap context. Run `/reload` (or restart pi) to recover.";
+const REFLECTION_BOOTSTRAP_WARNING_REWIND =
+  "⚠ 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.";
+
+// ---------------------------------------------------------------------------
+// Typed views over pi internals.
+//
+// pi-coding-agent doesn't expose `agent`, `state`, `prepareNextTurn`, or
+// `sessionManager` on `AgentSession` in its public types, but they are plain
+// (non-`#`-private) fields on the class. Each cast point is a fragility
+// surface for pi version bumps; grouping them here makes the dependency
+// surface explicit.
+// ---------------------------------------------------------------------------
+
+interface PiInternals {
+  agent: {
+    state: {
+      systemPrompt: string;
+      messages: unknown[];
+      tools: unknown[];
+    };
+    prepareNextTurn?: unknown;
+  };
+  sessionManager: SessionManager;
+}
+
+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. This differs
+// 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; revisit if the call
+// site changes.
+type PntFn = (...args: unknown[]) => Promise<PntResult> | PntResult;
+type MarkedPntFn = PntFn & { [PNT_MARKER]?: boolean; __prior?: PntFn };
+
+// =============================================================================
+// Reflection bootstrap & in-loop refresh
+// =============================================================================
+
+const sessionInstances: WeakRef<AgentSession>[] = [];
+let seenSessions = new WeakSet<AgentSession>();
+
+function captureSession(session: AgentSession): void {
+  if (seenSessions.has(session)) return;
+  seenSessions.add(session);
+  sessionInstances.push(new WeakRef(session));
+  // Reap dead WeakRefs occasionally so the array doesn't grow unbounded
+  // across /new and /resume cycles.
+  if (sessionInstances.length > MAX_SESSION_REFS) {
+    for (let i = sessionInstances.length - 1; i >= 0; i--) {
+      if (!sessionInstances[i].deref()) sessionInstances.splice(i, 1);
+    }
+  }
+}
+
+function patchAgentSessionPrototype(): void {
+  const proto = AgentSession.prototype as unknown as Record<
+    PropertyKey,
+    unknown
+  >;
+  // Stash the truly-original prompt the FIRST time we patch. On subsequent
+  // /reloads the value is already there — we don't overwrite, we just read it
+  // back so the new wrapper still calls the original (not a previous wrapper).
+  if (!proto[ORIG_PROMPT_KEY]) {
+    proto[ORIG_PROMPT_KEY] = proto.prompt;
+  }
+  const orig = proto[ORIG_PROMPT_KEY] as (...args: unknown[]) => unknown;
+
+  // Always replace the wrapper, even if a previous load already patched. On
+  // /reload the previous wrapper closes over the previous module's
+  // `sessionInstances` — if we don't replace, captures land in the dead
+  // 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 `agent.prepareNextTurn` so the in-flight agent loop refreshes 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.
+ *
+ * The Agent class's `createLoopConfig` dereferences `this.prepareNextTurn`
+ * at the closure call site, so the value here is read at every turn boundary.
+ * But it gates the closure on `this.prepareNextTurn` 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 prepareNextTurn was installed by a previous load of THIS
+  // extension, recover the chain it captured (its `__prior`) so we don't
+  // strand other extensions' closures across /reload. Preserve any other
+  // extension's prepareNextTurn 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 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;
+}
+
+function findOwningSession(sm: SessionManager): AgentSession | null {
+  for (const ref of sessionInstances) {
+    const s = ref.deref();
+    if (s && asInternals(s).sessionManager === sm) {
+      return s;
+    }
+  }
+  return null;
+}
+
+function refreshAgentMessages(sm: SessionManager): boolean {
+  // Manually replicate the agent-state refresh that pi's
+  // commandCtx.navigateTree does after branchWithSummary. Returns true on
+  // success, false if reflection couldn't find the owning AgentSession (in
+  // which case the rewind is structurally complete on disk, but the next LLM
+  // call will still see stale messages).
+  const session = findOwningSession(sm);
+  if (!session) return false;
+  try {
+    const sessionContext = sm.buildSessionContext();
+    const agent = asInternals(session).agent;
+    if (!agent?.state) return false;
+    agent.state.messages = sessionContext.messages;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// =============================================================================
+// Helpers (extension-internal; pure helpers in ./helpers.ts)
+// =============================================================================
+
+function findLabeledEntry(
+  sm: SessionManager,
+  fullLabel: string,
+): string | null {
+  const path = sm.getBranch();
+  for (let i = path.length - 1; i >= 0; i--) {
+    if (sm.getLabel(path[i].id) === fullLabel) return path[i].id;
+  }
+  return null;
+}
+
+function estimateActiveBranchTokens(sm: SessionManager): number {
+  return estimateContextTokens(sm.buildSessionContext().messages).tokens;
+}
+
+function estimateAtEntry(
+  entries: SessionEntry[],
+  entryId: string,
+  byId: Map<string, SessionEntry>,
+): number {
+  return estimateContextTokens(
+    buildSessionContext(entries, entryId, byId).messages,
+  ).tokens;
+}
+
+/**
+ * Walk parentId chain back from `fromId` and return a one-line preview of
+ * the first entry that has meaningful text content. Branch summaries are
+ * prefixed with `summary:` so the source is clear; user/assistant text is
+ * shown as-is.
+ */
+function findLabelHint(
+  sm: SessionManager,
+  fromId: string,
+  maxLen: number,
+): string | null {
+  let cur: string | null | undefined = fromId;
+  let depth = 0;
+  while (cur && depth < MAX_HINT_WALK_DEPTH) {
+    const e = sm.getEntry(cur);
+    if (!e) break;
+    let text = "";
+    let prefix = "";
+    if (e.type === "branch_summary" && e.summary) {
+      text = stripBranchSummaryBoilerplate(e.summary);
+      prefix = "summary: ";
+    } else if (e.type === "message") {
+      const role = e.message.role;
+      if (role === "user" || role === "assistant") {
+        text = extractTextContent(e.message.content);
+      }
+    } else if (e.type === "custom_message") {
+      text = extractTextContent(e.content);
+    }
+    const oneLine = toOneLine(text, maxLen - prefix.length);
+    if (oneLine) return prefix + oneLine;
+    cur = e.parentId;
+    depth++;
+  }
+  return null;
+}
+
+/**
+ * Build a synthetic assistant message containing a single tool_call whose id
+ * matches the in-flight tool_call id. Appended after `branchWithSummary` so
+ * the real tool_result lands paired with a matching tool_use.
+ *
+ * `usage` fields are zeroed except `totalTokens`, which is set to the
+ * chain size measured BEFORE this synthetic is appended (the post-rewind
+ * baseline that pi-agent-core's `estimateContextTokens` reads off the last
+ * assistant). `stopReason: "toolUse"` survives Kiro's `normalizeMessages`
+ * filter (which strips `error` / `aborted`); without it the synthetic would
+ * be filtered out and the tool_result would re-orphan.
+ */
+function buildSyntheticAssistant(
+  toolCallId: string,
+  toolName: string,
+  args: Record<string, unknown>,
+  model: { api?: string; provider?: string; id?: string } | undefined,
+  totalTokens: number,
+) {
+  return {
+    role: "assistant" as const,
+    content: [
+      {
+        type: "toolCall" as const,
+        id: toolCallId,
+        name: toolName,
+        arguments: args,
+      },
+    ],
+    api: model?.api ?? "unknown",
+    provider: model?.provider ?? "unknown",
+    model: model?.id ?? "unknown",
+    stopReason: "toolUse" as const,
+    timestamp: Date.now(),
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+  };
+}
+
+// =============================================================================
+// Extension
+// =============================================================================
+
+interface ToolResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+  isError?: boolean;
+}
+
+function toolError(
+  text: string,
+  details: Record<string, unknown> = {},
+): ToolResult {
+  return {
+    content: [{ type: "text", text }],
+    details,
+    isError: true,
+  };
+}
+
+export default function (
+  pi: ExtensionAPI,
+  opts?: { summarize?: typeof generateBranchSummary },
+) {
+  // DI seam: tests inject a stub `summarize` to avoid hitting the real
+  // model. Production callers (pi's extension loader) pass no second
+  // argument, so this falls back to the real `generateBranchSummary`
+  // import.
+  const summarize = opts?.summarize ?? generateBranchSummary;
+  patchAgentSessionPrototype();
+
+  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",
+    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):
+  • action='anchor', name='<milestone-name>': label the current point so a later rewind can target it. Use at the start of a stage you'll summarize (e.g. 'design-start', 'impl-start'). If the same name already exists on the active branch, the prior label is moved to the new leaf (no duplicates).
+  • action='rewind', labelStart='<existing>', labelEnd='<new>': collapse work between labelStart and the current leaf into a branch_summary. The new summary entry is itself labeled with labelEnd, so you can chain rewinds.
+  • action='list': show all named anchors on the active branch in chronological order, with cumulative context % at each anchor.
+
+Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor namespace — either becomes addressable as a future \`labelStart\`. \`list\` shows every anchor under the \`anchor:\` prefix, regardless of which action wrote it. Pi labels written via \`/label anchor:foo\` (manually or by other extensions) are also addressable here. Avoid the \`anchor:\` prefix in manually-set labels.
+
+\`summaryFocus\` is required when \`action='rewind'\` (≥${MIN_SUMMARY_FOCUS_LENGTH} chars after trim). Calls without it are rejected. It's passed to pi's \`generateBranchSummary\` as \`customInstructions\`, biasing the summarizer LLM toward the agent's specified focus while it rewrites the collapsed work into pi's structured summary format. To preserve continuity, instruct the summarizer to keep: (1) the user's most recent message verbatim, (2) what's done in the collapsed segment, (3) what's left to do as a next action.`,
+    promptSnippet:
+      "Use to anchor named milestones and rewind the conversation tree to a prior point with a model-generated summary, for token-efficient long autonomous sessions.",
+    // The schema is intentionally a flat `Type.Object` with everything-but-
+    // `action` optional, with action-conditional required-ness enforced at
+    // runtime in `execute`. Discriminated unions / property-level required-
+    // when-action shapes break the Kiro/CodeWhisperer adapter, which forwards
+    // `inputSchema.json` verbatim and 400s on non-`type: "object"` roots.
+    // The runtime guards in `execute` provide the conditional-required
+    // behavior the schema can't express.
+    parameters: Type.Object({
+      action: Type.Union(
+        [Type.Literal("anchor"), Type.Literal("rewind"), Type.Literal("list")],
+        {
+          description:
+            "Which operation to perform. 'anchor' labels the current point, 'rewind' collapses work between an anchor and the current leaf into a branch_summary, 'list' shows every anchor on the active branch.",
+        },
+      ),
+      name: Type.Optional(
+        Type.String({
+          description: `Required when action='anchor'. Kebab-case label (max ${MAX_NAME_LENGTH} chars) for the milestone. If a label with this name already exists on the active branch, it is moved to the new leaf.`,
+        }),
+      ),
+      labelStart: Type.Optional(
+        Type.String({
+          description: `Required when action='rewind'. Kebab-case name (max ${MAX_NAME_LENGTH} chars) of an existing anchor on the active branch — work between this anchor and the current leaf is summarized.`,
+        }),
+      ),
+      labelEnd: Type.Optional(
+        Type.String({
+          description: `Required when action='rewind'. Kebab-case name (max ${MAX_NAME_LENGTH} chars) for the resulting branch_summary entry. If a label with this name already exists on the active branch, it is moved to the new entry (mirrors anchor's move-on-collision). Becomes addressable as a future labelStart.`,
+        }),
+      ),
+      summaryFocus: Type.Optional(
+        Type.String({
+          description: `Required when action='rewind'. ≥${MIN_SUMMARY_FOCUS_LENGTH} chars after trim. Should encode (1) the user's most recent instruction verbatim, (2) what was done in the collapsed segment, (3) what's left to do as a next action.`,
+        }),
+      ),
+    }),
+    execute: async (toolCallId, params, signal, _onUpdate, ctx) => {
+      const sm = ctx.sessionManager as SessionManager;
+      const p = params as {
+        action: "anchor" | "rewind" | "list";
+        name?: string;
+        labelStart?: string;
+        labelEnd?: string;
+        summaryFocus?: string;
+      };
+
+      // --- list ---
+      if (p.action === "list") {
+        const path = sm.getBranch();
+        const allEntries = sm.getEntries();
+        const byId = new Map<string, SessionEntry>();
+        for (const e of allEntries) byId.set(e.id, e);
+        const cw = ctx.model?.contextWindow ?? 0;
+        const totalTokens = estimateActiveBranchTokens(sm);
+        const reflectionOk = !!findOwningSession(sm);
+
+        const lines: string[] = [];
+        for (const e of path) {
+          const lbl = sm.getLabel(e.id);
+          if (lbl?.startsWith(LABEL_PREFIX)) {
+            const name = lbl.slice(LABEL_PREFIX.length);
+            const tokensAt = estimateAtEntry(allEntries, e.id, byId);
+            const pct = formatPct1(tokensAt, cw).padStart(LIST_PCT_COL_WIDTH);
+            const hint = findLabelHint(sm, e.id, LIST_HINT_MAX_LENGTH);
+            const hintPart = hint ? `  (after: “${hint}”)` : "";
+            lines.push(
+              `  ${pct}  ${name.padEnd(LIST_LABEL_COL_WIDTH)}${hintPart}`,
+            );
+          }
+        }
+
+        const reflectionWarning = reflectionOk
+          ? ""
+          : ` · ${REFLECTION_BOOTSTRAP_WARNING_LIST}`;
+        const header = `[list] · ${lines.length} label${lines.length === 1 ? "" : "s"} · ctx ${formatPct1(totalTokens, cw)}${cw > 0 ? ` of ${formatWindow(cw)}` : ""}${reflectionWarning}`;
+        const body = lines.length
+          ? `Active labels (root → leaf):\n${lines.join("\n")}`
+          : "No labels on the active branch.";
+        return {
+          content: [{ type: "text", text: `${header}\n\n${body}` }],
+          details: {
+            count: lines.length,
+            contextTokens: totalTokens,
+            contextWindow: cw,
+            reflectionOk,
+          },
+        };
+      }
+
+      // --- anchor ---
+      if (p.action === "anchor") {
+        if (!isValidName(p.name)) {
+          return toolError(
+            `anchor requires \`name\` in kebab-case, max ${MAX_NAME_LENGTH} chars (e.g. 'impl-start').`,
+          );
+        }
+        const leafId = sm.getLeafId();
+        if (!leafId) {
+          return toolError("No session entries yet — nothing to anchor.");
+        }
+        // Write the new label first, then clear the prior. If the second
+        // setLabel throws, two labels of the same name briefly coexist on
+        // the active branch — `findLabeledEntry` walks leaf→root and
+        // returns the leaf-side match, so navigation behavior is correct
+        // during the overlap. The pre-PR "no enforcement" semantics already
+        // tolerated this. The reverse order (clear-then-set) was move-then-
+        // lose under failure: a partial collapse left the active branch
+        // with no anchor of the requested name at all.
+        const fullLabel = LABEL_PREFIX + p.name;
+        const prior = findLabeledEntry(sm, fullLabel);
+        pi.setLabel(leafId, fullLabel);
+        if (prior && prior !== leafId) {
+          pi.setLabel(prior, undefined);
+        }
+        const cw = ctx.model?.contextWindow ?? 0;
+        const tokensHere = estimateActiveBranchTokens(sm);
+        const labelHint = findLabelHint(sm, leafId, ANCHOR_HINT_MAX_LENGTH);
+        const positionLine = `${formatPct1(tokensHere, cw)}${cw > 0 ? ` of ${formatWindow(cw)}` : ""}`;
+        const hintLine = labelHint ? ` (after: “${labelHint}”)` : "";
+        return {
+          content: [
+            {
+              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>').`,
+            },
+          ],
+          details: {
+            label: p.name,
+            entryId: leafId,
+            contextTokens: tokensHere,
+            labelHint,
+            movedFromPriorEntry: prior && prior !== leafId ? prior : null,
+          },
+        };
+      }
+
+      // --- rewind ---
+      if (!isValidName(p.labelStart)) {
+        return toolError(
+          `rewind requires \`labelStart\` in kebab-case, max ${MAX_NAME_LENGTH} chars.`,
+        );
+      }
+      if (!isValidName(p.labelEnd)) {
+        return toolError(
+          `rewind requires \`labelEnd\` in kebab-case, max ${MAX_NAME_LENGTH} chars.`,
+        );
+      }
+      if (
+        !p.summaryFocus ||
+        p.summaryFocus.trim().length < MIN_SUMMARY_FOCUS_LENGTH
+      ) {
+        const focusLen = p.summaryFocus?.trim().length ?? 0;
+        return toolError(
+          `\`summaryFocus\` must be ≥${MIN_SUMMARY_FOCUS_LENGTH} chars after trim (got ${focusLen}). The user's most recent instruction (which triggered this rewind) lives on the chain that's about to be collapsed — if summaryFocus doesn't preserve it, the post-rewind turn won't know what's left to do.\n\n` +
+            `Include in summaryFocus:\n` +
+            `  1. the user's most recent instruction verbatim,\n` +
+            `  2. which parts have already been done in the work being collapsed,\n` +
+            `  3. which parts remain unactioned.`,
+        );
+      }
+
+      const target = findLabeledEntry(sm, LABEL_PREFIX + p.labelStart);
+      if (!target) {
+        return toolError(
+          `No label '${p.labelStart}' on the active branch. Use action='list' to see available labels.`,
+        );
+      }
+
+      const oldLeaf = sm.getLeafId();
+      if (!oldLeaf || oldLeaf === target) {
+        return toolError(
+          `Already at '${p.labelStart}' — nothing to summarize.`,
+        );
+      }
+
+      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}`);
+      }
+
+      // 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
+      // user just saw. Use the chain up to its parent (which has the prior
+      // assistant's usage as baseline) so beforeTokens matches the value
+      // `list` would have reported on the previous turn.
+      const oldLeafEntry = sm.getEntry(oldLeaf);
+      let beforeTokens: number;
+      if (
+        oldLeafEntry &&
+        oldLeafEntry.type === "message" &&
+        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 { entries } = collectEntriesForBranchSummary(sm, oldLeaf, target);
+      if (entries.length === 0) {
+        return toolError(
+          `No entries between leaf and '${p.labelStart}' — nothing to summarize.`,
+        );
+      }
+      // Chained-rewind-no-turns guard: bail if the only message between
+      // leaf and target matches our synthetic shape (single navigate_tree
+      // toolCall block + stopReason "toolUse" + zero usage), meaning the
+      // agent didn't append a real turn between rewinds. Keep only message
+      // entries — label / compaction / branch_summary / etc. carry no
+      // rewindable semantic content for this guard. The synthetic-shape
+      // predicate avoids false-positives on real navigate_tree calls
+      // (which have nonzero usage from the model).
+      const messageEntries = entries.filter((e) => e.type === "message");
+      if (messageEntries.length === 1) {
+        const lone = messageEntries[0];
+        if (lone.type === "message" && lone.message.role === "assistant") {
+          const msg = lone.message as {
+            content: Array<{ type?: string; name?: string }>;
+            stopReason?: string;
+            usage?: { input?: number; output?: number };
+          };
+          const block = msg.content[0];
+          const isSyntheticShape =
+            msg.stopReason === "toolUse" &&
+            (msg.usage?.input ?? 0) === 0 &&
+            (msg.usage?.output ?? 0) === 0;
+          if (
+            block &&
+            block.type === "toolCall" &&
+            block.name === "navigate_tree" &&
+            isSyntheticShape
+          ) {
+            return toolError(
+              `Already at synthetic boundary — no work to summarize. Append at least one turn between rewinds.`,
+            );
+          }
+        }
+      }
+
+      const result = await summarize(entries, {
+        model: ctx.model,
+        apiKey: auth.apiKey ?? "",
+        headers: auth.headers,
+        signal: signal ?? new AbortController().signal,
+        customInstructions: p.summaryFocus,
+      });
+      if (result.aborted) {
+        return toolError("Summarization aborted.");
+      }
+      if (result.error || !result.summary) {
+        return toolError(
+          `Summarization failed: ${result.error ?? "no summary text"}`,
+        );
+      }
+
+      // Move the tree.
+      const summaryId = sm.branchWithSummary(target, result.summary, {
+        readFiles: result.readFiles ?? [],
+        modifiedFiles: result.modifiedFiles ?? [],
+      });
+
+      // Chain-validity invariants once `branchWithSummary` succeeds: a
+      // synthetic must land on every path with toolCallId === this
+      // in-flight call (so pi's appended tool_result pairs), and
+      // stopReason: "toolUse" (survives Kiro's normalizeMessages filter
+      // — see `buildSyntheticAssistant` JSDoc). The synthetic append
+      // sits OUTSIDE the try so it runs exactly once regardless of
+      // which earlier step threw. labelEnd write moves before clear,
+      // mirroring `anchor`'s move-on-collision so duplicate anchors
+      // can't survive a chained rewind.
+      const fullLabelEnd = LABEL_PREFIX + p.labelEnd;
+      let priorLabelEnd: ReturnType<typeof findLabeledEntry> = null;
+      let tokensAtNewLeaf = 0;
+      let originalErr: unknown;
+      let salvageDetail = "";
+      let failedStep:
+        | "lookup"
+        | "setLabelEnd"
+        | "clearPrior"
+        | "estimate"
+        | null = null;
+      try {
+        failedStep = "lookup";
+        priorLabelEnd = findLabeledEntry(sm, fullLabelEnd);
+        failedStep = "setLabelEnd";
+        pi.setLabel(summaryId, fullLabelEnd);
+        // `summaryId` was freshly allocated by branchWithSummary above;
+        // no pre-existing label can already point at it.
+        if (priorLabelEnd) {
+          failedStep = "clearPrior";
+          pi.setLabel(priorLabelEnd, undefined);
+        }
+
+        // Compute afterTokens NOW — before we append the synthetic. This
+        // captures the chain size at the new leaf (branch_summary) using
+        // the prior real assistant's usage as the baseline.
+        failedStep = "estimate";
+        tokensAtNewLeaf = estimateActiveBranchTokens(sm);
+        failedStep = null;
+      } catch (err) {
+        originalErr = err;
+        // Best-effort retry of the specific failed step (pi.setLabel is
+        // idempotent under re-application). Per-step recovery shape:
+        //   - setLabelEnd: retry pi.setLabel(summaryId, fullLabelEnd).
+        //   - clearPrior:  retry pi.setLabel(priorLabelEnd, undefined).
+        //   - lookup / estimate: no retry — either prior state unknown
+        //     or both labels already wrote; redundant retry would mask
+        //     the real cause.
+        if (failedStep === "setLabelEnd") {
+          try {
+            pi.setLabel(summaryId, fullLabelEnd);
+          } catch (retryErr) {
+            salvageDetail = `labelEnd retry failed: ${
+              retryErr instanceof Error ? retryErr.message : String(retryErr)
+            }`;
+          }
+        } else if (failedStep === "clearPrior" && priorLabelEnd) {
+          try {
+            pi.setLabel(priorLabelEnd, undefined);
+          } catch (retryErr) {
+            salvageDetail = `prior-clear retry failed: ${
+              retryErr instanceof Error ? retryErr.message : String(retryErr)
+            }`;
+          }
+        }
+      }
+
+      // Synthetic append: runs in BOTH the happy path and the salvage path.
+      // If `originalErr` is set we use a degenerate synthetic
+      // (totalTokens=0, since `tokensAtNewLeaf` may not have been computed).
+      // The synthetic's matching toolCallId is the only structural
+      // requirement for chain validity — pi's appended tool_result pairs
+      // with this synthetic regardless of which earlier step threw.
+      //
+      // The full `summaryFocus` is already live in the LLM call to
+      // `generateBranchSummary`; we only need a trimmed copy in the
+      // synthetic's args (which pi will re-emit on every subsequent turn).
+      // Truncate to MAX_SYNTHETIC_FOCUS_LENGTH so a long focus string
+      // doesn't inflate every later turn indefinitely.
+      const syntheticArgs: Record<string, unknown> = {
+        ...(p as unknown as Record<string, unknown>),
+      };
+      if (
+        typeof p.summaryFocus === "string" &&
+        p.summaryFocus.length > MAX_SYNTHETIC_FOCUS_LENGTH
+      ) {
+        syntheticArgs.summaryFocus = `${p.summaryFocus.slice(0, MAX_SYNTHETIC_FOCUS_LENGTH)}… [truncated]`;
+      }
+      const syntheticMsg = buildSyntheticAssistant(
+        toolCallId,
+        "navigate_tree",
+        syntheticArgs,
+        ctx.model as
+          | { api?: string; provider?: string; id?: string }
+          | undefined,
+        originalErr ? 0 : tokensAtNewLeaf,
+      );
+      const syntheticId = sm.appendMessage(syntheticMsg);
+
+      // Refresh agent.state.messages so the next prompt() snapshot reflects
+      // the rewound chain. Runs in both paths; `refreshAgentMessages`
+      // already swallows internal throws, so it can't re-trigger salvage.
+      const refreshed = refreshAgentMessages(sm);
+
+      if (originalErr) {
+        // Salvage path: synthetic landed (chain is valid), labelEnd retry
+        // and refresh were best-effort. Re-throw the original error with
+        // any salvage detail attached so the failure surfaces to the
+        // agent and post-mortem reviewers can tell what was recovered.
+        // Preserve the original via `Error.cause` (ES2022) so callers
+        // doing `instanceof` checks against typed subclasses, or
+        // post-mortem readers walking the cause chain, can recover the
+        // original throw. Older runtimes silently ignore the options
+        // bag, so this is forward-compatible without a feature gate.
+        const baseMsg =
+          originalErr instanceof Error
+            ? originalErr.message
+            : String(originalErr);
+        throw new Error(
+          salvageDetail ? `${baseMsg} (salvage: ${salvageDetail})` : baseMsg,
+          { cause: originalErr },
+        );
+      }
+
+      const afterTokens = tokensAtNewLeaf;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              `[rewind '${p.labelStart}' → '${p.labelEnd}'] · ${formatContextDelta(beforeTokens, afterTokens, contextWindow)}\n\n` +
+              `A branch_summary recording the work just collapsed has been appended to your context. Items under '### Done' are complete. Items under '### In Progress', '### Blocked', or '## Next Steps' are pending — execute them next without re-confirming with the user. Other branch_summary messages, if present, record earlier collapsed segments.` +
+              (refreshed ? "" : `\n\n${REFLECTION_BOOTSTRAP_WARNING_REWIND}`),
+          },
+        ],
+        details: {
+          labelStart: p.labelStart,
+          labelEnd: p.labelEnd,
+          targetId: target,
+          summaryId,
+          syntheticAssistantId: syntheticId,
+          collapsedEntries: entries.length,
+          contextBefore: beforeTokens,
+          contextAfter: afterTokens,
+          contextWindow,
+          agentMessagesRefreshed: refreshed,
+          readFiles: result.readFiles ?? [],
+          modifiedFiles: result.modifiedFiles ?? [],
+        },
+      };
+    },
+  });
+}
+
+/**
+ * Non-stable testing-only hooks. **Do NOT import in production code.**
+ *
+ * The `__` prefix and individual member names are subject to change in any
+ * release without a semver-major bump. Intended exclusively for hermetic
+ * tests within this package; the hooks reach into module-internal state
+ * (the `AgentSession.prototype` patch, the `seenSessions` WeakSet, the
+ * `sessionInstances` array, the `prepareNextTurn` marker symbol) and are
+ * not designed for external consumption.
+ *
+ * If you found this via `node_modules` archaeology, you're holding it
+ * wrong — use the registered tool surface (`navigate_tree`) instead.
+ */
+export const __testHooks = {
+  /**
+   * Restore the original `AgentSession.prototype.prompt` (stashed by
+   * `patchAgentSessionPrototype` under the `ORIG_PROMPT_KEY` symbol) and
+   * drain the captured-session refs. Idempotent: a no-op if the patch was
+   * never installed or has already been reset.
+   */
+  resetPrototype(): void {
+    const proto = AgentSession.prototype as unknown as Record<
+      PropertyKey,
+      unknown
+    >;
+    const orig = proto[ORIG_PROMPT_KEY];
+    if (typeof orig === "function") {
+      proto.prompt = orig;
+      delete proto[ORIG_PROMPT_KEY];
+    }
+    sessionInstances.length = 0;
+    // WeakSet has no .clear(); rebind to a fresh instance so a test that
+    // re-captures the SAME session identity post-reset isn't deduped by
+    // stale state from the previous test's capture.
+    seenSessions = new WeakSet();
+  },
+  /** Module-internal helpers exposed for hermetic unit tests. */
+  buildSyntheticAssistant,
+  findLabelHint,
+  findLabeledEntry,
+  installPrepareNextTurn,
+  refreshAgentMessages,
+  captureSession,
+  /** Symbol used to mark the wrapper installed by `installPrepareNextTurn`. */
+  PNT_MARKER,
+  /** Read-only view of captured-session ref count for reaping assertions. */
+  sessionRefCount(): number {
+    return sessionInstances.length;
+  },
+  /**
+   * The reflection-bootstrap-missing warning strings, split per site.
+   * Exported so tests can pin the per-site verbatim wording (the `list`
+   * site is read-only and uses the read-only phrasing; the `rewind` site
+   * writes to disk and uses the write phrasing). Tests assert literal
+   * containment at each site to catch drift.
+   */
+  REFLECTION_BOOTSTRAP_WARNING_LIST,
+  REFLECTION_BOOTSTRAP_WARNING_REWIND,
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@cad0p/pi-tree-navigator",
+  "version": "0.1.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",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "session-tree",
+    "branch-summary",
+    "agent-memory",
+    "context-management"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cad0p/pi-tree-navigator.git"
+  },
+  "homepage": "https://github.com/cad0p/pi-tree-navigator#readme",
+  "bugs": {
+    "url": "https://github.com/cad0p/pi-tree-navigator/issues"
+  },
+  "files": [
+    "extensions/**/*.ts",
+    "!extensions/**/*.test.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "extensions/navigate-tree"
+    ]
+  },
+  "scripts": {
+    "lint": "bunx biome check extensions/",
+    "lint:fix": "bunx biome check --write extensions/",
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@types/bun": "^1.3.0",
+    "typescript": "^5.8.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": ">=0.74.0",
+    "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "typebox": "^1.0.0"
+  },
+  "license": "MIT"
+}