pi-fold 3.0.0 → 3.1.0

package/extensions/lib/scheduling.ts

@@ -3,6 +3,7 @@ import type { EvidenceRef } from "../json.ts";
 import {
   bytes,
   clone,
+  contentText,
   messageRole,
 } from "./canonical.ts";
 import {
@@ -10,6 +11,7 @@ import {
   pinnedPeekMass,
   preparedMatchesCandidate,
   prepareFold,
+  projectActiveContext,
   renderFold,
   renderFoldParts,
   selectAutomaticChapter,
@@ -17,6 +19,7 @@ import {
   setFoldProjectionState,
 } from "./folding.ts";
 import type { AutomaticRungSelection } from "./folding.ts";
+import { staleSpanMatureEnd } from "./transcript.ts";
 import {
   foldInterval,
   budgetOccupancy,
@@ -27,7 +30,6 @@ import {
 } from "./measurement.ts";
 import {
   childFoldIds,
-  clearPrepared,
   flattenFoldRefs,
   foldIdFor,
   parsePendingMarks,
@@ -41,6 +43,7 @@ import {
   MAX_UNMARKED_CANDIDATES,
 } from "./policy.ts";
 import type {
+  ToolClip,
   ActiveContextSnapshot,
   ActiveContextState,
   FoldCandidate,
@@ -217,7 +220,14 @@ export function markEligibility(
   if (span.unresolved) return span.unresolved.pending ? "protected" : "unfulfillable";
   const refs = span.refs;
   if (!refs.length) return "unfulfillable";
-  const mapped = new Set(snapshot.mapped.flatMap((item) => item.ref ? [objectRefKey(item.ref)] : []));
+  // THE MAPPED INDEX IS ALREADY DERIVED (2026-08-28). This built a fresh Set over the whole
+  // window to answer a membership question about the handful of refs in one mark's span, and
+  // `markAccounting` calls this once per pending mark while the commit fill calls
+  // `markAccounting` once per staged mark, so it was O(marks^2 x window). `mappedByKey` is
+  // gate 113's memo, keyed on the snapshot OBJECT, and `refsProtected` on the next line
+  // already depends on it being fresh: if it could serve stale, this function was already
+  // wrong. Measured 177.2ms to 41.6ms at the observed peak of 39 pending marks.
+  const mapped = mappedByKey(snapshot);
   if (refs.some((ref) => !mapped.has(objectRefKey(ref)))) return "unfulfillable";
   const blocked = refsProtected(refs, state, snapshot);
   return blocked ? "protected" : "eligible";
@@ -231,7 +241,6 @@ export interface MarkAccounting {
   freedBytes: number;
   freedTokens: number;
   freedBudgetShare: number;
-  rewriteTokens: number;
   eligibleMarks: number;
   retainedMarks: number;
   eligibleFreedBytes: number;
@@ -246,13 +255,10 @@ export function markAccounting(
   state: ActiveContextState,
 ): MarkAccounting {
   const marks = pendingMarks(state);
-  const indexByKey = new Map(snapshot.mapped.flatMap((item) =>
-    item.ref ? [[objectRefKey(item.ref), item.index] as const] : []));
   let freedBytes = 0;
   let eligibleFreedBytes = 0;
   let eligibleMarks = 0;
   let retainedMarks = 0;
-  let earliest = -1;
   for (const mark of marks) {
     const freed = markFreedBytes(snapshot, state, mark);
     freedBytes += freed;
@@ -261,15 +267,7 @@ export function markAccounting(
       eligibleMarks += 1;
       eligibleFreedBytes += freed;
     } else if (eligibility === "protected") retainedMarks += 1;
-    for (const ref of markSpanRefs(state, mark).refs) {
-      const index = indexByKey.get(objectRefKey(ref));
-      if (index === undefined) continue;
-      if (earliest < 0 || index < earliest) earliest = index;
-    }
   }
-  const rewriteBytes = earliest < 0
-    ? 0
-    : bytes(snapshot.messages.slice(earliest));
   const freedTokens = estimatedTokens(freedBytes);
   const eligibleFreedTokens = estimatedTokens(eligibleFreedBytes);
   const pinned = pinnedPeekMass(snapshot, state);
@@ -281,7 +279,6 @@ export function markAccounting(
     freedBytes,
     freedTokens,
     freedBudgetShare: snapshot.budgetTokens > 0 ? freedTokens / snapshot.budgetTokens : 0,
-    rewriteTokens: estimatedTokens(rewriteBytes),
     eligibleMarks,
     retainedMarks,
     eligibleFreedBytes,
@@ -294,6 +291,40 @@ export function markAccounting(
   };
 }
 
+/**
+ * What one commit would make the provider re-read: the marked tail, from the earliest
+ * marked message to the end of the window.
+ *
+ * IT IS DERIVED WHERE IT IS READ (2026-08-28). This was a field on `MarkAccounting`, which
+ * meant `bytes(snapshot.messages.slice(earliest))`, a serialization of the whole marked
+ * tail, ran on EVERY accounting call: the commit fill calls one per staged mark, and the
+ * `brief` handler calls one to read `pending` alone. Two readers want the number and both
+ * already hold the snapshot and the state, so the work moved to them. A memo could not have
+ * helped: `snapshot.messages` is `clone(input.eventMessages)` (transcript.ts:531), so its
+ * elements are fresh objects on every derivation and nothing keyed on them can ever hit.
+ *
+ * `schedulingStatus` still publishes `rewriteTokens` and now derives it here, so the status
+ * surface is unchanged. It is NOT a getter on the accounting object: `schedulingStatus`
+ * spreads the accounting, and a spread evaluates getters, which would put the cost straight
+ * back on every reader it was moved away from.
+ */
+export function markRewriteTokens(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+): number {
+  const indexByKey = new Map(snapshot.mapped.flatMap((item) =>
+    item.ref ? [[objectRefKey(item.ref), item.index] as const] : []));
+  let earliest = -1;
+  for (const mark of pendingMarks(state)) {
+    for (const ref of markSpanRefs(state, mark).refs) {
+      const index = indexByKey.get(objectRefKey(ref));
+      if (index === undefined) continue;
+      if (earliest < 0 || index < earliest) earliest = index;
+    }
+  }
+  return earliest < 0 ? 0 : estimatedTokens(bytes(snapshot.messages.slice(earliest)));
+}
+
 export function epochCommitDue(snapshot: ActiveContextSnapshot, ratio: number | null): boolean {
   const occupancy = budgetOccupancy(snapshot, ratio);
   return occupancy !== null && occupancy >= snapshot.thresholds.maxTarget;
@@ -1083,9 +1114,6 @@ export async function commitPendingMarks(input: {
         generation: input.generation,
       });
       applied.push({ mark: "fold", id: mark.id, origin: mark.origin, foldId: prepared.id });
-      if (state.prepared && state.folds.some((fold) => fold.id === state.prepared!.id)) {
-        state = clearPrepared(state);
-      }
     } catch (error) {
       refused.push({
         mark: mark.mark,
@@ -1112,6 +1140,11 @@ export function schedulingStatus(input: {
   return {
     mode: "epoch",
     ...accounting,
+    // The status surface keeps this field; the accounting no longer carries it. Status is a
+    // read the agent or the human asks for, so paying for the tail serialization HERE is
+    // the point of moving it: the commit fill calls `markAccounting` once per staged mark
+    // and none of those calls wants this number.
+    rewriteTokens: markRewriteTokens(input.snapshot, input.state),
     thresholds: { ...input.snapshot.thresholds },
     budgetTokens: input.snapshot.budgetTokens,
     commitDue: epochCommitDue(input.snapshot, input.ratio),
@@ -1131,3 +1164,57 @@ export function schedulingStatus(input: {
     })),
   };
 }
+
+// THE TOOL-CALL DIET SELECTS AT COMMIT TIME ONLY (2026-08-24, Shane's ToolFoldThreshold).
+// The zone is the oldest `threshold` share of the projected window measured in bytes,
+// because "the tool calls prior to the X point" is a statement about what the provider
+// is being made to re-read, and the projection is exactly that. Eligibility mirrors the
+// fold lanes' own laws one view over: the result must be MATURE (past
+// staleSpanMatureEnd, the batch lane's consumption proof), unprotected (a pinned ref is
+// a durable hold), not blacklisted (a tool whose results must stay raw stays raw in
+// view too), bigger than the floor (small calls are cheap; the win is the multi-KB
+// result), not a rendering the projection already substituted, and not already clipped.
+// The additions are VIEW state: encodedFoldSource reads raw parts, so a later fold of a
+// clipped span still encodes the full bytes and losslessness is untouched.
+export function toolClipAdditions(input: {
+  snapshot: ActiveContextSnapshot;
+  state: ActiveContextState;
+  threshold: number;
+  blacklist: ReadonlySet<string>;
+}): ToolClip[] {
+  const { snapshot, state, threshold, blacklist } = input;
+  const projected = projectActiveContext(snapshot, state);
+  const perMessage = projected.map((message) => bytes([message]));
+  const total = perMessage.reduce((sum, size) => sum + size, 0);
+  const zoneEnd = threshold * total;
+  const matureEnd = staleSpanMatureEnd(snapshot.messages);
+  const snapshotIndexByCallId = new Map<string, number>();
+  for (let index = 0; index < snapshot.messages.length; index += 1) {
+    const message = snapshot.messages[index] as { role?: unknown; toolCallId?: unknown };
+    if (message?.role === "toolResult" && typeof message.toolCallId === "string") {
+      snapshotIndexByCallId.set(message.toolCallId, index);
+    }
+  }
+  const already = new Set((state.clips ?? []).map((clip) => clip.callId));
+  const additions: ToolClip[] = [];
+  let offset = 0;
+  for (let index = 0; index < projected.length; index += 1) {
+    const start = offset;
+    offset += perMessage[index];
+    if (start >= zoneEnd) break;
+    const message = projected[index] as {
+      role?: unknown; toolCallId?: unknown; toolName?: unknown; details?: unknown;
+    };
+    if (message?.role !== "toolResult" || typeof message.toolCallId !== "string") continue;
+    if (already.has(message.toolCallId)) continue;
+    if (message.details && typeof (message.details as { projection?: unknown }).projection === "string") continue;
+    if (typeof message.toolName === "string" && blacklist.has(message.toolName)) continue;
+    const snapshotIndex = snapshotIndexByCallId.get(message.toolCallId);
+    if (snapshotIndex === undefined || snapshotIndex >= matureEnd) continue;
+    const ref = snapshot.mapped.find((item) => item.index === snapshotIndex)?.ref;
+    if (!ref || refsProtected([ref], state, snapshot)) continue;
+    if (contentText(message).length <= snapshot.policy.toolClipFloorChars) continue;
+    additions.push({ callId: message.toolCallId, entryId: ref.entryId });
+  }
+  return additions;
+}

package/extensions/lib/selection.ts

@@ -42,6 +42,7 @@ import {
   chapterSegments,
   scanTurnToolBatches,
   structurallyClosedChapterUnits,
+  deadAssistant,
   terminalAssistant,
 } from "./transcript.ts";
 import type { ChapterUnit } from "./transcript.ts";
@@ -102,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;
       }
@@ -728,7 +736,7 @@ 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);
+    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 });
@@ -736,6 +744,39 @@ export function automaticToolBatches(
   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,
@@ -997,8 +1038,6 @@ export function manualFoldCandidate(
   ids: string[],
   options: { allowProtected?: boolean } = {},
 ): FoldCandidate {
-  const blockedTool = (refs: EvidenceRef[]): boolean =>
-    !options.allowProtected && refsProtected(refs, state, snapshot);
   const blocked = (refs: EvidenceRef[]): boolean =>
     !options.allowProtected && refsProtected(refs, state, snapshot);
   const owners = directFoldOwners(state.folds);
@@ -1026,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 });
     }
   }
@@ -1061,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);
 }
@@ -1073,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,7 +31,7 @@ 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 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.`
+    ? ` 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("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."
@@ -43,13 +45,16 @@ export function buildActiveContextTool(input: {
   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, brief, expand, refold, pin, 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} 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,
@@ -62,9 +67,10 @@ export function buildActiveContextTool(input: {
           type: "string",
           minLength: 1,
           maxLength: input.maxBriefChars,
-          description: "Brief only: what this pending fold covers and what you will want " +
-            `back from it, at most ${input.maxBriefChars} characters. Free to write, ` +
-            "because the fold it names is not in your window yet.",
+          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: {
@@ -83,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,

package/extensions/lib/transcript.ts

@@ -37,6 +37,17 @@ export function terminalAssistant(message: unknown): boolean {
   return stop === "stop" || stop === "length";
 }
 
+/**
+ * An assistant stop that ends a turn by dying rather than by finishing. It is never
+ * terminal on its own: while it is the last message the turn may still be retried in
+ * place, so only a FOLLOWING user message proves the turn is over.
+ */
+export function deadAssistant(message: unknown): boolean {
+  if (messageRole(message) !== "assistant") return false;
+  const stop = ownValue(message, "stopReason");
+  return stop === "error" || stop === "aborted";
+}
+
 export function completeTurns(messages: unknown[]): CompleteTurn[] {
   const starts: number[] = [];
   for (let index = 0; index < messages.length; index += 1) if (messageRole(messages[index]) === "user") starts.push(index);
@@ -47,24 +58,26 @@ export function completeTurns(messages: unknown[]): CompleteTurn[] {
     let end = limit;
     while (end > start && (messageRole(messages[end - 1]) === "custom" ||
         messageRole(messages[end - 1]) === "bashExecution")) end -= 1;
-    if (end > start && terminalAssistant(messages[end - 1])) turns.push({ start, end });
+    if (end <= start) continue;
+    // A DEAD TURN IS A CLOSED TURN (sol-20260826-full2, pifold rep 1). A turn whose last
+    // word is an errored or aborted assistant, with a user message already standing after
+    // it, is over: no response for its material is ever coming, so holding its spans for
+    // a consumption proof holds them forever. That hold is what deadlocked a live run:
+    // the projection-budget fence aborted a request that would not fit, the abort put an
+    // errored assistant at the end of the turn holding the 423KB that made it not fit,
+    // the errored turn was invisible to every fold lane, and the next thirty-four
+    // requests aborted identically with the reclaimer finding nothing it was allowed to
+    // touch. The live tail keeps the strict rule: while the errored assistant is the
+    // last message the turn may still be retried in place, so death alone closes
+    // nothing.
+    if (terminalAssistant(messages[end - 1]) ||
+        (starts[cursor + 1] !== undefined && deadAssistant(messages[end - 1]))) {
+      turns.push({ start, end });
+    }
   }
   return turns;
 }
 
-export function leadingCompactionContinuation(messages: unknown[]): CompleteTurn | null {
-  if (messageRole(messages[0]) !== "compactionSummary") return null;
-  let firstUser = -1;
-  for (let index = 0; index < messages.length; index += 1) {
-    if (messageRole(messages[index]) === "user") { firstUser = index; break; }
-  }
-  if (firstUser <= 1 || messageRole(messages[1]) !== "assistant") return null;
-  let end = firstUser;
-  while (end > 1 && (messageRole(messages[end - 1]) === "custom" ||
-      messageRole(messages[end - 1]) === "bashExecution")) end -= 1;
-  return end > 1 && terminalAssistant(messages[end - 1]) ? { start: 1, end } : null;
-}
-
 export const READ_ONLY_CONTEXT_ACTION_ARGUMENTS: Readonly<Record<string, readonly string[]>> = Object.freeze({
   status: Object.freeze(["action", "detail", "offset", "limit"]),
   // offset and bytes are the tool surface's own narrowing parameters: a paged or
@@ -327,6 +340,44 @@ export function unsafeChapterIndices(messages: unknown[]): Set<number> {
  * than a curation preference. The fresh-tail byte walk that used to sit here is deleted:
  * nothing decided on it, and stale-first ordering already leaves recent material last.
  */
+/**
+ * THE STALE-SPAN MATURITY FLOOR (2026-08-24). The tool-batch lane proves consumption
+ * before it will index a result: two later generations in an open turn, one or the
+ * terminal assistant in a closed one (resultCallIndex). The chapter lane had no such
+ * proof, and on the pull-shaped workload the frontier cuts the moment a span crosses
+ * minFoldChars, which is always one turn before the same span's batch qualifies:
+ * sol-20260823-live rep 3 cut 219 chapters and ZERO tool folds over a transcript whose
+ * every span replays as a tool-result when aged, so every placeholder read "User: No
+ * user ask · Tools: 1×repo_stage · Assistant: No assistant text" and the agent
+ * re-peeked 76 folds 209 times to rebuild the index the brief should have carried. One
+ * floor, kind-agnostic, derived from the proof the batch lane already demands: a stale
+ * span may be cut only when it ends before the second-newest open generation, so by the
+ * time the chapter lane may touch material the tool lane has had its turn at it, and
+ * the tool-first preference in selectAutomaticSpan is reachable rather than starved.
+ * This is NOT gate 19/72's fresh-tail proportion returning: nothing here reads bytes or
+ * shares, and a closed session (terminal assistant) folds to its end exactly as before.
+ */
+export function staleSpanMatureEnd(messages: unknown[]): number {
+  if (messages.length && terminalAssistant(messages[messages.length - 1])) return messages.length;
+  const generations: number[] = [];
+  for (let index = 0; index < messages.length; index += 1) {
+    const message = messages[index];
+    if (messageRole(message) === "assistant" && ownValue(message, "stopReason") === "toolUse") {
+      generations.push(index);
+    }
+  }
+  const generationFloor = generations.length < 2 ? 0 : generations[generations.length - 2];
+  // MATURITY REACHES THROUGH EVERY CLOSED TURN; the generation floor governs only the
+  // live one. A closed turn's material has had every chance it will ever get: a finished
+  // turn was consumed by its own terminal, and a dead one (completeTurns' rule) can never
+  // be consumed at all, which is exactly the state that wedged sol-20260826-full2. The
+  // generation count alone under-reads both, because it keeps demanding two responses
+  // AFTER material that no response will ever follow.
+  const turns = completeTurns(messages);
+  const closedEnd = turns.length ? turns[turns.length - 1].end : 0;
+  return Math.max(generationFloor, closedEnd);
+}
+
 export function freshBoundary(messages: unknown[], turns: CompleteTurn[]): number {
   if (!messages.length) return 0;
   let unfinishedUser = messages.length;