pi-fold 2.0.0 → 3.0.0

package/extensions/index.js

@@ -1,8 +1,16 @@
 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",
 ]);
 
 const GENERATOR_DELETED = "the model brief generator is deleted (2026-08-14): across 15 sealed " +
@@ -16,15 +24,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, which is not optional: a fold the agent is never told about is one " +
+    "it can never brief",
   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/lib/curation.ts

@@ -1,71 +1,68 @@
 import { boundReceiptText } from "./measurement.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 }>;
+  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.`);
-}
-
-export function contextRiderText(input: {
-  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.`,
-  );
+  // 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.
+  const entries = input.unbriefed
+    .map((fold) => `${fold.id} (${fold.kind}, ~${fold.tokens} tokens)`);
+  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 interface ContextReceipt {
@@ -142,7 +139,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 +157,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.`;