gentle-pi 3.7.0 → 4.0.0

package/lib/gentle-ai-renderer.ts

@@ -1,7 +1,9 @@
 import { keyHint, type AgentToolResult } from "@earendil-works/pi-coding-agent";
-import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
-import { CARD_TONE, cardBottom, cardInnerWidth, cardLine, cardTop, type Card, type CardTheme, type CardTone } from "./shell-card.ts";
-import { sanitizeTerminalText } from "./terminal-theme.ts";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { type GentleAiTimingLookup } from "./gentle-ai-elapsed-store.ts";
+import { CARD_TONE, cardBodyRows, cardBottom, cardInnerWidth, cardLine, cardTop, floatRows, type Card, type CardTheme, type CardTone } from "./shell-card.ts";
+import { formatElapsed } from "./agents-widget.ts";
+import { sanitizeTerminalText, stripAnsi } from "./terminal-theme.ts";
 
 // Gentle AI tool cards: every call into the gentle-ai binary and every
 // gentle_review tool draws the same card as the other Gentle notices. The
@@ -18,6 +20,14 @@ export interface GentleAiRenderState {
 	 * call (which pi never marks as started) still shows its outcome. */
 	finished?: boolean;
 	failed?: boolean;
+	/** Wall-clock ms of the first LIVE non-terminal observation — replays never
+	 * stamp a start — and of the terminal freeze, so a replayed row still shows
+	 * the true call duration. */
+	startedAt?: number;
+	endedAt?: number;
+	/** The row's single pending live-duration wake-up. Every render used to stack
+	 * another untracked timer; a terminal render must leave none behind. */
+	pendingTimer?: ReturnType<typeof setTimeout>;
 }
 
 export interface GentleAiRenderContext {
@@ -29,6 +39,11 @@ export interface GentleAiRenderContext {
 	lastComponent?: unknown;
 	state?: unknown;
 	invalidate?: () => void;
+	/** pi's stable id for this tool execution; keys the durable timing lookup. */
+	toolCallId?: string;
+	/** Durable timing source (session entries). pi's row `state` is render-local,
+	 * so only this survives the fresh state a historical replay constructs. */
+	elapsedTiming?: GentleAiTimingLookup;
 }
 
 const LIFECYCLE_STATUS = {
@@ -47,13 +62,28 @@ const STATUS_TONE: Record<LifecycleStatus, CardTone> = {
 	[LIFECYCLE_STATUS.FAILED]: CARD_TONE.ERROR,
 };
 
-const CARD_TITLE = "Gentle AI";
-// The binary keeps its rose; Gentle Shell notices keep the flower.
-const CARD_GLYPH = "\u{1F339}\uFE0E";
+// The title reads like the quiet read card: a short name, then the operation
+// as its argument. Review operations are `rdd <op>`; any other binary call
+// is `gentle-ai <op>`.
+const REVIEW_PREFIX = "review";
+const REVIEW_TITLE = "rdd";
+const BINARY_TITLE = "gentle-ai";
+const SEPARATOR = " · ";
+// The binary keeps its rose as a colored emoji (2 cells, no text-presentation
+// selector); Gentle Shell notices keep the flower.
+const CARD_GLYPH = "\u{1F339}";
 const DETAIL_ROLE = "dim";
-const HIDDEN_ROLE = "dim";
 const passthroughTheme: CardTheme = { fg: (_color, text) => text };
 
+// The running/failed state stays visible until the call completes.
+function callTitle(status: LifecycleStatus, operationPath: string): string {
+	const review = operationPath === REVIEW_PREFIX || operationPath.startsWith(`${REVIEW_PREFIX} `);
+	const name = review ? REVIEW_TITLE : BINARY_TITLE;
+	const operation = review ? operationPath.slice(REVIEW_PREFIX.length).trim() : operationPath;
+	const argument = [status === LIFECYCLE_STATUS.COMPLETED ? "" : status, operation].filter((part) => part.length > 0).join(SEPARATOR);
+	return argument.length > 0 ? `${name} ${argument}` : name;
+}
+
 export function getGentleAiRenderState(state: unknown): GentleAiRenderState | undefined {
 	if (!state || typeof state !== "object" || Array.isArray(state)) return undefined;
 	const rowState = state as Record<string, unknown>, existing = rowState.gentleAiRender;
@@ -68,65 +98,140 @@ export function getGentleAiRenderState(state: unknown): GentleAiRenderState | un
 // also closes the frame, because no result row exists yet; once a final
 // result is in, the result card closes it instead.
 export class GentleAiCallCard {
-	private card: Card = { title: CARD_TITLE, body: [], tone: CARD_TONE.WARNING };
+	private card: Card = { title: REVIEW_TITLE, body: [], tone: CARD_TONE.WARNING, glyph: CARD_GLYPH };
 	private theme: GentleAiRenderTheme = passthroughTheme;
 	private detail: string | undefined;
 	private hint: string | undefined;
+	private elapsed = "";
 	private open = true;
 
-	update(status: LifecycleStatus, operationPath: string, theme: GentleAiRenderTheme, detail?: string, hint?: string): void {
-		this.card = { title: CARD_TITLE, subtitle: `${status} · ${operationPath}`, body: [], tone: STATUS_TONE[status], glyph: CARD_GLYPH };
+	update(status: LifecycleStatus, operationPath: string, theme: GentleAiRenderTheme, detail?: string, hint?: string, elapsed?: string): void {
+		this.card = { title: callTitle(status, operationPath), body: [], tone: STATUS_TONE[status], glyph: CARD_GLYPH };
 		this.theme = theme;
 		this.detail = detail;
 		this.hint = hint;
+		this.elapsed = elapsed ?? "";
 		this.open = status === LIFECYCLE_STATUS.RUNNING || status === LIFECYCLE_STATUS.PREPARING;
 	}
 
 	render(width: number): string[] {
-		const lines = [cardTop(this.card, this.theme, width, this.hint)];
-		if (this.detail) lines.push(cardLine(this.theme.fg(DETAIL_ROLE, this.detail), this.card.tone, this.theme, width));
-		if (this.open) lines.push(cardBottom(this.card.tone, this.theme, width));
-		return lines;
+		if (width <= 0) return [];
+		// The command detail belongs to the heading; the result below owns the body.
+		return floatRows(this.card.tone, this.theme, width, (inner) => ({
+			head: [cardTop(this.card, this.theme, inner, this.hint), ...(this.detail ? [cardLine(this.theme.fg(DETAIL_ROLE, this.detail), this.card.tone, this.theme, inner)] : [])],
+			bottom: this.open ? cardBottom(this.card.tone, this.theme, inner, this.elapsed || undefined) : undefined,
+		}));
 	}
 
 	invalidate(): void {}
 }
 
-// The result rows: the body when expanded, a count-only line when collapsed
-// (the call card carries the expand key and the text stays hidden), and
+// JSON envelopes collapse to one human line built from these fields, in this
+// order, looked up at the top level and then inside `result`. Each group
+// contributes its first present value. Schemas, hashes, bindings and command
+// strings are never listed, so they never reach the summary.
+const SUMMARY_FIELD_GROUPS: readonly (readonly string[])[] = [
+	["status", "state"],
+	["outcome"],
+	["risk", "risk_tier", "riskLevel"],
+	["action", "provider_action"],
+	["next_transition.reason_code", "nextTransition.reasonCode", "next_transition", "nextTransition", "reason_code", "reasonCode", "diagnostics.error_code"],
+	["diagnostics.message", "diagnostics.stderr", "error.message", "error", "reasons.0.detail", "reason", "message"],
+];
+const HASH_PATTERN = /^(?:sha256:)?[0-9a-f]{32,}$/i;
+
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseJsonObject(text: string): Record<string, unknown> | undefined {
+	const trimmed = text.trim();
+	if (!trimmed.startsWith("{")) return undefined;
+	try {
+		const value: unknown = JSON.parse(trimmed);
+		return isJsonObject(value) ? value : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function fieldAt(source: Record<string, unknown>, path: string): unknown {
+	let value: unknown = source;
+	for (const key of path.split(".")) {
+		if (Array.isArray(value)) value = value[Number(key)];
+		else if (isJsonObject(value)) value = value[key];
+		else return undefined;
+	}
+	return value;
+}
+
+// One readable clause: first line, first sentence part, no nested "Error: "
+// prefixes, and no control characters decoded from JSON escapes.
+function summaryValue(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const clause = sanitizeTerminalText(value).split("\n")[0]!.split("; ")[0]!
+		.replace(/(^|: )\w*Error: /g, "$1").replace(/\s+/g, " ").trim();
+	return clause.length > 0 && !HASH_PATTERN.test(clause) ? clause : undefined;
+}
+
+export function summarizeJsonEnvelope(envelope: Record<string, unknown>): string {
+	const scopes = isJsonObject(envelope.result) ? [envelope, envelope.result] : [envelope];
+	const parts: string[] = [];
+	for (const group of SUMMARY_FIELD_GROUPS) {
+		const found = scopes.flatMap((scope) => group.map((path) => summaryValue(fieldAt(scope, path)))).find((part) => part !== undefined);
+		if (found !== undefined && !parts.includes(found)) parts.push(found);
+	}
+	if (parts.length > 0) return parts.join(SEPARATOR);
+	const count = Object.keys(envelope).length;
+	return `${count} ${count === 1 ? "field" : "fields"}`;
+}
+
+// The result rows: complete output when expanded, a useful bounded preview
+// when collapsed (the call card carries the expand key), and
 // always the bottom rule that closes the frame. The rail follows the outcome:
-// amber while partial, green when done, red on error.
+// amber while partial, green when done, red on error. A JSON envelope
+// collapses to one summary row and expands pretty-printed.
 export class GentleAiResultCard {
 	private readonly text: string;
+	private readonly envelope: Record<string, unknown> | undefined;
 	private readonly expanded: boolean;
 	private readonly tone: CardTone;
 	private readonly theme: GentleAiRenderTheme;
 	private readonly partial: boolean;
+	private readonly elapsed: string;
 
-	constructor(text: string, expanded: boolean, tone: CardTone, theme: GentleAiRenderTheme, partial = false) {
-		this.text = text;
+	constructor(text: string, expanded: boolean, tone: CardTone, theme: GentleAiRenderTheme, partial = false, elapsed = "") {
+		this.envelope = parseJsonObject(text);
+		this.text = this.envelope !== undefined && expanded ? JSON.stringify(this.envelope, null, 2) : text;
 		this.expanded = expanded;
 		this.tone = tone;
 		this.theme = theme;
 		this.partial = partial;
+		this.elapsed = elapsed;
 	}
 
 	render(width: number): string[] {
-		const lines: string[] = [];
-		if (this.text.length > 0) {
-			if (this.expanded) {
-				const innerWidth = cardInnerWidth(width);
-				for (const raw of this.text.split("\n")) {
-					for (const line of raw === "" ? [""] : wrapTextWithAnsi(raw, innerWidth)) lines.push(cardLine(line, this.tone, this.theme, width));
-				}
-			} else {
-				const count = this.text.split("\n").length;
-				lines.push(cardLine(this.theme.fg(HIDDEN_ROLE, `${count} ${count === 1 ? "line" : "lines"}`), this.tone, this.theme, width));
-			}
+		if (width <= 0) return [];
+		const role = this.tone === CARD_TONE.ERROR ? "error" : "toolOutput";
+		// A partial result sits under a running call card, which still closes the
+		// frame; there, the call's closing row already separates the body.
+		return floatRows(this.tone, this.theme, width, (inner) => ({
+			body: this.body(inner, role),
+			bottom: this.partial ? undefined : cardBottom(this.tone, this.theme, inner, this.elapsed || undefined),
+			afterHeading: !this.partial,
+		}));
+	}
+
+	private body(width: number, role: string): string[] {
+		if (this.envelope !== undefined && !this.expanded) {
+			const summary = truncateToWidth(summarizeJsonEnvelope(this.envelope), cardInnerWidth(width), "…");
+			return [cardLine(this.theme.fg(role, summary), this.tone, this.theme, width)];
 		}
-		// A partial result sits under a running call card, which still closes the frame.
-		if (!this.partial) lines.push(cardBottom(this.tone, this.theme, width));
-		return lines;
+		const rows = this.text.length > 0 ? this.text.split("\n") : [];
+		const useful = this.expanded ? rows : rows.filter((row) => stripAnsi(row).trim().length > 0);
+		return cardBodyRows(useful.map((row) => this.theme.fg(role, row)), this.tone, this.theme, width, {
+			expanded: this.expanded, previewRows: 3,
+		});
 	}
 
 	invalidate(): void {}
@@ -146,18 +251,22 @@ export function renderGentleAiResult(
 ): GentleAiResultCard {
 	const textItems = result.content.flatMap((content) => (content.type === "text" ? [sanitizeTerminalText(content.text)] : []));
 	const text = textItems.some((item) => item.length > 0) ? textItems.join("\n") : "";
-	const tone = options.isError ? CARD_TONE.ERROR : options.isPartial ? CARD_TONE.WARNING : CARD_TONE.SUCCESS;
+	const isError = context?.isError ?? options.isError ?? false;
+	const tone = isError ? CARD_TONE.ERROR : options.isPartial ? CARD_TONE.WARNING : CARD_TONE.SUCCESS;
 	const state = getGentleAiRenderState(context?.state);
+	// The frozen duration rides the closing rule, right-aligned.
+	let elapsed: string | undefined;
+	if (state?.startedAt !== undefined && state.endedAt !== undefined) elapsed = formatElapsed(state.endedAt - state.startedAt);
 	if (state && options.isPartial !== true) {
-		const changed = state.finished !== true || state.failed !== (options.isError === true);
+		const changed = state.finished !== true || state.failed !== isError;
 		state.finished = true;
-		state.failed = options.isError === true;
+		state.failed = isError;
 		// pi's invalidate re-runs the tool display synchronously; called from
 		// inside this render it would nest a second call+result pair into the
 		// same container. Deferring it keeps one frame per execution.
 		if (changed) queueMicrotask(() => context?.invalidate?.());
 	}
-	return new GentleAiResultCard(text, options.expanded === true, tone, theme, options.isPartial === true);
+	return new GentleAiResultCard(text, options.expanded === true, tone, theme, options.isPartial === true, elapsed ?? "");
 }
 
 export function renderGentleAiLifecycleCall(
@@ -165,10 +274,24 @@ export function renderGentleAiLifecycleCall(
 	theme: GentleAiRenderTheme,
 	context?: GentleAiRenderContext,
 	detail?: string,
+	now: number = Date.now(),
 ): GentleAiCallCard {
 	// A finished execution is completed even when pi replays it without
 	// argsComplete (session reload); preparing only applies before it starts.
 	const state = getGentleAiRenderState(context?.state);
+	// Durable timestamps live in session entries; the row state is render-local
+	// and a replay constructs a fresh one. Seed from the durable record for this
+	// tool call; without one the stamps stay unset and the card stays honest.
+	if (state && state.startedAt === undefined && state.endedAt === undefined && typeof context?.toolCallId === "string") {
+		const durable = context.elapsedTiming?.lookup(context.toolCallId);
+		// Only a complete start+end record restores: a start-only record has no
+		// honest duration, and seeding its start would make a replayed card tick
+		// against the replay clock instead of the execution that ended long ago.
+		if (durable?.endedAt !== undefined) {
+			state.startedAt = durable.startedAt;
+			state.endedAt = durable.endedAt;
+		}
+	}
 	const finished = (context?.executionStarted === true && context.isPartial !== true) || state?.finished === true;
 	const failed = context?.isError === true || state?.failed === true;
 	const status: LifecycleStatus = failed
@@ -178,11 +301,45 @@ export function renderGentleAiLifecycleCall(
 			: context?.argsComplete === false
 				? LIFECYCLE_STATUS.PREPARING
 				: LIFECYCLE_STATUS.RUNNING;
+	if (state) {
+		if (status === LIFECYCLE_STATUS.COMPLETED || status === LIFECYCLE_STATUS.FAILED) {
+			// Only a live terminal observation may freeze the end (pi never raises
+			// executionStarted on replayed rows): a replayed start-only record would
+			// otherwise grow an invented end at replay time.
+			if (state.startedAt !== undefined && context?.executionStarted === true) state.endedAt ??= now;
+		} else if ((status === LIFECYCLE_STATUS.RUNNING && context?.argsComplete === true) || context?.executionStarted === true) {
+			// Stamp only on live evidence: a live running row carries argsComplete
+			// (true), while a replayed row omits it entirely — an unexplained RUNNING
+			// on a historical row must not fabricate a start. executionStarted never
+			// fires on replays.
+			state.startedAt ??= now;
+		}
+	}
+	// Elapsed is live from the first observation: every re-render recomputes it
+	// from now, and the terminal freeze keeps the final value stable.
+	const elapsed = state?.startedAt === undefined ? "" : formatElapsed((state.endedAt ?? now) - state.startedAt);
+	// Hint: the expand key only — the elapsed lives on the bottom rule.
+	const expandHint = finished ? stripAnsi(keyHint("app.tools.expand", context?.expanded ? "to collapse" : "to expand")) : undefined;
+	const hint = [expandHint].filter((part): part is string => part !== undefined && part.length > 0).join(" · ");
 	const component = context?.lastComponent instanceof GentleAiCallCard && (!state || state.lifecycleComponent === true)
 		? context.lastComponent
 		: new GentleAiCallCard();
 	if (state) state.lifecycleComponent = true;
-	const hint = finished ? keyHint("app.tools.expand", context?.expanded ? "to collapse" : "to expand") : undefined;
-	component.update(status, operationPath, theme, detail ? sanitizeTerminalText(detail) : undefined, hint);
+	component.update(status, operationPath, theme, detail ? sanitizeTerminalText(detail) : undefined, hint, elapsed);
+	// While the call runs, wake the row once a second so the live duration ticks.
+	// At most one pending timer per row: frequent renders must not stack
+	// independent invalidation chains, and none may outlive the terminal render.
+	if (state) {
+		if (state.pendingTimer !== undefined) clearTimeout(state.pendingTimer);
+		if ((status === LIFECYCLE_STATUS.RUNNING || status === LIFECYCLE_STATUS.PREPARING) && state.startedAt !== undefined && state.endedAt === undefined) {
+			state.pendingTimer = setTimeout(() => {
+				state.pendingTimer = undefined;
+				context?.invalidate?.();
+			}, 1000);
+			state.pendingTimer.unref?.();
+		} else {
+			state.pendingTimer = undefined;
+		}
+	}
 	return component;
 }

package/lib/gentle-shell-launcher.ts

@@ -194,6 +194,16 @@ function linkDir(env: Record<string, string | undefined>, homedir: string): stri
 	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: Record<string, string | undefined>, homedir: string): string {
+	return env[USER_PI_HOME_ENV] || linkDir(env, homedir);
+}
+
 function isolatedDir(env: Record<string, string | undefined>, homedir: string): string {
 	return env.GENTLE_SHELL_HOME || join(homedir, ".gentle-shell", "agent");
 }
@@ -379,7 +389,7 @@ export function missingPiMessage(): string {
 
 // --- pi version gate ---------------------------------------------------------
 
-export const MIN_PI_VERSION = "0.85.1";
+export const MIN_PI_VERSION = "0.99.1";
 
 export type PiVersionCheck = { ok: true; version: string } | { ok: false; message: string; version?: string };
 
@@ -866,6 +876,8 @@ export interface BuildPiInvocationInput {
 	// gentle-pi extension injection below may precede it.
 	piSubcommand?: PiSubcommand;
 	baseEnv: Record<string, string | undefined>;
+	// The OS home behind userPiHome's conventional ~/.pi/agent fallback.
+	homedir: string;
 }
 
 export interface PiInvocation {
@@ -874,18 +886,11 @@ export interface PiInvocation {
 	env: Record<string, string | undefined>;
 }
 
-function packageRootAssetArgs(packageRoot: string): string[] {
-	return ["--theme", join(packageRoot, "themes"), "--skill", join(packageRoot, "skills"), "--prompt-template", join(packageRoot, "prompts")];
-}
-
-function packageRootInjectionArgs(packageRoot: string): string[] {
-	return ["-e", packageRoot, ...packageRootAssetArgs(packageRoot)];
-}
 
 // Four cases, checked in this order — `piSubcommand` first, then `takeOver`:
 //   - piSubcommand: pi dispatches install/remove/uninstall/update/list/
 //     config/auth on argv[0] before it even parses flags, so any injected
-//     -e/--theme/--skill/--prompt-template flag ahead of it stops pi from
+//     -e flag ahead of it stops pi from
 //     recognising its subcommand at all — this is exactly the observed
 //     2026-09-22 bug where `gentle-shell install npm:x` opened an
 //     interactive pi session instead of running the package manager. No
@@ -908,7 +913,8 @@ function packageRootInjectionArgs(packageRoot: string): string[] {
 //     (R3-001): a loose entry that duplicates an other-package path, or
 //     repeats within looseExtensionEntries itself, is skipped rather than
 //     loaded twice.
-//   - Not takeOver, no declaration: inject this launcher's own packageRoot,
+//   - Not takeOver, no declaration: inject this launcher's own packageRoot
+//     once via -e; Pi discovers its extensions, skills, prompts and themes,
 //     exactly as when nothing else in settings loads gentle-pi.
 //   - Not takeOver, with a declaration: no injection at all — the target
 //     settings already load a gentle-pi the launcher accepts as-is (the
@@ -939,9 +945,9 @@ export function buildPiInvocation(input: BuildPiInvocationInput): PiInvocation {
 			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);
@@ -949,7 +955,12 @@ export function buildPiInvocation(input: BuildPiInvocationInput): PiInvocation {
 	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/lib/gentle-shell-resume-hint.ts

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