gentle-pi 3.7.0 → 4.0.0

package/lib/yolo-session-policy.ts

@@ -0,0 +1,240 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { appendSystemPromptOnce, type AppendableSystemPromptOptions } from "./append-system-prompt.ts";
+import { captureReviewSessionIdentity, sameReviewSessionIdentity, type ReviewSessionIdentity } from "./review-session-standing-permission.ts";
+
+export const YOLO_STATUS_KEY = "gentle:yolo";
+export const YOLO_STATUS_TEXT = "🚀 YOLO ON 🔥 — destructive confirmations remain";
+export const YOLO_DIRECTIVE = `<gentle-yolo-session>
+YOLO session standing permission is ON, explicitly activated by the human for this live primary session and Git clone.
+Qualify the default commit, push and PR confirmation clauses: for ordinary already-scoped implementation, checks, commits, non-force pushes and PR creation, this activation supplies standing permission instead of repeated permission questions. Make ordinary reversible implementation choices without needless interviews.
+This does NOT override explicit human restrictions, repository policy, project trust, configured confirmations or blocks, or the authorized task scope. Ask before scope expansion, privacy-sensitive disclosure, genuinely unresolved consequential product choices, or ambiguous destinations or credentials. Never invent destinations or credentials.
+Destructive/data-loss confirmations remain mandatory and independent. Never auto-answer ask_user tools, provider consent, maintenance/recovery authorization or opaque-token decisions. Review standing permission and RDD are unchanged. Children remain bounded by their delegated task; they receive no independent delivery grant or YOLO inheritance.
+</gentle-yolo-session>`;
+
+/** Separate from review grants; no registry, entries, configuration or environment enable switch. */
+export class YoloSessionPolicy {
+	private grant: ReviewSessionIdentity | undefined;
+	private generation = 0;
+
+	get epoch(): number { return this.generation; }
+	get enabled(): boolean { return this.grant !== undefined; }
+
+	reset(): void {
+		this.generation += 1;
+		this.grant = undefined;
+	}
+
+	set(enabled: boolean, identity: ReviewSessionIdentity | undefined, expectedEpoch = this.epoch): boolean {
+		if (expectedEpoch !== this.epoch) return false;
+		this.reset();
+		if (!enabled) return true;
+		if (identity === undefined) return false;
+		this.grant = identity;
+		return true;
+	}
+
+	active(identity: ReviewSessionIdentity | undefined): boolean {
+		if (!this.grant) return false;
+		if (identity !== undefined && sameReviewSessionIdentity(this.grant, identity)) return true;
+		this.reset();
+		return false;
+	}
+}
+
+/** Remove our exact block as well as adding it: bridge options can be reused. */
+export function updateYoloPrompt(options: AppendableSystemPromptOptions | null | undefined, active: boolean): void {
+	if (!options) return;
+	options.appendSystemPrompt = (options.appendSystemPrompt ?? "")
+		.replace(`\n\n${YOLO_DIRECTIVE}`, "").replace(YOLO_DIRECTIVE, "");
+	if (active) appendSystemPromptOnce(options, YOLO_DIRECTIVE);
+}
+
+const HUMAN_ACTION = { on: "on", off: "off", toggle: "" } as const;
+type HumanAction = (typeof HUMAN_ACTION)[keyof typeof HUMAN_ACTION];
+export const YOLO_DISPLAY = { on: "ON", off: "OFF", unavailable: "UNAVAILABLE" } as const;
+export type YoloDisplay = (typeof YOLO_DISPLAY)[keyof typeof YOLO_DISPLAY];
+
+/** Private trusted-extension discovery, never a model/tool or serialized authority event. */
+const HOST_UI_CHANNEL = "gentle:yolo:host-ui";
+const DISCOVERY_TIMEOUT_MS = 100;
+export interface YoloUiAdapter {
+	read(): Promise<YoloDisplay>;
+	toggle(): Promise<void>;
+	observe(refresh: () => void): () => void;
+	dispose(): void;
+}
+interface HostUiRequest {
+	context: ExtensionContext;
+	respond(adapter: YoloUiAdapter): void;
+}
+function isUiAdapter(value: unknown): value is YoloUiAdapter {
+	if (!value || typeof value !== "object") return false;
+	const adapter = value as Partial<YoloUiAdapter>;
+	return [adapter.read, adapter.toggle, adapter.observe, adapter.dispose].every(fn => typeof fn === "function");
+}
+
+/** emit is void (and listeners may be wrapped async); explicitly bound the callback wait. */
+export function discoverYoloUiAdapter(pi: ExtensionAPI, context: ExtensionContext): Promise<YoloUiAdapter | undefined> {
+	return new Promise(resolve => {
+		let settled = false;
+		const timer = setTimeout(() => { settled = true; resolve(undefined); }, DISCOVERY_TIMEOUT_MS);
+		const respond = (value: unknown) => {
+			if (!isUiAdapter(value)) return;
+			if (settled) { value.dispose(); return; }
+			settled = true;
+			clearTimeout(timer);
+			resolve(value);
+		};
+		try { pi.events.emit(HOST_UI_CHANNEL, { context, respond } satisfies HostUiRequest); }
+		catch { settled = true; clearTimeout(timer); resolve(undefined); }
+	});
+}
+
+export interface YoloSessionController {
+	active(context: ExtensionContext): Promise<boolean>;
+	humanAction(action: HumanAction, context: ExtensionContext, current?: () => boolean): Promise<boolean>;
+	reset(context: ExtensionContext): void;
+}
+
+/** Register only a human slash command, never a tool, flag or persisted setting. */
+export function registerYoloSessionPolicy(pi: ExtensionAPI, env: NodeJS.ProcessEnv): YoloSessionController {
+	const policy = new YoloSessionPolicy();
+	let ownerGeneration = 0;
+	let publishedEpoch = policy.epoch;
+	const observers = new Set<() => void>();
+	const publish = (context: ExtensionContext, active: boolean): void => {
+		// Display is not authority. Widgets survive shells that hide the status rail.
+		try { context.ui.setStatus(YOLO_STATUS_KEY, active ? YOLO_STATUS_TEXT : undefined); } catch { /* nonblocking */ }
+		try { context.ui.setWidget(YOLO_STATUS_KEY, active ? [YOLO_STATUS_TEXT] : undefined); } catch { /* nonblocking */ }
+		// Repeated state reads publish indicators, but only a policy transition
+		// wakes observers. active -> publish -> observer -> read thus terminates.
+		if (publishedEpoch === policy.epoch) return;
+		publishedEpoch = policy.epoch;
+		for (const refresh of [...observers]) { try { refresh(); } catch { /* display only */ } }
+	};
+	const capture = async (context: ExtensionContext): Promise<ReviewSessionIdentity | undefined> => {
+		try {
+			const cwd = context.cwd;
+			const identity = await captureReviewSessionIdentity(context, env);
+			// Git lookup awaits: a replacement manager ID must not activate stale scope.
+			return cwd === context.cwd && identity?.sessionManager === context.sessionManager &&
+				identity?.sessionId === context.sessionManager.getSessionId() ? identity : undefined;
+		} catch { return undefined; }
+	};
+	const active = async (context: ExtensionContext): Promise<boolean> => {
+		const epoch = policy.epoch;
+		const identity = policy.enabled ? await capture(context) : undefined;
+		if (epoch !== policy.epoch) return false;
+		const enabled = policy.active(identity);
+		publish(context, enabled);
+		return enabled;
+	};
+	// The owning extension calls this from its existing lifecycle hooks, including
+	// reload. Keep their cardinality and ordering intact for SDK and legacy hosts.
+	const reset = (context: ExtensionContext): void => {
+		ownerGeneration += 1;
+		policy.reset();
+		publish(context, false);
+		observers.clear();
+	};
+	// Binds an interaction to the session that opened it: a reload, replacement,
+	// or cwd change while the human is deciding must not act on the new scope.
+	const bindCurrent = (context: ExtensionContext, disposed = () => false): (() => boolean) => {
+		const generation = ownerGeneration;
+		const manager = context.sessionManager, sessionId = manager.getSessionId(), cwd = context.cwd;
+		return () => {
+			try { return !disposed() && generation === ownerGeneration && manager === context.sessionManager &&
+				sessionId === manager.getSessionId() && cwd === context.cwd && context.hasUI; }
+			catch { return false; } // SDK contexts throw after runtime replacement.
+		};
+	};
+	// Both entry points execute this operation, including off/pending-on races.
+	// Resolves false only when the interaction stopped being current, so the
+	// caller can report the discarded choice; a superseding action stays silent.
+	const humanAction = async (action: HumanAction, context: ExtensionContext, current = () => true): Promise<boolean> => {
+		if (!current()) return false;
+		if (action === HUMAN_ACTION.off) {
+			policy.reset(); publish(context, false); context.ui.notify("YOLO OFF", "info");
+			return true;
+		}
+		const wasEnabled = policy.enabled;
+		policy.reset();
+		publish(context, false);
+		const epoch = policy.epoch;
+		const identity = await capture(context);
+		const enable = action === HUMAN_ACTION.on || !wasEnabled;
+		if (!current()) return false;
+		if (epoch !== policy.epoch) return true;
+		const changed = policy.set(enable, identity, epoch);
+		const enabled = changed && policy.active(identity);
+		publish(context, enabled);
+		context.ui.notify(enabled ? YOLO_STATUS_TEXT : enable
+			? "YOLO OFF — activation requires an interactive primary TUI session and an identifiable Git clone."
+			: "YOLO OFF", enabled || !enable ? "info" : "warning");
+		return true;
+	};
+	// Legacy minimal hosts can run the command without an inter-extension bus;
+	// they simply cannot expose the menu adapter.
+	pi.events?.on?.(HOST_UI_CHANNEL, (payload: unknown) => {
+		if (!payload || typeof payload !== "object") return;
+		const request = payload as Partial<HostUiRequest>;
+		if (typeof request.respond !== "function" || !request.context) return;
+		const context = request.context;
+		try {
+			let disposed = false;
+			const subscriptions = new Set<() => void>();
+			const current = bindCurrent(context, () => disposed);
+			const read = async (): Promise<YoloDisplay> => {
+				if (!current()) return YOLO_DISPLAY.unavailable;
+				const epoch = policy.epoch;
+				const identity = await capture(context);
+				if (!current()) return YOLO_DISPLAY.unavailable;
+				if (epoch !== policy.epoch) return read(); // observe the winning off/on, never an old ON.
+				const enabled = policy.active(identity);
+				publish(context, enabled);
+				return identity ? enabled ? YOLO_DISPLAY.on : YOLO_DISPLAY.off : YOLO_DISPLAY.unavailable;
+			};
+			request.respond({
+				read,
+				toggle: async () => { await humanAction(HUMAN_ACTION.toggle, context, current); },
+				observe: (refresh) => {
+					if (!current()) return () => {};
+					subscriptions.add(refresh); observers.add(refresh);
+					return () => { subscriptions.delete(refresh); observers.delete(refresh); };
+				},
+				dispose: () => {
+					disposed = true;
+					for (const refresh of subscriptions) observers.delete(refresh);
+					subscriptions.clear();
+				},
+			});
+		} catch { /* Missing or obsolete trusted host context: discovery expires closed. */ }
+	});
+	pi.registerCommand("gentle:yolo", {
+		description: "Session-only ordinary development/delivery permission (enable|disable|status); no argument opens a menu. Destructive confirmations remain.",
+		handler: async (args, context) => {
+			let action = args.trim() || "status";
+			let current = () => true;
+			// Headless callers keep the status fallback: an empty argument never grants.
+			if (!args.trim() && context.hasUI && typeof context.ui.select === "function") {
+				current = bindCurrent(context);
+				const state = await active(context) ? YOLO_DISPLAY.on : YOLO_DISPLAY.off;
+				const selected = await context.ui.select(`🚀 Gentle YOLO 🔥 — full speed, destructive actions still ask (current: ${state})`, ["enable", "disable", "status"]);
+				if (selected === undefined) return;
+				action = selected;
+			}
+			if (action !== "enable" && action !== "disable" && action !== "status") {
+				context.ui.notify("Use /gentle:yolo enable|disable|status. State unchanged.", "warning");
+				return;
+			}
+			if (action === "status") {
+				context.ui.notify(await active(context) ? YOLO_STATUS_TEXT : "YOLO OFF", "info");
+				return;
+			}
+			if (await humanAction(action === "enable" ? HUMAN_ACTION.on : HUMAN_ACTION.off, context, current)) return;
+			try { context.ui.notify("YOLO unchanged — the session changed while the menu was open.", "warning"); }
+			catch { /* SDK contexts throw after runtime replacement. */ }
+		},
+	});
+	return { active, humanAction, reset };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "gentle-pi",
-	"version": "3.7.0",
-	"description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
+	"version": "4.0.0",
+	"description": "Turn Pi into el Gentleman: an ODD development harness with focused subagents, configured TDD evidence, native review, and skill discovery.",
 	"license": "MIT",
 	"type": "module",
 	"bin": {
@@ -13,8 +13,7 @@
 		"pi-coding-agent",
 		"gentle-pi",
 		"gentle-ai",
-		"sdd",
-		"openspec",
+		"odd",
 		"subagents",
 		"tdd",
 		"code-review",
@@ -37,6 +36,7 @@
 		"skills/",
 		"scripts/",
 		"tests/",
+		"!tests/fixtures/legacy/sdd-research-v2.5.0.md",
 		"themes/",
 		"README.md"
 	],
@@ -44,7 +44,7 @@
 		"check:provider-contract": "node scripts/check-provider-contract.mjs",
 		"mirror:odd-routing": "node scripts/mirror-odd-routing.mjs",
 		"postinstall": "node scripts/install-gentle-ai.mjs",
-		"test": "node --experimental-strip-types --test tests/*.test.ts && pnpm run check:provider-contract && pnpm run test:harness",
+		"test": "node scripts/run-test-suite.mjs",
 		"test:harness": "node --experimental-strip-types tests/runtime-harness.mjs",
 		"test:dev-binary": "node --experimental-strip-types --test tests/devbinary/*.devtest.ts",
 		"test:cross-lane": "node tests/crosslane/cross-lane.mjs",
@@ -72,22 +72,34 @@
 		]
 	},
 	"dependencies": {
-		"@earendil-works/pi-tui": "0.85.1",
 		"@heyhuynhgiabuu/pi-pretty": "0.6.27"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": ">=0.85.1",
+		"@earendil-works/pi-coding-agent": ">=0.99.1",
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-tui": "*",
 		"typebox": "*"
 	},
 	"peerDependenciesMeta": {
 		"@earendil-works/pi-coding-agent": {
 			"optional": true
+		},
+		"@earendil-works/pi-ai": {
+			"optional": true
+		},
+		"@earendil-works/pi-tui": {
+			"optional": true
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "0.85.1",
+		"@earendil-works/pi-coding-agent": ">=1.0.0",
+		"@earendil-works/pi-ai": ">=1.0.0",
+		"@earendil-works/pi-tui": ">=1.0.0",
 		"@types/node": "^24.13.3",
 		"typescript": "^5.9.3"
 	},
+	"engines": {
+		"node": ">=22.19.0"
+	},
 	"packageManager": "pnpm@11.1.1"
 }

package/runtime/gentle-shell-launcher.mjs

@@ -195,6 +195,16 @@ function linkDir(env                                    , homedir        )
 	return env.PI_CODING_AGENT_DIR || join(homedir, ".pi", "agent");
 }
 
+// The isolated home replaces PI_CODING_AGENT_DIR for the whole session, so the
+// user's own Pi home travels in this variable for read-only features such as
+// /gentle:stats. An inherited value wins: a gentle-shell launched from inside
+// a Gentle Shell session sees the outer isolated home as PI_CODING_AGENT_DIR.
+export const USER_PI_HOME_ENV = "GENTLE_SHELL_USER_PI_HOME";
+
+export function userPiHome(env                                    , homedir        )         {
+	return env[USER_PI_HOME_ENV] || linkDir(env, homedir);
+}
+
 function isolatedDir(env                                    , homedir        )         {
 	return env.GENTLE_SHELL_HOME || join(homedir, ".gentle-shell", "agent");
 }
@@ -380,7 +390,7 @@ export function missingPiMessage()         {
 
 // --- pi version gate ---------------------------------------------------------
 
-export const MIN_PI_VERSION = "0.85.1";
+export const MIN_PI_VERSION = "0.99.1";
 
 
 
@@ -875,18 +885,13 @@ export function discoverLooseExtensionEntries(dir        , fs                  )
 
 
 
-function packageRootAssetArgs(packageRoot        )           {
-	return ["--theme", join(packageRoot, "themes"), "--skill", join(packageRoot, "skills"), "--prompt-template", join(packageRoot, "prompts")];
-}
 
-function packageRootInjectionArgs(packageRoot        )           {
-	return ["-e", packageRoot, ...packageRootAssetArgs(packageRoot)];
-}
+
 
 // Four cases, checked in this order — `piSubcommand` first, then `takeOver`:
 //   - piSubcommand: pi dispatches install/remove/uninstall/update/list/
 //     config/auth on argv[0] before it even parses flags, so any injected
-//     -e/--theme/--skill/--prompt-template flag ahead of it stops pi from
+//     -e flag ahead of it stops pi from
 //     recognising its subcommand at all — this is exactly the observed
 //     2026-09-22 bug where `gentle-shell install npm:x` opened an
 //     interactive pi session instead of running the package manager. No
@@ -909,7 +914,8 @@ function packageRootInjectionArgs(packageRoot        )           {
 //     (R3-001): a loose entry that duplicates an other-package path, or
 //     repeats within looseExtensionEntries itself, is skipped rather than
 //     loaded twice.
-//   - Not takeOver, no declaration: inject this launcher's own packageRoot,
+//   - Not takeOver, no declaration: inject this launcher's own packageRoot
+//     once via -e; Pi discovers its extensions, skills, prompts and themes,
 //     exactly as when nothing else in settings loads gentle-pi.
 //   - Not takeOver, with a declaration: no injection at all — the target
 //     settings already load a gentle-pi the launcher accepts as-is (the
@@ -940,9 +946,9 @@ export function buildPiInvocation(input                        )               {
 			injected.add(input.packageRoot);
 			args.push("-e", input.packageRoot);
 		}
-		args.push(...packageRootAssetArgs(input.packageRoot));
+
 	} else if (input.declaration === undefined) {
-		args.push(...packageRootInjectionArgs(input.packageRoot));
+		args.push("-e", input.packageRoot);
 	}
 
 	args.push(...input.passthrough);
@@ -950,7 +956,12 @@ export function buildPiInvocation(input                        )               {
 	return {
 		command: input.runtime.command,
 		args,
-		env: { ...input.baseEnv, PI_CODING_AGENT_DIR: input.home.dir, GENTLE_PI_AGENT_HOME: input.home.dir },
+		env: {
+			...input.baseEnv,
+			PI_CODING_AGENT_DIR: input.home.dir,
+			GENTLE_PI_AGENT_HOME: input.home.dir,
+			[USER_PI_HOME_ENV]: userPiHome(input.baseEnv, input.homedir),
+		},
 	};
 }
 

package/runtime/gentle-shell-resume-hint.mjs

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