pum-agent 0.2.34-beta.2 → 0.2.35-beta.1

package/src/context-window.ts

@@ -1,7 +1,7 @@
 import { Type } from "typebox";
+import { createHash } from "node:crypto";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import {
-  estimateTokens,
   sessionEntryToContextMessages,
   type AgentSession,
   type ExtensionAPI,
@@ -11,6 +11,9 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { registerTranscriptHistoryTool } from "./transcript-history";
 import { CONTEXT_GUIDANCE } from "./context-guidance";
+import { contextRecoveryGuidance } from "./context-recovery";
+import { contextCalibration, contextUsage, estimateContextMessage as estimateTokens, estimateContextText,
+  CONTEXT_MESSAGE_TOKENS } from "./context-estimate";
 
 export const CONTEXT_TOOL_NAMES = ["history", "get_context_remaining", "new_context"] as const;
 export const CONTEXT_WINDOW_CUSTOM_TYPE = "pum.context_window";
@@ -18,16 +21,38 @@ export const CONTEXT_HANDOFF_MAX_CHARS = 20_000;
 
 interface BoundaryData { version: 1; handoff?: string }
 interface Pending { id: string; handoff?: string; signal?: AbortSignal; duplicate: boolean }
-interface PromptSnapshot { systemPrompt: string; tools: string; modelKey?: string }
+interface EstimateFingerprint { hash: string; tokens: number }
+interface PromptSnapshot { systemPrompt: EstimateFingerprint; tools: EstimateFingerprint; modelKey?: string }
 interface RequestSnapshot extends PromptSnapshot {
   windowId: string | null;
-  stateSystemPrompt: string;
-  stateTools: string;
+  generation: number;
+  stateSystemPrompt: EstimateFingerprint;
+  stateTools: EstimateFingerprint;
   injectedTokens: number;
+  estimatedInputTokens: number;
+  sourceHash: string;
+  sourceCount: number;
+}
+interface UsageSnapshot extends RequestSnapshot {
+  responseHash: string;
+  total: number;
+  factor: number;
+  limited: boolean;
+  eligible: boolean;
+  growth: number;
+}
+function fingerprint(text: string): EstimateFingerprint {
+  return { hash: createHash("sha256").update(text).digest("hex"), tokens: estimateContextText(text) };
+}
+function messageHash(messages: readonly AgentMessage[]): string {
+  const hash = createHash("sha256");
+  for (const message of messages) hash.update(JSON.stringify(message)).update("\n");
+  return hash.digest("hex");
 }
 const MANUAL_COMPACTION_REFUSAL = "Manual /compress is unavailable after a PUM context rollover on the active branch. Use new_context instead. The full transcript is retained.";
 function modelIdentity(model: AgentSession["model"]): string | undefined {
-  return model ? `${model.provider}/${model.id}:${model.contextWindow}` : undefined;
+  return model && Number.isFinite(model.contextWindow) && model.contextWindow > 0
+    ? JSON.stringify([model.provider, model.id, model.api, model.contextWindow]) : undefined;
 }
 
 function object(value: unknown): value is Record<string, unknown> {
@@ -47,11 +72,11 @@ function boundaryData(value: unknown): BoundaryData {
   const { handoff } = handoffParams({ handoff: value.handoff });
   return { version: 1, ...(handoff === undefined ? {} : { handoff }) };
 }
-function header(id: string, handoff?: string, navigation?: { userId?: string; previousId?: string | null }): AgentMessage {
+function header(id: string, handoff?: string, navigation?: { userId?: string; previousId?: string | null }, recovery = ""): AgentMessage {
   return {
     role: "custom", customType: CONTEXT_WINDOW_CUSTOM_TYPE, display: false, timestamp: 0,
-    content: `Fresh PUM context window: ${id}. Earlier transcript entries remain available through history. The rollover generated no summary. Restore project memory and the session todo list with the available tools. Recover exact user instructions and relevant results with history before continuing. Current system instructions still apply.`
-      + (navigation ? `\nHistory navigation: latest prior user entry ID: ${navigation.userId ?? "none"}; previous transcript entry ID: ${navigation.previousId ?? "none"}. Use history with op "read" and entryId, then follow parentId links to recover exact earlier instructions.` : "")
+    content: `Fresh PUM context window: ${id}. Earlier transcript entries remain retained in the full session transcript. The rollover generated no summary. Current system instructions still apply. ${recovery}`
+      + (navigation ? `\nHistory navigation: latest prior user entry ID: ${navigation.userId ?? "none"}; previous transcript entry ID: ${navigation.previousId ?? "none"}. These IDs are navigation metadata, not a requirement to restore earlier content.` : "")
       + (handoff === undefined ? "" : `\n\nLiteral handoff supplied to new_context:\n${handoff}`),
   };
 }
@@ -73,7 +98,11 @@ export class ContextWindowController {
   private usageFloor = 0;
   private preparedPrompt?: PromptSnapshot;
   private requestSnapshot?: RequestSnapshot;
-  private usageSnapshots = new WeakMap<AgentMessage, RequestSnapshot>();
+  private usageSnapshots = new WeakMap<AgentMessage, UsageSnapshot>();
+  private latestUsageSnapshot?: UsageSnapshot;
+  private generation = 0;
+
+  constructor(private readonly options: { memoryInjected?: boolean } = {}) {}
 
   extension(): InlineExtension {
     return { name: "pum-context-window", factory: (pi: ExtensionAPI) => {
@@ -81,10 +110,10 @@ export class ContextWindowController {
         const meter = this.remaining();
         if (meter.reserveExceedsCapacity === true && typeof meter.remainingTokens === "number") {
           const model = this.requireSession().model!;
-          return Math.max(0, meter.remainingTokens - Math.min(model.maxTokens, Math.floor(model.contextWindow / 4)));
+          return this.historyBudget(Math.max(0, meter.remainingTokens - this.responseHeadroom(model.contextWindow)), meter);
         }
         return typeof meter.remainingBeforeReserve === "number" && typeof meter.remainingTokens === "number"
-          ? Math.min(meter.remainingBeforeReserve, meter.remainingTokens) : undefined;
+          ? this.historyBudget(Math.min(meter.remainingBeforeReserve, meter.remainingTokens), meter) : undefined;
       });
       pi.on("session_start", () => { this.disableAutomaticCompaction(); this.restore(); });
       pi.on("session_tree", () => { this.pending = undefined; this.restore(); });
@@ -92,6 +121,7 @@ export class ContextWindowController {
         const key = modelIdentity(event.model);
         if (key !== this.modelKey) {
           this.modelKey = key;
+          this.generation++;
           this.usageFloor = this.session?.agent.state.messages.length ?? 0;
         }
       });
@@ -154,8 +184,18 @@ export class ContextWindowController {
         this.preparedPrompt = undefined;
         this.requestSnapshot = undefined;
       } else if (event.type === "message_end" && event.message.role === "assistant") {
-        if (this.requestSnapshot) this.usageSnapshots.set(event.message, this.requestSnapshot);
+        const snapshot = this.requestSnapshot;
         this.requestSnapshot = undefined;
+        const usage = contextUsage(event.message.usage);
+        if (snapshot && snapshot.modelKey && usage && ["stop", "toolUse", "length"].includes(event.message.stopReason)
+          && snapshot.generation === this.generation && snapshot.modelKey === modelIdentity(session.model)
+          && event.message.provider === session.model?.provider && event.message.model === session.model?.id
+          && event.message.api === session.model?.api) {
+          const paired = { ...snapshot, responseHash: messageHash([event.message]),
+            total: usage.total, ...contextCalibration(usage.input, snapshot.estimatedInputTokens), growth: 0 };
+          this.usageSnapshots.set(event.message, paired);
+          this.latestUsageSnapshot = paired;
+        }
       }
     });
     // Reload and unrelated settings saves replace effective overrides. Native
@@ -171,17 +211,34 @@ export class ContextWindowController {
     const transform = session.agent.transformContext;
     session.agent.transformContext = async (messages, signal) => {
       const originalTokens = messages.reduce((sum, message) => sum + estimateTokens(message), 0);
-      const stateSystemPrompt = session.agent.state.systemPrompt;
+      const stateSystemPrompt = fingerprint(session.agent.state.systemPrompt);
       const stateTools = this.toolSchemas();
       const prompt = this.preparedPrompt ?? { systemPrompt: stateSystemPrompt, tools: stateTools, modelKey: modelIdentity(session.model) };
       this.requestSnapshot = undefined;
+      const generation = this.generation;
+      const windowId = this.windowId;
+      const sourceHash = messageHash(messages);
+      const sourceCount = messages.length;
       const transformed = transform ? await transform.call(session.agent, messages, signal) : messages;
       // Observe the complete extension chain, including memory injected after our
       // extension. Return it unchanged; memory and dynamic instructions stay active.
-      this.observedExtraTokens = Math.max(0, transformed.reduce((sum, message) => sum + estimateTokens(message), 0)
-        - originalTokens);
-      this.requestSnapshot = { ...prompt, windowId: this.windowId, stateSystemPrompt, stateTools,
-        injectedTokens: this.observedExtraTokens };
+      if (generation === this.generation && !signal?.aborted) {
+        this.observedExtraTokens = Math.max(0, transformed.reduce((sum, message) => sum + estimateTokens(message), 0)
+          - originalTokens);
+        const measured = this.latestUsageSnapshot;
+        if (measured?.generation === generation && measured.modelKey === prompt.modelKey) {
+          // A failed request may have observed growth followed by shrinkage
+          // without an intervening meter call. Do not reclaim that observation.
+          measured.growth = Math.max(measured.growth,
+            Math.max(0, prompt.systemPrompt.tokens - measured.systemPrompt.tokens)
+            + Math.max(0, prompt.tools.tokens - measured.tools.tokens)
+            + Math.max(0, this.observedExtraTokens - measured.injectedTokens));
+        }
+        this.requestSnapshot = { ...prompt, windowId, generation, stateSystemPrompt, stateTools,
+          injectedTokens: this.observedExtraTokens, sourceHash, sourceCount,
+          estimatedInputTokens: transformed.reduce((sum, message) => sum + estimateTokens(message), 0)
+            + prompt.systemPrompt.tokens + prompt.tools.tokens };
+      }
       return transformed;
     };
     const previous = session.agent.prepareNextTurnWithContext;
@@ -193,7 +250,7 @@ export class ContextWindowController {
       const input = fresh ? { ...turn, context: { ...turn.context, messages: session.agent.state.messages.slice() } } : turn;
       const update = previous ? await previous.call(session.agent, input, signal) : await legacy?.call(session.agent, signal);
       const context = update?.context ?? input.context;
-      this.preparedPrompt = { systemPrompt: context.systemPrompt, tools: this.toolSchemas(context.tools),
+      this.preparedPrompt = { systemPrompt: fingerprint(context.systemPrompt), tools: this.toolSchemas(context.tools),
         modelKey: modelIdentity(update?.model ?? session.model) };
       return fresh ? { ...update, context } : update;
     };
@@ -215,11 +272,13 @@ export class ContextWindowController {
     const branch = session.sessionManager.getBranch();
     const index = branch.findLastIndex(isBoundary);
     this.windowId = index < 0 ? null : branch[index]!.id;
+    this.generation++;
     this.usageFloor = 0;
     this.modelKey = modelIdentity(session.model);
     this.requestSnapshot = undefined;
     this.preparedPrompt = undefined;
     this.usageSnapshots = new WeakMap();
+    this.latestUsageSnapshot = undefined;
     if (index < 0) { this.restoreUsageFloor(branch); return; }
     const boundary = branch[index]!;
     if (boundary.type !== "custom") return;
@@ -239,7 +298,7 @@ export class ContextWindowController {
     const latestUser = branch.slice(0, index).findLast((entry) => entry.type === "message" && entry.message.role === "user");
     session.agent.state.messages = [header(boundary.id, data.handoff, {
       userId: latestUser?.id, previousId: boundary.parentId,
-    }), ...entries.flatMap(sessionEntryToContextMessages)];
+    }, this.recoveryGuidance()), ...entries.flatMap(sessionEntryToContextMessages)];
     this.restoreUsageFloor(branch);
     this.refreshPending = true;
   }
@@ -292,12 +351,12 @@ export class ContextWindowController {
     const latestUser = branch.findLast((entry) => entry.type === "message" && entry.message.role === "user");
     const freshTokens = estimateTokens(header("pending", handoff, {
       userId: latestUser?.id, previousId: session.sessionManager.getLeafId(),
-    })) + this.overheadTokens();
+    }, this.recoveryGuidance())) + this.overheadTokens();
     const configuredReserve = this.reserveTokens();
     // A default reserve can exceed a small model's entire window. It is not an
     // automatic threshold; use bounded output headroom for explicit rollover.
     const reserve = capacity && configuredReserve >= capacity
-      ? Math.min(model?.maxTokens ?? 0, Math.floor(capacity / 4)) : configuredReserve;
+      ? this.responseHeadroom(capacity) : configuredReserve;
     if (!capacity || !Number.isFinite(capacity) || freshTokens >= Math.max(0, capacity - reserve)) {
       throw new Error("The handoff and prompt overhead do not fit the current model's fresh context with response headroom.");
     }
@@ -306,36 +365,55 @@ export class ContextWindowController {
     const reserve = this.requireSession().settingsManager.getCompactionSettings().reserveTokens;
     return Number.isFinite(reserve) ? Math.max(0, reserve) : 0;
   }
-  private toolSchemas(tools = this.requireSession().agent.state.tools): string {
-    return JSON.stringify(tools.map((tool) => ({
+  private recoveryGuidance(): string {
+    return contextRecoveryGuidance(this.requireSession().agent.state.tools.map((tool) => tool.name),
+      this.options.memoryInjected === true);
+  }
+  private responseHeadroom(capacity: number): number {
+    const max = this.requireSession().model?.maxTokens;
+    return Math.min(typeof max === "number" && Number.isFinite(max) && max > 0 ? max : 1024, Math.floor(capacity / 4));
+  }
+  private historyBudget(available: number, meter: Record<string, unknown>): number {
+    const factor = typeof meter.calibrationFactor === "number" ? meter.calibrationFactor : 1;
+    return Math.max(0, Math.floor(available / factor) - CONTEXT_MESSAGE_TOKENS);
+  }
+  private toolSchemas(tools = this.requireSession().agent.state.tools): EstimateFingerprint {
+    const schema = fingerprint(JSON.stringify(tools.map((tool) => ({
       name: tool.name, description: tool.description, parameters: tool.parameters,
-    })));
+    }))));
+    // Provider envelopes/deferred references differ. Reserve framing per active
+    // definition; measured requests already include this, so only growth is added.
+    schema.tokens += tools.length * 32;
+    return schema;
   }
   private overheadTokens(): number {
     const state = this.requireSession().agent.state;
-    return Math.ceil((state.systemPrompt.length + this.toolSchemas().length) / 4) + this.observedExtraTokens;
+    return Math.max(estimateContextText(state.systemPrompt), this.preparedPrompt?.systemPrompt.tokens ?? 0)
+      + Math.max(this.toolSchemas().tokens, this.preparedPrompt?.tools.tokens ?? 0) + this.observedExtraTokens;
   }
-  private overheadGrowth(snapshot: RequestSnapshot): number {
+  private overheadGrowth(snapshot: UsageSnapshot): number {
     const state = this.requireSession().agent.state;
     // A public next-turn hook can supply a request prompt different from state.
     // Keep that effective baseline until state actually changes. Never subtract
     // estimated shrinkage from measured provider usage or offset tool growth.
-    const prompt = state.systemPrompt === snapshot.stateSystemPrompt ? snapshot.systemPrompt : state.systemPrompt;
+    const statePrompt = fingerprint(state.systemPrompt);
+    const prompt = statePrompt.hash === snapshot.stateSystemPrompt.hash ? snapshot.systemPrompt : statePrompt;
     const stateTools = this.toolSchemas();
-    const tools = stateTools === snapshot.stateTools ? snapshot.tools : stateTools;
-    return Math.ceil(Math.max(0, prompt.length - snapshot.systemPrompt.length) / 4)
-      + Math.ceil(Math.max(0, tools.length - snapshot.tools.length) / 4)
-      + Math.max(0, this.observedExtraTokens - snapshot.injectedTokens);
+    const tools = stateTools.hash === snapshot.stateTools.hash ? snapshot.tools : stateTools;
+    snapshot.growth = Math.max(snapshot.growth, Math.max(0, prompt.tokens - snapshot.systemPrompt.tokens)
+      + Math.max(0, tools.tokens - snapshot.tools.tokens)
+      + Math.max(0, this.observedExtraTokens - snapshot.injectedTokens));
+    return snapshot.growth;
   }
   private remaining(): Record<string, unknown> {
     const session = this.requireSession();
     const model = session.model;
     const messages = session.agent.state.messages;
     const key = modelIdentity(model);
-    if (key !== this.modelKey) { this.modelKey = key; this.usageFloor = messages.length; }
+    if (key !== this.modelKey) { this.modelKey = key; this.generation++; this.usageFloor = messages.length; }
     let usageIndex = -1;
     let usageTokens = 0;
-    let usageSnapshot: RequestSnapshot | undefined;
+    let usageSnapshot: UsageSnapshot | undefined;
     for (let index = messages.length - 1; index >= this.usageFloor; index--) {
       const message = messages[index]!;
       if (message.role !== "assistant") continue;
@@ -343,21 +421,19 @@ export class ContextWindowController {
       if (message.provider !== model?.provider || message.model !== model?.id) break;
       const snapshot = this.usageSnapshots.get(message);
       // A restored usage count has no trustworthy prompt/schema baseline.
-      if (!snapshot || snapshot.modelKey !== key || snapshot.windowId !== this.windowId) continue;
-      const usage = message.usage;
-      if (!usage || typeof usage !== "object") continue;
-      const values = [usage.input, usage.output, usage.cacheRead, usage.cacheWrite];
-      if (message.stopReason !== "error" && message.stopReason !== "aborted"
-        && values.every((value) => Number.isFinite(value) && value >= 0)) {
-        const components = values.reduce((sum, value) => sum + value, 0);
-        const total = Number.isFinite(usage.totalTokens) && usage.totalTokens >= 0 ? usage.totalTokens : 0;
-        if (Math.max(components, total) > 0) {
-          usageTokens = Math.max(components, total); usageIndex = index; usageSnapshot = snapshot; break;
-        }
-      }
+      if (!snapshot || snapshot.modelKey !== key || snapshot.windowId !== this.windowId
+        || snapshot.generation !== this.generation) continue;
+      // A non-append source or modified response invalidates this projection.
+      // Fall back once rather than hashing every older prefix (quadratic work).
+      if (snapshot.sourceCount !== index || snapshot.responseHash !== messageHash([message])
+        || snapshot.sourceHash !== messageHash(messages.slice(0, index))) break;
+      usageTokens = snapshot.total; usageIndex = index; usageSnapshot = snapshot; break;
     }
-    const trailing = messages.slice(usageIndex + 1).reduce((sum, message) => sum + estimateTokens(message), 0);
-    const overhead = usageSnapshot ? this.overheadGrowth(usageSnapshot) : this.overheadTokens();
+    const rawTrailing = messages.slice(usageIndex + 1).reduce((sum, message) => sum + estimateTokens(message), 0);
+    const rawOverhead = usageSnapshot ? this.overheadGrowth(usageSnapshot) : this.overheadTokens();
+    const factor = usageSnapshot?.factor ?? 1;
+    const trailing = Math.ceil(rawTrailing * factor);
+    const overhead = Math.ceil(rawOverhead * factor);
     const used = Math.ceil(usageTokens + trailing + overhead);
     const capacity = model && Number.isFinite(model.contextWindow) && model.contextWindow > 0 ? model.contextWindow : null;
     const reserve = this.reserveTokens();
@@ -368,7 +444,10 @@ export class ContextWindowController {
       remainingBeforeReserve: capacity === null ? null : Math.max(0, capacity - reserve - used),
       source: usageIndex < 0 ? "estimate" : trailing > 0 || overhead > 0 ? "provider_usage_plus_estimate" : "provider_usage",
       providerUsageTokens: usageTokens, estimatedTrailingTokens: trailing, estimatedOverheadTokens: overhead,
-      note: "Remaining capacity is approximate. Provider usage requires a matching request, model capacity, and active window. Conservative estimates add only positive prompt, tool-schema, and observed injected-context growth; shrinkage never reduces measured usage. Unobserved dynamic context and provider tokenization can differ. Without a request baseline, the full active context is estimated. No automatic rollover threshold is enabled. If the configured reserve exhausts capacity, explicit rollover uses bounded response headroom instead.",
+      calibrationFactor: factor, calibrationLimited: usageSnapshot?.limited ?? false,
+      calibrationEligible: usageSnapshot?.eligible ?? false,
+      uncalibratedTrailingTokens: rawTrailing, uncalibratedOverheadTokens: rawOverhead,
+      note: "Remaining capacity is approximate. Provider usage requires a matching request, model capacity, and active window. Conservative estimates use UTF-8 bytes / 3, 1200 tokens per image and message framing. The upward-only calibration factor (1–2, prompt samples >=1024 estimated tokens) applies only to heuristic tail and positive overhead growth, never measured totals. Growth stays at its per-anchor high-water mark until a newer measured response; shrinkage never reduces measured usage. Factor saturation is uncertainty, not an accuracy guarantee. Unobserved dynamic context, payload hooks and provider tokenization can differ. Without a request baseline, the full active context is estimated. No automatic rollover threshold is enabled. If the configured reserve exhausts capacity, explicit rollover uses bounded response headroom instead.",
     };
   }
 }

package/src/conversation-branch-popup.tsx

@@ -0,0 +1,46 @@
+import type { ConversationBranchPoint } from "./conversation-branch";
+import { PopupFrame } from "./popup-frame";
+import { truncateStatusText } from "./status-metadata";
+import type { Theme } from "./theme";
+
+/** Small pages also bound mounted rows; App alone owns keyboard and authority. */
+export const CONVERSATION_BRANCH_PAGE_SIZE = 8;
+
+export function ConversationBranchPopup({ theme, points, cursor, offset, total, confirming, terminalWidth, terminalHeight }: {
+  theme: Theme;
+  points: readonly ConversationBranchPoint[];
+  cursor: number;
+  offset: number;
+  total: number;
+  confirming: boolean;
+  terminalWidth: number;
+  terminalHeight: number;
+}) {
+  const width = Math.max(1, Math.min(100, terminalWidth - 2));
+  const height = Math.max(1, Math.min(22, terminalHeight - 2));
+  const columns = Math.max(1, width - 4);
+  const selected = points[cursor];
+  const rows = Math.max(1, height - 12);
+  const start = Math.max(0, cursor - rows + 1);
+  return <PopupFrame theme={theme} terminalWidth={terminalWidth} terminalHeight={terminalHeight}
+    geometry={{ left: Math.max(0, Math.floor((terminalWidth - width) / 2)), top: Math.max(0, Math.floor((terminalHeight - height) / 2)), width, height }}
+    title=" Same-session conversation branch " padding={1} zIndex={110}>
+    <text content="SAME session and file; full tree and archives retained." fg={theme.fg} flexShrink={0} />
+    <text content="Files/code and CURRENT goals, todos, settings, News and tool groups are NOT rewound." fg={theme.warn} flexShrink={0} />
+    <text content="No summary, file copy or automatic submission. Runtime approvals are revoked." fg={theme.dim} flexShrink={0} />
+    <box height={1} flexShrink={0} />
+    {confirming && selected ? <>
+      <text content={selected.kind === "user" ? "Return BEFORE this user message; restore plain text as an untrusted draft." : "Continue AFTER this settled assistant endpoint; editor stays empty."} fg={theme.fg} flexShrink={0} />
+      <text content={truncateStatusText(selected.label, columns) ?? ""} fg={theme.accent} flexShrink={0} />
+      <text content={`${selected.currentPath ? "current path" : "alternate path"}${selected.archived ? " · archived window" : ""}`} fg={theme.dim} flexShrink={0} />
+    </> : <>
+      {points.length === 0 ? <text content="No safe conversation points available." fg={theme.dim} /> : points.slice(start, start + rows).map((point, index) => <text key={point.entryId}
+        content={truncateStatusText(`${start + index === cursor ? "› " : "  "}${point.kind === "user" ? "BEFORE user" : "AFTER assistant"} · ${point.currentPath ? "current" : "alternate"}${point.archived ? " · archived" : ""} · ${point.label}`, columns) ?? ""}
+        fg={start + index === cursor ? theme.accent : theme.fg} bg={start + index === cursor ? theme.selectionBg : theme.popupBg}
+        height={1} flexShrink={0} wrapMode="none" />)}
+    </>}
+    <box flexGrow={1} />
+    <text content={confirming ? "Enter confirm branch · Esc back · Ctrl+C close" : `Points ${total ? offset + 1 : 0}–${offset + points.length} / ${total} · ↑↓ select · ←→ page`} fg={theme.dim} flexShrink={0} />
+    {!confirming ? <text content="Enter preview · Esc close" fg={theme.dim} flexShrink={0} /> : null}
+  </PopupFrame>;
+}

package/src/conversation-branch.ts

@@ -0,0 +1,227 @@
+import { createHash, randomUUID } from "node:crypto";
+import type { AgentSession, ModelRuntime, SessionEntry, SessionManager } from "@earendil-works/pi-coding-agent";
+
+export const CONVERSATION_BRANCH_CUSTOM_TYPE = "pum.conversation_branch";
+const MAX_ENTRIES = 100_000;
+const MAX_TEXT = 100_000;
+const runtimeTokens = new WeakMap<AgentSession, { token: string; manager: SessionManager; id: string; cwd: string; file: string | undefined }>();
+const inputTracking = new WeakMap<AgentSession, { disposed: boolean; nextTurnSeen: boolean }>();
+
+/** Bind immediately after SDK creation, BEFORE extension startup/first admission.
+ * pi's public pending count excludes nextTurn custom messages, and it has no
+ * public getter or unique consumption receipt for that queue. Conservatively
+ * refuse branching for the remainder of a runtime that ever accepted nextTurn.
+ * No private SDK fields, content copies, or persisted trust markers are used.
+ */
+export function bindConversationBranchSession(session: AgentSession): void {
+  if (inputTracking.has(session)) return;
+  const state = { disposed: false, nextTurnSeen: false };
+  inputTracking.set(session, state);
+  const send = session.sendCustomMessage.bind(session);
+  session.sendCustomMessage = (...args) => {
+    if (state.disposed) return Promise.reject(new Error("The conversation runtime is disposed."));
+    if (args[1]?.deliverAs === "nextTurn") state.nextTurnSeen = true;
+    return send(...args);
+  };
+  const dispose = session.dispose.bind(session);
+  session.dispose = () => { state.disposed = true; dispose(); };
+}
+
+export function hasConversationBranchPendingInput(session: AgentSession): boolean {
+  const state = inputTracking.get(session);
+  return !state || state.disposed || state.nextTurnSeen || session.agent.hasQueuedMessages();
+}
+
+/** The SDK ignores recorded model/effort when the selected context has no
+ * messages. Explicitly restore navigation-anchored state even before root-user
+ * re-edit, using pi's catalog and creation options, never global-default writes.
+ */
+export function conversationBranchState(manager: SessionManager, models: ModelRuntime): {
+  model: AgentSession["model"]; thinkingLevel: AgentSession["thinkingLevel"];
+} | undefined {
+  const entries = manager.getEntries();
+  if (!entries.some((entry) => entry.type === "custom" && entry.customType === CONVERSATION_BRANCH_CUSTOM_TYPE)) return;
+  // Selection limits must not become a new general resume limit after a session
+  // grows. Bound traversal by the already-loaded entry count instead, without
+  // copying the tree or letting a malformed cycle enter SDK context building.
+  let remaining = entries.length;
+  let cursor = manager.getLeafId();
+  let anchored = false;
+  while (cursor !== null) {
+    const entry = manager.getEntry(cursor);
+    if (!entry || remaining-- <= 0) throw new Error("Conversation branch history has invalid ancestry.");
+    if (entry.type === "custom" && entry.customType === CONVERSATION_BRANCH_CUSTOM_TYPE) anchored = true;
+    cursor = entry.parentId;
+  }
+  if (!anchored) return;
+  const state = manager.buildSessionContext();
+  const model = state.model ? models.getModel(state.model.provider, state.model.modelId) : undefined;
+  if (state.model && !model) throw new Error("The conversation branch's recorded model is unavailable. Refusing to substitute global defaults.");
+  if (!["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(state.thinkingLevel)) {
+    throw new Error("The conversation branch's recorded effort is invalid.");
+  }
+  return { model, thinkingLevel: state.thinkingLevel as AgentSession["thinkingLevel"] };
+}
+
+/** An opaque, runtime-local confirmation snapshot, never command authority. */
+export interface ConversationBranchSelection {
+  entryId: string;
+  runtimeToken: string;
+  leafId: string | null;
+  entryCount: number;
+  prefixDigest: string;
+  textDigest: string;
+}
+export interface ConversationBranchPoint {
+  selection: ConversationBranchSelection;
+  entryId: string;
+  kind: "user" | "assistant";
+  label: string;
+  currentPath: boolean;
+  archived: boolean;
+}
+export interface ConversationBranchPage {
+  points: ConversationBranchPoint[];
+  total: number;
+  nextOffset: number | null;
+}
+const digest = (text: string) => createHash("sha256").update(text).digest("hex");
+function token(session: AgentSession): string {
+  let value = runtimeTokens.get(session);
+  const manager = session.sessionManager;
+  if (!value) {
+    value = { token: randomUUID(), manager, id: manager.getSessionId(), cwd: manager.getCwd(), file: manager.getSessionFile() };
+    runtimeTokens.set(session, value);
+  }
+  return value.token;
+}
+/** Identity/ancestry only: never inspect private custom-entry data. */
+function prefix(entries: SessionEntry[]): string {
+  const hash = createHash("sha256");
+  for (const entry of entries) hash.update(JSON.stringify([entry.id, entry.parentId, entry.type])).update("\n");
+  return hash.digest("hex");
+}
+function plainText(content: unknown, user: boolean): string | undefined {
+  if (typeof content === "string") return user && content.length <= MAX_TEXT && content.trim() ? content : undefined;
+  if (!Array.isArray(content) || !content.length || content.length > 4096) return;
+  let text = "";
+  for (const part of content) {
+    if (!part || typeof part !== "object") return;
+    if (part.type === "text" && typeof part.text === "string") {
+      if (text.length + part.text.length > MAX_TEXT) return;
+      text += part.text;
+    }
+    else if (!user && part.type === "thinking") continue; // Never read reasoning/signatures.
+    else return; // No attachment loss, tool payloads, or unknown content kinds.
+    if (text.length > MAX_TEXT) return;
+  }
+  return text.trim() ? text : undefined;
+}
+type State = { pending: ReadonlyMap<string, string>; valid: boolean };
+type Candidate = { entry: SessionEntry; kind: "user" | "assistant" };
+function project(session: AgentSession) {
+  const entries = session.sessionManager.getEntries();
+  if (entries.length > MAX_ENTRIES) throw new Error("Conversation branch history exceeds the safe selection limit.");
+  const byId = new Map<string, SessionEntry>();
+  const states = new Map<string, State>();
+  const candidates: Candidate[] = [];
+  const empty: State = { pending: new Map(), valid: true };
+  for (const entry of entries) {
+    if (typeof entry.id !== "string" || !entry.id || entry.id.length > 128 || byId.has(entry.id)
+      || (entry.parentId !== null && !byId.has(entry.parentId))) {
+      throw new Error("Conversation branch history has invalid ancestry.");
+    }
+    byId.set(entry.id, entry);
+    const parent = entry.parentId === null ? empty : states.get(entry.parentId)!;
+    let state = parent;
+    if (entry.type === "message") {
+      const message = entry.message;
+      if (!message || typeof message !== "object") throw new Error("Conversation branch history has an invalid message.");
+      if (message.role === "assistant") {
+        const boundedContent = Array.isArray(message.content) && message.content.length <= 4096;
+        const calls = boundedContent ? message.content.filter((part) => part?.type === "toolCall") : [];
+        const pending = new Map<string, string>();
+        let valid = parent.valid && parent.pending.size === 0 && boundedContent && message.stopReason !== "pending"
+          && message.content.every((part) => part && ["text", "thinking", "toolCall"].includes(part.type));
+        for (const call of calls) {
+          if (typeof call.id !== "string" || !call.id || typeof call.name !== "string" || !call.name || pending.has(call.id)) valid = false;
+          pending.set(call.id, call.name);
+        }
+        if (pending.size > 256) valid = false;
+        state = { pending, valid };
+        const text = plainText(message.content, false);
+        if (valid && !pending.size && message.stopReason === "stop" && text !== undefined) {
+          candidates.push({ entry, kind: "assistant" });
+        }
+      } else if (message.role === "toolResult") {
+        const pending = new Map(parent.pending);
+        const valid = parent.valid && typeof message.toolCallId === "string" && typeof message.toolName === "string"
+          && pending.has(message.toolCallId) && pending.get(message.toolCallId) === message.toolName;
+        pending.delete(message.toolCallId);
+        state = { pending, valid };
+      } else if (message.role === "user") {
+        state = { pending: parent.pending, valid: parent.valid && parent.pending.size === 0 };
+        const text = plainText(message.content, true);
+        if (state.valid && text !== undefined) candidates.push({ entry, kind: "user" });
+      }
+    }
+    states.set(entry.id, state);
+  }
+  const current = new Set<string>();
+  let cursor = session.sessionManager.getLeafId();
+  if (cursor !== null && !byId.has(cursor)) throw new Error("Conversation branch history has an invalid leaf.");
+  while (cursor !== null) { current.add(cursor); cursor = byId.get(cursor)!.parentId; }
+  // Structural metadata only: a boundary archives its ancestors, not its literal handoff.
+  const archived = new Set<string>();
+  for (let index = entries.length - 1; index >= 0; index--) {
+    const entry = entries[index]!;
+    if ((archived.has(entry.id) || (entry.type === "custom" && entry.customType === "pum.context_window")) && entry.parentId !== null) {
+      archived.add(entry.parentId);
+    }
+  }
+  return { entries, candidates, current, archived };
+}
+
+/** Bounded newest-first UI projection. No IO, private bodies, summaries, or mutation. */
+export function listConversationBranchPoints(session: AgentSession, options: { offset?: number; limit?: number } = {}): ConversationBranchPage {
+  const offset = options.offset ?? 0;
+  const limit = options.limit ?? 20;
+  if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 50) {
+    throw new Error("Invalid conversation branch page.");
+  }
+  const { entries, candidates, current, archived } = project(session);
+  const snapshot = { runtimeToken: token(session), leafId: session.sessionManager.getLeafId(), entryCount: entries.length, prefixDigest: prefix(entries) };
+  const ordered = candidates.reverse();
+  return {
+    points: ordered.slice(offset, offset + limit).map(({ entry, kind }) => {
+      const text = entry.type === "message" && "content" in entry.message ? plainText(entry.message.content, kind === "user")! : "";
+      return {
+        entryId: entry.id, kind,
+        label: text.slice(0, 512).replace(/[\u0000-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, " ").replace(/\s+/g, " ").trim().slice(0, 160),
+        currentPath: current.has(entry.id), archived: archived.has(entry.id),
+        selection: { ...snapshot, entryId: entry.id, textDigest: digest(text) },
+      };
+    }),
+    total: ordered.length,
+    nextOffset: offset + limit < ordered.length ? offset + limit : null,
+  };
+}
+
+/** Re-run safety, identity, leaf and immutable-prefix validation at confirmation. */
+export function validateConversationBranchSelection(session: AgentSession, selection: ConversationBranchSelection): { targetId: string | null; editorText?: string } {
+  const stale = () => new Error("Conversation branch selection is stale or unsafe. Open /branch again.");
+  const bound = runtimeTokens.get(session);
+  const manager = session.sessionManager;
+  if (!bound || !selection || selection.runtimeToken !== bound.token || bound.manager !== manager
+    || bound.id !== manager.getSessionId() || bound.cwd !== manager.getCwd() || bound.file !== manager.getSessionFile()
+    || selection.leafId !== manager.getLeafId()) throw stale();
+  const { entries, candidates } = project(session);
+  if (selection.entryCount !== entries.length || selection.prefixDigest !== prefix(entries)) throw stale();
+  const candidate = candidates.find(({ entry }) => entry.id === selection.entryId);
+  if (!candidate || candidate.entry.type !== "message" || !("content" in candidate.entry.message)) throw stale();
+  const text = plainText(candidate.entry.message.content, candidate.kind === "user");
+  if (text === undefined || selection.textDigest !== digest(text)) throw stale();
+  return candidate.kind === "user"
+    ? { targetId: candidate.entry.parentId, editorText: text }
+    : { targetId: candidate.entry.id };
+}