gentle-pi 2.3.0 → 2.5.0

package/tests/shell-bar.test.ts

@@ -0,0 +1,176 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import {
+	formatCost,
+	formatTokens,
+	gaugeTone,
+	renderGauge,
+	renderShellBar,
+	shellEnabled,
+	type ShellBarModel,
+	type ShellBarTheme,
+} from "../lib/shell-bar.ts";
+
+// The Gentle Shell bar replaces pi's three-line footer with one line of
+// segments. Rendering is pure so it can be verified without a TUI.
+
+const taggedTheme: ShellBarTheme = {
+	fg(color: string, value: string) {
+		return `<${color}>${value}</${color}>`;
+	},
+	bold(value: string) {
+		return value;
+	},
+};
+
+const plainTheme: ShellBarTheme = {
+	fg(_color: string, value: string) {
+		return value;
+	},
+	bold(value: string) {
+		return value;
+	},
+};
+
+function model(overrides: Partial<ShellBarModel> = {}): ShellBarModel {
+	return {
+		cwd: "~/work/gentle-pi",
+		branch: "main",
+		dirty: undefined,
+		sessionName: undefined,
+		modelId: "gpt-5.5",
+		effort: "medium",
+		contextPercent: 45,
+		contextWindow: 272_000,
+		costTotal: 9.49,
+		subscription: true,
+		usage: undefined,
+		statuses: [],
+		...overrides,
+	};
+}
+
+test("renderGauge fills cells proportionally to the percentage", () => {
+	assert.equal(renderGauge(45, 8), "▰▰▰▰▱▱▱▱");
+	assert.equal(renderGauge(0, 8), "▱▱▱▱▱▱▱▱");
+	assert.equal(renderGauge(100, 8), "▰▰▰▰▰▰▰▰");
+	assert.equal(renderGauge(null, 8), "▱▱▱▱▱▱▱▱");
+});
+
+test("gaugeTone turns to warning at 80% and error at 95%", () => {
+	assert.equal(gaugeTone(45), "accent");
+	assert.equal(gaugeTone(79.9), "accent");
+	assert.equal(gaugeTone(80), "warning");
+	assert.equal(gaugeTone(95), "error");
+	assert.equal(gaugeTone(null), "dim");
+});
+
+test("formatTokens and formatCost keep the bar compact", () => {
+	assert.equal(formatTokens(950), "950");
+	assert.equal(formatTokens(4_200), "4.2k");
+	assert.equal(formatTokens(272_000), "272k");
+	assert.equal(formatTokens(13_000_000), "13M");
+	assert.equal(formatCost(9.49, true), "$9.49 sub");
+	assert.equal(formatCost(0.004, false), "$0.004");
+});
+
+test("renderShellBar renders one line with the segments in order", () => {
+	const [line, ...rest] = renderShellBar(model(), plainTheme, 160);
+	assert.equal(rest.length, 0);
+	assert.equal(
+		line,
+		"✿ gentle-pi ⟡ ~/work/gentle-pi main ⟡ gpt-5.5 · medium ⟡ ctx ▰▰▰▰▱▱▱▱ 45% ⟡ $9.49 sub",
+	);
+});
+
+test("renderShellBar colors the brand, model, effort, and gauge by role", () => {
+	const [line] = renderShellBar(model(), taggedTheme, 400);
+	assert.match(line, /<accent>✿ gentle-pi<\/accent>/);
+	assert.match(line, /<text>gpt-5\.5<\/text>/);
+	assert.match(line, /<syntaxFunction>medium<\/syntaxFunction>/);
+	assert.match(line, /<accent>▰▰▰▰<\/accent><border>▱▱▱▱<\/border>/);
+	assert.match(line, /<dim>⟡<\/dim>/);
+});
+
+test("renderShellBar shows the branch as dirty-neutral and omits it outside git", () => {
+	const [line] = renderShellBar(model({ branch: null }), plainTheme, 160);
+	assert.match(line, /⟡ ~\/work\/gentle-pi ⟡/);
+});
+
+test("renderShellBar shows the session dirty count next to the branch", () => {
+	const [line] = renderShellBar(model({ dirty: 3 }), taggedTheme, 400);
+	assert.match(line, /<text>main<\/text> <warning>±3<\/warning>/);
+	const [clean] = renderShellBar(model({ dirty: 0 }), plainTheme, 160);
+	assert.doesNotMatch(clean, /±/);
+});
+
+test("renderShellBar adds the subscription windows after the cost when usage is known", () => {
+	const usage = {
+		provider: "openai-codex",
+		plan: "pro",
+		fetchedAt: 0,
+		limits: [{ name: "codex", limitReached: false, windows: [
+			{ label: "5h", usedPercent: 62, windowSeconds: 18_000, resetAt: null },
+			{ label: "week", usedPercent: 31, windowSeconds: 604_800, resetAt: null },
+		] }],
+	};
+	const [line] = renderShellBar(model({ usage }), plainTheme, 200);
+	assert.match(line, /\$9\.49 sub ⟡ codex 5h ▰▰▰▰▰▱▱▱ 62% · week 31%$/);
+});
+
+test("renderShellBar shows an unknown context as a question mark after compaction", () => {
+	const [line] = renderShellBar(model({ contextPercent: null }), plainTheme, 160);
+	assert.match(line, /ctx ▱▱▱▱▱▱▱▱ \?%/);
+});
+
+test("renderShellBar right-aligns the session name when it fits", () => {
+	const [line] = renderShellBar(model({ sessionName: "Release notes" }), plainTheme, 120);
+	assert.equal(visibleWidth(line), 120);
+	assert.match(line, /Release notes$/);
+});
+
+test("renderShellBar appends extension statuses as trailing segments", () => {
+	const [line] = renderShellBar(model({ statuses: ["🔌 MCP: 3 servers\tenabled"] }), plainTheme, 160);
+	assert.match(line, /⟡ 🔌 MCP: 3 servers enabled$/);
+});
+
+test("renderShellBar repaints extension statuses in the bar role, discarding colors the extension embedded", () => {
+	const tagged = { fg: (color: string, text: string) => `<${color}>${text}</${color}>`, bold: (text: string) => text };
+	const [line] = renderShellBar(model({ statuses: ["\x1b[38;2;255;0;0mMCP: 3/3 servers\x1b[0m"] }), tagged, 400);
+	assert.match(line, /<muted>MCP: 3\/3 servers<\/muted>$/);
+	assert.doesNotMatch(line, /\x1b\[/);
+});
+
+test("renderShellBar compacts the path and branch before it sacrifices an extension status", () => {
+	const long = model({ branch: "fix/shell-bar-status-ansi", dirty: 2, statuses: ["MCP: 3/3 servers"] });
+	const [full] = renderShellBar(long, plainTheme, 160);
+	assert.match(full, /~\/work\/gentle-pi fix\/shell-bar-status-ansi ±2 .* MCP: 3\/3 servers$/);
+	const [compact] = renderShellBar(long, plainTheme, 118);
+	assert.ok(visibleWidth(compact) <= 118, `line overflowed: ${visibleWidth(compact)}`);
+	assert.match(compact, /⟡ gentle-pi fix\/shell-bar-… ±2 ⟡/);
+	assert.match(compact, /MCP: 3\/3 servers$/);
+});
+
+test("renderShellBar drops the session name, then trailing segments, before truncating", () => {
+	const wide = model({ sessionName: "Release notes", statuses: ["MCP: 3 servers enabled"] });
+	const [atNinety] = renderShellBar(wide, plainTheme, 90);
+	assert.ok(visibleWidth(atNinety) <= 90, `line overflowed: ${visibleWidth(atNinety)}`);
+	assert.doesNotMatch(atNinety, /Release notes/);
+	assert.match(atNinety, /gpt-5\.5/);
+
+	const [atFifty] = renderShellBar(wide, plainTheme, 50);
+	assert.ok(visibleWidth(atFifty) <= 50, `line overflowed: ${visibleWidth(atFifty)}`);
+	assert.match(atFifty, /^✿ gentle-pi/);
+});
+
+test("shellEnabled stays off inside a Gentle Agents child", () => {
+	assert.equal(shellEnabled({ GENTLE_PI_AGENTS_CHILD: "1" }), false);
+});
+
+test("shellEnabled honors GENTLE_PI_SHELL=0", () => {
+	assert.equal(shellEnabled({}), true);
+	assert.equal(shellEnabled({ GENTLE_PI_SHELL: "1" }), true);
+	assert.equal(shellEnabled({ GENTLE_PI_SHELL: "0" }), false);
+	assert.equal(shellEnabled({ GENTLE_PI_SHELL: "false" }), false);
+});

package/tests/shell-card.test.ts

@@ -0,0 +1,118 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { CARD_TONE, renderCard, type Card } from "../lib/shell-card.ts";
+import { stripAnsi } from "../lib/terminal-theme.ts";
+
+// Cards are how Gentle notices look: the same rounded frame as the prompt,
+// with the title in the notice tone. They collapse to one body line when pi
+// asks for it.
+
+const plainTheme = {
+	fg(_color: string, text: string) {
+		return text;
+	},
+};
+
+const taggedTheme = {
+	fg(color: string, text: string) {
+		return `<${color}>${text}</${color}>`;
+	},
+};
+
+const ansiTheme = {
+	fg(_color: string, text: string) {
+		return `\x1b[35m${text}\x1b[0m`;
+	},
+};
+
+function card(overrides: Partial<Card> = {}): Card {
+	return {
+		title: "Gentle AI",
+		subtitle: "review preflight",
+		body: ["Receipt-driven development is enabled, and this worktree holds an unreviewed candidate.", "", "Call the gentle_review tool with inspect and follow the transition it returns."],
+		tone: CARD_TONE.INFO,
+		...overrides,
+	};
+}
+
+test("renderCard draws the rounded frame with the title in the top rule and wraps the body inside", () => {
+	const lines = renderCard(card(), plainTheme, 48, { expanded: true }).map(stripAnsi);
+	assert.match(lines[0], /^╭─ ✿ Gentle AI · review preflight ─+╮$/);
+	assert.match(lines[1], /^│ Receipt-driven development is enabled, and +│$/);
+	for (const line of lines) assert.equal(visibleWidth(line), 48, `"${line}" is not 48 wide`);
+	assert.ok(lines.some((line) => /^│ +│$/.test(line)), "blank body lines keep the frame");
+	assert.ok(lines.some((line) => line.includes("gentle_review")), "every paragraph is rendered when expanded");
+	assert.match(lines[lines.length - 1], /^╰─+╯$/);
+});
+
+test("renderCard collapses to the frame and the first body line with an expand hint", () => {
+	const lines = renderCard(card(), plainTheme, 60, { expanded: false }).map(stripAnsi);
+	assert.equal(lines.length, 3);
+	assert.match(lines[1], /^│ Receipt-driven development is enabled.*… +│$/);
+	assert.equal(visibleWidth(lines[1]), 60);
+});
+
+test("renderCard keeps the rail and its corners in the tone and the rest of the frame in the border color", () => {
+	const info = renderCard(card(), taggedTheme, 80, { expanded: true });
+	assert.match(info[0], /^<customMessageLabel>╭<\/customMessageLabel><border>─ <\/border><customMessageLabel>✿ Gentle AI<\/customMessageLabel> <muted>·<\/muted> <muted>review preflight<\/muted><border> ─+<\/border><border>╮<\/border>$/);
+	assert.match(info[1], /^<customMessageLabel>│<\/customMessageLabel> <text>.*<border>│<\/border>$/);
+	assert.match(info[info.length - 1], /^<customMessageLabel>╰<\/customMessageLabel><border>─+╯<\/border>$/);
+
+	const warning = renderCard(card({ tone: CARD_TONE.WARNING, subtitle: undefined }), taggedTheme, 80, { expanded: true });
+	assert.match(warning[0], /^<warning>╭<\/warning>/);
+	assert.match(warning[0], /<warning>✿ Gentle AI<\/warning>/);
+	assert.match(warning[1], /^<warning>│<\/warning> /);
+	assert.match(warning[warning.length - 1], /^<warning>╰<\/warning>/);
+
+	const error = renderCard(card({ tone: CARD_TONE.ERROR }), taggedTheme, 80, { expanded: true });
+	assert.match(error[0], /<error>✿ Gentle AI<\/error>/);
+	assert.equal(CARD_TONE.SUCCESS, "success");
+});
+
+test("renderCard places a hint at the right end of the top rule and can paint every line", () => {
+	const lines = renderCard(card(), plainTheme, 60, { expanded: false, hint: "ctrl+o expand" });
+	assert.match(stripAnsi(lines[0]), /^╭─ ✿ Gentle AI · review preflight ─+ ctrl\+o expand ╮$/);
+	assert.equal(visibleWidth(lines[0]), 60);
+
+	const painted = renderCard(card(), plainTheme, 60, { expanded: false, paint: (line) => `[bg]${line}[/bg]` });
+	assert.ok(painted.every((line) => line.startsWith("[bg]") && line.endsWith("[/bg]")));
+});
+
+test("renderCard accepts a custom glyph and an empty body", () => {
+	const lines = renderCard(card({ glyph: "✎", body: [] }), plainTheme, 40, { expanded: true }).map(stripAnsi);
+	assert.equal(lines.length, 2);
+	assert.match(lines[0], /^╭─ ✎ Gentle AI · review preflight ─+╮$/);
+	assert.match(lines[1], /^╰─+╯$/);
+});
+
+test("renderCard keeps the top rule at width with a two-cell glyph", () => {
+	const lines = renderCard(card({ glyph: "\u{1F339}\uFE0E" }), plainTheme, 60, { expanded: false, hint: "ctrl+o expand" });
+	for (const line of lines) assert.equal(visibleWidth(line), 60, `"${stripAnsi(line)}" is not 60 wide`);
+});
+
+test("renderCard drops the hint before truncating title content", () => {
+	const lines = renderCard(card(), plainTheme, 40, { expanded: false, hint: "ctrl+o expand" }).map(stripAnsi);
+	assert.equal(lines[0], "╭─ ✿ Gentle AI · review preflight ─────╮");
+	assert.ok(!lines[0].includes("ctrl+o"));
+	assert.equal(visibleWidth(lines[0]), 40);
+});
+
+test("renderCard truncates ANSI-styled title content at display width", () => {
+	const lines = renderCard(
+		card({ glyph: "\u{1F339}\uFE0E", title: "Gentle AI review", subtitle: "completed · review acknowledge approved" }),
+		ansiTheme,
+		30,
+		{ expanded: false, hint: "ctrl+o to expand" },
+	);
+	assert.match(stripAnsi(lines[0]), /^╭─ 🌹︎ Gentle AI review.*╮$/);
+	assert.ok(!stripAnsi(lines[0]).includes("ctrl+o"));
+	for (const line of lines) assert.equal(visibleWidth(line), 30, `"${stripAnsi(line)}" is not 30 wide`);
+});
+
+test("renderCard never exceeds extremely narrow supplied widths", () => {
+	for (const width of [0, 1, 2, 3, 4, 5, 8, 16]) {
+		const lines = renderCard(card({ glyph: "\u{1F339}\uFE0E" }), ansiTheme, width, { expanded: true, hint: "ctrl+o to expand" });
+		for (const line of lines) assert.equal(visibleWidth(line), width, `"${stripAnsi(line)}" is not ${width} wide`);
+	}
+});

package/tests/shell-changes-view.test.ts

@@ -0,0 +1,146 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { CHANGE_STATUS, changesModel, type ChangedFile } from "../lib/shell-changes.ts";
+import { ChangesView, colorDiff, type ChangesViewDeps } from "../lib/shell-changes-view.ts";
+import { stripAnsi } from "../lib/terminal-theme.ts";
+
+// The changes overlay: files on the left, the selected file's diff on the
+// right, keys at the bottom. Rendering is pure; git access is injected.
+
+const plainTheme = {
+	fg(_color: string, text: string) {
+		return text;
+	},
+};
+
+const taggedTheme = {
+	fg(color: string, text: string) {
+		return `<${color}>${text}</${color}>`;
+	},
+};
+
+function file(path: string, added: number, deleted: number, status: ChangedFile["status"] = CHANGE_STATUS.MODIFIED): ChangedFile {
+	return { path, added, deleted, status };
+}
+
+const DIFF_A = ["diff --git a/lib/a.ts b/lib/a.ts", "index 1..2 100644", "--- a/lib/a.ts", "+++ b/lib/a.ts", "@@ -1,2 +1,3 @@", " const a = 1;", "-const b = 2;", "+const b = 3;", "+const c = 4;"].join("\n");
+
+function view(overrides: Partial<ChangesViewDeps> = {}, files = [file("lib/a.ts", 2, 1), file("lib/b.ts", 10, 0, CHANGE_STATUS.ADDED)]) {
+	const calls: string[] = [];
+	const events: string[] = [];
+	const deps: ChangesViewDeps = {
+		theme: plainTheme,
+		rows: 12,
+		async loadDiff(target) {
+			calls.push(target.path);
+			return target.path === "lib/a.ts" ? DIFF_A : "";
+		},
+		onOpen(target) {
+			events.push(`open:${target.path}`);
+		},
+		onClose() {
+			events.push("close");
+		},
+		requestRender() {
+			events.push("render");
+		},
+		...overrides,
+	};
+	return { view: new ChangesView(changesModel(files), deps), calls, events };
+}
+
+async function settle(): Promise<void> {
+	await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+test("colorDiff drops git headers and colors hunks, additions, and removals by role", () => {
+	const lines = colorDiff(DIFF_A, taggedTheme);
+	assert.deepEqual(lines, [
+		"<customMessageLabel>@@ -1,2 +1,3 @@</customMessageLabel>",
+		"<toolDiffContext> const a = 1;</toolDiffContext>",
+		"<toolDiffRemoved>-const b = 2;</toolDiffRemoved>",
+		"<toolDiffAdded>+const b = 3;</toolDiffAdded>",
+		"<toolDiffAdded>+const c = 4;</toolDiffAdded>",
+	]);
+});
+
+test("ChangesView renders a framed two-pane layout at the requested size", async () => {
+	const { view: component } = view();
+	await settle();
+	const lines = component.render(80);
+	assert.equal(lines.length, 12);
+	for (const line of lines) assert.equal(visibleWidth(line), 80, `"${stripAnsi(line)}" is not 80 wide`);
+	const plain = lines.map(stripAnsi);
+	assert.match(plain[0], /^╭─ ✎ Changes · 2 files · \+12 −1 ─+╮$/);
+	assert.match(plain[1], /^│ ▸ lib\/a\.ts +\+2 −1 +│ @@ -1,2 \+1,3 @@ +│$/);
+	assert.match(plain[2], /^│   lib\/b\.ts +\+10 new +│  const a = 1; +│$/);
+	assert.match(plain[11], /^╰─+╯$/);
+	assert.match(plain[10], /j\/k file .* o open in editor .* esc close/);
+});
+
+test("ChangesView loads the selected diff lazily and moves with j/k and arrows", async () => {
+	const { view: component, calls, events } = view();
+	await settle();
+	assert.deepEqual(calls, ["lib/a.ts"]);
+	component.handleInput("j");
+	await settle();
+	assert.deepEqual(calls, ["lib/a.ts", "lib/b.ts"]);
+	assert.match(stripAnsi(component.render(80)[2]), /^│ ▸ lib\/b\.ts/);
+	component.handleInput("\x1b[A");
+	assert.match(stripAnsi(component.render(80)[1]), /^│ ▸ lib\/a\.ts/);
+	component.handleInput("k");
+	assert.match(stripAnsi(component.render(80)[1]), /^│ ▸ lib\/a\.ts/);
+	assert.ok(events.filter((event) => event === "render").length >= 2);
+});
+
+test("ChangesView scrolls the diff pane and shows an empty state for files without a diff", async () => {
+	const long = Array.from({ length: 40 }, (_, index) => `+line ${index}`).join("\n");
+	const { view: component } = view({ async loadDiff() { return `@@ -0,0 +1,40 @@\n${long}`; } });
+	await settle();
+	component.handleInput("\x1b[6~");
+	const plain = component.render(80).map(stripAnsi);
+	assert.doesNotMatch(plain[1], /@@/);
+	assert.match(plain[1], /\+line \d+/);
+	component.handleInput("\x0b");
+	assert.match(stripAnsi(component.render(80)[1]), /@@/, "ctrl+k scrolls back to the top");
+	component.handleInput("\x0a");
+	assert.doesNotMatch(stripAnsi(component.render(80)[1]), /@@/, "ctrl+j scrolls a page down");
+
+	const empty = view({ async loadDiff() { return ""; } });
+	await settle();
+	assert.match(stripAnsi(empty.view.render(80)[1]), /no diff for this file/);
+});
+
+test("ChangesView opens the selected file and closes on escape or q", async () => {
+	const { view: component, events } = view();
+	await settle();
+	component.handleInput("o");
+	assert.ok(events.includes("open:lib/a.ts"));
+	component.handleInput("\x1b");
+	component.handleInput("q");
+	assert.equal(events.filter((event) => event === "close").length, 2);
+});
+
+test("ChangesView.update keeps the selected file, reloads moved diffs, and survives an empty tree", async () => {
+	const { view: component, calls } = view();
+	await settle();
+	component.handleInput("j");
+	await settle();
+	assert.deepEqual(calls, ["lib/a.ts", "lib/b.ts"]);
+
+	component.update(changesModel([file("lib/a.ts", 5, 1), file("lib/b.ts", 10, 0, CHANGE_STATUS.ADDED), file("lib/c.ts", 1, 0)]));
+	await settle();
+	assert.match(stripAnsi(component.render(80)[2]), /^│ ▸ lib\/b\.ts/);
+	assert.deepEqual(calls, ["lib/a.ts", "lib/b.ts"], "unchanged selected file must not reload");
+	component.handleInput("k");
+	await settle();
+	assert.deepEqual(calls, ["lib/a.ts", "lib/b.ts", "lib/a.ts"], "moved counts must reload the diff");
+
+	component.update(changesModel([]));
+	const plain = component.render(80).map(stripAnsi);
+	assert.match(plain[0], /0 files · \+0 −0/);
+	assert.match(plain[1], /working tree is clean/);
+	component.handleInput("j");
+	component.handleInput("o");
+});

package/tests/shell-changes.test.ts

@@ -0,0 +1,182 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import {
+	CHANGE_STATUS,
+	ChangesTracker,
+	changesSummary,
+	emptyChanges,
+	parseNumstat,
+	parsePorcelain,
+	renderChangesWidget,
+	changesModel,
+	snapshotChanges,
+	type ChangedFile,
+} from "../lib/shell-changes.ts";
+
+// The changes view shows the working tree against HEAD, new files included,
+// so a resumed session sees the same picture as a fresh one.
+
+const plainTheme = {
+	fg(_color: string, text: string) {
+		return text;
+	},
+	bold(text: string) {
+		return text;
+	},
+};
+
+const taggedTheme = {
+	fg(color: string, text: string) {
+		return `<${color}>${text}</${color}>`;
+	},
+	bold(text: string) {
+		return text;
+	},
+};
+
+function file(path: string, added: number, deleted: number, status: ChangedFile["status"] = CHANGE_STATUS.MODIFIED): ChangedFile {
+	return { path, added, deleted, status };
+}
+
+test("parseNumstat reads counts, treats binaries as zero, and resolves rename braces", () => {
+	const parsed = parseNumstat("12\t3\tlib/a.ts\n-\t-\tassets/logo.png\n0\t0\tsrc/{old => new}/file.ts\n5\t1\told.ts => new.ts\n");
+	assert.deepEqual(parsed, [
+		{ path: "lib/a.ts", added: 12, deleted: 3 },
+		{ path: "assets/logo.png", added: 0, deleted: 0 },
+		{ path: "src/new/file.ts", added: 0, deleted: 0 },
+		{ path: "new.ts", added: 5, deleted: 1 },
+	]);
+});
+
+test("parsePorcelain reads NUL-separated status entries including renames and untracked files", () => {
+	const raw = [" M lib/a.ts", "A  lib/b.ts", " D lib/c.ts", "?? notes.md", "R  new.ts", "old.ts", "MM lib/d.ts"].join("\0") + "\0";
+	const parsed = parsePorcelain(raw);
+	assert.deepEqual(
+		[...parsed.entries()],
+		[
+			["lib/a.ts", CHANGE_STATUS.MODIFIED],
+			["lib/b.ts", CHANGE_STATUS.ADDED],
+			["lib/c.ts", CHANGE_STATUS.DELETED],
+			["notes.md", CHANGE_STATUS.UNTRACKED],
+			["new.ts", CHANGE_STATUS.RENAMED],
+			["lib/d.ts", CHANGE_STATUS.MODIFIED],
+		],
+	);
+});
+
+test("snapshotChanges merges status with counts and keeps untracked files without counts", () => {
+	const files = snapshotChanges({
+		numstat: "4\t2\tlib/a.ts\n",
+		porcelain: " M lib/a.ts\0?? notes.md\0",
+	});
+	assert.deepEqual(files, [file("lib/a.ts", 4, 2), file("notes.md", 0, 0, CHANGE_STATUS.UNTRACKED)]);
+});
+
+test("changesModel sorts files by path and totals the counts", () => {
+	const model = changesModel([file("lib/b.ts", 10, 0, CHANGE_STATUS.ADDED), file("lib/a.ts", 4, 2)]);
+	assert.deepEqual(model.files, [file("lib/a.ts", 4, 2), file("lib/b.ts", 10, 0, CHANGE_STATUS.ADDED)]);
+	assert.equal(model.added, 14);
+	assert.equal(model.deleted, 2);
+});
+
+test("changesSummary and the widget describe the session at a glance", () => {
+	const model = changesModel([file("extensions/gentle-shell.ts", 31, 0, CHANGE_STATUS.ADDED), file("lib/shell-bar.ts", 9, 7), file("tests/x.test.ts", 2, 0)]);
+	assert.equal(changesSummary(model), "3 files · +42 −7");
+	assert.equal(changesSummary(changesModel([file("a.ts", 1, 0)])), "1 file · +1 −0");
+
+	const [line, ...rest] = renderChangesWidget(model, plainTheme, 120);
+	assert.equal(rest.length, 0);
+	assert.match(line, /^✎ 3 files · \+42 −7 · extensions\/gentle-shell\.ts · lib\/shell-bar\.ts · tests\/x\.test\.ts {2,}\/gentle:changes$/);
+	assert.equal(visibleWidth(line), 120, "the command sits on the right edge");
+});
+
+test("renderChangesWidget colors counts by direction and yields nothing when clean", () => {
+	const model = changesModel([file("a.ts", 1, 2)]);
+	const [line] = renderChangesWidget(model, taggedTheme, 400);
+	assert.match(line, /<accent>✎<\/accent>/);
+	assert.match(line, /<success>\+1<\/success> <error>−2<\/error>/);
+	assert.match(line, /<dim>\/gentle:changes<\/dim>$/);
+	assert.deepEqual(renderChangesWidget(emptyChanges(), plainTheme, 120), []);
+});
+
+test("renderChangesWidget drops the file list before truncating on narrow terminals", () => {
+	const model = changesModel([file("a/very/long/path/one.ts", 1, 0), file("a/very/long/path/two.ts", 1, 0)]);
+	const [line] = renderChangesWidget(model, plainTheme, 40);
+	assert.equal(visibleWidth(line), 40);
+	assert.match(line, /^✎ 2 files · \+2 −0 +\/gentle:changes$/);
+	assert.doesNotMatch(line, /one\.ts/);
+	const [tiny] = renderChangesWidget(model, plainTheme, 20);
+	assert.ok(visibleWidth(tiny) <= 20);
+	assert.match(tiny, /^✎ 2 files/);
+});
+
+function fakeGit(numstats: string[], porcelains: string[], code = 0) {
+	const calls: string[][] = [];
+	let round = 0;
+	const git = async (args: string[]) => {
+		calls.push(args);
+		const isNumstat = args[0] === "diff";
+		const index = Math.min(isNumstat ? round : round++, numstats.length - 1);
+		return { stdout: isNumstat ? numstats[index] : porcelains[index], code };
+	};
+	return { git, calls };
+}
+
+test("ChangesTracker reads the working tree on start and again on refresh", async () => {
+	const { git, calls } = fakeGit(
+		["4\t2\tlib/a.ts\n", "4\t2\tlib/a.ts\n10\t0\tlib/b.ts\n"],
+		[" M lib/a.ts\0", " M lib/a.ts\0A  lib/b.ts\0"],
+	);
+	const tracker = new ChangesTracker(git);
+	await tracker.start();
+	assert.deepEqual(tracker.model.files, [file("lib/a.ts", 4, 2)]);
+	const model = await tracker.refresh();
+	assert.deepEqual(model.files, [file("lib/a.ts", 4, 2), file("lib/b.ts", 10, 0, CHANGE_STATUS.ADDED)]);
+	assert.equal(calls.length, 4);
+	assert.deepEqual(calls[0], ["diff", "--numstat", "HEAD"]);
+	assert.deepEqual(calls[1], ["status", "--porcelain=v1", "--untracked-files=all", "-z"]);
+});
+
+test("ChangesTracker stays quiet outside a git repository", async () => {
+	const { git, calls } = fakeGit([""], [""], 128);
+	const tracker = new ChangesTracker(git);
+	await tracker.start();
+	assert.deepEqual(await tracker.refresh(), emptyChanges());
+	assert.equal(calls.length, 2);
+});
+
+test("ChangesTracker coalesces overlapping refreshes into at most one extra round", async () => {
+	let resolveGate: (() => void) | undefined;
+	let rounds = 0;
+	const git = async (args: string[]) => {
+		if (args[0] === "diff") {
+			rounds += 1;
+			if (rounds === 2) await new Promise<void>((resolve) => { resolveGate = resolve; });
+		}
+		return { stdout: "", code: 0 };
+	};
+	const tracker = new ChangesTracker(git);
+	await tracker.start();
+	const first = tracker.refresh();
+	const second = tracker.refresh();
+	const third = tracker.refresh();
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	resolveGate?.();
+	await Promise.all([first, second, third]);
+	assert.equal(rounds, 3);
+});
+
+test("ChangesTracker counts the lines of untracked files, which git numstat leaves out", async () => {
+	const { git } = fakeGit(["", ""], ["", "?? notes.md\0?? empty.md\0"]);
+	const counted: string[] = [];
+	const tracker = new ChangesTracker(git, async (path) => {
+		counted.push(path);
+		return path === "notes.md" ? 3 : 0;
+	});
+	await tracker.start();
+	const model = await tracker.refresh();
+	assert.deepEqual(model.files, [file("empty.md", 0, 0, CHANGE_STATUS.UNTRACKED), file("notes.md", 3, 0, CHANGE_STATUS.UNTRACKED)]);
+	assert.equal(model.added, 3);
+	assert.deepEqual(counted, ["notes.md", "empty.md"]);
+});