pi-fold 2.0.0 → 3.1.0

package/extensions/evidence.js

@@ -562,10 +562,6 @@ function mcpServerForTool(toolName, fallback) {
     : fallback;
 }
 
-function conventionalMcpTool(toolName) {
-  return mcpServerForTool(toolName, null) !== null;
-}
-
 export function registerEvidenceIngestion(pi, {
   entryTypePrefix = DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX,
 } = {}) {
@@ -626,7 +622,7 @@ export function registerEvidenceIngestion(pi, {
       return projectEvidenceText(text, descriptor, "utf8-head", truncation ? { truncation } : undefined);
     }
 
-    if (conventionalMcpTool(toolName)) {
+    if (mcpServerForTool(toolName, null) !== null) {
       const envelope = eventEnvelope(event);
       const serialized = `${stableStringify(envelope)}\n`;
       if (utf8Bytes(serialized) <= TOOL_RESULT_PROJECTION_BYTES) return;

package/extensions/index.js

@@ -1,8 +1,17 @@
 import { registerActiveContext } from "./active-context.ts";
 import { registerEvidenceIngestion } from "./evidence.js";
 
+export {
+  applyFoldSettingsEdit,
+  loadFoldSettingsFile,
+  readFoldSettingsFile,
+  registerFoldSettings,
+  saveFoldSettingsFile,
+} from "./settings.ts";
+
 const PUBLIC_OPTIONS = Object.freeze([
-  "thresholds", "providerInputBudget", "blacklistAutoFoldTools", "guidance",
+  "thresholds", "providerInputBudget", "blacklistAutoFoldTools", "toolFoldThreshold",
+  "workingMemory", "postFoldNotice",
 ]);
 
 const GENERATOR_DELETED = "the model brief generator is deleted (2026-08-14): across 15 sealed " +
@@ -16,15 +25,20 @@ const INVERTED_AUTO_FOLD_LIST = "renamed blacklistAutoFoldTools, and the sense i
   "it meant to permit";
 
 const REFUSED_OPTIONS = Object.freeze({
+  guidance: "deleted 2026-08-23: it switched the copy that taught the agent to " +
+    "CHOOSE SPANS, and the agent does not choose spans. The runtime cuts at the frontier and " +
+    "the agent annotates what it cut, so the guidance it switched is replaced wholesale by " +
+    "the post-fold notice. That notice has its own option, postFoldNotice, which defaults " +
+    "false: the deterministic shape is what the campaign measured",
   toolName: "the deployment identity is hardwired to pi-fold: the tool is pi_fold_context",
   toolLabel: "the deployment identity is hardwired to pi-fold",
   brandNoun: "the deployment identity is hardwired to pi-fold",
   entryTypePrefix: "the deployment identity is hardwired to pi-fold: durable state lives " +
     "under pi-fold-active-context, and moving it would strand every fold already written",
   commandPrefix: "the deployment identity is hardwired to pi-fold: the commands are " +
-    "/pi-fold-context and /fold-context",
+    "/fold, /fold-editor, /fold-status and /fold-settings",
   commandNames: "the deployment identity is hardwired to pi-fold: the commands are " +
-    "/pi-fold-context and /fold-context",
+    "/fold, /fold-editor, /fold-status and /fold-settings",
   isMcpTool: "MCP tools are recognized by the mcp__server__tool naming convention. The " +
     "predicate defaulted to false, so conventionally named MCP tools were never classified " +
     "unless a host supplied one, which is a documented feature that never ran",

package/extensions/json.ts

@@ -194,8 +194,30 @@ export function isObjectRef(value: unknown): value is EvidenceRef {
     typeof sha256 === "string" && reflectApply(regexpTest, sha256Pattern, [sha256]);
 }
 
+// THE HOT PATH (issue #2, 2026-08-28). This is the most-called function in the package:
+// every mark, span, claim, eligibility and measurement pass keys its refs through it,
+// and a reporter profiling a 467KB window found the serializer under it at the top of a
+// V8 profile with the process pegged at 80 percent for forty minutes. The general
+// serializer earns its cost on arbitrary values, checking for proxies, cycles, accessors
+// and non-plain prototypes; none of that is in question for three strings off a ref.
+//
+// The output is IDENTICAL, not merely equivalent, and that is the whole design of this
+// shape: safeJson emits object keys in own-property order rather than sorted, so the
+// literal below is the same byte sequence its object form produced, and string escaping
+// is native JSON.stringify on both paths. It matters because these keys order
+// `protectionSha256`'s sort and reach `branchSha256`'s missing-digest, so a format that
+// merely round-trips would move digests that sealed sessions carry. Anything that is not
+// three strings falls through to the serializer, which owns every remaining case.
+// Measured 8.5x, 4.27us to 0.50us per call, over 2,000 refs. Gate 150 pins the identity.
 export function objectRefKey(ref: EvidenceRef): string {
-  return stableStringify({ sessionId: ref.sessionId, entryId: ref.entryId, role: ref.role });
+  const sessionId = ref.sessionId;
+  const entryId = ref.entryId;
+  const role = ref.role;
+  if (typeof sessionId === "string" && typeof entryId === "string" && typeof role === "string") {
+    return `{"sessionId":${jsonStringify(sessionId)},"entryId":${jsonStringify(entryId)},` +
+      `"role":${jsonStringify(role)}}`;
+  }
+  return stableStringify({ sessionId, entryId, role });
 }
 
 export function sameObjectIdentity(left: EvidenceRef, right: EvidenceRef): boolean {

package/extensions/lib/canonical.ts

@@ -15,6 +15,40 @@ export function bytes(value: unknown): number {
   return Buffer.byteLength(typeof value === "string" ? value : stableStringify(value), "utf8");
 }
 
+/**
+ * Does `heldText`, the serialization of the first `held` elements, stand as a prefix of
+ * `bodyText`, the serialization of the whole array?
+ *
+ * ARRAY SERIALIZATION IS PREFIX-FREE BY CONSTRUCTION, which is the whole reason this can be
+ * answered from a string the caller already has instead of by serializing a slice. `safeJson`
+ * emits `[`, then the elements separated by `,`, then `]`: no whitespace, no trailing comma.
+ * So the serialization of the first `held` elements is exactly the head of the whole one with
+ * `]` in place of the `,` that follows element `held - 1`.
+ *
+ * The two ends break that rule and are branched on rather than argued away. At `held` 0 the
+ * prefix is `[]` and there is no comma to match, so testing `"[," ` would be nonsense. At
+ * `held === length` there is no following element and the two strings are simply equal.
+ *
+ * The comma is the reason this is not a bare `startsWith`, and it is worth being exact about
+ * when it earns its place. JSON's object and string forms SELF-TERMINATE, with `}` and a
+ * closing quote, so for the message arrays this has one caller for, a bare `startsWith` would
+ * happen to agree. Numbers do not self-terminate: `[1]` is a leading substring of `[12]` and
+ * a bare `startsWith` accepts it. The separator is what makes the predicate correct for any
+ * array rather than for today's caller, and a false positive in that caller splices a stale
+ * head in front of a live tail. Gate 154 drives the numeric case for exactly this reason.
+ */
+export function serializedPrefixHolds(
+  bodyText: string,
+  heldText: string | null | undefined,
+  held: number,
+  length: number,
+): boolean {
+  if (heldText === null || heldText === undefined || length < held) return false;
+  if (held === 0) return heldText === "[]";
+  if (held === length) return bodyText === heldText;
+  return bodyText.startsWith(`${heldText.slice(0, -1)},`);
+}
+
 export function boundedUtf8(text: string, maximumBytes: number): string {
   const buffer = Buffer.from(text, "utf8");
   if (buffer.length <= maximumBytes) return text;

package/extensions/lib/curation.ts

@@ -1,71 +1,112 @@
 import { boundReceiptText } from "./measurement.ts";
+import { oneLine } from "./selection.ts";
 import {
   contextBrand,
-  CONTEXT_MARK_RESPONSE_BYTES,
   CONTEXT_RECEIPT_BLOCK_BYTES,
+  FOLD_NOTICE_BYTES,
   DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN,
   MAX_CONTEXT_RECEIPTS,
 } from "./policy.ts";
 
-export function markAwarenessText(input: {
-  held: ReadonlyArray<{ id: string; kind: string; tokens: number }>;
-  remainder: { spans: number; tokens: number; share: number; candidates: ReadonlyArray<{ id: string; tokens: number }> };
+/**
+ * THE POST-FOLD NOTICE: THE ONE MOMENT THE AGENT KNOWS SOMETHING THE RUNTIME DOES NOT.
+ *
+ * The runtime has just cut folds behind the agent, out of material the agent is still
+ * looking at. It knows the spans, the sizes and the staleness; it does not know why any
+ * of it mattered. So the notice states what was cut and asks for exactly one thing, a
+ * brief, and it states the price of answering, which is nothing: the folds it names are
+ * PENDING, so a brief written now is stored outside the projection and reaches the window
+ * only when the commit writes that placeholder for the first time.
+ *
+ * It is batched rather than continuous. One notice per cut is noise, and noise is how
+ * guidance gets ignored; this one appears when enough folds are standing unbriefed to be
+ * worth a turn's attention, and it is ephemeral, so it never accumulates.
+ */
+export function foldNoticeText(input: {
+  unbriefed: ReadonlyArray<{ id: string; kind: string; tokens: number; brief?: string }>;
+  pending: number;
   toolName: string;
   brandNoun?: string;
 }): string {
   const brand = contextBrand(input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN);
-  const { remainder } = input;
-  const held = input.held.length
-    ? input.held.map((span) => `${span.id} (${span.kind}, about ${span.tokens} tokens)`).join("; ")
-    : "none";
-  const candidates = remainder.candidates.length
-    ? remainder.candidates.map((item) => `${item.id} (about ${item.tokens} tokens)`).join("; ")
-    : "none";
-  return boundReceiptText([
-    `[${brand} marks] Held until they age out or the next fold event: ${held}.`,
-    `Unmarked remainder: ${remainder.spans} span(s), about ${remainder.tokens} tokens of stale mass, ` +
-      `${Math.round(remainder.share * 100)}% of the non-fresh window.`,
-    `Largest unmarked by reclaim value: ${candidates}.`,
-    `Mark several spans in one ${input.toolName} call: one call, and this whole picture comes back with it.`,
-  ].join("\n"), CONTEXT_MARK_RESPONSE_BYTES, `[${brand} marks] Held; the remainder is unavailable this pass.`);
+  // THE INSTRUCTION IS SEATED BEFORE THE LIST, and the list is what gives when the
+  // notice runs out of room. The first cut of this built one string with the ids in the
+  // opening line and handed the whole thing to the bound, so a seven-fold batch spent its
+  // budget on ids and lost "here is how to answer" off the end: the agent was told which
+  // folds were unbriefed and not told that briefing them was free, which is the only fact
+  // in here it cannot work out for itself. Fold count grows without limit and the
+  // instruction does not, so the instruction is fixed and the ids are the variable part.
+  const head = [
+    `[${brand} folds] ${input.unbriefed.length} of your ${input.pending} pending fold(s) carry ` +
+      "no brief yet. These spans are cut but NOT folded: every byte they cover is still in " +
+      "front of you exactly as it was, and they enter your window only when a commit " +
+      "applies them.",
+    `Give each one a sentence: ${input.toolName} {"action":"brief","id":"<fold-id>","brief":"..."}. ` +
+      "You know why the span mattered and what you will want back from it; the automatic " +
+      "brief reads the span alone and does not. Writing it now costs your window nothing, " +
+      "because the fold is not in your window yet.",
+    `Wrong boundary? ${input.toolName} {"action":"reboundary","ids":[...]} re-cuts it. ` +
+      `Should not be taken at all? ${input.toolName} {"action":"unmark","ids":["<fold-id>"]}.`,
+  ].join("\n");
+  // WHAT IT COULD NOT NAME, IT COUNTS (gate 136's law, and gate 115's shape one level
+  // out): a list that stops early and says nothing reads as a complete list.
+  // EACH ROW IDENTIFIES ITS SPAN. The pending mark carries the deterministic brief the
+  // runtime cut it with, and a notice that withholds it makes the agent guess: the
+  // dogfooded 1M session answered "I need to brief three pending folds. What are they?
+  // Likely: ..." from memory, and a wrong guess writes an accurate-sounding brief onto
+  // the wrong fold. The head is the identification; the agent adds what it cannot know.
+  const NOTICE_ROW_CHARS = 160;
+  const entries = input.unbriefed
+    .map((fold) => `${fold.id} (${fold.kind}, ~${fold.tokens} tokens)` +
+      (fold.brief ? `: ${oneLine(fold.brief, NOTICE_ROW_CHARS)}` : ""));
+  const overflowText = (seated: number) =>
+    `${input.toolName} {"action":"status"} lists the other ${input.unbriefed.length - seated}.`;
+  let seated = entries.length;
+  let list = `Unbriefed: ${entries.join("; ")}.`;
+  while (seated > 0 && Buffer.byteLength(`${head}\n${list}`, "utf8") > FOLD_NOTICE_BYTES) {
+    seated -= 1;
+    list = seated === 0
+      ? overflowText(0)
+      : `Unbriefed: ${entries.slice(0, seated).join("; ")}. ${overflowText(seated)}`;
+  }
+  return boundReceiptText(`${head}\n${list}`, FOLD_NOTICE_BYTES,
+    `[${brand} folds] Pending folds are waiting for briefs; the list is unavailable this pass.`);
 }
 
-export function contextRiderText(input: {
+/**
+ * THE WORKING MEMORY'S TABLE OF CONTENTS (Shane, 2026-08-26). One copy rides the
+ * projection, refreshed at each commit by the carrier freeze: keys only, freshest first,
+ * because the bodies live in state and are read on demand. The instruction is fixed and
+ * the key list is the variable part, exactly as the fold notice above, and a list that
+ * stops early counts what it dropped (gate 136's law). It shares FOLD_NOTICE_BYTES: both
+ * are one-glance carriers and a second bound would be a knob with no second job.
+ */
+export function memoryTocText(input: {
+  entries: ReadonlyArray<{ key: string; chars: number }>;
   toolName: string;
   brandNoun?: string;
-  pendingAgentMarks: number;
-  eligibleMarks: number;
-  freedTokens: number;
-  eligibleFreedTokens: number;
-  anchors: string[];
-  pinnedShare: number;
-  maxPinnedShare: number;
 }): string {
   const brand = contextBrand(input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN);
-  const anchors = input.anchors.length
-    ? input.anchors.slice(0, 3).join(", ")
-    : "none";
-  const pinnedPercent = Math.round(input.pinnedShare * 100);
-  const capPercent = Math.round(input.maxPinnedShare * 100);
-  return boundReceiptText(
-    [
-      `[${brand} notice] A fold commit just landed; the next one will batch every pending mark ` +
-        "into one rewrite, and marks are free until then.",
-      "Mark FINISHED units at their clean boundaries; batches beat singles: " +
-        `${input.toolName} {"action":"fold","marks":[{"ids":["<start>","<end>"],"brief":"<factual brief>"}]} ` +
-        "carries several decisions into that single rewrite, each keeping your brief instead of a " +
-        `generated one. ${input.pendingAgentMarks} of your mark(s) pending; ` +
-        `${input.eligibleMarks} mark(s) eligible now, freeing about ${input.eligibleFreedTokens} ` +
-        `of the ${input.freedTokens} marked token(s).`,
-      `Completed units ready to mark, largest first: ${anchors}.`,
-      `Pinning: ${input.toolName} {"action":"protect","ids":["<entry-id>"]} holds entries raw through ` +
-        `every fold, and {"action":"unprotect"} releases them. Pinned context is ${pinnedPercent}% of ` +
-        `the working window against a ${capPercent}% cap; at the cap, protect refuses until ` +
-        "something is released.",
-    ].join("\n"),
-    2_048,
-    `[${brand} notice] Post-commit curation details are unavailable this pass.`,
-  );
+  const head = [
+    `[${brand} memory] Your working memory holds ${input.entries.length} ` +
+      `entr${input.entries.length === 1 ? "y" : "ies"}, freshest first.`,
+    `Read any of them with ${input.toolName} {"action":"recall","keys":["<key>"]}. ` +
+      `Update an entry whose facts have changed, or add one, with ${input.toolName} ` +
+      '{"action":"remember","key":"<key>","body":"..."}; an empty body removes the entry.',
+  ].join("\n");
+  const rows = input.entries.map((entry) => `${entry.key} (${entry.chars} chars)`);
+  const overflowText = (seated: number) =>
+    `${input.toolName} {"action":"recall"} lists the other ${input.entries.length - seated}.`;
+  let seated = rows.length;
+  let list = `Entries: ${rows.join("; ")}.`;
+  while (seated > 0 && Buffer.byteLength(`${head}\n${list}`, "utf8") > FOLD_NOTICE_BYTES) {
+    seated -= 1;
+    list = seated === 0
+      ? overflowText(0)
+      : `Entries: ${rows.slice(0, seated).join("; ")}. ${overflowText(seated)}`;
+  }
+  return boundReceiptText(`${head}\n${list}`, FOLD_NOTICE_BYTES,
+    `[${brand} memory] Working memory has entries; the list is unavailable this pass.`);
 }
 
 export interface ContextReceipt {
@@ -79,8 +120,6 @@ export interface ContextReceipt {
   occupancyAfter: number | null;
   spansFolded: number;
   toolResultsFolded: number;
-  splitFolds: number;
-  splitFromChars: number;
   absorbedWedges: number;
   recovered: boolean;
   protectedBytes: number;
@@ -99,8 +138,6 @@ export function contextReceipt(input: Partial<ContextReceipt> & { kind: string;
     occupancyAfter: input.occupancyAfter ?? null,
     spansFolded: input.spansFolded ?? 0,
     toolResultsFolded: input.toolResultsFolded ?? 0,
-    splitFolds: input.splitFolds ?? 0,
-    splitFromChars: input.splitFromChars ?? 0,
     absorbedWedges: input.absorbedWedges ?? 0,
     recovered: input.recovered ?? false,
     protectedBytes: input.protectedBytes ?? 0,
@@ -131,9 +168,6 @@ export function receiptLine(receipt: ContextReceipt): string {
     `about ${receipt.freedTokens} tokens freed.`,
     occupancy,
     folded,
-    receipt.splitFolds
-      ? `A ${receipt.splitFromChars}-char span was split into ${receipt.splitFolds} bite-sized folds.`
-      : "",
     receipt.absorbedWedges
       ? `${receipt.absorbedWedges} short stale span(s) wedged between folds were absorbed into their ` +
         "later neighbour rather than left as crumbs."
@@ -142,7 +176,7 @@ export function receiptLine(receipt: ContextReceipt): string {
       ? "This ran as overflow recovery: the request would not have been transmissible, and it was rebuilt rather than dropped."
       : "",
     receipt.protectedBytes
-      ? `${receipt.protectedBytes} byte(s) stay pinned under protect; unprotect releases them when the work moves on.`
+      ? `${receipt.protectedBytes} byte(s) stay pinned; unpin releases them when the work moves on.`
       : "",
     receipt.note ?? "",
   ];
@@ -160,9 +194,8 @@ export function receiptBlockText(input: {
     `[${brand} actions] Recent automatic context actions, newest last. Exact source remains expandable.`;
   const verbs = `Correct any of it: ${input.toolName} ` +
     "{\"action\":\"expand\",\"id\":\"<fold-id>\"} restores a span in place; " +
-    "{\"action\":\"rebrief\",\"id\":\"<fold-id>\",\"brief\":\"<factual brief>\"} replaces a brief that " +
-    "does not describe what you needed; {\"action\":\"reboundary\",\"id\":\"<fold-id>\"} returns a " +
-    "mis-cut fold to raw so you can fold the span you meant.";
+    "{\"action\":\"reboundary\",\"id\":\"<fold-id>\"} returns a mis-cut fold to raw so you can " +
+    "fold the span you meant.";
   const fixed = Buffer.byteLength(header, "utf8") + Buffer.byteLength(verbs, "utf8") + 1;
   if (fixed > CONTEXT_RECEIPT_BLOCK_BYTES) {
     return `[${brand} actions] Recent automatic context actions are unavailable this pass.`;