pi-fold 2.0.0 → 3.1.0

package/extensions/lib/selection.ts

@@ -16,7 +16,6 @@ import {
   orderedRoots,
   refsInOrder,
   refsProtected,
-  toolRefsProtected,
   visibleCollapsedRoots,
 } from "./measurement.ts";
 import {
@@ -28,7 +27,6 @@ import {
 import {
   ACTIVE_CONTEXT_POLICY,
   DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
-  MAX_FOLD_SPAN_CHARS,
 } from "./policy.ts";
 import type {
   ActiveContextSnapshot,
@@ -42,9 +40,9 @@ import type {
 } from "./policy.ts";
 import {
   chapterSegments,
-  currentTurnBoundary,
   scanTurnToolBatches,
   structurallyClosedChapterUnits,
+  deadAssistant,
   terminalAssistant,
 } from "./transcript.ts";
 import type { ChapterUnit } from "./transcript.ts";
@@ -105,7 +103,14 @@ export function resultCallIndex(snapshot: ActiveContextSnapshot, allowConsumedIn
           const message = snapshot.messages[index];
           if (messageRole(message) !== "assistant") continue;
           if (ownValue(message, "stopReason") === "toolUse") laterGenerations += 1;
-          else if (complete && terminalAssistant(message)) laterGenerations = Math.max(laterGenerations, 1);
+          // A dead turn's own terminal grants the point a finished turn's does: the turn
+          // is only in completeTurns because a user message already stands after it, so
+          // no later response will ever consume this batch, and demanding one anyway is
+          // the hold that deadlocked sol-20260826-full2 (the 423KB peek copy behind an
+          // errored assistant, ineligible for thirty-five aborting passes).
+          else if (complete && (terminalAssistant(message) || deadAssistant(message))) {
+            laterGenerations = Math.max(laterGenerations, 1);
+          }
         }
         if ((complete && laterGenerations < 1) || (!complete && laterGenerations < 2)) continue;
       }
@@ -503,9 +508,7 @@ export function pinnedChildFold(
     const child = byId.get(part.foldId);
     if (!child) continue;
     const refs = flattenFoldRefs(child, state);
-    const pinned = child.kind === "tool-result"
-      ? toolRefsProtected(refs, state, snapshot)
-      : refsProtected(refs, state, snapshot);
+    const pinned = refsProtected(refs, state, snapshot);
     if (pinned) return child;
   }
   return null;
@@ -513,7 +516,7 @@ export function pinnedChildFold(
 
 export function pinnedNestingRefusal(pinned: ActiveFold, toolName: string): string {
   return `fold refused: ${pinned.id} is pinned, and nesting it would hide context you asked to keep. ` +
-    `Release it with ${toolName} {"action":"unprotect","ids":["${pinned.id}"]} first, ` +
+    `Release it with ${toolName} {"action":"unpin","ids":["${pinned.id}"]} first, ` +
     "or name a span that stops at its boundary.";
 }
 
@@ -676,7 +679,6 @@ function consolidationCandidate(
   if (refsProtected(raw, state, snapshot)) return null;
   if (raw.some((ref) => claims.refKeys.has(objectRefKey(ref)))) return null;
   const sourceRefs = candidateSourceRefs(parts, state);
-  if (sourceRefs.length > snapshot.policy.maxFoldSourceRefs) return null;
   return { kind: "consolidation", parts, sourceRefs };
 }
 
@@ -734,15 +736,47 @@ export function automaticToolBatches(
     if (ids.size !== expected.length || expected.some((id) => !ids.has(id)) ||
         refs.some((ref) => !ref || ref.role !== "toolResult")) continue;
     const exactRefs = refs as EvidenceRef[];
-    const size = group.reduce((total, { item }) => total + bytes(item.message), 0);
-    if (exactRefs.length > snapshot.policy.maxFoldSourceRefs ||
-        toolRefsProtected(exactRefs, state, snapshot) || refsInOrder(snapshot, exactRefs) === null ||
-        size < snapshot.policy.minToolChars) continue;
+    const size = group.reduce((total, { item }) => total + messageBytes(item.message), 0);
+    if (refsProtected(exactRefs, state, snapshot) || refsInOrder(snapshot, exactRefs) === null ||
+        size < snapshot.thresholds.minFoldChars) continue;
     batches.push({ refs: exactRefs, indices: group.map(({ item }) => item.index), bytes: size });
   }
   return batches;
 }
 
+/**
+ * The serialized size of ONE transcript message, derived once per message object.
+ *
+ * `selectAutomaticSpan` tries the batch lane first, so this runs up to
+ * MAX_FRONTIER_CUTS_PER_PASS times per context event from `frontierMarks`, once per staged
+ * mark in a fill, and again from `unmarkedRemainder`. Everything else in
+ * `automaticToolBatches` was already memoized; this was not, and it ran BEFORE the
+ * eligibility filter, on every complete group including ones that go on to be refused.
+ *
+ * IT IS KEYED ON THE MESSAGE OBJECT, which is only useful because of where the object comes
+ * from: `snapshot.mapped[i].message` is `input.eventMessages[index]` VERBATIM
+ * (transcript.ts:494-508), so it is the same object across every snapshot derived from the
+ * same session, and the memo hits. `snapshot.messages` is `clone(input.eventMessages)`
+ * (transcript.ts:531), fresh objects on every derivation, so a caller reading THAT would
+ * never hit and should not be routed here.
+ *
+ * Deliberately NOT a wrapper on `bytes()`, which is also called on transient arrays
+ * (folding.ts, scheduling.ts) whose keys could never hit and would only grow the map.
+ *
+ * The accepted cost is gate 121's: a message mutated in place keeps its first size.
+ */
+const MESSAGE_BYTES = new WeakMap<object, number>();
+
+export function messageBytes(message: unknown): number {
+  const key = message && typeof message === "object" ? message as object : null;
+  if (!key) return bytes(message);
+  const memoized = MESSAGE_BYTES.get(key);
+  if (memoized !== undefined) return memoized;
+  const size = bytes(message);
+  MESSAGE_BYTES.set(key, size);
+  return size;
+}
+
 export function selectAutomaticToolBatch(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
@@ -770,9 +804,7 @@ export function selectAutomaticRefold(
     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"
-      ? toolRefsProtected(flattenFoldRefs(fold, state), state, snapshot)
-      : refsProtected(flattenFoldRefs(fold, state), state, snapshot));
+    const protectedSource = fold && (refsProtected(flattenFoldRefs(fold, state), state, snapshot));
     return fold && interval && !protectedSource && !state.leases[id]
       ? [{ id, ...interval }]
       : [];
@@ -805,47 +837,9 @@ export function resolveFoldInputIds(
 export function chapterRangeIsUnitAligned(snapshot: ActiveContextSnapshot, start: number, end: number): boolean {
   const units = chapterUnits(snapshot).filter((unit) => unit.end > start && unit.start <= end);
   if (!units.length || units[0].start !== start || units.at(-1)!.end !== end + 1) return false;
-  if (new Set(units.map((unit) => unit.turnStart)).size > snapshot.policy.maxChapterTurns) return false;
   return units.every((unit, index) => index === 0 || unit.start === units[index - 1].end);
 }
 
-export function splitCandidateBySize(
-  snapshot: ActiveContextSnapshot,
-  state: ActiveContextState,
-  candidate: FoldCandidate,
-  maxChars: number = MAX_FOLD_SPAN_CHARS,
-): FoldCandidate[] {
-  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];
-}
-
 export function candidateSpanChars(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
@@ -986,11 +980,6 @@ export function snapSpanIds(
           `${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 startUnit = units.find((unit) => start >= unit.start && start < unit.end);
     if (startUnit && startUnit.start !== start) {
       start = startUnit.start;
@@ -1001,23 +990,6 @@ export function snapSpanIds(
       end = endUnit.end - 1;
       note("span ended mid-unit; corrected to the end of its closed user/assistant/tool unit");
     }
-    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 (start === passStart && end === passEnd) break;
   }
   if (!corrections.length || end < start ||
@@ -1066,15 +1038,10 @@ export function manualFoldCandidate(
   ids: string[],
   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 owners = directFoldOwners(state.folds);
   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`);
-    }
     for (const part of candidate.parts) {
       if (part.kind !== "raw") continue;
       const ownerId = owners.get(objectRefKey(part.ref));
@@ -1098,10 +1065,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 && !blockedTool(refs)) {
+    if (completeBatch && !blocked(refs)) {
       return bounded({ kind: "tool-result", parts: refs.map((ref) => ({ kind: "raw", ref })), sourceRefs: refs });
     }
-    if (one && first && first.batch.length === 1 && !blockedTool(refs)) {
+    if (one && first && first.batch.length === 1 && !blocked(refs)) {
       return bounded({ kind: "tool-result", parts: [{ kind: "raw", ref: refs[0] }], sourceRefs: refs });
     }
   }
@@ -1133,6 +1100,26 @@ export function manualFoldCandidate(
   return bounded({ kind: "chapter", parts, sourceRefs: refs });
 }
 
+// THE TOOL-CLIP VIEW HEAD (2026-08-24). A clipped result keeps its opening verbatim,
+// not collapsed: the view stays a readable result head in place, unlike a brief's
+// one-line quote. The paragraph rule is gate 134's: an opening block terminated by a
+// blank line is kept whole up to the cap; a result that is bulk from line one keeps its
+// first cap's worth. The caller states the cut, per gate 136: the marker rides beside
+// the count of what it hides, never silently.
+export function toolClipHead(text: string, cap: number): string {
+  const lines = String(text ?? "").split(/\r?\n/);
+  const kept: string[] = [];
+  for (const line of lines) {
+    if (line.trim()) kept.push(line);
+    else if (kept.length) break;
+  }
+  const paragraph = kept.join("\n");
+  const head = paragraph.length > 0 && paragraph.length <= cap
+    ? paragraph
+    : String(text ?? "").slice(0, cap);
+  return head;
+}
+
 export function oneLine(value: string, maximum: number): string {
   return boundedSubject(value.replace(/\s+/g, " ").trim(), maximum);
 }
@@ -1145,44 +1132,58 @@ export function deterministicChapterBrief(
   if (refs.length !== messages.length || !refs.length) {
     throw new Error("Deterministic chapter brief requires aligned exact evidence");
   }
-  const firstUser = messages.find((message) => messageRole(message) === "user");
-  const toolCounts = new Map<string, number>();
+  // EVERY ENTRY IDENTIFIED IN SPAN ORDER (Shane 2026-08-24). The count-style brief
+  // ("User: ... \u00b7 Tools: 3\u00d7bash \u00b7 Assistant: No assistant text in this span")
+  // collapsed to the same anonymous line on every residue span of the pull workload:
+  // sol-20260823-live rep 3 committed 188 byte-identical placeholders of that shape and
+  // the agent re-peeked 76 folds 209 times to learn what each one held. The span's own
+  // calls are the index: each call named with its arguments and its result's opening
+  // line, an errored result marked, the user's ask and every assistant note seated in
+  // span order, and what the cap refuses COUNTED rather than dropped (the gate-135 law
+  // carried forward: a value recorded once in an assistant note between two batches must
+  // reach the brief). Cuts run through oneLine, so "..." always means the exact source
+  // continues.
+  const callNames = new Map<string, string>();
+  const pieces: string[] = [];
   for (const message of messages) {
-    if (messageRole(message) !== "assistant") continue;
-    for (const part of denseOwnArrayValues(ownValue(message, "content")) ?? []) {
-      if (ownValue(part, "type") !== "toolCall") continue;
-      const name = ownValue(part, "name");
-      if (typeof name === "string" && name) toolCounts.set(name, (toolCounts.get(name) ?? 0) + 1);
+    const role = messageRole(message);
+    if (role === "user") {
+      const ask = contentText(message);
+      if (ask.trim()) pieces.push(`User asked: ${oneLine(ask, 120)}`);
+    } else if (role === "assistant") {
+      for (const part of denseOwnArrayValues(ownValue(message, "content")) ?? []) {
+        if (ownValue(part, "type") !== "toolCall") continue;
+        const id = ownValue(part, "id");
+        const name = ownValue(part, "name");
+        if (typeof id !== "string" || !id || typeof name !== "string" || !name) continue;
+        let args = "{}";
+        try {
+          args = JSON.stringify(ownValue(part, "arguments") ?? {}) ?? "{}";
+        } catch {
+          args = "{unserializable}";
+        }
+        callNames.set(id, `${name}(${oneLine(args, 80)})`);
+      }
+      const note = assistantNoteText(message);
+      if (note) pieces.push(`Noted: ${boundedSubject(note, CHAPTER_NOTE_CHARS)}`);
+    } else if (role === "toolResult") {
+      const id = ownValue(message, "toolCallId");
+      const name = ownValue(message, "toolName");
+      const head = (typeof id === "string" ? callNames.get(id) : undefined) ??
+        (typeof name === "string" && name ? `${name}(...)` : "tool(...)");
+      const errored = ownValue(message, "isError") === true ? " [errored]" : "";
+      pieces.push(`${head}${errored} \u2192 "${oneLine(contentText(message), 90)}"`);
     }
   }
-  // EVERY assistant note in the span, not the first line of the first one
-  // (Shane 2026-08-14). A chapter is the first fold that hides its span, and a
-  // value the agent recorded once on a later turn died with the old single
-  // line: sol-20260814-traps rep 2 lost trace-a-02 and trace-d-05 to exactly
-  // that shape, an assistant message between two tool batches whose words
-  // reached zero briefs. Each note is the message's leading paragraph, capped
-  // per note, seated whole in span order until the brief's own bound refuses
-  // the next one, with the count of what did not seat stated rather than cut.
-  const notes = messages.flatMap((message) => {
-    if (messageRole(message) !== "assistant") return [];
-    const note = assistantNoteText(message);
-    return note ? [boundedSubject(note, CHAPTER_NOTE_CHARS)] : [];
-  });
-  const ask = oneLine(firstUser ? contentText(firstUser) : "No user ask in this span", 90);
-  const tools = oneLine([...toolCounts.entries()]
-    .sort(([left], [right]) => left.localeCompare(right))
-    .map(([name, count]) => `${count}×${name}`)
-    .join(" ") || "no tools", 500);
-  const separator = " | ";
+  const separator = " \u00b7 ";
   const compose = (kept: number): string => {
-    const omitted = notes.length - kept;
-    const shown = kept ? notes.slice(0, kept).join(separator)
-      : (notes.length ? "" : "No assistant text in this span");
-    const tail = omitted ? `${kept ? separator : ""}${omitted} more notes in this span` : "";
-    return `User: ${ask} · Tools: ${tools} · Assistant: ${shown}${tail}`;
+    const omitted = pieces.length - kept;
+    const shown = pieces.slice(0, kept).join(separator);
+    const tail = omitted ? `${kept ? separator : ""}${omitted} more entries in this span` : "";
+    return `${shown}${tail}`;
   };
-  let composed = compose(notes.length);
-  for (let kept = notes.length; kept > 0 && composed.length > ACTIVE_CONTEXT_POLICY.maxBriefChars; kept -= 1) {
+  let composed = compose(pieces.length);
+  for (let kept = pieces.length; kept > 0 && composed.length > ACTIVE_CONTEXT_POLICY.maxBriefChars; kept -= 1) {
     composed = compose(kept - 1);
   }
   const escapeName = (name: string) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");

package/extensions/lib/tool-surface.ts

@@ -7,6 +7,8 @@
  * nothing: the next model call that reads a result, a natural boundary in the work.
  */
 
+import { MEMORY_BODY_CHARS, MEMORY_KEY_CHARS, MEMORY_KEYS_MAX } from "./policy.ts";
+
 type ToolHandler = (
   toolCallId: string,
   params: Record<string, unknown>,
@@ -29,27 +31,30 @@ export function buildActiveContextTool(input: {
   handler: ToolHandler;
 }) {
   const peekGuidance = input.allowedActions.includes("peek")
-    ? ` Peek is the point read: it returns one fold's index view -- every nested fold's brief in full, plus the head and tail of that fold's own span with the omitted middle stated -- for any fold id, ancestors still collapsed, changing nothing. It serves ONE level: raw entries come back exactly, folds nested inside stay placeheld, and peeking a child id you see there returns that child's own bytes, so anything folded is one hop away at any depth. It returns at most ${input.defaultPeekBytes} bytes unless you widen it with bytes, and it stays in the window like any other tool result. Expand is the durable in-place restoration.`
+    ? ` Peek is the point read: it returns one fold's index view -- nested folds' briefs seated shallowest first inside the byte budget with the omitted rows counted, plus the head and tail of that fold's own span with the omitted middle stated -- for any fold id, ancestors still collapsed, changing nothing. It serves ONE level: raw entries come back exactly, folds nested inside stay placeheld, and peeking a child id you see there returns that child's own bytes, so anything folded is one hop away at any depth. It returns at most ${input.defaultPeekBytes} bytes unless you widen it with bytes, and it is EPHEMERAL by default: the bytes ride only until your next message, your reply then the surviving trace, so extract what your current task needs from them in that reply. Peeking again is lossless and costs one append, so a read you turn out to need twice is cheap; pass ephemeral false when you need the bytes standing across several turns. Expand is the durable in-place restoration.`
     : "";
-  const correctionGuidance = input.allowedActions.includes("rebrief")
-    ? " Curation is correctable: rebrief replaces a fold's brief, and reboundary with ids re-cuts a span into exactly one fold, which merges adjacent folds when the span covers several and splits one when the span sits inside it. Reboundary with a single id returns that fold's span to raw."
+  const correctionGuidance = input.allowedActions.includes("reboundary")
+    ? " Curation is correctable: reboundary with ids re-cuts a span into exactly one fold, which merges adjacent folds when the span covers several and splits one when the span sits inside it. Reboundary with a single id returns that fold's span to raw. A brief is written when you mark the span; a standing fold's brief is not rewritten, because rewriting it rewrites the projection at that fold's placeholder and costs the whole prefix cache from there on."
     : "";
-  const pinGuidance = input.allowedActions.includes("protect")
-    ? " Protect is the pin: protect with ids holds folds or entries against automatic folding, consolidation and refolding until unprotect releases them, so an expanded span you still need stays expanded. Protect reveals nothing on its own: a folded span stays folded, just held. Pinning moves no context bytes, and fold receipts report how much mass you have pinned."
+  const pinGuidance = input.allowedActions.includes("pin")
+    ? " Pin with ids holds folds or entries against automatic folding, consolidation and refolding until unpin releases them, so an expanded span you still need stays expanded. Pin reveals nothing on its own: a folded span stays folded, just held. Pinning moves no context bytes, and fold receipts report how much mass you have pinned."
     : "";
-  const epochGuidance = input.allowedActions.includes("unmark")
-    ? " Fold scheduling is epoch mode: fold records pending marks and moves no context bytes, and the runtime applies every pending mark in one rewrite when the fold event fires. Mark SEVERAL spans in one call: marks carries several {ids, brief} pairs, and one call answers with your whole picture, every span now held plus the unmarked remainder and what share of the non-fresh window it is. Between fold events nothing else in your context changes, so that result is where the picture lives. Mark freely as you work; when to fold is the runtime's to decide, and unmark withdraws a mark you no longer want."
+  const epochGuidance = input.allowedActions.includes("brief")
+    ? " THE RUNTIME CUTS THE FOLDS AND YOU ANNOTATE THEM. As raw material piles up it is cut into pending folds behind you, stalest first. A pending fold moves NO context bytes: you keep seeing the raw material exactly as it is, and the fold reaches your window only when a commit applies it. You are told when folds are cut and which ones carry no brief yet. Answer with brief, one id and one sentence: you know why the span mattered and what you will want back from it, and the deterministic brief that fills the gap reads the span alone and does not. Writing a brief on a pending fold is FREE, because the fold is not in your window yet; briefing a standing fold is refused, because its placeholder is in your window and rewriting it rewrites your context from that point on. reboundary re-cuts a span the runtime got wrong, unmark withdraws a cut you do not want taken, and when to commit stays the runtime's to decide."
     : "";
   const recoveryGuidance = input.allowedActions.includes("expand")
     ? " A fold brief is an index entry, not the source: when a question or task depends on material that is folded, peek or expand that fold and answer from the exact bytes, never from memory of them. Recalling folded detail without reopening it is how specifics get misremembered."
     : "";
+  const memoryGuidance = input.allowedActions.includes("remember")
+    ? ` WORKING MEMORY: a session-scoped dictionary you maintain beside the fold index. remember with key and body writes or updates an entry (${MEMORY_KEY_CHARS}-character keys, ${MEMORY_BODY_CHARS}-character bodies, ${MEMORY_KEYS_MAX} entries); an empty body removes it; recall with keys reads bodies back, or everything when keys is omitted. The bodies live outside your window: only a one-glance table of contents rides your context, refreshed at each commit, so writing an entry costs your window almost nothing. Keep entries current as the work moves: when a fact an entry records changes, or new information lands that belongs in one, update it then rather than at the end.`
+    : "";
   const standingGuidance = " Folding is automatic, lossless and recoverable: the runtime folds stale spans on its own when the window needs room, nothing is ever discarded, and every folded span keeps its exact source. You are never asked to make room and no fold is ever announced in advance. Work normally and let it happen.";
   return {
     name: input.name,
     label: input.label,
     description: input.fullSurface
-      ? `Page, peek, fold, expand, refold, protect, rebrief, or re-cut exact Pi active-context evidence.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${standingGuidance} Mutations persist immediately and affect the next model call inside the same continuing turn; no turn boundary is required. Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`
-      : `Use only the configured active-context actions: ${input.allowedActions.join(", ")}.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${standingGuidance} Call fold only by copying the exact eligibleChapter.action returned by status; if status has no eligibleChapter, continue the task without folding. Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`,
+      ? `Page, peek, brief, expand, refold, pin, or re-cut exact Pi active-context evidence.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${memoryGuidance}${standingGuidance} Mutations persist immediately and affect the next model call inside the same continuing turn; no turn boundary is required. Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`
+      : `Use only the configured active-context actions: ${input.allowedActions.join(", ")}.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${memoryGuidance}${standingGuidance} Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`,
     parameters: {
       type: "object",
       additionalProperties: false,
@@ -58,35 +63,25 @@ export function buildActiveContextTool(input: {
         action: { type: "string", enum: input.allowedActions },
         ids: { type: "array", minItems: 1, maxItems: 64, items: { type: "string", minLength: 1 } },
         id: { type: "string", minLength: 1 },
-        marks: {
-          type: "array",
-          minItems: 1,
-          maxItems: 64,
-          description: "Fold only: several spans with their own briefs in one call, which is the shape to prefer. An invalid or overlapping span is corrected to the nearest valid edge and the correction is reported back.",
-          items: {
-            type: "object",
-            additionalProperties: false,
-            required: ["ids"],
-            properties: {
-              ids: { type: "array", minItems: 1, maxItems: 64, items: { type: "string", minLength: 1 } },
-              brief: {
-                type: "string",
-                minLength: 1,
-                maxLength: input.maxBriefChars,
-                description: "Write one for every span you mark. You know why the span mattered and " +
-                  "what you will want back from it; the deterministic brief that fills the gap " +
-                  "reads the span alone and does not.",
-              },
-            },
-          },
-        },
         brief: {
           type: "string",
           minLength: 1,
           maxLength: input.maxBriefChars,
-          description: `Factual fold brief, at most ${input.maxBriefChars} characters.`,
+          description: "Brief only: what you will want back from this pending fold that " +
+            "its automatic brief cannot know. Your sentence is kept BESIDE the automatic " +
+            `brief, never instead of it, at most ${input.maxBriefChars} characters. Free ` +
+            "to write, because the fold it names is not in your window yet.",
         },
         offset: { type: "integer", minimum: 0 },
+        ephemeral: {
+          type: "boolean",
+          description: "Peek only. Default TRUE: the returned bytes ride your context " +
+            "exactly until your next message, then their place holds a one-line " +
+            "placeholder and your reply is the surviving trace, so extract what you need " +
+            "into that reply. Peeking again is lossless. Pass false to keep the result " +
+            "standing like any other tool result, which is what you want when the bytes " +
+            "have to survive several turns of work.",
+        },
         bytes: {
           type: "integer",
           minimum: input.minPeekSliceBytes,
@@ -94,6 +89,31 @@ export function buildActiveContextTool(input: {
         },
         limit: { type: "integer", minimum: 1, maximum: 100 },
         detail: { type: "string", enum: [...input.statusDetails] },
+        ...(input.allowedActions.includes("remember")
+          ? {
+            key: {
+              type: "string",
+              minLength: 1,
+              maxLength: MEMORY_KEY_CHARS,
+              description: "remember only: the working-memory entry to write, update or " +
+                "(with an empty body) remove.",
+            },
+            body: {
+              type: "string",
+              maxLength: MEMORY_BODY_CHARS,
+              description: "remember only: the entry's full text, replacing what the key " +
+                "held. Empty removes the entry.",
+            },
+            keys: {
+              type: "array",
+              minItems: 1,
+              maxItems: MEMORY_KEYS_MAX,
+              items: { type: "string", minLength: 1 },
+              description: "recall only: the working-memory entries to read. Omit to read " +
+                "every entry.",
+            },
+          }
+          : {}),
       },
     },
     execute: input.handler,
@@ -103,8 +123,10 @@ export function buildActiveContextTool(input: {
 export function buildActiveContextCommands(input: {
   statusName: string;
   foldName: string;
+  editorName: string;
   statusHandler: CommandHandler;
   foldHandler: CommandHandler;
+  editorHandler: CommandHandler;
 }) {
   return [
     {
@@ -114,9 +136,14 @@ export function buildActiveContextCommands(input: {
     },
     {
       name: input.foldName,
-      description: "Losslessly fold a stale context span, or \"commit\" to apply every eligible mark now; " +
+      description: "Commit every staged fold in one epoch; with explicit ids, folds exactly that span now; " +
         "works without a main-model request",
       handler: input.foldHandler,
     },
+    {
+      name: input.editorName,
+      description: "Open the context window editor: occupancy, fold roots and briefs, staged marks, pins",
+      handler: input.editorHandler,
+    },
   ];
 }