pi-fold 0.1.1 → 1.0.1

package/extensions/lib/selection.ts

@@ -28,6 +28,7 @@ import {
   ACTIVE_CONTEXT_POLICY,
   CONSOLIDATION_WIDTH_THRESHOLD,
   DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
+  MAX_FOLD_SPAN_CHARS,
 } from "./policy.ts";
 import type {
   ActiveContextSnapshot,
@@ -41,6 +42,7 @@ import type {
 } from "./policy.ts";
 import {
   chapterSegments,
+  currentTurnBoundary,
   scanTurnToolBatches,
   structurallyClosedChapterUnits,
   terminalAssistant,
@@ -87,6 +89,7 @@ export function resultCallIndex(snapshot: ActiveContextSnapshot, allowConsumedIn
       allowConsumedIncomplete,
       snapshot.toolName,
       snapshot.readOnlyTools,
+      snapshot.readOnlyContextActions,
     );
     if (!validated) continue;
     const batches = new Map<number, string[]>();
@@ -149,6 +152,85 @@ export function toolCallArguments(snapshot: ActiveContextSnapshot, assistantInde
   return calls.get(id);
 }
 
+/**
+ * Anchor budgets for a stage-identified brief. They exist to keep the composed brief
+ * inside the hard 1200-character brief cap with the generic prose trimmed away: an
+ * argument list, a leading label from the result head, and the result TAIL, which is
+ * where a staged chain puts its keys and a report puts its conclusion.
+ */
+export const IDENTIFIED_BRIEF_ARGUMENT_CHARS = 240;
+export const IDENTIFIED_BRIEF_VALUE_CHARS = 96;
+export const IDENTIFIED_BRIEF_HEAD_CHARS = 160;
+export const IDENTIFIED_BRIEF_TAIL_CHARS = 120;
+export const IDENTIFIED_BRIEF_CALLS_CHARS = 400;
+
+/** Every scalar argument of a call, in stable key order, bounded per value and in total. */
+export function identifiedCallArguments(
+  args: unknown,
+  factual: (value: string, maximum: number) => string,
+): string {
+  if (!args || typeof args !== "object" || Array.isArray(args)) return "";
+  const pairs: string[] = [];
+  for (const key of Object.keys(args as Record<string, unknown>).sort()) {
+    const value = ownValue(args, key);
+    const text = typeof value === "string"
+      ? value
+      : (typeof value === "number" || typeof value === "boolean" ? String(value) : "");
+    if (!text.trim()) continue;
+    pairs.push(`${factual(key, 40)}=${factual(text, IDENTIFIED_BRIEF_VALUE_CHARS)}`);
+  }
+  return oneLine(pairs.join(", "), IDENTIFIED_BRIEF_ARGUMENT_CHARS);
+}
+
+/** The last characters of a result, which is the region a truncated read never shows. */
+export function identifiedResultTail(
+  message: unknown,
+  factual: (value: string, maximum: number) => string,
+): string {
+  const text = String(contentText(message) ?? "").replace(/\s+/g, " ").trim();
+  if (!text) return "";
+  return factual(text.slice(Math.max(0, text.length - IDENTIFIED_BRIEF_TAIL_CHARS)), IDENTIFIED_BRIEF_TAIL_CHARS);
+}
+
+/**
+ * The stage-identified brief. The generic prose is trimmed to a few words so the
+ * character budget buys ANCHORS instead: which call this was, with which arguments,
+ * what the result opened with, and what it ENDED with. The tail anchor is the point
+ * of the whole change: a reader deciding which fold holds a chain key can only tell
+ * from the tail, and a generic sentence never carried one.
+ */
+export function stageIdentifiedToolBrief(input: {
+  snapshot: ActiveContextSnapshot;
+  refs: EvidenceRef[];
+  calls: ResultCall[];
+  factualValue: (value: string, maximum: number) => string;
+  factualToolName: (name: string) => string;
+}): string | null {
+  const { snapshot, refs, calls, factualValue, factualToolName } = input;
+  const messages = refs.map((ref) => exactMapped(snapshot, ref)?.message ?? null);
+  if (messages.some((message) => message === null)) return null;
+  const signatures = calls.map((call) => {
+    const args = identifiedCallArguments(
+      toolCallArguments(snapshot, call.assistantIndex, call.id),
+      factualValue,
+    );
+    return args ? `${factualToolName(call.name)}(${args})` : factualToolName(call.name);
+  });
+  const label = factualValue(
+    String(contentText(messages[0]) ?? "").split(/\r?\n/).find((line) => line.trim()) ?? "",
+    IDENTIFIED_BRIEF_HEAD_CHARS,
+  );
+  const tail = identifiedResultTail(messages.at(-1), factualValue);
+  const composed = [
+    `Read ${oneLine(signatures.join("; "), IDENTIFIED_BRIEF_CALLS_CHARS)}`,
+    label ? `opens "${label}"` : "",
+    tail ? `ends "${tail}"` : "",
+    calls.length > 1 ? `${calls.length} exact results here` : "exact source here",
+  ].filter(Boolean).join(" · ");
+  const bounded = oneLine(composed, ACTIVE_CONTEXT_POLICY.maxBriefChars);
+  return usefulBrief(bounded, ACTIVE_CONTEXT_POLICY.maxBriefChars, snapshot.toolName) ? bounded : null;
+}
+
 export function automaticToolBrief(snapshot: ActiveContextSnapshot, candidate: FoldCandidate): string {
   const refs = candidate.kind === "tool-result" && candidate.parts.every((part) => part.kind === "raw")
     ? candidate.parts.map((part) => (part as Extract<FoldPart, { kind: "raw" }>).ref)
@@ -163,16 +245,21 @@ export function automaticToolBrief(snapshot: ActiveContextSnapshot, candidate: F
     throw new Error("Automatic tool brief crossed a validated assistant batch");
   }
   const first = calls[0];
-  const factualBriefValue = (value: string): string => value
+  const factualValue = (value: string, maximum: number): string => value
     .replace(new RegExp(snapshot.toolName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "gi"), "active-context service")
     .replace(/[\u0000-\u001f\u007f]+/g, " ")
     .replace(/\s+/g, " ")
     .trim()
-    .slice(0, 120);
+    .slice(0, maximum);
+  const factualBriefValue = (value: string): string => factualValue(value, 120);
   const factualToolName = (name: string): string => name.toLowerCase() === snapshot.toolName.toLowerCase()
     ? "active-context status inspection"
     : factualBriefValue(name);
   const args = toolCallArguments(snapshot, first.assistantIndex, first.id);
+  // Exact anchors before generic prose: one sentence per tool made every fold of that
+  // tool carry the SAME brief, so no index could answer which fold holds a given stage.
+  const identified = stageIdentifiedToolBrief({ snapshot, refs, calls, factualValue, factualToolName });
+  if (identified) return identified;
   const targets: string[] = [];
   for (const key of ["path", "address", "query", "url", "action", "id"]) {
     const value = ownValue(args, key);
@@ -252,14 +339,18 @@ export function selectAutomaticConsolidation(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
   ratio: number,
+  claimed: ReadonlySet<string> = new Set<string>(),
 ): FoldCandidate | null {
   const visibleRoots = visibleCollapsedRoots(state, snapshot);
   const widthEligible = visibleRoots.length > CONSOLIDATION_WIDTH_THRESHOLD;
   const pressureEligible = Number.isFinite(ratio) && ratio >= snapshot.policy.consolidationRatio;
   if (!widthEligible && !pressureEligible) return null;
-  const roots = visibleRoots.filter(({ fold }) =>
-    (fold.kind === "chapter" || fold.kind === "consolidation") &&
-    !refsProtected(flattenFoldRefs(fold, state), state, snapshot));
+  const roots = visibleRoots.filter(({ fold }) => {
+    if (fold.kind !== "chapter" && fold.kind !== "consolidation") return false;
+    const refs = flattenFoldRefs(fold, state);
+    if (claimed.size && refs.some((ref) => claimed.has(objectRefKey(ref)))) return false;
+    return !refsProtected(refs, state, snapshot);
+  });
   const candidateFor = (selected: typeof roots): FoldCandidate | null => {
     const parts: FoldPart[] = selected.map(({ fold }) => ({ kind: "fold", foldId: fold.id }));
     const sourceRefs = candidateSourceRefs(parts, state);
@@ -301,14 +392,20 @@ export function selectAutomaticConsolidation(
   return finish();
 }
 
+/**
+ * The stalest eligible completed read-only batch. `claimed` lets a caller exclude
+ * evidence already spoken for by something that is not yet a fold (a pending mark),
+ * so repeated calls walk forward instead of returning the same batch.
+ */
 export function selectAutomaticToolBatch(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
   ratio: number,
+  claimed: ReadonlySet<string> = new Set<string>(),
 ): FoldCandidate[] {
   if (!Number.isFinite(ratio) || ratio < snapshot.policy.toolFoldRatio) return [];
-  const owned = new Set(state.folds.flatMap((fold) => fold.parts.flatMap((part) =>
-    part.kind === "raw" ? [objectRefKey(part.ref)] : [])));
+  const owned = new Set([...claimed, ...state.folds.flatMap((fold) => fold.parts.flatMap((part) =>
+    part.kind === "raw" ? [objectRefKey(part.ref)] : []))]);
   const groups = new Map<number, Array<{ item: MappedMessage; call: NonNullable<ReturnType<typeof resultCall>> }>>();
   for (const item of snapshot.mapped) {
     if (messageRole(item.message) !== "toolResult") continue;
@@ -342,9 +439,11 @@ export function selectAutomaticRefold(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
   ratio: number,
+  claimedFoldIds: ReadonlySet<string> = new Set<string>(),
 ): string | null {
   if (!Number.isFinite(ratio) || ratio < snapshot.policy.refoldRatio) return null;
   const candidates = state.expanded.flatMap((id) => {
+    if (claimedFoldIds.has(id)) return [];
     const fold = state.folds.find((item) => item.id === id);
     const interval = fold ? foldInterval(fold, state, snapshot) : null;
     const protectedSource = fold && (fold.kind === "tool-result"
@@ -360,11 +459,12 @@ export function selectAutomaticToolForRung(
   state: ActiveContextState,
   ratio: number,
   cadenceWaived = false,
+  claimed: ReadonlySet<string> = new Set<string>(),
 ): FoldCandidate | null {
   const cadenceSatisfied = state.tokensSinceToolFold >= toolFoldCadence(snapshot.contextWindow);
   if (!cadenceWaived && (!Number.isFinite(ratio) ||
       (ratio < snapshot.policy.toolFoldRatio && !cadenceSatisfied))) return null;
-  return selectAutomaticToolBatch(snapshot, state, 1)[0] ?? null;
+  return selectAutomaticToolBatch(snapshot, state, 1, claimed)[0] ?? null;
 }
 
 export function resolveFoldInputIds(
@@ -396,11 +496,336 @@ export function chapterRangeIsUnitAligned(snapshot: ActiveContextSnapshot, start
   return units.every((unit, index) => index === 0 || unit.start === units[index - 1].end);
 }
 
+/**
+ * Bite-sized folds.
+ *
+ * A fold is only navigable if reading one back is cheap. Measured 2026-08-06 (rep 6):
+ * one 60,432-byte chapter fold hid the fact the run needed in its tail, and every peek
+ * of it was either truncated short of the answer or too expensive to widen. So a span
+ * whose content exceeds the cap becomes SEQUENTIAL folds, each with its own brief,
+ * split only at structurally closed unit boundaries -- never mid-entry.
+ *
+ * A single unit that alone exceeds the cap is returned whole: there is no valid
+ * interior boundary, and refusing to fold it would leave the biggest span in the
+ * window as the one thing nothing may reclaim. The caller reports the split.
+ */
+export function splitCandidateBySize(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  candidate: FoldCandidate,
+  maxChars: number = MAX_FOLD_SPAN_CHARS,
+): FoldCandidate[] {
+  // A tool-result fold owns exactly one validated assistant batch and a consolidation
+  // owns whole child folds; neither has an interior boundary to split on.
+  if (candidate.kind !== "chapter") return [candidate];
+  const refs = candidate.sourceRefs.length ? candidate.sourceRefs : candidateSourceRefs(candidate.parts, state);
+  const indices = refs.map((ref) => exactMapped(snapshot, ref)?.index ?? -1);
+  if (!indices.length || indices.some((index) => index < 0)) return [candidate];
+  const start = Math.min(...indices);
+  const end = Math.max(...indices);
+  if (spanBytes(snapshot, start, end + 1) <= maxChars) return [candidate];
+  const units = chapterUnits(snapshot).filter((unit) => unit.start >= start && unit.end <= end + 1);
+  if (units.length < 2) return [candidate];
+  const split: FoldCandidate[] = [];
+  const emit = (from: number, to: number): boolean => {
+    const parts = partsForRange(snapshot, state, from, to, new Set<FoldKind>(["tool-result"]));
+    if (!parts) return false;
+    split.push({ kind: "chapter", parts, sourceRefs: candidateSourceRefs(parts, state) });
+    return true;
+  };
+  let runStart = units[0].start;
+  let runBytes = 0;
+  for (const unit of units) {
+    const size = spanBytes(snapshot, unit.start, unit.end);
+    if (runBytes > 0 && runBytes + size > maxChars) {
+      if (!emit(runStart, unit.start - 1)) return [candidate];
+      runStart = unit.start;
+      runBytes = 0;
+    }
+    runBytes += size;
+  }
+  if (runBytes > 0 && !emit(runStart, units.at(-1)!.end - 1)) return [candidate];
+  return split.length ? split : [candidate];
+}
+
+/** Exact serialized size of a candidate's whole span, folds and raw entries alike. */
+export function candidateSpanChars(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  candidate: FoldCandidate,
+): number {
+  const refs = candidate.sourceRefs.length ? candidate.sourceRefs : candidateSourceRefs(candidate.parts, state);
+  const indices = refs.map((ref) => exactMapped(snapshot, ref)?.index ?? -1).filter((index) => index >= 0);
+  if (!indices.length) return 0;
+  return spanBytes(snapshot, Math.min(...indices), Math.max(...indices) + 1);
+}
+
+/** Exact serialized size of a half-open mapped message range. */
+export function spanBytes(snapshot: ActiveContextSnapshot, start: number, end: number): number {
+  return bytes(snapshot.messages.slice(start, end));
+}
+
+/** One auto-snap the runtime applied to a requested span, reported never inferred. */
+export interface SpanCorrection {
+  from: string[];
+  to: string[];
+  reason: string;
+}
+
+export interface SnappedFoldSpan {
+  candidate: FoldCandidate;
+  corrections: SpanCorrection[];
+}
+
+/**
+ * Resolve a requested span, correcting it where a correction exists.
+ *
+ * A span the agent got slightly wrong -- crossing a fold it forgot about, reaching
+ * into the turn still in flight, landing mid-unit -- is a span it MEANT, and refusing
+ * it teaches the agent that curating is a coin flip. So an invalid span SNAPS to the
+ * nearest valid edge and the correction is stated in the result. Rejection is reserved
+ * for a request with no valid interpretation at all, and it says exactly what failed.
+ */
+export function snapFoldCandidate(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  ids: string[],
+  options: { allowProtected?: boolean } = {},
+): SnappedFoldSpan {
+  let directError: Error;
+  try {
+    return { candidate: manualFoldCandidate(snapshot, state, ids, options), corrections: [] };
+  } catch (error) {
+    directError = error instanceof Error ? error : new Error(String(error));
+  }
+  // Nearest first, then the other readings of the same intent. A span that cuts into one
+  // fold has exactly two endpoint corrections -- absorb it, or step past it -- and which
+  // one survives depends on structure the caller cannot see. A span that cuts into folds
+  // on BOTH sides has neither: every endpoint correction still leaves a whole chapter
+  // inside the span, and a chapter may not swallow one.
+  const alternatives = snapSpanAlternatives(snapshot, state, ids);
+  let lastError: Error = directError;
+  for (const snapped of alternatives) {
+    try {
+      return {
+        candidate: manualFoldCandidate(snapshot, state, snapped.ids, options),
+        corrections: snapped.corrections,
+      };
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+    }
+  }
+  // A suggestion the caller cannot act on is worse than no suggestion: never name a
+  // "nearest valid span" this same validation just refused. Nothing snapped, so the
+  // refusal is the direct one, stated once.
+  throw new Error(
+    `${directError.message}. No corrected reading of that span is constructible`,
+    { cause: lastError },
+  );
+}
+
+/**
+ * Every constructible reading of a requested span, nearest intent first.
+ *
+ * The three endpoint modes move the EDGES; the fourth reading moves the FRAME. A span
+ * cutting into folds at both ends has no endpoint correction that yields a foldable
+ * chapter -- each one still contains a whole chapter, which `partsForRange` refuses --
+ * so the only faithful reading left is the whole folds themselves: a consolidation.
+ */
+export function snapSpanAlternatives(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  ids: string[],
+): Array<{ ids: string[]; corrections: SpanCorrection[] }> {
+  const seen = new Set<string>();
+  const readings = [
+    ...(["nearest", "exclude", "absorb"] as const)
+      .map((mode) => snapSpanIds(snapshot, state, ids, mode)),
+    snapSpanToWholeFolds(snapshot, state, ids),
+  ];
+  return readings.flatMap((snapped) => {
+    if (!snapped) return [];
+    const key = snapped.ids.join("\u0000");
+    if (seen.has(key)) return [];
+    seen.add(key);
+    return [snapped];
+  });
+}
+
+/**
+ * The requested span read as the whole folds it cuts into.
+ *
+ * Constructible only when the outward snap lands on a contiguous tiling of two or more
+ * foldable roots: then the span the agent named IS those folds, and consolidating them
+ * is the one reading that both covers what was asked for and validates.
+ */
+export function snapSpanToWholeFolds(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  ids: string[],
+): { ids: string[]; corrections: SpanCorrection[] } | null {
+  let outward: ReturnType<typeof snapToFoldBoundaries>;
+  try { outward = snapToFoldBoundaries(snapshot, state, ids); }
+  catch { return null; }
+  if (!outward.corrections.length) return null;
+  const tiling = orderedRoots(state, snapshot)
+    .filter((root) => root.start >= outward.start && root.end <= outward.end);
+  if (tiling.length < 2) return null;
+  if (tiling[0].start !== outward.start || tiling.at(-1)!.end !== outward.end) return null;
+  if (tiling.some((root, index) => index > 0 && root.start !== tiling[index - 1].end + 1)) return null;
+  if (tiling.some((root) => root.fold.kind === "tool-result")) return null;
+  return {
+    ids: tiling.map((root) => root.fold.id),
+    corrections: [{
+      ...outward.corrections[0],
+      reason: `span cut into ${tiling.length} folds it may not re-fold; corrected outward to their whole ` +
+        `boundaries and read as a consolidation of ${tiling.map((root) => root.fold.id).join(", ")}`,
+    }],
+  };
+}
+
+/**
+ * The correction itself: pull the endpoints out of any fold they cut through, out of
+ * the turn still in flight, and onto structurally closed unit boundaries.
+ */
+export function snapSpanIds(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  ids: string[],
+  /** How an endpoint inside a fold is read: by distance, or always one way. */
+  mode: "nearest" | "absorb" | "exclude" = "nearest",
+): { ids: string[]; corrections: SpanCorrection[] } | null {
+  let resolved: Array<{ start: number; end: number; fold?: ActiveFold }>;
+  // An unknown id has no nearest valid edge: there is nothing to snap TO.
+  try { resolved = resolveFoldInputIds(snapshot, state, ids); }
+  catch { return null; }
+  const requested = [resolved[0].start, resolved.at(-1)!.end] as [number, number];
+  let [start, end] = requested;
+  const corrections: SpanCorrection[] = [];
+  const note = (reason: string): void => {
+    corrections.push({
+      from: [entryIdAt(snapshot, requested[0]), entryIdAt(snapshot, requested[1])],
+      to: [entryIdAt(snapshot, start), entryIdAt(snapshot, end)],
+      reason,
+    });
+  };
+  for (const root of orderedRoots(state, snapshot)) {
+    if (start > root.start && start <= root.end) {
+      const absorb = mode === "absorb" ||
+        (mode === "nearest" && start - root.start <= root.end + 1 - start);
+      start = absorb ? root.start : root.end + 1;
+      note(`span started inside ${root.fold.id}; corrected to its ` +
+        `${absorb ? "start" : "far"} boundary`);
+    }
+    if (end >= root.start && end < root.end) {
+      const absorb = mode === "absorb" ||
+        (mode === "nearest" && root.end - end <= end - (root.start - 1));
+      end = absorb ? root.end : root.start - 1;
+      note(`span ended inside ${root.fold.id}; corrected to its ` +
+        `${absorb ? "end" : "near"} boundary`);
+    }
+  }
+  const boundary = currentTurnBoundary(snapshot);
+  if (boundary >= 0 && end > boundary) {
+    end = boundary;
+    note("span reached into the turn still in flight; corrected back to the last closed turn");
+  }
+  const units = chapterUnits(snapshot);
+  const startUnit = units.find((unit) => start >= unit.start && start < unit.end);
+  if (startUnit && startUnit.start !== start) {
+    start = startUnit.start;
+    note("span started mid-unit; corrected to the start of its closed user/assistant/tool unit");
+  }
+  const endUnit = units.find((unit) => end >= unit.start && end < unit.end);
+  if (endUnit && endUnit.end - 1 !== end) {
+    end = endUnit.end - 1;
+    note("span ended mid-unit; corrected to the end of its closed user/assistant/tool unit");
+  }
+  // A chapter spans at most a few closed turns. A longer request is a span the agent
+  // meant, so it is CLAMPED to what one fold may hold rather than refused; the
+  // remainder stays raw and is the agent's to fold next.
+  const covered = units.filter((unit) => unit.start >= start && unit.end <= end + 1);
+  if (covered.length) {
+    const turns: number[] = [];
+    let clamped = end;
+    for (const unit of covered) {
+      if (!turns.includes(unit.turnStart)) {
+        if (turns.length >= snapshot.policy.maxChapterTurns) break;
+        turns.push(unit.turnStart);
+      }
+      clamped = unit.end - 1;
+    }
+    if (clamped < end) {
+      end = clamped;
+      note(`span covered more than the ${snapshot.policy.maxChapterTurns}-turn chapter limit; ` +
+        "corrected to the last turn that fits");
+    }
+  }
+  if (!corrections.length || end < start ||
+      !snapshot.mapped[start]?.ref || !snapshot.mapped[end]?.ref) return null;
+  return { ids: [entryIdAt(snapshot, start), entryIdAt(snapshot, end)], corrections };
+}
+
+/**
+ * Snap a span OUTWARD to whole-fold boundaries.
+ *
+ * The re-boundary verb operates on folds, so a span that cuts one in half has exactly
+ * one sane reading: the agent meant that fold. Outward rather than nearest, because
+ * losing a fold the agent did not name is the surprising outcome and re-cutting a
+ * slightly larger span is not.
+ */
+export function snapToFoldBoundaries(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  ids: string[],
+): { start: number; end: number; ids: string[]; covered: ActiveFold[]; corrections: SpanCorrection[] } {
+  const resolved = resolveFoldInputIds(snapshot, state, ids);
+  const requested: [number, number] = [resolved[0].start, resolved.at(-1)!.end];
+  let [start, end] = requested;
+  const corrections: SpanCorrection[] = [];
+  // Fixed point: absorbing one fold can pull the span across the next.
+  for (let pass = 0; pass < state.folds.length + 1; pass += 1) {
+    let moved = false;
+    for (const root of orderedRoots(state, snapshot)) {
+      if (root.end < start || root.start > end) continue;
+      if (root.start < start) { start = root.start; moved = true; }
+      if (root.end > end) { end = root.end; moved = true; }
+    }
+    if (!moved) break;
+  }
+  if (start !== requested[0] || end !== requested[1]) {
+    corrections.push({
+      from: [entryIdAt(snapshot, requested[0]), entryIdAt(snapshot, requested[1])],
+      to: [entryIdAt(snapshot, start), entryIdAt(snapshot, end)],
+      reason: "span partially covered one or more folds; corrected outward to their whole boundaries",
+    });
+  }
+  const covered = orderedRoots(state, snapshot)
+    .filter((root) => root.start >= start && root.end <= end)
+    .map((root) => root.fold);
+  return { start, end, ids: [entryIdAt(snapshot, start), entryIdAt(snapshot, end)], covered, corrections };
+}
+
+export function entryIdAt(snapshot: ActiveContextSnapshot, index: number): string {
+  return snapshot.mapped[index]?.ref?.entryId ?? `position-${index}`;
+}
+
 export function manualFoldCandidate(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
   ids: string[],
+  /**
+   * Accept a span that is still fresh or protected. Only a caller that will DEFER the
+   * fold may pass this: it relaxes eligibility, never structure, so contiguity, unit
+   * alignment and batch completeness are still enforced and the commit still refuses
+   * to apply a mark whose span is protected at commit time.
+   */
+  options: { allowProtected?: boolean } = {},
 ): FoldCandidate {
+  const blockedTool = (refs: EvidenceRef[]): boolean =>
+    !options.allowProtected && toolRefsProtected(refs, state, snapshot);
+  const blocked = (refs: EvidenceRef[]): boolean =>
+    !options.allowProtected && refsProtected(refs, state, snapshot);
   const bounded = (candidate: FoldCandidate): FoldCandidate => {
     if (candidate.sourceRefs.length > snapshot.policy.maxFoldSourceRefs) {
       throw new Error(`Folds may include at most ${snapshot.policy.maxFoldSourceRefs} exact source references`);
@@ -419,10 +844,10 @@ export function manualFoldCandidate(
       calls.length === first.batch.length &&
       new Set(calls.map((call) => call!.id)).size === first.batch.length &&
       first.batch.every((id) => calls.some((call) => call!.id === id));
-    if (completeBatch && !toolRefsProtected(refs, state, snapshot)) {
+    if (completeBatch && !blockedTool(refs)) {
       return bounded({ kind: "tool-result", parts: refs.map((ref) => ({ kind: "raw", ref })), sourceRefs: refs });
     }
-    if (one && first && first.batch.length === 1 && !toolRefsProtected(refs, state, snapshot)) {
+    if (one && first && first.batch.length === 1 && !blockedTool(refs)) {
       return bounded({ kind: "tool-result", parts: [{ kind: "raw", ref: refs[0] }], sourceRefs: refs });
     }
   }
@@ -431,7 +856,7 @@ export function manualFoldCandidate(
   if (exactFolds && selected.length >= 2) {
     const parts: FoldPart[] = selected.map((item) => ({ kind: "fold", foldId: item.fold!.id }));
     const refs = candidateSourceRefs(parts, state);
-    if (refsProtected(refs, state, snapshot)) throw new Error("Manual consolidation contains protected evidence");
+    if (blocked(refs)) throw new Error("Manual consolidation contains protected evidence");
     return bounded({ kind: "consolidation", parts, sourceRefs: refs });
   }
   if (!chapterRangeIsUnitAligned(snapshot, start, end)) {
@@ -440,7 +865,7 @@ export function manualFoldCandidate(
   const parts = partsForRange(snapshot, state, start, end, new Set<FoldKind>(["tool-result"]));
   if (!parts) throw new Error("Chapter fold would partially overlap or swallow an existing chapter");
   const refs = candidateSourceRefs(parts, state);
-  if (refsProtected(refs, state, snapshot)) throw new Error("Manual chapter contains fresh, unfinished, unmatched, unmapped, or protected evidence");
+  if (blocked(refs)) throw new Error("Manual chapter contains fresh, unfinished, unmatched, unmapped, or protected evidence");
   return bounded({ kind: "chapter", parts, sourceRefs: refs });
 }
 

package/extensions/lib/surfacing.ts

@@ -13,7 +13,10 @@ import {
   refsProtected,
   toolRefsProtected,
 } from "./measurement.ts";
-import { flattenFoldRefs } from "./persistence.ts";
+import {
+  flattenFoldRefs,
+  foldBrief,
+} from "./persistence.ts";
 import {
   SURFACING_CHAR_BUDGET,
   SURFACING_COOLDOWN_ORDINALS,
@@ -191,15 +194,29 @@ export function surfacingLog(state: Pick<ActiveContextState, "surfacing">): Surf
   return state.surfacing ? clone(state.surfacing) : [];
 }
 
+/**
+ * Property ORDER is load-bearing: the state digest is a stable stringify, so a
+ * `surfacing` key assigned onto a state that did not already carry one would land
+ * after `pendingMarks`/`advisory`/`prepared` and replay as digest drift. Rebuild the
+ * tail of the record in the same order `parseActiveContextState` produces.
+ */
 export function withSurfacingLog(
   state: ActiveContextState,
   log: readonly SurfacingRecord[],
 ): ActiveContextState {
   const bounded = log.slice(Math.max(0, log.length - SURFACING_MAX_LOG_RECORDS));
-  const next = { ...state };
-  if (bounded.length) next.surfacing = clone(bounded) as SurfacingRecord[];
-  else delete next.surfacing;
-  return next;
+  const head = { ...state };
+  delete head.surfacing;
+  delete head.pendingMarks;
+  delete head.advisory;
+  delete head.prepared;
+  return {
+    ...head,
+    ...(bounded.length ? { surfacing: clone(bounded) as SurfacingRecord[] } : {}),
+    ...(state.pendingMarks?.length ? { pendingMarks: clone(state.pendingMarks) } : {}),
+    ...(state.advisory ? { advisory: clone(state.advisory) } : {}),
+    ...(state.prepared ? { prepared: clone(state.prepared) } : {}),
+  };
 }
 
 /** A shown suggestion the agent never peeked or expanded inside the outcome window is a reject. */
@@ -245,7 +262,7 @@ export function foldBriefCandidates(input: SuggestionSourceInput): SurfacingCand
     return [{
       source: SURFACING_SOURCE_ID,
       id: fold.id,
-      text: fold.brief,
+      text: foldBrief(fold, state),
       route: `${toolName} {"action":"expand","id":"${fold.id}"}`,
       alternateRoute: `${toolName} {"action":"peek","id":"${fold.id}"}`,
       position: interval.end,