pi-fold 1.0.2 → 1.0.4

package/extensions/lib/folding.ts

@@ -28,9 +28,7 @@ import {
   orderedRoots,
   refsInOrder,
   refsProtected,
-  toolFoldCadence,
   toolRefsProtected,
-  visibleCollapsedRoots,
 } from "./measurement.ts";
 import {
   childFoldIds,
@@ -39,6 +37,7 @@ import {
   foldBrief,
   foldIdFor,
   foldMap,
+  MAX_ACTIVE_PROTECTED,
   normalizedPart,
   protectionSha256,
   topologySha256,
@@ -48,7 +47,6 @@ import {
   ACTIVE_CONTEXT_POLICY,
   activeContextBrand,
   activeContextSource,
-  CONSOLIDATION_WIDTH_THRESHOLD,
   CONTEXT_STATUS_RESPONSE_BYTES,
   EXPAND_LEASE_GENERATIONS,
   MAX_EXPAND_LEASES,
@@ -56,6 +54,7 @@ import {
   PEEK_DEFAULT_MAX_BYTES,
   PEEK_HEAD_SHARE,
   STATUS_DIET_SUGGESTIONS,
+  zoneBytes,
 } from "./policy.ts";
 import type {
   ActiveContextSnapshot,
@@ -72,12 +71,15 @@ import {
   automaticToolBrief,
   candidateSourceRefs,
   chapterUnits,
+  unpinnedStaleFolds,
   deterministicChapterCandidateBrief,
+  deterministicConsolidationBrief,
+  NO_FOLD_KINDS,
   partsForRange,
   resultCall,
-  selectAutomaticConsolidation,
+  selectAutomaticConsolidations,
   selectAutomaticRefold,
-  selectAutomaticToolForRung,
+  selectAutomaticToolBatch,
 } from "./selection.ts";
 
 export function selectAutomaticChapter(
@@ -86,8 +88,17 @@ export function selectAutomaticChapter(
   maximumSourceRefs: number = snapshot.policy.maxFoldSourceRefs,
   claimed: ReadonlySet<string> = new Set<string>(),
 ): FoldCandidate | null {
+  // Every structurally closed unit is a candidate. What keeps a chapter off the newest
+  // material is `refsProtected` below -- the fresh byte tail and the agent's pins -- and
+  // what keeps it off the running excursion's own evidence is the guard adjudicated at
+  // the commit. There is no position filter here: a unit is composable or it is not.
   const units = chapterUnits(snapshot);
-  const allowedChildren = new Set<FoldKind>(["tool-result"]);
+  // An automatic chapter is raw material, always. Letting a chapter swallow placeholders
+  // once the root count reached `consolidateAfter` was the old approximation of
+  // consolidation, and the count law replaces it outright: a placeholder gets a parent
+  // when the count says it must, under a fold that says what it is, not as a side effect
+  // of which chapter happened to be composable that pass (Shane 2026-08-10).
+  const allowedChildren = NO_FOLD_KINDS;
   for (let unitIndex = 0; unitIndex < units.length; unitIndex += 1) {
     const first = units[unitIndex];
     let best: FoldCandidate | null = null;
@@ -124,6 +135,46 @@ export function selectAutomaticChapter(
   return null;
 }
 
+/**
+ * ONE automatic selection law for stale material.
+ *
+ * There is no chapter rung and no consolidation rung any more, each with its own
+ * trigger: automation proposes the stalest eligible SPAN, and what the span contains
+ * decides the fold's kind. Raw narrative folds as a chapter; a parent the root count
+ * requires folds as a consolidation. Nothing here is pressure-scaled: the epoch's own
+ * commit trigger decides WHEN, and this decides WHAT.
+ *
+ * One candidate, because that is what a single inline rung can apply. The count law
+ * itself is not rationed this way: the commit epoch takes EVERY group the count requires
+ * in one pass, and this is the leftover route by which the stalest of them can also ride
+ * an epoch's own rewrite.
+ */
+export function selectAutomaticStaleSpan(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  claimed: ReadonlySet<string> = new Set<string>(),
+): FoldCandidate | null {
+  const chapter = selectAutomaticChapter(snapshot, state, snapshot.policy.maxFoldSourceRefs, claimed);
+  const folds = selectAutomaticConsolidations(snapshot, state)[0] ?? null;
+  if (!chapter || !folds) return chapter ?? folds;
+  const at = (candidate: FoldCandidate): number =>
+    exactMapped(snapshot, candidate.sourceRefs[0])?.index ?? Number.MAX_SAFE_INTEGER;
+  return at(folds) < at(chapter) ? folds : chapter;
+}
+
+/**
+ * What the commit epoch proposes: a completed read-only tool batch if one is stale, and
+ * otherwise the stalest span the one law composes. This is the whole automatic path.
+ */
+export function selectAutomaticSpan(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  claimed: ReadonlySet<string> = new Set<string>(),
+): FoldCandidate | null {
+  return selectAutomaticToolBatch(snapshot, state, claimed)[0] ??
+    selectAutomaticStaleSpan(snapshot, state, claimed);
+}
+
 export type AutomaticRungSelection =
   | { kind: "prepared-chapter"; candidate: FoldCandidate }
   | { kind: "tool"; candidate: FoldCandidate }
@@ -133,7 +184,6 @@ export type AutomaticRungSelection =
   | { kind: "chapter-prepare"; candidate: FoldCandidate };
 
 export interface AutomaticRungSelectionOptions {
-  waiveToolCadence?: boolean;
   toolOnly?: boolean;
   summarizerAvailable?: boolean;
   failedPreparationIds?: ReadonlySet<string>;
@@ -169,14 +219,16 @@ export function selectAutomaticRung(
     const candidate = selectAutomaticChapter(snapshot, state, snapshot.policy.maxFoldSourceRefs, claimed);
     return candidate ? { kind: "prepared-chapter", candidate } : null;
   }
-  const tool = selectAutomaticToolForRung(snapshot, state, ratio, options.waiveToolCadence, claimed);
+  const tool = selectAutomaticToolBatch(snapshot, state, claimed)[0] ?? null;
   if (tool) return { kind: "tool", candidate: tool };
   if (options.toolOnly || !Number.isFinite(ratio)) return null;
-  const refold = selectAutomaticRefold(snapshot, state, ratio, claimedFoldIds);
+  const refold = selectAutomaticRefold(snapshot, state, claimedFoldIds);
   if (refold) return { kind: "refold", foldId: refold };
-  const consolidation = selectAutomaticConsolidation(snapshot, state, ratio, claimed);
-  if (consolidation) return { kind: "consolidation", candidate: consolidation };
-  const chapter = selectAutomaticChapter(snapshot, state, snapshot.policy.maxFoldSourceRefs, claimed);
+  // One law decides the span; only the CHAPTER kind still has a preparation path in
+  // front of it, because only a chapter brief is worth a model call.
+  const span = selectAutomaticStaleSpan(snapshot, state, claimed);
+  if (span?.kind === "consolidation") return { kind: "consolidation", candidate: span };
+  const chapter = span;
   if (!chapter) return null;
   const preparationFailed = options.failedPreparationIds?.has(
     automaticPreparationId(chapter, state),
@@ -207,10 +259,11 @@ export function foldCandidatesDetail(
   } = {},
 ): Record<string, unknown> {
   const measuredRatio = ratio !== null && Number.isFinite(ratio) ? ratio : Number.NaN;
-  const tool = selectAutomaticToolForRung(snapshot, state, measuredRatio);
-  const refold = selectAutomaticRefold(snapshot, state, measuredRatio);
-  const consolidation = selectAutomaticConsolidation(snapshot, state, measuredRatio);
-  const chapter = selectAutomaticChapter(snapshot, state);
+  const tool = selectAutomaticToolBatch(snapshot, state)[0] ?? null;
+  const refold = selectAutomaticRefold(snapshot, state);
+  const staleSpan = selectAutomaticStaleSpan(snapshot, state);
+  const consolidation = staleSpan?.kind === "consolidation" ? staleSpan : null;
+  const chapter = staleSpan?.kind === "chapter" ? staleSpan : null;
   const selection = selectAutomaticRung(snapshot, state, measuredRatio, {
     summarizerAvailable: options.summarizerAvailable,
     failedPreparationIds: options.failedPreparationIds,
@@ -243,13 +296,17 @@ export function foldCandidatesDetail(
     } : null,
     wouldFireNow,
     blockedBy,
-    cadence: {
-      tokensSinceToolFold: state.tokensSinceToolFold,
-      cadenceNeed: toolFoldCadence(snapshot.contextWindow),
+    // The one position that still cuts anything, plus the count law read as the
+    // arithmetic it is: the roots it counts, the width it divides by, and how many
+    // parents that count owes right now.
+    zones: {
+      freshBoundary: snapshot.freshBoundary,
+      budgetTokens: snapshot.budgetTokens,
     },
     width: {
-      visibleRoots: visibleCollapsedRoots(state, snapshot).length,
-      threshold: CONSOLIDATION_WIDTH_THRESHOLD,
+      visibleRoots: unpinnedStaleFolds(snapshot, state).length,
+      threshold: snapshot.thresholds.consolidateAfter,
+      groupsDue: selectAutomaticConsolidations(snapshot, state).length,
     },
   };
 }
@@ -312,6 +369,69 @@ export function encodedFoldSource(
   }));
 }
 
+/**
+ * What a generator reads to brief a PARENT: its children at depth one.
+ *
+ * `encodedFoldSource` renders a parent's children through `renderFold`, which yields their
+ * placeholders, so a parent's source was the children's briefs. Briefing that produces a
+ * summary of summaries, and by the second rung the material itself is three descriptions
+ * away. So each child is opened here instead: its own brief for orientation, then its
+ * contents, with ITS children left as placeholders. Depth one is the whole rule. It bounds
+ * the read at one level per rung whatever the ladder's height, and it is the same view an
+ * agent gets from expanding the parent, so a brief written from it describes what expanding
+ * would actually return.
+ *
+ * When the opened children do not fit, the LARGEST collapses back to brief-only first, and
+ * again until the rest fit. Size is what decides, not position: dropping in span order
+ * would spend the whole budget on an early giant and close every child behind it, while
+ * taking the giant out first buys back the most room for the fewest subjects lost. A
+ * collapsed child still appears, in span order, carrying its brief and saying it is
+ * collapsed, so the generator can tell a child it read from a child it only heard about.
+ */
+export function consolidationSourceText(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  parts: FoldPart[],
+): string {
+  const byId = foldMap(state);
+  const entries = parts.map((part, index) => {
+    if (part.kind === "raw") {
+      const item = exactMapped(snapshot, part.ref);
+      if (!item) throw new Error(`Exact Pi evidence drift for ${part.ref.entryId}`);
+      return { index, foldId: null, kind: "raw" as const, brief: null, messages: [clone(item.message)] };
+    }
+    const child = byId.get(part.foldId);
+    if (!child) throw new Error(`Consolidation source lost child fold ${part.foldId}`);
+    const messages = renderFoldParts(child.parts, state, snapshot);
+    if (!messages) throw new Error(`Consolidation source projection drifted at ${child.id}`);
+    return { index, foldId: child.id, kind: child.kind, brief: foldBrief(child, state), messages };
+  });
+  const collapsed = new Set<number>();
+  const render = (): string => stableStringify(entries.map((entry) => ({
+    child: entry.index + 1,
+    of: entries.length,
+    ...(entry.foldId === null ? {} : { foldId: entry.foldId }),
+    kind: entry.kind,
+    ...(entry.brief === null ? {} : { brief: entry.brief }),
+    ...(collapsed.has(entry.index)
+      ? { collapsed: "brief only: this child did not fit expanded" }
+      : { contents: entry.messages }),
+  })));
+  // Largest first, and only as many as the budget forces: each collapse is a subject the
+  // brief must describe from one sentence instead of from its contents.
+  const bySize = entries
+    .filter((entry) => entry.foldId !== null)
+    .map((entry) => ({ index: entry.index, size: bytes(entry.messages) }))
+    .sort((a, b) => b.size - a.size || a.index - b.index);
+  let text = render();
+  for (const entry of bySize) {
+    if (bytes(text) <= snapshot.policy.maxSourceChars) break;
+    collapsed.add(entry.index);
+    text = render();
+  }
+  return text;
+}
+
 export function boundedOrientation(
   snapshot: ActiveContextSnapshot,
   sourceRefs: EvidenceRef[],
@@ -339,6 +459,155 @@ export function boundedOrientation(
   return { beforeRefs: before, beforeText, afterRefs: after.refs, afterText: after.text };
 }
 
+/**
+ * What is wrong with a generated brief, said in words its author can act on, or null.
+ *
+ * Length is a criterion we set, so a brief that misses it is answered rather than cut.
+ * Truncating a long brief silently loses whatever the generator put last, which on a group
+ * is the last children it covered; the cure is to hand the complaint back and let the
+ * generator spend the budget itself. Coverage cannot be checked the same way: no test tells
+ * whether a sentence stands for a child, so coverage is instructed in the request and
+ * defended by the deterministic index underneath, and what is checked here is the pair of
+ * failures that were silent before.
+ */
+export function briefContractComplaint(
+  brief: string,
+  maxBriefChars: number,
+  toolName: string,
+): string | null {
+  if (!brief) return "You returned no brief text. Reply with the brief itself and nothing else.";
+  if (brief.length > maxBriefChars) {
+    return `Your brief was ${brief.length} characters and the limit is ${maxBriefChars}. ` +
+      "Rewrite it within the limit. Cut detail, not subjects: every subject you named must " +
+      "still be named in the shorter brief.";
+  }
+  if (!usefulBrief(brief, maxBriefChars, toolName)) {
+    return "Your brief carried no factual content once fold navigation lines were dropped. " +
+      "Name concrete things from the span: files, identifiers, decisions, results, errors.";
+  }
+  return null;
+}
+
+/**
+ * One brief from the generator, with one chance to cure a criterion it missed.
+ *
+ * The no-retry rule this lane was built with holds for what it was written about: a
+ * generator that fails on a span fails on it again, and looping would spend the session's
+ * calls proving it. A contract complaint is the other case. The request stated a limit, the
+ * answer missed it, and the complaint names exactly what to change, so the second ask is
+ * new information rather than the same ask twice. It is bounded at one, and only a
+ * complaint earns it: transport faults, timeouts and attribution drift still fail on the
+ * first answer. Both attempts sit inside the caller's timeout, so a brief costs no more
+ * wall clock than it did.
+ */
+export async function generatedBrief(input: {
+  summarize: (request: Record<string, unknown>, ctx?: unknown) => Promise<Record<string, unknown>>;
+  request: Record<string, unknown>;
+  ctx?: unknown;
+  maxBriefChars: number;
+  toolName: string;
+}): Promise<{ brief: string; provenance: BriefProvenance; cured: boolean }> {
+  let complaint: string | null = null;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const result = await input.summarize(
+      complaint === null ? input.request : { ...input.request, cure: complaint },
+      input.ctx,
+    );
+    const brief = typeof result?.brief === "string" ? result.brief.trim() : "";
+    const provenance = generatorAttribution(result);
+    complaint = briefContractComplaint(brief, input.maxBriefChars, input.toolName);
+    if (complaint === null) return { brief, provenance, cured: attempt > 0 };
+  }
+  throw new Error(`Model context brief usefulness contract drift after one cure: ${complaint}`);
+}
+
+/**
+ * Attribution is the harness's own wiring, not the generator's judgment, so it is never
+ * handed back to be cured: a summarizer that cannot say which model wrote a brief is broken
+ * in a way a second ask cannot mend. Shared by the single and batched paths so the two
+ * cannot drift.
+ */
+function generatorAttribution(result: Record<string, unknown> | null | undefined): BriefProvenance {
+  const digest = result?.launchContractDigest;
+  if (typeof result?.provider !== "string" || !result.provider ||
+      typeof result?.model !== "string" || !result.model ||
+      typeof result?.effort !== "string" || !result.effort || result.toolCalls !== 0 ||
+      (digest !== undefined && (typeof digest !== "string" || !/^[a-f0-9]{64}$/.test(digest)))) {
+    throw new Error("Model context brief attribution, zero-tool, or digest contract drift");
+  }
+  return {
+    kind: "model",
+    provider: result.provider,
+    model: result.model,
+    effort: result.effort,
+    ...(typeof digest === "string" ? { launchContractDigest: digest } : {}),
+  };
+}
+
+/**
+ * Many briefs from one call, with one chance to cure the ones that missed.
+ *
+ * The lane used to send one request per fold, two at a time, which meant most folds never
+ * reached a generator at all: the 2026-08-11 rep committed 87 folds and applied 14 model
+ * briefs, the rest keeping the deterministic sentence because the queue was full. A commit
+ * folds its spans together, so they are briefed together, and coverage stops competing with
+ * throughput.
+ *
+ * The cure is per-span and the retry carries only the spans that failed, so one bad brief
+ * does not make the model rewrite eleven good ones. A span still failing after its cure
+ * keeps its deterministic brief and is named in the error, which is the same outcome a
+ * single-span failure has always had; the difference is that its neighbours still land.
+ */
+export async function generatedBriefs(input: {
+  summarize: (request: Record<string, unknown>, ctx?: unknown) => Promise<Record<string, unknown>>;
+  request: Record<string, unknown>;
+  spans: Array<Record<string, unknown>>;
+  ctx?: unknown;
+  maxBriefChars: number;
+  toolName: string;
+}): Promise<{
+  briefs: Array<{ brief: string; provenance: BriefProvenance } | null>;
+  cured: number;
+  complaints: string[];
+}> {
+  const settled = new Array<{ brief: string; provenance: BriefProvenance } | null>(input.spans.length)
+    .fill(null);
+  let pending = input.spans.map((span, index) => ({ span, index }));
+  let cured = 0;
+  let complaints: string[] = [];
+  for (let attempt = 0; attempt < 2 && pending.length; attempt += 1) {
+    const asked = pending;
+    const result = await input.summarize({
+      ...input.request,
+      spans: asked.map((item) => item.span),
+      ...(complaints.length
+        ? {
+          cure: asked.map((item, at) =>
+            `Brief ${at + 1}: ${complaints[at] ?? "did not meet the stated criteria."}`).join(" "),
+        }
+        : {}),
+    }, input.ctx);
+    const provenance = generatorAttribution(result);
+    const written = Array.isArray(result?.briefs) ? result.briefs : [];
+    const failed: typeof pending = [];
+    const next: string[] = [];
+    for (let at = 0; at < asked.length; at += 1) {
+      const brief = typeof written[at] === "string" ? (written[at] as string).trim() : "";
+      const complaint = briefContractComplaint(brief, input.maxBriefChars, input.toolName);
+      if (complaint === null) {
+        settled[asked[at].index] = { brief, provenance };
+        if (attempt > 0) cured += 1;
+        continue;
+      }
+      failed.push(asked[at]);
+      next.push(complaint);
+    }
+    pending = failed;
+    complaints = next;
+  }
+  return { briefs: settled, cured, complaints };
+}
+
 export async function prepareFold(input: {
   candidate: FoldCandidate;
   snapshot: ActiveContextSnapshot;
@@ -366,6 +635,10 @@ export async function prepareFold(input: {
     throw new Error("Fold source is not exact, stale, and unprotected");
   }
   const sourceText = encodedFoldSource(snapshot, state, candidate.parts, candidate.kind);
+  const groupChildren = candidate.parts.filter((part) => part.kind === "fold").length;
+  const readableSource = groupChildren
+    ? consolidationSourceText(snapshot, state, candidate.parts)
+    : sourceText;
   const orientation = boundedOrientation(snapshot, candidate.sourceRefs);
   const sourceSha256 = sha256Text(sourceText);
   const beforeSha256 = sha256Text(orientation.beforeText);
@@ -396,7 +669,7 @@ export async function prepareFold(input: {
       input.signal?.addEventListener("abort", relayAbort, { once: true });
       let timeout: ReturnType<typeof setTimeout> | undefined;
       try {
-        if (bytes(sourceText) > snapshot.policy.maxSourceChars) {
+        if (bytes(readableSource) > snapshot.policy.maxSourceChars) {
           throw new Error("Fold source exceeds the bounded model-summary request");
         }
         const timed = new Promise<never>((_resolve, reject) => {
@@ -405,39 +678,31 @@ export async function prepareFold(input: {
             reject(new Error(`Context brief exceeded ${snapshot.policy.briefTimeoutMs}ms`));
           }, snapshot.policy.briefTimeoutMs);
         });
-        const result = await Promise.race([input.summarize({
-          candidateId,
-          sourceRefs: clone(candidate.sourceRefs),
-          sourceText,
-          sourceSha256,
-          beforeRefs: clone(orientation.beforeRefs),
-          beforeText: orientation.beforeText,
-          beforeSha256,
-          afterRefs: clone(orientation.afterRefs),
-          afterText: orientation.afterText,
-          afterSha256,
-          maxBriefChars: snapshot.policy.maxBriefChars,
-          signal: controller.signal,
-        }, input.ctx), timed]);
-        const generated = typeof result?.brief === "string" ? result.brief.trim() : "";
-        const digest = result?.launchContractDigest;
-        if (!usefulBrief(generated, snapshot.policy.maxBriefChars, snapshot.toolName) ||
-            typeof result?.provider !== "string" || !result.provider ||
-            typeof result?.model !== "string" || !result.model ||
-            typeof result?.effort !== "string" || !result.effort || result.toolCalls !== 0 ||
-            (digest !== undefined && (typeof digest !== "string" || !/^[a-f0-9]{64}$/.test(digest)))) {
-          throw new Error("Model context brief attribution, zero-tool, digest, or usefulness contract drift");
-        }
-        modelBrief = {
-          brief: generated,
-          provenance: {
-            kind: "model",
-            provider: result.provider,
-            model: result.model,
-            effort: result.effort,
-            ...(typeof digest === "string" ? { launchContractDigest: digest } : {}),
+        const generated = await Promise.race([generatedBrief({
+          summarize: input.summarize,
+          request: {
+            candidateId,
+            sourceRefs: clone(candidate.sourceRefs),
+            // What the generator READS, which for a group is its children opened one level
+            // rather than the placeholders `sourceText` renders. The fold's own identity
+            // stays `sourceSha256` above: what a span IS does not change with how it is read.
+            sourceText: readableSource,
+            sourceSha256: sha256Text(readableSource),
+            children: groupChildren,
+            beforeRefs: clone(orientation.beforeRefs),
+            beforeText: orientation.beforeText,
+            beforeSha256,
+            afterRefs: clone(orientation.afterRefs),
+            afterText: orientation.afterText,
+            afterSha256,
+            maxBriefChars: snapshot.policy.maxBriefChars,
+            signal: controller.signal,
           },
-        };
+          ctx: input.ctx,
+          maxBriefChars: snapshot.policy.maxBriefChars,
+          toolName: snapshot.toolName,
+        }), timed]);
+        modelBrief = { brief: generated.brief, provenance: generated.provenance };
       } catch (error) {
         if (input.signal?.aborted) throw error;
         input.onSummarizerFailure?.(error);
@@ -450,7 +715,11 @@ export async function prepareFold(input: {
       brief = modelBrief.brief;
       provenance = modelBrief.provenance;
     } else {
-      brief = deterministicChapterCandidateBrief(snapshot, candidate);
+      // By kind, not by assumption: a group that loses its generator falls back to the
+      // index of its children, and only a chapter falls back to a chapter's brief.
+      brief = candidate.kind === "consolidation"
+        ? deterministicConsolidationBrief(candidate, state)
+        : deterministicChapterCandidateBrief(snapshot, candidate);
       provenance = { kind: "deterministic" };
     }
   }
@@ -706,6 +975,14 @@ export function protectEvidence(
   });
   const byKey = new Map(state.protected.map((ref) => [objectRefKey(ref), ref]));
   for (const ref of refs) protect ? byKey.set(objectRefKey(ref), ref) : byKey.delete(objectRefKey(ref));
+  // Atomic: the whole resolved set pins or nothing does. A partial pin that reports
+  // success would leave part of the requested span silently reclaimable.
+  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",
+    );
+  }
   return clearPrepared({
     ...state,
     revision: state.revision + 1,
@@ -1114,7 +1391,7 @@ export function activeContextStatus(
       endId: eligibleSourceIds.at(-1),
       action: { action: "fold", ids: eligibleEndpoints, brief: "<factual brief, at most 1000 characters>" },
     } : null,
-    rawTailMinimumBytes: snapshot.policy.freshBytes,
+    rawTailMinimumBytes: zoneBytes(snapshot.thresholds.freshTail, snapshot.budgetTokens),
     currentTurnRequiresBoundary: false,
     actions: {
       status: { action: "status", offset, limit },
@@ -1274,15 +1551,16 @@ export function projectionSlateCandidates(
   });
 }
 
-export function recoverFoldMessages(input: {
+export interface FoldSourceRequest {
   foldId: string;
   state: ActiveContextState;
   entries: Array<Record<string, unknown>>;
   sessionId: string;
   projectEntry?: (entry: Record<string, unknown>) => unknown[];
-}): unknown[] {
-  const fold = input.state.folds.find((item) => item.id === input.foldId);
-  if (!fold) throw new Error(`Unknown active-context fold ${input.foldId}`);
+}
+
+/** One exact message per ref identity and digest, read off the immutable session entries. */
+function exactSessionMessages(input: FoldSourceRequest): Map<string, unknown> {
   const projectEntry = input.projectEntry ?? sessionEntryMessages;
   const exact = new Map<string, unknown>();
   for (const entry of input.entries) {
@@ -1292,20 +1570,81 @@ export function recoverFoldMessages(input: {
       exact.set(`${objectRefKey(ref)}:${ref.sha256}`, message);
     }
   }
-  return flattenFoldRefs(fold, input.state).map((ref) => {
-    if (ref.sessionId !== input.sessionId) throw new Error(`Fold source ${ref.entryId} belongs to another session`);
-    const message = exact.get(`${objectRefKey(ref)}:${ref.sha256}`);
-    if (!message || evidenceSha256(message) !== ref.sha256) {
-      throw new Error(`Exact recovery failed for ${ref.entryId}`);
-    }
-    return clone(message);
+  return exact;
+}
+
+function exactMessageFor(
+  exact: Map<string, unknown>,
+  ref: EvidenceRef,
+  sessionId: string,
+): unknown {
+  if (ref.sessionId !== sessionId) throw new Error(`Fold source ${ref.entryId} belongs to another session`);
+  const message = exact.get(`${objectRefKey(ref)}:${ref.sha256}`);
+  if (!message || evidenceSha256(message) !== ref.sha256) {
+    throw new Error(`Exact recovery failed for ${ref.entryId}`);
+  }
+  return clone(message);
+}
+
+/**
+ * One fold's ENTIRE original source, at every depth.
+ *
+ * This is the rescue read: restoration and the recovery audit both need the bytes as the
+ * session first wrote them, with nothing standing in for anything. Retrieval inside a
+ * session is the other function, and it serves one level.
+ */
+export function recoverFoldMessages(input: FoldSourceRequest): unknown[] {
+  const fold = input.state.folds.find((item) => item.id === input.foldId);
+  if (!fold) throw new Error(`Unknown active-context fold ${input.foldId}`);
+  const exact = exactSessionMessages(input);
+  return flattenFoldRefs(fold, input.state).map((ref) => exactMessageFor(exact, ref, input.sessionId));
+}
+
+/** A child fold as its parent's stored span holds it: the placeholder, not the bytes under it. */
+export function storedChildPlaceholder(child: ActiveFold, state: ActiveContextState): Record<string, unknown> {
+  return {
+    placeholder: "fold",
+    id: child.id,
+    kind: child.kind,
+    brief: foldBrief(child, state),
+    sourceSha256: child.sourceSha256,
+    sourceBytes: child.sourceChars,
+    children: childFoldIds(child).length,
+    peek: { action: "peek", id: child.id },
+  };
+}
+
+/**
+ * One fold's stored span, AS STORED: one level.
+ *
+ * A fold's span is what it took in, and what it took in was already whatever the window
+ * held: raw entries, and placeholders for folds that were there first. So the honest read
+ * of a parent is that same span, children still placeheld. Reading it as the original
+ * bytes at every depth would hand back a whole session's transcript for one call and
+ * undo the nesting the fold performed.
+ *
+ * The verbatim floor is untouched by this. A leaf's stored span IS its original bytes, so
+ * the bytes are always exactly one peek away from any id the read hands back.
+ */
+export function foldStoredSpan(input: FoldSourceRequest): unknown[] {
+  const fold = input.state.folds.find((item) => item.id === input.foldId);
+  if (!fold) throw new Error(`Unknown active-context fold ${input.foldId}`);
+  const exact = exactSessionMessages(input);
+  const byId = foldMap(input.state);
+  return fold.parts.map((part) => {
+    if (part.kind === "raw") return exactMessageFor(exact, part.ref, input.sessionId);
+    const child = byId.get(part.foldId);
+    if (!child) throw new Error(`Missing active-context child ${part.foldId}`);
+    return storedChildPlaceholder(child, input.state);
   });
 }
 
 /**
- * Ephemeral point read of one fold's exact source at any depth. It recovers the same
- * SHA-256-verified messages expansion restores, bounded for one model call, and changes no
- * projection: the fold stays collapsed and the durable state is untouched.
+ * Ephemeral point read of one fold's stored span. It returns the same SHA-256-verified
+ * span expansion restores, ONE level: raw entries verbatim, child folds still placeheld.
+ * It is bounded for one model call and changes no projection: the fold stays collapsed and
+ * the durable state is untouched. Any id in the result peeks in one hop, so the verbatim
+ * floor is a hop away at every depth rather than a payload nobody asked for.
  */
 export function peekFoldSource(input: {
   foldId: string;
@@ -1321,7 +1660,7 @@ export function peekFoldSource(input: {
 }): Record<string, unknown> {
   const fold = input.state.folds.find((item) => item.id === input.foldId);
   if (!fold) throw new Error(`Unknown active-context fold ${input.foldId}`);
-  const messages = recoverFoldMessages({
+  const messages = foldStoredSpan({
     foldId: input.foldId,
     state: input.state,
     entries: input.entries,
@@ -1377,12 +1716,17 @@ export function peekFoldSource(input: {
     ...(truncated
       ? { wider: { action: "peek", id: fold.id, bytes: Math.min(sourceBytes, ACTIVE_CONTEXT_POLICY.maxChapterChars) } }
       : {}),
-    lifetime: "these bytes stay in the window exactly as returned, like any other tool " +
-      "result, until the ladder folds them at a commit. Nothing rewrites this result in place.",
+    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
       ? `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.`
-      : "Complete exact source; the fold stayed collapsed and no projection changed.",
+      : 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.",
     source: returned,
     // Serialized AFTER the source on purpose: a reader that just consumed a bounded slice
     // decides its next action at the end of the payload, and a notice buried before ten