pi-umbra 0.1.4 → 0.2.0

package/node_modules/pi-umbra-theme/checks/umbra-working.check.ts

@@ -5,7 +5,8 @@
 import assert from "node:assert";
 import { visibleWidth } from "@earendil-works/pi-tui";
 import { compact, elapsed } from "../lib/umbra-format.ts";
-import { type Turn, entryFor, indicatorFor, labelFor, newTurn, statusLine } from "../extensions/umbra-working.ts";
+import { type Turn, entryFor, indicatorFor, labelFor, newTurn, statusLine,
+	streamingOf, syncedCycleMs } from "../extensions/umbra-working.ts";
 
 const ON = { tokens: true, elapsed: true };
 const TOOLS = ["read", "ls", "find", "grep", "write", "edit", "bash", "powershell"];
@@ -95,6 +96,13 @@ assert.equal(statusLine(at({ key: "fabric_exec" }), 1_000, ON, renamed), "Fabric
 
 // Streaming output counts before the message ends, or the number stands still mid-answer.
 assert.equal(statusLine(at({ settled: 100, streaming: 80 }), 5_000, ON), "Working… (5s · ↓ 180 tokens)");
+// A message in flight marks the count, which a provider may not move until the message ends.
+assert.equal(statusLine(at({ settled: 17_700, streaming: 6, open: true }), 5_000, ON), "Working… (5s · ↓ ~17.7k tokens)");
+assert.equal(statusLine(at({ open: true }), 1_000, ON), "Working… (1s)", "nothing counted yet: no arrow, no ~");
+const streamed = (usage: number, content: unknown[]) => ({ role: "assistant", usage: { output: usage }, content }) as never;
+assert.equal(streamingOf(streamed(4, [{ type: "thinking", thinking: "x".repeat(4000) }])), 1000, "the bridge's stale 4 loses to the text");
+assert.equal(streamingOf(streamed(4, [{ type: "text", text: "abcdefgh" }, { type: "toolCall", arguments: { a: 1 } }])), 4, "text 8 + args 7 chars");
+assert.equal(streamingOf(streamed(900, [{ type: "text", text: "short" }])), 900, "a larger reported count wins");
 
 // "thought for" belongs to the Thinking line alone and counts from zero at the block, so the two
 // numbers on that line are the turn and this thought - not the turn twice.
@@ -116,5 +124,29 @@ assert.equal(elapsed(-5), "0s", "a clock that went backwards must not print a ne
 assert.equal(compact(695), "695");
 assert.equal(compact(7_013), "7.0k");
 assert.equal(compact(224_310), "224k");
+assert.equal(compact(999_600), "1M", "no 1000k: the context window reads 1M");
+assert.equal(compact(1_697_000), "1.7M");
+assert.equal(compact(88_149_651), "88.1M");
+assert.equal(compact(250_000_000), "250M");
 
 console.log(`umbra-working.check.ts ok - ${KEYS.length} keys, frames 8 cases, settings 9, line 12, format 7`);
+
+// Spinner locked to the shimmer: whole loops per wave, and the shimmer speed scales both.
+assert.equal(syncedCycleMs(2000, 1), 500, "classic: 4 loops per 2000 ms wave");
+assert.equal(syncedCycleMs(4000, 0.5), 1000, "classic 0.5: same 4 loops, each twice as long");
+assert.equal(syncedCycleMs(2200, 1), 440, "kitt: 5 loops per 2200 ms round trip");
+const classic = { periodMs: 2000, speed: 1 };
+assert.equal(indicatorFor("idle", {}, classic).intervalMs, 63, "8 frames share the synced loop");
+assert.equal(indicatorFor("bash", {}, classic).intervalMs, 125, "4 frames share the same loop");
+assert.equal(indicatorFor("bash", { tools: { bash: { cycleMs: 900 } } }, classic).intervalMs, 225, "a set cycleMs still wins");
+// classic 2 once ran the 8-frame set at 31 ms a frame; it now turns twice per wave, not four times.
+assert.equal(syncedCycleMs(1000, 2, 8), 500, "8 frames: loops drop until a frame takes >= 60 ms");
+assert.equal(syncedCycleMs(1000, 2, 4), 250, "4 frames already fit four loops");
+assert.equal(indicatorFor("idle", {}, { periodMs: 1000, speed: 2 }).intervalMs, 63);
+assert.equal(syncedCycleMs(250, 8, 8), 250, "one loop per wave is the floor; the wave itself is that fast");
+for (const [period, speed] of [[2000, 1], [1000, 2], [500, 4], [4400, 0.5], [2200, 1]] as const) {
+	for (const frames of [3, 4, 6, 8]) {
+		const loop = syncedCycleMs(period, speed, frames);
+		assert.ok(Number.isInteger(Math.round((period / loop) * 1e9) / 1e9), `${period}/${speed}/${frames}: whole loops per wave`);
+	}
+}

package/node_modules/pi-umbra-theme/extensions/umbra-background.ts

@@ -27,7 +27,7 @@ const resetBackground = () => process.stdout.write("\x1b]111\x07");
 type Settings = { background?: string };
 
 const readSetting = (): string => {
-    const path = `${process.env.PI_AGENT_DIR ?? `${process.env.USERPROFILE ?? process.env.HOME}/.pi/agent`}/settings.json`;
+    const path = `${process.env.PI_CODING_AGENT_DIR ?? `${process.env.USERPROFILE ?? process.env.HOME}/.pi/agent`}/settings.json`;
     try {
         const settings = JSON.parse(readFileSync(path, "utf8")) as Record<string, Settings>;
         return settings[SETTINGS_KEY]?.background ?? "auto";

package/node_modules/pi-umbra-theme/extensions/umbra-footer.ts

@@ -1,8 +1,29 @@
 import type { AssistantMessage, Usage } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { homedir } from "node:os";
 import { compact } from "../lib/umbra-format.ts";
 
+const HOME = homedir();
+
+/**
+ * `read` at most once per `ms`, the last value in between. pi's getContextUsage walks the whole
+ * session branch on every call and the footer renders with every frame, so a 2300-message session
+ * spent ~5% of a core recounting a number that moves once per message.
+ */
+export const everyMs = <T>(ms: number, read: () => T, now: () => number = Date.now): (() => T) => {
+	let at = Number.NEGATIVE_INFINITY;
+	let value: T;
+	return () => {
+		const time = now();
+		if (time - at >= ms) {
+			value = read();
+			at = time;
+		}
+		return value;
+	};
+};
+
 const ANSI_CODES = /\x1b\[[0-9;]*m/g;
 
 const ponytailLevel = (statuses: ReadonlyMap<string, string>) => {
@@ -66,6 +87,10 @@ export default function (pi: ExtensionAPI) {
 	// paint — dozens of times a second while a reply streams, and O(session) each time.
 	let cost = 0;
 	let lastTurn: Usage | undefined;
+	// Session totals. Input counts a token once, when it is first sent: fresh input plus cache
+	// writes. Cache reads re-send the same context every turn and would count it again each time.
+	let sent = 0;
+	let received = 0;
 	let repaint: (() => void) | undefined;
 
 	const refresh = (ctx: ExtensionContext) => {
@@ -76,6 +101,8 @@ export default function (pi: ExtensionAPI) {
 		// On a subscription this is not what was billed — it is what the provider priced the
 		// turns at, and only a provider that reports per-turn cost fills it in at all.
 		cost = messages.reduce((sum, message) => sum + message.usage.cost.total, 0);
+		sent = messages.reduce((sum, message) => sum + message.usage.input + message.usage.cacheWrite, 0);
+		received = messages.reduce((sum, message) => sum + message.usage.output, 0);
 		lastTurn = messages.at(-1)?.usage;
 		repaint?.();
 	};
@@ -87,9 +114,25 @@ export default function (pi: ExtensionAPI) {
 	// entry landed, so new usage waited for whatever redrew the screen next — usually a keystroke.
 	pi.on("agent_end", (_event, ctx) => refresh(ctx));
 
+	// agent_end closes the whole run, and a run with many tool calls can take minutes; waiting for
+	// it left the context and cache groups on the previous run the whole time. Each assistant
+	// message carries its own usage, so the footer takes it as each message ends, and agent_end
+	// still recounts from the persisted branch. Not while it streams: claude-bridge fills usage in
+	// only at a message's start and end, so mid-stream they would show the opening numbers.
+	pi.on("message_end", (event) => {
+		const message = event.message as AssistantMessage;
+		if (message.role !== "assistant" || !message.usage) return;
+		lastTurn = message.usage;
+		cost += message.usage.cost.total;
+		sent += message.usage.input + message.usage.cacheWrite;
+		received += message.usage.output;
+		repaint?.();
+	});
+
 	pi.on("session_start", async (_event, ctx) => {
 		// A resumed session already has turns behind it, and no agent_end will fire for them.
 		refresh(ctx);
+		const contextUsage = everyMs(1000, () => ctx.getContextUsage());
 		ctx.ui.setFooter((tui, theme, footerData) => {
 			repaint = () => tui.requestRender();
 			return {
@@ -99,7 +142,7 @@ export default function (pi: ExtensionAPI) {
 					const promptTokens =
 						(lastTurn?.input ?? 0) + (lastTurn?.cacheRead ?? 0) + (lastTurn?.cacheWrite ?? 0);
 					const cacheHitRate = promptTokens > 0 ? ((lastTurn?.cacheRead ?? 0) / promptTokens) * 100 : 0;
-					const context = ctx.getContextUsage();
+					const context = contextUsage();
 
 					// "MiniMax: MiniMax M3 (CC)" → "MiniMax M3". pi names a model "<provider>: <model>"
 					// and the provider is already implied by the model, so both the prefix and the
@@ -121,28 +164,26 @@ export default function (pi: ExtensionAPI) {
 							`R${compact(lastTurn?.cacheRead ?? 0)} W${compact(lastTurn?.cacheWrite ?? 0)} CH${cacheHitRate.toFixed(1)}%`,
 						);
 					}
-					// `input` is the fresh half of the prompt. cacheRead and cacheWrite are already
-					// their own group, so counting them here too would make the arrow repeat what the
-					// R and the W just said.
-					const moved = (lastTurn?.input ?? 0) + (lastTurn?.output ?? 0);
-					if (moved > 0) parts.push(`↑ ${compact(lastTurn?.input ?? 0)} ↓ ${compact(lastTurn?.output ?? 0)}`);
+					if (sent + received > 0) parts.push(`↑ ${compact(sent)} ↓ ${compact(received)}`);
 					const statuses = footerData.getExtensionStatuses();
 					const level = ponytailLevel(statuses);
-					if (level) parts.push(`ponytail:${level}`);
+					if (level) parts.push(`pt:${level}`);
 					const loop = statuses.get("loop")?.replace(ANSI_CODES, "");
 					if (loop) parts.push(loop);
 
 					// getGitBranch() returns null outside a repo and "detached" on a detached HEAD, so
 					// the branch shows itself when there is one and costs nothing when there is not.
-					const right = [`🗀  ${ctx.sessionManager.getCwd()}`];
+					const cwd = ctx.sessionManager.getCwd();
+					const right = [`${cwd === HOME || cwd.startsWith(`${HOME}/`) ? `~${cwd.slice(HOME.length)}` : cwd}`];
 					const branch = footerData.getGitBranch();
-					if (branch) right.push(`⎇ ${branch}`);
+					if (branch) right.push(branch);
 
 					// One line. The rule that used to live here is drawn by the editor now - see the
 					// repatch entry "the autocomplete list has a closing edge" - which puts it in the
 					// border colour and only when there is a list to close. Drawing it here as well
 					// showed up as two rules with a blank row between them on every screen with no list.
-					return compose(parts, right, width, (text) => theme.fg("muted", text));
+					// The trailing blank row keeps the status line off the bottom edge of the terminal.
+					return [...compose(parts, right, width, (text) => theme.fg("muted", text)), ""];
 				},
 			};
 		});

package/node_modules/pi-umbra-theme/extensions/umbra-gutter.ts

@@ -3,23 +3,46 @@
 //
 // It is drawn as a Markdown quote rather than a literal "│ " prefix, because the transformer hook
 // is display-only and operates on Markdown source: a literal prefix would turn "```ts" into
-// "│ ```ts", which is no longer a fence, and every code block in the answer would render as
-// paragraph text. A quote keeps fences, lists and tables intact, and pi's own renderer draws the
-// bar from the active theme.
+// "│ ```ts", which is no longer a fence. pi's renderer draws the bar from the active theme.
+//
+// Code blocks stay outside the quote. pi draws a fence inside a quote as quoted prose, italic and
+// unhighlighted, so the quote closes before a fence and opens again after it.
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { readUmbraSettings } from "../lib/umbra-settings.ts";
 
 const QUOTE = "> ";
 
+const FENCE = /^\s{0,3}(`{3,}|~{3,})/;
+
 /**
  * A blank line inside a quote ends it, so blank lines carry a bare marker. Without that, one
  * empty line between two paragraphs would split the answer into two separate quote blocks.
+ * Fenced code, fence lines included, is left unquoted; a fence closes on a run of the same
+ * character at least as long as the one that opened it.
  */
-export const asQuote = (markdown: string): string =>
-    markdown
+export const asQuote = (markdown: string): string => {
+    let open: string | undefined;
+    const lines = markdown
         .split("\n")
-        .map((line) => (line.trim() === "" ? QUOTE.trimEnd() : QUOTE + line))
+        .map((line) => {
+            const fence = FENCE.exec(line)?.[1];
+            if (open) {
+                if (fence && fence[0] === open[0] && fence.length >= open.length) open = undefined;
+                return line;
+            }
+            if (fence) {
+                open = fence;
+                return line;
+            }
+            return line.trim() === "" ? QUOTE.trimEnd() : QUOTE + line;
+        });
+    // A blank marker only joins two quoted lines. Beside a code block it would draw a bar with
+    // nothing next to it.
+    const quoted = (line: string | undefined) => line !== undefined && line.startsWith(">");
+    return lines
+        .map((line, i) => (line === QUOTE.trimEnd() && !(quoted(lines[i - 1]) && quoted(lines[i + 1])) ? "" : line))
         .join("\n");
+};
 
 export default function umbraGutter(pi: ExtensionAPI) {
     // Read once. The transformer runs on every streaming update and every terminal resize, so a

package/node_modules/pi-umbra-theme/extensions/umbra-toolbox/LICENSE-pi-cc-extensions

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 minuque
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/pi-umbra-theme/extensions/umbra-toolbox/config/config.ts

@@ -0,0 +1,342 @@
+import type { CompactThinkingConfig } from "../feature/compact-thinking.ts";
+import {
+	DEFAULT_FOOTER_CHIP_LAYOUT,
+	formatFooterChipSummary,
+	normalizeFooterChipLayout,
+} from "../feature/shell/footer-layout.ts";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type CompactStyleMode = "on" | "compact" | "off";
+
+export type DiffViewMode = "auto" | "split" | "unified";
+export type DiffIndicatorMode = "bars" | "classic" | "none";
+
+export interface ToolDisplayConfig {
+	diffViewMode: DiffViewMode;
+	diffIndicatorMode: DiffIndicatorMode;
+	diffSplitMinWidth: number;
+	editDiffCollapsedLines: number;
+	/** Write-only collapsed body lines. 0 = `↳ created • click to show more`. */
+	writeDiffCollapsedLines: number;
+	diffWordWrap: boolean;
+	expandedPreviewMaxLines: number;
+}
+
+export const DEFAULT_TOOL_DISPLAY_CONFIG: ToolDisplayConfig = {
+	diffViewMode: "auto",
+	diffIndicatorMode: "bars",
+	diffSplitMinWidth: 120,
+	/** Collapsed edit/diff body: ~half a typical terminal after chrome. */
+	editDiffCollapsedLines: 24,
+	/**
+	 * Write create/overwrite collapsed body.
+	 * 0 = `↳ created • click to show more` (stats stay on the title).
+	 */
+	writeDiffCollapsedLines: 0,
+	diffWordWrap: true,
+	/**
+	 * Expanded TaskList body cap. Tool Input/Output and diffs use their own settings;
+	 * an expanded diff always renders every line.
+	 */
+	expandedPreviewMaxLines: 40,
+};
+
+export type Config = {
+	mode: CompactStyleMode;
+	excludeRenderers: string[];
+	diffViewMode: DiffViewMode;
+	diffIndicatorMode: DiffIndicatorMode;
+	diffSplitMinWidth: number;
+	editDiffCollapsedLines: number;
+	writeDiffCollapsedLines: number;
+	diffWordWrap: boolean;
+	expandedPreviewMaxLines: number;
+	expandedInputMaxLines: number;
+	expandedOutputMaxLines: number;
+	inputClip: number;
+	useSummaryTitlesAsThinkingTitle: boolean;
+	previewLines: number;
+	animationIntervalMs: number;
+	dimThinkingText: boolean;
+	showStartupHeader: boolean;
+	scrollStepLines: number;
+	enableSessionReference: boolean;
+	enableSubagentAutocomplete: boolean;
+	enableContextCommand: boolean;
+	enableAgentSummary: boolean;
+	enableWorkingMessage: boolean;
+	enableAliases: boolean;
+	enableCustomFooter: boolean;
+	footerNerdIcons: boolean;
+	footerHiddenKeys: string[];
+	footerLine1Keys: string[];
+	footerLine2Keys: string[];
+	footerLine3Keys: string[];
+};
+
+const AGENT_DIR = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+export const CONFIG_PATH = join(AGENT_DIR, "umbra-toolbox.json");
+const LEGACY_CONFIG_PATH = join(AGENT_DIR, "claude-code-style.json");
+
+export const DIFF_VIEW_MODES: DiffViewMode[] = ["auto", "split", "unified"];
+export const DIFF_INDICATOR_MODES: DiffIndicatorMode[] = ["bars", "classic", "none"];
+export const DIFF_SPLIT_MIN_WIDTH_VALUES = ["80", "100", "120", "140", "160", "180"];
+export const DIFF_COLLAPSED_LINES_VALUES = ["12", "24", "36", "48", "80", "120"];
+/** Write collapsed presets. 0 = stats only (`+N -0` + expand hint). */
+export const WRITE_DIFF_COLLAPSED_LINES_VALUES = ["0", "4", "8", "12", "24", "36"];
+/** Presets for expanded body height — keep low options first so cycling stays TUI-friendly. */
+export const EXPANDED_PREVIEW_MAX_LINES_VALUES = ["40", "60", "80", "120", "200", "500", "2000"];
+/** 展开工具卡 Input 可见行数预设。 */
+export const EXPANDED_INPUT_MAX_LINES_VALUES = ["5", "10", "20", "40", "80"];
+/** 展开工具卡 Output 可见行数预设。 */
+export const EXPANDED_OUTPUT_MAX_LINES_VALUES = ["10", "20", "40", "80", "120"];
+/** 工具摘要里 path/command 等输入的折叠字符数。 */
+export const INPUT_CLIP_VALUES = ["40", "60", "80", "100", "120", "160"];
+export const THINKING_PREVIEW_LINES_VALUES = ["0", "1", "3", "5", "10"];
+export const THINKING_ANIMATION_INTERVAL_VALUES = ["40", "60", "90", "120", "180"];
+/** fullscreen 滚轮步进行数预设。 */
+export const SCROLL_STEP_LINES_VALUES = ["1", "2", "3", "5", "10"];
+/** Tools commonly toggled in excludeRenderers via the settings panel. */
+export const EXCLUDE_RENDERER_CANDIDATES = [
+	"bash",
+	"powershell",
+	"read",
+	"edit",
+	"write",
+	"grep",
+	"find",
+	"ls",
+	"webfetch",
+	"wait",
+];
+
+export const DEFAULT_CONFIG: Config = {
+	mode: "on",
+	excludeRenderers: [],
+	diffViewMode: DEFAULT_TOOL_DISPLAY_CONFIG.diffViewMode,
+	diffIndicatorMode: DEFAULT_TOOL_DISPLAY_CONFIG.diffIndicatorMode,
+	diffSplitMinWidth: DEFAULT_TOOL_DISPLAY_CONFIG.diffSplitMinWidth,
+	editDiffCollapsedLines: DEFAULT_TOOL_DISPLAY_CONFIG.editDiffCollapsedLines,
+	writeDiffCollapsedLines: DEFAULT_TOOL_DISPLAY_CONFIG.writeDiffCollapsedLines,
+	diffWordWrap: DEFAULT_TOOL_DISPLAY_CONFIG.diffWordWrap,
+	expandedPreviewMaxLines: DEFAULT_TOOL_DISPLAY_CONFIG.expandedPreviewMaxLines,
+	expandedInputMaxLines: 5,
+	expandedOutputMaxLines: 10,
+	inputClip: 100,
+	useSummaryTitlesAsThinkingTitle: true,
+	previewLines: 3,
+	animationIntervalMs: 90,
+	dimThinkingText: false,
+	showStartupHeader: true,
+	scrollStepLines: 3,
+	enableSessionReference: true,
+	enableSubagentAutocomplete: true,
+	enableContextCommand: true,
+	enableAgentSummary: true,
+	enableWorkingMessage: true,
+	enableAliases: true,
+	enableCustomFooter: true,
+	footerNerdIcons: true,
+	...DEFAULT_FOOTER_CHIP_LAYOUT,
+};
+
+function pickEnum<T extends string>(value: unknown, allowed: readonly T[], fallback: T): T {
+	return typeof value === "string" && (allowed as readonly string[]).includes(value)
+		? (value as T)
+		: fallback;
+}
+
+export function pickPositiveInt(value: unknown, fallback: number, min = 1, max = 100_000): number {
+	const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+	if (!Number.isFinite(n)) return fallback;
+	return Math.min(max, Math.max(min, Math.floor(n)));
+}
+
+export function pickPositiveNumber(value: unknown, fallback: number, min = 1): number {
+	const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+	return Number.isFinite(n) ? Math.max(min, n) : fallback;
+}
+
+export function normalizeConfig(input: unknown): Config {
+	const source = (input && typeof input === "object" ? input : {}) as Record<string, unknown>;
+	const mode = pickEnum(source.mode, ["on", "compact", "off"], DEFAULT_CONFIG.mode);
+	const excludeRenderers = Array.isArray(source.excludeRenderers)
+		? [
+				...new Set(
+					source.excludeRenderers.filter(
+						(name): name is string => typeof name === "string" && name.length > 0,
+					),
+				),
+			]
+		: [];
+	return {
+		mode,
+		excludeRenderers,
+		diffViewMode: pickEnum(source.diffViewMode, DIFF_VIEW_MODES, DEFAULT_CONFIG.diffViewMode),
+		diffIndicatorMode: pickEnum(
+			source.diffIndicatorMode,
+			DIFF_INDICATOR_MODES,
+			DEFAULT_CONFIG.diffIndicatorMode,
+		),
+		diffSplitMinWidth: pickPositiveInt(
+			source.diffSplitMinWidth,
+			DEFAULT_CONFIG.diffSplitMinWidth,
+			40,
+			300,
+		),
+		editDiffCollapsedLines: pickPositiveInt(
+			source.editDiffCollapsedLines,
+			DEFAULT_CONFIG.editDiffCollapsedLines,
+			1,
+			500,
+		),
+		writeDiffCollapsedLines: pickPositiveInt(
+			source.writeDiffCollapsedLines,
+			DEFAULT_CONFIG.writeDiffCollapsedLines,
+			0,
+			500,
+		),
+		diffWordWrap: source.diffWordWrap !== false,
+		expandedPreviewMaxLines: pickPositiveInt(
+			source.expandedPreviewMaxLines,
+			DEFAULT_CONFIG.expandedPreviewMaxLines,
+			10,
+			50_000,
+		),
+		expandedInputMaxLines: pickPositiveInt(
+			source.expandedInputMaxLines,
+			DEFAULT_CONFIG.expandedInputMaxLines,
+			1,
+			5_000,
+		),
+		expandedOutputMaxLines: pickPositiveInt(
+			source.expandedOutputMaxLines,
+			DEFAULT_CONFIG.expandedOutputMaxLines,
+			1,
+			5_000,
+		),
+		inputClip: pickPositiveInt(source.inputClip, DEFAULT_CONFIG.inputClip, 8, 500),
+		useSummaryTitlesAsThinkingTitle: source.useSummaryTitlesAsThinkingTitle !== false,
+		previewLines: pickPositiveInt(
+			source.previewLines,
+			DEFAULT_CONFIG.previewLines,
+			0,
+			Number.MAX_SAFE_INTEGER,
+		),
+		animationIntervalMs: pickPositiveNumber(
+			source.animationIntervalMs,
+			DEFAULT_CONFIG.animationIntervalMs,
+		),
+		dimThinkingText: source.dimThinkingText === true,
+		showStartupHeader: source.showStartupHeader !== false,
+		scrollStepLines: pickPositiveInt(source.scrollStepLines, DEFAULT_CONFIG.scrollStepLines, 1, 50),
+		enableSessionReference: source.enableSessionReference !== false,
+		enableSubagentAutocomplete: source.enableSubagentAutocomplete !== false,
+		enableContextCommand: source.enableContextCommand !== false,
+		enableAgentSummary: source.enableAgentSummary !== false,
+		enableWorkingMessage: source.enableWorkingMessage !== false,
+		enableAliases: source.enableAliases !== false,
+		enableCustomFooter: source.enableCustomFooter !== false,
+		footerNerdIcons: source.footerNerdIcons !== false,
+		...normalizeFooterChipLayout(source),
+	};
+}
+
+export function getCompactThinkingConfig(source: Config = config): CompactThinkingConfig {
+	return {
+		useSummaryTitlesAsThinkingTitle: source.useSummaryTitlesAsThinkingTitle,
+		previewLines: source.previewLines,
+		animationIntervalMs: source.animationIntervalMs,
+	};
+}
+
+export function getToolDisplayConfig(source: Config = config): ToolDisplayConfig {
+	return {
+		diffViewMode: source.diffViewMode,
+		diffIndicatorMode: source.diffIndicatorMode,
+		diffSplitMinWidth: source.diffSplitMinWidth,
+		editDiffCollapsedLines: source.editDiffCollapsedLines,
+		writeDiffCollapsedLines: source.writeDiffCollapsedLines,
+		diffWordWrap: source.diffWordWrap,
+		expandedPreviewMaxLines: source.expandedPreviewMaxLines,
+	};
+}
+
+export function formatExcludeRenderers(names: readonly string[]): string {
+	return names.length === 0 ? "none" : names.join(", ");
+}
+
+export function formatConfigStatus(source: Config = config): string {
+	return [
+		`mode=${source.mode}`,
+		`exclude=[${source.excludeRenderers.join(", ") || "none"}]`,
+		`diffView=${source.diffViewMode}`,
+		`diffIndicator=${source.diffIndicatorMode}`,
+		`diffSplitMin=${source.diffSplitMinWidth}`,
+		`editCollapsed=${source.editDiffCollapsedLines}`,
+		`writeCollapsed=${source.writeDiffCollapsedLines}`,
+		`diffWordWrap=${source.diffWordWrap ? "on" : "off"}`,
+		`expandedMax=${source.expandedPreviewMaxLines}`,
+		`expandedInput=${source.expandedInputMaxLines}`,
+		`expandedOutput=${source.expandedOutputMaxLines}`,
+		`inputClip=${source.inputClip}`,
+		`thinkingTitle=${source.useSummaryTitlesAsThinkingTitle ? "summary" : "default"}`,
+		`thinkingPreview=${source.previewLines}`,
+		`thinkingAnimation=${source.animationIntervalMs}ms`,
+		`thinkingDim=${source.dimThinkingText ? "on" : "off"}`,
+		`startupHeader=${source.showStartupHeader ? "on" : "off"}`,
+		`scrollStep=${source.scrollStepLines}`,
+		`sessionRef=${source.enableSessionReference ? "on" : "off"}`,
+		`subagentAuto=${source.enableSubagentAutocomplete ? "on" : "off"}`,
+		`context=${source.enableContextCommand ? "on" : "off"}`,
+		`agentSummary=${source.enableAgentSummary ? "on" : "off"}`,
+		`workingMsg=${source.enableWorkingMessage ? "on" : "off"}`,
+		`aliases=${source.enableAliases ? "on" : "off"}`,
+		`footer=${source.enableCustomFooter ? "on" : "off"}`,
+		`footerIcons=${source.footerNerdIcons ? "nerd" : "plain"}`,
+		formatFooterChipSummary(source),
+	].join(" · ");
+}
+
+/** 进程内唯一的活动配置对象。读取直接用 `config.xxx`；写入必须走 `updateConfig`。 */
+export const config: Config = loadConfig();
+
+function loadConfig(): Config {
+	try {
+		const fromLegacy = !existsSync(CONFIG_PATH) && existsSync(LEGACY_CONFIG_PATH);
+		const rawPath = existsSync(CONFIG_PATH) ? CONFIG_PATH : fromLegacy ? LEGACY_CONFIG_PATH : null;
+		const source = rawPath
+			? (JSON.parse(readFileSync(rawPath, "utf8")) as Record<string, unknown>)
+			: {};
+		const next = normalizeConfig(source);
+		if (fromLegacy) {
+			try {
+				writeFileSync(CONFIG_PATH, JSON.stringify(next, null, 2));
+				rmSync(LEGACY_CONFIG_PATH, { force: true });
+			} catch {
+				// 新路径写失败时仍使用已读到的旧配置，旧文件保留。
+			}
+		}
+		return next;
+	} catch {
+		// Ignore bad config and fall back to defaults.
+	}
+	return { ...DEFAULT_CONFIG };
+}
+
+export function saveConfig() {
+	writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+/** 运行时配置写入的唯一入口：合并 + 规范化 + 持久化。 */
+export function updateConfig(partial: Partial<Config>): void {
+	Object.assign(config, normalizeConfig({ ...config, ...partial }));
+	saveConfig();
+}
+
+/** 整体替换配置（default export 的 configOverride 注入路径；就地覆盖，不持久化）。 */
+export function setConfig(next: Config): void {
+	Object.assign(config, next);
+}