pi-fold 4.1.3 → 4.1.5

package/README.md

@@ -33,14 +33,18 @@ The package registers one tool, `pi_fold_context`, with nine actions over the tr
 
 ### 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:
+In an interactive session one compact, full-height bar sits directly above Pi's footer.
 
 <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, 3 folds hide 412k tokens." src="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-bar-light.svg">
+  <img alt="A single full-height usage bar. Batlow colours group consolidated folds, span folds, tool folds, pinned content, marked content, and raw context in that order. The suffix shows percentage, commit point, and fold, pin, and mark counts." 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 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.
+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 in this order: **Consolidated Folds, Span Folds, Tool Folds, Pinned, Marked, Raw**. Compressed content uses the first half of [Crameri's Batlow palette](https://www.fabiocrameri.ch/colourmaps/); still-raw content uses the second half. Foreground lightness is adjusted for dark and light backgrounds, 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 Pin, Y Mark)`. `N Folds` counts visible compressed folds; `Pin` counts protected entries and `Mark` counts pending marks, 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.
+
+Matching dashed guides show `minTarget`, where a commit aims to land, and `maxTarget`, where automatic folding is triggered. 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.
 
 ## Results
 

package/extensions/active-context.ts

@@ -29,13 +29,13 @@ import {
   peekFoldSource,
   prepareFold,
   projectActiveContext,
+  renderFold,
   projectionSlateCandidates,
   protectEvidence,
   requireActiveFold,
   selectAutomaticRung,
   setFoldProjectionState,
   withExpandLease,
-  renderFoldParts,
 } from "./lib/folding.ts";
 import {
   admissionVerdict,
@@ -52,6 +52,7 @@ import {
   orderedRoots,
   parseNativeCompactionCompletion,
   exactMapped,
+  foldInterval,
   parseNativeCompactionDecision,
   parseProviderContextMeasurementReceipt,
   persistenceProjection,
@@ -63,7 +64,7 @@ import {
   stringIds,
   toolPayload,
 } from "./lib/measurement.ts";
-import { renderFoldBar, type FoldBarModel } from "./lib/status-widget.ts";
+import { emptyFoldBarMass, renderFoldBar, type FoldBarKind, type FoldBarModel } from "./lib/status-widget.ts";
 import type {
   NativeCompactionCompletionReceipt,
   NativeCompactionDecisionReceipt,
@@ -89,6 +90,7 @@ import {
   sameStateProjection,
   semanticStateSha256,
   topologySha256,
+  adoptDurableFoldRecords,
 } from "./lib/persistence.ts";
 import type { MaterializedStatePersistence } from "./lib/persistence.ts";
 import {
@@ -716,7 +718,7 @@ export function registerActiveContext(pi: any, options: {
    * named only when it is close enough to matter.
    */
   /**
-   * THE FOLD BAR (2026-09-02, dogfooding). One widget row directly above the footer,
+   * 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
@@ -729,8 +731,8 @@ export function registerActiveContext(pi: any, options: {
     /** 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>(),
+    /** Display-only reconstruction while waiting for the first real context event. */
+    startupSnapshot: null as ActiveContextSnapshot | null,
   };
   const installFoldBar = (ctx: any): void => {
     if (foldBar.installed || typeof ctx.ui?.setWidget !== "function") return;
@@ -738,6 +740,8 @@ export function registerActiveContext(pi: any, options: {
     ctx.ui.setWidget(entryTypePrefix, (tui: any) => {
       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; },
         render(width: number): string[] {
           if (!foldBar.model) return [];
           try { return [renderFoldBar(foldBar.model, width, ctx.ui.theme)]; }
@@ -748,7 +752,7 @@ export function registerActiveContext(pi: any, options: {
     }, { placement: "belowEditor" });
   };
   const foldBarModel = (ctx: any, input: {
-    share: number | null; budgetTokens: number; staged: number; roots: number; weighed: boolean;
+    share: number | null; staged: number; weighed: boolean;
   }): FoldBarModel => {
     const state = persistence.state;
     // THE SAME SNAPSHOT /fold-status PRICES AGAINST. `markFreedBytes` answers ZERO, silently,
@@ -757,46 +761,81 @@ export function registerActiveContext(pi: any, options: {
     // "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;
+    let snapshot = lifecycle.latestSnapshot ?? foldBar.startupSnapshot;
     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;
-      // 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 {
+    const model: FoldBarModel = {
       brand: brandNoun,
       share: input.share,
       commitShare: thresholds.maxTarget,
       aimShare: thresholds.minTarget,
-      stagedShare: stagedTokens / budget,
+      mapped: false, mass: emptyFoldBarMass(),
       stagedMarks: input.staged,
-      stagedTokens,
-      foldedShare: estimatedTokens(placeholderChars) / budget,
-      folds: input.roots,
-      hiddenTokens: estimatedTokens(hiddenChars),
+      folds: 0, foldSpans: 0, foldTruncations: 0, foldConsolidations: 0,
+      unplacedItems: 0,
+      pinnedRefs: state ? state.protected.length : 0,
       weighed: input.weighed,
       staleAfterCommit: input.share !== null && foldBar.staleSince !== null &&
         foldBar.staleSince === measurements.lastProviderMeasurement,
       stopped: ladder.automaticFailure?.message ?? null,
     };
+    if (!state || !snapshot) return model;
+    model.mapped = true;
+    // Price the visible projection once per category, never a hidden fold's original
+    // source. Revealing a parent reveals its parts, not necessarily every descendant.
+    // Correct inclusive intervals prevent the last hidden message being priced as raw.
+    const visibleAt = new Map<number, { fold: ActiveFold; end: number }>();
+    const byId = new Map(state.folds.map((fold) => [fold.id, fold]));
+    const visit = (fold: ActiveFold, interval: { start: number; end: number } | null): void => {
+      if (!interval) { model.unplacedItems += 1; return; }
+      const revealed = state.expanded.includes(fold.id) || refsProtected(flattenFoldRefs(fold, state), state, snapshot);
+      if (revealed) {
+        for (const part of fold.parts) {
+          if (part.kind !== "fold") continue;
+          const child = byId.get(part.foldId);
+          if (child) visit(child, foldInterval(child, state, snapshot));
+        }
+        return;
+      }
+      visibleAt.set(interval.start, { fold, end: interval.end });
+      model.folds += 1;
+      if (fold.kind === "chapter") model.foldSpans += 1;
+      else if (fold.kind === "tool-result") model.foldTruncations += 1;
+      else model.foldConsolidations += 1;
+    };
+    const roots = orderedRoots(state, snapshot);
+    const placedRoots = new Set(roots.map((root) => root.fold.id));
+    model.unplacedItems += state.folds.filter((fold) => !fold.parentId && !placedRoots.has(fold.id)).length;
+    for (const root of roots) visit(root.fold, root);
+
+    // Resolve all marks before walking roots: a pending consolidation can begin at a
+    // root and include raw gaps farther on. Membership, not an encountered start edge,
+    // determines Mark. A set also prevents overlapping marks charging a message twice.
+    const marked = new Set<number>();
+    for (const mark of pendingMarks(state)) {
+      const span = markSpanRefs(state, mark);
+      const indices = span.refs.map((ref) => exactMapped(snapshot, ref)?.index ?? -1);
+      if (span.unresolved || !indices.length || indices.some((index) => index < 0)) {
+        model.unplacedItems += 1;
+        continue;
+      }
+      for (const index of indices) marked.add(index);
+    }
+    const pinnedKeys = new Set(state.protected.map(objectRefKey));
+    for (let index = 0; index < snapshot.messages.length; index += 1) {
+      const root = visibleAt.get(index);
+      if (root) {
+        const kind: FoldBarKind = root.fold.kind === "chapter" ? "span"
+          : root.fold.kind === "tool-result" ? "tool" : "consolidated";
+        model.mass[kind] += pricedBytes(renderFold(root.fold, state, snapshot) ?? []);
+        index = root.end; // inclusive: advance PAST the final hidden message
+        continue;
+      }
+      const ref = snapshot.mapped[index]?.ref;
+      const kind: FoldBarKind = ref && pinnedKeys.has(objectRefKey(ref)) ? "pinned"
+        : marked.has(index) ? "marked" : "raw";
+      model.mass[kind] += pricedBytes([snapshot.messages[index]]);
+    }
+    return model;
   };
 
   const updateStatus = (ctx: any): void => {
@@ -810,7 +849,7 @@ export function registerActiveContext(pi: any, options: {
         installFoldBar(ctx);
         if (foldBar.installed) {
           foldBar.model = foldBarModel(ctx, {
-            share, budgetTokens: capacity.budgetTokens, staged, roots,
+            share, staged,
             weighed: ladder.bandTopMeasurement !== null &&
               ladder.bandTopMeasurement === measurements.lastProviderMeasurement,
           });
@@ -1041,6 +1080,7 @@ export function registerActiveContext(pi: any, options: {
     cancelPreparation();
     lifecycle.latestSnapshot = null;
     lifecycle.latestSnapshotError = null;
+    foldBar.startupSnapshot = null;
     measurements.latestRatio = null;
     measurements.lastProviderMeasurement = null;
     measurements.wallInflowSteps.length = 0;
@@ -1143,6 +1183,13 @@ export function registerActiveContext(pi: any, options: {
     );
     measurements.latestRatio = contextUsageRatio(measurements.lastProviderMeasurement);
     persistence.persisted = clone(durableRestored);
+    // Reuse Pi's own reconstructed messages, including custom messages and branch
+    // selection. This is ONLY a view for the bar: do not populate latestSnapshot,
+    // advance the frontier, persist a projection, or pretend a provider event occurred.
+    if (typeof ctx.ui?.setWidget === "function" && Array.isArray(restoredMessages)) {
+      try { foldBar.startupSnapshot = snapshotForEvent(ctx, restoredMessages); }
+      catch { /* Keep the honest mapping fallback if the host cannot supply a view. */ }
+    }
     if (restoreError) safeNotify(
       ctx,
       `Active-context state was ignored; Pi native context remains authoritative: ${String(restoreError)}`,
@@ -2528,6 +2575,11 @@ export function registerActiveContext(pi: any, options: {
       state: persistence.state!,
       generation: generationAtStart,
     });
+    const adoption = adoptDurableFoldRecords(nextState.folds, persistence.persistedFoldRecords);
+    if (adoption.adopted.length) {
+      emit("context.adopt", { adopted: adoption.adopted.length, fold_ids: adoption.adopted.slice(0, 64) });
+      return { preparedFold, nextState: { ...nextState, folds: adoption.folds } };
+    }
     return { preparedFold, nextState };
   };
 
@@ -2769,6 +2821,16 @@ export function registerActiveContext(pi: any, options: {
           clips: [...(result.state.clips ?? []), ...clipAdditions] } };
       }
     }
+    // A RE-CUT SPAN ADOPTS ITS DURABLE RECORD (persistence.ts, adoptDurableFoldRecords):
+    // a fold minted here under an id the store already holds, with the same source, takes
+    // the record's bytes before the projection is measured, so the persist path finds
+    // equal digests where session 01a06746 found "Conflicting durable active-context
+    // fold" and stopped folding for good.
+    const adoption = adoptDurableFoldRecords(result.state.folds, persistence.persistedFoldRecords);
+    if (adoption.adopted.length) {
+      result = { ...result, state: { ...result.state, folds: adoption.folds } };
+      emit("context.adopt", { adopted: adoption.adopted.length, fold_ids: adoption.adopted.slice(0, 64) });
+    }
     persistence.state = result.state;
     const bytesAfter = pricedBytes(projectActiveContext(snapshot, persistence.state));
     const freedBytes = Math.max(0, bytesBefore - bytesAfter);
@@ -2804,6 +2866,7 @@ export function registerActiveContext(pi: any, options: {
       closing_consolidation_marks: closingAdded,
       absorbed_wedges: wedges.absorbed.length,
       clipped_results: clippedResults,
+      adopted_records: adoption.adopted.length,
       freed_bytes: freedBytes,
       freed_tokens: estimatedTokens(freedBytes),
       rewrite_tokens: rewriteTokens,
@@ -3143,6 +3206,7 @@ export function registerActiveContext(pi: any, options: {
     try {
       const snapshot = snapshotForEvent(ctx, event.messages);
       lifecycle.latestSnapshot = snapshot;
+      foldBar.startupSnapshot = null;
       if (ladder.automaticFailure) {
         ladder.automaticFailure.suppressedCallbacks = Math.min(
           Number.MAX_SAFE_INTEGER,
@@ -4903,6 +4967,7 @@ export function registerActiveContext(pi: any, options: {
     curation.receipts = [];
     try { ctx.ui?.setStatus?.(entryTypePrefix, undefined); } catch { }
     foldBar.model = null;
+    foldBar.startupSnapshot = null;
     foldBar.requestRender?.();
   });
 

package/extensions/lib/folding.ts

@@ -1181,12 +1181,17 @@ export function activeContextStatus(
       sourceIdsTruncated: eligibleSourceIds.length > 64,
       startId: eligibleSourceIds[0],
       endId: eligibleSourceIds.at(-1),
-      action: { action: "fold", ids: eligibleEndpoints, brief: "<factual brief, at most 1000 characters>" },
+      action: { action: "reboundary", ids: eligibleEndpoints },
     } : null,
     currentTurnRequiresBoundary: false,
+    // EVERY ACTION ADVERTISED HERE IS ONE THE SCHEMA ACCEPTS (gate 168). This block named a
+    // "fold" action with a 1,000-character brief long after the schema had replaced it
+    // with reboundary and the cap had moved to the policy's; the model followed the page,
+    // was refused by the schema, and had to read the schema to learn the real name.
     actions: {
       status: { action: "status", offset, limit },
-      fold: { action: "fold", ids: ["<source-or-fold-id>"], brief: "<optional factual brief, at most 1000 characters>" },
+      reboundary: { action: "reboundary", ids: ["<source-or-fold-id>"] },
+      brief: { action: "brief", id: "<pending-fold-id>", brief: `<factual brief, at most ${ACTIVE_CONTEXT_POLICY.maxBriefChars} characters>` },
       pin: { action: "pin", ids: ["<source-or-fold-id>"] },
     },
   };

package/extensions/lib/measurement.ts

@@ -405,7 +405,9 @@ export function explicitProtectedMass(
   let refs = 0;
   for (const item of snapshot.mapped) {
     if (!item.ref || !explicit.has(objectRefKey(item.ref))) continue;
-    total += bytes(item.message);
+    // Priced, not counted: a pinned screenshot is one image against the pin cap and on
+    // the bar, not its base64 length (pricedBytes, gate 166's law).
+    total += pricedBytes([item.message]);
     refs += 1;
   }
   return { bytes: total, refs };

package/extensions/lib/persistence.ts

@@ -789,11 +789,44 @@ export function parseActiveContextStateV2(value: unknown, sessionId: string): Ac
   return parsed;
 }
 
+/**
+ * A RE-CUT SPAN ADOPTS ITS DURABLE RECORD (2026-09-04).
+ *
+ * A fold's id is derived from its parts, so the same span cut twice mints the same id,
+ * and a durable record under an id is immutable by design. Those two facts met in
+ * session 01a06746: a persistence projection on the first pass after a restart could
+ * not seat one consolidation root and dropped it with its 30 children, the spans read
+ * as raw, the frontier cut them again, and the re-cut folds differed from their records
+ * by 25 bytes of placeholder text. `normalizeFoldsForPersistedRecords` and the persist
+ * path both refused the conflict, folding suspended, and every restart walked into the
+ * same refusal because the durable state had already lost the folds.
+ *
+ * The record is the canonical fold for its source. A fold whose id has a record with
+ * the SAME kind and SAME source hash takes the record's bytes (brief, provenance,
+ * placeholder size, createdAt) and keeps only its own parent link, so the persist path
+ * finds equal digests and the session goes on. A record under the same id with a
+ * DIFFERENT source is a corrupt store and still refuses by name.
+ */
+export function adoptDurableFoldRecords(
+  folds: ActiveFold[],
+  records: Map<string, FoldRecordEntry>,
+): { folds: ActiveFold[]; adopted: string[] } {
+  const adopted: string[] = [];
+  const next = folds.map((fold) => {
+    const record = records.get(fold.id);
+    if (!record || sameFoldRecordIdentity(fold, record.fold)) return fold;
+    if (record.fold.kind !== fold.kind || record.fold.sourceSha256 !== fold.sourceSha256) return fold;
+    adopted.push(fold.id);
+    return { ...clone(record.fold), parentId: fold.parentId };
+  });
+  return { folds: next, adopted };
+}
+
 export function normalizeFoldsForPersistedRecords(
   folds: ActiveFold[],
   records: Map<string, FoldRecordEntry>,
 ): ActiveFold[] {
-  const normalized = folds.map((fold) => {
+  const normalized = adoptDurableFoldRecords(folds, records).folds.map((fold) => {
     const record = records.get(fold.id);
     if (!record) return clone(fold);
     if (!sameFoldRecordIdentity(fold, record.fold)) {

package/extensions/lib/status-widget.ts

@@ -1,91 +1,55 @@
-/**
- * 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.
- */
-
+/** One full-height usage bar, coloured by six disjoint content categories. */
 import { truncateToWidth } from "@earendil-works/pi-tui";
 
 export const FOLD_BAR_WIDTH = 40;
+// The first half of Batlow is compressed; the second half is still raw.
+export const FOLD_BAR_KINDS = ["consolidated", "span", "tool", "pinned", "marked", "raw"] as const;
+export type FoldBarKind = typeof FOLD_BAR_KINDS[number];
+export type FoldBarMass = Record<FoldBarKind, number>;
+export const emptyFoldBarMass = (): FoldBarMass => ({ consolidated: 0, span: 0, tool: 0, pinned: 0, marked: 0, raw: 0 });
 
-/** 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;
+  /** Estimated visible mass, counted exactly once, in the category order above. */
+  mass: FoldBarMass;
+  mapped: boolean;
   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. */
+  foldSpans: number;
+  foldTruncations: number;
+  foldConsolidations: number;
+  pinnedRefs: number;
+  stagedMarks: number;
+  unplacedItems: number;
   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;
 }
-
-/** The subset of pi's Theme the row uses. */
 export interface FoldBarTheme {
-  fg(color: "dim" | "muted" | "text" | "warning" | "error", text: string): string;
+  fg(color: "dim" | "muted" | "text" | "warning" | "error" | "accent", text: string): string;
   bold(text: string): string;
   getColorMode?(): "truecolor" | "256color";
-  getFgAnsi?(color: "text"): string;
+  getFgAnsi?(color: "text" | "muted" | "accent"): string;
   name?: string;
 }
 
-// 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;
+// Batlow samples at 0, .2, .4 | .6, .8, 1, in the requested category order.
+// Static foreground lightness adjustments retain readable labels on dark/white
+// reference backgrounds. No palette generator or new dependency ships.
+const ON_DARK: Record<FoldBarKind, string> = {
+  consolidated: "#6C89C7", span: "#5B919F", tool: "#729261",
+  pinned: "#B38E2F", marked: "#FBA689", raw: "#FACCFA",
+};
+const ON_LIGHT: Record<FoldBarKind, string> = {
+  consolidated: "#011959", span: "#185562", tool: "#577647",
+  pinned: "#927012", marked: "#AA624A", raw: "#8F6891",
+};
 
-/**
- * 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);
+    const match = /38;2;(\d+);(\d+);(\d+)/.exec(theme.getFgAnsi?.("text") ?? "");
     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;
@@ -93,116 +57,117 @@ export function lightBackground(theme: FoldBarTheme): boolean {
   } catch { }
   return /light/i.test(theme.name ?? "");
 }
-
 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`;
+  const rgb = [1, 3, 5].map((at) => parseInt(hex.slice(at, at + 2), 16));
+  return `\x1b[38;2;${rgb.join(";")}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");
+/** Two half-cell samples per terminal column. The measured fill never grows to fit
+ * inventory. Each nonempty CATEGORY gets one half-cell when there is room, then quotas
+ * follow relative mass. This is a visibility floor, not a per-fold width or token-exact
+ * proportion. Both halves of a guide column are reserved so it cannot erase a category.
+ */
+export function foldBarCells(model: FoldBarModel, width = FOLD_BAR_WIDTH): Array<FoldBarKind | "empty" | "unknown" | "tick"> {
+  const samples = 2 * width;
+  const filled = Math.max(0, Math.min(samples, Math.round((model.share ?? 0) * samples)));
+  const ticks = foldBarTicks(model, width);
+  const total = FOLD_BAR_KINDS.reduce((sum, kind) => sum + model.mass[kind], 0);
+  const cells: Array<FoldBarKind | "empty" | "unknown" | "tick"> = Array.from({ length: samples }, (_, i) =>
+    ticks.has(Math.floor(i / 2)) ? "tick" : i < filled ? "unknown" : "empty");
+  const slots = cells.flatMap((kind, i) => kind === "unknown" ? [i] : []);
+  if (!model.mapped || total <= 0 || !slots.length) return cells;
+  const allocation = FOLD_BAR_KINDS.filter((kind) => model.mass[kind] > 0)
+    .map((kind) => ({ kind, quota: model.mass[kind] * slots.length / total, count: 0 }));
+  if (slots.length < allocation.length) {
+    // At very low occupancy there may be fewer slots than kinds. Keep the largest
+    // shares rather than inventing occupancy; ties keep the declared category order.
+    for (const item of [...allocation].sort((a, b) => b.quota - a.quota).slice(0, slots.length)) item.count = 1;
+  } else {
+    for (const item of allocation) item.count = Math.max(1, Math.floor(item.quota));
+    let assigned = allocation.reduce((sum, item) => sum + item.count, 0);
+    while (assigned !== slots.length) {
+      const direction = assigned < slots.length ? 1 : -1;
+      const candidates = allocation.filter((item) => direction > 0 || item.count > 1);
+      candidates.sort((a, b) => direction * ((b.quota - b.count) - (a.quota - a.count)));
+      candidates[0].count += direction;
+      assigned += direction;
+    }
+  }
+  let next = 0;
+  for (const item of allocation) {
+    for (let n = 0; n < item.count; n += 1) cells[slots[next++]] = item.kind;
   }
   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"> {
+export function foldBarTicks(model: FoldBarModel, width = 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;
+  return new Map([[at(model.aimShare), "aim"], [at(model.commitShare), "commit"]]);
 }
-
-/** 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,
-  });
+  return renderFoldBar(model, Number.POSITIVE_INFINITY, { fg: (_c, t) => t, bold: (t) => t });
 }
 
 export function renderFoldBar(model: FoldBarModel, width: number, theme: FoldBarTheme): string {
+  const cut = (text: string): string => truncateToWidth(text, width, theme.fg("dim", "..."));
+  const neutral = (text: string): string => theme.fg("text", text);
+  const muted = (text: string): string => theme.fg("muted", text);
   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 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),
-    folded: (t) => rich ? truecolor(BATLOW.folded, t) : theme.fg("dim", t),
-    empty: (t) => theme.fg("dim", t),
+  if (model.stopped) return cut(`${brand} ${theme.fg("error", theme.bold("FOLDING STOPPED"))}` +
+    (model.share === null ? "" : neutral(` · ${Math.round(model.share * 100)}% full`)));
+  if (model.share === null) return cut(`${brand} ${muted(`not measured yet · folds automatically at ${Math.round(model.commitShare * 100)}%`)}`);
+  const palette = lightBackground(theme) ? ON_LIGHT : ON_DARK;
+  const ink = (kind: FoldBarKind, text: string): string => {
+    if (theme.getColorMode?.() === "truecolor") return truecolor(palette[kind], text);
+    if (kind === "pinned") return theme.fg("accent", text);
+    return theme.fg(kind === "raw" ? "muted" : "text", text);
   };
   const cells = foldBarCells(model);
-  const ticks = foldBarTicks(model);
+  const solid = (kind: typeof cells[number]): string => {
+    if (kind === "tick") return neutral(theme.bold("┆"));
+    if (kind === "empty") return theme.fg("dim", "░");
+    if (kind === "unknown") return muted("█");
+    return ink(kind, "█");
+  };
+  const background = (kind: FoldBarKind): string | null => {
+    if (theme.getColorMode?.() === "truecolor") return truecolor(palette[kind], "").replace("[38;", "[48;");
+    // Pi exposes the same theme ink in 256-colour mode. Convert its foreground escape
+    // to background, without assuming an RGB theme or leaking styles into the label.
+    const fg = theme.getFgAnsi?.(kind === "pinned" ? "accent" : kind === "raw" ? "muted" : "text") ?? "";
+    const extended = /^\x1b\[38;(?:2;\d+;\d+;\d+|5;\d+)m$/.test(fg);
+    if (extended) return fg.replace("[38;", "[48;");
+    const basic = /^\x1b\[(3[0-7]|9[0-7])m$/.exec(fg);
+    return basic ? `\x1b[${Number(basic[1]) + 10}m` : null;
+  };
   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]]);
+  for (let i = 0; i < cells.length; i += 2) {
+    const left = cells[i], right = cells[i + 1];
+    if (left === right) { bar += solid(left); continue; }
+    // One full-height left-half glyph, right colour supplied by the cell background:
+    // two colours in one column, never a notch, gap, score, or extra terminal column.
+    if (right === "empty") {
+      bar += left === "unknown" ? muted("▌") : ink(left as FoldBarKind, "▌");
+    } else {
+      const bg = background(right as FoldBarKind);
+      bar += bg ? `${bg}${ink(left as FoldBarKind, "▌")}\x1b[49m` : solid(left);
+    }
   }
   const pct = Math.round(model.share * 100);
   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"} hide ${formatTokens(model.hiddenTokens)} tokens`));
+  if (model.staleAfterCommit) parts.push(muted(`${pct}% before the commit`));
+  else {
+    const when = model.share < model.commitShare ? `commit at ${Math.round(model.commitShare * 100)}%`
+      : model.weighed ? "commit held" : "at commit point";
+    parts.push(neutral(`${pct}%`), muted(when));
   }
-  // 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", "..."));
+  if (model.mapped) {
+    // N counts compressed folds. Pin/Mark are accompanying states, not added to N.
+    const counts = [
+      ink("consolidated", `${model.foldConsolidations} Cons.`), ink("span", `${model.foldSpans} Span`),
+      ink("tool", `${model.foldTruncations} Tool`), ink("pinned", `${model.pinnedRefs} Pin`),
+      ink("marked", `${model.stagedMarks} Mark`),
+    ];
+    parts.push(neutral(`${model.folds} Folds (`) + counts.join(muted(", ")) + neutral(")"));
+    if (model.unplacedItems > 0) parts.push(muted(`${model.unplacedItems} not mapped`));
+  } else parts.push(muted("mapping"));
+  return cut(`${bar} ${parts.join(theme.fg("dim", " · "))}`);
 }

package/package.json

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