gentle-pi 3.7.0 → 4.0.0

package/tests/gentle-shell-bin.test.ts

@@ -3,6 +3,7 @@ import { spawn, spawnSync } from "node:child_process";
 import {
 	chmodSync,
 	existsSync,
+	lstatSync,
 	mkdirSync,
 	mkdtempSync,
 	readdirSync,
@@ -29,6 +30,62 @@ const binUrl = new URL("../bin/gentle-shell.mjs", import.meta.url);
 const binPath = fileURLToPath(binUrl);
 const packageRoot = dirname(dirname(binPath));
 
+test("real adjacent Pi resolves through its public entry without PATH or a runtime override", (t) => {
+	const f = fixture(t);
+	const result = spawnSync(process.execPath, [binPath, "--version"], {
+		env: { HOME: f.home, USERPROFILE: f.home, PATH: "", GENTLE_SHELL_NO_AUTO_SETUP: "1" },
+		encoding: "utf8",
+	});
+	assert.equal(result.status, 0, result.stderr);
+	// The adjacent peer is the release the open development range resolved,
+	// not the manifest specifier.
+	const installed: string = JSON.parse(readFileSync(join(packageRoot, "node_modules", "@earendil-works", "pi-coding-agent", "package.json"), "utf8")).version;
+	assert.match(result.stdout, new RegExp(`pi ${installed.replace(/\./g, "\\.")}\\b`));
+	assert.equal(existsSync(join(f.home, ".gentle-shell", "agent")), false);
+});
+
+// A private copy places the launcher's resolution root outside this checkout,
+// so absent-peer fallback is exercised without moving any real dependency.
+function standaloneLauncher(t: test.TestContext) {
+	const f = fixture(t);
+	const root = join(f.root, "standalone");
+	mkdirSync(join(root, "bin"), { recursive: true });
+	writeFileSync(join(root, "bin", "gentle-shell.mjs"), readFileSync(binPath));
+	writeFileSync(join(root, "package.json"), readFileSync(join(packageRoot, "package.json")));
+	for (const dir of ["runtime", "scripts"]) symlinkSync(join(packageRoot, dir), join(root, dir), "junction");
+	const env = { HOME: f.home, USERPROFILE: f.home, PATH: `${root}${delimiter}${dirname(process.execPath)}`, GENTLE_SHELL_NO_AUTO_SETUP: "1" };
+	return { ...f, root, env, launcher: join(root, "bin", "gentle-shell.mjs") };
+}
+
+test("a genuinely absent adjacent peer falls back to PATH", (t) => {
+	const f = standaloneLauncher(t);
+	writePiScript(join(f.root, "pi"), "0.99.2");
+	const result = spawnSync(process.execPath, [f.launcher, "--version"], { env: f.env, encoding: "utf8" });
+	assert.equal(result.status, 0, result.stderr);
+	assert.match(result.stdout, /pi 0\.99\.2/);
+});
+
+test("malformed adjacent metadata never silently falls back to PATH; env override still wins", (t) => {
+	const f = standaloneLauncher(t);
+	const peer = join(f.root, "node_modules", "@earendil-works", "pi-coding-agent");
+	mkdirSync(join(peer, "dist", "bundle"), { recursive: true });
+	writeFileSync(join(peer, "dist", "index.js"), "");
+	writePiScript(join(peer, "dist", "bundle", "cli.js"), "0.99.1");
+	const fallback = join(f.root, "pi");
+	writePiScript(fallback, "0.99.2");
+	const base = { name: "@earendil-works/pi-coding-agent", type: "module", exports: { ".": { import: "./dist/index.js" } }, bin: { pi: "dist/bundle/cli.js" } };
+	for (const metadata of [{ ...base, name: "impostor" }, { ...base, bin: { pi: "../outside.js" } }, { ...base, bin: {} }, "malformed"]) {
+		writeFileSync(join(peer, "package.json"), metadata === "malformed" ? "{" : JSON.stringify(metadata));
+		const result = spawnSync(process.execPath, [f.launcher, "--version"], { env: f.env, encoding: "utf8" });
+		assert.equal(result.status, 1);
+		assert.equal(result.stdout, "");
+	}
+	writeFileSync(join(peer, "package.json"), JSON.stringify({ ...base, name: "impostor" }));
+	const override = spawnSync(process.execPath, [f.launcher, "--version"], { env: { ...f.env, GENTLE_SHELL_PI: fallback }, encoding: "utf8" });
+	assert.equal(override.status, 0, override.stderr);
+	assert.match(override.stdout, /pi 0\.99\.2/);
+});
+
 // The launcher's own gentle-pi version, exactly as `ownPackageVersion()` in
 // bin/gentle-shell.mjs reads it (package.json at packageRoot) — used to
 // assert the post-install gentle-pi removal message and the provisioning
@@ -50,7 +107,7 @@ function fixture(t: test.TestContext) {
 	const home = join(root, "home");
 	mkdirSync(home, { recursive: true });
 	const piScript = join(root, "fake-pi.mjs");
-	writePiScript(piScript, "0.85.1");
+	writePiScript(piScript, "0.99.1");
 	const gentleShellHome = join(root, "gentle-shell-home");
 	const env: NodeJS.ProcessEnv = {
 		...process.env,
@@ -94,6 +151,7 @@ function writePiScript(path: string, version: string, removeExitCode = 0) {
 			"  args,",
 			"  PI_CODING_AGENT_DIR: process.env.PI_CODING_AGENT_DIR,",
 			"  GENTLE_PI_AGENT_HOME: process.env.GENTLE_PI_AGENT_HOME,",
+			"  GENTLE_SHELL_USER_PI_HOME: process.env.GENTLE_SHELL_USER_PI_HOME,",
 			"}));",
 			"process.exit(0);",
 			"",
@@ -106,6 +164,133 @@ function run(env: NodeJS.ProcessEnv, args: string[], options: { cwd?: string } =
 	return spawnSync(process.execPath, [binPath, ...args], { encoding: "utf8", env, ...options });
 }
 
+// Herdr tests model terminal/socket metadata only: no socket is opened and the
+// real managed bridge is never imported. The fake pi records launch resources.
+function herdrFixture(t: test.TestContext) {
+	const f = fixture(t);
+	const bridge = join(f.home, ".pi", "agent", "extensions", "herdr-agent-state.ts");
+	mkdirSync(dirname(bridge), { recursive: true });
+	writeFileSync(bridge, "export default function () {}\n");
+	const socket = join(f.root, "mock-herdr.sock");
+	const preload = join(f.root, "terminal-and-socket.cjs");
+	writeFileSync(preload, [
+		"const fs = require('node:fs');",
+		"const { syncBuiltinESMExports } = require('node:module');",
+		"const originalStat = fs.statSync;",
+		"fs.statSync = (path, ...args) => path === process.env.HERDR_SOCKET_PATH",
+		"  ? { isSocket: () => process.env.TEST_SOCKET_VALID === '1' } : originalStat(path, ...args);",
+		"process.stdin.isTTY = process.env.TEST_STDIN_TTY === '1';",
+		"process.stdout.isTTY = process.env.TEST_STDOUT_TTY === '1';",
+		"require('node:net').createConnection = () => { throw new Error('Live socket forbidden'); };",
+		"syncBuiltinESMExports();",
+	].join("\n"));
+	const env: NodeJS.ProcessEnv = {
+		...f.env,
+		HERDR_ENV: "1", HERDR_SOCKET_PATH: socket, HERDR_PANE_ID: "mock-pane",
+		TEST_SOCKET_VALID: "1", TEST_STDIN_TTY: "1", TEST_STDOUT_TTY: "1",
+	};
+	delete env.GENTLE_PI_AGENTS_CHILD;
+	// Keep parent agent-home inheritance out of every portable test fixture.
+	delete env.PI_CODING_AGENT_DIR;
+	const launch = (args: string[] = [], overrides: NodeJS.ProcessEnv = {}) => {
+		const result = spawnSync(process.execPath, ["--require", preload, binPath, ...args], {
+			encoding: "utf8", env: { ...env, ...overrides }, cwd: f.root,
+		});
+		assert.equal(result.status, 0, result.stderr);
+		return JSON.parse(result.stdout).args as string[];
+	};
+	return { ...f, bridge, env, launch };
+}
+
+function extensionPaths(args: string[]): string[] {
+	return args.flatMap((arg, i) => arg === "-e" || arg === "--extension" ? [args[i + 1]] : []);
+}
+
+test("Herdr isolated TUI launch explicitly loads the canonical managed bridge", (t) => {
+	const f = herdrFixture(t);
+	assert.ok(extensionPaths(f.launch()).includes(realpathSync(f.bridge)));
+	assert.equal(readFileSync(f.bridge, "utf8"), "export default function () {}\n");
+});
+
+test("Herdr prefers the incoming agent-home bridge and falls back to the conventional home", (t) => {
+	const f = herdrFixture(t);
+	const previousHome = join(f.root, "previous-agent");
+	const previousBridge = join(previousHome, "extensions", "herdr-agent-state.ts");
+	mkdirSync(dirname(previousBridge), { recursive: true });
+	writeFileSync(previousBridge, "export default function () {}\n");
+	const previousPaths = extensionPaths(f.launch([], { PI_CODING_AGENT_DIR: previousHome }));
+	assert.ok(previousPaths.includes(realpathSync(previousBridge)));
+	assert.ok(!previousPaths.includes(realpathSync(f.bridge)));
+	assert.ok(extensionPaths(f.launch([], { PI_CODING_AGENT_DIR: f.gentleShellHome })).includes(realpathSync(f.bridge)));
+	const selectedBridge = join(f.gentleShellHome, "extensions", "herdr-agent-state.ts");
+	mkdirSync(dirname(selectedBridge), { recursive: true });
+	writeFileSync(selectedBridge, "export default function () {}\n");
+	const selectedPaths = extensionPaths(f.launch([], { PI_CODING_AGENT_DIR: previousHome }));
+	assert.ok(selectedPaths.includes(realpathSync(selectedBridge)));
+	assert.ok(!selectedPaths.includes(realpathSync(previousBridge)));
+	assert.ok(!selectedPaths.includes(realpathSync(f.bridge)));
+});
+
+test("Herdr bridge injection respects disabled extensions, headless modes and child launches", (t) => {
+	const f = herdrFixture(t);
+	for (const args of [["--no-extensions"], ["-ne"], ["-p", "prompt"], ["--print", "prompt"],
+		["--mode", "rpc"], ["--mode", "json"], ["--export", "session.jsonl"], ["--list-models"],
+		["--link"], ["--home", f.gentleShellHome], ["list"]]) {
+		assert.ok(!extensionPaths(f.launch(args)).includes(realpathSync(f.bridge)), JSON.stringify(args));
+	}
+	for (const overrides of [{ HERDR_ENV: "0" }, { HERDR_ENV: undefined }, { HERDR_PANE_ID: "" },
+		{ HERDR_SOCKET_PATH: "" }, { TEST_SOCKET_VALID: "0" }, { TEST_STDIN_TTY: "0" },
+		{ TEST_STDOUT_TTY: "0" }, { GENTLE_PI_AGENTS_CHILD: "1" }]) {
+		assert.ok(!extensionPaths(f.launch([], overrides)).includes(realpathSync(f.bridge)), JSON.stringify(overrides));
+	}
+	assert.ok(extensionPaths(f.launch(["--mode", "text"])).includes(realpathSync(f.bridge)));
+});
+
+test("Herdr absent bridge is nonfatal and explicit resources are preserved", (t) => {
+	const f = herdrFixture(t);
+	const absentHome = join(f.root, "empty-home");
+	mkdirSync(absentHome);
+	assert.ok(!extensionPaths(f.launch([], { HOME: absentHome, USERPROFILE: absentHome })).includes(realpathSync(f.bridge)));
+	const alias = join(f.root, "bridge-alias.ts");
+	symlinkSync(f.bridge, alias);
+	const args = f.launch(["-e", alias]);
+	assert.ok(extensionPaths(args).includes(alias));
+	assert.ok(extensionPaths(args).includes(realpathSync(f.bridge)));
+	const disabled = f.launch(["--no-extensions", "-e", alias]);
+	assert.ok(extensionPaths(disabled).includes(alias));
+	assert.ok(!extensionPaths(disabled).includes(realpathSync(f.bridge)));
+});
+
+test("Pi real resource loader deduplicates the bridge across discovery, explicit files and package directories", async (t) => {
+	const { DefaultResourceLoader, SettingsManager, createEventBus } = await import("@earendil-works/pi-coding-agent");
+	for (const scenario of ["discovered", "explicit", "directory"] as const) {
+		const f = fixture(t);
+		const agentDir = join(f.home, ".pi", "agent");
+		const bridge = join(agentDir, "extensions", "herdr-agent-state.ts");
+		mkdirSync(dirname(bridge), { recursive: true });
+		writeFileSync(bridge, "export default function (pi) { pi.events.emit('mock:bridge-loaded', {}); }\n");
+		const canonical = realpathSync(bridge);
+		const alias = join(f.root, "alias.ts");
+		symlinkSync(bridge, alias);
+		writeFileSync(join(agentDir, "package.json"), JSON.stringify({ pi: { extensions: ["./extensions/herdr-agent-state.ts"] } }));
+		const eventBus = createEventBus();
+		let factoryCalls = 0;
+		eventBus.on("mock:bridge-loaded", () => { factoryCalls++; });
+		const additionalExtensionPaths = scenario === "explicit" ? [alias, canonical, canonical]
+			: scenario === "directory" ? [agentDir, canonical] : [canonical];
+		const loader = new DefaultResourceLoader({ cwd: f.root, agentDir, eventBus,
+			settingsManager: SettingsManager.inMemory({ extensions: ["-builtin:mcp", "-builtin:llama.cpp", "-builtin:codemode", "-builtin:tool-search"] }),
+			additionalExtensionPaths, noExtensions: scenario !== "discovered", noSkills: true,
+			noPromptTemplates: true, noThemes: true, noContextFiles: true,
+		});
+		await loader.reload();
+		const loaded = loader.getExtensions();
+		assert.deepEqual(loaded.errors, [], scenario);
+		assert.equal(loaded.extensions.length, 1, scenario);
+		assert.equal(factoryCalls, 1, scenario);
+	}
+});
+
 // Test/development-only stub for the setup subcommand's gentle-ai binary:
 // records its argv and the environment gentle-shell sets around it, instead
 // of running the real package-local gentle-ai (whose supply-chain integrity
@@ -276,7 +461,7 @@ function writeGentleAiScriptDeclaringGentlePi(path: string, extraSources: string
 // the invocation), this models what a real `pi remove` does to settings.json
 // closely enough to prove a later plain launch sees the declaration gone and
 // resumes the launcher's own injection.
-function writePiScriptEditingSettingsOnRemove(path: string, version = "0.85.1") {
+function writePiScriptEditingSettingsOnRemove(path: string, version = "0.99.1") {
 	writeFileSync(
 		path,
 		[
@@ -449,12 +634,6 @@ test("forwarded args reach pi after the injected extension flags, in order", (t)
 	assert.deepEqual(payload.args, [
 		"-e",
 		packageRoot,
-		"--theme",
-		join(packageRoot, "themes"),
-		"--skill",
-		join(packageRoot, "skills"),
-		"--prompt-template",
-		join(packageRoot, "prompts"),
 		"--mode",
 		"rpc",
 		"-p",
@@ -463,6 +642,34 @@ test("forwarded args reach pi after the injected extension flags, in order", (t)
 	assert.equal(payload.GENTLE_PI_AGENT_HOME, f.gentleShellHome);
 });
 
+test("an isolated launch keeps its own agent home and carries the user's original Pi home, even when nested", (t) => {
+	const f = fixture(t);
+	const base = { ...f.env };
+	delete base.PI_CODING_AGENT_DIR;
+	delete base.GENTLE_SHELL_USER_PI_HOME;
+	const launch = (overrides: NodeJS.ProcessEnv, args: string[] = []) => {
+		const result = run({ ...base, ...overrides }, [...args, "--mode", "rpc"]);
+		assert.equal(result.status, 0, result.stderr);
+		return JSON.parse(result.stdout);
+	};
+	const conventional = launch({});
+	assert.equal(conventional.PI_CODING_AGENT_DIR, f.gentleShellHome);
+	assert.equal(conventional.GENTLE_SHELL_USER_PI_HOME, join(f.home, ".pi", "agent"));
+	const customHome = join(f.root, "custom-pi");
+	const custom = launch({ PI_CODING_AGENT_DIR: customHome });
+	assert.equal(custom.PI_CODING_AGENT_DIR, f.gentleShellHome);
+	assert.equal(custom.GENTLE_PI_AGENT_HOME, f.gentleShellHome);
+	assert.equal(custom.GENTLE_SHELL_USER_PI_HOME, customHome);
+	// A gentle-shell started from inside a Gentle Shell session inherits both variables.
+	const nested = launch({ PI_CODING_AGENT_DIR: custom.PI_CODING_AGENT_DIR, GENTLE_SHELL_USER_PI_HOME: custom.GENTLE_SHELL_USER_PI_HOME });
+	assert.equal(nested.PI_CODING_AGENT_DIR, f.gentleShellHome);
+	assert.equal(nested.GENTLE_SHELL_USER_PI_HOME, customHome);
+	const linked = launch({ PI_CODING_AGENT_DIR: customHome }, ["--link"]);
+	assert.equal(linked.PI_CODING_AGENT_DIR, customHome);
+	assert.equal(linked.GENTLE_SHELL_USER_PI_HOME, customHome);
+	assert.equal(existsSync(join(customHome, "sessions")), false);
+});
+
 test("--link skips injection and leaves settings.json byte-identical when it already declares gentle-pi", (t) => {
 	const f = fixture(t);
 	const piAgentDir = join(f.root, "pi-agent");
@@ -511,12 +718,6 @@ test("an isolated home whose settings.json does not declare gentle-pi keeps the
 	assert.deepEqual(payload.args, [
 		"-e",
 		packageRoot,
-		"--theme",
-		join(packageRoot, "themes"),
-		"--skill",
-		join(packageRoot, "skills"),
-		"--prompt-template",
-		join(packageRoot, "prompts"),
 		"--mode",
 		"rpc",
 	]);
@@ -538,12 +739,6 @@ test("an isolated home whose settings.json declares a path-based gentle-pi takes
 		"--no-extensions",
 		"-e",
 		packageRoot,
-		"--theme",
-		join(packageRoot, "themes"),
-		"--skill",
-		join(packageRoot, "skills"),
-		"--prompt-template",
-		join(packageRoot, "prompts"),
 		"--mode",
 		"rpc",
 	]);
@@ -573,7 +768,7 @@ test("a too-old pi exits 1 naming both versions", (t) => {
 	const result = run(f.env, []);
 	assert.equal(result.status, 1);
 	assert.match(result.stderr, /0\.80\.0/);
-	assert.match(result.stderr, /0\.85\.1/);
+	assert.match(result.stderr, /0\.99\.1/);
 });
 
 test("--version prints three lines", (t) => {
@@ -583,7 +778,7 @@ test("--version prints three lines", (t) => {
 	const lines = result.stdout.trim().split("\n");
 	assert.equal(lines.length, 3);
 	assert.match(lines[0], /^gentle-shell /);
-	assert.match(lines[1], /^pi 0\.85\.1$/);
+	assert.match(lines[1], /^pi 0\.99\.1$/);
 	assert.match(lines[2], /^home isolated /);
 });
 
@@ -904,12 +1099,6 @@ test("a later normal launch injects the launcher's own package root once gentle-
 	assert.deepEqual(payload.args, [
 		"-e",
 		packageRoot,
-		"--theme",
-		join(packageRoot, "themes"),
-		"--skill",
-		join(packageRoot, "skills"),
-		"--prompt-template",
-		join(packageRoot, "prompts"),
 		"--mode",
 		"rpc",
 	]);
@@ -920,7 +1109,7 @@ test("gentle-shell setup propagates a non-zero pi remove exit code with an actio
 	const gentleAiScript = join(f.root, "fake-gentle-ai.mjs");
 	writeGentleAiScriptDeclaringConflict(gentleAiScript);
 	const failingPiScript = join(f.root, "fake-pi-remove-fails.mjs");
-	writePiScript(failingPiScript, "0.85.1", 7);
+	writePiScript(failingPiScript, "0.99.1", 7);
 	const env = { ...f.env, GENTLE_SHELL_GENTLE_AI_BIN: gentleAiScript, GENTLE_SHELL_PI: failingPiScript };
 
 	const result = run(env, ["setup"]);
@@ -941,7 +1130,7 @@ test("gentle-shell setup --home <dir> includes --home <dir> in the failing-remov
 	const gentleAiScript = join(f.root, "fake-gentle-ai.mjs");
 	writeGentleAiScriptDeclaringConflict(gentleAiScript);
 	const failingPiScript = join(f.root, "fake-pi-remove-fails.mjs");
-	writePiScript(failingPiScript, "0.85.1", 7);
+	writePiScript(failingPiScript, "0.99.1", 7);
 	const env = { ...f.env, GENTLE_SHELL_GENTLE_AI_BIN: gentleAiScript, GENTLE_SHELL_PI: failingPiScript };
 
 	const result = run(env, ["--home", target, "setup"]);
@@ -965,7 +1154,7 @@ test("gentle-shell setup shell-quotes a --home path containing a space in the fa
 	const gentleAiScript = join(f.root, "fake-gentle-ai.mjs");
 	writeGentleAiScriptDeclaringConflict(gentleAiScript);
 	const failingPiScript = join(f.root, "fake-pi-remove-fails.mjs");
-	writePiScript(failingPiScript, "0.85.1", 7);
+	writePiScript(failingPiScript, "0.99.1", 7);
 	const env = { ...f.env, GENTLE_SHELL_GENTLE_AI_BIN: gentleAiScript, GENTLE_SHELL_PI: failingPiScript };
 
 	const result = run(env, ["--home", target, "setup"]);
@@ -1493,7 +1682,8 @@ test("a --home equal to pi's own default agent home is never auto-provisioned, e
 	const gentleAiScript = join(f.root, "fake-gentle-ai.mjs");
 	const counterPath = join(f.root, "gentle-ai-runs.log");
 	writeGentleAiScriptCountingRuns(gentleAiScript, counterPath);
-	const env = enableAutoProvision({ ...f.env, GENTLE_SHELL_GENTLE_AI_BIN: gentleAiScript, GENTLE_SHELL_GENTLE_AI_PIN: "3.6.0" });
+	// Exercise the default Pi home, not an ambient PI_CODING_AGENT_DIR override.
+	const env = enableAutoProvision({ ...f.env, PI_CODING_AGENT_DIR: undefined, GENTLE_SHELL_GENTLE_AI_BIN: gentleAiScript, GENTLE_SHELL_GENTLE_AI_PIN: "3.6.0" });
 
 	const result = run(env, ["--home", defaultPiHome, "--mode", "rpc"]);
 	assert.equal(result.status, 0, result.stderr);
@@ -1737,7 +1927,7 @@ test("a hung 'pi remove' during post-install cleanup is killed after the timeout
 		[
 			"#!/usr/bin/env node",
 			"const args = process.argv.slice(2);",
-			'if (args.includes("--version")) { console.log("0.85.1"); process.exit(0); }',
+			'if (args.includes("--version")) { console.log("0.99.1"); process.exit(0); }',
 			"if (args[0] === 'remove') { await new Promise((resolve) => setTimeout(resolve, 60000)); process.exit(0); }",
 			"console.log(JSON.stringify({ args, PI_CODING_AGENT_DIR: process.env.PI_CODING_AGENT_DIR }));",
 			"process.exit(0);",
@@ -1882,6 +2072,253 @@ test("automatic setup restores the home's own theme when gentle-ai overwrites it
 	assert.equal(settings.theme, "dracula");
 });
 
+// --- builtin codemode exclusion ----------------------------------------------
+//
+// gentle-pi registers its own decorated codemode tool, so Pi's replaceable
+// builtin codemode always loses to it and Pi prints a startup warning. The
+// only per-builtin opt-out Pi supports is a `-builtin:codemode` entry in the
+// settings `extensions` array, which every normal launch ensures in a home
+// gentle-shell owns — never in --link, a foreign --home, pi's own default
+// agent home, a pi subcommand, or `setup --dry-run`.
+
+const CODEMODE_EXCLUSION = "-builtin:codemode";
+
+function settingsText(dir: string): string {
+	return readFileSync(join(dir, "settings.json"), "utf8");
+}
+
+test("a fresh isolated home excludes Pi's builtin codemode, and a second launch changes nothing", (t) => {
+	const f = fixture(t);
+	const first = run(f.env, ["--mode", "rpc"]);
+	assert.equal(first.status, 0, first.stderr);
+	const settings = JSON.parse(settingsText(f.gentleShellHome));
+	assert.deepEqual(settings.extensions, [CODEMODE_EXCLUSION]);
+	assert.equal(settings.tuiMode, "fullscreen");
+	assert.equal(settings.theme, "Gentleman-Cute");
+
+	const before = settingsText(f.gentleShellHome);
+	const second = run(f.env, ["--mode", "rpc"]);
+	assert.equal(second.status, 0, second.stderr);
+	assert.equal(settingsText(f.gentleShellHome), before);
+	assert.doesNotMatch(second.stderr, /builtin codemode/);
+});
+
+test("an existing isolated home gains the exclusion after its own extension entries, keeping every other key and its formatting", (t) => {
+	for (const [indent, newline] of [[4, "\n"], [undefined, ""]] as const) {
+		const f = fixture(t);
+		mkdirSync(f.gentleShellHome, { recursive: true });
+		const original = { tuiMode: "fullscreen", theme: "rose", extensions: ["./ext/a.ts", "!./ext/b.ts"], packages: ["npm:pi-btw"] };
+		writeFileSync(join(f.gentleShellHome, "settings.json"), `${JSON.stringify(original, null, indent)}${newline}`);
+
+		const result = run(f.env, ["--mode", "rpc"]);
+		assert.equal(result.status, 0, result.stderr);
+		const expected = { ...original, extensions: [...original.extensions, CODEMODE_EXCLUSION] };
+		assert.equal(settingsText(f.gentleShellHome), `${JSON.stringify(expected, null, indent)}${newline}`);
+		assert.match(result.stderr, /builtin codemode/);
+	}
+});
+
+test("an explicit user entry for builtin:codemode is left byte-identical", (t) => {
+	for (const entry of ["+builtin:codemode", "!builtin:codemode", "builtin:codemode", CODEMODE_EXCLUSION]) {
+		const f = fixture(t);
+		mkdirSync(f.gentleShellHome, { recursive: true });
+		const text = JSON.stringify({ tuiMode: "fullscreen", extensions: ["./ext/a.ts", entry] });
+		writeFileSync(join(f.gentleShellHome, "settings.json"), text);
+
+		const result = run(f.env, ["--mode", "rpc"]);
+		assert.equal(result.status, 0, result.stderr);
+		assert.equal(settingsText(f.gentleShellHome), text, entry);
+	}
+});
+
+test("a malformed or unexpected settings.json is never overwritten and pi still starts", (t) => {
+	for (const text of ["{ not json", "[]", '{"extensions":"oops"}']) {
+		const f = fixture(t);
+		mkdirSync(f.gentleShellHome, { recursive: true });
+		writeFileSync(join(f.gentleShellHome, "settings.json"), text);
+
+		const result = run(f.env, ["--mode", "rpc"]);
+		assert.equal(result.status, 0, result.stderr);
+		assert.deepEqual(JSON.parse(result.stdout).args.slice(-2), ["--mode", "rpc"]);
+		assert.equal(settingsText(f.gentleShellHome), text);
+	}
+});
+
+test("an owned home without settings.json is not given one", (t) => {
+	const f = fixture(t);
+	mkdirSync(f.gentleShellHome, { recursive: true });
+	const result = run(f.env, ["--mode", "rpc"]);
+	assert.equal(result.status, 0, result.stderr);
+	assert.equal(existsSync(join(f.gentleShellHome, "settings.json")), false);
+});
+
+test("--link never gains the exclusion", (t) => {
+	const f = fixture(t);
+	const piAgentDir = join(f.root, "pi-agent-link");
+	mkdirSync(piAgentDir, { recursive: true });
+	const text = JSON.stringify({ tuiMode: "fullscreen" });
+	writeFileSync(join(piAgentDir, "settings.json"), text);
+
+	const result = run({ ...f.env, PI_CODING_AGENT_DIR: piAgentDir }, ["--link", "--mode", "rpc"]);
+	assert.equal(result.status, 0, result.stderr);
+	assert.equal(settingsText(piAgentDir), text);
+});
+
+test("a foreign --home and pi's own default agent home are never edited, while a bootstrapped --home is", (t) => {
+	const f = fixture(t);
+	const foreign = join(f.root, "existing-pi-home");
+	const defaultPiHome = join(f.home, ".pi", "agent");
+	const text = JSON.stringify({ tuiMode: "fullscreen" });
+	for (const dir of [foreign, defaultPiHome]) {
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(join(dir, "settings.json"), text);
+		const result = run({ ...f.env, PI_CODING_AGENT_DIR: undefined }, ["--home", dir, "--mode", "rpc"]);
+		assert.equal(result.status, 0, result.stderr);
+		assert.equal(settingsText(dir), text, dir);
+	}
+
+	const bootstrapped = join(f.root, "brand-new-home");
+	const result = run(f.env, ["--home", bootstrapped, "--mode", "rpc"]);
+	assert.equal(result.status, 0, result.stderr);
+	assert.deepEqual(JSON.parse(settingsText(bootstrapped)).extensions, [CODEMODE_EXCLUSION]);
+});
+
+test("a pi subcommand and setup --dry-run never edit the home's settings", (t) => {
+	const f = fixture(t);
+	mkdirSync(f.gentleShellHome, { recursive: true });
+	const text = JSON.stringify({ tuiMode: "fullscreen" });
+	writeFileSync(join(f.gentleShellHome, "settings.json"), text);
+	const gentleAiScript = join(f.root, "fake-gentle-ai.mjs");
+	writeGentleAiScript(gentleAiScript);
+	const env = { ...f.env, GENTLE_SHELL_GENTLE_AI_BIN: gentleAiScript };
+
+	for (const args of [["list"], ["setup", "--dry-run"]]) {
+		const result = run(env, args);
+		assert.equal(result.status, 0, result.stderr);
+		assert.equal(settingsText(f.gentleShellHome), text, args.join(" "));
+	}
+});
+
+test("the exclusion is ensured after automatic setup rewrites settings.json", (t) => {
+	const f = fixture(t);
+	const gentleAiScript = join(f.root, "fake-gentle-ai-drops-extensions.mjs");
+	writeFileSync(
+		gentleAiScript,
+		[
+			"#!/usr/bin/env node",
+			"import { readFileSync, writeFileSync } from 'node:fs';",
+			"import { join } from 'node:path';",
+			"const settingsPath = join(process.env.PI_CODING_AGENT_DIR, 'settings.json');",
+			"const { extensions, ...settings } = JSON.parse(readFileSync(settingsPath, 'utf8'));",
+			"writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\\n');",
+			"process.exit(0);",
+			"",
+		].join("\n"),
+	);
+	chmodSync(gentleAiScript, 0o755);
+	mkdirSync(f.gentleShellHome, { recursive: true });
+	writeFileSync(join(f.gentleShellHome, "settings.json"), `${JSON.stringify({ tuiMode: "fullscreen", extensions: [CODEMODE_EXCLUSION] }, null, 2)}\n`);
+	const env = enableAutoProvision({ ...f.env, GENTLE_SHELL_GENTLE_AI_BIN: gentleAiScript, GENTLE_SHELL_GENTLE_AI_PIN: "3.6.0" });
+
+	const result = run(env, ["--mode", "rpc"]);
+	assert.equal(result.status, 0, result.stderr);
+	assert.deepEqual(JSON.parse(settingsText(f.gentleShellHome)).extensions, [CODEMODE_EXCLUSION]);
+});
+
+// --- atomic writes keep symlinked config files intact ------------------------
+//
+// Dotfile managers (Nix home-manager, stow, ...) ship settings.json and
+// config.json as symlinks. Every atomic launcher write must rename onto the
+// link's real target, so the link survives and the target gets the new
+// bytes with its own permission bits.
+
+// File symlinks need extra privileges on Windows; skip where unavailable.
+const fileSymlinkSkip = (() => {
+	const dir = mkdtempSync(join(tmpdir(), "gentle-shell-symlink-probe-"));
+	try {
+		writeFileSync(join(dir, "target"), "");
+		symlinkSync(join(dir, "target"), join(dir, "link"), "file");
+		return false;
+	} catch {
+		return "file symlinks are unavailable here";
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+})();
+
+function symlinkedFile(linkPath: string, targetPath: string, text: string, mode: number) {
+	mkdirSync(dirname(linkPath), { recursive: true });
+	mkdirSync(dirname(targetPath), { recursive: true });
+	writeFileSync(targetPath, text);
+	chmodSync(targetPath, mode);
+	symlinkSync(targetPath, linkPath, "file");
+}
+
+function assertStillLinkedTo(linkPath: string, targetPath: string, mode: number) {
+	assert.ok(lstatSync(linkPath).isSymbolicLink(), `${linkPath} is still a symlink`);
+	assert.equal(realpathSync(linkPath), realpathSync(targetPath));
+	if (process.platform !== "win32") assert.equal(statSync(targetPath).mode & 0o777, mode);
+	for (const dir of [dirname(linkPath), dirname(targetPath)]) {
+		assert.deepEqual(readdirSync(dir).filter((name) => name.endsWith(".tmp")), [], `no temp file left in ${dir}`);
+	}
+}
+
+test("the builtin codemode exclusion writes through a symlinked settings.json", { skip: fileSymlinkSkip }, (t) => {
+	const f = fixture(t);
+	const linkPath = join(f.gentleShellHome, "settings.json");
+	const targetPath = join(f.root, "dotfiles", "settings.json");
+	symlinkedFile(linkPath, targetPath, JSON.stringify({ tuiMode: "fullscreen", theme: "rose" }), 0o640);
+
+	const result = run(f.env, ["--mode", "rpc"]);
+	assert.equal(result.status, 0, result.stderr);
+	assertStillLinkedTo(linkPath, targetPath, 0o640);
+	assert.deepEqual(JSON.parse(readFileSync(targetPath, "utf8")), { tuiMode: "fullscreen", theme: "rose", extensions: [CODEMODE_EXCLUSION] });
+});
+
+test("the automatic setup theme restore writes through a symlinked settings.json", { skip: fileSymlinkSkip }, (t) => {
+	const f = fixture(t);
+	const target = join(f.root, "linked-themed-home");
+	const linkPath = join(target, "settings.json");
+	const targetPath = join(f.root, "dotfiles", "themed-settings.json");
+	symlinkedFile(linkPath, targetPath, JSON.stringify({ tuiMode: "fullscreen", theme: "dracula" }), 0o600);
+	writeFileSync(join(target, ".gentle-shell-home"), JSON.stringify({ createdBy: "gentle-shell", version: ownGentlePiVersion() }));
+
+	const gentleAiScript = join(f.root, "fake-gentle-ai-sets-theme.mjs");
+	writeGentleAiScriptSettingTheme(gentleAiScript, "kanagawa");
+	const env = enableAutoProvision({ ...f.env, GENTLE_SHELL_GENTLE_AI_BIN: gentleAiScript, GENTLE_SHELL_GENTLE_AI_PIN: "3.6.0" });
+
+	const result = run(env, ["--home", target, "--mode", "rpc"]);
+	assert.equal(result.status, 0, result.stderr);
+	assertStillLinkedTo(linkPath, targetPath, 0o600);
+	assert.equal(JSON.parse(readFileSync(targetPath, "utf8")).theme, "dracula");
+});
+
+test("'home' persistence writes through a symlinked config.json", { skip: fileSymlinkSkip }, (t) => {
+	const f = fixture(t);
+	const linkPath = join(f.root, "config", "config.json");
+	const targetPath = join(f.root, "dotfiles", "config.json");
+	symlinkedFile(linkPath, targetPath, "{}\n", 0o600);
+
+	const result = run({ ...f.env, GENTLE_SHELL_CONFIG: linkPath }, ["home", "link"]);
+	assert.equal(result.status, 0, result.stderr);
+	assertStillLinkedTo(linkPath, targetPath, 0o600);
+	assert.deepEqual(JSON.parse(readFileSync(targetPath, "utf8")), { home: "link" });
+});
+
+test("a dangling config.json symlink is replaced in place, never followed to create its target", { skip: fileSymlinkSkip }, (t) => {
+	const f = fixture(t);
+	const linkPath = join(f.root, "config", "config.json");
+	const missingTarget = join(f.root, "missing", "config.json");
+	mkdirSync(dirname(linkPath), { recursive: true });
+	symlinkSync(missingTarget, linkPath, "file");
+
+	const result = run({ ...f.env, GENTLE_SHELL_CONFIG: linkPath }, ["home", "link"]);
+	assert.equal(result.status, 0, result.stderr);
+	assert.equal(lstatSync(linkPath).isSymbolicLink(), false);
+	assert.deepEqual(JSON.parse(readFileSync(linkPath, "utf8")), { home: "link" });
+	assert.equal(existsSync(dirname(missingTarget)), false);
+});
+
 // --- --package-root silently ignored in a declared non-link home ----------
 
 test("--package-root warns and is ignored when an isolated home already declares gentle-pi", (t) => {
@@ -1963,12 +2400,6 @@ test("--link takes over a path-declared conflicting gentle-pi: --no-extensions,
 		join(piAgentDir, "npm", "node_modules", "some-other"),
 		"-e",
 		packageRoot,
-		"--theme",
-		join(packageRoot, "themes"),
-		"--skill",
-		join(packageRoot, "skills"),
-		"--prompt-template",
-		join(packageRoot, "prompts"),
 		"--mode",
 		"rpc",
 	]);
@@ -2019,7 +2450,7 @@ test("--link does not take over a git-sourced other package: it is skipped with
 	assert.match(result.stderr, /skipping git-sourced package/);
 
 	const payload = JSON.parse(result.stdout);
-	assert.deepEqual(payload.args, ["--no-extensions", "-e", packageRoot, "--theme", join(packageRoot, "themes"), "--skill", join(packageRoot, "skills"), "--prompt-template", join(packageRoot, "prompts")]);
+	assert.deepEqual(payload.args, ["--no-extensions", "-e", packageRoot]);
 });
 
 test("--package-root forces a takeover even when settings already declare a matching npm:gentle-pi", (t) => {
@@ -2039,17 +2470,7 @@ test("--package-root forces a takeover even when settings already declare a matc
 	assert.match(result.stderr, /taking over gentle-pi from npm:gentle-pi/);
 
 	const payload = JSON.parse(result.stdout);
-	assert.deepEqual(payload.args, [
-		"--no-extensions",
-		"-e",
-		forcedRoot,
-		"--theme",
-		join(forcedRoot, "themes"),
-		"--skill",
-		join(forcedRoot, "skills"),
-		"--prompt-template",
-		join(forcedRoot, "prompts"),
-	]);
+	assert.deepEqual(payload.args, ["--no-extensions", "-e", forcedRoot]);
 	assert.equal(readFileSync(settingsPath, "utf8"), settingsText);
 });
 
@@ -2079,12 +2500,6 @@ test("--package-root forces a takeover even with no gentle-pi declaration at all
 		join(piAgentDir, "npm", "node_modules", "some-other"),
 		"-e",
 		forcedRoot,
-		"--theme",
-		join(forcedRoot, "themes"),
-		"--skill",
-		join(forcedRoot, "skills"),
-		"--prompt-template",
-		join(forcedRoot, "prompts"),
 	]);
 	assert.equal(readFileSync(settingsPath, "utf8"), settingsText);
 });
@@ -2117,12 +2532,6 @@ test("--link take-over with --package-root injects exactly one -e when a setting
 		"--no-extensions",
 		"-e",
 		realOtherDir,
-		"--theme",
-		join(realOtherDir, "themes"),
-		"--skill",
-		join(realOtherDir, "skills"),
-		"--prompt-template",
-		join(realOtherDir, "prompts"),
 	]);
 });
 
@@ -2189,12 +2598,6 @@ test("--link take-over re-injects loose extension files, one -e per discovered f
 		join(resolvedLooseProjectExtensions, "project-ext.mjs"),
 		"-e",
 		packageRoot,
-		"--theme",
-		join(packageRoot, "themes"),
-		"--skill",
-		join(packageRoot, "skills"),
-		"--prompt-template",
-		join(packageRoot, "prompts"),
 		"--mode",
 		"rpc",
 	]);
@@ -2234,12 +2637,6 @@ test("--link take-over injects a root-level index.ts as its own loose file entry
 		join(looseAgentExtensions, "index.ts"),
 		"-e",
 		packageRoot,
-		"--theme",
-		join(packageRoot, "themes"),
-		"--skill",
-		join(packageRoot, "skills"),
-		"--prompt-template",
-		join(packageRoot, "prompts"),
 	]);
 });
 
@@ -2270,12 +2667,6 @@ test("--link take-over injects a subdirectory's own index.ts entry point even wh
 		join(subDir, "index.ts"),
 		"-e",
 		packageRoot,
-		"--theme",
-		join(packageRoot, "themes"),
-		"--skill",
-		join(packageRoot, "skills"),
-		"--prompt-template",
-		join(packageRoot, "prompts"),
 	]);
 });
 
@@ -2295,7 +2686,7 @@ test("--link take-over omits -e flags for loose extension dirs that do not exist
 	assert.equal(result.status, 0, result.stderr);
 
 	const payload = JSON.parse(result.stdout);
-	assert.deepEqual(payload.args, ["--no-extensions", "-e", packageRoot, "--theme", join(packageRoot, "themes"), "--skill", join(packageRoot, "skills"), "--prompt-template", join(packageRoot, "prompts")]);
+	assert.deepEqual(payload.args, ["--no-extensions", "-e", packageRoot]);
 });
 
 // --- R3-001/R4-takeover-injects-unverified-package-dirs -------------------
@@ -2342,12 +2733,6 @@ test("--link take-over skips a declared package directory that is not installed,
 		installedOtherDir,
 		"-e",
 		packageRoot,
-		"--theme",
-		join(packageRoot, "themes"),
-		"--skill",
-		join(packageRoot, "skills"),
-		"--prompt-template",
-		join(packageRoot, "prompts"),
 		"--mode",
 		"rpc",
 	]);
@@ -2380,12 +2765,6 @@ test("--link take-over injects the launcher's own package root once when --packa
 		"--no-extensions",
 		"-e",
 		forcedRoot,
-		"--theme",
-		join(forcedRoot, "themes"),
-		"--skill",
-		join(forcedRoot, "skills"),
-		"--prompt-template",
-		join(forcedRoot, "prompts"),
 	]);
 });
 
@@ -2402,12 +2781,6 @@ test("--isolated --package-root produces the plain injection (no --no-extensions
 	assert.deepEqual(payload.args, [
 		"-e",
 		forcedRoot,
-		"--theme",
-		join(forcedRoot, "themes"),
-		"--skill",
-		join(forcedRoot, "skills"),
-		"--prompt-template",
-		join(forcedRoot, "prompts"),
 		"--mode",
 		"rpc",
 	]);
@@ -2453,7 +2826,7 @@ test("--link take-over warns once when a loose extensions directory cannot be re
 	assert.match(result.stderr, /extensions/);
 
 	const payload = JSON.parse(result.stdout);
-	assert.deepEqual(payload.args, ["--no-extensions", "-e", packageRoot, "--theme", join(packageRoot, "themes"), "--skill", join(packageRoot, "skills"), "--prompt-template", join(packageRoot, "prompts")]);
+	assert.deepEqual(payload.args, ["--no-extensions", "-e", packageRoot]);
 });
 
 // --- R3-004: loose-extensions manifest branch coverage ----------------------
@@ -2485,12 +2858,6 @@ test("--link take-over falls through to per-file discovery when a loose dir's pa
 		join(looseAgentExtensions, "a.ts"),
 		"-e",
 		packageRoot,
-		"--theme",
-		join(packageRoot, "themes"),
-		"--skill",
-		join(packageRoot, "skills"),
-		"--prompt-template",
-		join(packageRoot, "prompts"),
 	]);
 });
 
@@ -2521,12 +2888,6 @@ test("--link take-over treats a malformed package.json as no manifest and falls
 		join(looseAgentExtensions, "a.ts"),
 		"-e",
 		packageRoot,
-		"--theme",
-		join(packageRoot, "themes"),
-		"--skill",
-		join(packageRoot, "skills"),
-		"--prompt-template",
-		join(packageRoot, "prompts"),
 	]);
 });
 
@@ -2567,5 +2928,181 @@ test("--link take-over treats a file named `extensions` as not a loose extension
 	assert.equal(result.status, 0, result.stderr);
 
 	const payload = JSON.parse(result.stdout);
-	assert.deepEqual(payload.args, ["--no-extensions", "-e", packageRoot, "--theme", join(packageRoot, "themes"), "--skill", join(packageRoot, "skills"), "--prompt-template", join(packageRoot, "prompts")]);
+	assert.deepEqual(payload.args, ["--no-extensions", "-e", packageRoot]);
+});
+
+// --- resume-hint handoff (lib/gentle-shell-resume-hint.ts) ----------------------
+
+// A stand-in pi that writes a resume handoff like extensions/resume-hint.ts
+// does, prints pi's own exit hint, and exits with the given code.
+function writeHandoffPiScript(path: string, exitCode = 0) {
+	writeFileSync(
+		path,
+		[
+			"#!/usr/bin/env node",
+			"const { writeFileSync } = require('node:fs');",
+			"const args = process.argv.slice(2);",
+			"if (args.includes('--version')) { console.log('0.99.1'); process.exit(0); }",
+			"const handoff = process.env.GENTLE_SHELL_RESUME_HANDOFF;",
+			"if (handoff) writeFileSync(handoff, JSON.stringify({ sessionId: 'abc' }));",
+			"if (process.env.PI_STUB_PRINT_ENV) console.log(JSON.stringify({ args, handoff }));",
+			"process.stdout.write('To resume this session: pi --session abc\\n');",
+			`process.exit(${exitCode});`,
+			"",
+		].join("\n"),
+	);
+	chmodSync(path, 0o755);
+}
+
+test("interactive launch hands pi a private resume handoff and cleans it up", (t) => {
+	const f = fixture(t);
+	const piScript = join(f.root, "handoff-pi.cjs");
+	writeHandoffPiScript(piScript);
+	const result = run({ ...f.env, GENTLE_SHELL_PI: piScript, PI_STUB_PRINT_ENV: "1" }, []);
+	assert.equal(result.status, 0, result.stderr);
+	const lines = result.stdout.trim().split("\n");
+	const { handoff } = JSON.parse(lines[0]);
+	assert.equal(typeof handoff, "string");
+	assert.match(handoff, /gentle-shell-resume-/);
+	assert.equal(existsSync(dirname(handoff)), false, "handoff dir must be removed after pi exits");
+	// Not a TTY: like pi's own hint, the gentle-shell line is not printed.
+	assert.deepEqual(lines.slice(1), ["To resume this session: pi --session abc"]);
+});
+
+test("pi subcommands get no resume handoff", (t) => {
+	const f = fixture(t);
+	const piScript = join(f.root, "handoff-pi.cjs");
+	writeHandoffPiScript(piScript);
+	const result = run({ ...f.env, GENTLE_SHELL_PI: piScript, PI_STUB_PRINT_ENV: "1" }, ["list"]);
+	assert.equal(result.status, 0, result.stderr);
+	assert.equal(JSON.parse(result.stdout.trim().split("\n")[0]).handoff, undefined);
+});
+
+// The hint is only printed to a real TTY, so drive the launcher through a
+// pseudo-terminal. Python's pty module is the portable POSIX way to get one
+// without a native dependency; skipped where it is unavailable.
+const hasPythonPty = process.platform !== "win32" && spawnSync("python3", ["-c", "import pty"], { stdio: "ignore" }).status === 0;
+const PTY_RUNNER = [
+	"import fcntl, os, pty, struct, subprocess, sys, termios",
+	"m, s = pty.openpty()",
+	"fcntl.ioctl(s, termios.TIOCSWINSZ, struct.pack('HHHH', 24, 120, 0, 0))",
+	"p = subprocess.Popen(sys.argv[1:], stdin=s, stdout=s, stderr=s)",
+	"os.close(s)",
+	"out = b''",
+	// PTY_SIGNAL_AFTER: once this text appears, send PTY_SIGNAL to the launcher.
+	"after = os.environ.get('PTY_SIGNAL_AFTER', '').encode()",
+	"while True:",
+	"    try: d = os.read(m, 4096)",
+	"    except OSError: break",
+	"    if not d: break",
+	"    out += d",
+	"    if after and after in out:",
+	"        after = b''",
+	"        os.kill(p.pid, int(os.environ['PTY_SIGNAL']))",
+	"sys.stdout.write(out.decode())",
+	"sys.exit(p.wait())",
+].join("\n");
+
+function runInPty(env: NodeJS.ProcessEnv, args: string[], expectedStatus = 0): string {
+	// Pin the color environment so the launcher's hasColors() check does not
+	// depend on the machine running the tests; a test can still override it.
+	const { NO_COLOR, FORCE_COLOR, NODE_DISABLE_COLORS, ...rest } = env;
+	const colorEnv = { ...rest, TERM: "xterm-256color", ...(env.PTY_NO_COLOR ? { NO_COLOR: "1" } : {}) };
+	// Bounded so a stand-in pi that never exits fails the test instead of hanging CI.
+	const result = spawnSync("python3", ["-c", PTY_RUNNER, process.execPath, binPath, ...args], { encoding: "utf8", env: colorEnv, timeout: 30_000 });
+	assert.equal(result.error, undefined, String(result.error));
+	assert.equal(result.status, expectedStatus, result.stdout + result.stderr);
+	return result.stdout;
+}
+
+const PI_HINT = "To resume this session: pi --session abc\r\n";
+const GENTLE_HINT = "\u001b[2mTo resume in gentle-shell:\u001b[22m gentle-shell --link --session abc\r\n";
+
+test("on a TTY the launcher appends a gentle-shell resume line below pi's hint", { skip: !hasPythonPty && "needs python3 pty" }, (t) => {
+	const f = fixture(t);
+	const piScript = join(f.root, "tty-pi.cjs");
+	writeHandoffPiScript(piScript);
+	const out = runInPty({ ...f.env, GENTLE_SHELL_PI: piScript }, ["--link"]);
+	assert.ok(out.endsWith(PI_HINT + GENTLE_HINT), JSON.stringify(out));
+});
+
+test("on a TTY the gentle-shell line still follows a non-zero pi exit, keeping the code", { skip: !hasPythonPty && "needs python3 pty" }, (t) => {
+	const f = fixture(t);
+	const piScript = join(f.root, "tty-pi.cjs");
+	writeHandoffPiScript(piScript, 3);
+	const out = runInPty({ ...f.env, GENTLE_SHELL_PI: piScript }, ["--link"], 3);
+	assert.ok(out.endsWith(PI_HINT + GENTLE_HINT), JSON.stringify(out));
+});
+
+// A stand-in pi that writes the handoff and then waits: it quits with its
+// own hint on SIGHUP/SIGTERM, but survives SIGINT (like an interrupted turn)
+// and quits only on the next line of input.
+function writeWaitingPiScript(path: string) {
+	writeFileSync(
+		path,
+		[
+			"#!/usr/bin/env node",
+			"const { writeFileSync } = require('node:fs');",
+			"if (process.argv.includes('--version')) { console.log('0.99.1'); process.exit(0); }",
+			"writeFileSync(process.env.GENTLE_SHELL_RESUME_HANDOFF, JSON.stringify({ sessionId: 'abc' }));",
+			"const quit = () => { process.stdout.write('To resume this session: pi --session abc\\n'); process.exit(0); };",
+			"process.on('SIGHUP', quit);",
+			"process.on('SIGTERM', quit);",
+			"process.on('SIGINT', () => { process.stdout.write('interrupted\\n'); setTimeout(quit, 50); });",
+			"process.stdout.write('ready\\n');",
+			"setInterval(() => {}, 1000);",
+			"",
+		].join("\n"),
+	);
+	chmodSync(path, 0o755);
+}
+
+test("on a TTY the launcher prints nothing extra after the terminal hangs up", { skip: !hasPythonPty && "needs python3 pty" }, (t) => {
+	const f = fixture(t);
+	const piScript = join(f.root, "tty-pi.cjs");
+	writeWaitingPiScript(piScript);
+	const out = runInPty({ ...f.env, GENTLE_SHELL_PI: piScript, PTY_SIGNAL_AFTER: "ready", PTY_SIGNAL: "1" }, ["--link"]);
+	// pi quit cleanly with its own hint; only the gentle-shell line is withheld.
+	assert.ok(out.endsWith(PI_HINT), JSON.stringify(out));
+	assert.equal(out.includes("gentle-shell --"), false, JSON.stringify(out));
+});
+
+test("on a TTY a forwarded SIGINT that pi survives does not silence the gentle-shell line", { skip: !hasPythonPty && "needs python3 pty" }, (t) => {
+	const f = fixture(t);
+	const piScript = join(f.root, "tty-pi.cjs");
+	writeWaitingPiScript(piScript);
+	const out = runInPty({ ...f.env, GENTLE_SHELL_PI: piScript, PTY_SIGNAL_AFTER: "ready", PTY_SIGNAL: "2" }, ["--link"]);
+	assert.ok(out.includes("interrupted"), JSON.stringify(out));
+	assert.ok(out.endsWith(PI_HINT + GENTLE_HINT), JSON.stringify(out));
+});
+
+test("on a TTY a cross-project session resumes by its session file", { skip: !hasPythonPty && "needs python3 pty" }, (t) => {
+	const f = fixture(t);
+	const sessionFile = join(f.root, "other project", "session.jsonl");
+	const piScript = join(f.root, "tty-pi.cjs");
+	writeFileSync(
+		piScript,
+		[
+			"#!/usr/bin/env node",
+			"const { writeFileSync } = require('node:fs');",
+			"if (process.argv.includes('--version')) { console.log('0.99.1'); process.exit(0); }",
+			`writeFileSync(process.env.GENTLE_SHELL_RESUME_HANDOFF, JSON.stringify({ sessionId: 'abc', sessionFile: ${JSON.stringify(sessionFile)} }));`,
+			"process.stdout.write('To resume this session: pi --session abc\\n');",
+			"",
+		].join("\n"),
+	);
+	chmodSync(piScript, 0o755);
+	const out = runInPty({ ...f.env, GENTLE_SHELL_PI: piScript }, ["--link"]);
+	assert.ok(
+		out.endsWith(`${PI_HINT}\u001b[2mTo resume in gentle-shell:\u001b[22m gentle-shell --link --session '${sessionFile}'\r\n`),
+		JSON.stringify(out),
+	);
+});
+
+test("on a TTY without colors the gentle-shell line has no ANSI styling", { skip: !hasPythonPty && "needs python3 pty" }, (t) => {
+	const f = fixture(t);
+	const piScript = join(f.root, "tty-pi.cjs");
+	writeHandoffPiScript(piScript);
+	const out = runInPty({ ...f.env, GENTLE_SHELL_PI: piScript, PTY_NO_COLOR: "1" }, ["--link"]);
+	assert.ok(out.endsWith(`${PI_HINT}To resume in gentle-shell: gentle-shell --link --session abc\r\n`), JSON.stringify(out));
 });