pi-fold 0.1.1 → 1.0.0

package/extensions/lib/folding.ts

@@ -3,6 +3,7 @@ import {
   denseOwnArrayValues,
   evidenceRef,
   evidenceSha256,
+  isPlainRecord,
   objectRefKey,
   sha256Text,
   sha256Value,
@@ -16,6 +17,7 @@ import {
   ownValue,
   sessionEntryMessages,
   usefulBrief,
+  utf8Slice,
 } from "./canonical.ts";
 import {
   branchSha256,
@@ -34,6 +36,7 @@ import {
   childFoldIds,
   clearPrepared,
   flattenFoldRefs,
+  foldBrief,
   foldIdFor,
   foldMap,
   normalizedPart,
@@ -46,8 +49,13 @@ import {
   activeContextBrand,
   activeContextSource,
   CONSOLIDATION_WIDTH_THRESHOLD,
+  CONTEXT_STATUS_RESPONSE_BYTES,
   EXPAND_LEASE_GENERATIONS,
   MAX_EXPAND_LEASES,
+  MAX_FOLD_SPAN_CHARS,
+  PEEK_DEFAULT_MAX_BYTES,
+  PEEK_HEAD_SHARE,
+  STATUS_DIET_SUGGESTIONS,
 } from "./policy.ts";
 import type {
   ActiveContextSnapshot,
@@ -76,6 +84,7 @@ 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 = new Set<FoldKind>(["tool-result"]);
@@ -94,10 +103,21 @@ export function selectAutomaticChapter(
       if (!parts || parts.some((part) => part.kind === "fold" && state.expanded.includes(part.foldId))) continue;
       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;
       const size = bytes(encodedFoldSource(snapshot, state, parts, "chapter"));
-      if (size > snapshot.policy.maxChapterChars) break;
-      if (size >= snapshot.policy.minChapterChars) best = { kind: "chapter", parts, sourceRefs: refs };
+      // The chapter cap bounds what the rung COMPOSES, never what it may reclaim: a
+      // single closed unit that alone exceeds it is still accepted (rep 19: six status
+      // results, each above the cap, were exactly the mass nothing could fold).
+      if (size > snapshot.policy.maxChapterChars && endIndex > unitIndex) break;
+      // Bite-sized by construction. A multi-unit chapter never grows past the cap, so
+      // the ladder cannot build the 60kB fold whose tail hid the answer (rep 6); a
+      // SINGLE unit that alone exceeds it is still accepted, because there is no
+      // interior boundary to stop at and refusing would leave the biggest span in the
+      // window as the one thing nothing may reclaim.
+      const biteSized = size <= MAX_FOLD_SPAN_CHARS || endIndex === unitIndex;
+      if (size >= snapshot.policy.minChapterChars && biteSized) best = { kind: "chapter", parts, sourceRefs: refs };
+      if (size > MAX_FOLD_SPAN_CHARS) break;
     }
     if (best) return best;
   }
@@ -117,6 +137,14 @@ export interface AutomaticRungSelectionOptions {
   toolOnly?: boolean;
   summarizerAvailable?: boolean;
   failedPreparationIds?: ReadonlySet<string>;
+  /**
+   * Evidence and folds already spoken for by something that is not yet a fold, i.e.
+   * a pending epoch mark. Excluding them makes each eligible turn select NEW stale
+   * content instead of re-selecting the batch a mark already covers, which is the
+   * only way marks accumulate below the commit threshold.
+   */
+  claimed?: ReadonlySet<string>;
+  claimedFoldIds?: ReadonlySet<string>;
 }
 
 export function automaticPreparationId(candidate: FoldCandidate, state: ActiveContextState): string {
@@ -134,19 +162,21 @@ export function selectAutomaticRung(
   ratio: number,
   options: AutomaticRungSelectionOptions = {},
 ): AutomaticRungSelection | null {
+  const claimed = options.claimed ?? new Set<string>();
+  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);
+    const candidate = selectAutomaticChapter(snapshot, state, snapshot.policy.maxFoldSourceRefs, claimed);
     return candidate ? { kind: "prepared-chapter", candidate } : null;
   }
-  const tool = selectAutomaticToolForRung(snapshot, state, ratio, options.waiveToolCadence);
+  const tool = selectAutomaticToolForRung(snapshot, state, ratio, options.waiveToolCadence, claimed);
   if (tool) return { kind: "tool", candidate: tool };
   if (options.toolOnly || !Number.isFinite(ratio)) return null;
-  const refold = selectAutomaticRefold(snapshot, state, ratio);
+  const refold = selectAutomaticRefold(snapshot, state, ratio, claimedFoldIds);
   if (refold) return { kind: "refold", foldId: refold };
-  const consolidation = selectAutomaticConsolidation(snapshot, state, ratio);
+  const consolidation = selectAutomaticConsolidation(snapshot, state, ratio, claimed);
   if (consolidation) return { kind: "consolidation", candidate: consolidation };
-  const chapter = selectAutomaticChapter(snapshot, state);
+  const chapter = selectAutomaticChapter(snapshot, state, snapshot.policy.maxFoldSourceRefs, claimed);
   if (!chapter) return null;
   const preparationFailed = options.failedPreparationIds?.has(
     automaticPreparationId(chapter, state),
@@ -315,7 +345,12 @@ export async function prepareFold(input: {
   state: ActiveContextState;
   generation: number;
   brief?: string;
-  briefProvenance?: "supplied" | "deterministic";
+  /**
+   * Provenance for a supplied brief. A full record round-trips a brief whose
+   * generator already ran (a pending mark carrying a model brief); the string
+   * forms stay the shorthand for the two model-free kinds.
+   */
+  briefProvenance?: "supplied" | "deterministic" | BriefProvenance;
   summarize?: (request: Record<string, unknown>, ctx?: unknown) => Promise<Record<string, unknown>>;
   onSummarizerFailure?: (error: unknown) => void;
   ctx?: unknown;
@@ -350,7 +385,9 @@ export async function prepareFold(input: {
       throw new Error(`Supplied brief must be non-structural and at most ${snapshot.policy.maxBriefChars} characters`);
     }
     brief = input.brief.trim();
-    provenance = { kind: input.briefProvenance ?? "supplied" };
+    provenance = typeof input.briefProvenance === "object"
+      ? clone(input.briefProvenance)
+      : { kind: input.briefProvenance ?? "supplied" };
   } else {
     let modelBrief: { brief: string; provenance: BriefProvenance } | null = null;
     if (input.summarize) {
@@ -701,7 +738,7 @@ export function foldPlaceholder(fold: ActiveFold, state: ActiveContextState, sna
   const parent = fold.parentId ?? "root";
   return [
     `[${activeContextBrand(snapshot.brandNoun)} fold ${fold.id}]`,
-    fold.brief,
+    foldBrief(fold, state),
     `Topology: kind=${fold.kind}; parent=${parent}; children=${childFoldIds(fold).length}; ` +
       `previous=${navigation.previous ?? "none"}; next=${navigation.next ?? "none"}.`,
     `Expand exactly: ${snapshot.toolName} {"action":"expand","id":"${fold.id}"}`,
@@ -791,6 +828,50 @@ export function assertProjectionPreservesToolLinkage(source: unknown[], projecte
   }
 }
 
+/**
+ * Peek mass the ladder cannot take: results whose evidence the agent protected
+ * outright. This is the number that made rep 7's starvation invisible. The mass sat
+ * raw in the window, the ROI trigger's eligibility arithmetic could never reach its
+ * threshold over it, and no accounting field said so while the window grew to 235k
+ * tokens.
+ */
+export function pinnedPeekMass(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+): { bytes: number; results: number } {
+  const explicitProtected = explicitProtectedKeys(state);
+  const folded = new Set<string>();
+  for (const fold of state.folds) {
+    for (const ref of flattenFoldRefs(fold, state)) folded.add(objectRefKey(ref));
+  }
+  const peekCalls = new Map<string, string>();
+  for (const message of snapshot.messages) {
+    if (messageRole(message) !== "assistant") continue;
+    for (const part of denseOwnArrayValues(ownValue(message, "content")) ?? []) {
+      if (ownValue(part, "type") !== "toolCall" || ownValue(part, "name") !== snapshot.toolName) continue;
+      const callId = ownValue(part, "id");
+      const args = ownValue(part, "arguments");
+      const foldId = ownValue(args, "id");
+      if (typeof callId !== "string" || !callId || ownValue(args, "action") !== "peek" ||
+          typeof foldId !== "string" || !foldId) continue;
+      peekCalls.set(callId, foldId);
+    }
+  }
+  let total = 0;
+  let results = 0;
+  for (const item of snapshot.mapped) {
+    if (messageRole(item.message) !== "toolResult" || !item.ref) continue;
+    if (folded.has(objectRefKey(item.ref))) continue;
+    const toolCallId = ownValue(item.message, "toolCallId");
+    const foldId = typeof toolCallId === "string" ? peekCalls.get(toolCallId) : undefined;
+    if (!foldId) continue;
+    if (!explicitProtected.has(objectRefKey(item.ref))) continue;
+    total += bytes(item.message);
+    results += 1;
+  }
+  return { bytes: total, results };
+}
+
 export function projectActiveContext(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
@@ -812,6 +893,13 @@ export function projectActiveContext(
       index += 1;
     }
   }
+  // A peek result is APPEND-ONLY. It used to be rewritten in place once a model call
+  // had seen it, on the theory that the edit was tail-local; rep 22 disproved that.
+  // The result is only tail-local when it ARRIVES, and reclamation deliberately waits
+  // until a later assistant message exists, by which point the window has grown over
+  // it and the edit lands mid-prefix. Two peeks cost 100k fresh tokens that way. The
+  // duplicate bytes are still reclaimed, by the tool-fold rung at the next commit,
+  // which is the one moment a rewrite is already being paid for.
   assertProjectionPreservesToolLinkage(snapshot.messages, output);
   return output;
 }
@@ -840,6 +928,11 @@ export function foldStatusRow(fold: ActiveFold, state: ActiveContextState, snaps
     sourceCount: allSourceIds.length,
     sourceIdsTruncated: sourceIds.length < allSourceIds.length,
     sourceSha256: fold.sourceSha256,
+    // A paged row without the brief is a chronological id and nothing else: the
+    // agent that paged the tree to find WHICH fold holds something got the one
+    // field that answers it withheld, while the tree detail carried it all along.
+    brief: foldBrief(fold, state),
+    sourceChars: fold.sourceChars,
     actions: {
       primary: projection === "folded"
         ? { action: "expand", id: fold.id }
@@ -883,19 +976,70 @@ export function foldTreeDetail(
     kind: fold.kind,
     depth: foldDepth(state, fold),
     parentId: fold.parentId,
-    brief: fold.brief,
+    brief: foldBrief(fold, state),
     sourceCount: flattenFoldRefs(fold, state).length,
     state: state.expanded.includes(fold.id) ? "expanded" : "folded",
     peekable: true,
   }));
 }
 
+/**
+ * One compact row per collapsed fold: what is behind it, where its span starts and
+ * ends, and the brief that carries whatever key material the fold captured. This is
+ * the answer to "which fold has X" that agents were paying 56-83k chars per peek to
+ * reconstruct, and it costs a line.
+ */
+export function foldIndexRow(
+  fold: ActiveFold,
+  state: ActiveContextState,
+  snapshot: ActiveContextSnapshot,
+): Record<string, unknown> {
+  const refs = flattenFoldRefs(fold, state);
+  const interval = foldInterval(fold, state, snapshot);
+  const replacement = renderFold(fold, state, snapshot);
+  const source = renderFold(fold, { ...state, expanded: [...state.expanded, fold.id] }, snapshot);
+  const reclaimableBytes = replacement && source ? Math.max(0, bytes(source) - bytes(replacement)) : 0;
+  return {
+    id: fold.id,
+    kind: fold.kind,
+    depth: foldDepth(state, fold),
+    state: state.expanded.includes(fold.id) ? "expanded" : "folded",
+    startId: refs[0]?.entryId ?? null,
+    endId: refs.at(-1)?.entryId ?? null,
+    startPosition: interval?.start ?? null,
+    endPosition: interval?.end ?? null,
+    sourceCount: refs.length,
+    sourceBytes: fold.sourceChars,
+    reclaimableBytes,
+    brief: foldBrief(fold, state),
+    peek: { action: "peek", id: fold.id },
+    expand: { action: "expand", id: fold.id },
+  };
+}
+
+/** Every mapped source id to the fold that now holds it, so a lookup never needs a read. */
+export function foldSourceMap(
+  state: ActiveContextState,
+  snapshot: ActiveContextSnapshot,
+  limit = 512,
+): { entries: Array<[string, string]>; total: number; truncated: boolean } {
+  const entries: Array<[string, string]> = [];
+  for (const fold of orderedFoldTree(state, snapshot)) {
+    for (const ref of flattenFoldRefs(fold, state)) entries.push([ref.entryId, fold.id]);
+  }
+  // Deepest wins: the innermost fold is the one that actually holds the source.
+  const byEntry = new Map(entries);
+  const all = [...byEntry.entries()];
+  return { entries: all.slice(0, limit), total: all.length, truncated: all.length > limit };
+}
+
 export function activeContextStatus(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
   offset = 0,
   limit = 40,
   maximumChapterSourceRefs = Number.MAX_SAFE_INTEGER,
+  statusOptions: { diet?: boolean; suggestions?: number } = {},
 ): Record<string, unknown> {
   const roots = orderedRoots(state, snapshot).map((item) => item.fold.id);
   const ordered = orderedFoldTree(state, snapshot);
@@ -918,18 +1062,49 @@ export function activeContextStatus(
   const eligibleEndpoints = eligibleSourceIds.length
     ? [...new Set([eligibleSourceIds[0], eligibleSourceIds.at(-1)!])]
     : [];
+  // The index that used to ride every status call grew from 12.6k to 86.5k chars in
+  // one measured session, injected on every request that asked for state. On the diet
+  // the default payload carries counts, the source map and the folds worth acting on;
+  // the full tree and the object list move behind an explicit paged query.
+  const index = statusOptions.diet
+    ? visibleCollapsedFolds(state, snapshot)
+      .map((fold) => foldIndexRow(fold, state, snapshot))
+      .sort((left, right) =>
+        Number(right.reclaimableBytes) - Number(left.reclaimableBytes) ||
+        String(left.id).localeCompare(String(right.id)))
+      .slice(0, statusOptions.suggestions ?? STATUS_DIET_SUGGESTIONS)
+    : null;
+  const sourceMap = statusOptions.diet ? foldSourceMap(state, snapshot) : null;
   return {
     version: 1,
     service: "active-context-folding",
     roots,
-    folds: selected.map((fold) => foldStatusRow(fold, state, snapshot)),
+    ...(statusOptions.diet
+      ? {
+        index: "diet",
+        topFolds: index,
+        sourceMap: sourceMap!.entries,
+        sourceMapTotal: sourceMap!.total,
+        sourceMapTruncated: sourceMap!.truncated,
+        paging: {
+          note: "Results are delivered in bounded pages.",
+          folds: { action: "status", detail: "folds", offset: 0, limit: 40 },
+          objects: { action: "status", detail: "objects", offset: 0, limit: 40 },
+          tree: { action: "status", detail: "tree", offset: 0 },
+        },
+      }
+      : {
+        folds: selected.map((fold) => foldStatusRow(fold, state, snapshot)),
+        objects: selectedObjects,
+        nextObjectOffset: offset + selectedObjects.length < objects.length
+          ? offset + selectedObjects.length
+          : null,
+      }),
     offset,
     nextOffset: offset + selected.length < ordered.length ? offset + selected.length : null,
     totalFolds: ordered.length,
     protectedSourceIds: state.protected.flatMap((ref) => exactMapped(snapshot, ref) ? [ref.entryId] : []),
-    objects: selectedObjects,
     totalObjects: objects.length,
-    nextObjectOffset: offset + selectedObjects.length < objects.length ? offset + selectedObjects.length : null,
     eligibleChapter: eligibleChapter ? {
       kind: "chapter",
       sourceCount: eligibleSourceIds.length,
@@ -949,6 +1124,91 @@ export function activeContextStatus(
   };
 }
 
+/** Room reserved for the one-line continuation marker a truncated page carries. */
+const STATUS_CONTINUATION_RESERVE_BYTES = 400;
+
+/**
+ * Enforce the hard status page cap on one fully assembled status payload.
+ *
+ * Measured 2026-08-07 (rep 19): one status answer serialized to 526KB, 6.2x the
+ * remaining headroom, and aborted the request. The paging affordance existed;
+ * nothing forced it. This function is the force: every listing in the payload is
+ * truncated at a unit boundary (whole rows, never mid-unit) until the serialized
+ * page fits, and a one-line continuation marker names the next offset. Trim order
+ * spends the diagnostics first and the listing the caller asked for last, and the
+ * requested listing always keeps at least one unit so paging always progresses.
+ */
+export function boundStatusPayload(
+  payload: Record<string, unknown>,
+  detail: string | null,
+  offset: number,
+  cap: number = CONTEXT_STATUS_RESPONSE_BYTES,
+): Record<string, unknown> {
+  const size = (): number => Buffer.byteLength(JSON.stringify(payload, null, 2), "utf8");
+  if (size() <= cap) return payload;
+  const target = cap - STATUS_CONTINUATION_RESERVE_BYTES;
+  const fits = (): boolean => size() <= target;
+  const omitted: string[] = [];
+  // keepEnd keeps the NEWEST units of a time-ordered ledger; a paged listing keeps
+  // its head so the continuation offset is the next unread unit. Binary search for
+  // the largest keep that fits; a stage that cannot fit alone trims to its floor.
+  const shrink = (owner: unknown, key: string, label: string, keepEnd = false, minKeep = 0): number => {
+    if (!isPlainRecord(owner) || fits()) return 0;
+    const original = ownValue(owner, key);
+    if (!Array.isArray(original) || original.length <= minKeep) return 0;
+    const container = owner as Record<string, unknown>;
+    const apply = (keep: number): void => {
+      container[key] = keepEnd ? original.slice(original.length - keep) : original.slice(0, keep);
+    };
+    let low = minKeep;
+    let high = original.length - 1;
+    let keep = minKeep;
+    while (low <= high) {
+      const mid = (low + high) >> 1;
+      apply(mid);
+      if (fits()) { keep = mid; low = mid + 1; } else { high = mid - 1; }
+    }
+    apply(keep);
+    const dropped = original.length - keep;
+    if (dropped > 0) omitted.push(`${dropped} ${label}`);
+    return dropped;
+  };
+  const automatic = ownValue(payload, "automatic");
+  const instrumentation = isPlainRecord(automatic) ? ownValue(automatic, "instrumentation") : undefined;
+  const surfacing = isPlainRecord(automatic) ? ownValue(automatic, "surfacing") : undefined;
+  shrink(instrumentation, "projectionRecords", "projection record(s)", true);
+  shrink(instrumentation, "cacheObservations", "cache observation(s)", true);
+  shrink(instrumentation, "events", "context event(s)", true);
+  shrink(surfacing, "log", "surfacing log row(s)", true);
+  if (shrink(payload, "sourceMap", "source map row(s)") > 0) payload.sourceMapTruncated = true;
+  shrink(payload, "topFolds", "top fold row(s)");
+  const rowLabel = (key: string): string => key === "folds" ? "fold row(s)" : key === "objects" ? "object row(s)" : "tree row(s)";
+  // The listing the caller asked for goes last and never below one unit. Its
+  // machine-readable next offset moves back to the first unit the page dropped.
+  let continueAt: number | null = null;
+  if (detail === "folds" || detail === "objects") {
+    const rideKey = detail === "folds" ? "objects" : "folds";
+    if (shrink(payload, rideKey, rowLabel(rideKey)) > 0) {
+      const rideKept = (payload[rideKey] as unknown[]).length;
+      if (rideKey === "folds") payload.nextOffset = offset + rideKept;
+      else payload.nextObjectOffset = offset + rideKept;
+    }
+  }
+  const primaryKey = detail === "objects" ? "objects" : detail === "tree" ? "tree" : detail === "folds" ? "folds" : null;
+  if (primaryKey && shrink(payload, primaryKey, rowLabel(primaryKey), false, 1) > 0) {
+    continueAt = offset + (payload[primaryKey] as unknown[]).length;
+    if (primaryKey === "objects") payload.nextObjectOffset = continueAt;
+    else payload.nextOffset = continueAt;
+  }
+  if (!omitted.length) return payload;
+  const resume = continueAt === null
+    ? "the full lists stay reachable through the paged status details"
+    : `continue at ${JSON.stringify({ action: "status", detail, offset: continueAt })}`;
+  payload.continuation =
+    `Status pages are bounded to ${cap} bytes; omitted ${omitted.join(", ")}; ${resume}.`;
+  return payload;
+}
+
 export function visibleCollapsedFolds(
   state: ActiveContextState,
   snapshot: ActiveContextSnapshot,
@@ -1044,7 +1304,7 @@ export function recoverFoldMessages(input: {
 
 /**
  * Ephemeral point read of one fold's exact source at any depth. It recovers the same
- * SHA-256-verified messages expansion restores, bounded for the reply, and changes no
+ * 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.
  */
 export function peekFoldSource(input: {
@@ -1052,7 +1312,11 @@ export function peekFoldSource(input: {
   state: ActiveContextState;
   entries: Array<Record<string, unknown>>;
   sessionId: string;
+  /** Explicit widening. Absent, a peek returns the bounded index view. */
   maximumBytes?: number;
+  /** Byte offset into the exact stored source; the narrowing half of admission control. */
+  offset?: number;
+  toolName?: string;
   projectEntry?: (entry: Record<string, unknown>) => unknown[];
 }): Record<string, unknown> {
   const fold = input.state.folds.find((item) => item.id === input.foldId);
@@ -1066,9 +1330,25 @@ export function peekFoldSource(input: {
   });
   const source = stableStringify(messages);
   const sourceBytes = bytes(source);
-  const returned = boundedUtf8(source, input.maximumBytes ?? ACTIVE_CONTEXT_POLICY.maxChapterChars);
-  const returnedBytes = bytes(returned);
-  const truncated = returnedBytes < sourceBytes;
+  const offset = Math.min(Math.max(0, input.offset ?? 0), sourceBytes);
+  const budget = input.maximumBytes ?? PEEK_DEFAULT_MAX_BYTES;
+  const window = offset > 0 ? utf8Slice(source, offset) : source;
+  // Offset zero is the INDEX read and takes head AND tail, because chain keys and
+  // conclusions live at the end of a source and a head-only slice silently omits
+  // exactly that region. An explicit offset is paging and stays contiguous.
+  const view = offset > 0
+    ? { text: boundedUtf8(window, budget), omittedBytes: 0, contiguous: true }
+    : boundedHeadTail(window, budget);
+  const returned = view.text;
+  const returnedBytes = bytes(returned) - bytes(headTailMarker(view.omittedBytes));
+  const nextOffset = view.contiguous && offset + returnedBytes < sourceBytes
+    ? offset + returnedBytes
+    : null;
+  const truncated = view.omittedBytes > 0 || nextOffset !== null;
+  const children = childFoldIds(fold);
+  // The index view: every nested fold's brief in FULL. A brief is the navigable unit,
+  // so truncating it is the one economy that costs the read its purpose.
+  const index = descendantIndexRows(fold, input.state);
   return {
     version: 1,
     action: "peek",
@@ -1076,16 +1356,103 @@ export function peekFoldSource(input: {
     kind: fold.kind,
     parentId: fold.parentId,
     depth: foldDepth(input.state, fold),
-    brief: fold.brief,
+    brief: foldBrief(fold, input.state),
     sourceCount: messages.length,
     sourceSha256: fold.sourceSha256,
     sourceBytes,
+    offset,
     returnedBytes,
+    omittedBytes: view.omittedBytes,
+    nextOffset,
     truncated,
+    view: offset > 0 ? "slice" : (view.omittedBytes > 0 ? "index" : "complete"),
+    ...(index.length ? { index } : {}),
+    // Narrower and WIDER reads that are always constructible, so a refusal or a
+    // truncation can name one.
+    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) } }
+      : {}),
+    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.",
     note: truncated
-      ? `Truncated: this reply carries the first ${returnedBytes} of ${sourceBytes} exact source bytes; ` +
-        `expand ${fold.id} to restore the complete source in place.`
+      ? `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.",
     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
+    // thousand source bytes is a notice unread (measured: a run concluded a staged chain
+    // was finished because the chain key lived in the unshown tail of a truncated peek).
+    ...(truncated
+      ? {
+        truncationReminder: `STOP: ${view.omittedBytes || sourceBytes - returnedBytes} of ${sourceBytes} ` +
+          "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)}}` +
+          (nextOffset === null ? "" : ` or read on with {"action":"peek","id":"${fold.id}","offset":${nextOffset}}`) +
+          ".",
+      }
+      : {}),
+  };
+}
+
+/** The marker a head+tail view puts where the omitted middle was. */
+export function headTailMarker(omittedBytes: number): string {
+  return omittedBytes > 0 ? `\n... [${omittedBytes} exact source bytes omitted] ...\n` : "";
+}
+
+/**
+ * A bounded view that keeps the head AND the tail. A head-only bound drops exactly the
+ * region a staged chain keeps its key in; the omitted size is stated where the reading
+ * ends so "there is more" is never an inference.
+ */
+export function boundedHeadTail(
+  source: string,
+  budget: number,
+): { text: string; omittedBytes: number; contiguous: boolean } {
+  const total = bytes(source);
+  if (total <= budget) return { text: source, omittedBytes: 0, contiguous: true };
+  const headBudget = Math.max(1, Math.floor(budget * PEEK_HEAD_SHARE));
+  const head = boundedUtf8(source, headBudget);
+  const tailBudget = Math.max(1, budget - bytes(head));
+  const tailStart = Math.max(bytes(head), total - tailBudget);
+  const tail = boundedUtf8(utf8Slice(source, tailStart), tailBudget);
+  const omittedBytes = Math.max(0, total - bytes(head) - bytes(tail));
+  if (omittedBytes <= 0) return { text: source, omittedBytes: 0, contiguous: true };
+  return {
+    text: `${head}${headTailMarker(omittedBytes)}${tail}`,
+    omittedBytes,
+    contiguous: false,
+  };
+}
+
+/** Every descendant fold, in transcript order, with its brief in full. */
+export function descendantIndexRows(
+  fold: ActiveFold,
+  state: ActiveContextState,
+): Array<Record<string, unknown>> {
+  const byId = foldMap(state);
+  const rows: Array<Record<string, unknown>> = [];
+  const visit = (parent: ActiveFold): void => {
+    for (const childId of childFoldIds(parent)) {
+      const child = byId.get(childId);
+      if (!child) continue;
+      rows.push({
+        id: child.id,
+        kind: child.kind,
+        depth: foldDepth(state, child),
+        brief: foldBrief(child, state),
+        peek: { action: "peek", id: child.id },
+      });
+      visit(child);
+    }
   };
+  visit(fold);
+  return rows;
 }