gentle-pi 3.7.0 → 4.1.0

package/lib/gentle-shell-launcher.ts

@@ -1,10 +1,11 @@
-import { join, resolve as resolvePath } from "node:path";
+import { isAbsolute, join, resolve as resolvePath } from "node:path";
+import { CHILD_PACKAGE_INJECTION_ENV, encodeChildPackageInjection, type ChildPackageInjection } from "./child-package-injection.ts";
 
 // The gentle-shell launcher: pure, side-effect-free functions over injected
 // env/fs/exec. `bin/gentle-shell.mjs` (T2) wires these into the real process,
 // filesystem and child process so this module stays fully unit-testable.
 
-export type LauncherCommand = "home" | "setup";
+export type LauncherCommand = "home" | "setup" | "upgrade" | "self-uninstall";
 
 // pi's own package-management subcommands (see pi's cli/args.ts printHelp
 // "Commands" list): each is dispatched by pi itself, before pi's own flag
@@ -35,11 +36,12 @@ export interface ParsedLauncherArgs {
 	error?: string;
 }
 
-// Home-subcommand parsing is deliberately shallow: `home` only counts as the
-// subcommand when it is argv[0], and everything after it is handed over
+// Home-, upgrade- and self-uninstall-subcommand parsing is deliberately shallow:
+// each only counts as the subcommand when it is argv[0], and everything after it is handed over
 // untouched as commandArgs — T2 owns interpreting `home link|isolated|<path>`.
+// `self-uninstall` is not `uninstall`, which stays pi's own alias for `remove`.
 export function parseLauncherArgs(argv: string[]): ParsedLauncherArgs {
-	if (argv[0] === "home") {
+	if (argv[0] === "home" || argv[0] === "upgrade" || argv[0] === "self-uninstall") {
 		return {
 			link: false,
 			isolated: false,
@@ -47,7 +49,7 @@ export function parseLauncherArgs(argv: string[]): ParsedLauncherArgs {
 			packageRoot: undefined,
 			help: false,
 			version: false,
-			command: "home",
+			command: argv[0],
 			commandArgs: argv.slice(1),
 			passthrough: [],
 			piSubcommand: undefined,
@@ -188,25 +190,36 @@ export interface ResolveHomeInput {
 	config: LauncherConfig | undefined;
 }
 
-// Pi Subagents resolves `PI_CODING_AGENT_DIR || ~/.pi/agent`; `--link` reuses
-// that exact home so gentle-shell never diverges from the user's own pi.
+// Pi Subagents resolves `PI_CODING_AGENT_DIR || ~/.pi/agent`; this is the
+// user's own pi home when no Gentle Shell session is involved.
 function linkDir(env: Record<string, string | undefined>, homedir: string): string {
 	return env.PI_CODING_AGENT_DIR || join(homedir, ".pi", "agent");
 }
 
-function isolatedDir(env: Record<string, string | undefined>, homedir: string): string {
+// The isolated home replaces PI_CODING_AGENT_DIR for the whole session, so the
+// user's own Pi home travels in this variable for read-only features such as
+// /gentle:stats and for `--link`. An inherited value wins: a gentle-shell
+// launched from inside a Gentle Shell session sees the outer isolated home as
+// PI_CODING_AGENT_DIR, so `--link` must not re-select it (#2015).
+export const USER_PI_HOME_ENV = "GENTLE_SHELL_USER_PI_HOME";
+
+export function userPiHome(env: Record<string, string | undefined>, homedir: string): string {
+	return env[USER_PI_HOME_ENV] || linkDir(env, homedir);
+}
+
+export function isolatedDir(env: Record<string, string | undefined>, homedir: string): string {
 	return env.GENTLE_SHELL_HOME || join(homedir, ".gentle-shell", "agent");
 }
 
 export function resolveHome(input: ResolveHomeInput): ResolvedHome {
 	const { args, env, homedir, config } = input;
 
-	if (args.link) return { mode: "link", dir: linkDir(env, homedir), source: "flag" };
+	if (args.link) return { mode: "link", dir: userPiHome(env, homedir), source: "flag" };
 	if (args.isolated) return { mode: "isolated", dir: isolatedDir(env, homedir), source: "flag" };
 	if (args.home !== undefined) return { mode: "path", dir: args.home, source: "flag" };
 
 	if (config !== undefined) {
-		if (config.mode === "link") return { mode: "link", dir: linkDir(env, homedir), source: "config" };
+		if (config.mode === "link") return { mode: "link", dir: userPiHome(env, homedir), source: "config" };
 		if (config.mode === "isolated") return { mode: "isolated", dir: isolatedDir(env, homedir), source: "config" };
 		return { mode: "path", dir: config.dir, source: "config" };
 	}
@@ -379,7 +392,7 @@ export function missingPiMessage(): string {
 
 // --- pi version gate ---------------------------------------------------------
 
-export const MIN_PI_VERSION = "0.85.1";
+export const MIN_PI_VERSION = "0.99.1";
 
 export type PiVersionCheck = { ok: true; version: string } | { ok: false; message: string; version?: string };
 
@@ -866,6 +879,12 @@ export interface BuildPiInvocationInput {
 	// gentle-pi extension injection below may precede it.
 	piSubcommand?: PiSubcommand;
 	baseEnv: Record<string, string | undefined>;
+	// The OS home behind userPiHome's conventional ~/.pi/agent fallback.
+	homedir: string;
+	// The directory pi is spawned in, which pi resolves a relative -e path
+	// against. bin/gentle-shell.mjs spawns pi without a cwd, so this is the
+	// launcher's own process.cwd().
+	cwd: string;
 }
 
 export interface PiInvocation {
@@ -874,18 +893,11 @@ export interface PiInvocation {
 	env: Record<string, string | undefined>;
 }
 
-function packageRootAssetArgs(packageRoot: string): string[] {
-	return ["--theme", join(packageRoot, "themes"), "--skill", join(packageRoot, "skills"), "--prompt-template", join(packageRoot, "prompts")];
-}
-
-function packageRootInjectionArgs(packageRoot: string): string[] {
-	return ["-e", packageRoot, ...packageRootAssetArgs(packageRoot)];
-}
 
 // Four cases, checked in this order — `piSubcommand` first, then `takeOver`:
 //   - piSubcommand: pi dispatches install/remove/uninstall/update/list/
 //     config/auth on argv[0] before it even parses flags, so any injected
-//     -e/--theme/--skill/--prompt-template flag ahead of it stops pi from
+//     -e flag ahead of it stops pi from
 //     recognising its subcommand at all — this is exactly the observed
 //     2026-09-22 bug where `gentle-shell install npm:x` opened an
 //     interactive pi session instead of running the package manager. No
@@ -908,13 +920,21 @@ function packageRootInjectionArgs(packageRoot: string): string[] {
 //     (R3-001): a loose entry that duplicates an other-package path, or
 //     repeats within looseExtensionEntries itself, is skipped rather than
 //     loaded twice.
-//   - Not takeOver, no declaration: inject this launcher's own packageRoot,
+//   - Not takeOver, no declaration: inject this launcher's own packageRoot
+//     once via -e; Pi discovers its extensions, skills, prompts and themes,
 //     exactly as when nothing else in settings loads gentle-pi.
 //   - Not takeOver, with a declaration: no injection at all — the target
 //     settings already load a gentle-pi the launcher accepts as-is (the
 //     `--link` case with a pi-managed install matching this launcher).
+//
+// The two injecting cases also export CHILD_PACKAGE_INJECTION_ENV (#1690) so
+// the subagent runner can give delegated children the same package. It holds
+// only the launcher's own computed -e set; passthrough -e flags (the managed
+// herdr extension, or one the user typed) are not part of it. Every other case
+// removes an inherited value, so a nested launch never leaks a stale signal.
 export function buildPiInvocation(input: BuildPiInvocationInput): PiInvocation {
 	const args = [...input.runtime.args];
+	let childInjection: ChildPackageInjection | undefined;
 
 	if (input.piSubcommand !== undefined) {
 		// No injection at all: pi must see the bare subcommand as argv[0].
@@ -939,18 +959,36 @@ export function buildPiInvocation(input: BuildPiInvocationInput): PiInvocation {
 			injected.add(input.packageRoot);
 			args.push("-e", input.packageRoot);
 		}
-		args.push(...packageRootAssetArgs(input.packageRoot));
+		// The argv dedupe above compares raw strings; the signal dedupes again
+		// after absolutizing, so a relative and an absolute spelling of the same
+		// file appear once, in first-occurrence order.
+		const signalPaths = new Set([...injected].map((path) => absoluteExtensionPath(path, input.cwd)));
+		childInjection = { noExtensions: true, extensionPaths: [...signalPaths] };
 	} else if (input.declaration === undefined) {
-		args.push(...packageRootInjectionArgs(input.packageRoot));
+		args.push("-e", input.packageRoot);
+		childInjection = { noExtensions: false, extensionPaths: [absoluteExtensionPath(input.packageRoot, input.cwd)] };
 	}
 
 	args.push(...input.passthrough);
 
-	return {
-		command: input.runtime.command,
-		args,
-		env: { ...input.baseEnv, PI_CODING_AGENT_DIR: input.home.dir, GENTLE_PI_AGENT_HOME: input.home.dir },
+	const env: Record<string, string | undefined> = {
+		...input.baseEnv,
+		PI_CODING_AGENT_DIR: input.home.dir,
+		GENTLE_PI_AGENT_HOME: input.home.dir,
+		[USER_PI_HOME_ENV]: userPiHome(input.baseEnv, input.homedir),
 	};
+	if (childInjection === undefined) delete env[CHILD_PACKAGE_INJECTION_ENV];
+	else env[CHILD_PACKAGE_INJECTION_ENV] = encodeChildPackageInjection(childInjection);
+
+	return { command: input.runtime.command, args, env };
+}
+
+// pi resolves a relative -e path against its spawn cwd. Children may run
+// elsewhere, so the signal carries the same file as an absolute path. Loose
+// entries can be relative when the isolated or linked home comes from a
+// relative env value.
+function absoluteExtensionPath(path: string, cwd: string): string {
+	return isAbsolute(path) ? path : resolvePath(cwd, path);
 }
 
 // --- spawn planning ------------------------------------------------------------
@@ -1137,6 +1175,9 @@ export function helpText(): string {
 		"Usage: gentle-shell [options] [-- pi-args...]",
 		"       gentle-shell home [link|isolated|<path>]",
 		"       gentle-shell [home selectors] setup [--dry-run]",
+		"       gentle-shell upgrade [--channel release|main]",
+		"       gentle-shell upgrade --rollback",
+		"       gentle-shell self-uninstall [--dry-run] [--yes] [--include-shared]",
 		"",
 		"Opens pi with the Gentle Shell package loaded, without touching your",
 		"vanilla pi installation.",
@@ -1156,19 +1197,40 @@ export function helpText(): string {
 		"                   (runs the package-local gentle-ai 'install --agent pi --scope global').",
 		"                   Accepts --dry-run, forwarded to gentle-ai. Accepts a home selector",
 		"                   (--link, --isolated, --home <dir>) before it.",
+		"                   Warns if configured MCP servers remain disabled; never re-enables them.",
+		"  upgrade          Update Gentle Shell along its channel: the latest release, or the latest",
+		"                   main commits of Gentle Shell and Gentle AI (built locally; needs Go and",
+		"                   pnpm). --channel switches the channel first. A bundled install (the web",
+		"                   installer's own Node, pnpm and Pi) follows the release channel only:",
+		"                   it installs the new version beside the current one, verifies it, then",
+		"                   switches; --rollback switches back to the previous kept version.",
+		"  self-uninstall   Remove Gentle Shell: its own data, the isolated home and the gentle-pi",
+		"                   package. Shows the plan first and asks before removing (--yes skips",
+		"                   the question). The shared ~/.pi/gentle-ai configuration is kept unless",
+		"                   you accept or pass --include-shared; --dry-run only shows the plan.",
+		"                   Never touches your pi home or custom --home homes.",
 		"",
 		"Managing packages:",
 		"  gentle-shell install npm:<pkg>   Run pi's own 'install' against the resolved home.",
 		"  gentle-shell remove <source>     Run pi's own 'remove' against the resolved home.",
 		"  gentle-shell list                Run pi's own 'list' against the resolved home.",
 		"  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.",
 		"  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 uninstall <source>' is pi's own alias for 'remove'; to remove Gentle",
+		"  Shell itself, use 'gentle-shell self-uninstall'.",
 		"  These run pi's own commands, forwarded verbatim, against the --isolated home",
 		"  (or your own pi home with --link). Running 'gentle-shell install npm:gentle-pi'",
 		"  inside the isolated home is unnecessary: gentle-shell already loads the",
 		"  package itself.",
 		"",
+		"Bundled interactive startup:",
+		"  Before opening Pi, checks for a newer release (at most 1.5 seconds).",
+		"  Choose Update now to upgrade and reopen, Not now, or Skip this version.",
+		"  Offline, unavailable checks, commands and noninteractive runs open normally.",
+		"",
 		"Environment variables:",
 		"  GENTLE_SHELL_PI       Path to the pi executable to run.",
 		"  GENTLE_SHELL_HOME     Directory for the isolated home (default: ~/.gentle-shell/agent).",

package/lib/gentle-shell-resume-hint.ts

@@ -0,0 +1,176 @@
+// Pure logic behind the gentle-shell resume hint. On interactive quit pi
+// prints "To resume this session: pi --session <id>" (interactive-mode
+// formatResumeCommand). Under gentle-shell that command cannot find the
+// session: pi resolves sessions from PI_CODING_AGENT_DIR, which the launcher
+// points at the gentle-shell home, but the hint names the bare `pi` binary
+// and never mentions that directory, so running it looks in ~/.pi/agent.
+//
+// The clean fix belongs in pi (earendil-works/pi#8048, #9750). Until then,
+// gentle-shell appends its own line below pi's, leaving pi's output as is:
+// extensions/resume-hint.ts writes a ResumeHandoff on session_shutdown, and
+// bin/gentle-shell.mjs prints the planResumeHint line after pi exits.
+import { basename, dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
+import { shellQuote } from "./gentle-shell-launcher.ts";
+
+export const RESUME_HANDOFF_ENV = "GENTLE_SHELL_RESUME_HANDOFF";
+
+const HINT_LABEL = "To resume in gentle-shell:";
+
+// pi's assertValidSessionId charset. The handoff ends up on the terminal, so
+// anything outside it (or any C0/C1 control in a session dir) is refused
+// rather than escaped.
+const SESSION_ID_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/;
+
+// The launcher creates <tmpdir>/<RESUME_HANDOFF_DIR_PREFIX>XXXXXX/<RESUME_HANDOFF_FILE>.
+export const RESUME_HANDOFF_DIR_PREFIX = "gentle-shell-resume-";
+export const RESUME_HANDOFF_FILE = "handoff.json";
+
+// The extension only writes to a path shaped like the launcher's private
+// handoff, so an inherited or foreign env value cannot aim it at another file.
+export function isResumeHandoffPath(path: string): boolean {
+	return (
+		isAbsolute(path) &&
+		basename(path) === RESUME_HANDOFF_FILE &&
+		basename(dirname(path)).startsWith(RESUME_HANDOFF_DIR_PREFIX) &&
+		!CONTROL_CHARS.test(path)
+	);
+}
+
+export interface ResumeHandoff {
+	sessionId: string;
+	// Present only when pi would add --session-dir, i.e. the session does not
+	// live in pi's default per-cwd directory under the agent dir.
+	sessionDir?: string;
+	// Present only when the session belongs to another project than the one
+	// gentle-shell was launched from (e.g. after /resume). A bare id would
+	// then make pi offer a fork into the launch directory, while an absolute
+	// session file path reopens the original session.
+	sessionFile?: string;
+}
+
+// Mirror of pi's getDefaultSessionDirPath (core/session-manager), which pi
+// does not export. Kept byte-for-byte so usesDefaultSessionDir agrees.
+export function piDefaultSessionDir(cwd: string, agentDir: string): string {
+	const resolvedCwd = resolvePath(cwd);
+	const safePath = `--${resolvedCwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+	return join(resolvePath(agentDir), "sessions", safePath);
+}
+
+export interface SessionSnapshot {
+	sessionId: string;
+	sessionDir: string;
+	sessionFile: string | undefined;
+	cwd: string;
+	// The directory gentle-shell was launched from; pi never changes it.
+	launchCwd: string;
+	agentDir: string;
+	fileExists: (path: string) => boolean;
+}
+
+// Mirrors the guards in pi's formatResumeCommand: no hint for an
+// unpersisted session or one whose file was never written.
+export function resumeHandoffFromSession(snapshot: SessionSnapshot): ResumeHandoff | undefined {
+	const { sessionId, sessionDir, sessionFile, cwd, launchCwd, agentDir, fileExists } = snapshot;
+	if (!sessionFile || !fileExists(sessionFile)) return undefined;
+	if (resolvePath(cwd) !== resolvePath(launchCwd)) return { sessionId, sessionFile: resolvePath(sessionFile) };
+	if (sessionDir === piDefaultSessionDir(cwd, agentDir)) return { sessionId };
+	return { sessionId, sessionDir };
+}
+
+export function serializeResumeHandoff(handoff: ResumeHandoff): string {
+	return JSON.stringify(handoff);
+}
+
+// Tolerant on purpose: a missing, stale, or foreign handoff file just means
+// "print nothing".
+export function parseResumeHandoff(text: string): ResumeHandoff | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return undefined;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+	const { sessionId, sessionDir, sessionFile } = parsed as Record<string, unknown>;
+	if (typeof sessionId !== "string" || !SESSION_ID_PATTERN.test(sessionId)) return undefined;
+	if (sessionFile !== undefined) {
+		if (sessionDir !== undefined || typeof sessionFile !== "string") return undefined;
+		if (!isAbsolute(sessionFile) || !sessionFile.endsWith(".jsonl") || CONTROL_CHARS.test(sessionFile)) return undefined;
+		return { sessionId, sessionFile };
+	}
+	if (sessionDir === undefined) return { sessionId };
+	if (typeof sessionDir !== "string" || sessionDir.length === 0 || CONTROL_CHARS.test(sessionDir)) return undefined;
+	return { sessionId, sessionDir };
+}
+
+// Values that need no quoting in any shell a user might paste the hint into.
+const PLAIN_ARG = /^[A-Za-z0-9_\-.:/\\=]+$/;
+// Characters that stay live inside double quotes: cmd.exe expands %VAR% (and
+// !VAR! under delayed expansion), PowerShell expands $var and `escapes, and
+// an inner " ends the quoted argument in both. A trailing backslash would
+// escape the closing quote under the Windows argv rules. cmd.exe operators
+// are refused too: gentle-shell is installed as a .cmd shim, and PowerShell
+// drops the quotes of a space-free argument when it calls one, so cmd.exe
+// would read & | < > ^ ( ) as operators.
+const WINDOWS_UNQUOTABLE = /["%!$`&|<>^()]|\\$/;
+
+// Quotes one argument for the shell the user is likely to paste into:
+// POSIX single quotes elsewhere, double quotes on win32, where cmd.exe and
+// PowerShell do not treat single quotes as quoting. Returns undefined when
+// the value cannot be quoted safely there.
+function quoteArg(value: string, platform: NodeJS.Platform): string | undefined {
+	if (platform !== "win32") return shellQuote(value);
+	if (PLAIN_ARG.test(value)) return value;
+	if (WINDOWS_UNQUOTABLE.test(value) || CONTROL_CHARS.test(value)) return undefined;
+	return `"${value}"`;
+}
+
+// Returns the gentle-shell command that resumes the handed-off session, or
+// undefined when some argument cannot be quoted safely for the platform's
+// shell (the caller then prints no hint and leaves pi's own line alone).
+export function gentleShellResumeCommand(
+	handoff: ResumeHandoff,
+	homeFlags: string[],
+	platform: NodeJS.Platform,
+): string | undefined {
+	const values = [...homeFlags];
+	// pi treats a --session value containing a path separator as a file path
+	// and opens it directly, whatever the launch directory.
+	if (handoff.sessionFile !== undefined) {
+		values.push("--session", handoff.sessionFile);
+	} else {
+		if (handoff.sessionDir !== undefined) values.push("--session-dir", handoff.sessionDir);
+		values.push("--session", handoff.sessionId);
+	}
+	const args = ["gentle-shell"];
+	for (const value of values) {
+		const quoted = quoteArg(value, platform);
+		if (quoted === undefined) return undefined;
+		args.push(quoted);
+	}
+	return args.join(" ");
+}
+
+export interface ResumeHintInput {
+	handoff: ResumeHandoff | undefined;
+	homeFlags: string[];
+	stdoutIsTTY: boolean;
+	// True once the launcher got SIGHUP: the terminal is gone.
+	terminalHungUp: boolean;
+	platform: NodeJS.Platform;
+	// Whether stdout takes ANSI colors (NO_COLOR, FORCE_COLOR=0 and dumb
+	// terminals turn them off, as they do for pi's own dimmed label).
+	color: boolean;
+}
+
+// Returns the line to print after pi exits, or undefined to print nothing.
+// Like pi, it only prints to a TTY, and never after the terminal hung up.
+export function planResumeHint(input: ResumeHintInput): string | undefined {
+	const { handoff, homeFlags, stdoutIsTTY, terminalHungUp, platform, color } = input;
+	if (!handoff || !stdoutIsTTY || terminalHungUp) return undefined;
+	const command = gentleShellResumeCommand(handoff, homeFlags, platform);
+	if (command === undefined) return undefined;
+	const label = color ? `\u001b[2m${HINT_LABEL}\u001b[22m` : HINT_LABEL;
+	return `${label} ${command}\n`;
+}

package/lib/gentle-shell-startup-flow.ts

@@ -0,0 +1,54 @@
+import { realpathSync, readFileSync } from "node:fs";
+import { join, relative, isAbsolute } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// Resolve through the switched version, never the old launcher's captured pins.
+export async function resolveStartupRelaunch(input: {
+	root: string; home: string; platform: NodeJS.Platform; env: NodeJS.ProcessEnv; argv: string[];
+}): Promise<{ command: string; args: string[]; env: NodeJS.ProcessEnv }> {
+	const { activeVersion, prefixLayout } = await import("../scripts/bundled-install.mjs");
+	const layout = prefixLayout(input);
+	const id = activeVersion(layout);
+	if (!id) throw new Error("No active Gentle Shell after upgrade");
+	const versions = realpathSync(layout.versions);
+	const version = realpathSync(join(versions, id));
+	const inside = (root: string, file: string) => {
+		const path = relative(root, file);
+		return path !== "" && !path.startsWith("..") && !isAbsolute(path);
+	};
+	if (!inside(versions, version) || readFileSync(join(version, ".gentle-shell-version"), "utf8") !== `${id}\n`) {
+		throw new Error("Invalid active Gentle Shell version");
+	}
+	const pkg = join(version, "node_modules", "gentle-pi");
+	const modulePath = realpathSync(join(pkg, "scripts", "bundled-install.mjs"));
+	const entry = realpathSync(join(pkg, "bin", "gentle-shell.mjs"));
+	if (!inside(version, modulePath) || !inside(version, entry)) throw new Error("Active launcher escaped its version");
+	const release = await import(pathToFileURL(modulePath).href);
+	const next = release.prefixLayout(input);
+	return { command: next.node, args: [entry, ...input.argv], env: { ...input.env, GENTLE_SHELL_SKIP_STARTUP_UPDATE: "1" } };
+}
+
+// Only an explicit update selection may cross the existing upgrade boundary.
+export async function applyStartupChoice(choice: "update" | "skip" | "omit" | "cancel", effects: {
+	omit: () => void;
+	upgrade: () => Promise<number>;
+	relaunch: () => Promise<number>;
+	warn?: (message: string) => void;
+}): Promise<number | undefined> {
+	if (choice === "cancel") return 130;
+	if (choice === "omit") {
+		try { effects.omit(); }
+		catch { effects.warn?.("Could not remember the skipped release; continuing without saving."); }
+	}
+	if (choice !== "update") return undefined;
+	if (await effects.upgrade() !== 0) return undefined;
+	// A failed relaunch must not fall through to the captured old packageRoot.
+	return effects.relaunch();
+}
+
+export function omitStartupVersion(read: () => string | undefined, write: (text: string) => void, version: string): void {
+	const text = read();
+	const config = text === undefined ? {} : JSON.parse(text);
+	if (config === null || typeof config !== "object" || Array.isArray(config)) throw new Error("Invalid launcher config");
+	write(`${JSON.stringify({ ...config, skippedStartupRelease: version }, null, 2)}\n`);
+}

package/lib/gentle-shell-startup-update.ts

@@ -0,0 +1,92 @@
+import type { ParsedLauncherArgs } from "./gentle-shell-launcher.ts";
+
+export interface StartupUpdateOffer {
+	current: string;
+	latest: string;
+	notesUrl: string;
+}
+
+export interface StartupUpdateCheckOptions {
+	args: ParsedLauncherArgs;
+	env: Record<string, string | undefined>;
+	bundled: boolean;
+	inputTTY: boolean;
+	outputTTY: boolean;
+}
+
+export interface StartupUpdateLookupOptions {
+	current: string;
+	skipped?: string;
+	lookup: (signal: AbortSignal) => Promise<string | undefined>;
+	timeoutMs?: number;
+}
+
+export function shouldCheckStartupUpdate({ args, env, bundled, inputTTY, outputTTY }: StartupUpdateCheckOptions): boolean {
+	if (!bundled || !inputTTY || !outputTTY || args.command || args.piSubcommand || args.error || args.help || args.version || args.packageRoot !== undefined) {
+		return false;
+	}
+	if (env.GENTLE_PI_AGENTS_CHILD || env.PI_OFFLINE || env.GENTLE_SHELL_SKIP_STARTUP_UPDATE) {
+		return false;
+	}
+
+	// An allowlist keeps new command modes from accidentally showing a prompt.
+	for (let i = 0; i < args.passthrough.length; i += 1) {
+		const token = args.passthrough[i];
+		if (token === "--continue" || token === "-c") continue;
+		if (token.startsWith("--resume=") && token.length > "--resume=".length) continue;
+		if (token === "--resume" || token === "-r") {
+			const next = args.passthrough[i + 1];
+			if (next !== undefined && !next.startsWith("-")) i += 1;
+			continue;
+		}
+		return false;
+	}
+	return true;
+}
+
+function stableParts(version: string): string[] | undefined {
+	// No leading zeros, prefixes, whitespace, prereleases or build metadata.
+	const match = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.exec(version);
+	return match && match[0] === version ? match.slice(1) : undefined;
+}
+
+function isNewer(latest: string[], current: string[]): boolean {
+	for (let i = 0; i < 3; i += 1) {
+		if (latest[i] === current[i]) continue;
+		// Decimal string comparison avoids rounding even for arbitrarily large parts.
+		return latest[i].length !== current[i].length
+			? latest[i].length > current[i].length
+			: latest[i] > current[i];
+	}
+	return false;
+}
+
+export async function findStartupUpdate({ current, skipped, lookup, timeoutMs = 1500 }: StartupUpdateLookupOptions): Promise<StartupUpdateOffer | undefined> {
+	const currentParts = stableParts(current);
+	if (!currentParts) return undefined;
+	const controller = new AbortController();
+	const deadline = Number.isFinite(timeoutMs) && timeoutMs >= 0 && timeoutMs <= 2_147_483_647 ? timeoutMs : 1500;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		const timeout = new Promise<undefined>((resolve) => {
+			timer = setTimeout(() => {
+				resolve(undefined);
+				controller.abort();
+			}, deadline);
+		});
+		// The race bounds startup even if the injected lookup ignores cancellation.
+		const latest = await Promise.race([lookup(controller.signal), timeout]);
+		if (latest === undefined || latest === skipped) return undefined;
+		const latestParts = stableParts(latest);
+		if (!latestParts || !isNewer(latestParts, currentParts)) return undefined;
+		return {
+			current,
+			latest,
+			notesUrl: `https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v${latest}`,
+		};
+	} catch {
+		return undefined;
+	} finally {
+		clearTimeout(timer);
+	}
+}