pi-fold 2.0.0 → 3.1.0

package/extensions/lib/folding.ts

@@ -10,6 +10,7 @@ import {
   stableStringify,
 } from "../json.ts";
 import {
+  contentText,
   boundedUtf8,
   bytes,
   clone,
@@ -28,7 +29,6 @@ import {
   orderedRoots,
   refsInOrder,
   refsProtected,
-  toolRefsProtected,
 } from "./measurement.ts";
 import {
   childFoldIds,
@@ -54,7 +54,6 @@ import {
   PEEK_DEFAULT_MAX_BYTES,
   PEEK_HEAD_SHARE,
   STATUS_DIET_INDEX_ROWS,
-  zoneBytes,
 } from "./policy.ts";
 import type {
   ActiveContextSnapshot,
@@ -73,7 +72,9 @@ import {
   chapterUnits,
   unpinnedStaleFolds,
   deterministicChapterCandidateBrief,
+  toolClipHead,
   deterministicConsolidationBrief,
+  oneLine,
   NO_FOLD_KINDS,
   partsForRange,
   resultCall,
@@ -81,36 +82,59 @@ import {
   selectAutomaticRefold,
   selectAutomaticToolBatch,
 } from "./selection.ts";
+import { staleSpanMatureEnd } from "./transcript.ts";
 
 export function selectAutomaticChapter(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
-  maximumSourceRefs: number = snapshot.policy.maxFoldSourceRefs,
   claimed: ReadonlySet<string> = new Set<string>(),
 ): FoldCandidate | null {
   const units = chapterUnits(snapshot);
   const allowedChildren = NO_FOLD_KINDS;
+  // The maturity floor: a stale span may end only where the batch lane has already had
+  // its chance, so a chapter can never claim a tool batch one turn before it qualifies.
+  const matureEnd = staleSpanMatureEnd(snapshot.messages);
   for (let unitIndex = 0; unitIndex < units.length; unitIndex += 1) {
     const first = units[unitIndex];
+    if (first.end > matureEnd) break;
     let best: FoldCandidate | null = null;
-    const turnStarts = new Set<number>();
     for (let endIndex = unitIndex; endIndex < units.length; endIndex += 1) {
       const unit = units[endIndex];
+      if (unit.end > matureEnd) break;
       if (endIndex > unitIndex && unit.start !== units[endIndex - 1].end) break;
-      turnStarts.add(unit.turnStart);
-      if (turnStarts.size > snapshot.policy.maxChapterTurns) break;
       const coherentSegment = endIndex > unitIndex || first.end - first.start > 1;
       if (!coherentSegment) continue;
+      // A DISQUALIFIED RANGE DISQUALIFIES EVERY LARGER ONE, so the walk stops here rather
+      // than rediscovering the same obstruction at every remaining endIndex (issue #2,
+      // 2026-08-28). The inner loop only ever EXTENDS the range to the right, and all
+      // three conditions below are monotone under that extension: an unmapped index or an
+      // overlapping root stays inside a larger range, a claimed ref stays claimed because
+      // `claimed` is fixed for the whole walk, and a protected ref stays protected. Only
+      // `size > MAX_FOLD_SPAN_CHARS` bounded this loop, and these three `continue`s skipped
+      // the sizing that would have hit it, so an obstruction near the start of the window
+      // let the walk run to the end of `units` for every start: O(units^2) iterations doing
+      // O(span) work each. Instrumented on a 549KB window, ONE context event ran 457,986
+      // inner iterations and allocated 98,811,691 FoldPart objects, of which 456,724
+      // iterations (99.7 percent) died on the `claimed` check and only 72 ever reached the
+      // sizing. That is 42 seconds of CPU at 824KB, ungated by occupancy, on every event.
+      // With the walk stopped at the first obstruction the same event costs 377ms.
+      //
+      // This is 00dfeb3's defect one layer out. That commit memoized `orderedRoots` to kill
+      // the O(roots x folds) rebuild INSIDE each iteration and its own comment named "a walk
+      // that is quadratic in units" as the standing cost; this is that walk. Nothing about
+      // WHICH candidate is selected changes: every iteration this skips would have been
+      // skipped by the same condition.
       const parts = partsForRange(snapshot, state, first.start, unit.end - 1, allowedChildren);
-      if (!parts || parts.some((part) => part.kind === "fold" && state.expanded.includes(part.foldId))) continue;
+      if (!parts || parts.some((part) => part.kind === "fold" && state.expanded.includes(part.foldId))) break;
       const refs = candidateSourceRefs(parts, state);
-      if (refs.length > maximumSourceRefs) break;
-      if (claimed.size && refs.some((ref) => claimed.has(objectRefKey(ref)))) continue;
-      if (refsProtected(refs, state, snapshot)) continue;
+      if (claimed.size && refs.some((ref) => claimed.has(objectRefKey(ref)))) break;
+      if (refsProtected(refs, state, snapshot)) break;
       const size = bytes(encodedFoldSource(snapshot, state, parts, "chapter"));
-      if (size > snapshot.policy.maxChapterChars && endIndex > unitIndex) break;
       const biteSized = size <= MAX_FOLD_SPAN_CHARS || endIndex === unitIndex;
-      if (size >= snapshot.policy.minChapterChars && biteSized) best = { kind: "chapter", parts, sourceRefs: refs };
+      // ACCUMULATE UNTIL OVER, never cut to hit the number. The walk grows the span one
+      // whole unit at a time and records the first one that carries it past the floor,
+      // so a fold is always at least minFoldChars and always ends on a message boundary.
+      if (size >= snapshot.thresholds.minFoldChars && biteSized) best = { kind: "chapter", parts, sourceRefs: refs };
       if (size > MAX_FOLD_SPAN_CHARS) break;
     }
     if (best) return best;
@@ -123,7 +147,7 @@ export function selectAutomaticStaleSpan(
   state: ActiveContextState,
   claimed: ReadonlySet<string> = new Set<string>(),
 ): FoldCandidate | null {
-  const chapter = selectAutomaticChapter(snapshot, state, snapshot.policy.maxFoldSourceRefs, claimed);
+  const chapter = selectAutomaticChapter(snapshot, state, claimed);
   const folds = selectAutomaticConsolidations(snapshot, state)[0] ?? null;
   if (!chapter || !folds) return chapter ?? folds;
   const at = (candidate: FoldCandidate): number =>
@@ -173,7 +197,7 @@ export function selectAutomaticRung(
   const claimedFoldIds = options.claimedFoldIds ?? new Set<string>();
   if (!options.toolOnly && state.prepared) {
     if (!Number.isFinite(ratio) || ratio < hardFenceRatio(snapshot)) return null;
-    const candidate = selectAutomaticChapter(snapshot, state, snapshot.policy.maxFoldSourceRefs, claimed);
+    const candidate = selectAutomaticChapter(snapshot, state, claimed);
     return candidate ? { kind: "prepared-chapter", candidate } : null;
   }
   const tool = selectAutomaticToolBatch(snapshot, state, claimed)[0] ?? null;
@@ -405,10 +429,8 @@ export async function prepareFold(input: {
   now?: () => number;
 }): Promise<PreparedFold> {
   const { candidate, snapshot, state } = input;
-  const protectedSource = candidate.kind === "tool-result"
-    ? toolRefsProtected(candidate.sourceRefs, state, snapshot)
-    : refsProtected(candidate.sourceRefs, state, snapshot);
-  if (!candidate.sourceRefs.length || candidate.sourceRefs.length > snapshot.policy.maxFoldSourceRefs ||
+  const protectedSource = refsProtected(candidate.sourceRefs, state, snapshot);
+  if (!candidate.sourceRefs.length ||
       refsInOrder(snapshot, candidate.sourceRefs) === null || protectedSource) {
     throw new Error("Fold source is not exact, stale, and unprotected");
   }
@@ -421,13 +443,43 @@ export async function prepareFold(input: {
   let brief: string;
   let provenance: BriefProvenance;
   if (input.brief !== undefined) {
-    const complaint = briefContractComplaint(
-      input.brief.trim(), snapshot.policy.maxBriefChars, snapshot.toolName);
-    if (complaint !== null) throw new Error(`Supplied brief rejected. ${complaint}`);
-    brief = input.brief.trim();
-    provenance = typeof input.briefProvenance === "object"
-      ? clone(input.briefProvenance)
-      : { kind: input.briefProvenance ?? "supplied" };
+    const declaredKind = typeof input.briefProvenance === "object"
+      ? input.briefProvenance.kind
+      : input.briefProvenance ?? "supplied";
+    if (declaredKind === "supplied") {
+      // A SUPPLIED BRIEF AUGMENTS THE HEAD, NEVER REPLACES IT (rep 7 of
+      // sol-20260823-live: replacement deleted the fact-carrying identification and 74
+      // of 95 peeks recovered values the run's own briefs dropped). The agent's clause
+      // is judged against its own reserve so the refusal names the budget the agent
+      // actually has, and the deterministic head keeps the remainder of the one policy
+      // cap. Only the agent's OWN words take this path: a deterministic brief arriving
+      // through the same door IS the head, and a re-prepared augmented brief is already
+      // composed, so each passes through under the whole-brief cap instead.
+      const complaint = briefContractComplaint(
+        input.brief.trim(), snapshot.policy.agentBriefReserve, snapshot.toolName);
+      if (complaint !== null) throw new Error(`Supplied brief rejected. ${complaint}`);
+      const clause = input.brief.trim();
+      const head = candidate.kind === "consolidation"
+        ? deterministicConsolidationBrief(candidate, state, snapshot.toolName, snapshot)
+        : deterministicChapterCandidateBrief(snapshot, candidate);
+      if (head) {
+        const seam = " · Agent: ";
+        const headRoom = Math.max(0, snapshot.policy.maxBriefChars - seam.length - clause.length);
+        brief = `${oneLine(head, headRoom)}${seam}${clause}`;
+        provenance = { kind: "augmented" };
+      } else {
+        brief = clause;
+        provenance = { kind: "supplied" };
+      }
+    } else {
+      const complaint = briefContractComplaint(
+        input.brief.trim(), snapshot.policy.maxBriefChars, snapshot.toolName);
+      if (complaint !== null) throw new Error(`Supplied brief rejected. ${complaint}`);
+      brief = input.brief.trim();
+      provenance = typeof input.briefProvenance === "object"
+        ? clone(input.briefProvenance)
+        : { kind: declaredKind } as BriefProvenance;
+    }
   } else {
     brief = candidate.kind === "consolidation"
       ? deterministicConsolidationBrief(candidate, state, snapshot.toolName, snapshot)
@@ -580,13 +632,12 @@ export function preparedFoldError(input: {
   if (prepared.branchSha256 !== branchSha256(snapshot, [
     ...prepared.beforeRefs, ...prepared.sourceRefs, ...prepared.afterRefs,
   ])) return "branch drift";
-  const toolSource = prepared.fold.kind === "tool-result";
-  if (indices.some((index) => toolSource
-    ? snapshot.toolProtectedIndices.has(index)
-    : snapshot.protectedIndices.has(index))) return "fresh-tail drift";
-  if (toolSource
-    ? toolRefsProtected(prepared.sourceRefs, state, snapshot)
-    : refsProtected(prepared.sourceRefs, state, snapshot)) return "source became protected";
+  // One protected set now: an entry is unfoldable because its turn has not completed or
+  // because it carries no evidence ref, and both are validity, not recency. The branch on
+  // fold kind went with fresh-tail protection: it read `toolRefsProtected` on one side,
+  // and once that collapsed onto `refsProtected` both arms were the same call.
+  if (indices.some((index) => snapshot.protectedIndices.has(index))) return "protection drift";
+  if (refsProtected(prepared.sourceRefs, state, snapshot)) return "source became protected";
   if (Object.prototype.hasOwnProperty.call(input, "ratio")) {
     if (input.ratio === null || typeof input.ratio !== "number" || !Number.isFinite(input.ratio)) {
       return "current pressure unavailable";
@@ -686,7 +737,7 @@ export function protectEvidence(
   if (byKey.size > MAX_ACTIVE_PROTECTED) {
     throw new Error(
       `Protecting ${ids.join(", ")} would hold ${byKey.size} refs, over the ${MAX_ACTIVE_PROTECTED}-ref cap; ` +
-        "unprotect something first",
+        "unpin something first",
     );
   }
   return clearPrepared({
@@ -737,9 +788,7 @@ export function renderFold(
   const refs = flattenFoldRefs(fold, state);
   const indices = refsInOrder(snapshot, refs);
   if (!indices) return null;
-  const mustReveal = state.expanded.includes(fold.id) || (fold.kind === "tool-result"
-    ? toolRefsProtected(refs, state, snapshot)
-    : refsProtected(refs, state, snapshot));
+  const mustReveal = state.expanded.includes(fold.id) || (refsProtected(refs, state, snapshot));
   if (!mustReveal) {
     const first = snapshot.messages[indices[0]] as Record<string, unknown>;
     const text = foldPlaceholder(fold, state, snapshot);
@@ -816,6 +865,13 @@ export function pinnedPeekMass(
   state: ActiveContextState,
 ): { bytes: number; results: number } {
   const explicitProtected = explicitProtectedKeys(state);
+  // ITS TWO SIBLINGS ALREADY RETURN HERE (2026-08-28). `protectedStaleMass` and
+  // `explicitProtectedMass` both open with this guard; this one did the whole quadratic walk
+  // and then returned zero, because every increment in its final loop is gated on
+  // `explicitProtected.has(...)`. So the guard is exact, not an approximation. It is not
+  // hypothetical either: `state.protected` is empty in all 10,521 persisted state records
+  // across 36 sealed runs, the corpus carrying no `context.pin` event at all.
+  if (!explicitProtected.size) return { bytes: 0, results: 0 };
   const folded = new Set<string>();
   for (const fold of state.folds) {
     for (const ref of flattenFoldRefs(fold, state)) folded.add(objectRefKey(ref));
@@ -869,19 +925,62 @@ export function projectActiveContext(
       index += 1;
     }
   }
+  applyToolClips(output, state, snapshot);
   assertProjectionPreservesToolLinkage(snapshot.messages, output);
   return output;
 }
 
+// THE TOOL-CALL DIET'S VIEW (2026-08-24). A clipped result renders in place as its
+// identified head with the cut stated and the recovery named, matched BY CALL ID and
+// identity-preserving on role, call id, tool name, error flag and timestamp, exactly
+// the ephemeral-peek withdrawal's shape one mechanism over. Clips are only ever ADDED
+// inside a commit transaction, and a commit already rewrites the projection, so a
+// non-commit pass with unchanged clips renders byte-identically and the frozen prefix
+// never moves. Every reader shares this pass because every reader shares
+// projectActiveContext: the live projection, the persistence readers and the
+// attribution lens all see the same clipped view, and the full bytes stay in the
+// transcript behind the entry id the marker names.
+function applyToolClips(
+  output: unknown[],
+  state: ActiveContextState,
+  snapshot: ActiveContextSnapshot,
+): void {
+  if (!state.clips?.length) return;
+  const byCallId = new Map(state.clips.map((clip) => [clip.callId, clip]));
+  for (let index = 0; index < output.length; index += 1) {
+    const message = output[index] as Record<string, unknown> | null;
+    if (!message || (message as { role?: unknown }).role !== "toolResult") continue;
+    const callId = (message as { toolCallId?: unknown }).toolCallId;
+    if (typeof callId !== "string") continue;
+    const clip = byCallId.get(callId);
+    if (!clip) continue;
+    const details = (message as { details?: unknown }).details;
+    if (details && typeof (details as { projection?: unknown }).projection === "string") continue;
+    const full = contentText(message);
+    if (full.length <= snapshot.policy.toolClipFloorChars) continue;
+    const head = toolClipHead(full, snapshot.policy.toolClipHeadChars);
+    const hidden = full.length - head.length;
+    if (hidden <= 0) continue;
+    output[index] = {
+      role: "toolResult",
+      toolCallId: callId,
+      toolName: (message as { toolName?: unknown }).toolName,
+      content: [{ type: "text", text: `${head}\n... [${hidden} more chars clipped; ` +
+        `{"action":"peek","id":"${clip.entryId}"} returns the full result]` }],
+      isError: (message as { isError?: unknown }).isError ?? false,
+      details: { projection: "tool-clip" },
+      timestamp: (message as { timestamp?: unknown }).timestamp,
+    };
+  }
+}
+
 export function foldStatusRow(fold: ActiveFold, state: ActiveContextState, snapshot: ActiveContextSnapshot): Record<string, unknown> {
   const navigation = foldNavigation(fold, state, snapshot);
   const interval = foldInterval(fold, state, snapshot);
   const refs = flattenFoldRefs(fold, state);
   const allSourceIds = refs.map((ref) => ref.entryId);
   const sourceIds = allSourceIds.slice(0, 64);
-  const blocked = fold.kind === "tool-result"
-    ? toolRefsProtected(refs, state, snapshot)
-    : refsProtected(refs, state, snapshot);
+  const blocked = refsProtected(refs, state, snapshot);
   const projection = state.expanded.includes(fold.id) ? "expanded" : "folded";
   return {
     id: fold.id,
@@ -905,7 +1004,7 @@ export function foldStatusRow(fold: ActiveFold, state: ActiveContextState, snaps
         : { action: "refold", id: fold.id },
       expand: { action: "expand", id: fold.id },
       refold: { action: "refold", id: fold.id },
-      protect: { action: "protect", ids: [fold.id] },
+      pin: { action: "pin", ids: [fold.id] },
     },
   };
 }
@@ -995,7 +1094,6 @@ export function activeContextStatus(
   state: ActiveContextState,
   offset = 0,
   limit = 40,
-  maximumChapterSourceRefs = Number.MAX_SAFE_INTEGER,
   statusOptions: { diet?: boolean; indexRows?: number } = {},
 ): Record<string, unknown> {
   const roots = orderedRoots(state, snapshot).map((item) => item.fold.id);
@@ -1010,11 +1108,11 @@ export function activeContextStatus(
     stale: !snapshot.protectedIndices.has(item.index),
     protected: snapshot.protectedIndices.has(item.index) || protectedKeys.has(objectRefKey(item.ref)),
     staleToolResult: item.ref.role === "toolResult" &&
-      !snapshot.toolProtectedIndices.has(item.index) && !protectedKeys.has(objectRefKey(item.ref)) &&
+      !snapshot.protectedIndices.has(item.index) && !protectedKeys.has(objectRefKey(item.ref)) &&
       resultCall(snapshot, item.index, true) !== null,
   }] : []);
   const selectedObjects = objects.slice(offset, offset + limit);
-  const eligibleChapter = selectAutomaticChapter(snapshot, state, maximumChapterSourceRefs);
+  const eligibleChapter = selectAutomaticChapter(snapshot, state);
   const eligibleSourceIds = eligibleChapter?.sourceRefs.map((ref) => ref.entryId) ?? [];
   const eligibleEndpoints = eligibleSourceIds.length
     ? [...new Set([eligibleSourceIds[0], eligibleSourceIds.at(-1)!])]
@@ -1067,12 +1165,11 @@ export function activeContextStatus(
       endId: eligibleSourceIds.at(-1),
       action: { action: "fold", ids: eligibleEndpoints, brief: "<factual brief, at most 1000 characters>" },
     } : null,
-    rawTailMinimumBytes: zoneBytes(snapshot.thresholds.freshTail, snapshot.budgetTokens),
     currentTurnRequiresBoundary: false,
     actions: {
       status: { action: "status", offset, limit },
       fold: { action: "fold", ids: ["<source-or-fold-id>"], brief: "<optional factual brief, at most 1000 characters>" },
-      protect: { action: "protect", ids: ["<source-or-fold-id>"] },
+      pin: { action: "pin", ids: ["<source-or-fold-id>"] },
     },
   };
 }
@@ -1120,8 +1217,8 @@ export function boundStatusPayload(
   shrink(instrumentation, "events", "context event(s)", true);
   if (shrink(payload, "sourceMap", "source map row(s)") > 0) payload.sourceMapTruncated = true;
   shrink(payload, "topFolds", "top fold row(s)");
-  // The last epoch's receipt lists grow with commit depth (a 0.20 minTarget epoch
-  // applies dozens of marks). They are the commit's own receipt, so they outlast
+  // The last epoch's receipt lists grow with commit depth (a deep epoch applies dozens
+  // of marks). They are the commit's own receipt, so they outlast
   // every other diagnostic, but they still page away before any listing row the
   // caller actually asked for: on the detail pages, where none of the diagnostics
   // above exist, they are the mass that made one fold row miss the cap.
@@ -1170,9 +1267,7 @@ export function visibleCollapsedFolds(
   const visit = (fold: ActiveFold): void => {
     const refs = flattenFoldRefs(fold, state);
     if (!foldInterval(fold, state, snapshot)) return;
-    const protectedSource = fold.kind === "tool-result"
-      ? toolRefsProtected(refs, state, snapshot)
-      : refsProtected(refs, state, snapshot);
+    const protectedSource = refsProtected(refs, state, snapshot);
     if (!state.expanded.includes(fold.id) && !protectedSource) {
       output.push(fold);
       return;
@@ -1315,11 +1410,26 @@ export function peekFoldSource(input: {
   const source = stableStringify(messages);
   const sourceBytes = bytes(source);
   const offset = Math.min(Math.max(0, input.offset ?? 0), sourceBytes);
-  const budget = input.maximumBytes ?? PEEK_DEFAULT_MAX_BYTES;
+  // The widest read anyone may ask for is the policy's own source cap, the same ceiling
+  // the `wider` hint has always offered; an unclamped `bytes` was the one door left to a
+  // single result larger than any fold the runtime would cut.
+  const budget = Math.min(
+    input.maximumBytes ?? PEEK_DEFAULT_MAX_BYTES,
+    ACTIVE_CONTEXT_POLICY.maxSourceChars,
+  );
+  // ONE BUDGET GOVERNS THE WHOLE RESULT (sol-20260826-full2, pifold rep 1). The byte
+  // bound used to govern `source` alone while the descendant index rode free, so peeking
+  // the root of a deep consolidation tree returned 320 nested briefs, 423KB against a
+  // stated 16KB bound, durably into a window already near its budget; that one result is
+  // what the projection fence then aborted thirty-five requests over. The index seats
+  // first, into at most half the budget, because a parent's index is the point read; the
+  // source view takes everything the seated rows leave.
+  const catalog = boundedDescendantIndex(fold, input.state, Math.floor(budget / 2));
+  const sourceBudget = budget - catalog.seatedBytes;
   const window = offset > 0 ? utf8Slice(source, offset) : source;
   const view = offset > 0
-    ? { text: boundedUtf8(window, budget), omittedBytes: 0, contiguous: true }
-    : boundedHeadTail(window, budget);
+    ? { text: boundedUtf8(window, sourceBudget), omittedBytes: 0, contiguous: true }
+    : boundedHeadTail(window, sourceBudget);
   const returned = view.text;
   const returnedBytes = bytes(returned) - bytes(headTailMarker(view.omittedBytes));
   const nextOffset = view.contiguous && offset + returnedBytes < sourceBytes
@@ -1327,7 +1437,7 @@ export function peekFoldSource(input: {
     : null;
   const truncated = view.omittedBytes > 0 || nextOffset !== null;
   const children = childFoldIds(fold);
-  const index = descendantIndexRows(fold, input.state);
+  const index = catalog.rows;
   return {
     version: 1,
     action: "peek",
@@ -1346,25 +1456,31 @@ export function peekFoldSource(input: {
     truncated,
     view: offset > 0 ? "slice" : (view.omittedBytes > 0 ? "index" : "complete"),
     ...(index.length ? { index } : {}),
+    ...(catalog.omitted ? { indexOmitted: catalog.omitted } : {}),
     children,
     narrower: {
       ...(nextOffset === null ? {} : { slice: { action: "peek", id: fold.id, offset: nextOffset, bytes: returnedBytes } }),
       ...(children.length ? { child: { action: "peek", id: children[0] } } : {}),
     },
-    ...(truncated
-      ? { wider: { action: "peek", id: fold.id, bytes: Math.min(sourceBytes, ACTIVE_CONTEXT_POLICY.maxChapterChars) } }
+    ...(truncated || catalog.omitted
+      ? { wider: { action: "peek", id: fold.id, bytes: Math.min(sourceBytes, ACTIVE_CONTEXT_POLICY.maxSourceChars) } }
       : {}),
     lifetime: "these bytes stay in the window exactly as returned, like any other tool result, and " +
       `nothing rewrites this result in place. It is a COPY of fold ${fold.id}'s stored source, so the ` +
       `next commit reclaims it behind a placeholder naming ${fold.id}; peek ${fold.id} again for the ` +
       "same verbatim bytes, or pin this result to keep the copy raw.",
-    note: truncated
+    note: (truncated
       ? `Bounded read: ${returnedBytes} of ${sourceBytes} exact source bytes, ${view.omittedBytes} omitted ` +
         `from the middle. Widen with bytes, page with offset, or expand ${fold.id} to restore it in place.`
       : children.length
         ? `Complete stored span, one level: raw entries exactly, and ${children.length} child fold(s) still ` +
           "placeheld. Peek a child id to read its own span; the fold stayed collapsed and no projection changed."
-        : "Complete exact source; the fold stayed collapsed and no projection changed.",
+        : "Complete exact source; the fold stayed collapsed and no projection changed.") +
+      (catalog.omitted
+        ? ` The nested index seats the shallowest ${index.length} of ${index.length + catalog.omitted} ` +
+          "descendant briefs inside the byte budget; the deeper rows are one hop away by peeking a child id, " +
+          "or widen with bytes."
+        : ""),
     source: returned,
     ...(truncated
       ? {
@@ -1372,7 +1488,7 @@ export function peekFoldSource(input: {
           "bytes were NOT shown" +
           (view.omittedBytes ? " (the middle; the head and tail are both above)" : " (everything after this slice)") +
           `. Widen with {"action":"peek","id":"${fold.id}","bytes":${
-            Math.min(sourceBytes, ACTIVE_CONTEXT_POLICY.maxChapterChars)}}` +
+            Math.min(sourceBytes, ACTIVE_CONTEXT_POLICY.maxSourceChars)}}` +
           (nextOffset === null ? "" : ` or read on with {"action":"peek","id":"${fold.id}","offset":${nextOffset}}`) +
           ".",
       }
@@ -1404,6 +1520,38 @@ export function boundedHeadTail(
   };
 }
 
+/**
+ * The descendant index, seated inside a byte budget: shallowest rows first, whole rows
+ * only, the omitted counted rather than dropped. Depth order is the navigational order,
+ * because a row's own children are reachable by peeking it, so the rows worth seating
+ * first are the ones every deeper row is reachable THROUGH. Walk order breaks depth
+ * ties, which keeps siblings in span order. The seating stops at the first row that
+ * does not fit, so what is omitted is always a contiguous deep tail of the depth order
+ * and the note can state it as one count.
+ */
+export function boundedDescendantIndex(
+  fold: ActiveFold,
+  state: ActiveContextState,
+  budget: number,
+): { rows: Array<Record<string, unknown>>; omitted: number; seatedBytes: number } {
+  const walked = descendantIndexRows(fold, state)
+    .map((row, walk) => ({ row, walk }))
+    .sort((left, right) =>
+      Number(left.row.depth) - Number(right.row.depth) || left.walk - right.walk);
+  const rows: Array<Record<string, unknown>> = [];
+  // Counted as the array actually serializes, brackets and joining commas included, so
+  // "seated bytes" is the bytes the result carries and not an under-read of them.
+  let seatedBytes = 2;
+  for (const { row } of walked) {
+    const cost = bytes(stableStringify(row)) + (rows.length ? 1 : 0);
+    if (seatedBytes + cost > budget) break;
+    seatedBytes += cost;
+    rows.push(row);
+  }
+  if (!rows.length) seatedBytes = 0;
+  return { rows, omitted: walked.length - rows.length, seatedBytes };
+}
+
 export function descendantIndexRows(
   fold: ActiveFold,
   state: ActiveContextState,

package/extensions/lib/instrumentation.ts

@@ -64,6 +64,7 @@ export interface CacheObservation {
   change: ProjectionChange;
   inputTokens: number;
   cacheReadTokens: number;
+  cacheWriteTokens: number;
   providerSideMiss: boolean;
 }
 
@@ -83,20 +84,14 @@ export interface ContextEvent {
 export type ContextEventKind =
   | "context.attempt"
   | "context.correction"
-  | "context.protect"
+  | "context.pin"
   | "context.capacity"
   | "context.receipt"
-  | "context.rider"
-  | "context.lastcall"
-  | "context.response"
-  | "context.suggestion"
-  | "context.outcome"
-  | "context.notice"
+  | "context.frontier"
   | "context.commit"
   | "context.fold"
   | "context.brief"
   | "context.absorb"
-  | "context.split"
   | "context.recovery"
   | "context.suspend"
   | "context.rollback"
@@ -197,9 +192,14 @@ export function observeCacheUsage(
   const usage = input.usage;
   const inputTokens = ownValue(usage, "input");
   const cacheReadTokens = ownValue(usage, "cacheRead");
+  const rawCacheWriteTokens = ownValue(usage, "cacheWrite");
   if (typeof inputTokens !== "number" || !Number.isFinite(inputTokens) || inputTokens <= 0 ||
       typeof cacheReadTokens !== "number" || !Number.isFinite(cacheReadTokens) ||
       cacheReadTokens < 0) return null;
+  const cacheWriteTokens = typeof rawCacheWriteTokens === "number" &&
+      Number.isFinite(rawCacheWriteTokens) && rawCacheWriteTokens >= 0
+    ? rawCacheWriteTokens
+    : 0;
   const missed = cacheReadTokens === 0;
   const preserved = typeof input.preservedShare === "number" && Number.isFinite(input.preservedShare)
     ? input.preservedShare
@@ -209,7 +209,8 @@ export function observeCacheUsage(
     change: input.change,
     inputTokens,
     cacheReadTokens,
-    providerSideMiss: missed && (input.change !== "rewrite" ||
+    cacheWriteTokens,
+    providerSideMiss: missed && cacheWriteTokens === 0 && (input.change !== "rewrite" ||
       (preserved !== null && preserved >= PROVIDER_SIDE_MISS_PRESERVED_SHARE)),
   };
   if (missed) ledger.observedMisses += 1;

package/extensions/lib/measurement.ts

@@ -15,7 +15,7 @@ import {
 } from "./canonical.ts";
 import {
   childFoldIds,
-  deriveFoldParents,
+  assignFoldParents,
   flattenFoldRefs,
   foldMap,
   parseActiveContextState,
@@ -270,11 +270,42 @@ export function foldInterval(fold: ActiveFold, state: ActiveContextState, snapsh
   return indices ? { start: indices[0], end: indices.at(-1)! } : null;
 }
 
-export function orderedRoots(state: ActiveContextState, snapshot: ActiveContextSnapshot): Array<{ fold: ActiveFold; start: number; end: number }> {
-  return rootFolds(state).flatMap((fold) => {
+export type OrderedRoot = { fold: ActiveFold; start: number; end: number };
+
+// ROOT INTERVALS ARE DERIVED ONCE PER (STATE, SNAPSHOT) PAIR (2026-08-24). This derivation
+// is O(roots x folds) on its own, because `foldInterval` calls `flattenFoldRefs`, which
+// rebuilds `foldMap` for every root it walks. `partsForRange` opens with it, and
+// `selectAutomaticChapter` calls `partsForRange` from a walk that is quadratic in units,
+// so the cost was O(units^2 x roots x folds) for an answer that cannot change inside a
+// pass. Replaying sealed sol-20260823-live rep 3 at 125 folds, ONE frontier walk made
+// 12,333 calls and spent 22.5 seconds, and 12,328 of them returned null without reading a
+// root, because the automatic chapter passes an EMPTY allowed-child set and any overlap
+// refuses. At 140 folds the walk was 98.8 percent of the runtime's whole per-request cost;
+// the per-turn gap between a response and the next projection ran 3s at zero folds to 164s
+// past 150, and five per-turn call sites each pay a walk.
+//
+// The memo is gate 113's rule and gate 121's rule at a third address: kept against the
+// state and snapshot OBJECTS rather than their contents, because both are REPLACED on
+// every change rather than mutated, so a replaced one misses and derives again instead of
+// serving something stale. It hands every caller the SAME array, which is safe only while
+// no reading mutates it; gate 149 drives every call site against a frozen one so a reading
+// that starts mutating throws rather than quietly poisoning the memo.
+export const ORDERED_ROOTS = new WeakMap<ActiveContextState, WeakMap<ActiveContextSnapshot, OrderedRoot[]>>();
+
+export function orderedRoots(state: ActiveContextState, snapshot: ActiveContextSnapshot): OrderedRoot[] {
+  let bySnapshot = ORDERED_ROOTS.get(state);
+  if (!bySnapshot) {
+    bySnapshot = new WeakMap<ActiveContextSnapshot, OrderedRoot[]>();
+    ORDERED_ROOTS.set(state, bySnapshot);
+  }
+  const memoized = bySnapshot.get(snapshot);
+  if (memoized) return memoized;
+  const roots = rootFolds(state).flatMap((fold) => {
     const interval = foldInterval(fold, state, snapshot);
     return interval ? [{ fold, ...interval }] : [];
   }).sort((left, right) => left.start - right.start);
+  bySnapshot.set(snapshot, roots);
+  return roots;
 }
 
 export function visibleCollapsedRoots(state: ActiveContextState, snapshot: ActiveContextSnapshot) {
@@ -317,7 +348,9 @@ export function persistenceProjection(state: ActiveContextState, snapshot: Activ
   if (projected.prepared && projected.prepared.sourceRefs.some((ref) => !mapped.has(objectRefKey(ref)))) {
     delete projected.prepared;
   }
-  projected.folds = deriveFoldParents(projected.folds);
+  // The parse on the next line validates this forest, so `assignFoldParents` is the whole
+  // job here; `deriveFoldParents` would walk it twice.
+  projected.folds = assignFoldParents(projected.folds);
   return parseActiveContextState(projected, state.sessionId);
 }
 
@@ -325,6 +358,12 @@ export function explicitProtectedKeys(state: ActiveContextState): Set<string> {
   return new Set(state.protected.map(objectRefKey));
 }
 
+/**
+ * Held against folding: pinned by name, or unfoldable for validity (an unfinished turn, an
+ * entry with no evidence ref). There used to be a second reading of this for tool spans,
+ * differing only in which protected set it consulted; the two sets collapsed into one when
+ * fresh-tail was deleted, and the two functions were byte-identical after that.
+ */
 export function refsProtected(
   refs: EvidenceRef[],
   state: ActiveContextState,
@@ -337,18 +376,6 @@ export function refsProtected(
   });
 }
 
-export function toolRefsProtected(
-  refs: EvidenceRef[],
-  state: ActiveContextState,
-  snapshot: ActiveContextSnapshot,
-): boolean {
-  const explicit = explicitProtectedKeys(state);
-  return refs.some((ref) => {
-    const item = exactMapped(snapshot, ref);
-    return !item || explicit.has(objectRefKey(ref)) || snapshot.toolProtectedIndices.has(item.index);
-  });
-}
-
 export function protectedStaleMass(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,