gentle-pi 4.4.0 → 4.5.1

package/extensions/gentle-music.ts

@@ -1,8 +1,10 @@
 import { spawn as nodeSpawn } from "node:child_process";
 import { accessSync, constants, statSync } from "node:fs";
+import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Component } from "@earendil-works/pi-tui";
+import { runningBundledPrefix } from "../lib/gentle-shell-bundled.ts";
 
 // Gentle Music: /gentle:music hands the whole terminal to gentle-stream's own
 // TUI, the way Pi's external editor (ctrl+g) does: stop Pi's TUI, run the
@@ -12,12 +14,22 @@ import type { Component } from "@earendil-works/pi-tui";
 // `gentle-stream ctl …` with captured output and never take the terminal.
 //
 // Runtime imports stay node-only so the command loads without Pi's packages.
+//
+// A bundled Gentle Shell without any player offers to install one inside its
+// own folder (scripts/bundled-install.mjs installMusicPlayer): the pinned uv,
+// a uv-managed Python 3.13 and gentle-stream, all under the prefix. Other
+// installs keep the manual hint.
 
 export const MUSIC_COMMAND_NAME = "gentle:music";
 export const GENTLE_STREAM_SPEC = "gentle-stream[samples] @ git+https://github.com/Gentleman-Programming/gentle-stream";
 export const MUSIC_CONTROL_COMMANDS = ["next", "pause", "play", "stop", "status"] as const;
 export type MusicControlCommand = (typeof MUSIC_CONTROL_COMMANDS)[number];
 
+export const MUSIC_INSTALL_TITLE = "Install the music player?";
+export const MUSIC_INSTALL_OFFER = "Install the gentle-stream music player inside Gentle Shell? It downloads uv, Python 3.13 and the player (about 150 MB) into the Gentle Shell folder.";
+// gentle-stream needs POSIX (fcntl locks, an AF_UNIX control socket, process
+// groups), so a native Windows Pi can neither install nor run it; WSL is Linux.
+export const MUSIC_WINDOWS_UNSUPPORTED = "/gentle:music is not available on Windows yet: the gentle-stream player runs on macOS and Linux. It works when Gentle Shell runs inside WSL.";
 const UV_INSTALL_URL = "https://docs.astral.sh/uv/getting-started/installation/";
 const CTL_TIMEOUT_MS = 30_000;
 const SHUTDOWN_TIMEOUT_MS = 2_000;
@@ -65,8 +77,19 @@ interface TerminalOwner {
 	requestRender(force?: boolean): void;
 }
 
+/** The player a bundled Gentle Shell installs inside its prefix on request. */
+export interface BundledMusicPlayer {
+	gentleStream: string;
+	installed(): boolean;
+	install(progress: (line: string) => void): Promise<{ gentleStream: string; samples: boolean }>;
+}
+
 export interface GentleMusicDeps {
 	which?: MusicWhich;
+	/** The bundled install's player, or undefined outside a bundled install. */
+	bundled?: () => Promise<BundledMusicPlayer | undefined>;
+	/** The platform Pi runs on; gentle-stream does not run on native Windows. */
+	platform?: NodeJS.Platform;
 	spawn?: MusicSpawn;
 	signals?: MusicSignals;
 	usage?: MusicUsage;
@@ -95,10 +118,11 @@ export function findOnPath(name: string, env: NodeJS.ProcessEnv = process.env, p
 	return undefined;
 }
 
-/** gentle-stream on PATH, else the published spec through uvx, else through `uv tool run`. */
-export function resolveGentleStream(which: MusicWhich): GentleStreamCommand | undefined {
+/** gentle-stream on PATH, else the one installed inside the bundled prefix, else the published spec through uvx, else through `uv tool run`. */
+export function resolveGentleStream(which: MusicWhich, bundledPlayer?: string): GentleStreamCommand | undefined {
 	const installed = which("gentle-stream");
 	if (installed) return { command: installed, prefix: [] };
+	if (bundledPlayer) return { command: bundledPlayer, prefix: [] };
 	const uvx = which("uvx");
 	if (uvx) return { command: uvx, prefix: ["--from", GENTLE_STREAM_SPEC, "gentle-stream"] };
 	const uv = which("uv");
@@ -144,6 +168,22 @@ export function formatMusicStatus(stdout: string): string | undefined {
 	return `♪ ${[...parts, playing === true ? "playing" : "paused"].join(" · ")}`;
 }
 
+/** The running bundled install's player (GENTLE_SHELL_PREFIX, checked by runningBundledPrefix). */
+async function defaultBundled(): Promise<BundledMusicPlayer | undefined> {
+	const prefix = runningBundledPrefix(process.env);
+	if (prefix === undefined) return undefined;
+	const { installMusicPlayer, installedMusicPlayer, prefixLayout } = await import("../scripts/bundled-install.mjs");
+	const layout = prefixLayout({ platform: process.platform, env: process.env, home: homedir(), root: prefix });
+	return {
+		gentleStream: layout.gentleStream,
+		installed: () => installedMusicPlayer(layout),
+		install: async (progress) => {
+			const result = await installMusicPlayer({ layout, platform: process.platform, arch: process.arch, env: process.env, out: progress });
+			return { gentleStream: result.gentleStream, samples: result.samples };
+		},
+	};
+}
+
 const defaultSpawn: MusicSpawn = (command, args, options) => nodeSpawn(command, [...args], { stdio: options.stdio === "inherit" ? "inherit" : [...options.stdio] });
 const defaultSignals: MusicSignals = { on: (signal, listener) => process.on(signal, listener), off: (signal, listener) => process.off(signal, listener) };
 const USAGE_KEY = Symbol.for("gentle-pi.gentle-music.usage");
@@ -223,6 +263,37 @@ export default function gentleMusic(pi: ExtensionAPI, deps: GentleMusicDeps = {}
 	const signals = deps.signals ?? defaultSignals;
 	const usage = deps.usage ?? processUsage();
 	const shutdownTimeoutMs = deps.shutdownTimeoutMs ?? SHUTDOWN_TIMEOUT_MS;
+	const bundled = deps.bundled ?? defaultBundled;
+	const platform = deps.platform ?? process.platform;
+
+	const findPlayer = async (): Promise<{ stream?: GentleStreamCommand; offer?: BundledMusicPlayer }> => {
+		let player: BundledMusicPlayer | undefined;
+		try {
+			player = await bundled();
+		} catch {
+			player = undefined;
+		}
+		const stream = resolveGentleStream(which, player?.installed() ? player.gentleStream : undefined);
+		return stream ? { stream } : { offer: player };
+	};
+
+	/** The bundled offer: undefined when declined or failed (after telling the user). */
+	const offerInstall = async (ctx: ExtensionContext, player: BundledMusicPlayer): Promise<GentleStreamCommand | undefined> => {
+		if ((await ctx.ui.confirm(MUSIC_INSTALL_TITLE, MUSIC_INSTALL_OFFER)) !== true) {
+			ctx.ui.notify(installHint(), "warning");
+			return undefined;
+		}
+		try {
+			const result = await player.install((line) => ctx.ui.notify(line, "info"));
+			ctx.ui.notify(result.samples
+				? "♪ gentle-stream installed inside Gentle Shell."
+				: "♪ gentle-stream installed inside Gentle Shell without the sample voices (they need the system FluidSynth library).", "info");
+			return { command: result.gentleStream, prefix: [] };
+		} catch (error) {
+			ctx.ui.notify(`/gentle:music could not install gentle-stream: ${errorMessage(error)}`, "error");
+			return undefined;
+		}
+	};
 
 	const openTui = async (ctx: ExtensionContext, stream: GentleStreamCommand, mood: string | undefined) => {
 		const args = [...stream.prefix, ...musicTuiArgs({ model: ctx.model, mood })];
@@ -261,15 +332,19 @@ export default function gentleMusic(pi: ExtensionAPI, deps: GentleMusicDeps = {}
 		description: "Open gentle-stream full screen (optional mood text); b returns with the music playing, q stops it. next, pause, play, stop, status control the music without leaving Pi.",
 		handler: async (args, ctx) => {
 			if (!ctx.hasUI) return;
-			if (ctx.mode !== "tui") {
-				ctx.ui.notify("/gentle:music needs the interactive terminal.", "warning");
+			if (platform === "win32") {
+				ctx.ui.notify(MUSIC_WINDOWS_UNSUPPORTED, "warning");
 				return;
 			}
-			const stream = resolveGentleStream(which);
-			if (!stream) {
-				ctx.ui.notify(installHint(), "warning");
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("/gentle:music needs the interactive terminal.", "warning");
 				return;
 			}
+			const found = await findPlayer();
+			let stream = found.stream;
+			if (!stream && found.offer) stream = await offerInstall(ctx, found.offer);
+			else if (!stream) ctx.ui.notify(installHint(), "warning");
+			if (!stream) return;
 			usage.used = true;
 			const request = parseMusicArgs(args);
 			if (request.kind === "ctl") await control(ctx, stream, request.command);
@@ -281,7 +356,7 @@ export default function gentleMusic(pi: ExtensionAPI, deps: GentleMusicDeps = {}
 	// Switching or reloading sessions keeps the same process, so the music plays on.
 	pi.on("session_shutdown", async (event) => {
 		if ((event as { reason?: string }).reason !== "quit" || !usage.used) return;
-		const stream = resolveGentleStream(which);
+		const { stream } = await findPlayer();
 		if (!stream) return;
 		usage.used = false;
 		await runCaptured(spawn, stream.command, [...stream.prefix, "ctl", "stop"], shutdownTimeoutMs);

package/extensions/gentle-shell.ts

@@ -1,6 +1,6 @@
 import { CustomEditor, keyHint, type ExtensionAPI, type ExtensionContext, type KeybindingsManager } from "@earendil-works/pi-coding-agent";
 import { isHomeOrBroadUserDirectory } from "../lib/bounded-writer-admission.ts";
-import { Editor, Image, decodeKittyPrintable, getCapabilities, isKeyRelease, matchesKey, parseKey, truncateToWidth, visibleWidth, type EditorTheme, type TUI } from "@earendil-works/pi-tui";
+import { Editor, Image, decodeKittyPrintable, getCapabilities, isKeyRelease, matchesKey, parseKey, truncateToWidth, visibleWidth, type Component, type EditorTheme, type TUI } from "@earendil-works/pi-tui";
 import { readClipboardImage, type ClipboardImage } from "../lib/clipboard-image.ts";
 import { describeAttachment, ImageAttachments } from "../lib/image-attachments.ts";
 import { execFile, spawnSync } from "node:child_process";
@@ -17,7 +17,7 @@ import { CHANGE_STATUS, DIFF_MAX_BYTES, DIFF_MAX_LINES, DIFF_TOO_LARGE, Worktree
 import { WorktreeChangesView } from "../lib/shell-changes-view.ts";
 import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
 import { SessionWorktreeRegistry, resolveSessionWorktree, worktreeGitEnvironment, type WorktreeResolver, type WorktreeIdentity } from "../lib/session-worktree-registry.ts";
-import { CARD_STYLE, CARD_TONE, cardStyle, renderCard, setCardStyle, type Card, type CardTheme } from "../lib/shell-card.ts";
+import { CARD_STYLE, CARD_TONE, cardStyle, panelHeaderRow, renderCard, setCardStyle, type Card, type CardTheme } from "../lib/shell-card.ts";
 import { resolveCardStyle, writeCardStyle } from "../lib/card-style-policy.ts";
 import { CARD_CONTENT, resolveCardContent, setCardContent, writeCardContent } from "../lib/card-content-policy.ts";
 import { CommandPalette, commandsKey, type CommandPaletteResult } from "../lib/command-palette.ts";
@@ -125,7 +125,9 @@ import { sidebarHeader, sidebarPart, sidebarState, VISUAL_SETTINGS_CHANGED, type
 import { installSidebar, invalidateSidebar, narrowStatusOwner, SIDEBAR_BREAKPOINT, STATUS_OWNER } from "../lib/shell-sidebar-layout.ts";
 import { sessionChangeRoots } from "../lib/session-changes.ts";
 import { REVIEW_SIDEBAR_EVENT, isReviewSidebarSnapshot, type ReviewSidebarSnapshot } from "../lib/review-sidebar-state.ts";
-import { JOBS_SIDEBAR_EVENT, JOBS_STATUS_KEY, isJobsSidebarSnapshot, type RunningJobDisplay } from "../lib/jobs-sidebar-state.ts";
+import { JOBS_SIDEBAR_EVENT, JOBS_STATUS_KEY, isJobsSidebarSnapshot, jobsCollapseKey, type RunningJobDisplay } from "../lib/jobs-sidebar-state.ts";
+import { JOBS_FINISHED_TTL_MS, jobsCardTone, renderJobsCard } from "../lib/jobs-widget.ts";
+import { NativePointerRegion } from "../lib/native-pointer-region.ts";
 import { installSessionChangeCapture } from "../lib/session-change-capture.ts";
 import { SelectionEngine } from "../lib/selection-engine.ts";
 import { withOverlayRepaint } from "../lib/overlay-repaint.ts";
@@ -2048,6 +2050,7 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 	let currentContext: ExtensionContext | undefined;
 	let review: ReviewSidebarSnapshot | undefined;
 	let runningJobs: RunningJobDisplay[] | undefined;
+	let jobsCollapsed = false;
 	const redrawReview = () => {
 		renderHost?.invalidateSidebar?.();
 		renderHost?.requestRender();
@@ -2063,7 +2066,7 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 		const event = value as { sessionId?: unknown; snapshot?: unknown } | undefined;
 		if (!currentContext || event?.sessionId !== currentContext.sessionManager.getSessionId()) return;
 		if (!isJobsSidebarSnapshot(event.snapshot)) return;
-		runningJobs = event.snapshot.jobs.map(({ id, label, startedAt }) => ({ id, label, startedAt }));
+		runningJobs = event.snapshot.jobs.map(({ id, label, startedAt, status, endedAt, exitCode }) => ({ id, label, startedAt, status, endedAt, exitCode }));
 		redrawReview();
 	});
 	pi.on("session_tree", () => {
@@ -2156,7 +2159,9 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 				pi, ctx, footerData,
 				usage: () => usage.get(ctx.model?.provider ?? ""),
 				profile: () => deps.activeProfile(),
-				jobs: () => runningJobs,
+				// The compact bar and header derive ⧗ N jobs from model.jobs.length,
+				// so this input is running-only: the snapshot carries the finished tail.
+				jobs: () => runningJobs?.filter((job) => job.status === undefined),
 				review: () => review,
 				tracker: () => tracker,
 				visualSettings: () => visualSettings,
@@ -2194,6 +2199,68 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 				render: (width) => renderShellSidebarBar(footerModel(), theme, width, visualSettings),
 				invalidate() {},
 			});
+			// The Jobs card: its own rail section, like Agents and Todos, fed by the
+			// same running-job display snapshot the Status card used to print. The
+			// rail is natively scrollable, so it lists every running job; there is
+			// no above-editor copy — regular mode keeps the compact bar count.
+			let jobsHovered = false;
+			let jobsPainted = false;
+			let jobsHeaderRow = 0;
+			const jobsRailCard: Component = {
+				render(width: number) {
+					const jobs = runningJobs ?? [];
+					if (jobs.length === 0) { jobsPainted = false; return []; }
+					const lines = renderJobsCard(jobs, theme, width, deps.now(), { collapsed: jobsCollapsed, collapseKey: jobsKey, collapseControl: true, hovered: jobsHovered });
+					jobsPainted = lines.length > 0;
+					jobsHeaderRow = jobsPainted ? panelHeaderRow(theme, width, jobsCardTone(jobs)) : 0;
+					return lines;
+				},
+				invalidate() {
+					jobsHovered = false;
+				},
+			};
+			const jobsRegion = new NativePointerRegion(jobsRailCard, {
+				onHover(event) {
+					const next = event.y === jobsHeaderRow;
+					if (next === jobsHovered) return { handled: true };
+					jobsHovered = next;
+					return { handled: true, render: true };
+				},
+				onLeave() {
+					if (!jobsHovered) return;
+					jobsHovered = false;
+					tui.requestRender();
+				},
+				onClick(event) {
+					if (event.button !== "left" || event.y !== jobsHeaderRow) return undefined;
+					jobsCollapsed = !jobsCollapsed;
+					invalidateSidebar(tui);
+					tui.requestRender();
+					return { handled: true, render: true };
+				},
+			});
+			const jobsRail: Component & { digest(): string; dispose(): void } = {
+				digest: () => JSON.stringify([jobsCollapsed, jobsHovered, runningJobs, Math.floor(deps.now() / 1000)]),
+				render: (width) => jobsRegion.render(width),
+				handleMouse: (event) => jobsRegion.handleMouse(event),
+				invalidate() {
+					jobsRegion.invalidate();
+				},
+				dispose() {
+					jobsRegion.dispose();
+				},
+			};
+			const jobsPart = sidebarPart(tui, "jobs", { render: () => [], invalidate() {}, dispose() {} }, jobsRail);
+			// Elapsed time moves while a job runs, and a finished tail must clear
+			// itself once its TTL expires with nothing running behind it; one frame
+			// a second is enough, and the digest's second bucket revalidates the
+			// cached section.
+			const jobsTimer = setInterval(() => {
+				const now = deps.now();
+				const fresh = (runningJobs ?? []).some((job) => job.status === undefined || now - (job.endedAt ?? 0) < JOBS_FINISHED_TTL_MS);
+				if (jobsPainted || fresh) tui.requestRender();
+			}, 1_000);
+			jobsTimer.unref?.();
 			// The header row carries everything that ticks every frame (model,
 			// effort, context, cost, usage) plus session identity and the jobs count
 			// when Status is absent. Opaque statuses and working state stay excluded.
@@ -2229,15 +2296,17 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 			}), { placement: "belowEditor" });
 			return { ...part,
 				render(width: number) {
-					if (visualSettings.statusPlacement === "hidden" && (tui as TUI & { mode?: string }).mode !== "fullscreen" && runningJobs?.length) {
-						return [truncateToWidth(theme.fg("muted", shellJobsCount(runningJobs.length)), width, "…")];
+					// Running-only: a finished tail must never paint a ⧗ 0 jobs row.
+					const compactRunningJobs = runningJobs?.filter((job) => job.status === undefined);
+					if (visualSettings.statusPlacement === "hidden" && (tui as TUI & { mode?: string }).mode !== "fullscreen" && compactRunningJobs?.length) {
+						return [truncateToWidth(theme.fg("muted", shellJobsCount(compactRunningJobs.length)), width, "…")];
 					}
 					const rows = part.render(width);
 					// Preserve a shrinkable exterior dock row, outside prompt/completion geometry.
 					return rows.length === 0 && (tui as TUI & { mode?: string }).mode === "fullscreen"
 						&& resolvePromptLayout(width, cardStyle(), theme.bg?.bind(theme)).background ? [""] : rows;
 				},
-				dispose() { ctx.ui.setWidget(HEADER_WIDGET_KEY, undefined); disposeHeader(); uninstall(); part.dispose(); if (sidebarTui === tui) { sidebarTui = undefined; groupedChangesOwner = () => false; } } };
+				dispose() { clearInterval(jobsTimer); jobsPart.dispose(); ctx.ui.setWidget(HEADER_WIDGET_KEY, undefined); disposeHeader(); uninstall(); part.dispose(); if (sidebarTui === tui) { sidebarTui = undefined; groupedChangesOwner = () => false; } } };
 		});
 		void refreshUsage(ctx, true);
 		const ownsPrompt = installPrompt(
@@ -2358,6 +2427,17 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 			handler: async (ctx) => showCommandPalette(pi, ctx, env),
 		});
 	}
+	const jobsKey = jobsCollapseKey(env);
+	if (jobsKey) {
+		pi.registerShortcut(jobsKey as Parameters<ExtensionAPI["registerShortcut"]>[0], {
+			description: "Collapse or expand the jobs card",
+			handler: async () => {
+				jobsCollapsed = !jobsCollapsed;
+				if (sidebarTui) invalidateSidebar(sidebarTui);
+				renderHost?.requestRender();
+			},
+		});
+	}
 	pi.registerCommand("gentle:customize", {
 		description: "Configure appearance, audio notifications, Vim editing, session permissions and global Auto/YOLO defaults, and prompt history capture.",
 		handler: async (_args, ctx) => {

package/lib/command-palette-catalog.ts

@@ -20,8 +20,7 @@ export const COMMAND_PALETTE_CATALOG: readonly CommandPaletteCatalogGroup[] = [
 	{
 		title: "Configuration",
 		items: [
-			{ command: "gentle:models", label: "Assign models and effort" },
-			{ command: "gentle:profiles", label: "Agent-model profiles" },
+			{ command: "gentle:profiles", label: "Models and profiles" },
 			{ command: "gentle:persona", label: "Switch persona" },
 			{ command: "gentle:review-mode", label: "Review mode (receipt-driven development)" },
 			{ command: "gentle:background-subagents", label: "Background subagents" },

package/lib/gentle-shell-bundled.ts

@@ -568,6 +568,9 @@ export function withoutMissingBundledNpmCommand(settingsText: string | undefined
 export interface BundledUpdatePlan {
 	// Pi's own update was asked for: redirect it to `gentle-shell upgrade`.
 	self: boolean;
+	// `--latest` asked for the newest published Pi in place of the release's
+	// verified one (scripts/bundled-install.mjs upgradePiLatest). Only set then.
+	latest?: boolean;
 	// What Pi still runs, if anything: the extension part of `--all`, or the
 	// whole command when it never updates Pi itself.
 	piArgs?: string[];
@@ -578,7 +581,9 @@ export interface BundledUpdatePlan {
 // `update`, `--self`, or a `self`/`pi` positional, and "all" for `--all`,
 // `--self --extensions` or `self`/`pi` with `--extensions`. Only Pi's own part
 // is redirected; "all" still sends `update --extensions` (with the other
-// flags) to Pi. Packages, models, help, and forms Pi refuses (conflicting or
+// flags) to Pi. `--latest` marks Pi's own part as the newest published Pi;
+// with any form that is not Pi's own update it is unknown to Pi, so it passes
+// through. Packages, models, help, and forms Pi refuses (conflicting or
 // unknown options) reach Pi unchanged.
 export function bundledUpdatePlan(passthrough: string[]): BundledUpdatePlan {
 	const passThrough = { self: false, piArgs: passthrough };
@@ -587,8 +592,10 @@ export function bundledUpdatePlan(passthrough: string[]): BundledUpdatePlan {
 	let self = false;
 	let extensions = false;
 	let all = false;
+	let latest = false;
 	for (const token of passthrough.slice(1)) {
 		if (token === "--self") self = true;
+		else if (token === "--latest") latest = true;
 		else if (token === "--extensions") extensions = true;
 		else if (token === "--all") all = true;
 		else if (["--approve", "-a", "--no-approve", "-na", "--force"].includes(token)) flags.push(token);
@@ -600,19 +607,21 @@ export function bundledUpdatePlan(passthrough: string[]): BundledUpdatePlan {
 		if ((positional[0] !== "self" && positional[0] !== "pi") || self) return passThrough;
 		self = true;
 	}
-	if (all || (self && extensions)) return { self: true, piArgs: ["update", "--extensions", ...flags] };
+	const marked = latest ? { latest: true } : {};
+	if (all || (self && extensions)) return { self: true, ...marked, piArgs: ["update", "--extensions", ...flags] };
 	if (extensions) return passThrough;
-	return { self: true };
+	return { self: true, ...marked };
 }
 
-// What `gentle-shell update` does after the redirected upgrade (`upgradeCode`
-// is undefined when it did not run): with nothing left for Pi it exits with the
-// upgrade's code; otherwise Pi still runs, so `update --all` updates the
-// extensions even when the upgrade could not complete.
+// What `gentle-shell update` does after the redirected upgrade or the
+// `--latest` Pi update (`upgradeCode` is undefined when it did not run): with
+// nothing left for Pi it exits with that code; otherwise Pi still runs, so
+// `update --all` updates the extensions even when that step could not complete.
 export function bundledUpdateNext(plan: BundledUpdatePlan, upgradeCode: number | undefined): { exitCode: number } | { piArgs: string[]; note?: string } {
 	if (plan.piArgs === undefined) return { exitCode: upgradeCode ?? 0 };
 	if (plan.self && upgradeCode !== undefined && upgradeCode !== 0) {
-		return { piArgs: plan.piArgs, note: "gentle-shell: the Gentle Shell upgrade did not complete; updating the extensions anyway." };
+		const step = plan.latest ? "latest Pi update" : "Gentle Shell upgrade";
+		return { piArgs: plan.piArgs, note: `gentle-shell: the ${step} did not complete; updating the extensions anyway.` };
 	}
 	return { piArgs: plan.piArgs };
 }
@@ -623,6 +632,7 @@ export function bundledUpdateNotice(input: { piVersion: string; interactive: boo
 		input.interactive
 			? "Running 'gentle-shell upgrade'..."
 			: "Run 'gentle-shell upgrade' to install the latest Gentle Shell release and its Pi.",
+		"Run 'gentle-shell update --latest' to install the newest published Pi now, without the release's verified lockfile.",
 	];
 }
 

package/lib/gentle-shell-launcher.ts

@@ -1351,6 +1351,8 @@ export function helpText(): string {
 		"  gentle-shell update [target]     Run pi's own 'update' against the resolved home.",
 		"                                   In a bundled install Pi ships pinned: 'update' without a package",
 		"                                   runs 'gentle-shell upgrade' instead of updating Pi.",
+		"                                   'update --latest' installs the newest published Pi instead,",
+		"                                   without the release's verified lockfile.",
 		"  gentle-shell config              Run pi's own 'config' against the resolved home.",
 		"  gentle-shell auth <command>      Run pi's own 'auth' against the resolved home.",
 		"  gentle-shell mcp <command>       Run pi's own 'mcp' (add, list, login, logout) against the",

package/lib/jobs-sidebar-state.ts

@@ -2,10 +2,23 @@
 export const JOBS_SIDEBAR_EVENT = "gentle-ai:jobs-sidebar";
 export const JOBS_STATUS_KEY = "gentle-jobs";
 
+const COLLAPSE_KEY_DEFAULT = "ctrl+shift+j";
+
+export function jobsCollapseKey(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const value = env.GENTLE_PI_JOBS_KEY?.trim();
+	if (value === undefined) return COLLAPSE_KEY_DEFAULT;
+	return value === "" || value.toLowerCase() === "off" ? undefined : value;
+}
+
 export interface RunningJobDisplay {
 	id: string;
 	label: string;
 	startedAt: number;
+	// Finished-tail fields; optional so older publishers that only list running
+	// jobs keep validating (the Agents-card pattern: results linger briefly).
+	status?: "exited" | "stopped" | "failed";
+	endedAt?: number;
+	exitCode?: number | null;
 }
 
 export interface JobsSidebarSnapshot {
@@ -14,7 +27,13 @@ export interface JobsSidebarSnapshot {
 
 export function isJobsSidebarSnapshot(value: unknown): value is JobsSidebarSnapshot {
 	if (!value || typeof value !== "object" || !Array.isArray((value as JobsSidebarSnapshot).jobs)) return false;
-	return (value as JobsSidebarSnapshot).jobs.every((job) => job && typeof job === "object" &&
-		typeof job.id === "string" && job.id.length > 0 && typeof job.label === "string" &&
-		typeof job.startedAt === "number" && Number.isFinite(job.startedAt));
+	return (value as JobsSidebarSnapshot).jobs.every((job) => {
+		if (!job || typeof job !== "object") return false;
+		if (typeof job.id !== "string" || job.id.length === 0 || typeof job.label !== "string") return false;
+		if (typeof job.startedAt !== "number" || !Number.isFinite(job.startedAt)) return false;
+		if (job.status !== undefined && job.status !== "exited" && job.status !== "stopped" && job.status !== "failed") return false;
+		if (job.endedAt !== undefined && (typeof job.endedAt !== "number" || !Number.isFinite(job.endedAt))) return false;
+		if (job.exitCode !== undefined && typeof job.exitCode !== "number" && job.exitCode !== null) return false;
+		return true;
+	});
 }

package/lib/jobs-widget.ts

@@ -0,0 +1,112 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { JOB_GLYPH, formatJobDuration } from "./background-jobs-tools.ts";
+import type { RunningJobDisplay } from "./jobs-sidebar-state.ts";
+import { paintHoverable } from "./shell-hover.ts";
+import { CARD_TONE, panelInnerWidth, renderCard, type CardTheme, type CardTone } from "./shell-card.ts";
+import { sanitizeTerminalText } from "./terminal-theme.ts";
+
+// Gentle Jobs widget: the sidebar card for this session's background jobs.
+// Reads the running-job display snapshot only (id, label, startedAt), the same
+// data the Status card used to print, so drawing it costs nothing per event.
+// One row per job: glyph, label, elapsed right-aligned. Jobs are transient —
+// the card paints nothing while no job runs, and the overlay (/gentle:jobs)
+// stays the full view with stop controls and output tails.
+
+export const JOBS_GLYPH = JOB_GLYPH;
+
+// Finished jobs linger like the Agents card's results: newest 3 for a minute,
+// so an exit is visible long enough to read before the card empties itself.
+export const JOBS_FINISHED_TTL_MS = 60_000;
+const MAX_FINISHED = 3;
+
+export interface JobsWidgetOptions {
+	collapsed: boolean;
+	collapseKey?: string;
+	// Paint the clickable "▾ Collapse" / "▸ Expand" control in the header, the
+	// same control the Agents and Todos cards carry.
+	collapseControl?: boolean;
+	hovered?: boolean;
+}
+
+const GLYPH_ROLE = "accent";
+const NAME_ROLE = "text";
+const META_ROLE = "dim";
+const GLYPH_GAP = "  ";
+const ELLIPSIS = "…";
+
+// Running jobs newest first, matching the /gentle:jobs running group and the
+// old Status group this card replaces; finished tails follow, newest first.
+export function widgetJobs(jobs: readonly RunningJobDisplay[], now: number): RunningJobDisplay[] {
+	const running = jobs.filter((job) => job.status === undefined).sort((a, b) => b.startedAt - a.startedAt);
+	const finished = jobs.filter((job) => job.status !== undefined && now - (job.endedAt ?? 0) < JOBS_FINISHED_TTL_MS)
+		.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0)).slice(0, MAX_FINISHED);
+	return [...running, ...finished];
+}
+
+function clean(text: string): string {
+	return sanitizeTerminalText(text).replace(/\s+/g, " ");
+}
+
+function clip(text: string, width: number): string {
+	if (width <= 0) return "";
+	if (visibleWidth(text) <= width) return text;
+	// Plain clip, mirroring the status bar: pi's truncateToWidth wraps the
+	// result in resets, which would end up inside a painted segment.
+	let clipped = "";
+	for (const char of text) {
+		if (visibleWidth(clipped + char) > width - 1) break;
+		clipped += char;
+	}
+	return `${clipped}${ELLIPSIS}`;
+}
+
+// The /gentle:jobs glyph roles: running keeps the spinner, exits mirror the
+// overlay's outcome marks.
+function glyph(job: RunningJobDisplay): [string, string] {
+	if (job.status === "stopped") return ["–", "dim"];
+	if (job.status === "failed") return ["✗", "error"];
+	if (job.status === "exited") return job.exitCode === 0 ? ["✓", "success"] : ["✗", "error"];
+	return [JOBS_GLYPH, GLYPH_ROLE];
+}
+
+function counts(jobs: readonly RunningJobDisplay[]): string {
+	const running = jobs.filter((job) => job.status === undefined).length;
+	const finished = jobs.length - running;
+	const parts: string[] = [];
+	if (running > 0) parts.push(running === 1 ? "1 running" : `${running} running`);
+	if (finished > 0) parts.push(finished === 1 ? "1 finished" : `${finished} finished`);
+	return parts.join(" · ");
+}
+
+/** The tone the card paints, so a host can locate its header row. */
+export function jobsCardTone(_jobs: readonly RunningJobDisplay[]): CardTone {
+	return CARD_TONE.INFO;
+}
+
+export function renderJobsCard(jobs: readonly RunningJobDisplay[], theme: CardTheme, width: number, now: number, options: JobsWidgetOptions): string[] {
+	const shown = widgetJobs(jobs, now);
+	if (shown.length === 0) return [];
+	const tone = jobsCardTone(shown);
+	const inner = panelInnerWidth(theme, width, tone);
+	const listed = options.collapsed ? [shown[0]!] : shown;
+	const body = listed.map((job) => {
+		// A finished row freezes its elapsed at the end; a running one ticks.
+		const [mark, role] = glyph(job);
+		const elapsed = formatJobDuration(Math.max(0, (job.status === undefined ? now : job.endedAt ?? now) - job.startedAt));
+		const label = clip(clean(job.label), Math.max(0, inner - visibleWidth(elapsed) - GLYPH_GAP.length - 1));
+		const head = `${theme.fg(role, mark)}${GLYPH_GAP}${theme.fg(NAME_ROLE, label)}`;
+		const tail = theme.fg(META_ROLE, " ".repeat(Math.max(1, inner - visibleWidth(head) - visibleWidth(elapsed))) + elapsed);
+		return `${head}${tail}`;
+	});
+	if (options.collapsed && shown.length > 1) body.push(theme.fg(META_ROLE, `${ELLIPSIS} ${shown.length - 1} more`));
+	const icon = options.collapsed ? "▸" : "▾";
+	const control = `${icon} ${width >= 28 ? (options.collapsed ? "Expand" : "Collapse") : ""}`.trimEnd();
+	const title = options.collapseControl ? `Jobs ${paintHoverable(theme, control, options.hovered ?? false, "accent")}` : "Jobs";
+	const hint = options.collapsed && options.collapseKey ? `${options.collapseKey} expand` : undefined;
+	return renderCard(
+		{ title, subtitle: counts(shown), body, tone, glyph: JOBS_GLYPH },
+		theme,
+		width,
+		{ expanded: true, hint, panel: true },
+	);
+}

package/lib/session-profile-freeze.ts

@@ -252,7 +252,7 @@ export function inheritedProfileDriftNotice(options: SessionProfileOptions): str
 	if (seen.has(key)) return undefined;
 	seen.add(key);
 	notified.set(options.sessionId!, seen);
-	return `el Gentleman: the default profile changed to ${describe(current)}, this session keeps ${describe(resolution.profile)}. Press Enter on a profile in /gentle:profiles to adopt it.`;
+	return `el Gentleman: the default profile changed to ${describe(current)}, this session keeps ${describe(resolution.profile)}. Open /gentle:profiles and choose Use in this session to adopt one.`;
 }
 
 // gentle-shell#2228: an explicit binding re-copies the profile definition at
@@ -280,7 +280,7 @@ function bindingDefinitionDriftNotice(
 	if (seen.has(key)) return undefined;
 	seen.add(key);
 	notified.set(options.sessionId!, seen);
-	return `el Gentleman: the profile definition changed to "${resolution.name}" (profiles.json), this session keeps the binding from selection. Press Enter on a profile in /gentle:profiles to adopt it.`;
+	return `el Gentleman: the profile definition changed to "${resolution.name}" (profiles.json), this session keeps the binding from selection. Open /gentle:profiles and choose Use in this session to adopt one.`;
 }
 
 /** Testing-only reset of every frozen snapshot and drift memory. */

package/lib/shell-bar.ts

@@ -251,10 +251,8 @@ 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))),
-		}] : []),
+		// Running jobs live in their own sidebar card (extensions/gentle-shell.ts
+		// registers the "jobs" rail part); the compact bar keeps the count.
 		{ title: "Integrations", lines: model.statuses.length
 			? model.statuses.map((status) => theme.fg(ROLE.STATUS, sanitizeStatus(status)))
 			: [label("No status reported")] },

package/lib/shell-sidebar-layout.ts

@@ -255,7 +255,7 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme, placement: () =>
 			const preparedHeaderLines = [...(headerPart?.render(Math.max(0, width - HEADER_RIGHT_INSET)) ?? [])];
 			const headerActive = headerPart !== undefined && preparedHeaderLines.some((line) => line.trim() !== "");
 			const contentWidth = scroll.getContentWidth(RAIL_WIDTH);
-			const sections = ["footer", "agents", "todo"].filter((key) => key !== "todo" || state.visibility?.todo !== false).map((key) => {
+			const sections = ["footer", "jobs", "agents", "todo"].filter((key) => key !== "todo" || state.visibility?.todo !== false).map((key) => {
 				const component = state.parts.get(key);
 				if (!component) {
 					sectionCache.delete(key);

package/lib/vim-editor-adapter.ts

@@ -1,7 +1,7 @@
 import { CURSOR_MARKER, Editor, visibleWidth } from "@earendil-works/pi-tui";
 import { createRequire } from "node:module";
 
-// Private shape audited against @earendil-works/pi-tui 0.99.1, 0.99.2, 1.0.0, 1.1.0 and 1.2.0:
+// Private shape audited against @earendil-works/pi-tui 0.99.1, 0.99.2, 1.0.0, 1.1.0, 1.2.0, 1.3.0 and 1.4.0:
 // editor.js state/pastes/history, sticky cursor reset, layoutText/render geometry,
 // autocomplete cancellation and { state, pastes, pasteCounter } undo restoration;
 // undo-stack.js clone-on-push/pop snapshots. The two 0.99 releases ship identical
@@ -17,6 +17,7 @@ import { createRequire } from "node:module";
 // markers resolved by the host TUI (including hardware-cursor suppression).
 // Keep these markers intact and rearm selection after their reverse-off;
 // state, undo, paste, layout and autocomplete contracts remain unchanged.
+// 1.3.0 and 1.4.0 ship editor.js, undo-stack.js and keys.js byte-identical to 1.2.0.
 // Never silently adapt another build: undo also owns the paste registry.
 interface Position { line: number; col: number }
 interface State { lines: string[]; cursorLine: number; cursorCol: number }
@@ -57,7 +58,7 @@ interface PrivateEditor {
 
 // The single audited-release source for the adapter and Gentle Shell's runtime
 // identity gates. Add a release only after re-auditing the files named above.
-export const AUDITED_PI_EDITOR_VERSIONS = Object.freeze(["0.99.1", "0.99.2", "1.0.0", "1.1.0", "1.2.0"] as const);
+export const AUDITED_PI_EDITOR_VERSIONS = Object.freeze(["0.99.1", "0.99.2", "1.0.0", "1.1.0", "1.2.0", "1.3.0", "1.4.0"] as const);
 export type AuditedPiEditorVersion = (typeof AUDITED_PI_EDITOR_VERSIONS)[number];
 
 export function isAuditedPiEditorVersion(version: unknown): version is AuditedPiEditorVersion {