pi-fold 3.1.0 → 4.1.0

package/extensions/lib/tool-surface.ts

@@ -7,8 +7,6 @@
  * nothing: the next model call that reads a result, a natural boundary in the work.
  */
 
-import { MEMORY_BODY_CHARS, MEMORY_KEY_CHARS, MEMORY_KEYS_MAX } from "./policy.ts";
-
 type ToolHandler = (
   toolCallId: string,
   params: Record<string, unknown>,
@@ -45,16 +43,13 @@ export function buildActiveContextTool(input: {
   const recoveryGuidance = input.allowedActions.includes("expand")
     ? " A fold brief is an index entry, not the source: when a question or task depends on material that is folded, peek or expand that fold and answer from the exact bytes, never from memory of them. Recalling folded detail without reopening it is how specifics get misremembered."
     : "";
-  const memoryGuidance = input.allowedActions.includes("remember")
-    ? ` WORKING MEMORY: a session-scoped dictionary you maintain beside the fold index. remember with key and body writes or updates an entry (${MEMORY_KEY_CHARS}-character keys, ${MEMORY_BODY_CHARS}-character bodies, ${MEMORY_KEYS_MAX} entries); an empty body removes it; recall with keys reads bodies back, or everything when keys is omitted. The bodies live outside your window: only a one-glance table of contents rides your context, refreshed at each commit, so writing an entry costs your window almost nothing. Keep entries current as the work moves: when a fact an entry records changes, or new information lands that belongs in one, update it then rather than at the end.`
-    : "";
   const standingGuidance = " Folding is automatic, lossless and recoverable: the runtime folds stale spans on its own when the window needs room, nothing is ever discarded, and every folded span keeps its exact source. You are never asked to make room and no fold is ever announced in advance. Work normally and let it happen.";
   return {
     name: input.name,
     label: input.label,
     description: input.fullSurface
-      ? `Page, peek, brief, expand, refold, pin, or re-cut exact Pi active-context evidence.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${memoryGuidance}${standingGuidance} Mutations persist immediately and affect the next model call inside the same continuing turn; no turn boundary is required. Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`
-      : `Use only the configured active-context actions: ${input.allowedActions.join(", ")}.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${memoryGuidance}${standingGuidance} Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`,
+      ? `Page, peek, brief, expand, refold, pin, or re-cut exact Pi active-context evidence.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${standingGuidance} Mutations persist immediately and affect the next model call inside the same continuing turn; no turn boundary is required. Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`
+      : `Use only the configured active-context actions: ${input.allowedActions.join(", ")}.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${standingGuidance} Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`,
     parameters: {
       type: "object",
       additionalProperties: false,
@@ -89,31 +84,6 @@ export function buildActiveContextTool(input: {
         },
         limit: { type: "integer", minimum: 1, maximum: 100 },
         detail: { type: "string", enum: [...input.statusDetails] },
-        ...(input.allowedActions.includes("remember")
-          ? {
-            key: {
-              type: "string",
-              minLength: 1,
-              maxLength: MEMORY_KEY_CHARS,
-              description: "remember only: the working-memory entry to write, update or " +
-                "(with an empty body) remove.",
-            },
-            body: {
-              type: "string",
-              maxLength: MEMORY_BODY_CHARS,
-              description: "remember only: the entry's full text, replacing what the key " +
-                "held. Empty removes the entry.",
-            },
-            keys: {
-              type: "array",
-              minItems: 1,
-              maxItems: MEMORY_KEYS_MAX,
-              items: { type: "string", minLength: 1 },
-              description: "recall only: the working-memory entries to read. Omit to read " +
-                "every entry.",
-            },
-          }
-          : {}),
       },
     },
     execute: input.handler,

package/extensions/lib/transcript.ts

@@ -31,6 +31,49 @@ import type {
   MappedMessage,
 } from "./policy.ts";
 
+/**
+ * ONE MESSAGE, AS THE TEXT A PERSON WOULD READ (2026-08-30).
+ *
+ * WHAT THIS REPLACED. `/fold-editor` built its entry previews inline, and the reading was
+ * `content.find((part) => part.type === "text")` sliced to 300 characters. So a message
+ * whose first block is not text previewed as the empty string, a tool result carrying its
+ * body in a later block previewed as its first block alone, and everything past 300
+ * characters was unreachable from the editor at any depth: the detail row sliced to 480,
+ * a bound the 300-character preview could never reach, so the deeper number was dead.
+ * Shane, 2026-08-30: "the amount of detail we can expand out to is a bit limited".
+ *
+ * EVERY BLOCK IS ACCOUNTED FOR, and the ones that are not text are NAMED rather than
+ * dropped. A window a person is auditing may not show them an empty row where an image or
+ * a tool call stands; naming it is how the row stays honest about what it could not
+ * render. The result is UNBOUNDED here on purpose. Bounding belongs to the caller, which
+ * knows whether it is drawing a one-line row or serving a paged read, and a cut applied
+ * here would be a cut nobody could state.
+ */
+export function entryText(message: unknown): string {
+  const content = ownValue(message, "content");
+  if (typeof content === "string") return content;
+  const parts = denseOwnArrayValues(content);
+  if (!parts) return "";
+  const out: string[] = [];
+  for (const part of parts) {
+    if (typeof part === "string") { out.push(part); continue; }
+    const type = ownValue(part, "type");
+    const text = ownValue(part, "text");
+    if (typeof text === "string" && text) { out.push(text); continue; }
+    if (type === "toolCall") {
+      const name = ownValue(part, "name");
+      // The ARGUMENTS are the content of a tool call, and they are what a person auditing
+      // a window needs to see: the call is why the result below it exists.
+      const args = ownValue(part, "arguments");
+      out.push(`[calls ${typeof name === "string" ? name : "a tool"}` +
+        `${args === undefined ? "" : ` ${stableStringify(args)}`}]`);
+      continue;
+    }
+    out.push(`[${typeof type === "string" && type ? type : "content"}]`);
+  }
+  return out.join("\n");
+}
+
 export function terminalAssistant(message: unknown): boolean {
   if (messageRole(message) !== "assistant") return false;
   const stop = ownValue(message, "stopReason");

package/extensions/settings.ts

@@ -20,12 +20,15 @@ import { dirname, join } from "node:path";
 import { Container, Input, Key, matchesKey, SettingsList, Spacer, Text } from "@earendil-works/pi-tui";
 import {
 	DEFAULT_CONTEXT_WINDOW,
+	DEFAULT_NOTICE_LEAD_SHARE,
 	DEFAULT_THRESHOLDS,
+	DEFAULT_TOOL_FOLD_THRESHOLD,
 	resolveThresholds,
 	servingBudgetTokens,
 	ThresholdPolicyError,
 	type ActiveContextThresholds,
 } from "./lib/policy.ts";
+import { applyLiveSettings, liveSettingsReachable } from "./lib/live-settings.ts";
 
 export const DEFAULT_FOLD_SETTINGS_PATH = join(
 	homedir(),
@@ -36,6 +39,14 @@ export const DEFAULT_FOLD_SETTINGS_PATH = join(
 
 export interface FoldSettingsFile {
 	thresholds?: ActiveContextThresholds;
+	// TWO INDEPENDENT SCALARS, NOT A SECOND WHOLE-OBJECT (2026-08-28). The thresholds
+	// object is stored whole because its fields carry cross-field invariants and a partial
+	// one would silently mean whatever the defaults are at read time. These two answer to
+	// nothing but themselves, so absent simply means the package default, which is what
+	// lets an older file gain them without a migration.
+	toolFoldThreshold?: number;
+	preCommitNotice?: boolean;
+	noticeLeadShare?: number;
 }
 
 // The four settings, named once. This was a hand-written union until the migration
@@ -48,7 +59,15 @@ const THRESHOLD_FIELDS = [
 	"minFoldChars",
 ] as const;
 
-export type FoldSettingId = typeof THRESHOLD_FIELDS[number];
+// The settings that are NOT thresholds. Each is a top-level scalar with its own
+// 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];
+
+function isThresholdField(id: FoldSettingId): id is typeof THRESHOLD_FIELDS[number] {
+	return (THRESHOLD_FIELDS as readonly string[]).includes(id);
+}
 
 // One edit, applied against the WHOLE draft: the merged thresholds object is
 // re-validated through resolveThresholds so cross-field invariants
@@ -59,6 +78,33 @@ export function applyFoldSettingsEdit(
 	id: FoldSettingId,
 	rawValue: string,
 ): { ok: true; draft: FoldSettingsFile } | { ok: false; error: string } {
+	if (id === "preCommitNotice") {
+		const raw = rawValue.trim().toLowerCase();
+		if (raw !== "true" && raw !== "false") {
+			return { ok: false, error: "preCommitNotice is on or off" };
+		}
+		return { ok: true, draft: { ...draft, preCommitNotice: raw === "true" } };
+	}
+	if (id === "noticeLeadShare") {
+		const value = Number(rawValue.trim());
+		// The runtime's own range, restated here so the screen refuses before the file does:
+		// a share strictly inside 0 and 1. Zero would put the notice on the same pass as the
+		// commit it warns about, which is not a warning.
+		if (!Number.isFinite(value) || value <= 0 || value >= 1) {
+			return { ok: false, error: "noticeLeadShare is a share above 0 and below 1: how far below the commit point the notice speaks" };
+		}
+		return { ok: true, draft: { ...draft, noticeLeadShare: value } };
+	}
+	if (id === "toolFoldThreshold") {
+		const value = Number(rawValue.trim());
+		// The runtime's own range, restated here so the screen refuses before the file
+		// does: [0, 1) with 0 meaning off. Absence would ALSO mean the default rather
+		// than off, which is why 0 has to be expressible.
+		if (!Number.isFinite(value) || value < 0 || value >= 1) {
+			return { ok: false, error: "toolFoldThreshold is a share from 0 up to but not including 1; 0 turns it off" };
+		}
+		return { ok: true, draft: { ...draft, toolFoldThreshold: value } };
+	}
 	try {
 		const value = Number(rawValue.trim());
 		if ((id === "consolidateAfter" || id === "minFoldChars") && !Number.isSafeInteger(value)) {
@@ -79,6 +125,14 @@ export function applyFoldSettingsEdit(
 // user surface on 2026-08-21 and stayed a registration option for the harness.
 const RETIRED_FILE_KEYS: readonly string[] = ["providerInputBudget"];
 
+// Keys this surface RENAMED, carried across with their VALUE (2026-08-30). postFoldNotice
+// was on the screen from 2026-08-27 and became preCommitNotice when the carrier stopped
+// soliciting briefs and started stating status. Dropping it the way a retired key is
+// dropped would silently revert a deployment that had deliberately turned the carrier ON,
+// and refusing it would revert every other value in the file over a key this package
+// itself wrote. Both readings mean the same thing on the same carrier, so the value moves.
+const RENAMED_FILE_KEYS: Readonly<Record<string, FoldSettingId>> = { postFoldNotice: "preCommitNotice" };
+
 // Threshold fields this package's own surface used to write. freshTail was the fifth
 // setting until 2026-08-23, when fresh-tail protection was deleted outright: nothing
 // decided on it, and stale-first ordering already leaves recent material last. A stored
@@ -145,14 +199,42 @@ export function readFoldSettingsFile(path: string = DEFAULT_FOLD_SETTINGS_PATH):
 	// wrote providerInputBudget until 2026-08-21, so refusing it would revert a file
 	// this package created. A key that was never on the surface is still a refusal.
 	let dropped = false;
+	for (const [from, to] of Object.entries(RENAMED_FILE_KEYS)) {
+		if (!Object.prototype.hasOwnProperty.call(parsed, from)) continue;
+		// The new name wins if a hand-edited file somehow carries both, since that is the
+		// one the screen and the runtime read; either way the old key leaves and the file is
+		// written back whole under the current surface.
+		if (parsed[to] === undefined) parsed[to] = parsed[from];
+		delete parsed[from];
+		dropped = true;
+	}
 	for (const key of Object.keys(parsed)) {
-		if (key === "thresholds") continue;
+		if (key === "thresholds" || (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`);
+		return refused(`fold settings file has no ${key} field: the surface is ` +
+			`thresholds, ${SCALAR_FIELDS.join(", ")}`);
+	}
+	// 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.
+	const scalars: FoldSettingsFile = {};
+	for (const field of SCALAR_FIELDS) {
+		if (parsed[field] === undefined) continue;
+		const value = parsed[field];
+		const applied = applyFoldSettingsEdit({}, field, String(value));
+		if (!applied.ok) return refused(`fold settings ${field} is invalid: ${applied.error}`);
+		// String("0.5") round-trips, but a JSON string would too, and the file's own type
+		// has to be right or the value means something different on the next read.
+		if (field === "preCommitNotice" && typeof value !== "boolean") {
+			return refused("fold settings preCommitNotice must be true or false");
+		}
+		if ((field === "toolFoldThreshold" || field === "noticeLeadShare") && typeof value !== "number") {
+			return refused(`fold settings ${field} must be a number`);
+		}
+		Object.assign(scalars, applied.draft);
 	}
 	if (parsed.thresholds === undefined) {
-		if (dropped) { try { saveFoldSettingsFile(path, {}); } catch { } }
-		return { settings: {}, refusal: null, migrated: dropped };
+		if (dropped) { try { saveFoldSettingsFile(path, scalars); } catch { } }
+		return { settings: scalars, refusal: null, migrated: dropped };
 	}
 	const stored = parsed.thresholds;
 	if (!stored || typeof stored !== "object" || Array.isArray(stored)) {
@@ -169,8 +251,9 @@ export function readFoldSettingsFile(path: string = DEFAULT_FOLD_SETTINGS_PATH):
 			? { ...Object.fromEntries(missing.map((field) => [field, DEFAULT_THRESHOLDS[field]])), ...supplied }
 			: supplied);
 		const migrated = missing.length > 0 || dropped;
-		if (migrated) { try { saveFoldSettingsFile(path, { thresholds }); } catch { } }
-		return { settings: { thresholds }, refusal: null, migrated };
+		const settings: FoldSettingsFile = { thresholds, ...scalars };
+		if (migrated) { try { saveFoldSettingsFile(path, settings); } catch { } }
+		return { settings, refusal: null, migrated };
 	} catch (error: any) {
 		return refused(`fold settings file at ${path} is invalid: ${error?.message ?? error}`);
 	}
@@ -183,6 +266,11 @@ export function loadFoldSettingsFile(path: string = DEFAULT_FOLD_SETTINGS_PATH):
 export function saveFoldSettingsFile(path: string, settings: FoldSettingsFile): void {
 	const clean: FoldSettingsFile = {};
 	if (settings.thresholds !== undefined) clean.thresholds = settings.thresholds;
+	// Written only when SET. An absent scalar means the package default, and writing the
+	// default out would pin today's value into a file that should follow the package.
+	if (settings.toolFoldThreshold !== undefined) clean.toolFoldThreshold = settings.toolFoldThreshold;
+	if (settings.preCommitNotice !== undefined) clean.preCommitNotice = settings.preCommitNotice;
+	if (settings.noticeLeadShare !== undefined) clean.noticeLeadShare = settings.noticeLeadShare;
 	mkdirSync(dirname(path), { recursive: true });
 	const temporary = `${path}.tmp`;
 	writeFileSync(temporary, `${JSON.stringify(clean, null, 2)}\n`);
@@ -195,20 +283,37 @@ interface EditorRow {
 	description: string;
 }
 
+// WRITTEN FOR THE READER, NOT THE IMPLEMENTER (2026-08-28). "Fires a fold epoch" and
+// "parents owed per epoch = visible roots divided by this" are this codebase's words for
+// its own internals, and a person setting a value should not have to learn them. Each
+// description now says what the setting DOES to their session; the option name stays in
+// parentheses as the bridge to the README table and to registerPiFold, which document
+// these exact names.
 const EDITOR_ROWS: readonly EditorRow[] = [
-	{ id: "maxTarget", label: "Commit trigger", description: "Occupancy share of the budget that fires a fold epoch (maxTarget)" },
-	{ id: "minTarget", label: "Post-commit aim", description: "Share the epoch cuts back down toward (minTarget)" },
-	{ id: "consolidateAfter", label: "Consolidation divisor", description: "Parents owed per epoch = visible roots divided by this (consolidateAfter)" },
-	{ id: "minFoldChars", label: "Minimum fold size", description: "Characters a fold must reach to be worth making; a smaller gap between folds is absorbed by the fold beside it (minFoldChars)" },
+	{ id: "maxTarget", label: "Start folding at", description: "How full the window gets before pi-fold folds. Nothing moves below this (maxTarget)" },
+	{ id: "minTarget", label: "Fold down to", description: "How empty a fold leaves the window. The gap between the two sets how often folding runs (minTarget)" },
+	{ id: "consolidateAfter", label: "Folds per group", description: "Once this many folds are visible, pi-fold groups them under one (consolidateAfter)" },
+	{ id: "minFoldChars", label: "Smallest fold", description: "Text this short is not worth folding on its own; it joins the fold beside it instead (minFoldChars)" },
+	{ 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 cycle lattices. Shares step in cents so no float drift reaches a threshold;
-// each row's list is FILTERED against the current draft before display, which is
-// what makes an invalid combination unselectable rather than an error message.
-const SHARE_STEPS: Record<"maxTarget" | "minTarget", { min: number; max: number; step: number }> = {
-	maxTarget: { min: 0.40, max: 0.95, step: 0.05 },
-	minTarget: { min: 0.05, max: 0.60, step: 0.05 },
-};
+// The cycle lattice for both shares. Shares step in cents so no float drift reaches a
+// threshold; each row's list is FILTERED against the current draft before display, which
+// is what makes an invalid combination unselectable rather than an error message.
+//
+// ONE LATTICE, AND ITS ONLY GUARDS ARE THE POLICY'S OWN (Shane, 2026-08-29). The rows
+// used to carry ranges of their own, 0.40 to 0.95 for the trigger and 0.05 to 0.60 for
+// the aim, and nothing in the runtime asks for either bound: resolveThresholds wants a
+// share strictly between 0 and 1 with the aim below the trigger, and that is all. Found
+// in use on a 1,000,000-token window, where 0.40 is a first fold at about 393,000 tokens:
+// later than the person wanted to start, reachable past only through Enter's exact-value
+// editor, and one arrow keypress after that snapped the value back up to 0.40, because
+// the lattice did not contain where they were standing.
+// The lattice now spans the legal range at the same step, so stepping is the ordinary
+// way to reach a low band and typing is only for values finer than the step.
+const SHARE_LATTICE = { min: 0.05, max: 0.95, step: 0.05 };
 
 const CONSOLIDATE_CHOICES = [2, 3, 4, 5, 6, 8, 10, 12, 15, 20];
 
@@ -217,8 +322,12 @@ const CONSOLIDATE_CHOICES = [2, 3, 4, 5, 6, 8, 10, 12, 15, 20];
 // enforces, below which a placeholder can cost more than the source it replaces.
 const MIN_FOLD_CHOICES = [2_000, 4_000, 6_000, 8_000, 12_000, 16_000, 24_000, 32_000];
 
-function shareCandidates(id: "maxTarget" | "minTarget"): number[] {
-	const { min, max, step } = SHARE_STEPS[id];
+// 0 IS ON THE LATTICE, and first, because absence means the package default rather than
+// 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];
+
+function shareCandidates(): number[] {
+	const { min, max, step } = SHARE_LATTICE;
 	const values: number[] = [];
 	for (let cents = Math.round(min * 100); cents <= Math.round(max * 100); cents += Math.round(step * 100)) {
 		values.push(cents / 100);
@@ -229,26 +338,56 @@ function shareCandidates(id: "maxTarget" | "minTarget"): 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[] {
+	if (id === "toolFoldThreshold") return TOOL_FOLD_CHOICES;
+	// 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
+	// cross-field invariant here for a filter to enforce.
+	if (id === "noticeLeadShare") return shareCandidates();
 	if (id === "consolidateAfter") return CONSOLIDATE_CHOICES;
 	if (id === "minFoldChars") return MIN_FOLD_CHOICES;
 	const { minTarget, maxTarget } = thresholds;
+	// The cross-field invariant IS the filter, so a row can be stepped to any legal share
+	// and never to an illegal one; the trigger stops one increment above the aim rather
+	// than at some number chosen here.
 	return id === "maxTarget"
-		? shareCandidates("maxTarget").filter((v) => v > minTarget)
-		: shareCandidates("minTarget").filter((v) => v < maxTarget);
+		? shareCandidates().filter((v) => v > minTarget)
+		: shareCandidates().filter((v) => v < maxTarget);
 }
 
 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 (!isThresholdField(id)) {
+		if (id === "toolFoldThreshold") return String(settings.toolFoldThreshold ?? DEFAULT_TOOL_FOLD_THRESHOLD);
+		if (id === "noticeLeadShare") return String(settings.noticeLeadShare ?? DEFAULT_NOTICE_LEAD_SHARE);
+		return String(settings.preCommitNotice ?? false);
+	}
 	const thresholds = settings.thresholds ?? DEFAULT_THRESHOLDS;
 	return String(thresholds[id]);
 }
 
 function rowDisplayValue(settings: FoldSettingsFile, id: FoldSettingId, budgetTokens: number): string {
 	const raw = rowRawValue(settings, id);
+	if (id === "preCommitNotice") return raw === "true" ? "on" : "off";
+	if (id === "noticeLeadShare") {
+		// STATED AS THE DISTANCE IT IS, in the same dialect as the two band rows: a share of
+		// the budget, with the tokens it works out to, because "10%" alone reads as a point
+		// on the bar rather than as a gap before one.
+		return `${Math.round(Number(raw) * 100)}% earlier · ${Math.round(Number(raw) * budgetTokens).toLocaleString("en-US")} tokens`;
+	}
+	if (id === "toolFoldThreshold") {
+		// The share is of the window rather than of a budget, so it is stated as the
+		// slice it names instead of the token count the other two shares translate to.
+		return Number(raw) === 0 ? "off" : `oldest ${Math.round(Number(raw) * 100)}%`;
+	}
 	if (id === "consolidateAfter") return raw;
-	if (id === "minFoldChars") return `${Number(raw).toLocaleString("en-US")} chars`;
-	// toFixed(2) matches the cycle entries exactly; String(0.8) renders "0.8" while
-	// the cycle list carries "0.80", and SettingsList cycles by indexOf(currentValue).
-	return `${Number(raw).toFixed(2)} · ${Math.round(Number(raw) * budgetTokens).toLocaleString("en-US")} tok`;
+	if (id === "minFoldChars") return `${Number(raw).toLocaleString("en-US")} characters`;
+	// 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.
+	return `${Math.round(Number(raw) * 100)}% · ${Math.round(Number(raw) * budgetTokens).toLocaleString("en-US")} tokens`;
 }
 
 // The frame Pi's own /settings screen draws around its list. Implemented locally
@@ -337,12 +476,19 @@ export class FoldSettingsEditor extends Container {
 		// place a refused file is ever named, so it says so before showing the
 		// defaults that took its place.
 		notice: string | null = null,
+		// THE RUNNING SESSION, when there is one to reach. Given, every saved edit is
+		// pushed into the runtime registered on the same host and takes effect at once;
+		// absent, the file is still written and the next start reads it. The screen SAYS
+		// which of the two it is rather than promising the one it cannot deliver.
+		private readonly live: ((settings: FoldSettingsFile) => void) | null = null,
 	) {
 		super();
 		const theme = this.themeLike;
 		this.addChild(new SettingsBorder((text) => theme.fg("border", text)));
 		this.addChild(new Text(theme.bold(theme.fg("accent", "pi-fold settings")), 0, 0));
-		this.addChild(new Text(theme.fg("muted", "Shares are of the serving budget; edits save immediately. ←→ steps · Enter types an exact value."), 0, 0));
+		this.addChild(new Text(theme.fg("muted", live
+			? "Percentages are of the usable window. Every change saves and takes effect at once."
+			: "Percentages are of the usable window. Every change saves now and applies when pi next starts."), 0, 0));
 		if (notice) this.addChild(new Text(theme.fg("error", notice), 0, 0));
 		this.addChild(new Spacer(1));
 		// SettingsList takes its own theme shape; adapt it off the live theme.
@@ -351,7 +497,12 @@ export class FoldSettingsEditor extends Container {
 			value: (text: string, selected: boolean) => (selected ? theme.fg("accent", text) : theme.fg("muted", text)),
 			description: (text: string) => theme.fg("dim", text),
 			cursor: theme.fg("accent", "→ "),
-			hint: (text: string) => theme.fg("dim", text),
+			// SettingsList ships its own hint, "Enter/Space to change · Esc to cancel", and
+			// BOTH halves are wrong on this screen: Enter opens an exact-value editor rather
+			// than cycling a value, and nothing is cancelled because every change is saved
+			// the moment it is made. The hint function is ours and is handed the string, so
+			// the correction happens here rather than being contradicted a line below.
+			hint: () => theme.fg("dim", "←→ adjust · Enter types an exact value · Esc closes"),
 		};
 		this.settingsList = new SettingsList(
 			EDITOR_ROWS.map((row) => ({
@@ -375,8 +526,6 @@ export class FoldSettingsEditor extends Container {
 			() => this.done(true),
 		);
 		this.addChild(this.settingsList);
-		this.addChild(new Spacer(1));
-		this.addChild(new Text(theme.fg("dim", "  ←→ to step · Enter for exact · Esc to close"), 0, 0));
 		this.addChild(new SettingsBorder((text) => theme.fg("border", text)));
 	}
 
@@ -384,6 +533,12 @@ export class FoldSettingsEditor extends Container {
 	// filtered against the CURRENT draft, so stepping can never leave the policy
 	// surface; an exact off-lattice value arrives only through Enter's editor.
 	private step(id: FoldSettingId, direction: number): void {
+		// A SWITCH HAS NO LATTICE. Either direction moves to the other value, which is
+		// what a person expects of a two-state row sitting among stepped ones.
+		if (id === "preCommitNotice") {
+			this.applyAndSave(id, rowRawValue(this.draft, id) === "true" ? "false" : "true");
+			return;
+		}
 		const thresholds = this.draft.thresholds ?? DEFAULT_THRESHOLDS;
 		const candidates = allowedValues(id, thresholds);
 		const current = Number(rowRawValue(this.draft, id));
@@ -399,6 +554,12 @@ export class FoldSettingsEditor extends Container {
 		if (!result.ok) return result;
 		this.draft = result.draft;
 		saveFoldSettingsFile(this.settingsPath, this.draft);
+		// THE FILE FIRST, THE SESSION SECOND. The draft has already been through
+		// resolveThresholds, which is the same validation the runtime applies, so a refusal
+		// here would be a defect rather than a person's mistake; it is caught anyway,
+		// because a settings screen may not take down the session it configures, and the
+		// durable file is already correct for the next start either way.
+		if (this.live) { try { this.live(this.draft); } catch { } }
 		for (const row of EDITOR_ROWS) {
 			const item = (this.settingsList as any).items.find((candidate: any) => candidate.id === row.id);
 			if (item) item.currentValue = rowDisplayValue(this.draft, row.id, this.budgetTokens);
@@ -434,7 +595,7 @@ export function registerFoldSettings(
 ): void {
 	const settingsPath = options.settingsPath ?? DEFAULT_FOLD_SETTINGS_PATH;
 	pi.registerCommand("fold-settings", {
-		description: "Configure pi-fold: commit trigger, post-commit aim, consolidation divisor, minimum fold size",
+		description: "Configure pi-fold: commit band, consolidation, fold size, tool-result clipping, brief invitation",
 		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");
@@ -447,9 +608,16 @@ export function registerFoldSettings(
 			// experiment harness, which declares a budget so runs stay comparable across
 			// descriptor changes; no person has to know that to read this screen.
 			const budgetTokens = servingBudgetTokens(descriptorWindow);
+			// THE CHANNEL TO THE RUNNING RUNTIME, read HERE rather than at registration: this
+			// module and registerPiFold are registered independently and in either order, and
+			// by the time a person opens this screen both have run. A host with no runtime on
+			// it gets a null, which the screen states plainly.
+			const live = liveSettingsReachable(pi)
+				? (settings: FoldSettingsFile) => { applyLiveSettings(pi, settings, ctx); }
+				: null;
 			await ctx.ui.custom((_tui: unknown, theme: any, _keybindings: unknown, done: (saved: boolean) => void) =>
 				new FoldSettingsEditor(
-					stored.settings, budgetTokens, settingsPath, theme, done, stored.refusal,
+					stored.settings, budgetTokens, settingsPath, theme, done, stored.refusal, live,
 				));
 		},
 	});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-fold",
-  "version": "3.1.0",
-  "description": "Lossless, agent-governed context folding for the Pi coding agent: only the oldest context changes; the fresh window stays untouched.",
+  "version": "4.1.0",
+  "description": "Lossless context folding for the Pi coding agent: only the oldest context changes; the fresh window stays untouched.",
   "keywords": [
     "pi-package",
     "pi",
@@ -18,10 +18,10 @@
   "private": false,
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/shaneconner/pi-fold.git"
+    "url": "git+https://github.com/shaneconner/fold.git"
   },
-  "bugs": "https://github.com/shaneconner/pi-fold/issues",
-  "homepage": "https://github.com/shaneconner/pi-fold#readme",
+  "bugs": "https://github.com/shaneconner/fold/issues",
+  "homepage": "https://github.com/shaneconner/fold#readme",
   "author": "Shane Conner",
   "license": "MIT",
   "files": [