pi-fold 4.1.5 → 4.2.0

package/README.md

@@ -37,14 +37,14 @@ In an interactive session one compact, full-height bar sits directly above Pi's
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-bar-dark.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">
+  <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 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 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 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.
+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.
 
-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.
+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.
 
 ## Results
 
@@ -80,7 +80,7 @@ Four papers with figure sources, redacted per-request ledgers and campaign logs
 
 The one thing worth adding is a long-term memory store. Rotation and retention are different jobs: folding gets stale material out of the window, a store keeps what the session learned. A handoff summary tries to do both in one record, written once under time pressure, bounded by the window it has to fit in. Folding is the rotation half and only that half.
 
-Six options, and every other name is refused.
+Seven options, and every other name is refused.
 
 | Option | Default | Effect |
 | --- | --- | --- |
@@ -90,6 +90,7 @@ Six options, and every other name is refused.
 | `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. |
 | `noticeLeadShare` | `0.10` | How far below the commit trigger that notice speaks, as a share of the serving budget. A distance rather than a point, so it follows a band that moves. Read only when `preCommitNotice` is on. |
+| `palette` | `{ map: "batlow", start: 0, end: 1 }` | The fold bar's colours, and nothing about folding. `map` is one of `batlow`, `viridis`, `plasma`, `magma`, `cividis`; `start` and `end` are positions on it in `[0, 1]` for the most compressed and the pinned shade, which may not coincide and may run backwards. Set whole or not at all. |
 
 Four commands ship for the human: `/fold-status`, `/fold` (commit every staged mark now), `/fold-editor` (the interactive map of the window) and `/fold-settings` (edit the options above; each change is saved to `~/.config/pi-fold/settings.json` and takes effect in the running session).
 

package/extensions/active-context.ts

@@ -64,7 +64,10 @@ import {
   stringIds,
   toolPayload,
 } from "./lib/measurement.ts";
-import { emptyFoldBarMass, renderFoldBar, type FoldBarKind, type FoldBarModel } from "./lib/status-widget.ts";
+import {
+  emptyFoldBarMass, renderFoldBar, resolveFoldBarPalette,
+  type FoldBarKind, type FoldBarModel, type FoldBarPalette,
+} from "./lib/status-widget.ts";
 import type {
   NativeCompactionCompletionReceipt,
   NativeCompactionDecisionReceipt,
@@ -82,6 +85,7 @@ import {
   makeStateCheckpoint,
   makeStateDelta,
   MAX_ACTIVE_FOLD_RECORDS,
+  MAX_DELTAS_BETWEEN_CHECKPOINTS,
   materializeStatePersistence,
   foldProvenance,
   normalizeFoldsForPersistedRecords,
@@ -115,7 +119,7 @@ import {
   ESTIMATED_BYTES_PER_TOKEN,
   IMAGE_ESTIMATED_TOKENS,
   entryTypeNamespace,
-  MAX_FOLD_SPAN_CHARS,
+  chapterSpanCap,
   DEFAULT_TOOL_FOLD_THRESHOLD,
   MAX_PINNED_SHARE,
   PEEK_DEFAULT_MAX_BYTES,
@@ -303,6 +307,12 @@ export function registerActiveContext(pi: any, options: {
    *  rather than a point, so it tracks a band that moves. Read only when preCommitNotice
    *  is true. */
   noticeLeadShare?: number;
+  /** THE FOLD BAR'S COLOURS (2026-09-06, Shane): which colour map the status bar shades
+   *  its five folded-to-raw categories from and where on that map the two ends of the
+   *  ramp sit. A display preference: it moves nothing about folding, and it is here only
+   *  because the settings file is handed to registration whole. Absent means Batlow end
+   *  to end. */
+  palette?: FoldBarPalette;
 }): {
   projectionCandidates: (ctx: any) => Array<Record<string, unknown>>;
 } {
@@ -320,6 +330,7 @@ export function registerActiveContext(pi: any, options: {
   let preCommitNotice = resolvedPreCommitNotice(options.preCommitNotice);
   let noticeLeadShare = resolveNoticeLeadShare(options.noticeLeadShare);
   let toolFoldThreshold = resolvedToolFoldThreshold(options.toolFoldThreshold);
+  let palette = resolveFoldBarPalette(options.palette);
   // THE RENAMED OPTION IS REFUSED BY NAME, not ignored (2026-08-30). postFoldNotice was
   // public for three days and named a carrier that no longer exists in that shape: it
   // fired on a fold count, after the cut, and asked for briefs. Silently accepting the
@@ -422,6 +433,14 @@ export function registerActiveContext(pi: any, options: {
     state: null as ActiveContextState | null,
     persisted: null as ActiveContextState | null,
     persistedWireVersion: 0 as 0 | 1 | 2,
+    /** Set when the branch HELD durable state this build could not read. Distinct from a
+     *  session that never had any, which is what `persistedWireVersion` 0 also means and
+     *  which legitimately writes the first checkpoint. See `persist`. */
+    lineageUnreadable: false,
+    /** Deltas standing after the newest checkpoint in the branch. See
+     *  `MAX_DELTAS_BETWEEN_CHECKPOINTS`: at the bound, `persist` writes a checkpoint instead
+     *  of a delta, which is what keeps a load's replay bounded. */
+    deltasSinceCheckpoint: 0,
     persistedStateSha256: "",
     persistedFoldRecords: new Map<string, FoldRecordEntry>(),
     persistenceQueue: Promise.resolve<void>(undefined),
@@ -777,6 +796,7 @@ export function registerActiveContext(pi: any, options: {
       staleAfterCommit: input.share !== null && foldBar.staleSince !== null &&
         foldBar.staleSince === measurements.lastProviderMeasurement,
       stopped: ladder.automaticFailure?.message ?? null,
+      palette,
     };
     if (!state || !snapshot) return model;
     model.mapped = true;
@@ -928,6 +948,7 @@ export function registerActiveContext(pi: any, options: {
     const nextToolFoldThreshold = resolvedToolFoldThreshold(settings?.toolFoldThreshold);
     const nextPreCommitNotice = resolvedPreCommitNotice(settings?.preCommitNotice);
     const nextNoticeLeadShare = resolveNoticeLeadShare(settings?.noticeLeadShare);
+    const nextPalette = resolveFoldBarPalette(settings?.palette);
     const changed: string[] = [];
     for (const field of ["maxTarget", "minTarget", "consolidateAfter", "minFoldChars"] as const) {
       if (nextThresholds[field] !== thresholds[field]) changed.push(field);
@@ -935,6 +956,7 @@ export function registerActiveContext(pi: any, options: {
     if (nextToolFoldThreshold !== toolFoldThreshold) changed.push("toolFoldThreshold");
     if (nextPreCommitNotice !== preCommitNotice) changed.push("preCommitNotice");
     if (nextNoticeLeadShare !== noticeLeadShare) changed.push("noticeLeadShare");
+    if (nextPalette.map !== palette.map || nextPalette.start !== palette.start || nextPalette.end !== palette.end) changed.push("palette");
     // A SAVE THAT MOVED NOTHING IS NOT AN EVENT. The screen saves every keystroke that
     // lands, including a row stepped back to where it started.
     if (!changed.length) return;
@@ -942,6 +964,7 @@ export function registerActiveContext(pi: any, options: {
     toolFoldThreshold = nextToolFoldThreshold;
     preCommitNotice = nextPreCommitNotice;
     noticeLeadShare = nextNoticeLeadShare;
+    palette = nextPalette;
     dropDerivationMemo();
     // THE STREAM CARRIES IT, because from here on the session's commits fire at a point
     // no earlier record explains, and an archive reading this run later has no other way
@@ -955,6 +978,7 @@ export function registerActiveContext(pi: any, options: {
       tool_fold_threshold: toolFoldThreshold,
       pre_commit_notice: preCommitNotice,
       notice_lead_share: noticeLeadShare,
+      palette: { ...palette },
     });
     // The person is standing in the settings screen, so the line they will look at next
     // is the status line. Without this it keeps the old number until a context event.
@@ -1172,7 +1196,19 @@ export function registerActiveContext(pi: any, options: {
     }
     const durableRestored = restored ?? emptyActiveContextState(sessionId);
     persistence.state = durableRestored.prepared ? clearPrepared(durableRestored) : clone(durableRestored);
+    // AN UNREADABLE LINEAGE IS NOT AN EMPTY ONE (2026-09-07). `persistedWireVersion` reads
+    // 0 for both, and `persist` writes a CHECKPOINT whenever it is not 2, so a restore that
+    // threw put a second checkpoint into a branch that already had one. The reader refuses
+    // exactly that ("Duplicate active-context v2 checkpoint"), so the next load threw too,
+    // and wrote a third. ONE TRANSIENT FAILURE OF ANY CAUSE LATCHED THE SESSION DEAD AND
+    // EVERY RELOAD MADE IT STRICTLY WORSE: a real session reached five checkpoints, four of
+    // them from four /reload presses inside eleven minutes, and grew from 859 entries to
+    // 4,393 because each restart also re-cut the same spans and wrote fold records under
+    // the same ids with drifted bytes, 48 of 85 ids left conflicting. The two states are
+    // told apart here, once, rather than at each of `persist`'s callers.
+    persistence.lineageUnreadable = restoreError !== null;
     persistence.persistedWireVersion = restoredPersistence?.wireVersion ?? 0;
+    persistence.deltasSinceCheckpoint = restoredPersistence?.deltasSinceCheckpoint ?? 0;
     persistence.persistedFoldRecords = restoredPersistence?.records ?? new Map<string, FoldRecordEntry>();
     persistence.persistedStateSha256 = restoredPersistence?.stateSha256 ?? semanticStateSha256(durableRestored);
     const restoredMessages = ctx.sessionManager.buildSessionContext?.()?.messages;
@@ -1190,11 +1226,19 @@ export function registerActiveContext(pi: any, options: {
       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)}`,
-      "warning",
-    );
+    // The warning names the CONSEQUENCE and not only the cause: "state was ignored" read as
+    // graceful degradation, and the session it described could no longer fold at all. The
+    // suspension carries no ctx of its own so the canonical `context.suspend` record is
+    // emitted for a headless host without a second UI line saying the same thing twice.
+    if (restoreError) {
+      safeNotify(
+        ctx,
+        "Active-context state could not be read, so folding is suspended for this session and " +
+        `Pi native context remains authoritative: ${String(restoreError)}`,
+        "warning",
+      );
+      suspendAutomatic(restoreError, "restore", undefined);
+    }
     if (measurementRestoreError) safeNotify(
       ctx,
       `Malformed provider measurement receipt was ignored; automatic context remains unmeasured: ${String(measurementRestoreError)}`,
@@ -1205,6 +1249,18 @@ export function registerActiveContext(pi: any, options: {
   const persist = (ctx?: any): Promise<void> => {
     const operation = persistence.persistenceQueue.then(async () => {
       if (!persistence.state || !persistence.persisted) return;
+      // THE ONE WRITE THAT MUST NOT HAPPEN. Folding is suspended the moment a restore fails,
+      // so nothing automatic reaches this; a manual action still can, and one appended state
+      // entry is all it takes to latch the session. Raising rather than returning keeps the
+      // law of the discarded commit: a write that cannot land says so instead of vanishing,
+      // and the manual path already restores the state it entered with and reports.
+      if (persistence.lineageUnreadable) {
+        throw new Error(
+          "Active-context durable state is unreadable for this session, so no state may be " +
+          "written: a checkpoint here would be the second in this branch and would make every " +
+          "later load fail",
+        );
+      }
       let next = clone(persistence.state);
       const persistedFoldIds = new Set(persistence.persisted.folds.map((fold) => fold.id));
       const arrivingFoldIds = next.folds.filter((fold) => !persistedFoldIds.has(fold.id)).map((fold) => fold.id);
@@ -1272,7 +1328,15 @@ export function registerActiveContext(pi: any, options: {
           throw new Error("Active-context session changed after fold-record persistence");
         }
       }
-      const wire = persistence.persistedWireVersion === 2 ? makeStateDelta(persistence.persisted, next) : makeStateCheckpoint(next);
+      // A CHECKPOINT ENDS THE RUN THE READER WOULD OTHERWISE WALK (2026-09-20). A delta is
+      // the cheap write and stays the common one; at the bound the run is closed instead, so
+      // the next load replays at most `MAX_DELTAS_BETWEEN_CHECKPOINTS` deltas however long the
+      // session runs. A session that is already past the bound when this build first reads it
+      // closes its run on this write, so it pays the long load once and never again.
+      const runIsLong = persistence.deltasSinceCheckpoint >= MAX_DELTAS_BETWEEN_CHECKPOINTS;
+      const wire = persistence.persistedWireVersion === 2 && !runIsLong
+        ? makeStateDelta(persistence.persisted, next)
+        : makeStateCheckpoint(next);
       // THE WIRE CARRIES BOTH DIGESTS IT JUST DERIVED (2026-08-28). `makeStateDelta` writes
       // `baseStateSha256` from `persistence.persisted` and `stateSha256` from `next`, and
       // nothing mutates either state between that call and here, so re-hashing two whole
@@ -1286,6 +1350,7 @@ export function registerActiveContext(pi: any, options: {
       await pi.appendEntry(stateEntryType, wire);
       persistence.persisted = clone(next);
       persistence.persistedWireVersion = 2;
+      persistence.deltasSinceCheckpoint = wire.kind === "checkpoint" ? 0 : persistence.deltasSinceCheckpoint + 1;
       persistence.persistedStateSha256 = wire.stateSha256;
       persistence.state = lifecycle.shuttingDown ? null : clone(next);
       if (!sessionIdentityStillValid(ctx, sessionId, generationAtStart)) {
@@ -4132,7 +4197,7 @@ export function registerActiveContext(pi: any, options: {
               last: rollback.last ? clone(rollback.last) : null,
             },
           },
-          foldSpanCap: MAX_FOLD_SPAN_CHARS,
+          foldSpanCap: chapterSpanCap(thresholds.minFoldChars),
           projectionBudgetTokens: currentCapacity(ctx).budgetTokens,
           projectionCharsPerToken: projectionCharsPerToken(),
           projectionEstimatorErrorShare: estimatorErrorShare(),

package/extensions/index.js

@@ -11,7 +11,7 @@ export {
 
 const PUBLIC_OPTIONS = Object.freeze([
   "thresholds", "providerInputBudget", "blacklistAutoFoldTools", "toolFoldThreshold",
-  "preCommitNotice", "noticeLeadShare",
+  "preCommitNotice", "noticeLeadShare", "palette",
 ]);
 
 const GENERATOR_DELETED = "the model brief generator is deleted (2026-08-14): across 15 sealed " +

package/extensions/lib/folding.ts

@@ -51,7 +51,7 @@ import {
   CONTEXT_STATUS_RESPONSE_BYTES,
   EXPAND_LEASE_GENERATIONS,
   MAX_EXPAND_LEASES,
-  MAX_FOLD_SPAN_CHARS,
+  chapterSpanCap,
   PEEK_DEFAULT_MAX_BYTES,
   PEEK_HEAD_SHARE,
   STATUS_DIET_INDEX_ROWS,
@@ -95,6 +95,10 @@ export function selectAutomaticChapter(
   // The maturity floor: a stale span may end only where the batch lane has already had
   // its chance, so a chapter can never claim a tool batch one turn before it qualifies.
   const matureEnd = staleSpanMatureEnd(snapshot.messages);
+  // THE CAP FOLLOWS THE FLOOR: a multi-unit span may not pass it, and it sits at least
+  // one floor above `minFoldChars` so the accumulate-until-over walk below can always
+  // land between the two (policy.ts, chapterSpanCap).
+  const spanCap = chapterSpanCap(snapshot.thresholds.minFoldChars);
   for (let unitIndex = 0; unitIndex < units.length; unitIndex += 1) {
     const first = units[unitIndex];
     if (first.end > matureEnd) break;
@@ -131,12 +135,12 @@ export function selectAutomaticChapter(
       if (claimed.size && refs.some((ref) => claimed.has(objectRefKey(ref)))) break;
       if (refsProtected(refs, state, snapshot)) break;
       const size = bytes(encodedFoldSource(snapshot, state, parts, "chapter"));
-      const biteSized = size <= MAX_FOLD_SPAN_CHARS || endIndex === unitIndex;
+      const biteSized = size <= spanCap || endIndex === unitIndex;
       // ACCUMULATE UNTIL OVER, never cut to hit the number. The walk grows the span one
       // whole unit at a time and records the first one that carries it past the floor,
       // so a fold is always at least minFoldChars and always ends on a message boundary.
       if (size >= snapshot.thresholds.minFoldChars && biteSized) best = { kind: "chapter", parts, sourceRefs: refs };
-      if (size > MAX_FOLD_SPAN_CHARS) break;
+      if (size > spanCap) break;
     }
     if (best) return best;
   }

package/extensions/lib/live-settings.ts

@@ -25,6 +25,7 @@
 // deployment) still agrees on the property.
 
 import type { ActiveContextThresholds } from "./policy.ts";
+import type { FoldBarPalette } from "./status-widget.ts";
 
 /**
  * What the settings screen hands the runtime: exactly the settings FILE's shape, where an
@@ -37,6 +38,7 @@ export interface LiveFoldSettings {
 	toolFoldThreshold?: number;
 	preCommitNotice?: boolean;
 	noticeLeadShare?: number;
+	palette?: FoldBarPalette;
 }
 
 /** Refuses by throwing, exactly as registration does, and leaves the runtime untouched. */

package/extensions/lib/persistence.ts

@@ -68,6 +68,53 @@ export const STATE_DELTA_V2_KEYS = [
 export const MAX_ACTIVE_FOLD_RECORD_BYTES = 256 * 1024;
 export const MAX_ACTIVE_STATE_EVENT_BYTES = 512 * 1024;
 export const MAX_ACTIVE_FOLD_RECORDS = 4_096;
+
+/**
+ * HOW MANY DELTAS MAY STAND BETWEEN CHECKPOINTS (2026-09-20).
+ *
+ * The v2 ledger was one checkpoint and then deltas for the life of the session, and
+ * `materializeStatePersistence` replays every one of them on every load. Each delta rebuilds
+ * the WHOLE state, so a load costs the delta count times the state size: quadratic in
+ * session length. Shane's noloss session 01a0ad40 reached 2,207 deltas and took 129.6s to
+ * restore, against 0.6s for pi to parse the same 93MB of entries; 01a0ba4e took 56.1s on
+ * 1,147 deltas. Doubling the entries quadrupled the time (3,987 entries 9.3s, 7,974 entries
+ * 38.8s) and the per-delta cost rose with it (7.5ms to 57.0ms), because what each delta
+ * re-walks is the state, not the delta. The load is also not paid once: `session_start`,
+ * `session_tree`, `session_compact` and a branch switch each pay it again, and
+ * `doubleEscapeAction: "tree"` puts it behind a keypress.
+ *
+ * A CHECKPOINT STATES THE WHOLE STATE, so a replay may start at the LAST one rather than the
+ * only one and never walk the run before it. That bounds a load at this many deltas instead
+ * of at the session's lifetime. Nothing is weakened by starting later: a checkpoint carries
+ * its own digest and the deltas after it still chain, so the final state is proven by the
+ * same equalities as before. What a later start gives up is re-proving revisions that were
+ * already proven when they were written, and the fingerprint map loses the revisions before
+ * the checkpoint, which its one reader already treats as absent (see `projectionFingerprints`).
+ *
+ * THE BOUND IS A TRADE, AND 50 IS WHERE IT WAS MEASURED. A checkpoint names every standing
+ * fold by id and digest, so it costs far more bytes than a delta: 237.9KB against a 2.55KB
+ * delta at 375 folds, 248.9KB against 3.34KB at 213. The load after a checkpoint is 0.34s and
+ * 0.20s for those two sessions, and each replayed delta adds about 85ms at 375 folds, so the
+ * bound sets both the worst load and the write overhead:
+ *
+ *   K=100   8.8s worst load   +93% state-ledger bytes   (+5.6% of the session file)
+ *   K= 50   4.4s worst load  +187% state-ledger bytes   (+11% of the session file)
+ *   K= 25   2.2s worst load  +374% state-ledger bytes   (+22% of the session file)
+ *
+ * The state ledger is a small part of a session (5.9MB of 01a0ad40's 93MB), which is why the
+ * percentages look worse against the ledger than against the file. 50 takes the worst load
+ * under five seconds and the average near two, for a tenth of the file, and a session already
+ * past the bound heals itself on its next durable write.
+ *
+ * WHAT WOULD MAKE THE BOUND STOP MATTERING is the per-delta cost itself, which is still the
+ * whole state: 23.8% of a profiled load is `structuredClone` and 34% is `stableStringify`
+ * under `semanticStateSha256`, both walking every standing fold on every delta. Neither is
+ * reachable without giving the reader one canonical fold object per id for the life of a
+ * materialization, so that the clone stops being per-delta and a serializer memo can hit at
+ * all. That is a change to the aliasing barrier gate 158 guards and is deliberately NOT made
+ * here; until it is, this constant is what bounds the load.
+ */
+export const MAX_DELTAS_BETWEEN_CHECKPOINTS = 50;
 export const MAX_ACTIVE_FOLD_PARTS = 1_024;
 export const MAX_ACTIVE_EXPANDED = 1_024;
 export const MAX_ACTIVE_PROTECTED = 1_024;
@@ -269,15 +316,54 @@ export function directFoldOwners(folds: readonly ActiveFold[]): Map<string, stri
   return owner;
 }
 
+/**
+ * A FOLD THIS MATERIALIZATION HAS ALREADY PROVEN, AND WILL NOT PROVE AGAIN (2026-09-20).
+ *
+ * The replay's cost was never the deltas, it was re-proving the whole forest at each one.
+ * `stateFromFoldRefs` runs per delta and ends in `parseActiveContextState`, so a session with
+ * 2,207 deltas and 400 standing folds recomputed 400 content addresses and flattened and
+ * hashed 400 fold subtrees 2,207 times over. Profiling a 1,147-delta load put 48.2% of all
+ * time inside `validateFoldForest` and 14.8% on `foldIdFor` alone.
+ *
+ * WHAT THE MARK ASSERTS, and why each half of it is already true:
+ *
+ *   The content address. `parseFoldRecordEntry` refuses a record unless
+ *   `fold.id === foldIdFor(fold.kind, fold.parts)`, and every fold reaching a marked forest
+ *   came out of `records` past that check, matched to its ref on `recordSha256`. The only
+ *   field `assignFoldParents` writes is `parentId`, which `foldIdFor` does not read. So the
+ *   recomputation could not reach a different verdict. This is the argument the 2026-08-28
+ *   `foldRecordRef` change already made in `persist`, applied on the reading side.
+ *
+ *   The source digest. This one is NOT implied by the record, so it is not skipped: it is
+ *   paid ONCE PER DISTINCT FOLD PER MATERIALIZATION instead of once per delta. A fold's
+ *   flattened refs are a pure function of its id, because the id pins kind and parts and each
+ *   child id pins its own subtree in turn, so a second computation over the same id is
+ *   arithmetic already done. `stateFromFoldRefs` marks only ids already proven against THIS
+ *   records map and leaves a newly arriving fold unmarked, so its digest is still checked, and
+ *   still inside `validateFoldForest` after the ownership loop that proves its children are
+ *   present. Error ordering is unchanged.
+ *
+ * KEYED ON OBJECT IDENTITY, like gate 160's VALIDATED_FORESTS, so nothing outside this module
+ * can present itself as proven. It carries none of gate 160's stated cost: a fold mutated in
+ * place is never marked, because the mark is applied to the objects `assignFoldParents` has
+ * just built and is read before `clone` hands the forest on.
+ */
+const RECORD_PROVEN_FOLDS = new WeakSet<ActiveFold>();
+const PROVEN_SOURCE_DIGESTS = new WeakMap<Map<string, FoldRecordEntry>, Set<string>>();
+
 export function validateFoldForest(folds: ActiveFold[]): ActiveFold[] {
   const rawValues = denseOwnArrayValues(folds);
   if (!rawValues || rawValues.some((fold) => !validFoldShape(fold))) {
     throw new Error("Invalid active-context fold forest shape");
   }
   const values = clone(rawValues) as ActiveFold[];
+  // READ OFF THE CALLER'S OBJECTS, BEFORE THE CLONE ABOVE COSTS US THE IDENTITY. `clone`
+  // preserves order, so the verdict for `values[i]` is the mark on `rawValues[i]`.
+  const proven = rawValues.map((fold) => RECORD_PROVEN_FOLDS.has(fold as ActiveFold));
   const byId = new Map<string, ActiveFold>();
-  for (const fold of values) {
-    if (fold.id !== foldIdFor(fold.kind, fold.parts) || byId.has(fold.id)) {
+  for (let index = 0; index < values.length; index += 1) {
+    const fold = values[index];
+    if ((!proven[index] && fold.id !== foldIdFor(fold.kind, fold.parts)) || byId.has(fold.id)) {
       throw new Error("Invalid active-context fold");
     }
     if (fold.kind === "tool-result" &&
@@ -304,7 +390,9 @@ export function validateFoldForest(folds: ActiveFold[]): ActiveFold[] {
   for (const fold of values) {
     if ((parent.get(fold.id) ?? null) !== fold.parentId) throw new Error(`Fold ${fold.id} parent drift`);
   }
-  for (const fold of values) {
+  for (let index = 0; index < values.length; index += 1) {
+    if (proven[index]) continue;
+    const fold = values[index];
     const refs = flattenFoldRefs(fold, { folds: values });
     if (fold.sourceSha256 !== sha256Value(refs)) throw new Error(`Fold ${fold.id} source digest drift`);
   }
@@ -890,13 +978,28 @@ export function stateFromFoldRefs(
     if (!record || record.recordSha256 !== ref.sha256) throw new Error(`Missing active-context fold record ${ref.id}`);
     return record.fold;
   });
+  const parented = assignFoldParents(folds);
+  // WHAT THIS MATERIALIZATION HAS ALREADY PROVEN IS MARKED; THE REST IS STILL PROVEN BELOW.
+  // See RECORD_PROVEN_FOLDS. A fold standing across deltas is marked from its second
+  // appearance on, so its content address and source digest are computed once for the whole
+  // replay rather than once per delta. A fold arriving now is deliberately left unmarked: its
+  // digest is checked by `validateFoldForest`, after the loop that proves its children are
+  // present, exactly where it was checked before.
+  let provenIds = PROVEN_SOURCE_DIGESTS.get(records);
+  if (!provenIds) {
+    provenIds = new Set<string>();
+    PROVEN_SOURCE_DIGESTS.set(records, provenIds);
+  }
+  for (const fold of parented) {
+    if (provenIds.has(fold.id)) RECORD_PROVEN_FOLDS.add(fold);
+  }
   const state: ActiveContextState = {
     version: 1,
     sessionId: wire.sessionId,
     revision: wire.revision,
     // `parseActiveContextState` at the end of this function validates the forest, so
     // validating it here as well was the same walk twice on one persist.
-    folds: assignFoldParents(folds),
+    folds: parented,
     expanded: clone(wire.expanded),
     protected: clone(wire.protected),
     tokensSinceToolFold: wire.tokensSinceToolFold ?? 0,
@@ -907,7 +1010,10 @@ export function stateFromFoldRefs(
     ...(wire.advisory === undefined ? {} : { advisory: clone(wire.advisory) }),
     ...(wire.prepared === null || wire.prepared === undefined ? {} : { prepared: clone(wire.prepared) }),
   };
-  return parseActiveContextState(state, wire.sessionId, false);
+  const parsed = parseActiveContextState(state, wire.sessionId, false);
+  // RECORDED ONLY ONCE THE FOREST HAS PASSED, so a throw leaves nothing marked as proven.
+  for (const fold of parented) provenIds.add(fold.id);
+  return parsed;
 }
 
 export interface ProjectionFingerprint {
@@ -933,6 +1039,12 @@ export interface MaterializedStatePersistence {
   records: Map<string, FoldRecordEntry>;
   stateSha256: string;
   projectionFingerprints: ProjectionFingerprints;
+  /**
+   * HOW MANY DELTAS STAND AFTER THE LAST CHECKPOINT in the branch just read. `persist` writes
+   * a checkpoint instead of a delta once this reaches `MAX_DELTAS_BETWEEN_CHECKPOINTS`, which
+   * is what stops the run, and therefore the load, from growing without bound.
+   */
+  deltasSinceCheckpoint: number;
 }
 
 export function materializeStatePersistence(
@@ -985,6 +1097,7 @@ export function materializeStatePersistence(
   let stateStart = -1;
   let checkpointIndex = -1;
   let v2Seen = false;
+  let deltasSinceCheckpoint = 0;
   const rememberProjection = (): void => {
     fingerprintSources.set(state.revision, state);
   };
@@ -1001,11 +1114,25 @@ export function materializeStatePersistence(
     if (version !== 2) throw new Error("Invalid active-context persisted state version");
     const kind = ownValue(entry.data, "kind");
     if (kind === "checkpoint") {
-      if (v2Seen || checkpointIndex >= 0) throw new Error("Duplicate active-context v2 checkpoint");
+      // THE LAST CHECKPOINT WINS, AND A SECOND ONE IS NO LONGER FATAL (2026-09-20). This
+      // raised "Duplicate active-context v2 checkpoint" on sight of a second, which made the
+      // ledger append-only in the strongest sense: one checkpoint, then deltas forever, and a
+      // replay that walked all of them on every load. Restarting the replay at the newest
+      // checkpoint is what makes `MAX_DELTAS_BETWEEN_CHECKPOINTS` possible, and it reaches
+      // the same final state by the same digest equalities.
+      //
+      // It also un-latches the failure gate 173 describes. A branch that took a second
+      // checkpoint from a failed restore used to be unreadable forever, and every reload made
+      // it worse; such a branch now reads from its newest checkpoint. That is a second line of
+      // defence, not the first: the `lineageUnreadable` guard in `persist` still refuses to
+      // write the state entry that starts the damage, and gate 173 still pins it.
       checkpointIndex = index;
       stateStart = index;
+      deltasSinceCheckpoint = 0;
     } else if (checkpointIndex < 0) {
       throw new Error("Active-context v2 delta precedes migration checkpoint");
+    } else {
+      deltasSinceCheckpoint += 1;
     }
     v2Seen = true;
   }
@@ -1142,7 +1269,7 @@ export function materializeStatePersistence(
     writtenSha256 = wire.stateSha256 === calculated ? null : wire.stateSha256;
     rememberProjection();
   }
-  return { state, wireVersion, records, stateSha256, projectionFingerprints };
+  return { state, wireVersion, records, stateSha256, projectionFingerprints, deltasSinceCheckpoint };
 }
 
 export function materializeActiveContextState(

package/extensions/lib/policy.ts

@@ -343,6 +343,26 @@ export const CONTEXT_STATUS_RESPONSE_BYTES = 24_000;
 export const MAX_UNMARKED_CANDIDATES = 3;
 
 export const MAX_FOLD_SPAN_CHARS = 16_000;
+
+/**
+ * THE LADDER'S CHAPTER CAP FOLLOWS THE FLOOR (2026-09-07).
+ *
+ * `selectAutomaticChapter` accumulates whole units until a span reaches `minFoldChars` and
+ * refuses a multi-unit span past this cap, so the cap has to sit at least one unit above
+ * the floor or the walk can never satisfy both. At the shipped 8,000 the 16,000 constant
+ * does. /fold-settings offers floors up to 32,000, and at any floor past the constant every
+ * multi-unit chapter was refused by arithmetic: only a single oversized unit or a tool batch
+ * could fold, and a prose session with the floor at 32,000 held its raw material forever
+ * while the status row announced a commit (session 01a07498, 2026-09-07: fourteen sizable
+ * units in view, none over 32,000, the frontier staging nothing). Twice the floor is the
+ * smallest cap under which a walk that crosses the floor by one unit shorter than the floor
+ * always lands inside it; the constant stays as the cap's own floor so every default reads
+ * exactly as before, and a manual span is never bounded by either (Shane, 2026-08-22).
+ */
+export function chapterSpanCap(minFoldChars: number): number {
+  return Math.max(MAX_FOLD_SPAN_CHARS, 2 * minFoldChars);
+}
+
 export const PEEK_DEFAULT_MAX_BYTES = 16_000;
 export const PEEK_HEAD_SHARE = 0.6;
 

package/extensions/lib/status-widget.ts

@@ -2,11 +2,254 @@
 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;
+// GROUPED BY DISTANCE FROM COMPRESSION, left to right (Shane 2026-09-06). Consolidated,
+// span and tool folds are compressed now, deepest first. Marked content is raw now and
+// folds at the next commit. Raw content is raw now and eligible later. Pinned content is
+// raw and HELD against every commit until released, so it is the farthest from
+// compression of all, and it sits at the fresh edge of the bar.
+export const FOLD_BAR_KINDS = ["consolidated", "span", "tool", "marked", "raw", "pinned"] 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 });
+export const emptyFoldBarMass = (): FoldBarMass => ({ consolidated: 0, span: 0, tool: 0, marked: 0, raw: 0, pinned: 0 });
+
+// ALL SIX KINDS TAKE THEIR SHADE FROM THE MAP, in that order (Shane 2026-09-06, second
+// pass). A pin sat off the ramp in the theme accent for one build; Shane put it back at
+// the far end, because a pin is the MOST settled state of all, decided and held, and the
+// map's last shade reads as separate from the rest of the fill on its own.
+
+// THE COLOUR MAPS, sampled at 64 positions by lab/generate_colour_maps.py: Batlow from
+// Crameri's own 256-step table, the other four from matplotlib. Five shades are read off
+// the chosen map by linear interpolation between a start and an end position, so a
+// person can use the whole map, a slice of it, or run it backwards. No palette library
+// ships: these tables are the whole dependency.
+export const COLOUR_MAP_NAMES = ["batlow", "viridis", "plasma", "magma", "cividis"] as const;
+export type ColourMapName = typeof COLOUR_MAP_NAMES[number];
+const COLOUR_MAPS: Record<ColourMapName, readonly string[]> = {
+  batlow: [
+    "#011959", "#051F5A", "#08265B", "#0B2B5C", "#0D315D", "#0E365E", "#0F3B5F", "#103F60",
+    "#114360", "#124761", "#134B61", "#154F62", "#175362", "#195662", "#1C5A62", "#1F5D61",
+    "#236061", "#27635F", "#2C665D", "#31695B", "#376B59", "#3C6D56", "#426F52", "#49714F",
+    "#4F734C", "#557548", "#5C7744", "#627941", "#697B3D", "#707D3A", "#777F36", "#7E8133",
+    "#858330", "#8D852E", "#94872C", "#9C892B", "#A48B2C", "#AC8C2D", "#B48E30", "#BC8F34",
+    "#C49138", "#CB923E", "#D29343", "#D9954A", "#E09651", "#E69858", "#EC9A61", "#F19C69",
+    "#F59F73", "#F8A17C", "#FAA486", "#FCA78F", "#FDAB98", "#FDAEA1", "#FDB1AA", "#FDB3B3",
+    "#FDB6BB", "#FDB9C4", "#FDBCCC", "#FCBFD5", "#FCC2DE", "#FBC6E7", "#FBC9F1", "#FACCFA",
+  ],
+  viridis: [
+    "#440154", "#46075A", "#470D60", "#471365", "#48186B", "#481E6F", "#482374", "#482878",
+    "#472D7C", "#46327F", "#453782", "#433C84", "#424186", "#404688", "#3E4A89", "#3C4F8A",
+    "#3A538B", "#38578C", "#365C8D", "#34608D", "#32648E", "#31688E", "#2F6C8E", "#2D708E",
+    "#2C748E", "#2A778E", "#297B8E", "#277F8E", "#26838E", "#24878E", "#238A8D", "#218E8D",
+    "#20928C", "#1F968B", "#1F9A8A", "#1F9D89", "#1FA187", "#21A586", "#23A984", "#26AC81",
+    "#2AB07F", "#2FB47C", "#35B779", "#3BBB75", "#42BE71", "#4AC26D", "#52C569", "#5AC864",
+    "#63CB5F", "#6CCE59", "#76D054", "#80D34D", "#8AD547", "#94D841", "#9FDA3A", "#A9DC33",
+    "#B4DD2C", "#BFDF25", "#CAE01F", "#D4E21A", "#DFE318", "#E9E41A", "#F3E61E", "#FDE725",
+  ],
+  plasma: [
+    "#0D0887", "#19068C", "#220690", "#2A0593", "#320597", "#39049A", "#40049C", "#46039F",
+    "#4D02A1", "#5402A3", "#5A01A5", "#6001A6", "#6700A7", "#6D00A8", "#7301A8", "#7902A8",
+    "#7F03A8", "#8506A7", "#8B0AA5", "#910EA3", "#9613A1", "#9C179E", "#A11C9B", "#A62098",
+    "#AB2594", "#B02991", "#B42E8D", "#B93289", "#BD3785", "#C13B82", "#C5407E", "#C9457A",
+    "#CD4976", "#D14E73", "#D4526F", "#D8576C", "#DB5C68", "#DE6065", "#E16561", "#E46A5E",
+    "#E76F5A", "#EA7457", "#ED7953", "#EF7E50", "#F2834C", "#F48849", "#F68D45", "#F89342",
+    "#F9993E", "#FA9E3B", "#FCA437", "#FDAA34", "#FDB031", "#FEB62E", "#FEBC2B", "#FDC328",
+    "#FDC926", "#FCD025", "#FBD624", "#F9DD25", "#F7E425", "#F5EB27", "#F2F227", "#F0F921",
+  ],
+  magma: [
+    "#000004", "#02010A", "#040312", "#06051A", "#0A0822", "#0F0B2B", "#130D34", "#180F3E",
+    "#1D1148", "#231151", "#29115B", "#301164", "#37106C", "#3E0F72", "#450F76", "#4B117A",
+    "#52137C", "#58157E", "#5F187F", "#651A80", "#6B1D81", "#721F81", "#782281", "#7E2482",
+    "#852681", "#8B2981", "#922B81", "#982D80", "#9F2F7F", "#A5317E", "#AC337C", "#B3357A",
+    "#B93878", "#C03A76", "#C63D74", "#CD3F71", "#D3436E", "#D9466B", "#DF4A68", "#E44F65",
+    "#E95462", "#ED5A5F", "#F1605D", "#F4675C", "#F66E5C", "#F8765C", "#FA7E5E", "#FB8560",
+    "#FC8D63", "#FD9567", "#FD9C6B", "#FEA470", "#FEAB75", "#FEB37A", "#FEBA80", "#FEC286",
+    "#FEC98D", "#FED193", "#FED89A", "#FDDFA1", "#FDE7A8", "#FCEEB0", "#FCF5B7", "#FCFDBF",
+  ],
+  cividis: [
+    "#00224E", "#002554", "#00285B", "#002B63", "#002E6A", "#003070", "#063370", "#123670",
+    "#1B386F", "#223B6E", "#283E6E", "#2D416D", "#32446D", "#37476C", "#3C496C", "#404C6C",
+    "#444F6C", "#48526C", "#4C556C", "#50576C", "#545A6D", "#575D6D", "#5B606E", "#5F636F",
+    "#62666F", "#666870", "#696B71", "#6D6E72", "#707173", "#747475", "#777776", "#7A7A78",
+    "#7E7D78", "#828078", "#868379", "#898678", "#8D8978", "#918C78", "#958F77", "#999277",
+    "#9D9576", "#A19875", "#A59C74", "#A99F73", "#ADA272", "#B2A570", "#B6A96F", "#BAAC6D",
+    "#BEAF6B", "#C2B369", "#C7B667", "#CBBA64", "#CFBD62", "#D4C15F", "#D8C45C", "#DDC859",
+    "#E1CC55", "#E5CF51", "#EAD34D", "#EFD748", "#F3DB42", "#F8DF3C", "#FDE234", "#FEE838",
+  ],
+};
+
+/** Which map the bar reads and where on it the two ends of the ramp sit. `start` is the
+ *  position of the most compressed shade and `end` the position of raw; a start above
+ *  its end runs the map backwards. Both are positions in [0, 1] and may not coincide,
+ *  because six shades read at one position are one shade. */
+export interface FoldBarPalette { map: ColourMapName; start: number; end: number; }
+export const DEFAULT_FOLD_BAR_PALETTE: Readonly<FoldBarPalette> = Object.freeze({ map: "batlow", start: 0, end: 1 });
+
+export class FoldBarPaletteError extends Error {}
+
+/** One resolver for every path a palette arrives by: registration, the settings file and
+ *  a live edit. Absent means the package default; anything present is validated whole. */
+export function resolveFoldBarPalette(value: unknown): FoldBarPalette {
+  if (value === undefined) return { ...DEFAULT_FOLD_BAR_PALETTE };
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new FoldBarPaletteError("palette must be an object { map, start, end }");
+  }
+  const candidate = value as Record<string, unknown>;
+  for (const key of Object.keys(candidate)) {
+    if (key !== "map" && key !== "start" && key !== "end") {
+      throw new FoldBarPaletteError(`palette has no ${key} field: the fields are map, start, end`);
+    }
+  }
+  const { map, start, end } = candidate;
+  if (typeof map !== "string" || !(COLOUR_MAP_NAMES as readonly string[]).includes(map)) {
+    throw new FoldBarPaletteError(`palette.map must be one of ${COLOUR_MAP_NAMES.join(", ")}`);
+  }
+  for (const [name, position] of [["start", start], ["end", end]] as const) {
+    if (typeof position !== "number" || !Number.isFinite(position) || position < 0 || position > 1) {
+      throw new FoldBarPaletteError(`palette.${name} must be a position on the map from 0 to 1`);
+    }
+  }
+  if (start === end) {
+    throw new FoldBarPaletteError("palette.start and palette.end must differ: six shades read at one position are one shade");
+  }
+  return { map: map as ColourMapName, start: start as number, end: end as number };
+}
+
+// sRGB <-> linear <-> OKLab, enough to hold a hue while moving its lightness.
+const hexToRgb = (hex: string): number[] => [1, 3, 5].map((at) => parseInt(hex.slice(at, at + 2), 16) / 255);
+const rgbToHex = (rgb: number[]): string =>
+  "#" + rgb.map((v) => Math.round(Math.max(0, Math.min(1, v)) * 255).toString(16).padStart(2, "0").toUpperCase()).join("");
+const toLinear = (c: number): number => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const fromLinear = (c: number): number => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
+const luminanceOf = (hex: string): number => {
+  const [r, g, b] = hexToRgb(hex).map(toLinear);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+/** WCAG contrast ratio between two colours, the measure gate 165 has always applied. */
+export function contrastRatio(a: string, b: string): number {
+  const [la, lb] = [luminanceOf(a), luminanceOf(b)];
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+const linearToOklab = ([r, g, b]: number[]): number[] => {
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  return [
+    0.2104542553 * l + 0.7936177850 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.4285922050 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.8086757660 * s,
+  ];
+};
+const oklabToLinear = ([L, a, b]: number[]): number[] => {
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.2914855480 * b) ** 3;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s,
+  ];
+};
+/** An OKLab colour brought into the sRGB gamut by shrinking its chroma, hue held. */
+const inGamut = (L: number, a: number, b: number): number[] => {
+  const inside = (rgb: number[]): boolean => rgb.every((v) => v >= -1e-6 && v <= 1 + 1e-6);
+  let rgb = oklabToLinear([L, a, b]);
+  if (inside(rgb)) return rgb.map(fromLinear);
+  let lo = 0, hi = 1;
+  for (let i = 0; i < 16; i += 1) {
+    const mid = (lo + hi) / 2;
+    if (inside(oklabToLinear([L, a * mid, b * mid]))) lo = mid; else hi = mid;
+  }
+  rgb = oklabToLinear([L, a * lo, b * lo]);
+  return rgb.map((v) => fromLinear(Math.max(0, Math.min(1, v))));
+};
+
+/** The two reference backgrounds the readability floor is measured against. */
+export const READABILITY = Object.freeze({ dark: "#202122", light: "#FFFFFF", contrast: 4.5 });
+
+/** THE READABILITY CLAMP. A map's dark end vanishes on a dark terminal and its pale end
+ *  on a light one, and the old build carried two hand-adjusted hex tables to cover that
+ *  for one map at one range. With the map and the range a choice, the adjustment runs
+ *  here: lightness moves away from the background, hue held and chroma shrunk only as far
+ *  as the gamut needs, until the shade clears 4.5:1 against the reference background. A
+ *  shade that already clears it is returned untouched. */
+export function readableOn(hex: string, dark: boolean): string {
+  const background = dark ? READABILITY.dark : READABILITY.light;
+  if (contrastRatio(hex, background) >= READABILITY.contrast) return hex.toUpperCase();
+  const [L, a, b] = linearToOklab(hexToRgb(hex).map(toLinear));
+  // Lightness is monotone in luminance at held hue, so the boundary is found by bisection
+  // between the shade's own lightness and the far end, which always clears the floor.
+  let fails = L;
+  let passes = dark ? 1 : 0;
+  for (let i = 0; i < 24; i += 1) {
+    const mid = (fails + passes) / 2;
+    if (contrastRatio(rgbToHex(inGamut(mid, a, b)), background) >= READABILITY.contrast) passes = mid;
+    else fails = mid;
+  }
+  return rgbToHex(inGamut(passes, a, b));
+}
+
+/** The glyph a guide draws. Marks, not breaks: the fill's own colour stays behind them.
+ *  DOTTED, NOT A LINE (Shane 2026-09-06, sixth pass): a full-height one-pixel stroke
+ *  inside a solid colour is exactly what the boundary between two folds of that colour
+ *  looks like, so the edge strokes "read as fold segments"; a mark that does not span
+ *  the cell's height cannot be a boundary. The dotted vertical is centred in its cell,
+ *  so each guide stands just inside the band's edge: the aim in the cell whose left edge
+ *  is the aim share, the commit in the cell whose right edge is the commit share, a
+ *  quarter cell in from each line. Earlier passes: a text-ink hairline "too pronounced",
+ *  a notch "confusing", brackets off their lines because a font insets them. The ink is
+ *  the fill's own hue toned toward the background, muted on the track. */
+export const GUIDE_GLYPHS = Object.freeze({ aim: "┊", commit: "┊" });
+/** How far a bracket's ink is pulled from the shade under it toward the reference
+ *  background. Shane 2026-09-06, fourth pass: black brackets were too heavy, and no one
+ *  fixed accent is legible over a map that runs from navy to pale pink (the theme's teal
+ *  vanished over the teal span shade, violet over the blue, white over the pink). The
+ *  fill's own hue, darkened on a dark theme and lightened on a light one, is legible over
+ *  every shade because the readability clamp holds each shade at 4.5:1 against that
+ *  background: at this depth the floor is 3:1 over the darkest shade a map can carry. */
+export const GUIDE_TONE = 0.75;
+/** A guide's ink over a shade: the same hue, most of the way to the reference
+ *  background, so a bracket over salmon is a dark salmon and one over navy a deeper navy.
+ *  Never a hue of its own, so no guide competes with a category. */
+export function guideInk(under: string, dark: boolean): string {
+  const background = hexToRgb(dark ? READABILITY.dark : READABILITY.light);
+  return rgbToHex(hexToRgb(under).map((v, i) => v * (1 - GUIDE_TONE) + background[i] * GUIDE_TONE));
+}
+/** How far the dim ink is pulled toward the reference background to stand in for the
+ *  ░ texture it replaces: a quarter-coverage glyph reads as about a quarter of its ink. */
+export const TRACK_DEPTH = 0.7;
+/** The empty track's one shade, or null when the theme's dim ink is not an RGB escape. */
+export function trackShade(theme: FoldBarTheme, dark: boolean): string | null {
+  const match = /^\x1b\[38;2;(\d+);(\d+);(\d+)m$/.exec(theme.getFgAnsi?.("dim") ?? "");
+  if (!match) return null;
+  const dim = match.slice(1, 4).map((v) => Number(v) / 255);
+  const background = hexToRgb(dark ? READABILITY.dark : READABILITY.light);
+  return rgbToHex(dim.map((v, i) => v * (1 - TRACK_DEPTH) + background[i] * TRACK_DEPTH));
+}
+
+/** The shade a map holds at a position in [0, 1], interpolated between its samples. */
+export function sampleColourMap(map: ColourMapName, position: number): string {
+  const table = COLOUR_MAPS[map];
+  const at = Math.max(0, Math.min(1, position)) * (table.length - 1);
+  const lo = Math.floor(at), hi = Math.min(table.length - 1, lo + 1), t = at - lo;
+  const a = hexToRgb(table[lo]), b = hexToRgb(table[hi]);
+  return rgbToHex(a.map((v, i) => v * (1 - t) + b[i] * t));
+}
+
+const shadeMemo = new Map<string, Record<FoldBarKind, string>>();
+/** The six shades for a palette on a background: read off the map at evenly spaced
+ *  positions from start to end, then brought up to the readability floor. Memoized on
+ *  the palette and background, since the bar renders many times per choice. */
+export function foldBarShades(palette: FoldBarPalette, dark: boolean): Record<FoldBarKind, string> {
+  const key = `${palette.map}:${palette.start}:${palette.end}:${dark ? "dark" : "light"}`;
+  const held = shadeMemo.get(key);
+  if (held) return held;
+  const shades = Object.fromEntries(FOLD_BAR_KINDS.map((kind, i) => {
+    const position = palette.start + (palette.end - palette.start) * (i / (FOLD_BAR_KINDS.length - 1));
+    return [kind, readableOn(sampleColourMap(palette.map, position), dark)];
+  })) as Record<FoldBarKind, string>;
+  shadeMemo.set(key, shades);
+  return shades;
+}
 
 export interface FoldBarModel {
   brand: string;
@@ -26,27 +269,17 @@ export interface FoldBarModel {
   weighed: boolean;
   staleAfterCommit: boolean;
   stopped: string | null;
+  /** Absent means the package default, exactly as it does in the settings file. */
+  palette?: FoldBarPalette;
 }
 export interface FoldBarTheme {
   fg(color: "dim" | "muted" | "text" | "warning" | "error" | "accent", text: string): string;
   bold(text: string): string;
   getColorMode?(): "truecolor" | "256color";
-  getFgAnsi?(color: "text" | "muted" | "accent"): string;
+  getFgAnsi?(color: "text" | "muted" | "accent" | "dim"): string;
   name?: string;
 }
 
-// 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",
-};
-
 export function lightBackground(theme: FoldBarTheme): boolean {
   try {
     const match = /38;2;(\d+);(\d+);(\d+)/.exec(theme.getFgAnsi?.("text") ?? "");
@@ -65,7 +298,9 @@ const truecolor = (hex: string, text: string): string => {
 /** 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.
+ * proportion. A guide reserves the RIGHT half of its column only: the hairline is drawn
+ * at that column's right edge, which is the exact share the guide names, over whatever
+ * colour the left half holds, so a guide costs one half-cell and erases no category.
  */
 export function foldBarCells(model: FoldBarModel, width = FOLD_BAR_WIDTH): Array<FoldBarKind | "empty" | "unknown" | "tick"> {
   const samples = 2 * width;
@@ -73,7 +308,7 @@ export function foldBarCells(model: FoldBarModel, width = FOLD_BAR_WIDTH): Array
   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");
+    i % 2 === 1 && 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)
@@ -99,9 +334,16 @@ export function foldBarCells(model: FoldBarModel, width = FOLD_BAR_WIDTH): Array
   }
   return cells;
 }
+/** Each guide stands in the band's own edge cell: the aim in the column whose LEFT edge
+ *  is the aim share, the commit in the column whose RIGHT edge is the commit share, so
+ *  the band is the run of cells from one mark to the other inclusive. When both land on
+ *  one column the commit wins, since it is the one the label also names. */
 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));
-  return new Map([[at(model.aimShare), "aim"], [at(model.commitShare), "commit"]]);
+  const column = (value: number): number => Math.max(0, Math.min(width - 1, value));
+  return new Map([
+    [column(Math.round(model.aimShare * width)), "aim"],
+    [column(Math.round(model.commitShare * width) - 1), "commit"],
+  ]);
 }
 export function foldBarPlainText(model: FoldBarModel): string {
   return renderFoldBar(model, Number.POSITIVE_INFINITY, { fg: (_c, t) => t, bold: (t) => t });
@@ -115,37 +357,73 @@ export function renderFoldBar(model: FoldBarModel, width: number, theme: FoldBar
   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 truecolorMode = theme.getColorMode?.() === "truecolor";
+  const dark = !lightBackground(theme);
+  const shades = foldBarShades(model.palette ?? DEFAULT_FOLD_BAR_PALETTE, dark);
+  // Without truecolor the theme's own inks stand in: pinned takes the accent, raw the
+  // muted ink, everything compressed or marked the text ink.
   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);
+    if (truecolorMode) return truecolor(shades[kind], text);
+    return theme.fg(kind === "pinned" ? "accent" : kind === "raw" ? "muted" : "text", text);
   };
   const cells = foldBarCells(model);
+  const ticks = foldBarTicks(model);
+  // THE TRACK IS SOLID (Shane 2026-09-06, fourth pass): a guide cell on a ░ track was a
+  // blank cell with a bracket in it, which read as a hole. With an RGB dim ink the empty
+  // track is one shade, the dim ink pulled most of the way to the reference background
+  // so it sits where ░ used to, and a bracket on it stands on that same shade. Without
+  // an RGB dim ink the ░ texture stays, and the guide cell there is bare.
+  const track = trackShade(theme, dark);
+  const trackBg = track ? truecolor(track, "").replace("[38;", "[48;") : null;
   const solid = (kind: typeof cells[number]): string => {
-    if (kind === "tick") return neutral(theme.bold("┆"));
-    if (kind === "empty") return theme.fg("dim", "░");
+    if (kind === "empty") return trackBg ? `${trackBg} \x1b[49m` : theme.fg("dim", "░");
     if (kind === "unknown") return muted("█");
-    return ink(kind, "█");
+    return ink(kind as FoldBarKind, "█");
   };
-  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 background = (kind: FoldBarKind | "unknown"): string | null => {
+    if (truecolorMode && kind !== "unknown") return truecolor(shades[kind], "").replace("[38;", "[48;");
+    // Pi exposes the same theme ink in 256-colour mode, and the accent for a pin there.
+    // 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" || kind === "unknown" ? "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;
   };
+  // THE GUIDES ARE MARKS ON THE AXIS, NOT BREAKS IN THE FILL (Shane 2026-09-06, third
+  // pass). A hairline in text ink read as a white bar; a notch cut into the fill read as
+  // a boundary between two kinds of content, which a threshold is not. The band is an
+  // interval, so a dotted mark stands in each of its edge cells, drawn over the fill's
+  // own colour in that colour's own hue pulled toward the background. No hue of its
+  // own, since a coloured guide competes with a category; never the warning ink, since
+  // folding is automatic and the person has nothing to do about it. On the track the
+  // muted ink stands on the track's shade; without truecolor the mark stands on the
+  // default background, because the theme's inks are the fill.
+  const shadeUnder = (left: typeof cells[number]): string | null =>
+    truecolorMode && (FOLD_BAR_KINDS as readonly string[]).includes(left) ? shades[left as FoldBarKind] : null;
+  const guide = (column: number, left: typeof cells[number]): string => {
+    const glyph = GUIDE_GLYPHS[ticks.get(column) ?? "aim"];
+    const under = shadeUnder(left);
+    if (under) return `${background(left as FoldBarKind)}${truecolor(guideInk(under, dark), glyph)}\x1b[49m`;
+    if (left === "empty" && trackBg) return `${trackBg}${theme.fg("muted", glyph)}\x1b[49m`;
+    return theme.fg("muted", glyph);
+  };
   let bar = "";
   for (let i = 0; i < cells.length; i += 2) {
     const left = cells[i], right = cells[i + 1];
+    if (right === "tick") {
+      // The mark over the left half's own colour: the guide stands in the band's edge
+      // cell and hides no fill. Off the fill it stands on the track.
+      bar += guide(i / 2, left);
+      continue;
+    }
     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, "▌");
+      const half = left === "unknown" ? muted("▌") : ink(left as FoldBarKind, "▌");
+      bar += trackBg ? `${trackBg}${half}\x1b[49m` : half;
     } else {
       const bg = background(right as FoldBarKind);
       bar += bg ? `${bg}${ink(left as FoldBarKind, "▌")}\x1b[49m` : solid(left);
@@ -160,13 +438,18 @@ export function renderFoldBar(model: FoldBarModel, width: number, theme: FoldBar
     parts.push(neutral(`${pct}%`), muted(when));
   }
   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(")"));
+    // N counts compressed folds. Mark/Pin are accompanying states, not added to N, and
+    // they are named in the bar's own order. A kind with nothing to count is not named
+    // (Shane 2026-09-06): the row's width is the scarce thing, and "0 Tool" tells a
+    // person nothing the bar does not already show by its absence.
+    const counts = ([
+      ["consolidated", model.foldConsolidations, "Cons."], ["span", model.foldSpans, "Span"],
+      ["tool", model.foldTruncations, "Tool"], ["marked", model.stagedMarks, "Mark"],
+      ["pinned", model.pinnedRefs, "Pin"],
+    ] as const).filter(([, count]) => count > 0).map(([kind, count, word]) => ink(kind, `${count} ${word}`));
+    parts.push(counts.length
+      ? neutral(`${model.folds} Folds (`) + counts.join(muted(", ")) + neutral(")")
+      : neutral(`${model.folds} Folds`));
     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/extensions/settings.ts

@@ -29,6 +29,13 @@ import {
 	type ActiveContextThresholds,
 } from "./lib/policy.ts";
 import { applyLiveSettings, liveSettingsReachable } from "./lib/live-settings.ts";
+import {
+	COLOUR_MAP_NAMES,
+	DEFAULT_FOLD_BAR_PALETTE,
+	FoldBarPaletteError,
+	resolveFoldBarPalette,
+	type FoldBarPalette,
+} from "./lib/status-widget.ts";
 
 export const DEFAULT_FOLD_SETTINGS_PATH = join(
 	homedir(),
@@ -47,6 +54,11 @@ export interface FoldSettingsFile {
 	toolFoldThreshold?: number;
 	preCommitNotice?: boolean;
 	noticeLeadShare?: number;
+	// THE BAR'S COLOURS, stored whole for the same reason the thresholds are (2026-09-06):
+	// start and end may not coincide, which is a cross-field invariant, so a partial object
+	// would mean whatever the defaults are at read time. Absent means the package default.
+	// It is a display preference and moves nothing about folding.
+	palette?: FoldBarPalette;
 }
 
 // The four settings, named once. This was a hand-written union until the migration
@@ -63,11 +75,17 @@ const THRESHOLD_FIELDS = [
 // validation and no relationship to any other value on the screen.
 const SCALAR_FIELDS = ["toolFoldThreshold", "preCommitNotice", "noticeLeadShare"] as const;
 
-export type FoldSettingId = typeof THRESHOLD_FIELDS[number] | typeof SCALAR_FIELDS[number];
+// The three rows that edit the palette object, each naming the field it moves.
+const PALETTE_FIELDS = { paletteMap: "map", paletteStart: "start", paletteEnd: "end" } as const;
+
+export type FoldSettingId = typeof THRESHOLD_FIELDS[number] | typeof SCALAR_FIELDS[number] | keyof typeof PALETTE_FIELDS;
 
 function isThresholdField(id: FoldSettingId): id is typeof THRESHOLD_FIELDS[number] {
 	return (THRESHOLD_FIELDS as readonly string[]).includes(id);
 }
+function isPaletteField(id: FoldSettingId): id is keyof typeof PALETTE_FIELDS {
+	return Object.hasOwn(PALETTE_FIELDS, id);
+}
 
 // One edit, applied against the WHOLE draft: the merged thresholds object is
 // re-validated through resolveThresholds so cross-field invariants
@@ -105,6 +123,20 @@ export function applyFoldSettingsEdit(
 		}
 		return { ok: true, draft: { ...draft, toolFoldThreshold: value } };
 	}
+	if (isPaletteField(id)) {
+		// The palette is re-validated WHOLE through the runtime's own resolver, so the
+		// cross-field rule (start and end differ) holds at every saved state.
+		const field = PALETTE_FIELDS[id];
+		const raw = rawValue.trim();
+		const value = field === "map" ? raw : Number(raw);
+		try {
+			const palette = resolveFoldBarPalette({ ...(draft.palette ?? DEFAULT_FOLD_BAR_PALETTE), [field]: value });
+			return { ok: true, draft: { ...draft, palette } };
+		} catch (error) {
+			if (error instanceof FoldBarPaletteError) return { ok: false, error: error.message };
+			throw error;
+		}
+	}
 	try {
 		const value = Number(rawValue.trim());
 		if ((id === "consolidateAfter" || id === "minFoldChars") && !Number.isSafeInteger(value)) {
@@ -209,10 +241,10 @@ export function readFoldSettingsFile(path: string = DEFAULT_FOLD_SETTINGS_PATH):
 		dropped = true;
 	}
 	for (const key of Object.keys(parsed)) {
-		if (key === "thresholds" || (SCALAR_FIELDS as readonly string[]).includes(key)) continue;
+		if (key === "thresholds" || key === "palette" || (SCALAR_FIELDS as readonly string[]).includes(key)) continue;
 		if (RETIRED_FILE_KEYS.includes(key)) { delete parsed[key]; dropped = true; continue; }
 		return refused(`fold settings file has no ${key} field: the surface is ` +
-			`thresholds, ${SCALAR_FIELDS.join(", ")}`);
+			`thresholds, ${SCALAR_FIELDS.join(", ")}, palette`);
 	}
 	// The two scalars are validated the same way the editor validates them, through the
 	// one path, so a hand-edited file cannot hold a value the screen would refuse.
@@ -232,6 +264,12 @@ export function readFoldSettingsFile(path: string = DEFAULT_FOLD_SETTINGS_PATH):
 		}
 		Object.assign(scalars, applied.draft);
 	}
+	// The palette goes through the one resolver the runtime and the editor use, so a
+	// hand-edited file cannot hold a map name or a range the screen would refuse.
+	if (parsed.palette !== undefined) {
+		try { scalars.palette = resolveFoldBarPalette(parsed.palette); }
+		catch (error: any) { return refused(`fold settings palette is invalid: ${error?.message ?? error}`); }
+	}
 	if (parsed.thresholds === undefined) {
 		if (dropped) { try { saveFoldSettingsFile(path, scalars); } catch { } }
 		return { settings: scalars, refusal: null, migrated: dropped };
@@ -271,6 +309,7 @@ export function saveFoldSettingsFile(path: string, settings: FoldSettingsFile):
 	if (settings.toolFoldThreshold !== undefined) clean.toolFoldThreshold = settings.toolFoldThreshold;
 	if (settings.preCommitNotice !== undefined) clean.preCommitNotice = settings.preCommitNotice;
 	if (settings.noticeLeadShare !== undefined) clean.noticeLeadShare = settings.noticeLeadShare;
+	if (settings.palette !== undefined) clean.palette = settings.palette;
 	mkdirSync(dirname(path), { recursive: true });
 	const temporary = `${path}.tmp`;
 	writeFileSync(temporary, `${JSON.stringify(clean, null, 2)}\n`);
@@ -297,6 +336,12 @@ const EDITOR_ROWS: readonly EditorRow[] = [
 	{ id: "toolFoldThreshold", label: "Clip old tool results", description: "The oldest share of the window shows tool results shortened, still recoverable in full. Off keeps them whole (toolFoldThreshold)" },
 	{ id: "preCommitNotice", label: "Tell the model before folding", description: "Show the model the window's status once as a fold approaches: what is staged, what is pinned, what it can change. Off is what the measured runs used (preCommitNotice)" },
 	{ id: "noticeLeadShare", label: "How early to tell it", description: "How far below the folding point that status appears. Only used when the notice is on (noticeLeadShare)" },
+	// THE BAR'S COLOURS ARE A CHOICE (Shane 2026-09-06). Three rows over one stored object:
+	// which map, and where on it the two ends of the ramp sit. The status line repaints on
+	// every step, so the bar itself is the preview.
+	{ id: "paletteMap", label: "Bar colours", description: "The colour map the status bar reads its six shades from, most compressed first and pinned last (palette.map)" },
+	{ id: "paletteStart", label: "Folded shade at", description: "Where on that map the most compressed content sits. Put it past the pinned end to run the map backwards (palette.start)" },
+	{ id: "paletteEnd", label: "Pinned shade at", description: "Where on that map pinned content sits, with raw just before it. The shades between are spaced evenly (palette.end)" },
 ];
 
 // The cycle lattice for both shares. Shares step in cents so no float drift reaches a
@@ -326,6 +371,9 @@ const MIN_FOLD_CHOICES = [2_000, 4_000, 6_000, 8_000, 12_000, 16_000, 24_000, 32
 // off: without a 0 here the only way to decline in-view clipping would be the file.
 const TOOL_FOLD_CHOICES = [0, 0.25, 0.35, 0.50, 0.65, 0.75, 0.90];
 
+// Positions on a colour map, the whole of it in twentieths, ends included.
+const MAP_POSITION_CHOICES = Array.from({ length: 21 }, (_, i) => i / 20);
+
 function shareCandidates(): number[] {
 	const { min, max, step } = SHARE_LATTICE;
 	const values: number[] = [];
@@ -337,8 +385,13 @@ function shareCandidates(): number[] {
 
 // The lattice a row steps along, as numbers. Display belongs to rowDisplayValue and
 // only to it: this list is stepped, never shown.
-function allowedValues(id: FoldSettingId, thresholds: ActiveContextThresholds): number[] {
+function allowedValues(id: FoldSettingId, thresholds: ActiveContextThresholds, palette: FoldBarPalette): number[] {
 	if (id === "toolFoldThreshold") return TOOL_FOLD_CHOICES;
+	// Each end of the ramp may step anywhere on the map except onto the other end: the
+	// cross-field rule is the filter, so stepping across the other end is one keypress.
+	if (id === "paletteStart") return MAP_POSITION_CHOICES.filter((v) => Math.abs(v - palette.end) > 1e-9);
+	if (id === "paletteEnd") return MAP_POSITION_CHOICES.filter((v) => Math.abs(v - palette.start) > 1e-9);
+	if (id === "paletteMap") return [];
 	// THE LEAD STEPS THE ONE SHARE LATTICE, unfiltered. It answers to nothing but its own
 	// range: a lead wider than the trigger is legal and means "speak from the first
 	// measurement", which the runtime floors rather than refuses, so there is no
@@ -359,6 +412,7 @@ function rowRawValue(settings: FoldSettingsFile, id: FoldSettingId): string {
 	// A SCALAR THAT IS ABSENT READS AS THE PACKAGE DEFAULT, never as zero or false. The
 	// file omits what was never set on purpose, so the screen has to supply the same
 	// value the runtime would, or the row would show a setting nobody chose.
+	if (isPaletteField(id)) return String((settings.palette ?? DEFAULT_FOLD_BAR_PALETTE)[PALETTE_FIELDS[id]]);
 	if (!isThresholdField(id)) {
 		if (id === "toolFoldThreshold") return String(settings.toolFoldThreshold ?? DEFAULT_TOOL_FOLD_THRESHOLD);
 		if (id === "noticeLeadShare") return String(settings.noticeLeadShare ?? DEFAULT_NOTICE_LEAD_SHARE);
@@ -384,6 +438,13 @@ function rowDisplayValue(settings: FoldSettingsFile, id: FoldSettingId, budgetTo
 	}
 	if (id === "consolidateAfter") return raw;
 	if (id === "minFoldChars") return `${Number(raw).toLocaleString("en-US")} characters`;
+	if (id === "paletteMap") return raw;
+	if (id === "paletteStart" || id === "paletteEnd") {
+		// A POSITION ON THE MAP, not a share of the window: the percentages elsewhere on this
+		// screen are occupancy, and this one is not, so it says what it is along.
+		const position = Number(raw);
+		return position === 0 ? "start of the map" : position === 1 ? "end of the map" : `${Math.round(position * 100)}% along the map`;
+	}
 	// A PERCENTAGE, like every other human surface. The screen used to read "0.80" while
 	// the status line, /fold-status and the editor header all said "80%", so the one place
 	// a person CHANGES the number spoke a different dialect from the three that report it.
@@ -539,8 +600,14 @@ export class FoldSettingsEditor extends Container {
 			this.applyAndSave(id, rowRawValue(this.draft, id) === "true" ? "false" : "true");
 			return;
 		}
+		// A NAMED LIST steps by index, clamped at its ends like every other row.
+		if (id === "paletteMap") {
+			const at = (COLOUR_MAP_NAMES as readonly string[]).indexOf(rowRawValue(this.draft, id)) + direction;
+			if (at >= 0 && at < COLOUR_MAP_NAMES.length) this.applyAndSave(id, COLOUR_MAP_NAMES[at]);
+			return;
+		}
 		const thresholds = this.draft.thresholds ?? DEFAULT_THRESHOLDS;
-		const candidates = allowedValues(id, thresholds);
+		const candidates = allowedValues(id, thresholds, this.draft.palette ?? DEFAULT_FOLD_BAR_PALETTE);
 		const current = Number(rowRawValue(this.draft, id));
 		const target = direction > 0
 			? candidates.find((candidate) => candidate > current + 1e-9)
@@ -595,7 +662,7 @@ export function registerFoldSettings(
 ): void {
 	const settingsPath = options.settingsPath ?? DEFAULT_FOLD_SETTINGS_PATH;
 	pi.registerCommand("fold-settings", {
-		description: "Configure pi-fold: commit band, consolidation, fold size, tool-result clipping, brief invitation",
+		description: "Configure pi-fold: commit band, consolidation, fold size, tool-result clipping, the pre-commit notice, bar colours",
 		handler: async (_args: string, ctx: any) => {
 			if (typeof ctx.ui?.custom !== "function") {
 				throw new Error("/fold-settings needs an interactive UI; set thresholds in the settings file instead");

package/package.json

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