gentle-pi 3.7.0 → 4.0.0

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

@@ -32,6 +32,8 @@ import {
 	quoteForCmdExe,
 	recordProvisioned,
 	resolveHome,
+	USER_PI_HOME_ENV,
+	userPiHome,
 	resolvePiRuntime,
 	restoreJsonField,
 	settingsDeclareGentlePi,
@@ -620,20 +622,37 @@ test("checkPeerVersionPin passes for a matching pin", () => {
 	assert.deepEqual(result, { ok: true, pinned: ">=0.85.1" });
 });
 
+test("Pi 0.99.1 baseline and host peers follow the open development range policy", () => {
+	const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+	assert.equal(MIN_PI_VERSION, "0.99.1");
+	assert.equal(pkg.engines.node, ">=22.19.0");
+	for (const name of ["@earendil-works/pi-ai", "@earendil-works/pi-tui"]) {
+		assert.equal(pkg.peerDependencies[name], "*");
+		assert.equal(pkg.peerDependenciesMeta[name].optional, true);
+		assert.equal(pkg.dependencies[name], undefined);
+	}
+	// Development ranges are policy specifiers; their floor never drops below
+	// the runtime minimum the launcher enforces.
+	for (const name of ["@earendil-works/pi-coding-agent", "@earendil-works/pi-ai", "@earendil-works/pi-tui"]) {
+		assert.equal(pkg.devDependencies[name], ">=1.0.0", name);
+		assert.equal(checkPiVersion(pkg.devDependencies[name].slice(2)).ok, true, name);
+	}
+});
+
 test("checkPiVersion accepts a version equal to the minimum", () => {
-	assert.deepEqual(checkPiVersion("0.85.1"), { ok: true, version: "0.85.1" });
+	assert.deepEqual(checkPiVersion("0.99.1"), { ok: true, version: "0.99.1" });
 });
 
 test("checkPiVersion accepts a version above the minimum", () => {
-	assert.deepEqual(checkPiVersion("0.86.0"), { ok: true, version: "0.86.0" });
+	assert.deepEqual(checkPiVersion("0.100.0"), { ok: true, version: "0.100.0" });
 });
 
 test("checkPiVersion accepts a v-prefixed version", () => {
-	assert.deepEqual(checkPiVersion("v0.85.1"), { ok: true, version: "0.85.1" });
+	assert.deepEqual(checkPiVersion("v0.99.1"), { ok: true, version: "0.99.1" });
 });
 
 test("checkPiVersion accepts a prerelease suffix at the minimum", () => {
-	assert.deepEqual(checkPiVersion("pi version 0.85.1-rc.2"), { ok: true, version: "0.85.1" });
+	assert.deepEqual(checkPiVersion("pi version 0.99.1-rc.2"), { ok: true, version: "0.99.1" });
 });
 
 test("checkPiVersion rejects a version below the minimum and names both versions", () => {
@@ -642,7 +661,7 @@ test("checkPiVersion rejects a version below the minimum and names both versions
 	if (result.ok) throw new Error("expected a failing result");
 	assert.equal(result.version, "0.85.0");
 	assert.match(result.message, /0\.85\.0/);
-	assert.match(result.message, /0\.85\.1/);
+	assert.match(result.message, /0\.99\.1/);
 });
 
 test("checkPiVersion rejects a prerelease below the minimum", () => {
@@ -656,7 +675,7 @@ test("checkPiVersion reports unparsable output with the raw text and the minimum
 	if (result.ok) throw new Error("expected a failing result");
 	assert.equal(result.version, undefined);
 	assert.match(result.message, /not a version/);
-	assert.match(result.message, /0\.85\.1/);
+	assert.match(result.message, /0\.99\.1/);
 });
 
 test("checkPiVersion accepts a custom minimum", () => {
@@ -1103,6 +1122,23 @@ test("otherPackageInjections defaults to including every declared package when i
 
 // --- buildPiInvocation -------------------------------------------------------
 
+test("package injection relies on Pi's -e resource discovery in isolated and takeover modes", () => {
+	for (const takeOver of [false, true]) {
+		const built = buildPiInvocation({
+			runtime: { kind: "path", command: "/usr/bin/pi", args: [] },
+			home: { mode: "isolated", dir: "/gentle-shell/agent", source: "default" },
+			packageRoot: "/pkg",
+			declaration: undefined,
+			takeOver,
+			otherPackagePaths: [],
+			passthrough: [],
+			baseEnv: {},
+			homedir: "/home/u",
+		});
+		assert.deepEqual(built.args, takeOver ? ["--no-extensions", "-e", "/pkg"] : ["-e", "/pkg"]);
+	}
+});
+
 const linkHome: ResolvedHome = { mode: "link", dir: "/pi/agent", source: "flag" };
 const isolatedHomeResolved: ResolvedHome = { mode: "isolated", dir: "/gentle-shell/agent", source: "default" };
 
@@ -1116,8 +1152,9 @@ test("buildPiInvocation injects the launcher env into baseEnv", () => {
 		otherPackagePaths: [],
 		passthrough: [],
 		baseEnv: { PATH: "/usr/bin" },
+		homedir: "/home/u",
 	});
-	assert.deepEqual(built.env, { PATH: "/usr/bin", PI_CODING_AGENT_DIR: "/pi/agent", GENTLE_PI_AGENT_HOME: "/pi/agent" });
+	assert.deepEqual(built.env, { PATH: "/usr/bin", PI_CODING_AGENT_DIR: "/pi/agent", GENTLE_PI_AGENT_HOME: "/pi/agent", GENTLE_SHELL_USER_PI_HOME: join("/home/u", ".pi", "agent") });
 });
 
 test("buildPiInvocation skips injection when there is a declaration and no takeover (npm matches the launcher's own install)", () => {
@@ -1130,6 +1167,7 @@ test("buildPiInvocation skips injection when there is a declaration and no takeo
 		otherPackagePaths: [],
 		passthrough: ["--mode", "rpc"],
 		baseEnv: {},
+		homedir: "/home/u",
 	});
 	assert.deepEqual(built.command, "/usr/bin/pi");
 	assert.deepEqual(built.args, ["--mode", "rpc"]);
@@ -1145,16 +1183,11 @@ test("buildPiInvocation adds the gentle-pi injection flags when there is no decl
 		otherPackagePaths: [],
 		passthrough: ["--mode", "rpc"],
 		baseEnv: {},
+		homedir: "/home/u",
 	});
 	assert.deepEqual(built.args, [
 		"-e",
 		"/pkg",
-		"--theme",
-		join("/pkg", "themes"),
-		"--skill",
-		join("/pkg", "skills"),
-		"--prompt-template",
-		join("/pkg", "prompts"),
 		"--mode",
 		"rpc",
 	]);
@@ -1171,6 +1204,7 @@ test("buildPiInvocation emits only runtime args and passthrough when a pi subcom
 		passthrough: ["install", "npm:x"],
 		piSubcommand: "install",
 		baseEnv: {},
+		homedir: "/home/u",
 	});
 	assert.deepEqual(built.args, ["install", "npm:x"]);
 	assert.equal(built.command, "/usr/bin/pi");
@@ -1187,11 +1221,13 @@ test("buildPiInvocation still injects the launcher env for a pi subcommand", ()
 		passthrough: ["list"],
 		piSubcommand: "list",
 		baseEnv: { PATH: "/usr/bin" },
+		homedir: "/home/u",
 	});
 	assert.deepEqual(built.env, {
 		PATH: "/usr/bin",
 		PI_CODING_AGENT_DIR: "/gentle-shell/agent",
 		GENTLE_PI_AGENT_HOME: "/gentle-shell/agent",
+		GENTLE_SHELL_USER_PI_HOME: join("/home/u", ".pi", "agent"),
 	});
 });
 
@@ -1205,11 +1241,49 @@ test("buildPiInvocation in link mode with a pi subcommand is exactly pi <subcomm
 		otherPackagePaths: [join("/agent", "npm", "node_modules", "some-other")],
 		passthrough: ["auth", "status"],
 		piSubcommand: "auth",
-		baseEnv: {},
+		baseEnv: { PI_CODING_AGENT_DIR: "/pi/agent" },
+		homedir: "/home/u",
 	});
 	assert.equal(built.command, "/usr/bin/pi");
 	assert.deepEqual(built.args, ["auth", "status"]);
-	assert.deepEqual(built.env, { PI_CODING_AGENT_DIR: "/pi/agent", GENTLE_PI_AGENT_HOME: "/pi/agent" });
+	assert.deepEqual(built.env, { PI_CODING_AGENT_DIR: "/pi/agent", GENTLE_PI_AGENT_HOME: "/pi/agent", GENTLE_SHELL_USER_PI_HOME: "/pi/agent" });
+});
+
+// The isolated home overrides PI_CODING_AGENT_DIR for the session, so the
+// user's own Pi home travels separately for read-only features such as
+// /gentle:stats. Isolation itself is unchanged.
+test("buildPiInvocation carries the user's original Pi home without weakening isolation", () => {
+	const build = (baseEnv: Record<string, string | undefined>, home: ResolvedHome = isolatedHomeResolved) => buildPiInvocation({
+		runtime: { kind: "path", command: "/usr/bin/pi", args: [] },
+		home,
+		packageRoot: "/pkg",
+		declaration: undefined,
+		takeOver: false,
+		otherPackagePaths: [],
+		passthrough: [],
+		baseEnv,
+		homedir: "/home/u",
+	}).env;
+	const conventional = build({});
+	assert.equal(conventional.PI_CODING_AGENT_DIR, "/gentle-shell/agent");
+	assert.equal(conventional.GENTLE_PI_AGENT_HOME, "/gentle-shell/agent");
+	assert.equal(conventional.GENTLE_SHELL_USER_PI_HOME, join("/home/u", ".pi", "agent"));
+	// A custom Pi home is preserved; an empty value falls through like Pi itself.
+	const custom = build({ PI_CODING_AGENT_DIR: "/custom/pi" });
+	assert.equal(custom.PI_CODING_AGENT_DIR, "/gentle-shell/agent");
+	assert.equal(custom.GENTLE_SHELL_USER_PI_HOME, "/custom/pi");
+	assert.equal(build({ PI_CODING_AGENT_DIR: "" }).GENTLE_SHELL_USER_PI_HOME, join("/home/u", ".pi", "agent"));
+	// A nested launch inherits the outer isolated PI_CODING_AGENT_DIR; the
+	// original home the outer launcher recorded must win over it.
+	const nested = build({ PI_CODING_AGENT_DIR: "/gentle-shell/agent", GENTLE_SHELL_USER_PI_HOME: "/custom/pi" });
+	assert.equal(nested.PI_CODING_AGENT_DIR, "/gentle-shell/agent");
+	assert.equal(nested.GENTLE_SHELL_USER_PI_HOME, "/custom/pi");
+	// --link: the active and original homes are the same directory.
+	const linked = build({ PI_CODING_AGENT_DIR: "/pi/agent" }, linkHome);
+	assert.equal(linked.PI_CODING_AGENT_DIR, "/pi/agent");
+	assert.equal(linked.GENTLE_SHELL_USER_PI_HOME, "/pi/agent");
+	assert.equal(USER_PI_HOME_ENV, "GENTLE_SHELL_USER_PI_HOME");
+	assert.equal(userPiHome({ GENTLE_SHELL_USER_PI_HOME: "/kept" }, "/home/u"), "/kept");
 });
 
 test("buildPiInvocation keeps the runtime's own args ahead of the injection and passthrough", () => {
@@ -1222,6 +1296,7 @@ test("buildPiInvocation keeps the runtime's own args ahead of the injection and
 		otherPackagePaths: [],
 		passthrough: [],
 		baseEnv: {},
+		homedir: "/home/u",
 	});
 	assert.equal(built.args[0], "/bundled/cli.js");
 	assert.equal(built.command, "/usr/bin/node");
@@ -1237,6 +1312,7 @@ test("buildPiInvocation takes over a conflicting path declaration: --no-extensio
 		otherPackagePaths: [join("/agent", "npm", "node_modules", "some-other")],
 		passthrough: ["--mode", "rpc"],
 		baseEnv: {},
+		homedir: "/home/u",
 	});
 	assert.deepEqual(built.args, [
 		"--no-extensions",
@@ -1244,12 +1320,6 @@ test("buildPiInvocation takes over a conflicting path declaration: --no-extensio
 		join("/agent", "npm", "node_modules", "some-other"),
 		"-e",
 		"/pkg",
-		"--theme",
-		join("/pkg", "themes"),
-		"--skill",
-		join("/pkg", "skills"),
-		"--prompt-template",
-		join("/pkg", "prompts"),
 		"--mode",
 		"rpc",
 	]);
@@ -1265,17 +1335,12 @@ test("buildPiInvocation takes over with --package-root even for a matching npm d
 		otherPackagePaths: [],
 		passthrough: [],
 		baseEnv: {},
+		homedir: "/home/u",
 	});
 	assert.deepEqual(built.args, [
 		"--no-extensions",
 		"-e",
 		"/forced/root",
-		"--theme",
-		join("/forced/root", "themes"),
-		"--skill",
-		join("/forced/root", "skills"),
-		"--prompt-template",
-		join("/forced/root", "prompts"),
 	]);
 });
 
@@ -1289,6 +1354,7 @@ test("buildPiInvocation takes over with --package-root even when there is no dec
 		otherPackagePaths: [join("/agent", "npm", "node_modules", "some-other")],
 		passthrough: [],
 		baseEnv: {},
+		homedir: "/home/u",
 	});
 	assert.deepEqual(built.args, [
 		"--no-extensions",
@@ -1296,12 +1362,6 @@ test("buildPiInvocation takes over with --package-root even when there is no dec
 		join("/agent", "npm", "node_modules", "some-other"),
 		"-e",
 		"/forced/root",
-		"--theme",
-		join("/forced/root", "themes"),
-		"--skill",
-		join("/forced/root", "skills"),
-		"--prompt-template",
-		join("/forced/root", "prompts"),
 	]);
 });
 
@@ -1316,6 +1376,7 @@ test("buildPiInvocation injects loose extension entries during a takeover, after
 		looseExtensionEntries: [join("/agent", "extensions", "a.ts"), join("/project", ".pi", "extensions", "b.js")],
 		passthrough: ["--mode", "rpc"],
 		baseEnv: {},
+		homedir: "/home/u",
 	});
 	assert.deepEqual(built.args, [
 		"--no-extensions",
@@ -1327,12 +1388,6 @@ test("buildPiInvocation injects loose extension entries during a takeover, after
 		join("/project", ".pi", "extensions", "b.js"),
 		"-e",
 		"/pkg",
-		"--theme",
-		join("/pkg", "themes"),
-		"--skill",
-		join("/pkg", "skills"),
-		"--prompt-template",
-		join("/pkg", "prompts"),
 		"--mode",
 		"rpc",
 	]);
@@ -1348,8 +1403,9 @@ test("buildPiInvocation omits loose extension entry flags when the list is empty
 		otherPackagePaths: [],
 		passthrough: [],
 		baseEnv: {},
+		homedir: "/home/u",
 	});
-	assert.deepEqual(withoutField.args, ["--no-extensions", "-e", "/pkg", "--theme", join("/pkg", "themes"), "--skill", join("/pkg", "skills"), "--prompt-template", join("/pkg", "prompts")]);
+	assert.deepEqual(withoutField.args, ["--no-extensions", "-e", "/pkg"]);
 
 	const withEmptyField = buildPiInvocation({
 		runtime: { kind: "path", command: "/usr/bin/pi", args: [] },
@@ -1361,6 +1417,7 @@ test("buildPiInvocation omits loose extension entry flags when the list is empty
 		looseExtensionEntries: [],
 		passthrough: [],
 		baseEnv: {},
+		homedir: "/home/u",
 	});
 	assert.deepEqual(withEmptyField.args, withoutField.args);
 });
@@ -1381,6 +1438,7 @@ test("buildPiInvocation dedupes loose extension entries against other-package pa
 		looseExtensionEntries: ["/shared/dup.ts", "/agent/extensions/a.ts", "/agent/extensions/a.ts"],
 		passthrough: [],
 		baseEnv: {},
+		homedir: "/home/u",
 	});
 	assert.deepEqual(built.args, [
 		"--no-extensions",
@@ -1392,12 +1450,6 @@ test("buildPiInvocation dedupes loose extension entries against other-package pa
 		"/agent/extensions/a.ts",
 		"-e",
 		"/pkg",
-		"--theme",
-		join("/pkg", "themes"),
-		"--skill",
-		join("/pkg", "skills"),
-		"--prompt-template",
-		join("/pkg", "prompts"),
 	]);
 });
 
@@ -1415,6 +1467,7 @@ test("buildPiInvocation dedupes the launcher's own package root against an other
 		otherPackagePaths: [join("/agent", "npm", "node_modules", "some-other"), "/pkg"],
 		passthrough: [],
 		baseEnv: {},
+		homedir: "/home/u",
 	});
 	const eFlags = built.args.filter((arg, index) => built.args[index - 1] === "-e");
 	assert.deepEqual(eFlags, [join("/agent", "npm", "node_modules", "some-other"), "/pkg"]);
@@ -1424,12 +1477,6 @@ test("buildPiInvocation dedupes the launcher's own package root against an other
 		join("/agent", "npm", "node_modules", "some-other"),
 		"-e",
 		"/pkg",
-		"--theme",
-		join("/pkg", "themes"),
-		"--skill",
-		join("/pkg", "skills"),
-		"--prompt-template",
-		join("/pkg", "prompts"),
 	]);
 });
 

package/tests/gentle-shell-resume-hint.test.ts

@@ -0,0 +1,270 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import test from "node:test";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { getAgentDir, SessionManager } from "@earendil-works/pi-coding-agent";
+import {
+	RESUME_HANDOFF_ENV,
+	gentleShellResumeCommand,
+	isResumeHandoffPath,
+	parseResumeHandoff,
+	piDefaultSessionDir,
+	planResumeHint,
+	resumeHandoffFromSession,
+	serializeResumeHandoff,
+} from "../lib/gentle-shell-resume-hint.ts";
+
+const ID = "01a0e0a0-6d7b-7314-89c1-537d47bbf4f3";
+const AGENT_DIR = resolve("/home/u/.gentle-shell/agent");
+const CWD = resolve("/home/u/project");
+const DEFAULT_DIR = join(AGENT_DIR, "sessions", `--${CWD.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`);
+
+test("handoff env name is stable", () => {
+	assert.equal(RESUME_HANDOFF_ENV, "GENTLE_SHELL_RESUME_HANDOFF");
+});
+
+test("piDefaultSessionDir mirrors pi's encoded per-cwd session dir", () => {
+	assert.equal(piDefaultSessionDir(CWD, AGENT_DIR), DEFAULT_DIR);
+	if (process.platform !== "win32") assert.equal(piDefaultSessionDir("/home/u/project", "/a"), "/a/sessions/--home-u-project--");
+});
+
+test("piDefaultSessionDir matches pi's own SessionManager", () => {
+	const agentDir = mkdtempSync(join(tmpdir(), "resume-hint-agent-"));
+	const previous = process.env.PI_CODING_AGENT_DIR;
+	process.env.PI_CODING_AGENT_DIR = agentDir;
+	try {
+		const byDefault = SessionManager.create(CWD);
+		assert.equal(byDefault.usesDefaultSessionDir(), true);
+		assert.equal(byDefault.getSessionDir(), piDefaultSessionDir(CWD, getAgentDir()));
+		const custom = SessionManager.create(CWD, join(agentDir, "elsewhere"));
+		assert.equal(custom.usesDefaultSessionDir(), false);
+		assert.notEqual(custom.getSessionDir(), piDefaultSessionDir(CWD, getAgentDir()));
+	} finally {
+		if (previous === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = previous;
+		rmSync(agentDir, { recursive: true, force: true });
+	}
+});
+
+test("resumeHandoffFromSession omits the session dir when it is pi's default", () => {
+	const handoff = resumeHandoffFromSession({
+		sessionId: ID,
+		sessionDir: DEFAULT_DIR,
+		sessionFile: join(DEFAULT_DIR, "x.jsonl"),
+		cwd: CWD,
+		launchCwd: CWD,
+		agentDir: AGENT_DIR,
+		fileExists: () => true,
+	});
+	assert.deepEqual(handoff, { sessionId: ID });
+});
+
+test("resumeHandoffFromSession keeps a custom session dir", () => {
+	const handoff = resumeHandoffFromSession({
+		sessionId: ID,
+		sessionDir: "/tmp/my sessions",
+		sessionFile: "/tmp/my sessions/x.jsonl",
+		cwd: CWD,
+		launchCwd: CWD,
+		agentDir: AGENT_DIR,
+		fileExists: () => true,
+	});
+	assert.deepEqual(handoff, { sessionId: ID, sessionDir: "/tmp/my sessions" });
+});
+
+test("resumeHandoffFromSession carries the session file for a session from another project", () => {
+	const other = resolve("/home/u/other");
+	const handoff = resumeHandoffFromSession({
+		sessionId: ID,
+		sessionDir: DEFAULT_DIR,
+		sessionFile: join(DEFAULT_DIR, "x.jsonl"),
+		cwd: CWD,
+		launchCwd: other,
+		agentDir: AGENT_DIR,
+		fileExists: () => true,
+	});
+	assert.deepEqual(handoff, { sessionId: ID, sessionFile: join(DEFAULT_DIR, "x.jsonl") });
+	assert.equal(gentleShellResumeCommand(handoff!, ["--link"], "linux"), `gentle-shell --link --session ${join(DEFAULT_DIR, "x.jsonl")}`);
+});
+
+test("resumeHandoffFromSession returns undefined when pi would not print a hint", () => {
+	const base = { sessionId: ID, sessionDir: DEFAULT_DIR, cwd: CWD, launchCwd: CWD, agentDir: AGENT_DIR };
+	assert.equal(resumeHandoffFromSession({ ...base, sessionFile: undefined, fileExists: () => true }), undefined);
+	assert.equal(resumeHandoffFromSession({ ...base, sessionFile: join(DEFAULT_DIR, "x.jsonl"), fileExists: () => false }), undefined);
+});
+
+test("handoff round-trips and rejects malformed input", () => {
+	const handoff = { sessionId: ID, sessionDir: "/tmp/s" };
+	assert.deepEqual(parseResumeHandoff(serializeResumeHandoff(handoff)), handoff);
+	assert.deepEqual(parseResumeHandoff(serializeResumeHandoff({ sessionId: ID })), { sessionId: ID });
+	for (const text of ["", "not json", "null", "[]", '{"sessionId":""}', '{"sessionId":1}', '{"sessionId":"a","sessionDir":3}', '{"sessionId":"a","sessionDir":""}']) {
+		assert.equal(parseResumeHandoff(text), undefined, text);
+	}
+});
+
+test("handoff accepts only an absolute, control-free session file on its own", () => {
+	const file = resolve("/tmp/s/x.jsonl");
+	assert.deepEqual(parseResumeHandoff(JSON.stringify({ sessionId: ID, sessionFile: file })), { sessionId: ID, sessionFile: file });
+	for (const value of [
+		{ sessionId: ID, sessionFile: "relative/x.jsonl" },
+		{ sessionId: ID, sessionFile: resolve("/tmp/s/x.txt") },
+		{ sessionId: ID, sessionFile: resolve("/tmp/s/\u001b[2J.jsonl") },
+		{ sessionId: ID, sessionFile: 3 },
+		{ sessionId: ID, sessionFile: file, sessionDir: "/tmp/s" },
+	]) {
+		assert.equal(parseResumeHandoff(JSON.stringify(value)), undefined, JSON.stringify(value));
+	}
+});
+
+test("isResumeHandoffPath accepts only the launcher's private handoff shape", () => {
+	const tmp = tmpdir();
+	assert.equal(isResumeHandoffPath(join(tmp, "gentle-shell-resume-Ab12Cd", "handoff.json")), true);
+	assert.equal(isResumeHandoffPath(join(tmp, "gentle-shell-resume-Ab12Cd", "other.json")), false);
+	assert.equal(isResumeHandoffPath(join(tmp, "elsewhere", "handoff.json")), false);
+	assert.equal(isResumeHandoffPath(join(resolve("/home/u"), ".bashrc")), false);
+	assert.equal(isResumeHandoffPath("gentle-shell-resume-Ab12Cd/handoff.json"), false);
+});
+
+test("handoff rejects values that could inject terminal control sequences", () => {
+	const reject = (value: object) => assert.equal(parseResumeHandoff(JSON.stringify(value)), undefined, JSON.stringify(value));
+	// Session ids follow pi's assertValidSessionId charset.
+	reject({ sessionId: "abc\u001b[2J" });
+	reject({ sessionId: "abc def" });
+	reject({ sessionId: "-abc" });
+	reject({ sessionId: "abc$(id)" });
+	reject({ sessionId: ID, sessionDir: "/tmp/\u001b]0;pwned\u0007" });
+	reject({ sessionId: ID, sessionDir: "/tmp/a\u009bb" });
+	assert.deepEqual(parseResumeHandoff(JSON.stringify({ sessionId: "a.b_c-1" })), { sessionId: "a.b_c-1" });
+});
+
+test("gentleShellResumeCommand keeps home selectors and a custom session dir", () => {
+	assert.equal(gentleShellResumeCommand({ sessionId: ID }, [], "linux"), `gentle-shell --session ${ID}`);
+	assert.equal(gentleShellResumeCommand({ sessionId: ID }, ["--link"], "linux"), `gentle-shell --link --session ${ID}`);
+	assert.equal(
+		gentleShellResumeCommand({ sessionId: ID, sessionDir: "/tmp/my sessions" }, ["--home", "/x y"], "linux"),
+		`gentle-shell --home '/x y' --session-dir '/tmp/my sessions' --session ${ID}`,
+	);
+});
+
+test("the gentle-shell command matches pi's real exit hint with the binary swapped", async () => {
+	// formatResumeCommand is not in pi's exports map; load the module file.
+	const piDist = dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent")));
+	const modulePath = join(piDist, "modes", "interactive", "interactive-mode.js");
+	const { formatResumeCommand } = await import(pathToFileURL(modulePath).href);
+	// The appended line is only needed while pi prints this hint.
+	assert.ok(readFileSync(modulePath, "utf8").includes('chalk.dim("To resume this session:")'), "pi's hint label changed");
+
+	const agentDir = mkdtempSync(join(tmpdir(), "resume-hint-agent-"));
+	const previousDir = process.env.PI_CODING_AGENT_DIR;
+	const previousTTY = Object.getOwnPropertyDescriptor(process.stdout, "isTTY");
+	process.env.PI_CODING_AGENT_DIR = agentDir;
+	Object.defineProperty(process.stdout, "isTTY", { value: true, configurable: true });
+	try {
+		for (const sessionDir of [undefined, join(agentDir, "my sessions")]) {
+			const manager = SessionManager.create(CWD, sessionDir);
+			manager.appendMessage({ role: "user", content: "hi", timestamp: Date.now() } as never);
+			manager.appendMessage({ role: "assistant", content: [{ type: "text", text: "ok" }], timestamp: Date.now() } as never);
+			const handoff = resumeHandoffFromSession({
+				sessionId: manager.getSessionId(),
+				sessionDir: manager.getSessionDir(),
+				sessionFile: manager.getSessionFile(),
+				cwd: manager.getCwd(),
+				launchCwd: manager.getCwd(),
+				agentDir: getAgentDir(),
+				fileExists: existsSync,
+			});
+			assert.ok(handoff);
+			const piCommand: string = formatResumeCommand(manager);
+			assert.ok(piCommand.startsWith("pi "), piCommand);
+			// pi quotes the POSIX way on every platform; compare with the same quoting.
+			assert.equal(gentleShellResumeCommand(handoff, [], "linux"), `gentle-shell ${piCommand.slice("pi ".length)}`);
+		}
+	} finally {
+		if (previousTTY) Object.defineProperty(process.stdout, "isTTY", previousTTY);
+		else delete (process.stdout as { isTTY?: boolean }).isTTY;
+		if (previousDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = previousDir;
+		rmSync(agentDir, { recursive: true, force: true });
+	}
+});
+
+test("on win32 the command uses double quotes that cmd.exe and PowerShell honor", () => {
+	assert.equal(gentleShellResumeCommand({ sessionId: ID }, ["--link"], "win32"), `gentle-shell --link --session ${ID}`);
+	assert.equal(
+		gentleShellResumeCommand({ sessionId: ID, sessionDir: "C:\\Users\\Name With Space\\sessions" }, ["--home", "C:\\Users\\Name With Space\\home"], "win32"),
+		`gentle-shell --home "C:\\Users\\Name With Space\\home" --session-dir "C:\\Users\\Name With Space\\sessions" --session ${ID}`,
+	);
+	// Plain paths need no quotes at all.
+	assert.equal(
+		gentleShellResumeCommand({ sessionId: ID, sessionFile: "C:\\s\\x.jsonl" }, [], "win32"),
+		"gentle-shell --session C:\\s\\x.jsonl",
+	);
+	// Spaces alone are safe inside double quotes.
+	assert.equal(
+		gentleShellResumeCommand({ sessionId: ID, sessionFile: "C:\\My Sessions\\x.jsonl" }, [], "win32"),
+		'gentle-shell --session "C:\\My Sessions\\x.jsonl"',
+	);
+});
+
+test("on win32 no command is produced when a value cannot be quoted safely", () => {
+	// PowerShell passes a space-free argument to the .cmd shim unquoted, so
+	// cmd.exe operators are refused even though double quotes would cover them.
+	for (const home of ["C:\\%USERPROFILE%\\h", "C:\\a!b\\h", "C:\\$env\\h", "C:\\a`b\\h", 'C:\\a"b\\h', "C:\\a b\\", "C:\\R&D\\h", "C:\\a|b\\h", "C:\\a<b\\h", "C:\\a>b\\h", "C:\\a^b\\h", "C:\\a(b)\\h"]) {
+		assert.equal(gentleShellResumeCommand({ sessionId: ID }, ["--home", home], "win32"), undefined, home);
+	}
+	assert.equal(
+		planResumeHint({ handoff: { sessionId: ID }, homeFlags: ["--home", "C:\\%TEMP%\\h"], stdoutIsTTY: true, terminalHungUp: false, platform: "win32", color: true }),
+		undefined,
+	);
+	// The same characters are harmless inside POSIX single quotes elsewhere.
+	assert.equal(gentleShellResumeCommand({ sessionId: ID }, ["--home", "/tmp/$h"], "linux"), `gentle-shell --home '/tmp/$h' --session ${ID}`);
+});
+
+test("a cross-project session file reopens the original session in pi", () => {
+	const agentDir = mkdtempSync(join(tmpdir(), "resume-hint-agent-"));
+	const previousDir = process.env.PI_CODING_AGENT_DIR;
+	process.env.PI_CODING_AGENT_DIR = agentDir;
+	try {
+		const manager = SessionManager.create(CWD);
+		manager.appendMessage({ role: "user", content: "hi", timestamp: Date.now() } as never);
+		manager.appendMessage({ role: "assistant", content: [{ type: "text", text: "ok" }], timestamp: Date.now() } as never);
+		const handoff = resumeHandoffFromSession({
+			sessionId: manager.getSessionId(),
+			sessionDir: manager.getSessionDir(),
+			sessionFile: manager.getSessionFile(),
+			cwd: manager.getCwd(),
+			launchCwd: resolve("/home/u/other"),
+			agentDir: getAgentDir(),
+			fileExists: existsSync,
+		});
+		assert.ok(handoff?.sessionFile);
+		// pi's --session takes any value with a path separator as a file path.
+		assert.ok(/[/\\]/.test(handoff.sessionFile));
+		const reopened = SessionManager.open(handoff.sessionFile);
+		assert.equal(reopened.getSessionId(), manager.getSessionId());
+		assert.equal(reopened.getCwd(), manager.getCwd());
+	} finally {
+		if (previousDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = previousDir;
+		rmSync(agentDir, { recursive: true, force: true });
+	}
+});
+
+test("planResumeHint prints the gentle-shell line with pi's dim label style", () => {
+	const hint = planResumeHint({ handoff: { sessionId: ID }, homeFlags: ["--link"], stdoutIsTTY: true, terminalHungUp: false, platform: "linux", color: true });
+	assert.equal(hint, `\u001b[2mTo resume in gentle-shell:\u001b[22m gentle-shell --link --session ${ID}\n`);
+});
+
+test("planResumeHint drops the ANSI style when stdout has no colors", () => {
+	const hint = planResumeHint({ handoff: { sessionId: ID }, homeFlags: [], stdoutIsTTY: true, terminalHungUp: false, platform: "linux", color: false });
+	assert.equal(hint, `To resume in gentle-shell: gentle-shell --session ${ID}\n`);
+});
+
+test("planResumeHint prints nothing without a handoff, a TTY, or after a hang-up", () => {
+	const base = { handoff: { sessionId: ID } as { sessionId: string } | undefined, homeFlags: [], stdoutIsTTY: true, terminalHungUp: false, platform: "linux" as NodeJS.Platform, color: true };
+	assert.equal(planResumeHint({ ...base, handoff: undefined }), undefined);
+	assert.equal(planResumeHint({ ...base, stdoutIsTTY: false }), undefined);
+	assert.equal(planResumeHint({ ...base, terminalHungUp: true }), undefined);
+});