pi-fold 4.2.0 → 4.2.2

package/README.md

@@ -14,7 +14,7 @@
 pi install npm:pi-fold
 ```
 
-Node 22 or later, Pi 0.83 or later. MIT licensed.
+Node 22 or later and Pi 0.83 or later. Pi 1.0 is supported and requires Node 22.19 or later. MIT licensed. Pi supplies the extension's runtime packages; they are declared as host-provided peers, not private dependencies.
 
 Folding does not require a memory store, but every best result measured came from pairing it with one. The campaigns used [pi-canon](https://github.com/shaneconner/canon), installed separately. The two began as a single working setup and were split into separate extensions for modularity, and the experiments are what established that they work better as complements than either does alone. Only that pairing has been measured. Any durable long-term memory store is expected to compose the same way, though that is a suspicion rather than a result.
 
@@ -40,11 +40,11 @@ In an interactive session one compact, full-height bar sits directly above Pi's
   <img alt="A single full-height usage bar. Batlow colours group consolidated folds, span folds, tool folds, marked content, raw context and pinned content in that order. The suffix shows percentage, commit point, and fold, mark, and pin counts." src="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-bar-light.svg">
 </picture>
 
-The forty-column bar uses full-height half-blocks for eighty steps of fill, following the provider's measured count against the serving budget. Within that fill, colours show the estimated visible composition, grouped by distance from compression: **Consolidated Folds, Span Folds, Tool Folds, Marked, Raw, Pinned**. The first three are compressed now, deepest first; marked content folds at the next commit; raw content is eligible later; pinned content is held against every commit until released. The six shades, from consolidated to pinned, are read off a colour map, [Crameri's Batlow](https://www.fabiocrameri.ch/colourmaps/) end to end by default, so the bar reads as a gradient from most compressed to most settled. `/fold-settings` offers Batlow, viridis, plasma, magma and cividis, and where on the chosen map the two ends sit, so a slice of a map or a reversed one is a keypress away; the bar repaints on each step. Whatever the choice, each shade's lightness is moved away from the background, hue held, until it clears 4.5:1 on dark and light terminals, and label colours match the bar. Each nonempty category keeps at least one half-cell when the measured fill has room; remaining width follows relative mass. This visibility floor makes small compressed categories visible, so individual category widths are not token-exact. At very low occupancy, the largest shares take the available space. There are no individual fold edges, scores, or height differences.
+The forty-column bar uses full-height half-blocks for eighty steps of fill, reading Pi's `getContextUsage()` directly on every render. Its percentage uses Pi's full context window, the same scale as Pi's footer, including Pi's estimate of messages since the last provider response. Within that fill, colours show the estimated visible composition, grouped by distance from compression: **Consolidated Folds, Span Folds, Tool Folds, Marked, Raw, Pinned**. The first three are compressed now, deepest first; marked content folds at the next commit; raw content is eligible later; pinned content is held against every commit until released. The six shades, from consolidated to pinned, are read off a colour map, [Crameri's Batlow](https://www.fabiocrameri.ch/colourmaps/) end to end by default, so the bar reads as a gradient from most compressed to most settled. `/fold-settings` offers Batlow, viridis, plasma, magma and cividis, and where on the chosen map the two ends sit, so a slice of a map or a reversed one is a keypress away; the bar repaints on each step. Whatever the choice, each shade's lightness is moved away from the background, hue held, until it clears 4.5:1 on dark and light terminals, and label colours match the bar. Each nonempty category keeps at least one half-cell when the measured fill has room; remaining width follows relative mass. This visibility floor makes small compressed categories visible, so individual category widths are not token-exact. At very low occupancy, the largest shares take the available space. There are no individual fold edges, scores, or height differences.
 
-The suffix reads `34% · commit at 55% · N Folds (X Cons., Y Span, Z Tool, X Mark, Y Pin)`, naming only the kinds with something to count, in the bar's order; a fresh session reads `0 Folds`. `N Folds` counts visible compressed folds; `Mark` counts pending marks and `Pin` counts protected entries, not additional compressed folds. A tool fold is lossless compression of tool-result context, not a count of tool calls. `/fold-status` retains the detailed token and nesting figures.
+The suffix reads `34% · commit at 55% · N Folds (X Cons., Y Span, Z Tool, X Mark, Y Pin)`, naming only the kinds with something to count, in the bar's order; a fresh session reads `0 Folds`. `N Folds` counts visible compressed folds; `Mark` counts pending marks and `Pin` counts protected entries, not additional compressed folds. A tool fold is lossless compression of tool-result context, not a count of tool calls. `/fold-status` retains the detailed token and nesting figures. Its `Budget` row and the editor's `Budget` header report the separate serving budget and the tokens remaining before a commit.
 
-Two dotted marks stand in the band's edge cells: one at `minTarget`, where a commit aims to land, and one at `maxTarget`, where automatic folding is triggered. Each is drawn over the fill's own colour in a deeper tone of that same hue, so the fill continues behind the mark; on the empty track they stand in muted ink. Neither takes a colour of its own or a warning colour. Before a measurement the row says `not measured yet`; after a commit it identifies the old reading until the provider measures again. Crossing the target is routine runtime work, not a user action item. On reload, saved session context supplies the fold counts and composition without a new model message; the next real context event replaces that read-only view. Unavailable composition is stated as `mapping`; if folding stops, `FOLDING STOPPED` replaces the bar. Non-truecolor terminals use the theme's own colours.
+Two dotted marks stand in the band's edge cells: one where a commit aims to land and one where automatic folding is triggered. `minTarget` and `maxTarget` remain shares of the serving budget; the marks and displayed commit point are converted to Pi's full-window scale, so the trigger does not move. With a 272,000-token window and the default 255,616-token serving budget, the 80% trigger appears at about 75% of Pi's window. Percentages are rounded to whole numbers; a custom footer may round differently. Each is drawn over the fill's own colour in a deeper tone of that same hue, so the fill continues behind the mark; on the empty track they stand in muted ink. Neither takes a colour of its own or a warning colour. When Pi reports unknown usage, including immediately after native compaction, the row says `not measured yet`; no saved count or local estimate fills the gap. After a fold commit it identifies the old reading until the provider measures again. Crossing the target is routine runtime work, not a user action item. On reload, saved session context supplies the fold counts and composition without a new model message; the next real context event replaces that read-only view. Unavailable composition is stated as `mapping`; if folding stops, `FOLDING STOPPED` replaces the bar. Non-truecolor terminals use the theme's own colours.
 
 ## Results
 
@@ -85,7 +85,7 @@ Seven options, and every other name is refused.
 | Option | Default | Effect |
 | --- | --- | --- |
 | `thresholds` | `{ maxTarget: 0.80, minTarget: 0.20, consolidateAfter: 10, minFoldChars: 8000 }` | The band, set whole or not at all. The first two are proportions of the serving budget. `consolidateAfter` is how many visible roots a parent is owed. `minFoldChars` is the size a fold has to reach to be worth making, and the floor a gap between folds has to clear to stay raw. Validated atomically; an impossible policy is refused by name rather than clamped. |
-| `providerInputBudget` | the transport's descriptor | The tokens this deployment may actually put in a request, already net of any output reservation. Every ratio, fence and budget on this page is a share of this one number. |
+| `providerInputBudget` | derived from Pi's context window | The tokens this deployment may actually put in a request, already net of any output reservation when supplied. Without it, folding retains its default headroom of 16,384 tokens, capped at 10% of the window. This is a folding allowance, not a measured provider output reservation or a read of Pi's per-model compaction settings. Thresholds use this serving budget; the fold bar uses Pi's full-window scale. |
 | `blacklistAutoFoldTools` | `new Set()` | The exception list. Every completed tool batch is foldable without an agent mark; name a tool here and its results stay raw. |
 | `toolFoldThreshold` | `0.50` | The tool-call diet: a share in `[0, 1)` naming the oldest fraction of the window whose tool results are clipped in view. `0` turns it off. |
 | `preCommitNotice` | `false` | The notice switch. False is the shape that won the campaign above: no carrier reaches the projection and every fold ships the runtime's own words. `true` states the window's status to the agent once per approach to a commit: where the commit fires, how far away it is, what is staged, what that frees, what is pinned and what the pin costs, with the verbs listed and no argument made for using any of them. |
@@ -118,12 +118,13 @@ What the agent owns is the words. `brief` writes its own sentence onto a pending
 A commit fires on one condition: occupancy reaching `maxTarget` of the serving budget. It applies marks stalest first and stops at `minTarget`, so the newest events stay raw and a mark past the bound waits for the next epoch. Below `maxTarget` the window is quiet, because a commit is an epoch transition that risks the whole prefix cache and the right cadence is the fewest commits that keep the window inside its budget.
 
 ```
-272,000  the transport's descriptor
+272,000  Pi's full context window
+255,616  default serving budget, after folding headroom
 ─────────────────────────────────────────────────────
 ~250k    peak: inflow continues while the epoch computes
-217,600  maxTarget 0.80   ← the commit fires here
+204,493  maxTarget 0.80   ← about 75% on Pi's scale
    ⋮                        marks accumulate, free, quiet
- 54,400  minTarget 0.20   ← the commit stops here
+ 51,123  minTarget 0.20   ← about 19% on Pi's scale
 ─────────────────────────────────────────────────────
 ```
 

package/extensions/active-context.ts

@@ -739,8 +739,8 @@ export function registerActiveContext(pi: any, options: {
   /**
    * THE FOLD BAR. One coloured composition row directly above the footer,
    * drawn by `renderFoldBar` from a model this function rebuilds on every status update.
-   * The component reads the model and the LIVE theme at render time, so it repaints on
-   * a theme switch, which the status string cannot; the host is asked to render after
+   * The component reads Pi's context usage and the LIVE theme at render time. Neither
+   * reading is cached between status events; the host is asked to render after
    * each rebuild. Installed once per host UI, on the first update that finds one.
    */
   const foldBar = {
@@ -753,6 +753,34 @@ export function registerActiveContext(pi: any, options: {
     /** Display-only reconstruction while waiting for the first real context event. */
     startupSnapshot: null as ActiveContextSnapshot | null,
   };
+  // DISPLAY ONLY. Pi owns the live reading, including its unmeasured trailing messages
+  // and post-compaction unknown state. Never substitute our saved provider measurement
+  // or projection estimate. The band remains a share of the SERVING budget: convert its
+  // points onto Pi's full-window axis, without changing any scheduling arithmetic.
+  const foldBarUsage = (ctx: any): Pick<FoldBarModel, "share" | "commitShare" | "aimShare"> => {
+    let usage: unknown;
+    try { usage = ctx.getContextUsage?.(); } catch { }
+    const reportedWindow = ownValue(usage, "contextWindow");
+    const modelWindow = ownValue(ctx.model, "contextWindow");
+    const validWindow = (value: unknown): value is number =>
+      typeof value === "number" && Number.isFinite(value) && value > 0;
+    const window = validWindow(reportedWindow) ? reportedWindow
+      : validWindow(modelWindow) ? modelWindow : DEFAULT_CONTEXT_WINDOW;
+    const tokens = ownValue(usage, "tokens");
+    const percent = ownValue(usage, "percent");
+    const share = validWindow(reportedWindow) && typeof tokens === "number" &&
+      Number.isFinite(tokens) && tokens >= 0 && typeof percent === "number" &&
+      Number.isFinite(percent) && percent >= 0 ? percent / 100 : null;
+    const capacity = capacityAccounting({
+      window: providerInputBudget ?? window,
+      truthful: providerInputBudget !== null,
+      descriptorWindow: window,
+      usedTokens: null,
+    });
+    const budgetShare = capacity.budgetTokens / window;
+    return { share, commitShare: thresholds.maxTarget * budgetShare,
+      aimShare: thresholds.minTarget * budgetShare };
+  };
   const installFoldBar = (ctx: any): void => {
     if (foldBar.installed || typeof ctx.ui?.setWidget !== "function") return;
     foldBar.installed = true;
@@ -760,10 +788,13 @@ export function registerActiveContext(pi: any, options: {
       foldBar.requestRender = () => { try { tui.requestRender(); } catch { } };
       return {
         /** The model behind the row, for the lab and the gates. */
-        get model(): FoldBarModel | null { return foldBar.model; },
+        get model(): FoldBarModel | null {
+          return foldBar.model ? { ...foldBar.model, ...foldBarUsage(ctx) } : null;
+        },
         render(width: number): string[] {
-          if (!foldBar.model) return [];
-          try { return [renderFoldBar(foldBar.model, width, ctx.ui.theme)]; }
+          const model = this.model;
+          if (!model) return [];
+          try { return [renderFoldBar(model, width, ctx.ui.theme)]; }
           catch { return []; }
         },
         invalidate() { },
@@ -771,7 +802,7 @@ export function registerActiveContext(pi: any, options: {
     }, { placement: "belowEditor" });
   };
   const foldBarModel = (ctx: any, input: {
-    share: number | null; staged: number; weighed: boolean;
+    share: number | null; commitShare: number; aimShare: number; staged: number; weighed: boolean;
   }): FoldBarModel => {
     const state = persistence.state;
     // THE SAME SNAPSHOT /fold-status PRICES AGAINST. `markFreedBytes` answers ZERO, silently,
@@ -785,8 +816,8 @@ export function registerActiveContext(pi: any, options: {
     const model: FoldBarModel = {
       brand: brandNoun,
       share: input.share,
-      commitShare: thresholds.maxTarget,
-      aimShare: thresholds.minTarget,
+      commitShare: input.commitShare,
+      aimShare: input.aimShare,
       mapped: false, mass: emptyFoldBarMass(),
       stagedMarks: input.staged,
       folds: 0, foldSpans: 0, foldTruncations: 0, foldConsolidations: 0,
@@ -863,13 +894,13 @@ export function registerActiveContext(pi: any, options: {
       const roots = persistence.state && lifecycle.latestSnapshot ? orderedRoots(persistence.state, lifecycle.latestSnapshot).length : 0;
       const staged = persistence.state ? pendingMarks(persistence.state).length : 0;
       const capacity = currentCapacity(ctx);
-      const used = measurements.lastProviderMeasurement?.tokens ?? null;
-      const share = used !== null && capacity.budgetTokens > 0 ? used / capacity.budgetTokens : null;
+      const usage = foldBarUsage(ctx);
+      const { share } = usage;
       try {
         installFoldBar(ctx);
         if (foldBar.installed) {
           foldBar.model = foldBarModel(ctx, {
-            share, staged,
+            ...usage, staged,
             weighed: ladder.bandTopMeasurement !== null &&
               ladder.bandTopMeasurement === measurements.lastProviderMeasurement,
           });
@@ -889,7 +920,7 @@ export function registerActiveContext(pi: any, options: {
       // in /fold-settings went on being announced at its old value until the next event
       // rebuilt a snapshot. The number this line owes a person is the one that will fire,
       // and that is the runtime's own variable.
-      const trigger = thresholds.maxTarget;
+      const trigger = usage.commitShare;
       // WHEN, not just how full. "68% full" only answers the second question a reader has
       // if they already remember where the trigger sits; naming it answers both.
       //
@@ -911,9 +942,13 @@ export function registerActiveContext(pi: any, options: {
       if (share !== null && !ladder.automaticFailure) {
         const weighed = ladder.bandTopMeasurement !== null &&
           ladder.bandTopMeasurement === measurements.lastProviderMeasurement;
+        // Pi may include a trailing estimate ahead of the last provider count. Being
+        // over the displayed point alone must not promise an imminent runtime commit.
+        const due = capacity.usedTokens !== null &&
+          capacity.usedTokens >= thresholds.maxTarget * capacity.budgetTokens;
         parts.push(share < trigger
           ? `commit at ${Math.round(trigger * 100)}%`
-          : weighed ? "commit held" : "COMMIT DUE");
+          : weighed ? "commit held" : due ? "COMMIT DUE" : "at commit point");
       }
       if (staged > 0) parts.push(`${staged} staged`);
       if (roots > 0) parts.push(`${roots} fold${roots === 1 ? "" : "s"}`);

package/extensions/lib/curation.ts

@@ -261,12 +261,13 @@ export function foldStatusText(input: {
 
   if (input.usedTokens === null || !(input.budgetTokens > 0)) {
     // "provider" is infrastructure vocabulary and "sets it" names no observable event.
-    lines.push("  Window   not measured yet; the first model response will measure it.");
+    lines.push("  Budget   not measured yet; the first model response will measure it.");
   } else {
     const share = input.usedTokens / input.budgetTokens;
     const filled = Math.max(0, Math.min(STATUS_BAR_WIDTH, Math.round(share * STATUS_BAR_WIDTH)));
     const bar = `${"▇".repeat(filled)}${"░".repeat(STATUS_BAR_WIDTH - filled)}`;
-    lines.push(`  Window   ${bar}  ${Math.round(share * 100)}%  ` +
+    // This detailed view reports serving headroom, not Pi's full-window percentage.
+    lines.push(`  Budget   ${bar}  ${Math.round(share * 100)}%  ` +
       `${n(input.usedTokens)} / ${n(input.budgetTokens)} tokens`);
     const commitAt = input.commitAtShare * input.budgetTokens;
     // The headroom is what a person actually wants: not the trigger's share, but how much

package/extensions/lib/editor-ui.ts

@@ -1125,7 +1125,7 @@ export class FoldEditorView {
 		// one surface the rule was never checked against. Nothing here is estimated.
 		if (occupancy.usedTokens === null || !(occupancy.budgetTokens > 0)) {
 			lines.push(truncateToWidth(
-				"window not measured yet; the first model response will measure it", width));
+				"budget not measured yet; the first model response will measure it", width));
 			for (const line of this.stagedLines()) lines.push(truncateToWidth(line, width));
 			return lines;
 		}
@@ -1153,7 +1153,7 @@ export class FoldEditorView {
 			: ` · commit at ${(occupancy.commitOccupancy * 100).toFixed(0)}%${headroom}` +
 				`${occupancy.commitDue ? " · COMMIT DUE" : ""}`;
 		lines.push(truncateToWidth(
-			`${occupancyBar(occupancy.usedTokens, occupancy.budgetTokens)} ` +
+			`Budget ${occupancyBar(occupancy.usedTokens, occupancy.budgetTokens)} ` +
 			`${percent}%${timing}` +
 			` · ${usedTokensText}/${occupancy.budgetTokens.toLocaleString("en-US")}`,
 			width,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fold",
-  "version": "4.2.0",
+  "version": "4.2.2",
   "description": "Lossless context folding for the Pi coding agent: only the oldest context changes; the fresh window stays untouched.",
   "keywords": [
     "pi-package",
@@ -37,7 +37,8 @@
     "test": "node tests/verify.mjs"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.83.0 <1"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -52,8 +53,5 @@
     "extensions": [
       "./extensions"
     ]
-  },
-  "dependencies": {
-    "@earendil-works/pi-tui": "^0.84.2"
   }
 }