magus-cli 7.3.1 → 7.4.0

package/src/services/tool-probe.ts

@@ -42,7 +42,7 @@ import {
 import os from "node:os";
 import path from "node:path";
 import semver from "semver";
-import type { CliTool } from "../data/cli-tools.js";
+import { CLAUDE_CODE_NPM_PACKAGE, type CliTool } from "../data/cli-tools.js";
 import type {
 	BinInstaller,
 	BinRequirement,
@@ -50,6 +50,15 @@ import type {
 } from "../types/index.js";
 import type { Command } from "../utils/command-utils.js";
 import type { InstallMethod } from "./cli-tool-commands.js";
+import {
+	readPackageVersionForBin,
+	readVersionDirForBin,
+	versionFromVersionedPath,
+} from "./cli-tool-version.js";
+import {
+	claudeNativeUpgradeCommand,
+	npmPrefixInstallCommand,
+} from "./toolchain.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -84,6 +93,10 @@ export type ToolFactSource =
 	| "pypi"
 	| "npm-registry"
 	| "go-proxy"
+	/** the package.json of the npm/bun package the PATH binary lives in. */
+	| "package-json"
+	/** the file name of a versioned install (`…/versions/2.1.276`). */
+	| "version-dir"
 	| "check-command";
 
 export interface ToolFacts {
@@ -124,6 +137,24 @@ export interface ToolFacts {
 	 * carried to both front ends.
 	 */
 	adopted?: string;
+	/**
+	 * The command that upgrades the file PATH runs, when it differs from the
+	 * spec's own installer command. Absent otherwise — and then the ordinary
+	 * builder (`binCommandForState`, `cliToolUpdate`) is right.
+	 *
+	 * Set in two cases, both where the owner is known but is not what the spec's
+	 * installer would write to:
+	 *  - an npm global install under ANOTHER prefix than the one `npm root -g`
+	 *    reports: `npm install -g --prefix <prefix> <pkg>@<latest|pin>`;
+	 *  - Claude Code's native installer: `claude update` (`claude install <pin>`
+	 *    when pinned).
+	 *
+	 * Built here, once, and carried to both front ends — `magus update` through
+	 * its plan item, the TUI through its row — so the two run the same argv.
+	 * It already aims at the only target the classifier can plan for this spec:
+	 * the pin when there is one, the newest version otherwise.
+	 */
+	upgradeCommand?: Command;
 	/** e.g. "timed out after 8s", "registry returned 404". */
 	failure?: string;
 	/** Where each fact came from, for diagnostics. */
@@ -188,6 +219,16 @@ function withFailure(text: string, failure: string | undefined): string {
 	return failure ? `${text} (${failure})` : text;
 }
 
+/** The `not-managed` sentence. Names the file and its owner, never the version. */
+function notManagedNote(spec: BinRequirement, facts: ToolFacts): string {
+	return facts.managed === false
+		? `on PATH at ${facts.resolvedPath ?? "?"}, which ${facts.owner ?? spec.via} does not own — upgrading through ${spec.via} would install a second copy`
+		: withFailure(
+				`could not tell whether ${spec.via} owns ${facts.resolvedPath ?? spec.name}`,
+				facts.failure,
+			);
+}
+
 /**
  * THE tool classifier. Pure. The first matching rule wins, and each branch
  * returns, so reading top to bottom is reading the precedence.
@@ -198,6 +239,13 @@ function withFailure(text: string, failure: string | undefined): string {
  * held formula is a no-op. Both would be replanned forever. The pin rules that
  * plan no work (at-pin, unorderable, ahead-of-pin) come before the vetoes,
  * because ownership cannot make a "nothing to do" answer wrong.
+ *
+ * One ownership answer comes earlier still: a file KNOWN to be nobody's the
+ * spec's installer reaches (`managed === false`) is `not-managed` even when no
+ * version could be read. That is where an unreadable version usually comes
+ * from, and "does not own it" is the sentence the user can act on. The pin
+ * rules are not displaced by it — they need a version to compare, and there is
+ * none.
  */
 export function classifyTool(
 	spec: BinRequirement,
@@ -221,8 +269,23 @@ export function classifyTool(
 		};
 	}
 
-	// 2. Present, but we could not read what version runs.
+	// 2. Present, owned by nobody the spec's installer is — and no version read.
+	// The ownership answer is the actionable one: the version is unreadable
+	// BECAUSE no installer's record covers the file (and check commands are off
+	// while planning), so "could not read its version" would hide the reason.
+	// Only a DEFINITE `false`; an undetermined owner (null) is not a finding.
 	const installed = facts.installed;
+	if (installed === null && facts.managed === false) {
+		return {
+			...base,
+			state: "unknown",
+			reason: "not-managed",
+			target: null,
+			note: notManagedNote(spec, facts),
+		};
+	}
+
+	// 3. Present, but we could not read what version runs.
 	if (installed === null) {
 		return {
 			...base,
@@ -236,7 +299,7 @@ export function classifyTool(
 		};
 	}
 
-	// 3–5. Pin rules that plan no work.
+	// 4–6. Pin rules that plan no work.
 	const vsPin = pin ? compareToolVersions(installed, pin) : undefined;
 	if (pin && vsPin === 0) {
 		return { ...base, state: "current", reason: "at-pin", target: null };
@@ -261,24 +324,18 @@ export function classifyTool(
 		};
 	}
 
-	// 6. The veto: the upgrade would not replace the file PATH runs.
+	// 7. The veto: the upgrade would not replace the file PATH runs.
 	if (facts.managed !== true) {
 		return {
 			...base,
 			state: "unknown",
 			reason: "not-managed",
 			target: null,
-			note:
-				facts.managed === false
-					? `on PATH at ${facts.resolvedPath ?? "?"}, which ${facts.owner ?? spec.via} does not own — upgrading through ${spec.via} would install a second copy`
-					: withFailure(
-							`could not tell whether ${spec.via} owns ${facts.resolvedPath ?? spec.name}`,
-							facts.failure,
-						),
+			note: notManagedNote(spec, facts),
 		};
 	}
 
-	// 7. The veto: the installer will refuse to move it.
+	// 8. The veto: the installer will refuse to move it.
 	if (facts.heldBack) {
 		return {
 			...base,
@@ -289,7 +346,7 @@ export function classifyTool(
 		};
 	}
 
-	// 8–9. Pinned and behind the pin (every other pinned case returned above).
+	// 9–10. Pinned and behind the pin (every other pinned case returned above).
 	// From here on a row can plan work, so an adoption must travel with it.
 	const adopted = facts.adopted ? { adopted: facts.adopted } : {};
 	if (pin) {
@@ -312,7 +369,7 @@ export function classifyTool(
 		};
 	}
 
-	// 10–11. The owning installer's own verdict.
+	// 11–12. The owning installer's own verdict.
 	if (facts.behind === true) {
 		return {
 			...base,
@@ -329,7 +386,7 @@ export function classifyTool(
 		return { ...base, state: "current", reason: "up-to-date", target: null };
 	}
 
-	// 12. Nothing to compare against.
+	// 13. Nothing to compare against.
 	const latest = facts.latest;
 	if (latest === null) {
 		return {
@@ -341,7 +398,7 @@ export function classifyTool(
 		};
 	}
 
-	// 13. Our own comparison.
+	// 14. Our own comparison.
 	const cmp = compareToolVersions(installed, latest);
 	if (cmp === null) {
 		return {
@@ -598,6 +655,33 @@ export function isInside(resolved: string, ownerDir: string): boolean {
 	return file.startsWith(dir.endsWith(path.sep) ? dir : `${dir}${path.sep}`);
 }
 
+/**
+ * The npm prefix whose global tree holds `resolved`, read from the path alone:
+ * `<prefix>/lib/node_modules/<pkg>/…` → `<prefix>`. Null when the file is not
+ * inside that package's directory under any `lib/node_modules`.
+ *
+ * This is npm's own global layout, so it names the owner even when the npm
+ * first on PATH reports another root — one machine with nvm, Homebrew and
+ * `~/.local` Node installs has three. The package segment must be `pkg`
+ * itself: a file of some other package is not what installing `pkg` replaces.
+ *
+ * A Homebrew keg is excluded. A formula bundles its package under
+ * `Cellar/<formula>/<version>/libexec/lib/node_modules/…`, which has the same
+ * shape, but brew owns that tree; npm writing into it would leave the keg's
+ * version and its contents disagreeing.
+ */
+export function npmGlobalPrefixOf(
+	resolved: string,
+	pkg: string,
+): string | null {
+	const marker = `${path.sep}${path.join("lib", "node_modules", pkg)}${path.sep}`;
+	const at = resolved.indexOf(marker);
+	if (at < 0) return null;
+	const prefix = resolved.slice(0, at) || path.sep;
+	if (prefix.split(path.sep).includes("Cellar")) return null;
+	return prefix;
+}
+
 // ── IO seam ──────────────────────────────────────────────────────────────────
 
 export interface ExecResult {
@@ -1261,44 +1345,145 @@ async function probePip(
 	if (!pinned) await pypiLatest(s, pkg, f);
 }
 
+/** Version from the package directory, latest from the registry (unpinned only). */
+async function readNodePackage(
+	s: ProbeSession,
+	pkg: string,
+	f: ToolFacts,
+	pkgDir: string,
+	source: "bun-global" | "npm-global",
+	pinned: boolean,
+): Promise<void> {
+	f.installed = await packageJsonVersion(s.io, pkgDir);
+	if (f.installed) addSource(f, source);
+	if (!pinned) await npmLatest(s, pkg, f);
+}
+
 async function probeNodeGlobal(
 	s: ProbeSession,
 	spec: BinRequirement,
 	f: ToolFacts,
 	resolvedPath: string,
-	pinned: boolean,
 ): Promise<void> {
 	const pkg = spec.package ?? spec.name;
-	let root: string;
+	const pin = pinOf(spec);
+	const pinned = pin !== undefined;
 	if (spec.via === "bun") {
-		root = path.join(
+		const root = path.join(
 			s.io.env.BUN_INSTALL ?? path.join(s.io.homedir, ".bun"),
 			"install",
 			"global",
 			"node_modules",
 		);
 		f.owner = `bun (global ${root})`;
-	} else {
-		const npmRoot = await s.npmRoot();
+		const { inside, real } = await containedIn(
+			s,
+			resolvedPath,
+			path.join(root, pkg),
+		);
+		f.managed = inside;
+		if (inside && real)
+			await readNodePackage(s, pkg, f, real, "bun-global", pinned);
+		return;
+	}
+
+	// The root the npm first on PATH installs into.
+	const npmRoot = await s.npmRoot();
+	if ("dir" in npmRoot) {
+		f.owner = `npm (root ${npmRoot.dir})`;
+		const { inside, real } = await containedIn(
+			s,
+			resolvedPath,
+			path.join(npmRoot.dir, pkg),
+		);
+		if (inside && real) {
+			f.managed = true;
+			await readNodePackage(s, pkg, f, real, "npm-global", pinned);
+			return;
+		}
+	}
+
+	// Not under that root — but perhaps under ANOTHER npm's. The file's own
+	// path names the prefix that owns it, and `--prefix` upgrades exactly that
+	// tree, so this is npm-managed, never the "second copy" veto.
+	const prefix = npmGlobalPrefixOf(resolvedPath, pkg);
+	if (prefix === null) {
 		if ("failure" in npmRoot) {
 			f.managed = null;
 			noteFailure(f, npmRoot.failure);
-			return;
-		}
-		root = npmRoot.dir;
-		f.owner = `npm (root ${root})`;
+		} else f.managed = false;
+		return;
 	}
-	const { inside, real } = await containedIn(
-		s,
-		resolvedPath,
-		path.join(root, pkg),
-	);
-	f.managed = inside;
-	if (!inside || !real) return;
-	f.installed = await packageJsonVersion(s.io, real);
-	if (f.installed)
-		addSource(f, spec.via === "bun" ? "bun-global" : "npm-global");
-	if (!pinned) await npmLatest(s, pkg, f);
+	f.managed = true;
+	f.owner = `npm (prefix ${prefix})`;
+	// Reached with the default root only when containment could not resolve the
+	// package directory; the plain command is right then, and --prefix is noise.
+	if (!(await isNpmDefaultPrefix(s, npmRoot, prefix))) {
+		f.upgradeCommand = npmPrefixInstallCommand(prefix, pkg, pin);
+	}
+	// `resolvedPath` is already real, so every ancestor of it is too.
+	const pkgDir = path.join(prefix, "lib", "node_modules", pkg);
+	await readNodePackage(s, pkg, f, pkgDir, "npm-global", pinned);
+}
+
+/** Does `prefix` hold the global root `npm root -g` reported? False when it failed. */
+async function isNpmDefaultPrefix(
+	s: ProbeSession,
+	npmRoot: Located,
+	prefix: string,
+): Promise<boolean> {
+	if (!("dir" in npmRoot)) return false;
+	const root = path.resolve(prefix, "lib", "node_modules");
+	if (path.resolve(npmRoot.dir) === root) return true;
+	const real = await s.io.realpath(npmRoot.dir);
+	return real !== null && path.resolve(real) === root;
+}
+
+/**
+ * Claude Code's native installer keeps every release side by side under
+ * `<data>/claude/versions/<version>` and points PATH (`~/.local/bin/claude`) at
+ * one. That file is Claude Code's own, updated by `claude update`: no package
+ * manager owns it, and the npm spec the catalogue carries would only install a
+ * second copy beside it. So this runs BEFORE the spec's installer is asked.
+ *
+ * Recognised only at the installer's own directory — `~/.local/share`, or
+ * `$XDG_DATA_HOME` when set — and only for a file named by a bare release
+ * number. The version is that name; the latest is npm's `latest` dist-tag for
+ * Claude Code, the channel the native installer tracks by default.
+ *
+ * True when it recognised the layout; `f` then holds the whole answer.
+ */
+async function probeClaudeNative(
+	s: ProbeSession,
+	spec: BinRequirement,
+	f: ToolFacts,
+	resolvedPath: string,
+): Promise<boolean> {
+	// The cheap, pure shape test first, so no other tool pays for the IO below.
+	const version = versionFromVersionedPath(resolvedPath);
+	if (!version) return false;
+	const dir = path.resolve(path.dirname(resolvedPath));
+	if (path.basename(path.dirname(dir)) !== "claude") return false;
+	const dataHomes = [
+		path.join(s.io.homedir, ".local", "share"),
+		...(s.io.env.XDG_DATA_HOME ? [s.io.env.XDG_DATA_HOME] : []),
+	];
+	let owned = false;
+	for (const home of dataHomes) {
+		const versions = path.resolve(home, "claude", "versions");
+		owned = versions === dir || (await s.io.realpath(versions)) === dir;
+		if (owned) break;
+	}
+	if (!owned) return false;
+
+	const pin = pinOf(spec);
+	f.managed = true;
+	f.owner = `Claude Code's native installer (${dir})`;
+	f.installed = version;
+	addSource(f, "version-dir");
+	f.upgradeCommand = claudeNativeUpgradeCommand(pin);
+	if (pin === undefined) await npmLatest(s, CLAUDE_CODE_NPM_PACKAGE, f);
+	return true;
 }
 
 async function probeGo(
@@ -1375,6 +1560,10 @@ async function probeInto(
 	f.present = true;
 	f.resolvedPath = resolvedPath;
 
+	// A file Claude Code's native installer owns answers for itself, whatever
+	// installer the spec names.
+	if (await probeClaudeNative(s, spec, f, resolvedPath)) return;
+
 	const pinned = pinOf(spec) !== undefined;
 	const via: BinInstaller = spec.via;
 	switch (via) {
@@ -1386,18 +1575,56 @@ async function probeInto(
 			break;
 		case "bun":
 		case "npm":
-			await probeNodeGlobal(s, spec, f, resolvedPath, pinned);
+			await probeNodeGlobal(s, spec, f, resolvedPath);
 			break;
 		case "go":
 			await probeGo(s, spec, f, resolvedPath, pinned);
 			break;
 	}
 
-	// The method's own record was silent: read the running file itself — but
-	// only where the caller opted into running a check command (see there).
+	// The method's own record was silent. Before anything runs, read what the
+	// installed files already say about themselves.
+	if (f.installed === null) versionFromFiles(f, resolvedPath);
+
+	// Still nothing: read the running file itself — but only where the caller
+	// opted into running a check command (see there).
 	if (f.installed === null) await versionFromCheck(s, spec, f, onPath);
 }
 
+/**
+ * The installed version, from files next to the binary — never by running it.
+ *
+ * The method's record is keyed to where THIS spec's installer keeps things, so
+ * it is silent whenever the tool on PATH came some other way: magus installed
+ * with bun while the catalogue says npm, a pnpm or yarn global. (An npm global
+ * under another prefix and Claude Code's native installer are recognised as
+ * OWNED before this runs.) Each of those still says what it is. A binary inside
+ * `node_modules` belongs to a package whose `package.json` carries the version;
+ * a versioned install names the file after it. Neither says who OWNS the file,
+ * so `managed` is left as the method found it — the classifier still refuses to
+ * plan an upgrade it cannot land — but the row can show a version instead of
+ * "could not be read".
+ *
+ * Reads the real filesystem rather than the IO seam: `resolvedPath` already
+ * came through the seam's `realpath`, and a path a test invented does not
+ * exist, so this answers null there exactly as a missing record does.
+ */
+function versionFromFiles(f: ToolFacts, resolvedPath: string): void {
+	if (resolvedPath.split(path.sep).includes("node_modules")) {
+		const version = readPackageVersionForBin(resolvedPath);
+		if (version) {
+			f.installed = version;
+			addSource(f, "package-json");
+			return;
+		}
+	}
+	const version = readVersionDirForBin(resolvedPath);
+	if (version) {
+		f.installed = version;
+		addSource(f, "version-dir");
+	}
+}
+
 /** A copy, with the verdict fields cleared: a timed-out tool is never "behind". */
 function timedOut(f: ToolFacts, deadlineMs: number): ToolFacts {
 	return {
@@ -1568,11 +1795,10 @@ function methodFromPath(binPath: string): InstallMethod | null {
 	if (binPath.includes("/.bun/")) return "bun";
 	if (binPath.includes("/homebrew/") || binPath.includes("/Cellar/"))
 		return "brew";
-	if (
-		binPath.includes("/.local/share/claude") ||
-		binPath.includes("/.local/bin/claude")
-	)
-		return "npm";
+	// Claude Code's native installer. `~/.local/bin/claude` itself proves
+	// nothing — an npm with prefix `~/.local` links there too — so the link's
+	// target decides.
+	if (binPath.includes("/.local/share/claude/")) return "native";
 	if (binPath.includes("/.nvm/") || binPath.includes("/node_modules/"))
 		return "npm";
 	if (binPath.includes("/.local/share/pnpm") || binPath.includes("/pnpm/"))
@@ -1624,7 +1850,8 @@ export async function detectInstallMethods(
 	for (const binPath of paths) {
 		let method = methodFromPath(binPath);
 		const linkTarget = (await io.readlink(binPath)) ?? "";
-		if (!method && linkTarget) method = methodFromPath(linkTarget);
+		if (!method && linkTarget)
+			method = methodFromPath(path.resolve(path.dirname(binPath), linkTarget));
 		if (method === "brew" && !brewFormula) {
 			brewFormula = extractBrewFormula(binPath, linkTarget);
 		}

package/src/services/toolchain.ts

@@ -316,6 +316,45 @@ export function binUpgradeCommand(
 	}
 }
 
+/**
+ * npm's global install INTO one named prefix: `npm install -g --prefix <prefix>
+ * <pkg>@<version>`.
+ *
+ * For a tool whose file lives under `<prefix>/lib/node_modules/<pkg>/` when the
+ * npm first on PATH reports a different global root — several Node installs
+ * side by side (nvm, Homebrew, `~/.local`). Plain `npm install -g` would write a
+ * second copy into ITS root, which PATH never runs.
+ *
+ * `--prefix` and not "run `<prefix>/bin/npm`": npm puts a global install next
+ * to the NODE executable that runs it (or wherever an `.npmrc` `prefix` says),
+ * not next to the npm script, so the script's own location proves nothing. The
+ * flag names the tree outright.
+ */
+export function npmPrefixInstallCommand(
+	prefix: string,
+	pkg: string,
+	version = "latest",
+): Command {
+	return {
+		cmd: "npm",
+		args: ["install", "-g", "--prefix", prefix, `${pkg}@${version}`],
+	};
+}
+
+/**
+ * Claude Code's own updater, for a copy its native installer put on PATH
+ * (`~/.local/share/claude/versions/<version>`). No package manager owns that
+ * file, so `npm install -g` would only add a second copy beside it.
+ *
+ * Unpinned: `claude update`. Pinned: `claude install <pin>`, which installs
+ * exactly that native build — `claude update` would go past the pin.
+ */
+export function claudeNativeUpgradeCommand(pin?: string): Command {
+	return pin
+		? { cmd: "claude", args: ["install", pin.replace(/^v/i, "")] }
+		: { cmd: "claude", args: ["update"] };
+}
+
 /**
  * The command that moves an ALREADY-INSTALLED binary to exactly its pin.
  *

package/src/services/update-engine.ts

@@ -554,12 +554,17 @@ export async function updatePluginInScope(
  * TUI's CLI Tools row so the two front ends cannot run different commands for
  * the same row. The CLI's plan report renders this same function, so what it
  * shows is what runs.
+ *
+ * An upgrade whose probe built its own command (`item.upgradeCommand`: another
+ * npm prefix, Claude Code's updater) runs that — the value the TUI row runs.
  */
 export function binCommandFor(
 	item: BinUpdateItem,
 	spec: ResolvedBin,
 ): Command | null {
 	if (!binNeedsWork(item)) return null;
+	if (item.action === "upgrade" && item.upgradeCommand)
+		return item.upgradeCommand;
 	return binCommandForState(
 		item.action === "install" ? "install" : "upgrade",
 		item.target,

package/src/services/update-plan.ts

@@ -29,6 +29,7 @@
  */
 
 import type { ProfileSkillRef, ResolvedBin } from "../types/index.js";
+import type { Command } from "../utils/command-utils.js";
 import type { PluginScope } from "./claude-cli.js";
 import {
 	type PluginInfo,
@@ -796,6 +797,13 @@ export interface BinUpdateItem {
 	 * afterwards.
 	 */
 	adopted?: string;
+	/**
+	 * {@link ToolFacts.upgradeCommand}: the argv that upgrades the file PATH
+	 * runs when the spec's own installer would not (another npm prefix, Claude
+	 * Code's updater). An `upgrade` runs this instead of the spec's command —
+	 * the same value the TUI's row runs on Enter.
+	 */
+	upgradeCommand?: Command;
 	/** The exact pin, when the profile declares one. */
 	version?: string;
 	/** The version PATH runs, or null when absent / unreadable. */
@@ -851,6 +859,7 @@ export function planBinUpdates(
 		};
 		if (status.note) item.note = status.note;
 		if (status.adopted) item.adopted = status.adopted;
+		if (f?.upgradeCommand) item.upgradeCommand = f.upgradeCommand;
 		if (bin.version) item.version = bin.version;
 		return item;
 	});

package/src/tui.tsx

@@ -10,6 +10,7 @@
 import { RGBA, type ThemeMode, createCliRenderer } from "@opentui/core";
 import { createRoot } from "@opentui/react";
 import { App } from "./ui/App.js";
+import { installShutdown } from "./ui/runtime/shutdown.js";
 import { setThemeMode } from "./ui/theme-mode.js";
 import { type ThemeEnv, resolveTheme } from "./ui/theme-resolve.js";
 
@@ -57,6 +58,49 @@ export async function startTui({
 		backgroundColor: RGBA.defaultBackground(),
 		useMouse: true,
 		enableMouseMovement: false,
+		// BOTH, so the renderer registers no signal handler and never quits on
+		// Ctrl+C by itself: `installShutdown` below is the ONE teardown owner.
+		// Left at their defaults the renderer is a second owner — it destroys
+		// itself first on a signal and the React tree is torn down after the
+		// terminal was already restored (measured; see ui/runtime/shutdown.ts).
+		exitSignals: [],
+		exitOnCtrlC: false,
+		// OFF, so a click never gives a renderable keyboard focus. With it on, one
+		// click in a scrollbox made that box a second key receiver: OpenTUI hands
+		// every key to the focused element as well as to the KeyRouter, so arrows
+		// and PgUp/PgDn acted twice (measured on the test renderer: scrollTop 0 → 2
+		// after a click, 0 → 0 with this off). The router is the one key owner;
+		// InputModal focuses its own <input>, which is the only focus magus needs.
+		autoFocus: false,
+	});
+
+	// Wired immediately, before anything that can wait: theme resolution below
+	// can probe the terminal for 250ms, and a signal or a throw landing in that
+	// window must restore the terminal too.
+	//
+	// SIGINT/SIGTERM/SIGHUP/… restore the terminal and exit 128 + signum; an
+	// uncaught exception or unhandled rejection restores it, prints the error,
+	// and exits 1. `shutdown(0)` is the clean quit.
+	const root = createRoot(renderer);
+	const shutdown = installShutdown(renderer, root);
+	const quit = (): void => {
+		void shutdown(0);
+	};
+
+	// Ctrl+C is a KEYPRESS here, not a signal: raw mode clears ISIG, so the tty
+	// delivers 0x03 and SIGINT is never raised. Without this listener
+	// (`exitOnCtrlC: false` above) Ctrl+C would do nothing at all.
+	//
+	// It is registered on the renderer before React mounts, so it runs ahead of
+	// every `useKeyboard` handler — and stopping propagation means no screen or
+	// modal ever sees the key. That is what makes Ctrl+C quit from under any
+	// modal, including the undismissable profile gate, and from a screen whose
+	// render crashed.
+	renderer.keyInput.on("keypress", (key) => {
+		if (key.ctrl && key.name === "c") {
+			key.stopPropagation();
+			quit();
+		}
 	});
 
 	// Mouse selection → system clipboard, on release. OSC 52 survives SSH;
@@ -86,27 +130,10 @@ export async function startTui({
 	});
 	setThemeMode(mode);
 
-	const root = createRoot(renderer);
-
-	// Cleanup function to restore terminal
-	const cleanup = () => {
-		root.unmount();
-		renderer.destroy(); // CRITICAL: Never use process.exit() directly
-	};
-
-	// Handle cleanup on exit signals
-	const handleExit = () => {
-		cleanup();
-		// Exit after cleanup completes
-		process.exit(0);
-	};
-
-	process.on("SIGINT", handleExit);
-	process.on("SIGTERM", handleExit);
-
-	// Render the OpenTUI app with exit handler
-	root.render(<App onExit={handleExit} />);
+	// `q`, Escape on the home tab and the profile gate's quit all end here.
+	root.render(<App onExit={quit} />);
 
-	// Wait indefinitely (app runs until user exits)
+	// Wait indefinitely: every exit goes through `shutdown`, which ends the
+	// process itself.
 	await new Promise(() => {});
 }