pi-fold 1.0.1 → 1.0.3

package/extensions/summarizer.js

@@ -1,14 +1,22 @@
 const loadPiHost = () => import("@earendil-works/pi-coding-agent");
 
 function normalizeSummarizer(summarizer) {
-  if (summarizer === "session" || summarizer === "deterministic") return summarizer;
+  // "deterministic" was a way to select the FAILURE PATH on purpose. Every summarizer
+  // failure already falls back to the deterministic brief, so the value bought nothing a
+  // failure does not, while reading as a third generator a deployment had to choose
+  // between. The generator stays; the value that named it does not.
+  if (summarizer === "deterministic") {
+    throw new Error('summarizer has no "deterministic" value: the deterministic brief is the ' +
+      "automatic fallback whenever a summarizer fails, not a mode to select");
+  }
+  if (summarizer === "session") return summarizer;
   if (!summarizer || typeof summarizer !== "object" || Array.isArray(summarizer) ||
       typeof summarizer.provider !== "string" || !summarizer.provider ||
       typeof summarizer.model !== "string" || !summarizer.model ||
       (summarizer.effort !== undefined &&
         (typeof summarizer.effort !== "string" || !summarizer.effort))) {
     throw new Error(
-      'summarizer must be "session", "deterministic", or an object with nonempty provider and model strings',
+      'summarizer must be "session" or an object with nonempty provider and model strings',
     );
   }
   return {
@@ -18,9 +26,158 @@ function normalizeSummarizer(summarizer) {
   };
 }
 
+/**
+ * The runtime hands the generator two BOUNDED orientation slices beside the span: up to
+ * two messages and 12,000 characters either side, hashed into the fold identity. They are
+ * labelled distinctly here rather than pasted in, because a model that cannot tell the
+ * span from its surroundings briefs the surroundings. An absent slice arrives as the
+ * empty-orientation literal, and a label with "[]" under it reads as content.
+ */
+const EMPTY_ORIENTATION = "[]";
+
+function orientationBlock(label, text) {
+  return typeof text === "string" && text && text !== EMPTY_ORIENTATION
+    ? `${label}:\n${text}`
+    : `${label}: none.`;
+}
+
+/**
+ * A brief does two jobs at once, so the request says both: it summarizes the span, and it
+ * tells the agent what expanding or peeking that fold would return, which is the whole
+ * basis on which the agent decides to dig back in. Naming the concrete contents is what
+ * makes the second job possible: an abstract description of a span is not a statement of
+ * what is recoverable from it.
+ */
+/**
+ * A GROUP is briefed under one extra rule: every child gets a share.
+ *
+ * A parent is what the ladder builds when folds pile up, and its brief is the only index
+ * of what the group holds. A brief that covers the first two children richly and drops the
+ * other eight closes them: the agent has no way to know the eighth is in there, so it never
+ * expands to find out. Coverage beats depth at this rung, and the children are numbered in
+ * the payload so "every one of them" is a countable instruction rather than a wish.
+ */
+function groupCoverageRule(children) {
+  return `The span is a GROUP of ${children} folded children, numbered 1 to ${children} ` +
+    "below, each with its own brief and then its contents; folds nested inside a child " +
+    "stay folded and appear as placeholders, and a child marked collapsed shows only its " +
+    "brief. Your brief is the only index of this group, so give EVERY one of the " +
+    `${children} children a share of it: name what each one holds in the order they ` +
+    "appear. A child you leave out is a child the agent cannot know to look for. Prefer " +
+    "one concrete clause per child over a full account of the first few.";
+}
+
+/** The marker a batched answer separates its briefs with. On its own line, so a brief that
+ * happens to mention one cannot split itself. */
+const BATCH_MARKER = (ordinal) => `=== BRIEF ${ordinal} ===`;
+const BATCH_MARKER_PATTERN = /^===[ \t]*BRIEF[ \t]+(\d+)[ \t]*===[ \t]*$/;
+
+/**
+ * Many spans, one call.
+ *
+ * A commit folds a dozen spans at once and the lane used to send a dozen separate requests,
+ * two at a time, so most folds never reached a generator at all: rep 2 of sol-20260811
+ * committed 87 folds and applied 14 model briefs. Batching is not only cheaper per brief,
+ * it is what makes coverage reachable. It also buys something a single-span call cannot
+ * have: the spans of one commit are consecutive, so each one is the orientation for the
+ * next, and a brief can say this continues the work two spans back because the model can
+ * see that it does. Orientation is therefore given ONCE around the whole run rather than
+ * per span, which is both smaller and truer.
+ */
+function batchBriefRequestPrompt(request) {
+  const spans = request.spans;
+  const bodies = spans.map((span, at) => [
+    `SPAN ${at + 1} OF ${spans.length}`,
+    ...(Number.isInteger(span.children) && span.children > 1
+      ? [groupCoverageRule(span.children)]
+      : []),
+    span.sourceText,
+  ].join("\n"));
+  return [
+    `Write ${spans.length} factual briefs, one for each of the ${spans.length} numbered ` +
+    "SPANS below. Each brief covers its own span and nothing else, and each is at most " +
+    `${request.maxBriefChars} characters. A brief does two jobs at once: it summarizes what ` +
+    "its span contains, and it tells an agent what it would get back by expanding or " +
+    "peeking that fold later, so the agent can decide whether to dig back in. Once a span " +
+    "is folded its brief is the only visible trace, so name the concrete things inside it: " +
+    "files, identifiers, decisions, results, errors. Do not describe a span abstractly. " +
+    "The spans are consecutive, so where one continues the work of an earlier one you may " +
+    "say so by number; do not let that replace naming what is actually in the span. The " +
+    "BEFORE and AFTER sections are orientation only: they say where the whole run of spans " +
+    "sits in the larger conversation, and their content belongs to no brief. Use no " +
+    "preamble and no Markdown headers.\n\n" +
+    `Answer with exactly ${spans.length} sections and nothing else. Begin each section ` +
+    `with its marker alone on a line: ${BATCH_MARKER(1)} then the first brief, ` +
+    `${BATCH_MARKER(2)} then the second, and so on through ` +
+    `${BATCH_MARKER(spans.length)}.`,
+    orientationBlock("BEFORE THE SPANS (orientation only, do not brief)", request.beforeText),
+    bodies.join("\n\n"),
+    orientationBlock("AFTER THE SPANS (orientation only, do not brief)", request.afterText),
+    ...(typeof request.cure === "string" && request.cure
+      ? [`YOUR PREVIOUS ANSWER DID NOT MEET THE CRITERIA. ${request.cure}\n` +
+        `Write all ${spans.length} briefs again, each under its own marker.`]
+      : []),
+  ].join("\n\n");
+}
+
+/**
+ * Split a batched answer back into one brief per span, by marker.
+ *
+ * Ordinals rather than fold ids: an id is 24 hex characters the model has no reason to
+ * reproduce faithfully, and a single transposed character would attach a brief to the wrong
+ * span silently. A position it can count. Anything before the first marker is preamble the
+ * request asked for none of, and it is dropped rather than prepended to brief one.
+ */
+function splitBatchedBriefs(text, expected) {
+  const briefs = new Array(expected).fill("");
+  let at = null;
+  let buffer = [];
+  const flush = () => {
+    if (at !== null && at >= 0 && at < expected) briefs[at] = buffer.join("\n").trim();
+    buffer = [];
+  };
+  for (const line of String(text).split(/\r?\n/)) {
+    const marked = BATCH_MARKER_PATTERN.exec(line.trim());
+    if (marked) {
+      flush();
+      at = Number(marked[1]) - 1;
+      continue;
+    }
+    if (at !== null) buffer.push(line);
+  }
+  flush();
+  return briefs;
+}
+
+function briefRequestPrompt(request) {
+  if (Array.isArray(request.spans)) return batchBriefRequestPrompt(request);
+  const children = Number.isInteger(request.children) && request.children > 1
+    ? request.children
+    : 0;
+  return [
+    `Write a factual brief of at most ${request.maxBriefChars} characters covering the ` +
+    "SPAN TO BRIEF below, and nothing else. The brief does two jobs at once: it " +
+    "summarizes what the span contains, and it tells an agent what it would get back by " +
+    "expanding or peeking this fold later, so the agent can decide whether to dig back " +
+    "in. Once the span is folded the brief is its only visible trace, so name the " +
+    "concrete things inside it: files, identifiers, decisions, results, errors. Do not " +
+    "describe the span abstractly. The BEFORE and AFTER sections are orientation only: " +
+    "they say where the span sits in the larger conversation, and their content is not " +
+    "part of what you are briefing. Use no preamble and no Markdown headers." +
+    (children ? `\n\n${groupCoverageRule(children)}` : ""),
+    orientationBlock("BEFORE THE SPAN (orientation only, do not brief)", request.beforeText),
+    `SPAN TO BRIEF:\n${request.sourceText}`,
+    orientationBlock("AFTER THE SPAN (orientation only, do not brief)", request.afterText),
+    // A second ask, and the only reason there is one: the first answer missed a criterion
+    // this request stated, and the caller would otherwise have to cut the brief itself.
+    ...(typeof request.cure === "string" && request.cure
+      ? [`YOUR PREVIOUS ANSWER DID NOT MEET THE CRITERIA. ${request.cure}\nWrite the brief again.`]
+      : []),
+  ].join("\n\n");
+}
+
 export function createSummarizeContextSpan(summarizer = "session", loadHostModule = loadPiHost) {
   const configured = normalizeSummarizer(summarizer);
-  if (configured === "deterministic") return undefined;
   if (typeof loadHostModule !== "function") {
     throw new Error("Summarizer host-module loader must be a function");
   }
@@ -38,8 +195,14 @@ export function createSummarizeContextSpan(summarizer = "session", loadHostModul
   };
 
   return async (request, ctx) => {
-    if (typeof request?.sourceText !== "string" ||
-        !Number.isInteger(request?.maxBriefChars) || request.maxBriefChars < 1) {
+    const batch = Array.isArray(request?.spans) ? request.spans : null;
+    if (batch && (!batch.length || !batch.every((span) => typeof span?.sourceText === "string"))) {
+      throw new Error("Summarizer batch requires a nonempty spans array, each with sourceText");
+    }
+    if (!batch && typeof request?.sourceText !== "string") {
+      throw new Error("Summarizer request requires sourceText and a positive maxBriefChars integer");
+    }
+    if (!Number.isInteger(request?.maxBriefChars) || request.maxBriefChars < 1) {
       throw new Error("Summarizer request requires sourceText and a positive maxBriefChars integer");
     }
 
@@ -63,9 +226,19 @@ export function createSummarizeContextSpan(summarizer = "session", loadHostModul
       : typeof ctx?.thinkingLevel === "string" && ctx.thinkingLevel
         ? ctx.thinkingLevel
         : "none";
-    const prompt = `Write a factual brief of at most ${request.maxBriefChars} characters. ` +
-      `Use no preamble and no Markdown headers.\n\n${request.sourceText}`;
-    const completionOptions = { maxTokens: 512, signal: request.signal };
+    const prompt = briefRequestPrompt(request);
+    // NO TOKEN CEILING, deliberately (Shane 2026-08-11). A maxTokens value does not tell a
+    // model to be brief, it cuts the model off mid-answer, and on a reasoning model the
+    // reasoning is drawn from the same budget: the harder the span is to read, the less
+    // remains for the brief, until nothing remains and the response carries no text at all.
+    // The 2026-08-11 rep ran with 512 and paid for it: 22 percent of calls failed with
+    // "Summarizer returned no text", every one of them after two minutes of thinking, and
+    // brief length correlated NEGATIVELY with call duration at r = -0.575. The group
+    // payloads suffered worst, because the most interesting input provokes the most
+    // reasoning. Length is bounded by three things that can explain themselves to the
+    // model instead: the limit stated in the request, the cure that hands back an
+    // over-long brief with the complaint, and the caller's timeout for a runaway.
+    const completionOptions = { signal: request.signal };
     if (model.reasoning && effort !== "none" && effort !== "off") {
       completionOptions.reasoning = effort;
     }
@@ -84,12 +257,35 @@ export function createSummarizeContextSpan(summarizer = "session", loadHostModul
         typeof model.id !== "string" || !model.id) {
       throw new Error("Resolved summarizer model lacks provider/id attribution");
     }
-    return {
-      brief,
+    // The generator bills outside the session, so this is the ONLY place its spend is
+    // visible. Passed through when the provider reports it and omitted when it does not,
+    // never defaulted to zero: an absent number and a free call are different facts.
+    const usage = response?.usage && typeof response.usage === "object"
+      ? {
+        ...(Number.isFinite(response.usage.input) ? { input: response.usage.input } : {}),
+        ...(Number.isFinite(response.usage.output) ? { output: response.usage.output } : {}),
+        ...(Number.isFinite(response.usage.cacheRead) ? { cacheRead: response.usage.cacheRead } : {}),
+        ...(Number.isFinite(response.usage.totalTokens) ? { totalTokens: response.usage.totalTokens } : {}),
+        ...(Number.isFinite(response.usage?.cost?.total) ? { costTotal: response.usage.cost.total } : {}),
+      }
+      : null;
+    const attribution = {
       provider: model.provider,
       model: model.id,
       effort,
       toolCalls: 0,
+      ...(usage && Object.keys(usage).length ? { usage } : {}),
     };
+    // A batch answers with one brief per span, split by marker and returned positionally.
+    // A span whose marker never appeared comes back empty rather than shifted into a
+    // neighbour's place: the caller holds each brief to the same contract either way, so an
+    // empty one is a complaint about that span alone and the rest still land.
+    if (batch) {
+      return {
+        briefs: splitBatchedBriefs(brief, batch.length),
+        ...attribution,
+      };
+    }
+    return { brief, ...attribution };
   };
 }

package/package.json

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

package/extensions/lib/advisory.ts

@@ -1,309 +0,0 @@
-import { sha256Value } from "../json.ts";
-import { clone } from "./canonical.ts";
-import {
-  boundReceiptText,
-  hardFenceRatio,
-} from "./measurement.ts";
-import { ADVISORY_BUDGETS, validAdvisoryState } from "./persistence.ts";
-import type {
-  ActiveContextSnapshot,
-  ActiveContextState,
-  AdvisoryMilestone,
-  GuidanceProfile,
-  SurfacingSuggestion,
-} from "./policy.ts";
-import {
-  contextBrand,
-  DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN,
-  DEFAULT_GUIDANCE_PROFILE,
-  GUIDANCE_PROFILES,
-} from "./policy.ts";
-
-export { ADVISORY_BUDGETS };
-
-export interface AdvisorySchedule {
-  key: string;
-  rungs: Array<{ milestone: AdvisoryMilestone; threshold: number; budget: number }>;
-}
-
-export function advisoryState(state: ActiveContextState): NonNullable<ActiveContextState["advisory"]> {
-  if (state.advisory === undefined) return { highWater: 0, delivered: {} };
-  if (!validAdvisoryState(state.advisory)) {
-    throw new Error("Corrupt in-memory advisory state (no silent fallback)");
-  }
-  return clone(state.advisory);
-}
-
-export function clearArmedAdvisory(state: ActiveContextState): ActiveContextState {
-  const current = advisoryState(state);
-  if (!current.armed) return state;
-  const advisory = { ...current };
-  delete advisory.armed;
-  return { ...state, advisory };
-}
-
-export function normalizeGuidanceProfile(guidance: unknown = DEFAULT_GUIDANCE_PROFILE): GuidanceProfile {
-  if (!GUIDANCE_PROFILES.includes(guidance as GuidanceProfile)) {
-    throw new Error('guidance must be "pressure", "curation", or "minimal"');
-  }
-  return guidance as GuidanceProfile;
-}
-
-function guidanceRungs(
-  snapshot: Pick<ActiveContextSnapshot, "policy" | "contextWindow">,
-  guidance: GuidanceProfile,
-): AdvisorySchedule["rungs"] {
-  const urgent = {
-    milestone: "urgent" as const,
-    threshold: hardFenceRatio(snapshot) - 0.03,
-    budget: ADVISORY_BUDGETS.urgent,
-  };
-  if (guidance === "minimal") return [urgent];
-  return [
-    ...(guidance === "curation"
-      ? [{ milestone: "orientation" as const, threshold: 0.25, budget: ADVISORY_BUDGETS.orientation }]
-      : []),
-    { milestone: "notice" as const, threshold: 0.50, budget: ADVISORY_BUDGETS.notice },
-    { milestone: "tools" as const, threshold: snapshot.policy.toolFoldRatio - 0.04,
-      budget: ADVISORY_BUDGETS.tools },
-    { milestone: "chapters" as const, threshold: snapshot.policy.prepareRatio - 0.05,
-      budget: ADVISORY_BUDGETS.chapters },
-    urgent,
-  ];
-}
-
-export function advisorySchedule(
-  snapshot: Pick<ActiveContextSnapshot, "policy" | "contextWindow">,
-  guidance: GuidanceProfile = DEFAULT_GUIDANCE_PROFILE,
-): AdvisorySchedule {
-  const rungs = guidanceRungs(snapshot, guidance);
-  for (let index = rungs.length - 2; index >= 0; index -= 1) {
-    rungs[index].threshold = Math.min(rungs[index].threshold, rungs[index + 1].threshold - 0.02);
-  }
-  for (const rung of rungs) rung.threshold = Math.max(0, Math.min(1, rung.threshold));
-  return {
-    key: sha256Value(rungs.map(({ milestone, threshold }) => ({ milestone, threshold }))),
-    rungs,
-  };
-}
-
-/**
- * Record that an armed advisory actually REACHED the agent.
- *
- * The budget used to be spent when a milestone armed. Any automatic fold in the same
- * context pass then cleared the arm before the projection was built, so a working
- * ladder drained every milestone budget without ever emitting a word. Measured
- * 2026-08-06 on an identical pressure schedule: an idle-ladder session delivered 7
- * advisories, and a tool-using session delivered 0 while reporting notice, tools and
- * chapters each "delivered" once. All four instrumented runs were the second case.
- */
-export function recordAdvisoryDelivery(
-  state: ActiveContextState,
-  milestone: AdvisoryMilestone,
-): ActiveContextState {
-  const current = advisoryState(state);
-  const delivered = { ...current.delivered };
-  delivered[milestone] = (delivered[milestone] ?? 0) + 1;
-  const advisory = { ...current, delivered };
-  delete advisory.armed;
-  return { ...state, advisory };
-}
-
-export function updateAdvisoryMilestone(
-  currentState: ActiveContextState,
-  ratio: number,
-  schedule: AdvisorySchedule,
-  scheduleChanged: boolean,
-  scheduleKey: string,
-  /** Spend the milestone budget on DELIVERY rather than on arming. */
-  countOnDelivery = false,
-): { state: ActiveContextState; milestone: AdvisoryMilestone | null } {
-  const current = advisoryState(currentState);
-  if (scheduleChanged) {
-    return {
-      state: { ...currentState, advisory: { ...current, highWater: Math.min(1, ratio) } },
-      milestone: null,
-    };
-  }
-  let highWater = current.highWater;
-  for (let index = schedule.rungs.length - 1; index >= 0; index -= 1) {
-    const rung = schedule.rungs[index];
-    if ((current.delivered[rung.milestone] ?? 0) > 0 && ratio < 0.85 * rung.threshold) {
-      highWater = Math.min(highWater, index > 0 ? schedule.rungs[index - 1].threshold : 0);
-    }
-  }
-  let selected: AdvisorySchedule["rungs"][number] | null;
-  if (countOnDelivery) {
-    // Only ever the highest rung the current pressure has reached, so a plateau does
-    // not replay a descending cascade of stale milestones. A rung that has never been
-    // DELIVERED stays armable even after the high-water mark has passed it: the old
-    // ratchet locked out every rung that armed once and was cleared before it spoke.
-    const reached = schedule.rungs.filter((rung) => ratio >= rung.threshold).at(-1) ?? null;
-    const deliveries = reached ? current.delivered[reached.milestone] ?? 0 : 0;
-    selected = reached && deliveries < reached.budget &&
-      (highWater < reached.threshold || deliveries === 0)
-      ? reached
-      : null;
-  } else {
-    const crossed = schedule.rungs.filter((rung) =>
-      highWater < rung.threshold && ratio >= rung.threshold &&
-      (current.delivered[rung.milestone] ?? 0) < rung.budget);
-    selected = crossed.at(-1) ?? null;
-  }
-  const delivered = { ...current.delivered };
-  if (selected && !countOnDelivery) {
-    delivered[selected.milestone] = (delivered[selected.milestone] ?? 0) + 1;
-  }
-  const armed = selected
-    ? { milestone: selected.milestone, threshold: selected.threshold, scheduleKey }
-    : current.armed;
-  return {
-    state: {
-      ...currentState,
-      advisory: {
-        highWater: Math.min(1, Math.max(highWater, ratio)),
-        delivered,
-        ...(armed ? { armed } : {}),
-      },
-    },
-    milestone: selected?.milestone ?? null,
-  };
-}
-
-/**
- * Wording rule for every dosage below: report what is HAPPENING and name the actions
- * that change it. The earlier phrasing asked the agent to fold proactively, which is
- * advice it can only act on by interrupting its own task; the runtime folds either way,
- * so the honest thing to say is what it will do and what reacting buys.
- */
-function curationText(milestone: AdvisoryMilestone, percent: number, toolName: string): string {
-  if (milestone === "orientation") {
-    return "Collapsed folds are a browsable index of the work behind you, and their briefs sit in the cached " +
-      `prefix of the window, so paging that index costs almost nothing. Page it with ${toolName} ` +
-      `{"action":"status"} and expand what the current task needs with ${toolName} ` +
-      '{"action":"expand","id":"<fold-id>"}.';
-  }
-  if (milestone === "notice") {
-    return `Context is ${percent}% full, and the ladder is folding stale spans as it fills. Spans you fold ` +
-      `yourself carry your brief instead of a generated one: ${toolName} ` +
-      '{"action":"fold","marks":[{"ids":["<start>","<end>"],"brief":"<factual brief>"}]} batches several at ' +
-      `once, and ${toolName} {"action":"protect","ids":["<entry-id>"]} keeps what must stay raw out of every ` +
-      "fold. Continuing the task is the default; nothing here needs a reply.";
-  }
-  if (milestone === "tools") {
-    return "Completed read-only tool batches are what the ladder reclaims first, and their endpoint ids are in " +
-      "the live advisory. A batch it folds keeps a generated brief; one you fold keeps yours. Either way the " +
-      `exact entries come back with ${toolName} {"action":"expand","id":"<fold-id>"}, and a brief that does ` +
-      `not describe what you needed is corrected with ${toolName} ` +
-      '{"action":"rebrief","id":"<fold-id>","brief":"<factual brief>"}.';
-  }
-  return "Adjacent folds of finished work are the next thing the ladder consolidates. Handing two or more to " +
-    `${toolName} {"action":"fold","ids":["<fold-id>","<fold-id>"],"brief":"<factual brief>"} nests them under ` +
-    "a brief you wrote, leaving the oldest material deepest and still exactly recoverable; a boundary that " +
-    `came out wrong is re-cut with ${toolName} {"action":"reboundary","ids":["<start>","<end>"]}.`;
-}
-
-export function milestoneText(
-  milestone: AdvisoryMilestone,
-  sessionId: string,
-  threshold: number,
-  toolName: string,
-  brandNoun = DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN,
-  guidance: GuidanceProfile = DEFAULT_GUIDANCE_PROFILE,
-): string {
-  const percent = Math.round(threshold * 100);
-  const prefix = `[${contextBrand(brandNoun)} milestone ${milestone}; session ${sessionId.slice(0, 16)}]`;
-  if (guidance === "curation" && milestone !== "urgent") {
-    return `${prefix} ${curationText(milestone, percent, toolName)}`;
-  }
-  if (milestone === "notice") {
-    return `${prefix} Context pressure has crossed ${percent}%. Automatic folding is available. ` +
-      `Inspect candidates exactly with ${toolName} {"action":"status"}.`;
-  }
-  if (milestone === "tools") {
-    return `${prefix} The read-only tool-fold rung begins at ${percent}%. ` +
-      "Eligible completed tool batches can be folded now; current endpoint ids are in the live advisory.";
-  }
-  if (milestone === "chapters") {
-    return `${prefix} The chapter preparation rung begins at ${percent}%. ` +
-      `Closed chapters fold from the eligibleChapter endpoints in ${toolName} {"action":"status"}; ` +
-      `${toolName} {"action":"fold","ids":["<start>","<end>"],"brief":"<factual brief>"} folds one with ` +
-      "your own brief instead of a generated one.";
-  }
-  return `${prefix} The hard context fence is near. The next automatic action is a committed chapter fold ` +
-    "or the provider request is aborted before transmission.";
-}
-
-/**
- * The surfacing carrier. It rides the same ephemeral tail channel as the live
- * advisory: appended after the stable prefix, never durable, never a mutation of
- * the projection, and cleared whenever the next context event is built.
- */
-export function surfacingText(input: {
-  suggestions: readonly SurfacingSuggestion[];
-  brandNoun?: string;
-}): string | null {
-  if (!input.suggestions.length) return null;
-  const brand = contextBrand(input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN);
-  const lines = input.suggestions.map((suggestion, index) => [
-    `${index + 1}. ${suggestion.id}${suggestion.depth ? ` (depth ${suggestion.depth})` : ""}: ${suggestion.text}`,
-    ...(suggestion.alternateRoute ? [`   peek (ephemeral read): ${suggestion.alternateRoute}`] : []),
-    `   expand (durable restore): ${suggestion.route}`,
-  ].join("\n"));
-  return boundReceiptText(
-    [
-      `[${brand} suggestions] ${input.suggestions.length} collapsed span(s) look relevant to the current ` +
-        "task. Peek reads one back ephemerally at any depth; expand restores it in place, outermost first. " +
-        "Ignoring them is a valid answer.",
-      ...lines,
-    ].join("\n"),
-    2_048,
-    `[${brand} suggestions] Relevant collapsed spans are unavailable this pass.`,
-  );
-}
-
-export interface AdvisoryCuration {
-  /** Room left before the truthful fence, in tokens. */
-  headroomTokens: number | null;
-  budgetTokens: number;
-  pendingMarks: number;
-  eligibleMarks: number;
-  /** What the pending marks would free, in TOKENS. A percentage is not actionable. */
-  freedTokens: number;
-  eligibleFreedTokens: number;
-  /** The share of what the request currently pays for that no pending decision reclaims. */
-  unmarkedShare: number;
-}
-
-export function liveAdvisoryText(input: {
-  milestone: AdvisoryMilestone;
-  ratio: number;
-  toolEndpoints: string[];
-  chapterEndpoints: string[];
-  remediationCount: number;
-  brandNoun?: string;
-  curation?: AdvisoryCuration | null;
-}): string {
-  const tools = input.toolEndpoints.length
-    ? input.toolEndpoints.slice(0, 3).join(", ")
-    : "none";
-  const chapter = input.chapterEndpoints.length
-    ? `${input.chapterEndpoints[0]}..${input.chapterEndpoints.at(-1)}`
-    : "none";
-  const curation = input.curation
-    ? `headroom ${input.curation.headroomTokens ?? "unmeasured"} of ${input.curation.budgetTokens} tokens; ` +
-      `unmarked share ${Math.round(input.curation.unmarkedShare * 100)}%; ` +
-      `${input.curation.pendingMarks} pending mark(s), ${input.curation.eligibleMarks} eligible now, ` +
-      `together freeing about ${input.curation.eligibleFreedTokens} tokens of the ` +
-      `${input.curation.freedTokens} marked; `
-    : "";
-  return boundReceiptText(
-    `[${contextBrand(input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN)} advisory] ` +
-      `pressure ${Math.round(input.ratio * 100)}%; milestone ${input.milestone}; ${curation}` +
-      `eligible read-only batch endpoints: ${tools}; eligibleChapter endpoints: ${chapter}; ` +
-      `session milestone count: ${input.remediationCount}.`,
-    2_048,
-    `[${contextBrand(input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN)} advisory] ` +
-      "Live pressure details are unavailable.",
-  );
-}