pi-fold 4.1.0 → 4.1.1

package/README.md

@@ -31,6 +31,17 @@ A fold takes a contiguous span of session entries and replaces it, in the window
 
 The package registers one tool, `pi_fold_context`, with nine actions over the transcript: `status`, `peek`, `brief`, `expand`, `refold`, `pin`, `unpin`, `reboundary` and `unmark`. A session that never calls the tool still folds; it degrades into lossless hierarchical compaction.
 
+### The fold bar
+
+In an interactive session one row sits directly above Pi's footer and shows the window against the two points where something happens to it:
+
+<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">
+</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.
+
 ## Results
 
 One 64-stage assignment over the curl C repository, run as a single agentic turn. Same model, same 251,520-token serving budget, every run. After all 64 stages landed, one withheld message asked sixteen questions about material from across the whole session.

package/extensions/active-context.ts

@@ -61,6 +61,7 @@ import {
   stringIds,
   toolPayload,
 } from "./lib/measurement.ts";
+import { renderFoldBar, type FoldBarModel } from "./lib/status-widget.ts";
 import type {
   NativeCompactionCompletionReceipt,
   NativeCompactionDecisionReceipt,
@@ -706,6 +707,63 @@ export function registerActiveContext(pi: any, options: {
    * leads now, occupancy is a percentage of the serving budget, and the commit point is
    * named only when it is close enough to matter.
    */
+  /**
+   * THE FOLD BAR (2026-09-02, dogfooding). One widget 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
+   * each rebuild. Installed once per host UI, on the first update that finds one.
+   */
+  const foldBar = {
+    model: null as FoldBarModel | null,
+    installed: false,
+    requestRender: null as (() => void) | null,
+  };
+  const installFoldBar = (ctx: any): void => {
+    if (foldBar.installed || typeof ctx.ui?.setWidget !== "function") return;
+    foldBar.installed = true;
+    ctx.ui.setWidget(entryTypePrefix, (tui: any) => {
+      foldBar.requestRender = () => { try { tui.requestRender(); } catch { } };
+      return {
+        render(width: number): string[] {
+          if (!foldBar.model) return [];
+          try { return [renderFoldBar(foldBar.model, width, ctx.ui.theme)]; }
+          catch { return []; }
+        },
+        invalidate() { },
+      };
+    }, { placement: "belowEditor" });
+  };
+  const foldBarModel = (input: {
+    share: number | null; budgetTokens: number; staged: number; roots: number; weighed: boolean;
+  }): FoldBarModel => {
+    const state = persistence.state;
+    const snapshot = lifecycle.latestSnapshot;
+    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);
+    }
+    const budget = input.budgetTokens > 0 ? input.budgetTokens : 1;
+    return {
+      brand: brandNoun,
+      share: input.share,
+      commitShare: thresholds.maxTarget,
+      aimShare: thresholds.minTarget,
+      stagedShare: stagedTokens / budget,
+      stagedMarks: input.staged,
+      stagedTokens,
+      foldedShare: estimatedTokens(placeholderChars) / budget,
+      folds: input.roots,
+      hiddenTokens: estimatedTokens(hiddenChars),
+      weighed: input.weighed,
+      stopped: ladder.automaticFailure?.message ?? null,
+    };
+  };
+
   const updateStatus = (ctx: any): void => {
     try {
       const roots = persistence.state && lifecycle.latestSnapshot ? orderedRoots(persistence.state, lifecycle.latestSnapshot).length : 0;
@@ -713,6 +771,17 @@ export function registerActiveContext(pi: any, options: {
       const capacity = currentCapacity(ctx);
       const used = measurements.lastProviderMeasurement?.tokens ?? null;
       const share = used !== null && capacity.budgetTokens > 0 ? used / capacity.budgetTokens : null;
+      try {
+        installFoldBar(ctx);
+        if (foldBar.installed) {
+          foldBar.model = foldBarModel({
+            share, budgetTokens: capacity.budgetTokens, staged, roots,
+            weighed: ladder.bandTopMeasurement !== null &&
+              ladder.bandTopMeasurement === measurements.lastProviderMeasurement,
+          });
+          foldBar.requestRender?.();
+        }
+      } catch { }
       const parts: string[] = [];
       // FAILURE LEADS. This line is cut to whatever width the host gives it, so the last
       // segment is the first one a narrow terminal removes, and folding having stopped is
@@ -754,7 +823,10 @@ export function registerActiveContext(pi: any, options: {
       }
       if (staged > 0) parts.push(`${staged} staged`);
       if (roots > 0) parts.push(`${roots} fold${roots === 1 ? "" : "s"}`);
-      ctx.ui?.setStatus?.(entryTypePrefix, `${brandNoun} ${parts.join(" · ")}`);
+      // ONE SURFACE, NOT TWO (Shane 2026-09-02, from a screenshot showing both). Where
+      // the fold bar widget is installed it carries every fact this string carries, so
+      // the string is withdrawn; a host without widgets keeps the string exactly as it was.
+      ctx.ui?.setStatus?.(entryTypePrefix, foldBar.installed ? undefined : `${brandNoun} ${parts.join(" · ")}`);
     } catch { }
   };
 
@@ -4791,6 +4863,8 @@ export function registerActiveContext(pi: any, options: {
     lifecycle.latestSnapshot = null;
     curation.receipts = [];
     try { ctx.ui?.setStatus?.(entryTypePrefix, undefined); } catch { }
+    foldBar.model = null;
+    foldBar.requestRender?.();
   });
 
   return { projectionCandidates };

package/extensions/lib/status-widget.ts

@@ -0,0 +1,175 @@
+/**
+ * THE FOLD BAR: one widget row above the footer, drawn by us rather than by the host.
+ *
+ * The always-on status line is a STRING handed to `ctx.ui.setStatus`, and everything a
+ * bar would need is denied to a string: the host sorts statuses by key and joins them,
+ * collapses runs of spaces, truncates from the right, and bakes ANSI that goes stale on a
+ * theme switch. `ctx.ui.setWidget` hands us a component instead: `render(width)` receives
+ * the terminal width, the row is ours alone, and the theme is read at render time so a
+ * `/theme` switch repaints it. Placed below the editor it sits directly above the footer,
+ * which is where Claude Code draws the same bar.
+ *
+ * WHAT THE BAR ARGUES: how full the window is against the two points where something
+ * happens to it. The fill is read against ticks ON the bar at the aim (minTarget) and the
+ * commit point (maxTarget). Inside the fill, oldest on the left: `▂` for the placeholders
+ * of standing folds, `▓` for staged raw spans (what the next commit collapses), `▇` for
+ * raw the ladder has not claimed. The label states what folding has already bought.
+ *
+ * THE BAR IS A FIXED WIDTH. A bar sized to the leftover width moves the commit tick
+ * between renders, and the tick is the landmark the whole row exists to place the fill
+ * against. What varies with the terminal is the label, cut from the right.
+ *
+ * WHAT IT WILL NOT DRAW: an unmeasured window (an empty bar is a guess drawn; law 2 of
+ * the human surfaces), a suspended session (no bar promising a commit beside FOLDING
+ * STOPPED; law 5), fold positions (a placeholder is a few hundred tokens against cells of
+ * tens of thousands), and fold depth, which /fold-editor shows with a row per fold.
+ *
+ * COLOUR: raw, staged and folded form an ordered ladder of how much of the window each
+ * state costs, so they are three classes sampled off Crameri's batlow, a perceptually
+ * uniform, colour-vision-deficiency-safe sequential map; on a 256-colour terminal they
+ * fall back to the theme's own names. Scaffolding (empty cells, the aim tick, the brand)
+ * stays on the theme's dim ink; the commit tick takes the theme's warning colour, which
+ * is what the host uses for its own context percentage past 70.
+ */
+
+import { truncateToWidth } from "@earendil-works/pi-tui";
+
+export const FOLD_BAR_WIDTH = 40;
+
+/** Everything the row reads. Built by the runtime on every status update. */
+export interface FoldBarModel {
+  brand: string;
+  /** The provider's own count against the serving budget, or null when unmeasured. */
+  share: number | null;
+  /** maxTarget and minTarget of the live thresholds, as shares. */
+  commitShare: number;
+  aimShare: number;
+  /** Share of the budget standing marks would free at the next commit (estimated). */
+  stagedShare: number;
+  stagedMarks: number;
+  stagedTokens: number;
+  /** Share of the budget the standing folds' placeholders occupy (estimated). */
+  foldedShare: number;
+  folds: number;
+  /** Tokens the standing folds hide: source minus placeholder, summed over the forest. */
+  hiddenTokens: number;
+  /** Whether a band-top commit has already been weighed against the current count. */
+  weighed: boolean;
+  /** The suspension message when automatic folding has stopped, else null. */
+  stopped: string | null;
+}
+
+/** The subset of pi's Theme the row uses. */
+export interface FoldBarTheme {
+  fg(color: "dim" | "muted" | "text" | "warning" | "error", text: string): string;
+  bold(text: string): string;
+  getColorMode?(): "truecolor" | "256color";
+}
+
+// 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;
+
+const truecolor = (hex: string, text: string): string => {
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  return `\x1b[38;2;${r};${g};${b}m${text}\x1b[39m`;
+};
+
+export function formatTokens(count: number): string {
+  if (count < 1000) return String(count);
+  if (count < 10_000) return `${(count / 1000).toFixed(1)}k`;
+  if (count < 1_000_000) return `${Math.round(count / 1000)}k`;
+  return `${(count / 1_000_000).toFixed(1)}M`;
+}
+
+type Cell = "folded" | "staged" | "raw" | "empty";
+// SCORED CELLS (Shane 2026-09-03): the README figure draws every cell as its own rectangle
+// with a hairline gap, and the full-width block fused adjacent cells into one solid run,
+// so the terminal read as a different figure. The left seven-eighths block leaves an
+// eighth of each cell empty on the right, which is the same score in a glyph. Staged and
+// raw share the glyph and differ by colour; the shade glyph is gone because at a small
+// font its texture read as a solid block anyway.
+const GLYPH: Record<Cell, string> = { folded: "▂", staged: "▉", raw: "▉", empty: "░" };
+
+/** The bar's cells, oldest on the left, before any tick is laid over them. */
+export function foldBarCells(model: FoldBarModel, width: number = FOLD_BAR_WIDTH): Cell[] {
+  const share = model.share ?? 0;
+  const filled = Math.max(0, Math.min(width, Math.round(share * width)));
+  const folded = Math.min(filled, Math.round(model.foldedShare * width));
+  const staged = Math.min(filled - folded, Math.round(model.stagedShare * width));
+  const cells: Cell[] = [];
+  for (let i = 0; i < width; i += 1) {
+    if (i < folded) cells.push("folded");
+    else if (i < folded + staged) cells.push("staged");
+    else if (i < filled) cells.push("raw");
+    else cells.push("empty");
+  }
+  return cells;
+}
+
+/** Tick positions: the cell whose right edge is the share. */
+export function foldBarTicks(model: FoldBarModel, width: number = FOLD_BAR_WIDTH): Map<number, "aim" | "commit"> {
+  const at = (share: number): number => Math.max(0, Math.min(width - 1, Math.round(share * width) - 1));
+  const ticks = new Map<number, "aim" | "commit">();
+  ticks.set(at(model.aimShare), "aim");
+  ticks.set(at(model.commitShare), "commit");
+  return ticks;
+}
+
+/** The row without colour, for tests and for a host that strips ANSI. */
+export function foldBarPlainText(model: FoldBarModel): string {
+  return renderFoldBar(model, Number.POSITIVE_INFINITY, {
+    fg: (_c, t) => t, bold: (t) => t,
+  });
+}
+
+export function renderFoldBar(model: FoldBarModel, width: number, theme: FoldBarTheme): string {
+  const brand = theme.fg("dim", model.brand);
+  if (model.stopped) {
+    const line = `${brand} ${theme.fg("error", theme.bold("FOLDING STOPPED"))}` +
+      (model.share === null ? "" : theme.fg("text", ` · ${Math.round(model.share * 100)}% full`));
+    return truncateToWidth(line, width, theme.fg("dim", "..."));
+  }
+  if (model.share === null) {
+    return truncateToWidth(
+      `${brand} ${theme.fg("muted", `not measured yet · folds automatically at ${Math.round(model.commitShare * 100)}%`)}`,
+      width, theme.fg("dim", "..."));
+  }
+  const rich = theme.getColorMode?.() === "truecolor";
+  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),
+    folded: (t) => rich ? truecolor(BATLOW.folded, t) : theme.fg("dim", t),
+    empty: (t) => theme.fg("dim", t),
+  };
+  const cells = foldBarCells(model);
+  const ticks = foldBarTicks(model);
+  let bar = "";
+  for (let i = 0; i < cells.length; i += 1) {
+    const tick = ticks.get(i);
+    if (tick === "commit") bar += theme.fg("warning", "│");
+    else if (tick === "aim") bar += theme.fg("dim", "│");
+    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`));
+  }
+  if (model.folds > 0) {
+    parts.push(ink.folded(`${model.folds} fold${model.folds === 1 ? "" : "s"} hold ${formatTokens(model.hiddenTokens)}`));
+  }
+  // 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.
+  const line = `${bar} ${parts.join(theme.fg("dim", " · "))}`;
+  return truncateToWidth(line, width, theme.fg("dim", "..."));
+}

package/package.json

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