pi-fold 1.0.2 → 1.0.4

package/extensions/evidence.js

@@ -562,8 +562,21 @@ function mcpServerForTool(toolName, fallback) {
     : fallback;
 }
 
+/**
+ * MCP tools are recognized by their name, and by nothing else.
+ *
+ * This was a host-supplied predicate whose default returned false for everything, so a
+ * conventionally named MCP tool was never classified unless a host wrote the predicate:
+ * a documented feature whose shipped state guaranteed it never ran. `mcp__server__tool`
+ * is the convention every MCP host follows, so it is the rule. A name outside the
+ * convention is deliberately not classified as MCP, and its oversized results fall to
+ * the ordinary tool-result path.
+ */
+function conventionalMcpTool(toolName) {
+  return mcpServerForTool(toolName, null) !== null;
+}
+
 export function registerEvidenceIngestion(pi, {
-  isMcpTool = () => false,
   entryTypePrefix = DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX,
 } = {}) {
   const evidenceNamespace = safeSegment(
@@ -623,7 +636,7 @@ export function registerEvidenceIngestion(pi, {
       return projectEvidenceText(text, descriptor, "utf8-head", truncation ? { truncation } : undefined);
     }
 
-    if (isMcpTool(toolName)) {
+    if (conventionalMcpTool(toolName)) {
       const envelope = eventEnvelope(event);
       const serialized = `${stableStringify(envelope)}\n`;
       if (utf8Bytes(serialized) <= TOOL_RESULT_PROJECTION_BYTES) return;

package/extensions/index.js

@@ -2,29 +2,77 @@ import { registerActiveContext } from "./active-context.ts";
 import { registerEvidenceIngestion } from "./evidence.js";
 import { createSummarizeContextSpan } from "./summarizer.js";
 
+/**
+ * THE public surface: five options, and every name outside them is refused.
+ *
+ * Unknown keys used to spread through silently, which made every deletion a no-op rather
+ * than an error and handed a deployment the opposite of what it asked for. A caller that
+ * passes a name believes it bought behavior, so a name this package does not sell is a
+ * throw with the replacement named in it.
+ */
+const PUBLIC_OPTIONS = Object.freeze([
+  "thresholds", "summarizer", "providerInputBudget", "blacklistAutoFoldTools", "guidance",
+]);
+
+/**
+ * Both spellings of the auto-fold list were ALLOW-lists, and the list runs the other way
+ * now. Forwarding one silently would be the worst possible outcome of a rename: a set of
+ * tools a deployment named to make foldable would become the exact set it barred.
+ */
+const INVERTED_AUTO_FOLD_LIST = "renamed blacklistAutoFoldTools, and the sense is INVERTED: " +
+  "every completed tool batch folds unmarked, and the list names the exceptions whose " +
+  "results must stay raw. An allow-list moved across verbatim would bar exactly the tools " +
+  "it meant to permit";
+
+/**
+ * Options that left the surface, each answered by name. Deployment identity is hardwired:
+ * this is a branded package with one deployment, not a framework a host rebrands, and a
+ * consumer that moved `entryTypePrefix` stranded its own durable folds under a namespace
+ * nothing would read back.
+ */
+const REFUSED_OPTIONS = Object.freeze({
+  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",
+  commandNames: "the deployment identity is hardwired to pi-fold: the commands are " +
+    "/pi-fold-context and /fold-context",
+  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",
+  readOnlyTools: INVERTED_AUTO_FOLD_LIST,
+  autoFoldableTools: INVERTED_AUTO_FOLD_LIST,
+  evidenceIngestion: "evidence ingestion is always on: the hook always registers, oversized " +
+    "tool results are pinned to read-only 0444 artifacts under the session directory, and " +
+    "the 512 MB session cap is a constant. Exact recovery is what the folds promise, and a " +
+    "switch that removed the anchors removed the promise",
+  providerTotalWindow: "renamed providerInputBudget, and it is ALREADY NET: pass the tokens " +
+    "the deployment may actually fill, not the total window the runtime then subtracts a " +
+    "guessed output reservation from",
+  summarizeContextSpan: "choose a brief generator with summarizer (\"session\" or " +
+    "{ provider, model, effort })",
+});
+
 export function registerPiFold(pi, options = {}, loadHostModule) {
-  const {
-    evidenceIngestion = true,
-    isMcpTool,
-    summarizer = "session",
-    summarizeContextSpan,
-    ...activeContextOptions
-  } = options;
-  if (Object.hasOwn(options, "summarizer") && summarizeContextSpan !== undefined) {
-    throw new Error("summarizer and summarizeContextSpan cannot be configured together");
-  }
-  const configuredSummarizer = summarizeContextSpan ??
-    createSummarizeContextSpan(summarizer, loadHostModule);
-  if (evidenceIngestion) {
-    registerEvidenceIngestion(pi, {
-      isMcpTool,
-      entryTypePrefix: activeContextOptions.entryTypePrefix,
-    });
+  for (const name of Object.keys(options)) {
+    if (Object.hasOwn(REFUSED_OPTIONS, name)) {
+      throw new Error(`${name} is no longer an option: ${REFUSED_OPTIONS[name]}`);
+    }
+    if (!PUBLIC_OPTIONS.includes(name)) {
+      throw new Error(`${name} is not a pi-fold option: the surface is ` +
+        `${PUBLIC_OPTIONS.join(", ")}`);
+    }
   }
-  return registerActiveContext(pi, {
-    ...activeContextOptions,
-    ...(configuredSummarizer ? { summarizeContextSpan: configuredSummarizer } : {}),
-  });
+  const { summarizer = "session", ...activeContextOptions } = options;
+  const summarizeContextSpan = createSummarizeContextSpan(summarizer, loadHostModule);
+  // Evidence first, then the runtime. Ingestion is unconditional: the artifacts are the
+  // exact-recovery anchors an oversized tool result folds against, so a deployment that
+  // turned them off kept the folds and lost what makes them lossless.
+  registerEvidenceIngestion(pi);
+  return registerActiveContext(pi, { ...activeContextOptions, summarizeContextSpan });
 }
 
 export default function piFold(pi, options) {

package/extensions/json.ts

@@ -216,8 +216,40 @@ export function evidenceValue(message: unknown): unknown {
   };
 }
 
+/**
+ * Evidence digests, kept against the message OBJECT.
+ *
+ * A message is canonicalized and hashed whole to produce its digest, and the messages
+ * this runs on are transcript entries: tool results in the tens of kilobytes. Nothing
+ * cached the result, so every reading that wanted to confirm a ref rehashed the entire
+ * message from scratch. `exactMapped` does exactly that on every lookup, and the
+ * selection, surfacing, ordering and accounting passes call it once per ref, per fold,
+ * several times a turn. Replayed against the sealed sol-20260812 rep-2 session at its
+ * 85 percent point, that single recomputation was 76 percent of all CPU, and it grows
+ * with the transcript because the transcript is what it rehashes.
+ *
+ * A WeakMap on the object is the same shape `MAPPED_BY_KEY` and `BRANCH_POSITIONS`
+ * already use one line over, and the same rule gate 113 settled for entry evidence: the
+ * session is append-only, so keep the derivation against the object and let a REPLACED
+ * object miss rather than serve a stale answer. Entries are never edited in place; they
+ * are appended, and a changed message is a different object, which misses and rehashes.
+ *
+ * What this no longer detects, stated plainly: a message mutated IN PLACE after it was
+ * first hashed now keeps its original digest. That case was already half invisible,
+ * because the ref a snapshot carries was itself computed from that same object at
+ * mapping time, so a mutation that beat the digest would have to be caught by this
+ * recomputation alone. No path in this package edits a persisted message, and the
+ * runtime clones before it stores.
+ */
+const EVIDENCE_DIGESTS = new WeakMap<object, string>();
+
 export function evidenceSha256(message: unknown): string {
-  return sha256Value(evidenceValue(message));
+  if (!message || typeof message !== "object") return sha256Value(evidenceValue(message));
+  const cached = EVIDENCE_DIGESTS.get(message);
+  if (cached !== undefined) return cached;
+  const digest = sha256Value(evidenceValue(message));
+  EVIDENCE_DIGESTS.set(message, digest);
+  return digest;
 }
 
 export function evidenceRef(sessionId: string, entryId: string, message: unknown): EvidenceRef {

package/extensions/lib/curation.ts

@@ -1,5 +1,6 @@
 import { objectRefKey } from "../json.ts";
 import {
+  boundedUtf8,
   bytes,
   messageRole,
 } from "./canonical.ts";
@@ -8,12 +9,11 @@ import {
   contextBrand,
   CONTEXT_MARK_RESPONSE_BYTES,
   CONTEXT_RECEIPT_BLOCK_BYTES,
-  CURATION_GATE_MAX_ROUNDS,
-  CURATION_OCCUPANCY_SHARE,
-  CURATION_REMINDER_SHARES,
-  CURATION_STALE_TOOL_SHARE,
   DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN,
   MAX_CONTEXT_RECEIPTS,
+  MAX_LAST_CALL_TEXT_BYTES,
+  MAX_SURFACING_LINE_BYTES,
+  MAX_THRESHOLD_NOTICE_TEXT_BYTES,
 } from "./policy.ts";
 import type {
   ActiveContextSnapshot,
@@ -67,6 +67,8 @@ export function staleToolMass(
 export interface CurationSignals {
   /** Measured provider tokens as a share of the truthful serving budget; null unmeasured. */
   occupancy: number | null;
+  /** The trigger line this occupancy is read against: thresholds.maxTarget. */
+  maxTarget: number;
   occupancyTokens: number | null;
   /** THE serving budget: one resolved value, the same one the fence and estimator use. */
   budgetTokens: number;
@@ -103,6 +105,7 @@ export function curationSignals(input: {
     : 4;
   const staleToolTokens = Math.ceil(mass.bytes / charsPerToken);
   return {
+    maxTarget: input.snapshot.thresholds.maxTarget,
     occupancy: input.usedTokens === null || input.budgetTokens <= 0
       ? null
       : input.usedTokens / input.budgetTokens,
@@ -117,50 +120,20 @@ export function curationSignals(input: {
 }
 
 /**
- * BOTH signals, never either. Occupancy alone announces a commit that has nothing to
- * fold; stale mass alone announces one in a window with room to spare.
+ * ONE signal. Occupancy of the serving budget reaches maxTarget, and a commit is due.
+ *
+ * The second signal is gone with the announcement it guarded. It existed because the
+ * trigger ANNOUNCED a commit before running one, and announcing a commit that has
+ * nothing stale to fold is a false statement in the window; the announcement was
+ * deleted when its cache cost was measured, and the AND-condition outlived its reason.
+ * A commit with nothing eligible now simply applies nothing and says so, which the
+ * reclaim floor and the eligibility accounting already report. Stale mass is still
+ * measured and still reported; it is no longer a condition on the trigger.
  */
 export function curationTriggerFires(signals: CurationSignals): boolean {
   return signals.occupancy !== null &&
     Number.isFinite(signals.occupancy) &&
-    signals.occupancy >= CURATION_OCCUPANCY_SHARE &&
-    signals.staleToolShare >= CURATION_STALE_TOOL_SHARE;
-}
-
-/**
- * The sparse reminders.
- *
- * Two per window cycle, one line each, tail-appended, and informatory. Below the
- * curation threshold NOTHING folds automatically, so the only useful thing to say
- * before the fold event is: mark as you go, and the folds will be neat when it fires.
- * `fired` is the count already spent this cycle; a commit resets it to zero.
- */
-export function dueReminderIndex(
-  occupancy: number | null,
-  fired: number,
-  shares: readonly number[] = CURATION_REMINDER_SHARES,
-): number | null {
-  if (occupancy === null || !Number.isFinite(occupancy)) return null;
-  for (let index = Math.max(0, Math.trunc(fired)); index < shares.length; index += 1) {
-    if (occupancy >= shares[index]) return index;
-  }
-  return null;
-}
-
-export function curationReminderText(input: {
-  signals: CurationSignals;
-  toolName: string;
-  brandNoun?: string;
-}): string {
-  const brand = contextBrand(input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN);
-  const occupancy = input.signals.occupancy === null
-    ? "unmeasured"
-    : `${Math.round(input.signals.occupancy * 100)}%`;
-  return `[${brand} curation] Occupancy ${occupancy} of the ${input.signals.budgetTokens}-token serving ` +
-    `budget; nothing folds until ${Math.round(CURATION_OCCUPANCY_SHARE * 100)}%. Mark SEVERAL finished ` +
-    `chapters in one call with ${input.toolName} {"action":"fold","marks":[{"ids":["<start>","<end>"],` +
-    "\"brief\":\"<factual brief>\"}]}: one call answers with everything held plus what is still " +
-    "unmarked, so the folds are neat when the fold event triggers.";
+    signals.occupancy >= signals.maxTarget;
 }
 
 /**
@@ -195,118 +168,141 @@ export function markAwarenessText(input: {
   ].join("\n"), CONTEXT_MARK_RESPONSE_BYTES, `[${brand} marks] Held; the remainder is unavailable this pass.`);
 }
 
-export type CurationProceedReason = "go" | "non-context-response" | "round-cap";
-
-export interface CurationGate {
-  openedOrdinal: number;
-  /** Context passes consumed while open. Monotonic, and capped, so a stall is impossible. */
-  roundsUsed: number;
-  /** Context-tool calls counted at the last evaluated pass. */
-  contextCallsAtLastRound: number;
-  marksAtOpen: number;
-  signals: CurationSignals;
+/**
+ * The rider: the one post-commit carrier, composed at a fold commit and delivered
+ * INSIDE the rewrite that commit already paid for, beside the receipt. Its wording
+ * follows the curation rule (report what is happening, name the actions), its numbers
+ * are decision inputs only: pending agent marks with what they free, up to three
+ * completed-unit anchors, and the pinned share against its cap. Raw occupancy,
+ * distance-to-commit and unmarked-share percentages stay OUT: they are pressure
+ * readouts, not decisions, and the pre-commit last call is where they are both
+ * accurate and free.
+ */
+export function contextRiderText(input: {
+  toolName: string;
+  brandNoun?: string;
+  pendingAgentMarks: number;
+  eligibleMarks: number;
+  freedTokens: number;
+  eligibleFreedTokens: number;
+  /** Up to three completed-unit entry ids the agent could mark next. */
+  anchors: string[];
+  pinnedShare: number;
+  maxPinnedShare: number;
+  /** The surfacing slate, already bounded and already logged; null on a silent pass. */
+  suggestion?: string | null;
+}): 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);
+  // The slate carries its OWN bound and is joined after this text is bounded, so the
+  // carrier's overhead is its bound plus the line's, and neither can eat the other: a
+  // long rider must never truncate the one sentence a suggestion consists of.
+  return joinSurfacing(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.`,
+  ), input.suggestion);
 }
 
-export interface CurationGateVerdict {
-  gate: CurationGate | null;
-  event: "opened" | "held" | "proceeded";
-  proceed: boolean;
-  proceededBy: CurationProceedReason | null;
-  roundsUsed: number;
+/** One carrier, one optional slate line, appended last and bounded on its own. */
+export function joinSurfacing(text: string, suggestion?: string | null): string {
+  if (!suggestion) return text;
+  return `${text}\n${boundedUtf8(suggestion, MAX_SURFACING_LINE_BYTES)}`;
 }
 
+/** The ruled last-call sentence (Shane, 2026-08-09 13:23), verbatim. */
+export const LAST_CALL_WORDING =
+  "Fold commit triggered, please add or edit marks, pin or unpin context based on foreseeable relevance.";
+
 /**
- * One evaluation of the gate, on one context pass.
+ * The pre-commit last-call.
  *
- * The termination argument, stated so it can be checked rather than trusted: every
- * evaluation either proceeds or increments `roundsUsed`, and `roundsUsed` proceeds
- * unconditionally once it reaches the cap. A pass whose response was not a
- * context-management call proceeds immediately, so continuing the task IS the default
- * path through the gate and no reply is ever required to make progress.
+ * It rides the commit boundary: the band-top trigger has fired, the rewrite is one
+ * round away, so this is the single moment telemetry is both accurate and free. It
+ * carries the ruled wording, the three numbers the ruling names (occupancy against the
+ * commit line, unmarked foldable mass the ladder can reach, pending marks), the verbs,
+ * and the one-round law. Never a question: continuing the task is the stated default,
+ * and the commit proceeds regardless.
  */
-export function advanceCurationGate(input: {
-  gate: CurationGate | null;
-  ordinal: number;
+export function lastCallText(input: {
   signals: CurationSignals;
-  /** Context-management tool calls observed in this session so far. */
-  contextCalls: number;
+  unmarked: { spans: number; tokens: number };
   pendingMarks: number;
-  maxRounds?: number;
-}): CurationGateVerdict {
-  const maxRounds = input.maxRounds ?? CURATION_GATE_MAX_ROUNDS;
-  if (!input.gate) {
-    return {
-      gate: {
-        openedOrdinal: input.ordinal,
-        roundsUsed: 0,
-        contextCallsAtLastRound: input.contextCalls,
-        marksAtOpen: input.pendingMarks,
-        signals: input.signals,
-      },
-      event: "opened",
-      proceed: false,
-      proceededBy: null,
-      roundsUsed: 0,
-    };
-  }
-  const roundsUsed = input.gate.roundsUsed + 1;
-  const engaged = input.contextCalls > input.gate.contextCallsAtLastRound;
-  if (engaged && roundsUsed < maxRounds) {
-    return {
-      gate: { ...input.gate, roundsUsed, contextCallsAtLastRound: input.contextCalls },
-      event: "held",
-      proceed: false,
-      proceededBy: null,
-      roundsUsed,
-    };
-  }
-  return {
-    gate: null,
-    event: "proceeded",
-    proceed: true,
-    proceededBy: engaged ? "round-cap" : "non-context-response",
-    roundsUsed,
-  };
+  /** Peek copies this exposure marked for reclaim, so the pin that vetoes one is timely. */
+  peekReclaims?: number;
+  /** The surfacing slate, already bounded and already logged; null on a silent pass. */
+  suggestion?: string | null;
+  toolName: string;
+  brandNoun?: string;
+}): string {
+  const brand = contextBrand(input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN);
+  const { signals } = input;
+  const occupancy = signals.occupancy === null ? "unmeasured" : `${Math.round(signals.occupancy * 100)}%`;
+  const peekReclaims = input.peekReclaims ?? 0;
+  return joinSurfacing(boundReceiptText([
+    `[${brand} last call] ${LAST_CALL_WORDING}`,
+    `Occupancy is ${occupancy} of the ${signals.budgetTokens}-token serving budget, at or past the ` +
+      `${Math.round(signals.maxTarget * 100)}% commit line. Unmarked foldable mass: ` +
+      `${input.unmarked.spans} span(s), about ${input.unmarked.tokens} tokens. ` +
+      `Pending marks: ${input.pendingMarks}.`,
+    // Stated only when there is one to veto: a standing sentence about zero peek copies
+    // is bytes every exposure pays for and no round ever acts on.
+    peekReclaims > 0
+      ? `Peek copies reclaimed by this commit: ${peekReclaims}. Each duplicates a fold you can peek ` +
+        "again at any time, and its placeholder names that fold, so nothing becomes unreachable. " +
+        "Pin one to keep the copy raw."
+      : "",
+    `Marks: ${input.toolName} ` +
+      "{\"action\":\"fold\",\"marks\":[{\"ids\":[\"<start>\",\"<end>\"],\"brief\":\"<factual brief>\"}]} " +
+      "adds or widens several in one call. Pins: {\"action\":\"protect\",\"ids\":[\"<entry-id>\"]} holds " +
+      "entries raw through every fold, and {\"action\":\"unprotect\"} releases them.",
+    "This is one round: the commit proceeds on the pass after your next response with whatever marks " +
+      "exist. Continuing the task is the default; nothing here needs a reply.",
+  ].filter(Boolean).join("\n"), MAX_LAST_CALL_TEXT_BYTES,
+  `[${brand} last call] ${LAST_CALL_WORDING}`), input.suggestion);
 }
 
 /**
- * The last-call notice.
- *
- * Shape rule, chosen deliberately: operational status plus available actions, with continuing
- * work as the stated default. A message shaped like a question inviting a chat-style
- * reply can make a single-turn agent emit a final answer and end its own run, so this
- * never asks anything and never implies a reply is expected.
+ * One occupancy waypoint, stated once. Informatory and quiet: below the commit line
+ * nothing folds automatically, so the only useful sentence is where the window stands
+ * and that marks and pins made now shape the eventual commit.
  */
-export function curationNoticeText(input: {
-  signals: CurationSignals;
-  roundsUsed: number;
-  maxRounds?: number;
+export function thresholdNoticeText(input: {
+  share: number;
+  occupancyTokens: number;
+  budgetTokens: number;
+  maxTarget: number;
   toolName: string;
   brandNoun?: string;
 }): string {
-  const maxRounds = input.maxRounds ?? CURATION_GATE_MAX_ROUNDS;
   const brand = contextBrand(input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN);
-  const { signals } = input;
-  const occupancy = signals.occupancy === null ? "unmeasured" : `${Math.round(signals.occupancy * 100)}%`;
-  const remaining = Math.max(0, maxRounds - input.roundsUsed);
-  return boundReceiptText([
-    `[${brand} curation] Occupancy ${occupancy} of the ${signals.budgetTokens}-token serving budget; ` +
-      `${Math.round(signals.staleToolShare * 100)}% of the window is stale tool output outside the fresh tail ` +
-      `(${signals.staleToolResults} result(s), about ${signals.staleToolTokens} tokens). ` +
-      "A commit epoch will fold that mass into briefed placeholders; " +
-      "the exact source stays expandable and nothing is lost.",
-    "Marking well is what makes this cheap: your briefs are what makes these spans findable later, and " +
-      "spans batched into one commit rewrite the prefix once instead of once per fold, so the cache survives " +
-      "and the next fold event arrives later.",
-    `Available now: ${input.toolName} ` +
-      "{\"action\":\"fold\",\"marks\":[{\"ids\":[\"<start>\",\"<end>\"],\"brief\":\"<factual brief>\"}]} " +
-      "marks SEVERAL spans in one call, and answers with everything held plus what is still unmarked; " +
-      "{\"action\":\"rebrief\",\"id\":\"<fold-id>\",\"brief\":\"<factual brief>\"} corrects an existing " +
-      "brief; {\"action\":\"reboundary\",\"id\":\"<fold-id>\"} returns a mis-cut fold to raw so you can " +
-      "re-fold it.",
-    "Continuing the task is the default: this commit proceeds on the next pass unless the next thing you do " +
-      `is a ${input.toolName} call, and it proceeds regardless after ${remaining} more curation round(s).`,
-  ].join("\n"), 2_048, `[${brand} curation] A commit epoch is due; details are unavailable this pass.`);
+  return boundReceiptText(
+    `[${brand} notice] Context occupancy crossed ${Math.round(input.share * 100)}% of the ` +
+      `${input.budgetTokens}-token serving budget (${input.occupancyTokens} tokens). Nothing folds before ` +
+      `the fold commit at ${Math.round(input.maxTarget * 100)}%; marks and pins made now shape it: ` +
+      `${input.toolName} {"action":"fold","marks":[{"ids":["<start>","<end>"],"brief":"<factual brief>"}]} ` +
+      'or {"action":"protect","ids":["<entry-id>"]}.',
+    MAX_THRESHOLD_NOTICE_TEXT_BYTES,
+    `[${brand} notice] Context occupancy crossed ${Math.round(input.share * 100)}% of the serving budget.`,
+  );
 }
 
 /** One automatic context action, reported back as status rather than as advice. */
@@ -330,6 +326,8 @@ export interface ContextReceipt {
   absorbedWedges: number;
   /** Overflow recovery, when this action rebuilt a request the provider would reject. */
   recovered: boolean;
+  /** Mass the agent's pins held out of this commit's reach, in bytes. */
+  protectedBytes: number;
   note: string | null;
 }
 
@@ -349,6 +347,7 @@ export function contextReceipt(input: Partial<ContextReceipt> & { kind: string;
     splitFromChars: input.splitFromChars ?? 0,
     absorbedWedges: input.absorbedWedges ?? 0,
     recovered: input.recovered ?? false,
+    protectedBytes: input.protectedBytes ?? 0,
     note: input.note ?? null,
   };
 }
@@ -387,6 +386,9 @@ export function receiptLine(receipt: ContextReceipt): string {
     receipt.recovered
       ? "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.note ?? "",
   ];
   return parts.filter(Boolean).join(" ");