pi-fold 0.1.0 → 1.0.0

package/extensions/lib/surfacing.ts

@@ -0,0 +1,349 @@
+import { stableStringify } from "../json.ts";
+import {
+  clone,
+  contentText,
+  messageRole,
+} from "./canonical.ts";
+import {
+  foldDepth,
+  orderedFoldTree,
+} from "./folding.ts";
+import {
+  foldInterval,
+  refsProtected,
+  toolRefsProtected,
+} from "./measurement.ts";
+import {
+  flattenFoldRefs,
+  foldBrief,
+} from "./persistence.ts";
+import {
+  SURFACING_CHAR_BUDGET,
+  SURFACING_COOLDOWN_ORDINALS,
+  SURFACING_DEPTH_WEIGHT,
+  SURFACING_LEXICAL_WEIGHT,
+  SURFACING_MAX_DEPTH,
+  SURFACING_MAX_LOG_RECORDS,
+  SURFACING_MAX_TASK_CHARS,
+  SURFACING_MAX_TEXT_CHARS,
+  SURFACING_MIN_SCORE,
+  SURFACING_OUTCOME_WINDOW_ORDINALS,
+  SURFACING_RECENCY_WEIGHT,
+  SURFACING_RECENT_TASK_SPANS,
+  SURFACING_SOURCE_ID,
+  SURFACING_TOP_K,
+} from "./policy.ts";
+import type {
+  ActiveContextSnapshot,
+  ActiveContextState,
+  SuggestionSource,
+  SuggestionSourceInput,
+  SurfacingCandidate,
+  SurfacingRecord,
+  SurfacingSuggestion,
+} from "./policy.ts";
+
+/**
+ * Deterministic, model-free surfacing. Every input is either the transcript's own
+ * ordering or the durable log: no wall clock, no randomness, no embedding call, so
+ * the same session state always produces the same slate in the same order.
+ */
+
+const SURFACING_STOPWORDS: ReadonlySet<string> = new Set([
+  "about", "after", "again", "against", "already", "also", "another", "because", "been",
+  "before", "being", "between", "both", "came", "come", "could", "does", "doing", "done",
+  "down", "during", "each", "either", "else", "even", "ever", "every", "exact", "exactly",
+  "first", "from", "have", "having", "here", "into", "just", "keep", "kept", "like", "made",
+  "make", "many", "more", "most", "much", "must", "need", "next", "none", "only", "other",
+  "over", "same", "should", "since", "some", "such", "take", "than", "that", "their", "them",
+  "then", "there", "these", "they", "this", "those", "through", "under", "until", "upon",
+  "very", "want", "were", "what", "when", "where", "which", "while", "will", "with", "would",
+  "your",
+]);
+
+export function surfacingTokens(value: string): string[] {
+  const tokens: string[] = [];
+  const seen = new Set<string>();
+  for (const raw of value.toLowerCase().split(/[^a-z0-9_]+/)) {
+    const token = raw.replace(/^_+|_+$/g, "");
+    if (token.length < 4 || SURFACING_STOPWORDS.has(token) || seen.has(token)) continue;
+    seen.add(token);
+    tokens.push(token);
+  }
+  return tokens;
+}
+
+/** The most recent user/assistant text spans: what the session is working on right now. */
+export function recentTaskText(
+  snapshot: Pick<ActiveContextSnapshot, "messages">,
+  spans = SURFACING_RECENT_TASK_SPANS,
+): string[] {
+  const collected: string[] = [];
+  let chars = 0;
+  for (let index = snapshot.messages.length - 1; index >= 0 && collected.length < spans; index -= 1) {
+    const message = snapshot.messages[index];
+    const role = messageRole(message);
+    if (role !== "user" && role !== "assistant") continue;
+    const text = contentText(message).trim();
+    if (!text) continue;
+    const bounded = text.slice(0, SURFACING_MAX_TASK_CHARS - chars);
+    if (!bounded) break;
+    collected.push(bounded);
+    chars += bounded.length;
+    if (chars >= SURFACING_MAX_TASK_CHARS) break;
+  }
+  return collected.reverse();
+}
+
+export function taskTokenSet(
+  snapshot: Pick<ActiveContextSnapshot, "messages">,
+  spans = SURFACING_RECENT_TASK_SPANS,
+): ReadonlySet<string> {
+  return new Set(surfacingTokens(recentTaskText(snapshot, spans).join(" ")));
+}
+
+/** Share of the candidate's own vocabulary the recent task text also uses. */
+export function lexicalOverlap(candidateText: string, taskTokens: ReadonlySet<string>): number {
+  const tokens = surfacingTokens(candidateText);
+  if (!tokens.length || !taskTokens.size) return 0;
+  let matched = 0;
+  for (const token of tokens) if (taskTokens.has(token)) matched += 1;
+  return matched / tokens.length;
+}
+
+export function roundedScore(value: number): number {
+  return Math.round(Math.max(0, Math.min(1, value)) * 10_000) / 10_000;
+}
+
+export function scoreSurfacingCandidate(
+  candidate: SurfacingCandidate,
+  taskTokens: ReadonlySet<string>,
+  positionCeiling: number,
+): number {
+  const lexical = lexicalOverlap(candidate.text, taskTokens);
+  const position = candidate.position ?? 0;
+  const recency = positionCeiling > 0 ? Math.max(0, Math.min(1, position / positionCeiling)) : 0;
+  const depth = Math.min(Math.max(0, candidate.depth ?? 0), SURFACING_MAX_DEPTH) / SURFACING_MAX_DEPTH;
+  return roundedScore(
+    SURFACING_LEXICAL_WEIGHT * lexical +
+    SURFACING_RECENCY_WEIGHT * recency +
+    SURFACING_DEPTH_WEIGHT * depth,
+  );
+}
+
+/** Ids suppressed by hysteresis: suggested recently, not acted on, still inside the cooldown. */
+export function cooledDownIds(
+  log: readonly SurfacingRecord[],
+  ordinal: number,
+  cooldown = SURFACING_COOLDOWN_ORDINALS,
+): Set<string> {
+  const suppressed = new Set<string>();
+  for (const record of log) {
+    if (record.outcome === "accept" || record.ordinal === ordinal) continue;
+    if (ordinal < record.ordinal + cooldown) suppressed.add(surfacingKey(record.source, record.id));
+  }
+  return suppressed;
+}
+
+export function surfacingKey(source: string, id: string): string {
+  return `${source}::${id}`;
+}
+
+export function rankSurfacingCandidates(input: {
+  candidates: readonly SurfacingCandidate[];
+  taskTokens: ReadonlySet<string>;
+  positionCeiling: number;
+  suppressed?: ReadonlySet<string>;
+  topK?: number;
+  minimumScore?: number;
+  charBudget?: number;
+}): SurfacingSuggestion[] {
+  const topK = input.topK ?? SURFACING_TOP_K;
+  const minimumScore = input.minimumScore ?? SURFACING_MIN_SCORE;
+  const charBudget = input.charBudget ?? SURFACING_CHAR_BUDGET;
+  const scored = input.candidates
+    .map((candidate) => ({
+      ...candidate,
+      text: candidate.text.replace(/\s+/g, " ").trim().slice(0, SURFACING_MAX_TEXT_CHARS),
+      score: scoreSurfacingCandidate(candidate, input.taskTokens, input.positionCeiling),
+    }))
+    .filter((candidate) => candidate.text && candidate.score >= minimumScore &&
+      !input.suppressed?.has(surfacingKey(candidate.source, candidate.id)))
+    // Ties break on source then id so the slate never depends on candidate arrival order.
+    .sort((left, right) => right.score - left.score ||
+      left.source.localeCompare(right.source) || left.id.localeCompare(right.id));
+  const selected: SurfacingSuggestion[] = [];
+  let used = 0;
+  for (const candidate of scored) {
+    if (selected.length >= topK) break;
+    const cost = candidate.text.length + candidate.id.length + candidate.route.length +
+      (candidate.alternateRoute?.length ?? 0);
+    if (used + cost > charBudget) continue;
+    used += cost;
+    selected.push(candidate);
+  }
+  return selected;
+}
+
+/** The session's monotonic transcript ordinal; recency and cooldown are measured in these. */
+export function surfacingOrdinal(snapshot: Pick<ActiveContextSnapshot, "mapped">): number {
+  return snapshot.mapped.length;
+}
+
+export function surfacingLog(state: Pick<ActiveContextState, "surfacing">): SurfacingRecord[] {
+  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 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. */
+export function resolvedSurfacingLog(
+  log: readonly SurfacingRecord[],
+  ordinal: number,
+  outcomeWindow = SURFACING_OUTCOME_WINDOW_ORDINALS,
+): SurfacingRecord[] {
+  return log.map((record) => record.outcome === "shown" && ordinal > record.ordinal + outcomeWindow
+    ? { ...record, outcome: "reject" as const }
+    : { ...record });
+}
+
+/** Marks a suggestion accepted when the agent peeks or expands it inside the outcome window. */
+export function acceptSurfacingSuggestion(
+  state: ActiveContextState,
+  id: string,
+  ordinal: number,
+  outcomeWindow = SURFACING_OUTCOME_WINDOW_ORDINALS,
+): ActiveContextState {
+  const log = surfacingLog(state);
+  let changed = false;
+  const next = log.map((record) => {
+    if (record.id !== id || record.outcome !== "shown" || ordinal > record.ordinal + outcomeWindow) return record;
+    changed = true;
+    return { ...record, outcome: "accept" as const };
+  });
+  return changed ? withSurfacingLog(state, next) : state;
+}
+
+/** The built-in source: every currently collapsed fold, nested ones included. */
+export function foldBriefCandidates(input: SuggestionSourceInput): SurfacingCandidate[] {
+  const { state, snapshot, toolName } = input;
+  const collapsed = orderedFoldTree(state, snapshot).filter((fold) => !state.expanded.includes(fold.id));
+  return collapsed.flatMap((fold) => {
+    const interval = foldInterval(fold, state, snapshot);
+    if (!interval) return [];
+    const refs = flattenFoldRefs(fold, state);
+    const blocked = fold.kind === "tool-result"
+      ? toolRefsProtected(refs, state, snapshot)
+      : refsProtected(refs, state, snapshot);
+    if (blocked) return [];
+    return [{
+      source: SURFACING_SOURCE_ID,
+      id: fold.id,
+      text: foldBrief(fold, state),
+      route: `${toolName} {"action":"expand","id":"${fold.id}"}`,
+      alternateRoute: `${toolName} {"action":"peek","id":"${fold.id}"}`,
+      position: interval.end,
+      depth: foldDepth(state, fold),
+    }];
+  });
+}
+
+export const FOLD_BRIEF_SUGGESTION_SOURCE: SuggestionSource = Object.freeze({
+  id: SURFACING_SOURCE_ID,
+  candidates: foldBriefCandidates,
+});
+
+export function collectSuggestionCandidates(
+  sources: readonly SuggestionSource[],
+  input: SuggestionSourceInput,
+): SurfacingCandidate[] {
+  return sources.flatMap((source) => {
+    let produced: unknown;
+    // One faulty external source may never take the carrier, the projection, or the
+    // ladder down with it; it simply contributes nothing this pass.
+    try { produced = source.candidates(input); }
+    catch { return []; }
+    if (!Array.isArray(produced)) return [];
+    return produced.flatMap((candidate) => validSurfacingCandidate(candidate, source.id)
+      ? [{ ...candidate, source: source.id }]
+      : []);
+  });
+}
+
+export function validSurfacingCandidate(value: unknown, sourceId: string): value is SurfacingCandidate {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const candidate = value as Partial<SurfacingCandidate>;
+  return Boolean(sourceId) && typeof candidate.id === "string" && Boolean(candidate.id) &&
+    typeof candidate.text === "string" && Boolean(candidate.text.trim()) &&
+    typeof candidate.route === "string" && Boolean(candidate.route) &&
+    (candidate.alternateRoute === undefined || typeof candidate.alternateRoute === "string") &&
+    (candidate.position === undefined || Number.isFinite(candidate.position)) &&
+    (candidate.depth === undefined || Number.isFinite(candidate.depth));
+}
+
+/**
+ * One pass of the selector: resolve outstanding outcomes, rank what is eligible now,
+ * and log what will be shown. Pure: the caller owns persistence and rendering.
+ */
+export function updateSurfacing(input: {
+  state: ActiveContextState;
+  snapshot: ActiveContextSnapshot;
+  sources: readonly SuggestionSource[];
+  toolName: string;
+}): { state: ActiveContextState; suggestions: SurfacingSuggestion[] } {
+  const { state, snapshot } = input;
+  const ordinal = surfacingOrdinal(snapshot);
+  const resolved = resolvedSurfacingLog(surfacingLog(state), ordinal);
+  const shownAtOrdinal = new Set(resolved
+    .filter((record) => record.ordinal === ordinal)
+    .map((record) => surfacingKey(record.source, record.id)));
+  const suggestions = rankSurfacingCandidates({
+    candidates: collectSuggestionCandidates(input.sources, {
+      state,
+      snapshot,
+      toolName: input.toolName,
+    }),
+    taskTokens: taskTokenSet(snapshot),
+    positionCeiling: Math.max(0, snapshot.mapped.length - 1),
+    suppressed: cooledDownIds(resolved, ordinal),
+  });
+  // Re-projecting the same ordinal re-renders the same slate; it is one showing,
+  // so it neither duplicates a log record nor trips its own cooldown.
+  const appended = suggestions.flatMap((suggestion) =>
+    shownAtOrdinal.has(surfacingKey(suggestion.source, suggestion.id))
+      ? []
+      : [{
+        source: suggestion.source,
+        id: suggestion.id,
+        score: suggestion.score,
+        ordinal,
+        outcome: "shown" as const,
+      }]);
+  const log = [...resolved, ...appended];
+  const next = withSurfacingLog(state, log);
+  const unchanged = stableStringify(state.surfacing ?? null) === stableStringify(next.surfacing ?? null);
+  return { state: unchanged ? state : next, suggestions };
+}

package/extensions/lib/tool-surface.ts

@@ -1,3 +1,12 @@
+/**
+ * Wording rule for everything in this file: describe units of WORK, never units of
+ * conversation. Text that presupposes turn-ending replies ("after the reply",
+ * "between tasks") tells a single-turn staged agent that a reply is the natural next
+ * move, and it rides in the tool surface of every request. It is the top unproven
+ * suspect for the iteration-2 phase flips, and saying the true thing instead costs
+ * nothing: the next model call that reads a result, a natural boundary in the work.
+ */
+
 type ToolHandler = (
   toolCallId: string,
   params: Record<string, unknown>,
@@ -14,14 +23,34 @@ export function buildActiveContextTool(input: {
   allowedActions: readonly string[];
   fullSurface: boolean;
   maxBriefChars: number;
+  statusDetails: readonly string[];
+  minPeekSliceBytes: number;
+  defaultPeekBytes: number;
   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 the raw source with the omitted middle stated -- at any depth, ancestors still collapsed, changing nothing. 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.`
+    : "";
+  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."
+    : "";
+  // Marking is yours, folding is the runtime's. The epoch guidance says how marks
+  // behave and stops there: there is no agent-callable commit verb to describe.
+  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."
+    : "";
+  // The standing facts about how this runtime behaves. They belong HERE, in the tool
+  // surface, because the tool surface sits in the stable prefix: it is cached from the
+  // first request and costs nothing per request thereafter, forever. The same sentences
+  // delivered as in-window carriers cost a cache break on the pass that renders them
+  // and every pass that displaces them. Anything always true is said once, here.
+  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, fold, expand, refold, or protect exact Pi active-context evidence. 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 1200-character maximum."
-      : `Use only the configured active-context actions: ${input.allowedActions.join(", ")}. 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 1200-character maximum.`,
+      ? `Page, peek, fold, expand, refold, protect, rebrief, or re-cut exact Pi active-context evidence.${peekGuidance}${correctionGuidance}${epochGuidance}${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 1200-character maximum.`
+      : `Use only the configured active-context actions: ${input.allowedActions.join(", ")}.${peekGuidance}${correctionGuidance}${epochGuidance}${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 1200-character maximum.`,
     parameters: {
       type: "object",
       additionalProperties: false,
@@ -30,6 +59,21 @@ 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 },
+            },
+          },
+        },
         brief: {
           type: "string",
           minLength: 1,
@@ -37,8 +81,13 @@ export function buildActiveContextTool(input: {
           description: "Factual fold brief; keep it at most 1000 characters to stay below the hard 1200-character limit.",
         },
         offset: { type: "integer", minimum: 0 },
+        bytes: {
+          type: "integer",
+          minimum: input.minPeekSliceBytes,
+          description: `Peek only: bytes of exact source to return, widening or narrowing the ${input.defaultPeekBytes}-byte default.`,
+        },
         limit: { type: "integer", minimum: 1, maximum: 100 },
-        detail: { type: "string", enum: ["fold_candidates"] },
+        detail: { type: "string", enum: [...input.statusDetails] },
       },
     },
     execute: input.handler,

package/extensions/lib/transcript.ts

@@ -3,6 +3,7 @@ import {
   evidenceRef,
   evidenceValue,
   isPlainRecord,
+  objectRefKey,
   sha256Text,
   stableStringify,
 } from "../json.ts";
@@ -20,6 +21,7 @@ import {
   DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX,
   DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
   DEFAULT_CONTEXT_WINDOW,
+  READ_ONLY_CONTEXT_ACTIONS_DEFAULT,
   READ_ONLY_TOOLS_DEFAULT,
 } from "./policy.ts";
 import type {
@@ -69,15 +71,29 @@ export function leadingCompactionContinuation(messages: unknown[]): CompleteTurn
   return end > 1 && terminalAssistant(messages[end - 1]) ? { start: 1, end } : null;
 }
 
+/**
+ * The exact argument surface each read-only active-context action may carry. A call
+ * outside this surface is not classified read-only, so its batch never folds.
+ */
+export const READ_ONLY_CONTEXT_ACTION_ARGUMENTS: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  status: Object.freeze(["action", "detail", "offset", "limit"]),
+  peek: Object.freeze(["action", "id"]),
+});
+
 export function isReadOnlyContextTool(
   name: string,
   args?: unknown,
   toolName = DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
   readOnlyTools: ReadonlySet<string> = READ_ONLY_TOOLS_DEFAULT,
+  readOnlyContextActions: ReadonlySet<string> = READ_ONLY_CONTEXT_ACTIONS_DEFAULT,
 ): boolean {
   if (readOnlyTools.has(name)) return true;
-  if (name !== toolName || !isPlainRecord(args) || ownValue(args, "action") !== "status") return false;
-  const allowed = new Set(["action", "offset", "limit"]);
+  if (name !== toolName || !isPlainRecord(args)) return false;
+  const action = ownValue(args, "action");
+  if (typeof action !== "string" || !readOnlyContextActions.has(action)) return false;
+  const permitted = ownValue(READ_ONLY_CONTEXT_ACTION_ARGUMENTS, action);
+  if (!Array.isArray(permitted)) return false;
+  const allowed = new Set(permitted as string[]);
   const keys = Reflect.ownKeys(args);
   for (let index = 0; index < keys.length; index += 1) {
     if (typeof keys[index] !== "string" || !allowed.has(keys[index] as string)) return false;
@@ -110,6 +126,7 @@ export function scanTurnToolBatches(
   allowIncomplete = false,
   toolName = DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
   readOnlyTools: ReadonlySet<string> = READ_ONLY_TOOLS_DEFAULT,
+  readOnlyContextActions: ReadonlySet<string> = READ_ONLY_CONTEXT_ACTIONS_DEFAULT,
 ): ScannedToolBatches | null {
   if (!Number.isSafeInteger(turn.start) || !Number.isSafeInteger(turn.end) ||
       turn.start < 0 || turn.end > messages.length || turn.start >= turn.end) return null;
@@ -146,7 +163,9 @@ export function scanTurnToolBatches(
       const id = ownValue(part, "id");
       const name = ownValue(part, "name");
       if (typeof id !== "string" || !id || typeof name !== "string" || !name ||
-          calls.has(id) || !isReadOnlyContextTool(name, ownValue(part, "arguments"), toolName, readOnlyTools)) safe = false;
+          calls.has(id) || !isReadOnlyContextTool(
+            name, ownValue(part, "arguments"), toolName, readOnlyTools, readOnlyContextActions,
+          )) safe = false;
       else calls.set(id, { id, name, assistantIndex: index });
     }
     for (let resultIndex = index + 1; resultIndex < end; resultIndex += 1) {
@@ -194,8 +213,11 @@ export function validateTurnToolBatch(
   turn: CompleteTurn,
   toolName = DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
   readOnlyTools: ReadonlySet<string> = READ_ONLY_TOOLS_DEFAULT,
+  readOnlyContextActions: ReadonlySet<string> = READ_ONLY_CONTEXT_ACTIONS_DEFAULT,
 ): ValidatedToolBatch | null {
-  const scanned = scanTurnToolBatches(messages, turn, false, toolName, readOnlyTools);
+  const scanned = scanTurnToolBatches(
+    messages, turn, false, toolName, readOnlyTools, readOnlyContextActions,
+  );
   return scanned && scanned.unsafeIndices.size === 0 ? { calls: scanned.calls } : null;
 }
 
@@ -380,6 +402,7 @@ export function mapActiveContext(input: {
   brandNoun?: string;
   entryTypePrefix?: string;
   readOnlyTools?: ReadonlySet<string>;
+  readOnlyContextActions?: ReadonlySet<string>;
   contextWindow?: number;
 }): ActiveContextSnapshot {
   const policy = Object.freeze({ ...ACTIVE_CONTEXT_POLICY, ...(input.policy ?? {}) }) as typeof ACTIVE_CONTEXT_POLICY;
@@ -473,7 +496,38 @@ export function mapActiveContext(input: {
     brandNoun: input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN,
     entryTypePrefix: input.entryTypePrefix ?? DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX,
     readOnlyTools: input.readOnlyTools ?? READ_ONLY_TOOLS_DEFAULT,
+    readOnlyContextActions: input.readOnlyContextActions ?? READ_ONLY_CONTEXT_ACTIONS_DEFAULT,
     contextWindow: reportedContextWindow ?? DEFAULT_CONTEXT_WINDOW,
     windowSource: reportedContextWindow === null ? "fallback" : "reported",
   };
 }
+
+/**
+ * The evidence boundary of the CURRENT turn: the position of the last terminal
+ * assistant message. Everything after it was gathered by the excursion still in
+ * progress, which is exactly the evidence a commit must not fold.
+ *
+ * Measured 2026-08-06 (rep 8): nineteen folds landed between the last read result and
+ * the agent's next reply, rewriting the projection from 938k to 487k chars, so the
+ * agent answered from a window where its own just-gathered evidence had become
+ * placeholders. Freshness in bytes did not catch it; the boundary is a TURN.
+ */
+export function currentTurnBoundary(snapshot: Pick<ActiveContextSnapshot, "messages">): number {
+  let boundary = -1;
+  for (let index = 0; index < snapshot.messages.length; index += 1) {
+    if (terminalAssistant(snapshot.messages[index])) boundary = index;
+  }
+  return boundary;
+}
+
+/** Every tool-result evidence key produced since that boundary. */
+export function currentTurnRefKeys(snapshot: ActiveContextSnapshot): Set<string> {
+  const boundary = currentTurnBoundary(snapshot);
+  const keys = new Set<string>();
+  for (const item of snapshot.mapped) {
+    if (item.index <= boundary || !item.ref) continue;
+    if (messageRole(item.message) !== "toolResult") continue;
+    keys.add(objectRefKey(item.ref));
+  }
+  return keys;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-fold",
-  "version": "0.1.0",
-  "description": "Lossless, agent-governed context folding for the Pi coding agent \u2014 only the oldest context changes; the fresh window stays untouched.",
+  "version": "1.0.0",
+  "description": "Lossless, agent-governed context folding for the Pi coding agent: only the oldest context changes; the fresh window stays untouched.",
   "keywords": [
     "pi-package",
     "pi",