pi-fold 4.1.1 → 4.1.3

package/README.md

@@ -37,10 +37,10 @@ In an interactive session one row sits directly above Pi's footer and shows the
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-bar-dark.svg">
-  <img alt="The fold bar: forty cells of the serving budget, oldest on the left, with ticks at the aim and the commit point. Staged spans, raw material and fold placeholders fill it in three colours, and the label reads 42%, commit at 80%, 12 staged, 118k to free, 3 folds hold 412k." src="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-bar-light.svg">
+  <img alt="The fold bar: forty cells of the serving budget, oldest on the left, with ticks at the aim and the commit point. Staged spans, raw material and fold placeholders fill it in three colours, and the label reads 42%, commit at 80%, 12 staged, 3 folds hide 412k tokens." src="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-bar-light.svg">
 </picture>
 
-The bar is the serving budget, forty cells wide, oldest material on the left. The two ticks are the band: the left one is `minTarget`, where a commit aims to land, and the right one is `maxTarget`, where the commit fires. The fill is the provider's own count of what is in the window, never an estimate, so before the first response the row says `not measured yet` and draws nothing. One cell is one fortieth of the budget, and the fill reads left to right in three colours: the placeholders of standing folds first, drawn as low slivers and small by design; then staged spans, the raw material the next commit collapses; then raw material the runtime has not claimed yet. The label repeats the percentage, names the commit point (or reads `COMMIT DUE` once the fill has crossed it and `commit held` once that count has been weighed), states how many spans are staged and what they free, and ends with what folding has already bought: the tokens the standing folds hide. If automatic folding ever stops, the row reads `FOLDING STOPPED` in place of the bar. On a truecolor terminal the three fill classes take three steps of Crameri's batlow colour map; elsewhere they use the theme's own colours.
+The bar is the serving budget, forty cells wide, oldest material on the left. The two ticks are the band: the left one is `minTarget`, where a commit aims to land, and the right one is `maxTarget`, where the commit fires. The fill is the provider's own count of what is in the window, never an estimate, so before the first response the row says `not measured yet` and draws nothing. One cell is one fortieth of the budget, and the fill reads left to right in three colours: the placeholders of standing folds first, drawn as low slivers and small by design; then staged spans, the raw material the next commit collapses; then raw material the runtime has not claimed yet. The label repeats the percentage, names the commit point (or reads `COMMIT DUE` once the fill has crossed it and `commit held` once that count has been weighed), states how many spans are staged, and ends with what folding has already bought: the tokens the standing folds hide from the window. Every token figure prices a pasted image as one image rather than as its base64 text, the same way the occupancy estimate does. Right after a commit the percentage is still the provider's last count, so the label says it is from before the commit until the next response measures the window again. If automatic folding ever stops, the row reads `FOLDING STOPPED` in place of the bar. On a truecolor terminal the three fill classes take three steps of Crameri's batlow colour map; elsewhere they use the theme's own colours.
 
 ## Results
 

package/extensions/active-context.ts

@@ -35,6 +35,7 @@ import {
   selectAutomaticRung,
   setFoldProjectionState,
   withExpandLease,
+  renderFoldParts,
 } from "./lib/folding.ts";
 import {
   admissionVerdict,
@@ -54,6 +55,7 @@ import {
   parseNativeCompactionDecision,
   parseProviderContextMeasurementReceipt,
   persistenceProjection,
+  pricedBytes,
   protectedStaleMass,
   providerContextMeasurement,
   providerTokens,
@@ -178,7 +180,6 @@ import {
   peekedSourceFoldIds,
   snapFoldCandidate,
   snapToFoldBoundaries,
-  spanBytes,
 } from "./lib/selection.ts";
 import type { SpanCorrection } from "./lib/selection.ts";
 import {
@@ -224,6 +225,7 @@ export * from "./lib/persistence.ts";
 export * from "./lib/policy.ts";
 export * from "./lib/rollback.ts";
 export * from "./lib/scheduling.ts";
+export * from "./lib/status-widget.ts";
 export * from "./lib/selection.ts";
 export * from "./lib/transcript.ts";
 
@@ -667,6 +669,12 @@ export function registerActiveContext(pi: any, options: {
 
   const deliverReceipt = (receipt: ContextReceipt): void => {
     curation.receipts = withReceipt(curation.receipts, receipt);
+    // THE BAR'S READING GOES STALE AT A COMMIT. Occupancy is the provider's last count,
+    // which does not move until the next response, so after a commit the bar went on
+    // showing the pre-commit number as if it were current (38% beside "10 folds hold
+    // 8.6M", Shane 2026-09-03). Remember which measurement the commit landed against;
+    // while it is still the latest, the bar says the number is from before the commit.
+    if (receipt.foldsCommitted > 0) foldBar.staleSince = measurements.lastProviderMeasurement;
     // MONOTONIC, unlike `curation.receipts.length`, which saturates at MAX_CONTEXT_RECEIPTS
     // and would stop distinguishing one approach from the next once the session is long
     // enough to matter. This is the only counter the notice latch reads.
@@ -718,6 +726,11 @@ export function registerActiveContext(pi: any, options: {
     model: null as FoldBarModel | null,
     installed: false,
     requestRender: null as (() => void) | null,
+    /** The provider measurement the last landed commit ran against; the reading is
+     *  stale while it is still the latest one. */
+    staleSince: null as unknown,
+    /** Each standing fold's source priced by the image law, keyed by the fold object. */
+    pricedSource: new WeakMap<ActiveFold, number>(),
   };
   const installFoldBar = (ctx: any): void => {
     if (foldBar.installed || typeof ctx.ui?.setWidget !== "function") return;
@@ -734,18 +747,38 @@ export function registerActiveContext(pi: any, options: {
       };
     }, { placement: "belowEditor" });
   };
-  const foldBarModel = (input: {
+  const foldBarModel = (ctx: any, input: {
     share: number | null; budgetTokens: number; staged: number; roots: number; weighed: boolean;
   }): FoldBarModel => {
     const state = persistence.state;
-    const snapshot = lifecycle.latestSnapshot;
+    // THE SAME SNAPSHOT /fold-status PRICES AGAINST. `markFreedBytes` answers ZERO, silently,
+    // for a span it cannot locate contiguously in the snapshot it is handed, and the last
+    // context event's snapshot can trail the branch the marks were cut from; the bar read
+    // "5 staged, 0 to free" beside a status command pricing the same marks at 41,877
+    // tokens (Shane, 2026-09-02, session 01a06272). The authoritative snapshot is memoized
+    // on the branch length, so reading it here costs nothing while nothing has changed.
+    let snapshot = lifecycle.latestSnapshot;
+    try { snapshot = authoritativeSnapshotFor(ctx); } catch { }
     let stagedTokens = 0;
     let placeholderChars = 0;
     let hiddenChars = 0;
     if (state && snapshot) {
       for (const mark of pendingMarks(state)) stagedTokens += estimatedTokens(markFreedBytes(snapshot, state, mark));
       for (const root of orderedRoots(state, snapshot)) placeholderChars += root.fold.placeholderChars;
-      for (const fold of state.folds) hiddenChars += Math.max(0, fold.sourceChars - fold.placeholderChars);
+      // WHAT FOLDING BOUGHT, IN WINDOW TERMS. `sourceChars` is the transcript count, base64
+      // and all, and read as tokens it said "8.6M" over a 1M window. Each standing fold's
+      // source is priced by the image law once per fold OBJECT (folds are immutable and
+      // replaced, never mutated, so a WeakMap memo is exact) and summed over the whole
+      // forest, which is additive because a parent's source is its children's placeholders.
+      for (const fold of state.folds) {
+        let priced = foldBar.pricedSource.get(fold);
+        if (priced === undefined) {
+          const source = renderFoldParts(fold.parts, state, snapshot);
+          priced = source ? pricedBytes(source) : fold.sourceChars;
+          foldBar.pricedSource.set(fold, priced);
+        }
+        hiddenChars += Math.max(0, priced - fold.placeholderChars);
+      }
     }
     const budget = input.budgetTokens > 0 ? input.budgetTokens : 1;
     return {
@@ -760,6 +793,8 @@ export function registerActiveContext(pi: any, options: {
       folds: input.roots,
       hiddenTokens: estimatedTokens(hiddenChars),
       weighed: input.weighed,
+      staleAfterCommit: input.share !== null && foldBar.staleSince !== null &&
+        foldBar.staleSince === measurements.lastProviderMeasurement,
       stopped: ladder.automaticFailure?.message ?? null,
     };
   };
@@ -774,7 +809,7 @@ export function registerActiveContext(pi: any, options: {
       try {
         installFoldBar(ctx);
         if (foldBar.installed) {
-          foldBar.model = foldBarModel({
+          foldBar.model = foldBarModel(ctx, {
             share, budgetTokens: capacity.budgetTokens, staged, roots,
             weighed: ladder.bandTopMeasurement !== null &&
               ladder.bandTopMeasurement === measurements.lastProviderMeasurement,
@@ -2652,7 +2687,7 @@ export function registerActiveContext(pi: any, options: {
       });
       return null;
     }
-    const bytesBefore = bytes(projectActiveContext(snapshot, state));
+    const bytesBefore = pricedBytes(projectActiveContext(snapshot, state));
     // THE COMMIT CUTS ONLY AS DEEP AS THE BUDGET ASKS (Shane, 2026-08-23). The frontier
     // stages as material arrives, so by now the pending set is most of the window; without
     // this bound the first commit would fold all of it. `freeingTarget` is a share of the
@@ -2735,7 +2770,7 @@ export function registerActiveContext(pi: any, options: {
       }
     }
     persistence.state = result.state;
-    const bytesAfter = bytes(projectActiveContext(snapshot, persistence.state));
+    const bytesAfter = pricedBytes(projectActiveContext(snapshot, persistence.state));
     const freedBytes = Math.max(0, bytesBefore - bytesAfter);
     const pinHeld = protectedStaleMass(snapshot, result.state);
     const commitEvent = emit("context.commit", {
@@ -4499,7 +4534,11 @@ export function registerActiveContext(pi: any, options: {
         safeNotify(
           ctx,
           committed
-            ? `Committed ${ownValue(committed, "applied_marks") ?? 0} mark(s)${topUp ? " with automatic top-up" : ""}. ` +
+            // THE EPOCH RECORD IS camelCase; `applied_marks` is the EVENT's spelling. Reading
+            // the event's name off the record printed "Committed 0 mark(s)" after a /fold that
+            // had just applied forty (Shane, 2026-09-03, session 01a06746: 378,216 tokens to
+            // 97,577 with the notice saying nothing happened).
+            ? `Committed ${ownValue(committed, "appliedMarks") ?? 0} mark(s)${topUp ? " with automatic top-up" : ""}. ` +
               "Exact source remains expandable."
             : "Nothing to commit: no staged mark could apply (pinned or already-folded spans hold).",
           "info",
@@ -4586,7 +4625,7 @@ export function registerActiveContext(pi: any, options: {
     // what the staged mark answers with after it.
     const spanCost = (from: number, to: number) => ({
       entries: Math.abs(to - from) + 1,
-      tokens: estimatedTokens(spanBytes(snapshot, Math.min(from, to), Math.max(from, to) + 1)),
+      tokens: estimatedTokens(pricedBytes(snapshot.messages.slice(Math.min(from, to), Math.max(from, to) + 1))),
     });
 
     /**

package/extensions/lib/measurement.ts

@@ -23,6 +23,8 @@ import {
 import {
   ACTIVE_CONTEXT_POLICY,
   DEFAULT_CONTEXT_WINDOW,
+  ESTIMATED_BYTES_PER_TOKEN,
+  IMAGE_ESTIMATED_TOKENS,
   servingBudgetTokens,
 } from "./policy.ts";
 import type {
@@ -594,6 +596,25 @@ export function parseNativeCompactionCompletion(value: unknown, expectedSessionI
  * needs to be the right order of magnitude instead of wrong by seventy times, and the
  * provider anchor corrects the remainder the moment a real measurement lands.
  */
+/**
+ * WHAT A SPAN COSTS THE WINDOW, in the byte unit every estimator already speaks.
+ *
+ * `bytes()` counts a message's serialized characters, and a pasted screenshot serializes
+ * as hundreds of thousands of base64 characters the provider prices as one image. The
+ * occupancy estimate has applied that law since gate 156; the pricing of what a fold
+ * FREES had not, so a session holding 83 screenshots (67.3M base64 characters against
+ * 1.5M of text) told its owner a commit had "5.8M to free" against a 1M window, and a
+ * commit that moved the window 280,000 tokens recorded 8.6M freed (Shane, 2026-09-03,
+ * session 01a06746). Text is counted as its bytes; each image is counted as the bytes
+ * that estimate to IMAGE_ESTIMATED_TOKENS, so `estimatedTokens(pricedBytes(m))` is the
+ * same reading gate 156 gives the projection. Every "frees N" figure derives from this.
+ */
+export function pricedBytes(messages: unknown[]): number {
+  const images = imageMass(messages);
+  return Math.max(0, bytes(messages) - images.base64Chars) +
+    images.images * IMAGE_ESTIMATED_TOKENS * ESTIMATED_BYTES_PER_TOKEN;
+}
+
 export function imageMass(projected: unknown[]): { base64Chars: number; images: number } {
   let base64Chars = 0;
   let images = 0;

package/extensions/lib/scheduling.ts

@@ -27,6 +27,7 @@ import {
   orderedRoots,
   protectedStaleMass,
   refsProtected,
+  pricedBytes,
 } from "./measurement.ts";
 import {
   childFoldIds,
@@ -179,13 +180,15 @@ export function markFreedBytes(
       ...state,
       expanded: state.expanded.filter((id) => id !== mark.id),
     }, snapshot);
-    return expanded && folded ? Math.max(0, bytes(expanded) - bytes(folded)) : 0;
+    return expanded && folded ? Math.max(0, pricedBytes(expanded) - pricedBytes(folded)) : 0;
   }
   const source = renderFoldParts(mark.parts, state, snapshot);
   if (!source) return 0;
   const placeholders = mark.kind === "tool-result" ? mark.parts.length : 1;
   const placeholder = placeholders * (mark.brief.length + ESTIMATED_PLACEHOLDER_OVERHEAD_BYTES);
-  return Math.max(0, bytes(source) - placeholder);
+  // PRICED, NOT COUNTED: a span holding a screenshot is worth one image to the
+  // window, not its base64 length (measurement.ts, pricedBytes).
+  return Math.max(0, pricedBytes(source) - placeholder);
 }
 
 export function markSpanStart(

package/extensions/lib/status-widget.ts

@@ -55,6 +55,8 @@ export interface FoldBarModel {
   hiddenTokens: number;
   /** Whether a band-top commit has already been weighed against the current count. */
   weighed: boolean;
+  /** A commit landed after the count `share` reads; the number is from before it. */
+  staleAfterCommit: boolean;
   /** The suspension message when automatic folding has stopped, else null. */
   stopped: string | null;
 }
@@ -64,11 +66,33 @@ export interface FoldBarTheme {
   fg(color: "dim" | "muted" | "text" | "warning" | "error", text: string): string;
   bold(text: string): string;
   getColorMode?(): "truecolor" | "256color";
+  getFgAnsi?(color: "text"): string;
+  name?: string;
 }
 
-// Crameri batlow10, classes 3, 6 and 8 (0-indexed). The two darkest classes are unusable
-// as fill on a dark terminal, and the lightest washes out on a light one.
-const BATLOW = { raw: "#3C6D56", staged: "#D29343", folded: "#FDB7BC" } as const;
+// Crameri batlow10, three classes per background. Classes 3, 6 and 8 (0-indexed) read on
+// a dark terminal; the lightest of them is 1.7:1 against white, so a light terminal steps
+// two classes darker (2, 5 and 6), the same triple the README's light figure uses.
+const BATLOW_ON_DARK = { raw: "#3C6D56", staged: "#D29343", folded: "#FDB7BC" } as const;
+const BATLOW_ON_LIGHT = { raw: "#1C5A62", staged: "#9D892B", folded: "#D29343" } as const;
+
+/**
+ * WHICH WAY THE BACKGROUND GOES, read off the theme's own text colour rather than its
+ * name: a theme whose body text is dark is drawn on a light background. pi hands the
+ * text colour out as a truecolor escape, and a theme that does not (256-colour mode,
+ * or a host without the accessor) falls back to the name, then to dark.
+ */
+export function lightBackground(theme: FoldBarTheme): boolean {
+  try {
+    const ansi = theme.getFgAnsi?.("text") ?? "";
+    const match = /38;2;(\d+);(\d+);(\d+)/.exec(ansi);
+    if (match) {
+      const [r, g, b] = match.slice(1).map((v) => Number(v) / 255);
+      return 0.2126 * r + 0.7152 * g + 0.0722 * b < 0.5;
+    }
+  } catch { }
+  return /light/i.test(theme.name ?? "");
+}
 
 const truecolor = (hex: string, text: string): string => {
   const r = parseInt(hex.slice(1, 3), 16);
@@ -138,6 +162,7 @@ export function renderFoldBar(model: FoldBarModel, width: number, theme: FoldBar
       width, theme.fg("dim", "..."));
   }
   const rich = theme.getColorMode?.() === "truecolor";
+  const BATLOW = lightBackground(theme) ? BATLOW_ON_LIGHT : BATLOW_ON_DARK;
   const ink: Record<Cell, (text: string) => string> = {
     raw: (t) => rich ? truecolor(BATLOW.raw, t) : theme.fg("muted", t),
     staged: (t) => rich ? truecolor(BATLOW.staged, t) : theme.fg("text", t),
@@ -154,19 +179,27 @@ export function renderFoldBar(model: FoldBarModel, width: number, theme: FoldBar
     else bar += ink[cells[i]](GLYPH[cells[i]]);
   }
   const pct = Math.round(model.share * 100);
-  const parts: string[] = [theme.fg("text", `${pct}%`)];
-  if (model.share < model.commitShare) parts.push(theme.fg("muted", `commit at ${Math.round(model.commitShare * 100)}%`));
-  else if (model.weighed) parts.push(theme.fg("muted", "commit held"));
-  else parts.push(theme.fg("warning", "COMMIT DUE"));
-  // A staged count with nothing priced behind it reads "0 to free", which is a
-  // contradiction on the face of the row; state the count alone until the marks price.
-  if (model.stagedMarks > 0) {
-    parts.push(ink.staged(model.stagedTokens > 0
-      ? `${model.stagedMarks} staged, ${formatTokens(model.stagedTokens)} to free`
-      : `${model.stagedMarks} staged`));
+  const parts: string[] = [];
+  // A READING FROM BEFORE THE COMMIT SAYS SO. The count only moves when the provider
+  // answers, so right after a commit the bar showed the pre-commit percentage in the
+  // same type as a live one and read as a commit that did nothing. No estimate is
+  // drawn in its place: the freed bytes are transcript mass and the arithmetic would
+  // go negative against the window.
+  if (model.staleAfterCommit) {
+    parts.push(theme.fg("muted", `${pct}% before the commit`));
+  } else {
+    parts.push(theme.fg("text", `${pct}%`));
+    if (model.share < model.commitShare) parts.push(theme.fg("muted", `commit at ${Math.round(model.commitShare * 100)}%`));
+    else if (model.weighed) parts.push(theme.fg("muted", "commit held"));
+    else parts.push(theme.fg("warning", "COMMIT DUE"));
   }
+  // A COUNT FOR WHAT IS STAGED, TOKENS FOR WHAT FOLDING BOUGHT. Both figures are priced
+  // by the image law now (measurement.ts pricedBytes): "5.8M to free" beside a 1M window
+  // was 83 screenshots' base64 counted as text (Shane 2026-09-03). The unit is written
+  // out because pi's k/M format read as megabytes.
+  if (model.stagedMarks > 0) parts.push(ink.staged(`${model.stagedMarks} staged`));
   if (model.folds > 0) {
-    parts.push(ink.folded(`${model.folds} fold${model.folds === 1 ? "" : "s"} hold ${formatTokens(model.hiddenTokens)}`));
+    parts.push(ink.folded(`${model.folds} fold${model.folds === 1 ? "" : "s"} hide ${formatTokens(model.hiddenTokens)} tokens`));
   }
   // NO BRAND IN FRONT OF THE BAR (Shane 2026-09-02): the bar identifies itself, and the
   // two prose states above keep the brand because nothing else on them says whose they are.

package/package.json

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