gentle-pi 4.0.0 → 4.2.0

package/lib/session-profile-persistence.ts

@@ -0,0 +1,187 @@
+// Standalone v1 codec and pure active-branch replay (gentle-shell#1064).
+// No Pi API, disk access, shared binding store, or orchestrator application.
+import { isValidProfileName } from "./agent-profiles.ts";
+import {
+	isSafeAgentName,
+	isThinkingLevel,
+	normalizeModelId,
+	normalizeRoutingEntry,
+	type AgentModelConfig,
+	type AgentRoutingEntry,
+} from "./model-routing-authority.ts";
+
+export const SESSION_PROFILE_CUSTOM_TYPE = "gentle-pi.session-profile/v1";
+const SESSION_PROFILE_FAMILY = "gentle-pi.session-profile/";
+
+export type SessionProfileOrigin = "user" | "local" | "repo" | "global";
+
+export interface SessionProfileBindPayload {
+	kind: "bind";
+	origin: SessionProfileOrigin;
+	name: string;
+	modelProfiles: AgentModelConfig;
+}
+
+export interface SessionProfileClearPayload {
+	kind: "clear";
+}
+
+/** Public structural entry shape only; ordinary messages need no custom fields. */
+export interface SessionProfileEntry {
+	type: string;
+	customType?: string;
+	data?: unknown;
+}
+
+export type SessionProfileReadResult =
+	| { status: "absent" }
+	| { status: "bound"; binding: SessionProfileBindPayload }
+	| { status: "cleared" }
+	| { status: "invalid" }
+	| { status: "unsupported" };
+
+export type SessionProfileReplayResult =
+	| { status: "absent" }
+	| (Exclude<SessionProfileReadResult, { status: "absent" }> & {
+			entryIndex: number;
+	  });
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasOwn(value: Record<string, unknown>, key: string): boolean {
+	return Object.hasOwn(value, key);
+}
+
+function isOrigin(value: unknown): value is SessionProfileOrigin {
+	return (
+		value === "user" ||
+		value === "local" ||
+		value === "repo" ||
+		value === "global"
+	);
+}
+
+/** Validate known fields before the permissive routing helper can drop them. */
+function readRoute(
+	value: unknown,
+	encoderInput = false,
+): AgentRoutingEntry | undefined {
+	if (typeof value === "string") return normalizeRoutingEntry(value);
+	if (!isRecord(value)) return undefined;
+	// Typed normalized routes can own optional undefined fields. Omit only those
+	// encoder fields; persisted fields and legacy effort retain strict validation.
+	const route = encoderInput
+		? Object.fromEntries(
+				Object.entries(value).filter(
+					([key, field]) =>
+						!((key === "model" || key === "thinking") && field === undefined),
+				),
+			)
+		: value;
+	if (hasOwn(route, "model") && normalizeModelId(route.model) === undefined)
+		return undefined;
+	if (hasOwn(route, "thinking") && !isThinkingLevel(route.thinking))
+		return undefined;
+	if (hasOwn(route, "effort") && !isThinkingLevel(route.effort))
+		return undefined;
+	// Project only own known fields. Unknown extras, even an unknown-only route,
+	// carry no routing meaning. Thinking wins over legacy effort as elsewhere.
+	const known = Object.fromEntries(
+		["model", "thinking", "effort"]
+			.filter((key) => hasOwn(route, key))
+			.map((key) => [key, route[key]]),
+	);
+	const normalized = normalizeRoutingEntry(known);
+	if (!normalized) return undefined;
+	return Object.fromEntries(
+		Object.entries(normalized).filter(([, field]) => field !== undefined),
+	);
+}
+
+function readSnapshot(
+	value: unknown,
+	encoderInput = false,
+): AgentModelConfig | undefined {
+	if (!isRecord(value)) return undefined;
+	const entries: Array<[string, AgentRoutingEntry]> = [];
+	for (const [name, rawRoute] of Object.entries(value)) {
+		// Shared agent-name policy, applied here without the forgiving whole-config
+		// normalization that would silently discard a bad route. Output below uses
+		// own data properties, never prototype setters.
+		if (!isSafeAgentName(name)) return undefined;
+		const route = readRoute(rawRoute, encoderInput);
+		if (route === undefined) return undefined;
+		entries.push([name, route]);
+	}
+	return Object.fromEntries(entries);
+}
+
+function readBind(
+	data: Record<string, unknown>,
+	encoderInput = false,
+): SessionProfileBindPayload | undefined {
+	if (!["origin", "name", "modelProfiles"].every((key) => hasOwn(data, key)))
+		return undefined;
+	if (!isOrigin(data.origin) || !isValidProfileName(data.name)) return undefined;
+	const modelProfiles = readSnapshot(data.modelProfiles, encoderInput);
+	if (modelProfiles === undefined) return undefined;
+	return { kind: "bind", origin: data.origin, name: data.name, modelProfiles };
+}
+
+/** Create a detached user selection payload; never appends or claims durability. */
+export function createSessionProfileBind(
+	name: string,
+	modelProfiles: AgentModelConfig,
+): SessionProfileBindPayload {
+	const binding = readBind({ origin: "user", name, modelProfiles }, true);
+	if (!binding) throw new TypeError("Invalid session profile binding");
+	return binding;
+}
+
+export function createSessionProfileClear(): SessionProfileClearPayload {
+	return { kind: "clear" };
+}
+
+/** Unknown family identifiers are terminal unsupported states, regardless of data. */
+export function readSessionProfileEntry(
+	entry: SessionProfileEntry,
+): SessionProfileReadResult {
+	if (
+		entry.type !== "custom" ||
+		typeof entry.customType !== "string" ||
+		!entry.customType.startsWith(SESSION_PROFILE_FAMILY)
+	)
+		return { status: "absent" };
+	if (entry.customType !== SESSION_PROFILE_CUSTOM_TYPE)
+		return { status: "unsupported" };
+	const data = entry.data;
+	if (!isRecord(data) || !hasOwn(data, "kind")) return { status: "invalid" };
+	if (data.kind === "clear") return { status: "cleared" };
+	if (data.kind !== "bind") return { status: "invalid" };
+	const binding = readBind(data);
+	return binding ? { status: "bound", binding } : { status: "invalid" };
+}
+
+/**
+ * Caller MUST supply ALREADY disk-corroborated active-branch entries, in branch
+ * order (oldest to newest). This function cannot establish that precondition:
+ * it does not read disk, call Pi, enforce append-failure recovery, establish
+ * durability, or update the shared map. In-memory getBranch() alone is NOT
+ * corroboration. Sibling and future paths must be excluded by the caller.
+ *
+ * The newest family entry wins even when invalid or unsupported; never revive
+ * an older binding. Cleared permits current fallback at a later consumer,
+ * whereas invalid/unsupported must remain distinct from absent. entryIndex is
+ * the actual supplied branch offset for a later adapter's location warning.
+ */
+export function replaySessionProfileBranch(
+	entries: readonly SessionProfileEntry[],
+): SessionProfileReplayResult {
+	for (let entryIndex = entries.length - 1; entryIndex >= 0; entryIndex--) {
+		const result = readSessionProfileEntry(entries[entryIndex]);
+		if (result.status !== "absent") return { ...result, entryIndex };
+	}
+	return { status: "absent" };
+}

package/lib/session-worktree-registry.ts

@@ -1,7 +1,7 @@
 import { execFileSync } from "node:child_process";
-import { realpathSync, statSync } from "node:fs";
+import { lstatSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 export const SESSION_WORKTREE_ENTRY = "gentle-pi.session-worktree/v1";
 export const SESSION_WORKTREE_CHANGED = "gentle-pi:session-worktree-changed";
@@ -23,12 +23,16 @@ export function worktreeGitEnvironment(env: NodeJS.ProcessEnv = process.env): No
 }
 
 // Match Pi's ordinary path spelling; Git, not the argument, establishes identity.
+function canonicalDirectory(path: string, cwd: string): string {
+	let spelling = path.replace(/^@/, "").replace(/[\u00a0\u2000-\u200a\u202f\u205f\u3000]/g, " ");
+	if (spelling === "~" || spelling.startsWith("~/")) spelling = homedir() + spelling.slice(1);
+	const canonical = realpathSync(resolve(cwd, spelling));
+	return statSync(canonical).isDirectory() ? canonical : dirname(canonical);
+}
+
 export function resolveSessionWorktreeWithGit(path: string, cwd: string, run: typeof execFileSync = execFileSync): WorktreeIdentity | undefined {
 	try {
-		let spelling = path.replace(/^@/, "").replace(/[\u00a0\u2000-\u200a\u202f\u205f\u3000]/g, " ");
-		if (spelling === "~" || spelling.startsWith("~/")) spelling = homedir() + spelling.slice(1);
-		const canonical = realpathSync(resolve(cwd, spelling));
-		const directory = statSync(canonical).isDirectory() ? canonical : dirname(canonical);
+		const directory = canonicalDirectory(path, cwd);
 		// Ambient Git routing must not redirect a path into another repository.
 		const env = worktreeGitEnvironment();
 		const git = (arg: string) => String(run("git", ["--no-optional-locks", "-C", directory, "rev-parse", "--path-format=absolute", arg], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "pipe"], shell: false, windowsHide: true, env })).replace(/\r?\n$/, "");
@@ -38,7 +42,69 @@ export function resolveSessionWorktreeWithGit(path: string, cwd: string, run: ty
 	}
 }
 
-export const resolveSessionWorktree: WorktreeResolver = resolveSessionWorktreeWithGit;
+// Filesystem identity of everything Git used to answer: no `.git` between the
+// directory and its root, and the same root, `.git` entry and common dir.
+// Undefined when any of it cannot be proven, so the answer is not memoized.
+function worktreeFingerprint(directory: string, identity: WorktreeIdentity): string | undefined {
+	const same = (a: string, b: string) => process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+	try {
+		for (let current = directory; !same(current, identity.root); current = dirname(current)) {
+			if (dirname(current) === current) return undefined;
+			try { lstatSync(join(current, ".git")); return undefined; }
+			catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") return undefined; }
+		}
+		const marker = lstatSync(join(identity.root, ".git"));
+		const parts = [statSync(identity.root), marker, statSync(identity.commonDir)].map(entry => `${entry.dev}:${entry.ino}`);
+		// A linked worktree's `.git` file can be rewritten in place to another clone.
+		if (marker.isFile()) parts.push(`${marker.size}:${marker.mtimeMs}`);
+		return parts.join("|");
+	} catch {
+		return undefined;
+	}
+}
+
+export interface WorktreeMemoOptions { ttlMs?: number; now?: () => number }
+interface MemoEntry { identity: WorktreeIdentity; directory: string; fingerprint: string; expiresAt: number }
+const memoInvalidators = new Set<() => void>();
+
+// Startup asks the same (cwd, cwd) question from several extensions; each
+// answer costs two synchronous Git children. Only proven repositories are
+// memoized, and every hit re-checks their filesystem identity, so removal,
+// replacement, a nested `.git` and bootstrap (never cached) are seen at once.
+// The TTL bounds what stat cannot see, such as Git config edits.
+export function memoizeWorktreeResolver(resolver: WorktreeResolver, { ttlMs = 5000, now = Date.now }: WorktreeMemoOptions = {}): WorktreeResolver {
+	const memo = new Map<string, MemoEntry>();
+	memoInvalidators.add(() => memo.clear());
+	return (path, cwd) => {
+		const key = `${path}\u0000${cwd}`;
+		const cached = memo.get(key);
+		if (cached && cached.expiresAt > now()) {
+			try {
+				const directory = canonicalDirectory(path, cwd);
+				if (directory === cached.directory && worktreeFingerprint(directory, cached.identity) === cached.fingerprint) return { ...cached.identity };
+			} catch { /* Fall through to a fresh resolution. */ }
+		}
+		memo.delete(key);
+		const identity = resolver(path, cwd);
+		if (!identity) return undefined;
+		try {
+			const directory = canonicalDirectory(path, cwd);
+			const fingerprint = worktreeFingerprint(directory, identity);
+			if (fingerprint !== undefined) {
+				if (memo.size >= 256) memo.clear();
+				memo.set(key, { identity: { ...identity }, directory, fingerprint, expiresAt: now() + ttlMs });
+			}
+		} catch { /* Unprovable identity is returned but never memoized. */ }
+		return identity;
+	};
+}
+
+/** Drops every memoized worktree identity; the next lookup asks Git again. */
+export function clearSessionWorktreeMemo(): void {
+	for (const invalidate of memoInvalidators) invalidate();
+}
+
+export const resolveSessionWorktree: WorktreeResolver = memoizeWorktreeResolver(resolveSessionWorktreeWithGit);
 
 export function toolWorktreePath(name: string, input: Record<string, unknown>): string | undefined {
 	if (!["read", "write", "edit", "grep", "find", "ls"].includes(name)) return undefined;
@@ -82,7 +148,7 @@ export class SessionWorktreeRegistry {
 		if (!this.isCurrent()) throw new Error("Cannot register a worktree for an inactive session.");
 		const identity = this.refreshIdentity();
 		const target = this.resolver(path, this.cwd);
-		if (!target || !identity || target.commonDir !== identity.commonDir) throw new Error("Select an existing worktree in the same Git clone as this session.");
+		if (!target || !identity || target.commonDir !== identity.commonDir) throw new Error("Select an existing worktree in the same Git clone as this session. To work in an independent Git repository, delegate with subagent_run with repository_root instead; it asks for your consent first.");
 		return target.root;
 	}
 

package/lib/shell-bar.ts

@@ -6,6 +6,8 @@ import { CARD_TONE, floatRows, panelInnerWidth, renderCard } from "./shell-card.
 import { REVIEW_SCOPE_UNAVAILABLE, REVIEW_SIDEBAR_LABELS, type ReviewSidebarSnapshot } from "./review-sidebar-state.ts";
 import type { VisualSettings } from "./visual-customization-policy.ts";
 import { renderChangesWidget, type ChangesModel } from "./shell-changes.ts";
+import type { RunningJobDisplay } from "./jobs-sidebar-state.ts";
+import { JOB_GLYPH } from "./background-jobs-tools.ts";
 
 type Presentation = Pick<VisualSettings, "density" | "visibility">;
 type HeaderPresentation = Presentation & Partial<Pick<VisualSettings, "headerPlacement" | "statusPlacement">>;
@@ -18,6 +20,7 @@ export { gaugeTone, renderGauge, type GaugeTone };
 
 export interface ShellBarModel {
 	review?: ReviewSidebarSnapshot;
+	jobs?: RunningJobDisplay[];
 	profile?: string;
 	changes?: { files: number; added: number; deleted: number; notice?: string };
 	cwd: string;
@@ -35,11 +38,10 @@ export interface ShellBarModel {
 }
 
 // The live header row above the fullscreen rail: session identity plus the
-// two counters that tick every frame (context, cost). Deliberately narrower
-// than ShellBarModel — extension statuses and the working/thinking state
-// never reach the header, so there is nothing on this type for them to leak
-// through.
+// live counters. Only the structured jobs count may join context/cost when
+// Status is absent; opaque extension statuses and working state stay excluded.
 export interface ShellHeaderModel {
+	jobs?: number;
 	cwd: string;
 	branch: string | null;
 	dirty: number | undefined;
@@ -55,9 +57,14 @@ export interface ShellHeaderModel {
 	usage: ProviderUsage | undefined;
 }
 
-export function buildShellHeaderModel(model: ShellBarModel): ShellHeaderModel {
+export function buildShellHeaderModel(model: ShellBarModel, showJobs = false): ShellHeaderModel {
 	const { cwd, branch, dirty, modelId, effort, profile, contextPercent, costTotal, subscription, usage } = model;
-	return { cwd, branch, dirty, modelId, effort, profile, contextPercent, costTotal, subscription, usage };
+	return { cwd, branch, dirty, modelId, effort, profile, contextPercent, costTotal, subscription, usage,
+		...(showJobs && model.jobs?.length ? { jobs: model.jobs.length } : {}) };
+}
+
+export function shellJobsCount(count: number): string {
+	return `${JOB_GLYPH} ${count} job${count === 1 ? "" : "s"}`;
 }
 
 /** A column span (`[start, end)`, in the rendered line's visible columns) a click must land in to hit the usage segment. */
@@ -110,6 +117,13 @@ export function shellEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
 	return !(value === "0" || value === "false" || value === "off");
 }
 
+// Herdr's native Pi detection matches Pi's standard loader row ("⠋ Working...").
+// Inside a Herdr pane keep that row, which Pi shows only during real activity,
+// so detection works without a local manifest override.
+export function keepNativeWorkingRow(env: NodeJS.ProcessEnv = process.env): boolean {
+	return env.HERDR_ENV === "1" && env.GENTLE_PI_AGENTS_CHILD !== "1";
+}
+
 export function formatTokens(count: number): string {
 	if (count < 1000) return count.toString();
 	if (count < 10_000) return `${(count / 1000).toFixed(1)}k`;
@@ -166,6 +180,7 @@ function buildSegments(model: ShellBarModel, theme: ShellBarTheme, presentation?
 		location,
 		...(presentation?.visibility.modelDetails === false ? [] : [modelSegment]),
 		...(presentation?.visibility.usageCost === false ? [] : [context, cost, ...(usage ? [usage] : [])]),
+		...(model.jobs?.length ? [theme.fg(ROLE.STATUS, shellJobsCount(model.jobs.length))] : []),
 		...statuses,
 	];
 }
@@ -237,6 +252,10 @@ export function renderShellSidebarBar(model: ShellBarModel, theme: ShellBarTheme
 				...(model.review.scope !== REVIEW_SCOPE_UNAVAILABLE ? [label(sanitizeStatus(model.review.scope))] : []),
 			],
 		}] : []),
+		...(model.jobs?.length ? [{
+			title: "Jobs",
+			lines: [...model.jobs].sort((a, b) => b.startedAt - a.startedAt).map((job) => value(sanitizeStatus(job.label))),
+		}] : []),
 		{ title: "Integrations", lines: model.statuses.length
 			? model.statuses.map((status) => theme.fg(ROLE.STATUS, sanitizeStatus(status)))
 			: [label("No status reported")] },
@@ -360,7 +379,11 @@ export function shellHeaderUsageHit(chrome: ShellHeaderChrome, x: number, y: num
 
 function headerContent(model: ShellHeaderModel, theme: ShellBarTheme, width: number, usageHint?: string, presentation?: Presentation): ShellHeaderResult {
 	const targetWidth = Math.max(0, Math.floor(width));
-	const ctxCost = joinSegments([contextSegment(model.contextPercent, theme), costSegment(model.costTotal, model.subscription, theme)], theme);
+	const jobs = model.jobs ? theme.fg(ROLE.STATUS, shellJobsCount(model.jobs)) : undefined;
+	const ctxCost = joinSegments([
+		...(jobs ? [jobs] : []),
+		...(presentation?.visibility.usageCost === false ? [] : [contextSegment(model.contextPercent, theme), costSegment(model.costTotal, model.subscription, theme)]),
+	], theme);
 	const windows = model.usage ? (selectUsageLimit(model.usage, model.modelId)?.windows ?? []) : [];
 	const leftStages = headerLeftStages(model, theme, presentation?.visibility.modelDetails !== false)
 		.map((stage) => presentation?.density === "minimal" ? stage.slice(1) : stage);
@@ -381,7 +404,7 @@ function headerContent(model: ShellHeaderModel, theme: ShellBarTheme, width: num
 	];
 	for (const { leftIndex, usageStage } of attempts) {
 		const usageText = usageStage ? usageSegmentText(windows, theme, usageStage, usageHint) : undefined;
-		const right = presentation?.visibility.usageCost === false ? "" : usageText ? joinSegments([ctxCost, usageText], theme) : ctxCost;
+		const right = usageText ? joinSegments([ctxCost, usageText], theme) : ctxCost;
 		const left = joinSegments(leftStages[leftIndex]!, theme);
 		if (visibleWidth(left) + (right ? RIGHT_PADDING : 0) + visibleWidth(right) > targetWidth) continue;
 		const text = left + " ".repeat(targetWidth - visibleWidth(left) - visibleWidth(right)) + right;
@@ -390,6 +413,10 @@ function headerContent(model: ShellHeaderModel, theme: ShellBarTheme, width: num
 		return { text, usageSpan: { start: usageStart, end: usageStart + visibleWidth(usageText) } };
 	}
 	const brand = presentation?.density === "minimal" ? "" : theme.fg(ROLE.BRAND, theme.bold(HEADER_BRAND));
+	if (jobs && visibleWidth(jobs) <= targetWidth) {
+		const left = visibleWidth(brand) + RIGHT_PADDING + visibleWidth(jobs) <= targetWidth ? brand : "";
+		return { text: left + " ".repeat(targetWidth - visibleWidth(left) - visibleWidth(jobs)) + jobs };
+	}
 	return { text: visibleWidth(brand) <= targetWidth ? brand : "" };
 }
 
@@ -399,11 +426,14 @@ export function renderShellBelowInputFloat(model: ShellBarModel, theme: ShellBar
 	if (presentation?.headerPlacement !== "below-input") return undefined;
 	const targetWidth = Math.max(0, Math.floor(width));
 	if (floatHeaderPaint(theme, targetWidth, () => "") === undefined) return undefined;
-	const chrome = renderShellHeaderChrome(buildShellHeaderModel(model), theme, targetWidth, usageHint, presentation);
+	const chrome = renderShellHeaderChrome(buildShellHeaderModel(model, presentation.statusPlacement === "hidden"), theme, targetWidth, usageHint, presentation);
 	const changesRow = changes?.files.length && presentation.visibility.changes !== false
 		? floatHeaderRow(theme, targetWidth, (inner) => renderChangesWidget(changes, theme, inner)[0] ?? "")
 		: undefined;
-	const statuses = presentation.statusPlacement === "hidden" ? [] : model.statuses.map(sanitizeStatus).filter(Boolean);
+	const statuses = presentation.statusPlacement === "hidden" ? [] : [
+		...(model.jobs?.length ? [shellJobsCount(model.jobs.length)] : []),
+		...model.statuses.map(sanitizeStatus).filter(Boolean),
+	];
 	const statusRow = statuses.length
 		? floatHeaderRow(theme, targetWidth, () => joinSegments(statuses.map((status) => theme.fg(ROLE.STATUS, status)), theme))
 		: undefined;
@@ -429,7 +459,7 @@ export function renderShellBelowInputFloat(model: ShellBarModel, theme: ShellBar
 export function renderShellBottomOnlyBar(model: ShellBarModel, theme: ShellBarTheme, width: number, usageHint?: string, presentation?: HeaderPresentation, changes?: ChangesModel): string[] {
 	const grouped = renderShellBelowInputFloat(model, theme, width, usageHint, presentation, changes);
 	if (grouped) return grouped.rows;
-	const headerModel = buildShellHeaderModel(model);
+	const headerModel = buildShellHeaderModel(model, true);
 	// Neon, missing backgrounds and sub-minimum widths keep the old row count.
 	const rows = [headerContent(headerModel, theme, width, usageHint, presentation).text];
 	const statuses = model.statuses.map(sanitizeStatus).filter((status) => status.length > 0).map((status) => theme.fg(ROLE.STATUS, status));

package/lib/shell-changes-view.ts

@@ -1,7 +1,7 @@
 import { Key, matchesKey, truncateToWidth, visibleWidth, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
 import { sanitizeTerminalText } from "./terminal-theme.ts";
-import { basename } from "node:path";
-import { CHANGE_STATUS, changesSummary, type ChangedFile, type ChangesModel, type WorktreeChanges } from "./shell-changes.ts";
+import { basename, posix } from "node:path";
+import { CHANGE_STATUS, DIFF_TOO_LARGE, changesSummary, type ChangedFile, type ChangesModel, type WorktreeChanges } from "./shell-changes.ts";
 import { paintHoverable } from "./shell-hover.ts";
 
 // Gentle Shell changes overlay: a framed two-pane view with the working
@@ -37,7 +37,7 @@ const ROLE = {
 } as const;
 
 const HEADER_PREFIXES = ["diff --git", "index ", "--- ", "+++ ", "new file mode", "deleted file mode", "similarity index", "rename from", "rename to", "Binary files"];
-const LIST_MAX_WIDTH = 36;
+const LIST_MAX_WIDTH = 48;
 const LIST_RATIO = 0.35;
 const CHROME_ROWS = 3;
 const MIN_BODY_ROWS = 1;
@@ -80,8 +80,32 @@ function fileCounts(file: ChangedFile, theme: ChangesViewTheme): string {
 	return `${theme.fg(ROLE.ADDED, `+${file.added}`)} ${theme.fg(ROLE.REMOVED, `-${file.deleted}`)}`;
 }
 
+// The name leads and the directory trails, so a narrow list clips the
+// directory instead of the part that identifies the file.
 function fileLabel(file: ChangedFile, theme: ChangesViewTheme, hovered: boolean, idleRole: string): string {
-	return `${paintHoverable(theme, `${FILE_STATUS[file.status]} ${displayText(file.path)}`, hovered, idleRole)}  ${fileCounts(file, theme)}`;
+	const directory = posix.dirname(file.path.replace(/\\/g, "/"));
+	const label = `${paintHoverable(theme, `${FILE_STATUS[file.status]} ${displayText(posix.basename(file.path.replace(/\\/g, "/")))}`, hovered, idleRole)}  ${fileCounts(file, theme)}`;
+	return directory === "." ? label : `${label}  ${theme.fg(ROLE.EMPTY, displayText(directory))}`;
+}
+
+// The diff pane's first row: the selected file's full path, clipped from the
+// left so the file name always stays visible.
+const PATH_HEADER_ROWS = 1;
+
+function pathHeader(file: ChangedFile, theme: ChangesViewTheme, width: number): string {
+	const status = `${FILE_STATUS[file.status]} `;
+	let path = displayText(file.path);
+	const room = Math.max(1, width - visibleWidth(status));
+	if (visibleWidth(path) > room) {
+		const characters = [...path];
+		while (characters.length > 0 && visibleWidth(`…${characters.join("")}`) > room) characters.shift();
+		path = `…${characters.join("")}`;
+	}
+	return theme.fg(ROLE.SELECTED, status + path);
+}
+
+function diffRows(bodyRows: number): number {
+	return Math.max(MIN_BODY_ROWS, bodyRows - PATH_HEADER_ROWS);
 }
 
 function fit(text: string, width: number): string {
@@ -90,10 +114,11 @@ function fit(text: string, width: number): string {
 }
 
 // Both standalone files and the worktree accordion use the original frame.
-function renderPanes(width: number, rows: number, theme: ChangesViewTheme, title: string, leftLine: (row: number) => string, rightLines: string[], keys: string): string[] {
+function renderPanes(width: number, rows: number, theme: ChangesViewTheme, title: string, leftLine: (row: number) => string, diffLines: string[], keys: string, headerFile?: ChangedFile): string[] {
 	const inner = Math.max(8, width - 2);
 	const listWidth = Math.min(LIST_MAX_WIDTH, Math.floor(inner * LIST_RATIO));
 	const diffWidth = inner - listWidth - 4;
+	const rightLines = headerFile ? [pathHeader(headerFile, theme, diffWidth), ...diffLines] : diffLines;
 	const titleText = truncateToWidth(title, inner - 4, "…");
 	const top = theme.fg(ROLE.FRAME, "╭─ ") + theme.fg(ROLE.TITLE, titleText) + theme.fg(ROLE.FRAME, ` ${rule(inner - visibleWidth(titleText) - 3)}╮`);
 	const body: string[] = [];
@@ -292,7 +317,7 @@ export class WorktreeChangesView {
 		};
 		const keys = theme.fg(ROLE.KEY_TEXT, "j/k select   enter toggle/open   ← parent/fold   ctrl+j/k scroll   r refresh   esc close");
 		this.pointerLayout = pointerLayout(width, height);
-		return renderPanes(width, height, theme, `✎ Changes · ${this.trees.length} worktrees`, leftLine, preview, keys);
+		return renderPanes(width, height, theme, `✎ Changes · ${this.trees.length} worktrees`, leftLine, preview, keys, selected?.file);
 	}
 
 	invalidate(): void {
@@ -406,8 +431,8 @@ export class ChangesView {
 		// the scroll keys are checked before the open key; a real Enter is CR.
 		if (data === "j" || matchesKey(data, Key.down)) this.select(this.selected + 1);
 		else if (data === "k" || matchesKey(data, Key.up)) this.select(this.selected - 1);
-		else if (matchesKey(data, Key.pageDown) || matchesKey(data, Key.ctrl("j"))) this.scrollBy(this.bodyRows());
-		else if (matchesKey(data, Key.pageUp) || matchesKey(data, Key.ctrl("k"))) this.scrollBy(-this.bodyRows());
+		else if (matchesKey(data, Key.pageDown) || matchesKey(data, Key.ctrl("j"))) this.scrollBy(diffRows(this.bodyRows()));
+		else if (matchesKey(data, Key.pageUp) || matchesKey(data, Key.ctrl("k"))) this.scrollBy(-diffRows(this.bodyRows()));
 		else if (data === "o" || matchesKey(data, Key.enter)) {
 			const file = this.model.files[this.selected];
 			if (file) this.deps.onOpen(file);
@@ -464,7 +489,7 @@ export class ChangesView {
 		this.fileScroll = this.clampFileScroll(this.fileScroll, rows);
 		const keys = KEYS.map(([key, label]) => `${theme.fg(ROLE.KEY, key)} ${theme.fg(ROLE.KEY_TEXT, key === "esc" ? (this.deps.backLabel ?? label) : label)}`).join("   ");
 		this.pointerLayout = pointerLayout(width, rows);
-		return renderPanes(width, rows, theme, `✎ Changes · ${changesSummary(this.model)}`, (row) => this.fileLine(row), this.visibleDiff(rows), keys);
+		return renderPanes(width, rows, theme, `✎ Changes · ${changesSummary(this.model)}`, (row) => this.fileLine(row), this.visibleDiff(rows), keys, this.model.files[this.selected]);
 	}
 
 	invalidate(): void {
@@ -500,8 +525,9 @@ export class ChangesView {
 		const lines = this.diffs.get(file.path);
 		if (!lines) return [];
 		if (lines.length === 0) return [this.deps.theme.fg(ROLE.EMPTY, EMPTY_DIFF)];
-		this.diffScroll = Math.min(this.diffScroll, Math.max(0, lines.length - rows));
-		return lines.slice(this.diffScroll, this.diffScroll + rows);
+		const visible = diffRows(rows);
+		this.diffScroll = Math.min(this.diffScroll, Math.max(0, lines.length - visible));
+		return lines.slice(this.diffScroll, this.diffScroll + visible);
 	}
 
 	private select(index: number): void {
@@ -534,7 +560,7 @@ export class ChangesView {
 		const file = this.model.files[this.selected];
 		const lines = file ? this.diffs.get(file.path) : undefined;
 		if (!lines) return false;
-		const next = Math.max(0, Math.min(Math.max(0, lines.length - rows), this.diffScroll + Math.trunc(delta)));
+		const next = Math.max(0, Math.min(Math.max(0, lines.length - diffRows(rows)), this.diffScroll + Math.trunc(delta)));
 		if (next === this.diffScroll) return false;
 		this.diffScroll = next;
 		return true;
@@ -557,7 +583,8 @@ export class ChangesView {
 		void this.deps.loadDiff(file).then(
 			(text) => {
 				if (this.disposed) return;
-				this.diffs.set(file.path, colorDiff(text, this.deps.theme));
+				// An oversized diff arrives as one plain line pointing at the editor.
+				this.diffs.set(file.path, text === DIFF_TOO_LARGE ? [this.deps.theme.fg(ROLE.EMPTY, text)] : colorDiff(text, this.deps.theme));
 				this.deps.requestRender();
 			},
 			() => {