pi-fold 0.1.0 → 0.1.1

package/README.md

@@ -1,10 +1,12 @@
 # pi-fold
 
-pi-fold provides lossless, agent-governed context folding for Pi. It changes only the oldest eligible context while leaving the fresh window untouched.
+pi-fold lets a Pi agent govern its own context window. The registered `active_context` tool gives the session's agent seven actions over its transcript: `status`, `peek`, `fold`, `expand`, `refold`, `protect`, and `unprotect`. Folding is lossless: a fold replaces a stale span with a short brief while keeping SHA-256-verified references to every original entry, so any fold can be expanded back to its exact source. Advisory milestones tell the agent what is eligible as measured context pressure rises; the agent decides what stays hot, what folds, and what is pinned.
+
+When the agent does not act, an autonomous ladder manages the window the same lossless way: it folds completed read-only tool batches, folds structurally closed chapters, and consolidates existing folds into a hierarchy only past explicit thresholds. Only the oldest eligible context changes; the fresh window is never touched.
 
 ![pi-fold folding a live session](https://raw.githubusercontent.com/shaneconner/pi-fold/main/docs/demo.gif)
 
-*A live session at 5.5× speed: the autonomous ladder folds a completed read batch mid-conversation — no command issued — and `/context` reports the fold.*
+*A live session at 5.5× speed: the autonomous ladder folds a completed read batch mid-conversation, no command issued, and `/context` reports the fold.*
 
 ## Status
 
@@ -22,10 +24,64 @@ pi install npm:pi-fold
 
 pi-fold maps canonical session entries into a fold lattice. A fold replaces an eligible stale span with a short placeholder while retaining ordered references to the exact source entries. Expansion checks the stored SHA-256 identities before restoring that source.
 
-An autonomous ladder first folds completed read-only tool batches, then refolds or consolidates existing folds, and finally folds structurally closed chapters. Cadence and fresh-tail rules prevent repeated or premature folding. Chapter briefs are generated by the session's model by default, using one request per fold with a bounded input span, bounded output, and no tool calls. Every summarizer failure falls back to a deterministic brief; set `summarizer: "deterministic"` to disable model calls entirely. The default spends provider tokens, as native compaction does. Advisory milestones describe eligible actions as measured context pressure rises, and the provider-window fence blocks an unsafe request if no lossless fold can make room.
+Collapsed folds double as a browsable index of earlier work. The briefs sit in the stable prefix of the window, which providers typically serve from cache, so the agent can page through them at little cost, note which spans matter to its current task, expand those, and leave the rest folded.
+
+The briefs are the index, and reading a fold is not the same as committing to it. `peek` is the ephemeral read: it returns one fold's exact SHA-256-verified source as a tool result, at any depth and with the ancestors still collapsed, without touching the projection; the content lands in the fresh window like any other read and can later fold away as a completed read batch. `expand` is the commitment, restoring that source in place until the fold is refolded, and `status` with `detail: "tree"` lists every fold, nested ones included, in transcript order with its depth and parent. Expansion is outside-in, level by level: expanding a parent reveals its children's briefs, each expandable in turn, and collapsing a parent re-collapses its descendants.
+
+The agent's own actions come first. Through the context tool it folds any structurally closed span it judges stale, folds completed tool batches, consolidates two or more adjacent folds into a deeper one at any time, expands any fold whose detail is needed again, and protects entries that must stay raw. None of the ladder's pressure or width thresholds apply to these actions.
+
+Every fold, agent-made or automatic, obeys the same structural rules. Folds form a DAG whose leaves are the exact session entries, and every fold record keeps ordered references down to those leaves, so expansion at any depth restores the originals after SHA-256 verification. Folds nest rather than partially overlap. Chapter folds align to closed user/assistant/tool-batch units, consolidations take two or more adjacent folds, and protected or fresh evidence never folds.
+
+The autonomous ladder is deliberately more conservative than the agent. It folds only completed read-only tool batches and structurally closed chapters, absorbs only the tool-result folds inside a chapter's own span, and creates folds of folds only past explicit thresholds, taking adjacent folds oldest first. Those thresholds are more than ten visible collapsed folds, which keeps the brief index tidy long before pressure matters, or total measured context usage (all of it, not just briefs) reaching 85% of the provider window, at which point consolidation squeezes existing folds to reclaim room. Briefs themselves are bounded at 1,200 characters each, so the visible index normally costs about 1% of the window. Cadence and fresh-tail rules prevent repeated or premature automatic folding.
+
+Chapter briefs are generated by the session's model by default, using one request per fold with a bounded input span, bounded output, and no tool calls. Every summarizer failure falls back to a deterministic brief; set `summarizer: "deterministic"` to disable model calls entirely. The default spends provider tokens, as native compaction does. A cheaper model from the same provider is the recommended summarizer: for example, a session on GPT 5.6 Sol can delegate fold briefs to GPT 5.6 Luna at medium effort with `summarizer: { provider: "openai", model: "gpt-5.6-luna", effort: "medium" }`, using the provider id from your Pi model registry. Advisory milestones describe eligible actions as measured context pressure rises, and the provider-window fence blocks an unsafe request if no lossless fold can make room.
+
+Milestone wording comes in three guidance profiles over the same rungs, thresholds, and per-session budgets. The default `"pressure"` frames each milestone as rising context pressure; `"curation"` frames the same milestones as curating context for the current task and adds one early orientation advisory, at 25% of the window, that introduces the fold index; `"minimal"` delivers only the urgent fence advisory.
 
 By default, evidence ingestion writes read-only artifact files under the session directory's `pi-fold-evidence/`, sets them to mode `0444`, and enforces a 512 MB session cap. These immutable files provide exact-recovery anchors for oversized tool results. Set `evidenceIngestion: false` to disable the hook and all evidence writes.
 
+## Surfacing relevant folds
+
+Paging the fold index is something the agent can do at any moment. Surfacing is that same act performed on its behalf when it did not think to look. As a session grows, the material most worth reopening tends to sit in the oldest and deepest folds, which are exactly the ones the agent stops seeing. pi-fold scores every collapsed fold against what the session is working on right now and hands the best two or three back with the fold id and both affordances, so the agent can peek one ephemerally, expand it in place, or dismiss the whole slate and carry on. The judgment stays with the agent; the mechanism only puts the option where it can be acted on.
+
+The selector is deterministic and model free: no extra provider call, no embeddings, no randomness, no wall clock. A fold scores on the lexical overlap between its brief and the most recent user and assistant text, plus a small recency component read from transcript position and a small bonus for depth (a deeply nested fold is otherwise invisible). Those structural components alone can never clear the threshold, so a suggestion always rests on evidence that the span matches the task in hand, and when nothing clears the threshold, nothing is shown at all. A fold that was suggested and left alone is suppressed for a cooldown; a fold that is currently expanded or protected is never suggested.
+
+Suggestions ride the same ephemeral channel as the advisory milestones: appended at the tail of the window, after the stable prefix, so no cached prefix is invalidated and nothing durable is written to the transcript. They never share an advisory with urgent fence text, where the only useful next action is the fold that keeps the request transmissible.
+
+Every suggestion shown is recorded in durable session state with its source, item id, score and transcript ordinal. The record resolves to `accept` when the agent peeks or expands that item within a short window of turns, and to `reject` otherwise. `active_context {"action":"status"}` returns the live slate and the whole log under `automatic.surfacing`. Set `surfacing: false` to register no sources and emit nothing. Slate size, threshold, cooldown and character budget are internal constants rather than options: they are the knobs the accept and reject record exists to settle.
+
+### Suggestion sources
+
+pi-fold owns the carrier, not the content. Any extension can put its own items into the same slate, with the same ranking, the same budget, and the same accept and reject log. The built-in fold-brief source is registered through that identical interface.
+
+```js
+registerPiFold(pi, {
+  setSuggestionSourceRegistrar: (register) => {
+    const memory = register({
+      id: "my-memory",
+      candidates: ({ state, snapshot, toolName }) => [
+        {
+          id: "note-42",
+          text: "Durable note the current task may want back.",
+          route: "recall {\"address\":\"note-42\"}",
+        },
+      ],
+    });
+    // memory.accepted("note-42") when the agent acts on it; memory.unregister() to withdraw.
+  },
+});
+```
+
+A candidate needs an id, the text that is scored and shown, and a route string naming the action that retrieves it. Optional `position` (a transcript ordinal, where higher is more recent) and `depth` feed the recency and depth components. A source that throws, or an item that is malformed, costs its own items and nothing else: the carrier, the projection, and the ladder are never at risk.
+
+## Relation to prior work
+
+pi-fold combines two recent lines of work in one mechanism. Lossless hierarchical compaction, exemplified by LCM ([arXiv:2605.04050](https://arxiv.org/abs/2605.04050)) with an interactive walkthrough at [losslesscontext.ai](https://www.losslesscontext.ai/), builds a summary DAG over older messages with lossless pointers to every original, but the system alone decides when to compact. Self-GC ([arXiv:2607.00692](https://arxiv.org/abs/2607.00692)) treats context as indexed, recoverable objects with fold, mask, and prune actions, proposed by a side-channel planner under harness enforcement. In pi-fold the session agent itself holds the verbs, in-band: it can fold, expand, refold, protect, and consolidate on its own judgment, and the autonomous ladder is the fallback; a session that never touches the tool degrades gracefully into lossless hierarchical compaction.
+
+Context-Folding ([arXiv:2510.11967](https://arxiv.org/abs/2510.11967), ByteDance Seed) has the agent branch into a sub-trajectory and fold it on completion, with the behavior shaped by reinforcement learning; the fold keeps a summary of the outcome rather than a lossless path back. MemGPT and its successor [Letta](https://github.com/letta-ai/letta) are the canonical agent-held memory-verb systems: the agent edits its own memory blocks and archives while the window pages against external stores. Two things separate pi-fold from that line. First, what is governed: Letta manages traffic between the window and outside storage, and when its message queue overflows the in-window record becomes a lossy recursive summary; pi-fold restructures the transcript in place. Second, recovery: theirs is retrieval, a search that re-ingests whatever comes back as new tokens; ours is expansion, which restores the exact folded entries after SHA-256 verification. Further inspirations include Hindsight and Hermes.
+
+The design also pairs with Pi's session trees: a fold's collapsed-or-expanded state is a natural unit for curating exactly which context a subagent or workflow leg inherits.
+
 ## Configuration
 
 The package entry calls `registerPiFold(pi)` with the defaults below. Hosts that call the named `registerPiFold` export directly may pass an options object. Replacement lists and sets replace the defaults; they are not additive.
@@ -40,8 +96,11 @@ The package entry calls `registerPiFold(pi)` with the defaults below. Hosts that
 | `commandNames` | `undefined` | Optional full-name overrides for the effective defaults `{ status: "context", fold: "fold-context" }`. Both names must be distinct kebab-case strings; supplied values take precedence over `commandPrefix`. |
 | `summarizer` | `"session"` | Brief generator: the live session model, `"deterministic"` for no model calls, or `{ provider, model, effort? }` resolved through Pi's model registry. Cannot be combined with `summarizeContextSpan`. |
 | `summarizeContextSpan` | `undefined` | Optional async brief generator. Results must include a useful bounded brief, provider/model/effort attribution, and `toolCalls: 0`; failure uses the deterministic brief. |
+| `guidance` | `"pressure"` | Advisory wording profile: `"pressure"`, `"curation"` for task-relevance self-curation plus an early orientation advisory, or `"minimal"` for the urgent advisory alone. Rungs, thresholds, and budgets are the same in every profile. |
 | `setProjectionProvider` | `undefined` | Optional host callback that receives the [projection-candidate provider](#projection-candidate-records). Normal Pi context events do not require it. |
-| `toolActions` | all six actions | Replacement allowlist drawn from `status`, `fold`, `expand`, `refold`, `protect`, and `unprotect`. |
+| `surfacing` | `true` | Score collapsed folds against the recent task context and offer the best few back through the ephemeral tail channel. Set `false` to register no suggestion sources and emit nothing. |
+| `setSuggestionSourceRegistrar` | `undefined` | Optional host callback that receives the [suggestion source](#suggestion-sources) registration function. |
+| `toolActions` | all seven actions | Replacement allowlist drawn from `status`, `peek`, `fold`, `expand`, `refold`, `protect`, and `unprotect`. |
 | `blockingTools` | `["Agent"]` | Replacement list of tool names that trigger one opportunistic stale-tool fold before the call. Use `[]` to disable it. |
 | `readOnlyTools` | `new Set(["read", "grep", "find", "ls"])` | Replacement set of tool names whose completed batches may fold automatically. Defaults to Pi's built-in read-only tools. Pass a `ReadonlySet<string>`. |
 | `isMcpTool` | `() => false` | Synchronous predicate enabling evidence ingestion for oversized structured MCP results. Names shaped as `mcp__<server>__<tool>` project the actual server; other names use the neutral namespace derived from `entryTypePrefix`. |

package/extensions/active-context.ts

@@ -10,6 +10,8 @@ import {
   clearArmedAdvisory,
   liveAdvisoryText,
   milestoneText,
+  normalizeGuidanceProfile,
+  surfacingText,
   updateAdvisoryMilestone,
 } from "./lib/advisory.ts";
 import {
@@ -25,6 +27,8 @@ import {
   commitPreparedFold,
   encodedFoldSource,
   foldCandidatesDetail,
+  foldTreeDetail,
+  peekFoldSource,
   prepareFold,
   preparedFoldError,
   projectActiveContext,
@@ -85,6 +89,7 @@ import {
   DEFAULT_ACTIVE_CONTEXT_TOOL_LABEL,
   DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
   DEFAULT_CONTEXT_WINDOW,
+  DEFAULT_SURFACING_ENABLED,
   entryTypeNamespace,
   READ_ONLY_TOOLS_DEFAULT,
   USER_RESCUE_MAX_SOURCE_CHARS,
@@ -97,7 +102,10 @@ import type {
   FoldCandidate,
   FoldKind,
   FoldRecordEntry,
+  GuidanceProfile,
   PreparedFold,
+  SuggestionSource,
+  SurfacingSuggestion,
 } from "./lib/policy.ts";
 import {
   automaticToolBrief,
@@ -107,6 +115,12 @@ import {
   selectAutomaticToolBatch,
   selectAutomaticToolForRung,
 } from "./lib/selection.ts";
+import {
+  acceptSurfacingSuggestion,
+  FOLD_BRIEF_SUGGESTION_SOURCE,
+  surfacingOrdinal,
+  updateSurfacing,
+} from "./lib/surfacing.ts";
 import { buildActiveContextCommands, buildActiveContextTool } from "./lib/tool-surface.ts";
 import { mapActiveContext } from "./lib/transcript.ts";
 
@@ -118,11 +132,22 @@ export * from "./lib/measurement.ts";
 export * from "./lib/persistence.ts";
 export * from "./lib/policy.ts";
 export * from "./lib/selection.ts";
+export * from "./lib/surfacing.ts";
 export * from "./lib/transcript.ts";
 
+/** Handle a suggestion source keeps: withdraw itself, and report that its item was acted on. */
+export interface SuggestionSourceHandle {
+  unregister: () => void;
+  accepted: (id: string) => void;
+}
+
+export type SuggestionSourceRegistrar = (source: SuggestionSource) => SuggestionSourceHandle;
+
 export function registerActiveContext(pi: any, options: {
   summarizeContextSpan?: (request: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>;
   setProjectionProvider?: (provider: (ctx: any) => Array<Record<string, unknown>>) => void;
+  setSuggestionSourceRegistrar?: (register: SuggestionSourceRegistrar) => void;
+  surfacing?: boolean;
   toolActions?: readonly ActiveContextToolAction[];
   toolName?: string;
   toolLabel?: string;
@@ -132,13 +157,22 @@ export function registerActiveContext(pi: any, options: {
   commandNames?: { status?: string; fold?: string };
   readOnlyTools?: ReadonlySet<string>;
   blockingTools?: readonly string[];
-}): { projectionCandidates: (ctx: any) => Array<Record<string, unknown>> } {
+  guidance?: GuidanceProfile;
+}): {
+  projectionCandidates: (ctx: any) => Array<Record<string, unknown>>;
+  registerSuggestionSource: SuggestionSourceRegistrar;
+} {
   const toolName = options.toolName ?? DEFAULT_ACTIVE_CONTEXT_TOOL_NAME;
   const toolLabel = options.toolLabel ?? DEFAULT_ACTIVE_CONTEXT_TOOL_LABEL;
   const brandNoun = options.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN;
   const entryTypePrefix = options.entryTypePrefix ?? DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX;
   const commandPrefix = options.commandPrefix ?? "";
   const readOnlyTools = options.readOnlyTools ?? READ_ONLY_TOOLS_DEFAULT;
+  const guidance = normalizeGuidanceProfile(options.guidance);
+  if (options.surfacing !== undefined && typeof options.surfacing !== "boolean") {
+    throw new Error("surfacing must be a boolean");
+  }
+  const surfacingEnabled = options.surfacing ?? DEFAULT_SURFACING_ENABLED;
   if (!toolName || !toolLabel || !brandNoun || !entryTypePrefix || typeof commandPrefix !== "string" ||
       (commandPrefix && !/^[a-z0-9-]+$/.test(commandPrefix)) ||
       [...readOnlyTools].some((name) => typeof name !== "string" || !name)) {
@@ -166,6 +200,7 @@ export function registerActiveContext(pi: any, options: {
   const foldRecordEntryType = `${entryTypePrefix}-fold-record`;
   const milestoneProjectionType = `${entryTypePrefix}-milestone`;
   const advisoryProjectionType = `${entryTypePrefix}-advisory`;
+  const surfacingProjectionType = `${entryTypePrefix}-surfacing`;
   const entryNamespace = entryTypeNamespace(entryTypePrefix);
   const providerMeasurementEntryType = `${entryNamespace}-provider-context-measurement`;
   const nativeReceiptEntryType = `${entryNamespace}-native-compaction-receipt`;
@@ -247,6 +282,14 @@ export function registerActiveContext(pi: any, options: {
     hardFenceReleasedProjectionKeys: new Set<string>(),
   };
 
+  // Owns the suggestion sources feeding the ephemeral surfacing carrier plus the slate
+  // rendered on the current context event. Nothing here is durable: the carrier is
+  // rebuilt from state on every projection, and only the log lives in session state.
+  const surfacing = {
+    sources: [] as SuggestionSource[],
+    suggestions: [] as SurfacingSuggestion[],
+  };
+
   // Owns native-compaction decisions and completion retry state; nativeReceiptQueue serializes it.
   const nativeCompaction = {
     lastThresholdDecision: null as Record<string, unknown> | null,
@@ -1018,14 +1061,40 @@ export function registerActiveContext(pi: any, options: {
       if (ownsSlot && sessionIdentityStillValid(ctx, snapshot.sessionId, capturedGeneration)) updateStatus(ctx);
     });
   };
+  // Appended at the very TAIL, after the stable prefix, so a suggestion never
+  // invalidates a cached prefix and never becomes durable transcript.
+  const appendSurfacing = (projected: unknown[], snapshot: ActiveContextSnapshot): unknown[] => {
+    const content = surfacingText({ suggestions: surfacing.suggestions, brandNoun });
+    if (!content) return projected;
+    projected.push({
+      role: "custom",
+      customType: surfacingProjectionType,
+      content,
+      display: false,
+      details: {
+        source: activeContextSource(entryTypePrefix),
+        ephemeral: true,
+        suggestions: surfacing.suggestions.map((suggestion) => ({
+          source: suggestion.source,
+          id: suggestion.id,
+          score: suggestion.score,
+        })),
+      },
+      timestamp: typeof ownValue(snapshot.messages.at(-1), "timestamp") === "number"
+        ? ownValue(snapshot.messages.at(-1), "timestamp")
+        : 0,
+    });
+    return projected;
+  };
   const projectWithAdvisory = (snapshot: ActiveContextSnapshot): unknown[] => {
     const projected = projectActiveContext(snapshot, persistence.state!).filter((message) => {
       const customType = ownValue(message, "customType");
-      return customType !== milestoneProjectionType && customType !== advisoryProjectionType;
+      return customType !== milestoneProjectionType && customType !== advisoryProjectionType &&
+        customType !== surfacingProjectionType;
     });
     const armed = advisoryState(persistence.state!).armed;
     if (!armed || armed.milestone !== advisory.armedMilestone || measurements.latestRatio === null ||
-        measurements.latestRatio < 0.85 * armed.threshold) return projected;
+        measurements.latestRatio < 0.85 * armed.threshold) return appendSurfacing(projected, snapshot);
     const status = activeContextStatus(snapshot, persistence.state!, 0, 1, snapshot.policy.maxFoldSourceRefs);
     const eligible = ownValue(status, "eligibleChapter");
     const startId = ownValue(eligible, "startId");
@@ -1040,7 +1109,9 @@ export function registerActiveContext(pi: any, options: {
     projected.push({
       role: "custom",
       customType: milestoneProjectionType,
-      content: milestoneText(armed.milestone, persistence.state!.sessionId, armed.threshold, toolName, brandNoun),
+      content: milestoneText(
+        armed.milestone, persistence.state!.sessionId, armed.threshold, toolName, brandNoun, guidance,
+      ),
       display: false,
       details: { source: activeContextSource(entryTypePrefix), ephemeral: true, milestone: armed.milestone },
       timestamp: 0,
@@ -1062,7 +1133,9 @@ export function registerActiveContext(pi: any, options: {
         ? ownValue(snapshot.messages.at(-1), "timestamp")
         : 0,
     });
-    return projected;
+    // A suggestion never shares an advisory with urgent fence text: at the fence the
+    // only useful next action is the fold that keeps the request transmissible.
+    return armed.milestone === "urgent" ? projected : appendSurfacing(projected, snapshot);
   };
   const commitDeterministicCandidate = async (
     snapshot: ActiveContextSnapshot,
@@ -1285,6 +1358,67 @@ export function registerActiveContext(pi: any, options: {
   };
   options.setProjectionProvider?.(projectionCandidates);
 
+  /**
+   * The suggestion-source hook. The built-in fold-brief source registers through this
+   * same call, so an external memory system's items reach the identical carrier,
+   * budget, ranking, and accept/reject log; pi-fold owns the channel, not the content.
+   */
+  const registerSuggestionSource: SuggestionSourceRegistrar = (source: SuggestionSource) => {
+    if (!source || typeof source !== "object" || typeof source.id !== "string" || !source.id ||
+        typeof source.candidates !== "function") {
+      throw new Error("A suggestion source needs a nonempty id and a candidates function");
+    }
+    if (surfacing.sources.some((registered) => registered.id === source.id)) {
+      throw new Error(`Suggestion source '${source.id}' is already registered`);
+    }
+    surfacing.sources.push(source);
+    return {
+      unregister: () => {
+        surfacing.sources = surfacing.sources.filter((registered) => registered !== source);
+      },
+      accepted: (id: string) => {
+        if (!persistence.state || typeof id !== "string" || !id) return;
+        // In-memory only: the next persisted state carries it. Reporting an outcome
+        // must never write a durable entry of its own.
+        persistence.state = acceptSurfacingSuggestion(
+          persistence.state,
+          id,
+          lifecycle.latestSnapshot ? surfacingOrdinal(lifecycle.latestSnapshot) : 0,
+        );
+      },
+    };
+  };
+  if (surfacingEnabled) registerSuggestionSource(FOLD_BRIEF_SUGGESTION_SOURCE);
+  options.setSuggestionSourceRegistrar?.(registerSuggestionSource);
+
+  /**
+   * Selects this context event's slate and logs what will be shown. Selection is
+   * deterministic and model-free, and a selector fault costs the session nothing but
+   * its suggestions: the projection itself is never at risk.
+   *
+   * Returns whether the log now differs from the DURABLE one rather than merely from
+   * the pre-selection value: an outcome marked by an ephemeral peek carries no
+   * persistence of its own and would otherwise never reach the session file.
+   */
+  const refreshSurfacing = (snapshot: ActiveContextSnapshot): boolean => {
+    surfacing.suggestions = [];
+    if (!surfacingEnabled || !surfacing.sources.length || !persistence.state) return false;
+    try {
+      const update = updateSurfacing({
+        state: persistence.state,
+        snapshot,
+        sources: surfacing.sources,
+        toolName,
+      });
+      surfacing.suggestions = update.suggestions;
+      persistence.state = update.state;
+    } catch {
+      surfacing.suggestions = [];
+    }
+    return stableStringify(persistence.state.surfacing ?? null) !==
+      stableStringify(persistence.persisted?.surfacing ?? null);
+  };
+
   // A same-session start/tree reload is a projection-generation mutation.
   // Queue it behind every context authority → preparation → commit →
   // projection transaction, then serialize the actual load with the action
@@ -1381,7 +1515,7 @@ export function registerActiveContext(pi: any, options: {
     if (!persistence.state) return false;
     const ratio = contextUsageRatio(measurement);
     if (ratio === null) return false;
-    const schedule = advisorySchedule(snapshot);
+    const schedule = advisorySchedule(snapshot, guidance);
     const scheduleKey = sha256Value({
       schedule: schedule.key,
       provider: measurement.provider,
@@ -1484,8 +1618,9 @@ export function registerActiveContext(pi: any, options: {
       } else {
         measurements.latestRatio = contextUsageRatio(measurements.lastProviderMeasurement);
       }
-      if ((advisoryChanged || measurementStateChanged) && persistence.state && persistence.persisted &&
-          !sameStateProjection(persistence.state, persistence.persisted)) {
+      const surfacingChanged = refreshSurfacing(snapshot);
+      if ((advisoryChanged || measurementStateChanged || surfacingChanged) && persistence.state &&
+          persistence.persisted && !sameStateProjection(persistence.state, persistence.persisted)) {
         mutationAttempted = true;
         await persistThroughActionQueue(ctx);
         persistedSucceeded = true;
@@ -1729,10 +1864,10 @@ export function registerActiveContext(pi: any, options: {
     const snapshot = authoritativeSnapshotFor(ctx);
     if (action === "status") {
       const detail = ownValue(params, "detail");
-      if (detail !== undefined && detail !== "fold_candidates") {
-        throw new Error("status detail must be 'fold_candidates'");
+      if (detail !== undefined && detail !== "fold_candidates" && detail !== "tree") {
+        throw new Error("status detail must be 'fold_candidates' or 'tree'");
       }
-      const schedule = advisorySchedule(snapshot);
+      const schedule = advisorySchedule(snapshot, guidance);
       return toolPayload({
         ...activeContextStatus(
           snapshot,
@@ -1750,6 +1885,16 @@ export function registerActiveContext(pi: any, options: {
           ])),
           armedMilestone: advisory.armedMilestone,
           advisory: advisoryState(persistence.state),
+          surfacing: {
+            enabled: surfacingEnabled,
+            sources: surfacing.sources.map((source) => source.id),
+            shown: surfacing.suggestions.map((suggestion) => ({
+              source: suggestion.source,
+              id: suggestion.id,
+              score: suggestion.score,
+            })),
+            log: clone(persistence.state.surfacing ?? []),
+          },
           historicalGuidanceEntries: advisory.historicalGuidanceEntries,
           warningRatio: snapshot.policy.warningRatio,
           toolFoldRatio: snapshot.policy.toolFoldRatio,
@@ -1801,12 +1946,33 @@ export function registerActiveContext(pi: any, options: {
             failedPreparationIds: ladder.failedPreparations,
           }),
         } : {}),
+        ...(detail === "tree" ? { tree: foldTreeDetail(snapshot, persistence.state) } : {}),
       });
     }
+    // Peeking or expanding a suggested fold is the accept signal. Peek stays
+    // ephemeral: the mark rides the next persisted state, never an entry of its own.
+    const noteSurfacingAccept = (id: string): void => {
+      if (!surfacingEnabled || !persistence.state) return;
+      persistence.state = acceptSurfacingSuggestion(persistence.state, id, surfacingOrdinal(snapshot));
+    };
+    if (action === "peek") {
+      const id = String(params.id ?? "").trim();
+      if (!id) throw new Error("peek requires id");
+      const payload = toolPayload(peekFoldSource({
+        foldId: id,
+        state: persistence.state,
+        entries: ctx.sessionManager.getEntries?.() ?? ctx.sessionManager.getBranch(),
+        sessionId: ctx.sessionManager.getSessionId(),
+        maximumBytes: snapshot.policy.maxChapterChars,
+      }));
+      noteSurfacingAccept(id);
+      return payload;
+    }
     if (action === "expand" || action === "refold") {
       const id = String(params.id ?? "").trim();
       if (!id) throw new Error(`${action} requires id`);
       requireActiveFold(snapshot, persistence.state, id);
+      if (action === "expand") noteSurfacingAccept(id);
       let next = setFoldProjectionState(persistence.state, id, action === "expand" ? "expanded" : "folded");
       if (action === "expand") next = withExpandLease(next, id);
       else {
@@ -1983,8 +2149,9 @@ export function registerActiveContext(pi: any, options: {
     persistence.persisted = null;
     lifecycle.latestSnapshot = null;
     advisory.armedMilestone = null;
+    surfacing.suggestions = [];
     try { ctx.ui?.setStatus?.(entryTypePrefix, undefined); } catch { /* Shutdown cannot be blocked by UI. */ }
   });
 
-  return { projectionCandidates };
+  return { projectionCandidates, registerSuggestionSource };
 }

package/extensions/lib/advisory.ts

@@ -9,8 +9,15 @@ 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";
-import { contextBrand, DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN } from "./policy.ts";
 
 export { ADVISORY_BUDGETS };
 
@@ -35,18 +42,41 @@ export function clearArmedAdvisory(state: ActiveContextState): ActiveContextStat
   return { ...state, advisory };
 }
 
-export function advisorySchedule(
+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">,
-): AdvisorySchedule {
-  const rungs = [
+  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 },
-    { milestone: "urgent" as const, threshold: hardFenceRatio(snapshot) - 0.03,
-      budget: ADVISORY_BUDGETS.urgent },
+    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);
   }
@@ -100,15 +130,43 @@ export function updateAdvisoryMilestone(
   };
 }
 
+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; curate it against the task you are on now. Fold the spans that task ` +
+      `no longer needs with ${toolName} ` +
+      '{"action":"fold","ids":["<start>","<end>"],"brief":"<factual brief>"}, and keep what must stay raw out ' +
+      `of every fold with ${toolName} {"action":"protect","ids":["<entry-id>"]}.`;
+  }
+  if (milestone === "tools") {
+    return "Completed read-only tool batches are the cheapest thing to fold, and their endpoint ids are in the " +
+      "live advisory. Fold the batches whose detail this task is finished with; each one expands back to the " +
+      `exact entries later with ${toolName} {"action":"expand","id":"<fold-id>"}.`;
+  }
+  return "Fold up: hand two or more adjacent folds of finished work to " +
+    `${toolName} {"action":"fold","ids":["<fold-id>","<fold-id>"],"brief":"<factual brief>"} so they nest in ` +
+    "one deeper fold, leaving the oldest material deepest and still exactly recoverable. A closed chapter " +
+    `folds first, from the eligibleChapter endpoints in ${toolName} {"action":"status"}.`;
+}
+
 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"}.`;
@@ -126,6 +184,34 @@ export function milestoneText(
     "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 function liveAdvisoryText(input: {
   milestone: AdvisoryMilestone;
   ratio: number;

package/extensions/lib/canonical.ts

@@ -15,6 +15,14 @@ export function bytes(value: unknown): number {
   return Buffer.byteLength(typeof value === "string" ? value : stableStringify(value), "utf8");
 }
 
+export function boundedUtf8(text: string, maximumBytes: number): string {
+  const buffer = Buffer.from(text, "utf8");
+  if (buffer.length <= maximumBytes) return text;
+  // A multi-byte sequence cut by the bound decodes to one trailing replacement
+  // character; dropping it keeps the slice an exact prefix of the source.
+  return buffer.subarray(0, maximumBytes).toString("utf8").replace(/\uFFFD$/, "");
+}
+
 export function ownValue(value: unknown, key: string): unknown {
   if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
   const descriptor = Object.getOwnPropertyDescriptor(value, key);