pi-fold 4.0.0 → 4.1.0

package/extensions/lib/folding.ts

@@ -31,6 +31,7 @@ import {
   refsProtected,
 } from "./measurement.ts";
 import {
+  assertFoldForestValid,
   childFoldIds,
   clearPrepared,
   flattenFoldRefs,
@@ -908,7 +909,7 @@ export function projectActiveContext(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
 ): unknown[] {
-  validateFoldForest(state.folds);
+  assertFoldForestValid(state.folds);
   const replacements = new Map<number, { end: number; messages: unknown[] }>();
   for (const root of orderedRoots(state, snapshot)) {
     const rendered = renderFold(root.fold, state, snapshot);
@@ -921,7 +922,24 @@ export function projectActiveContext(
       output.push(...replacement.messages);
       index = replacement.end + 1;
     } else {
-      output.push(clone(snapshot.messages[index]));
+      // A PASS-THROUGH MESSAGE IS SHARED, NOT COPIED (gate 158, 2026-08-29). This used to
+      // push `clone(...)`, which was in the first commit of the runtime and never load
+      // bearing: `snapshot.messages` is ALREADY `clone(input.eventMessages)`
+      // (transcript.ts:531), against an array Pi itself structuredClones before it calls
+      // any handler, so the copy was a third generation guarding objects the host never
+      // sees. It cost 54.3ms of a 298.5ms projection, 18 percent, on a sealed 3,364
+      // message session, and it is the only remaining per-message cost of that size.
+      //
+      // What makes sharing indistinguishable from copying: NOTHING writes a field into a
+      // projected message at any depth. Every rewrite builds a fresh object and replaces
+      // an array SLOT, here in `applyToolClips` and in `withdrawConsumedEphemeralPeeks`
+      // and `carryWithdrawalIntoFreeze` one layer up, so a shared element is never the
+      // thing that gets edited. Gate 158 pins that by deep-freezing `snapshot.messages`
+      // and driving the readers against it, so a future in-place write throws in the
+      // suite instead of silently corrupting every later projection through the frozen
+      // prefix. Folded spans keep their own copies: line 796 and `renderFoldParts` still
+      // clone, because those objects are built for the projection rather than read from it.
+      output.push(snapshot.messages[index]);
       index += 1;
     }
   }

package/extensions/lib/instrumentation.ts

@@ -94,10 +94,12 @@ export type ContextEventKind =
   | "context.absorb"
   | "context.recovery"
   | "context.suspend"
+  | "context.settings"
   | "context.rollback"
   | "context.projection"
   | "context.usage"
-  | "context.prefix";
+  | "context.prefix"
+  | "context.anchor";
 
 export function prefixDivergence(
   previous: string | null,

package/extensions/lib/live-settings.ts

@@ -0,0 +1,73 @@
+// THE CHANNEL FROM /fold-settings TO THE RUNNING RUNTIME.
+//
+// THE NEED, from a live session (2026-08-29). /fold-settings wrote the file and nothing
+// else: `registerPiFold` resolves thresholds, toolFoldThreshold and the notice settings
+// ONCE at registration, so a session kept the settings pi booted with while the screen showed
+// what the person had just chosen. Shane's terminal held both at once, "Start folding at
+// 40%" on the screen over "commit at 90%" on the status line, and neither surface said
+// why. The file was the durable truth and the running session was not reading it.
+//
+// The two halves are registered independently, `registerFoldSettings(pi)` and
+// `registerPiFold(pi, settings)`, in either order, and neither returns a handle the other
+// can hold. What they do share is the HOST OBJECT, so that is the channel: the runtime
+// hangs an applier off `pi` under a registry symbol, and the settings screen looks for it
+// when a person saves an edit, which is long after both registrations have run. Late
+// binding is what makes the order irrelevant.
+//
+// A MODULE-LEVEL SLOT WAS THE OTHER CANDIDATE AND IT IS WORSE: the applier would then be
+// process-global, every gate that registers a runtime would leave one standing, and a
+// screen in one host could push settings into a runtime in another. Keeping it on the
+// host means an unregistered host simply has no applier, which is a state the screen can
+// read and state honestly rather than a state it has to guess at.
+//
+// Symbol.for, not a fresh Symbol: the global registry keys by string, so a package loaded
+// twice through different module caches (jiti in the suite, pi's own loader in the
+// deployment) still agrees on the property.
+
+import type { ActiveContextThresholds } from "./policy.ts";
+
+/**
+ * What the settings screen hands the runtime: exactly the settings FILE's shape, where an
+ * absent field means the package default rather than "leave it alone". The runtime
+ * resolves it the same way it resolves its registration options, through one code path,
+ * so a value cannot mean one thing at boot and another at an edit.
+ */
+export interface LiveFoldSettings {
+	thresholds?: ActiveContextThresholds;
+	toolFoldThreshold?: number;
+	preCommitNotice?: boolean;
+	noticeLeadShare?: number;
+}
+
+/** Refuses by throwing, exactly as registration does, and leaves the runtime untouched. */
+export type LiveSettingsApplier = (settings: LiveFoldSettings, ctx?: unknown) => void;
+
+const LIVE_SETTINGS = Symbol.for("pi-fold.live-settings");
+
+export function publishLiveSettings(host: any, apply: LiveSettingsApplier): void {
+	// A HOST THAT REFUSES THE PROPERTY IS NOT A FAILURE. Nothing about folding depends on
+	// this channel: without it the file is still written and the next start still reads
+	// it, which is the behaviour every build before this one had.
+	try { host[LIVE_SETTINGS] = apply; } catch { }
+}
+
+/** Whether an edit saved now would reach a running runtime. The settings screen states
+ *  which of the two it is instead of promising the one it cannot deliver. */
+export function liveSettingsReachable(host: any): boolean {
+	try { return typeof host?.[LIVE_SETTINGS] === "function"; }
+	catch { return false; }
+}
+
+/**
+ * Push settings into the runtime registered on this host. Returns false when there is
+ * none, and lets the applier's own refusal THROW: the caller decides what a refusal
+ * means, and swallowing it here would leave a screen believing it had applied a value
+ * the runtime rejected.
+ */
+export function applyLiveSettings(host: any, settings: LiveFoldSettings, ctx?: unknown): boolean {
+	let apply: LiveSettingsApplier | undefined;
+	try { apply = host?.[LIVE_SETTINGS]; } catch { return false; }
+	if (typeof apply !== "function") return false;
+	apply(settings, ctx);
+	return true;
+}

package/extensions/lib/persistence.ts

@@ -22,9 +22,6 @@ import {
   EXPAND_LEASE_GENERATIONS,
   MAX_EXPAND_LEASES,
   MAX_PENDING_MARKS,
-  MEMORY_BODY_CHARS,
-  MEMORY_KEY_CHARS,
-  MEMORY_KEYS_MAX,
 } from "./policy.ts";
 import type {
   ActiveContextCheckpointV2,
@@ -314,6 +311,43 @@ export function validateFoldForest(folds: ActiveFold[]): ActiveFold[] {
   return values;
 }
 
+// A FOREST THAT VALIDATED ONCE IS NOT VALIDATED AGAIN (gate 160, 2026-08-29). Profiling
+// twelve projections of a sealed 681-fold session put 51.2 percent of ALL self time on one
+// call path, and caller attribution found every serialization sample on it:
+//
+//   projectActiveContext -> validateFoldForest -> sha256Value -> stableStringify -> safeJson
+//
+// The cost is this function's closing digest-drift loop, which flattens every fold's refs
+// (for a consolidation parent, the union of all descendants) and hashes the array. The
+// projection opens with `validateFoldForest(state.folds)` on EVERY context event and throws
+// the result away: it wants the throw, not the normalized array. So it paid a full forest
+// rehash per event to re-prove something it had already proven.
+//
+// THIS WRAPPER IS THE ONLY THING THAT CHANGES. `validateFoldForest` is untouched, still
+// clones, still normalizes, still returns; the three callers that CONSUME its return value
+// (parseActiveContextState, stateFromFoldRefs, commitPreparedFold) still call it directly
+// and are unaffected. Each of those hands it a freshly built array anyway, so a memo could
+// never have hit there; the projection is the one caller that reads the same array again
+// and again, which is exactly why it is the one that pays.
+//
+// KEYED ON THE INPUT ARRAY, and sound because a state is rebuilt immutably: a changed
+// forest is always a new array, and nothing anywhere mutates a folds array in place (no
+// push, splice, sort, reverse or slot assignment on any `.folds` in extensions/). Nothing
+// is shared out, because nothing is returned, so this carries none of gate 158's aliasing
+// question.
+//
+// THE ONE COST, stated rather than hidden: a folds array mutated IN PLACE keeps its first
+// verdict and a corruption introduced that way would go unreported. Gate 160 asserts that
+// cost directly rather than pretending it away, and still requires a corrupt NEW forest to
+// raise on first sight.
+const VALIDATED_FORESTS = new WeakSet<readonly ActiveFold[]>();
+
+export function assertFoldForestValid(folds: ActiveFold[]): void {
+  if (VALIDATED_FORESTS.has(folds)) return;
+  validateFoldForest(folds);
+  VALIDATED_FORESTS.add(folds);
+}
+
 export function parseActiveContextState(
   value: unknown,
   sessionId: string,

package/extensions/lib/policy.ts

@@ -34,14 +34,37 @@ export const ACTIVE_CONTEXT_STATE_ENTRY = `${DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_P
 export const ACTIVE_CONTEXT_FOLD_RECORD_ENTRY = `${DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX}-fold-record`;
 export const PROVIDER_CONTEXT_MEASUREMENT_ENTRY = `${DEFAULT_ENTRY_NAMESPACE}-provider-context-measurement`;
 /**
- * How many unbriefed pending folds stand before the runtime says so.
+ * THE NOTICE'S DEFAULT LEAD, as a share of the serving budget below the commit trigger
+ * (Shane, 2026-08-22: "around 10% from the commit threshold"; built 2026-08-30).
  *
- * A CONSTANT, not a threshold the deployment can turn (Shane's KISS rule): it is a
- * batching size, and the only thing a knob here would buy is a deployment that never
- * speaks. Three is the smallest batch that reads as a batch rather than as a running
- * commentary on every cut.
+ * A DISTANCE, NOT A POINT. Expressed as how far BELOW maxTarget the notice speaks, so it
+ * tracks a band that moves: a deployment that drops its trigger to 0.40 gets its notice
+ * at 0.30 without touching this, where an absolute 0.70 would have put the warning after
+ * the thing it warns about. The fire point is `maxTarget - noticeLeadShare`, floored at
+ * zero, so a lead wider than the trigger means "speak from the first measurement".
+ *
+ * IT REPLACED A COUNT. Until 2026-08-30 the notice fired at UNBRIEFED_FOLDS_BEFORE_NOTICE
+ * = 3 unbriefed pending folds, which is a batching size and not an occasion: the frontier
+ * cuts continuously and ungated by occupancy, so three folds stand within a few turns of
+ * a session's start and the notice spoke a long way from any commit. The share is the
+ * occasion, and the edge latch is what batches it: one notice per approach.
  */
-export const UNBRIEFED_FOLDS_BEFORE_NOTICE = 3;
+export const DEFAULT_NOTICE_LEAD_SHARE = 0.10;
+
+/**
+ * The lead is a share of the serving budget, so it is bounded the way every other share
+ * on this surface is: strictly inside 0 and 1. Zero would mean the notice fires exactly
+ * at the trigger, which is the same pass the commit fires on and therefore never a
+ * warning; 1 and above is not a share.
+ */
+export function resolveNoticeLeadShare(value: unknown): number {
+  if (value === undefined) return DEFAULT_NOTICE_LEAD_SHARE;
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value >= 1) {
+    throw new Error("noticeLeadShare must be a share above 0 and below 1: how far below the " +
+      "commit trigger, as a fraction of the serving budget, the notice speaks");
+  }
+  return value;
+}
 
 /**
  * How many spans the frontier cuts on one projection pass.
@@ -287,15 +310,35 @@ export const MAX_CONTEXT_RECEIPTS = 3;
 export const CONTEXT_RECEIPT_BLOCK_BYTES = 900;
 
 /**
- * The post-fold notice's bound, and its own rather than the receipt block's.
+ * The pre-commit notice's bound, and its own rather than the receipt block's.
  *
- * It is larger because it carries a variable-length list the receipt does not: three
- * fixed sentences of instruction plus one entry per unbriefed fold, and the pending set
- * grows past MAX_FRONTIER_CUTS_PER_PASS whenever the frontier stages faster than the
- * agent answers. 1,200 seats the instruction and roughly eight folds; past that the list
- * gives way and states how many it could not name.
+ * It is larger because it carries a variable-length list the receipt does not: the fixed
+ * status and verb block plus one entry per staged fold, and the pending set grows past
+ * MAX_FRONTIER_CUTS_PER_PASS whenever the frontier stages faster than a commit lands.
+ * 1,200 seated the old instruction and roughly eight folds; past the bound the list gives
+ * way and states how many it could not name.
  */
 export const FOLD_NOTICE_BYTES = 2_400;
+/**
+ * WHAT ONE /fold-editor ROW SUMMARIZES, and what one page of its detail serves
+ * (2026-08-30).
+ *
+ * The editor's whole reading of a message was 300 characters of its first text block,
+ * with a detail row that sliced to 480 and therefore could never bind. Two numbers replace
+ * it because they answer two different questions. EDITOR_ROW_PREVIEW_CHARS is a SUMMARY
+ * on a line that also carries a role, an id and a badge, so it is generous enough that a
+ * reader can tell two rows apart and no more. EDITOR_DETAIL_PAGE_CHARS is a READ, served
+ * a page at a time by an injected accessor with `total` and `hasMore` travelling beside
+ * it, so depth is bounded by the reader's patience rather than by a constant: there is no
+ * ceiling on what the editor can reach, only on what it hands over at once.
+ *
+ * THIS IS A READER'S BOUND, NOT A WINDOW'S. Nothing here reaches the projection: paging
+ * an entry to its end in the editor moves no bytes and the model never learns it
+ * happened. `maxSourceChars` 200,000 is the bound on a read that DOES reach the agent.
+ */
+export const EDITOR_ROW_PREVIEW_CHARS = 240;
+export const EDITOR_DETAIL_PAGE_CHARS = 4_000;
+
 export const CONTEXT_STATUS_RESPONSE_BYTES = 24_000;
 export const MAX_UNMARKED_CANDIDATES = 3;
 

package/extensions/lib/selection.ts

@@ -1,4 +1,6 @@
 import type { EvidenceRef } from "../json.ts";
+import { boundedSubject, oneLine, seatSubjects, toolClipHead } from "./brief-text.ts";
+export { oneLine, seatSubjects, toolClipHead };
 import {
   denseOwnArrayValues,
   objectRefKey,
@@ -397,13 +399,6 @@ function assistantNoteText(message: unknown): string {
 // "content continues in the exact source", and a reader never mistakes a cut
 // value for a complete one. oneLine collapses whitespace then delegates;
 // factualValue sanitizes then delegates through oneLine. No other site slices.
-function boundedSubject(text: string, budget: number): string {
-  if (text.length <= budget) return text;
-  let kept = text.slice(0, Math.max(0, budget - 3)).trimEnd();
-  const finalCode = kept.charCodeAt(kept.length - 1);
-  if (finalCode >= 0xd800 && finalCode <= 0xdbff) kept = kept.slice(0, -1);
-  return `${kept}...`;
-}
 
 export function deterministicConsolidationBrief(
   candidate: FoldCandidate,
@@ -467,29 +462,16 @@ export function deterministicConsolidationBrief(
   const noteCount = notes.length;
   const subjects = [...childSubjects, ...notes];
   if (!subjects.length) return "Grouped completed context covering no readable folds.";
-  const separator = " | ";
   const lead = noteCount
     ? `Grouped completed context covering ${foldCount} folds and ${noteCount} agent notes: `
     : `Grouped completed context covering ${subjects.length} folds: `;
-  const room = ACTIVE_CONTEXT_POLICY.maxBriefChars - lead.length - 1;
-  const named = Math.max(1, Math.min(subjects.length,
-    Math.floor((room + separator.length) / (MIN_SUBJECT_CHARS + separator.length))));
-  const omitted = subjects.length - named;
-  // With notes in the division, what the slice drops may be a note rather than
-  // a fold, so the tail only claims folds when folds are all it holds.
-  const tail = omitted ? `${separator}${omitted} more ${noteCount ? "in this group" : "folds in this group"}` : "";
-  const budget = room - tail.length - separator.length * (named - 1);
-  const order = subjects.slice(0, named).map((text, index) => ({ text, index })).sort((a, b) =>
-    a.text.length - b.text.length || a.index - b.index);
-  const bounded = new Array<string>(named);
-  let left = budget;
-  for (let taken = 0; taken < order.length; taken += 1) {
-    const owed = Math.max(1, Math.floor(left / (order.length - taken)));
-    const kept = boundedSubject(order[taken].text, owed);
-    bounded[order[taken].index] = kept;
-    left -= kept.length;
-  }
-  return `${lead}${bounded.join(separator)}${tail}.`.replace(/\s+/g, " ").trim();
+  // With notes in the division, what the count-slice drops may be a note rather
+  // than a fold, so the tail only claims folds when folds are all it holds.
+  return seatSubjects(subjects, lead, {
+    total: ACTIVE_CONTEXT_POLICY.maxBriefChars,
+    minSubjectChars: MIN_SUBJECT_CHARS,
+    omittedNoun: noteCount ? "in this group" : "folds in this group",
+  });
 }
 
 export const ALL_FOLD_KINDS: ReadonlySet<FoldKind> =
@@ -1106,23 +1088,6 @@ export function manualFoldCandidate(
 // 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);
-}
 
 export function deterministicChapterBrief(
   refs: EvidenceRef[],

package/extensions/lib/tool-surface.ts

@@ -7,7 +7,6 @@
  * nothing: the next model call that reads a result, a natural boundary in the work.
  */
 
-
 type ToolHandler = (
   toolCallId: string,
   params: Record<string, unknown>,

package/extensions/lib/transcript.ts

@@ -31,6 +31,49 @@ import type {
   MappedMessage,
 } from "./policy.ts";
 
+/**
+ * ONE MESSAGE, AS THE TEXT A PERSON WOULD READ (2026-08-30).
+ *
+ * WHAT THIS REPLACED. `/fold-editor` built its entry previews inline, and the reading was
+ * `content.find((part) => part.type === "text")` sliced to 300 characters. So a message
+ * whose first block is not text previewed as the empty string, a tool result carrying its
+ * body in a later block previewed as its first block alone, and everything past 300
+ * characters was unreachable from the editor at any depth: the detail row sliced to 480,
+ * a bound the 300-character preview could never reach, so the deeper number was dead.
+ * Shane, 2026-08-30: "the amount of detail we can expand out to is a bit limited".
+ *
+ * EVERY BLOCK IS ACCOUNTED FOR, and the ones that are not text are NAMED rather than
+ * dropped. A window a person is auditing may not show them an empty row where an image or
+ * a tool call stands; naming it is how the row stays honest about what it could not
+ * render. The result is UNBOUNDED here on purpose. Bounding belongs to the caller, which
+ * knows whether it is drawing a one-line row or serving a paged read, and a cut applied
+ * here would be a cut nobody could state.
+ */
+export function entryText(message: unknown): string {
+  const content = ownValue(message, "content");
+  if (typeof content === "string") return content;
+  const parts = denseOwnArrayValues(content);
+  if (!parts) return "";
+  const out: string[] = [];
+  for (const part of parts) {
+    if (typeof part === "string") { out.push(part); continue; }
+    const type = ownValue(part, "type");
+    const text = ownValue(part, "text");
+    if (typeof text === "string" && text) { out.push(text); continue; }
+    if (type === "toolCall") {
+      const name = ownValue(part, "name");
+      // The ARGUMENTS are the content of a tool call, and they are what a person auditing
+      // a window needs to see: the call is why the result below it exists.
+      const args = ownValue(part, "arguments");
+      out.push(`[calls ${typeof name === "string" ? name : "a tool"}` +
+        `${args === undefined ? "" : ` ${stableStringify(args)}`}]`);
+      continue;
+    }
+    out.push(`[${typeof type === "string" && type ? type : "content"}]`);
+  }
+  return out.join("\n");
+}
+
 export function terminalAssistant(message: unknown): boolean {
   if (messageRole(message) !== "assistant") return false;
   const stop = ownValue(message, "stopReason");