pi-fold 4.0.0 → 4.1.0

package/extensions/settings.ts

@@ -20,6 +20,7 @@ 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,
@@ -27,6 +28,7 @@ import {
 	ThresholdPolicyError,
 	type ActiveContextThresholds,
 } from "./lib/policy.ts";
+import { applyLiveSettings, liveSettingsReachable } from "./lib/live-settings.ts";
 
 export const DEFAULT_FOLD_SETTINGS_PATH = join(
 	homedir(),
@@ -43,7 +45,8 @@ export interface FoldSettingsFile {
 	// nothing but themselves, so absent simply means the package default, which is what
 	// lets an older file gain them without a migration.
 	toolFoldThreshold?: number;
-	postFoldNotice?: boolean;
+	preCommitNotice?: boolean;
+	noticeLeadShare?: number;
 }
 
 // The four settings, named once. This was a hand-written union until the migration
@@ -58,7 +61,7 @@ const THRESHOLD_FIELDS = [
 
 // 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", "postFoldNotice"] as const;
+const SCALAR_FIELDS = ["toolFoldThreshold", "preCommitNotice", "noticeLeadShare"] as const;
 
 export type FoldSettingId = typeof THRESHOLD_FIELDS[number] | typeof SCALAR_FIELDS[number];
 
@@ -75,12 +78,22 @@ export function applyFoldSettingsEdit(
 	id: FoldSettingId,
 	rawValue: string,
 ): { ok: true; draft: FoldSettingsFile } | { ok: false; error: string } {
-	if (id === "postFoldNotice") {
+	if (id === "preCommitNotice") {
 		const raw = rawValue.trim().toLowerCase();
 		if (raw !== "true" && raw !== "false") {
-			return { ok: false, error: "postFoldNotice is on or off" };
+			return { ok: false, error: "preCommitNotice is on or off" };
 		}
-		return { ok: true, draft: { ...draft, postFoldNotice: raw === "true" } };
+		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());
@@ -112,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
@@ -178,6 +199,15 @@ 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" || (SCALAR_FIELDS as readonly string[]).includes(key)) continue;
 		if (RETIRED_FILE_KEYS.includes(key)) { delete parsed[key]; dropped = true; continue; }
@@ -194,11 +224,11 @@ export function readFoldSettingsFile(path: string = DEFAULT_FOLD_SETTINGS_PATH):
 		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 === "postFoldNotice" && typeof value !== "boolean") {
-			return refused("fold settings postFoldNotice must be true or false");
+		if (field === "preCommitNotice" && typeof value !== "boolean") {
+			return refused("fold settings preCommitNotice must be true or false");
 		}
-		if (field === "toolFoldThreshold" && typeof value !== "number") {
-			return refused("fold settings toolFoldThreshold must be a number");
+		if ((field === "toolFoldThreshold" || field === "noticeLeadShare") && typeof value !== "number") {
+			return refused(`fold settings ${field} must be a number`);
 		}
 		Object.assign(scalars, applied.draft);
 	}
@@ -239,7 +269,8 @@ export function saveFoldSettingsFile(path: string, settings: FoldSettingsFile):
 	// 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.postFoldNotice !== undefined) clean.postFoldNotice = settings.postFoldNotice;
+	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`);
@@ -264,16 +295,25 @@ const EDITOR_ROWS: readonly EditorRow[] = [
 	{ 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: "postFoldNotice", label: "Ask the model for briefs", description: "Invite the model to rewrite a fold's summary. Off is what the measured runs used (postFoldNotice)" },
+	{ 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];
 
@@ -286,8 +326,8 @@ 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];
 
-function shareCandidates(id: "maxTarget" | "minTarget"): number[] {
-	const { min, max, step } = SHARE_STEPS[id];
+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);
@@ -299,12 +339,20 @@ function shareCandidates(id: "maxTarget" | "minTarget"): number[] {
 // 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 {
@@ -312,9 +360,9 @@ function rowRawValue(settings: FoldSettingsFile, id: FoldSettingId): string {
 	// 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)) {
-		return id === "toolFoldThreshold"
-			? String(settings.toolFoldThreshold ?? DEFAULT_TOOL_FOLD_THRESHOLD)
-			: String(settings.postFoldNotice ?? false);
+		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]);
@@ -322,7 +370,13 @@ function rowRawValue(settings: FoldSettingsFile, id: FoldSettingId): string {
 
 function rowDisplayValue(settings: FoldSettingsFile, id: FoldSettingId, budgetTokens: number): string {
 	const raw = rowRawValue(settings, id);
-	if (id === "postFoldNotice") return raw === "true" ? "on" : "off";
+	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.
@@ -422,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", "Percentages are of the usable window. Every change saves as you make it."), 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.
@@ -441,7 +502,7 @@ export class FoldSettingsEditor extends Container {
 			// 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: (_text: string) => theme.fg("dim", "←→ adjust · Enter types an exact value · Esc closes"),
+			hint: () => theme.fg("dim", "←→ adjust · Enter types an exact value · Esc closes"),
 		};
 		this.settingsList = new SettingsList(
 			EDITOR_ROWS.map((row) => ({
@@ -474,7 +535,7 @@ export class FoldSettingsEditor extends Container {
 	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 === "postFoldNotice") {
+		if (id === "preCommitNotice") {
 			this.applyAndSave(id, rowRawValue(this.draft, id) === "true" ? "false" : "true");
 			return;
 		}
@@ -493,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);
@@ -541,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": "4.0.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": [