gentle-pi 4.0.0 → 4.2.0

package/lib/bounded-writer-admission.ts

@@ -1,12 +1,15 @@
 import { realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { isAbsolute, parse, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, parse, relative, resolve } from "node:path";
 import { resolveSessionWorktree, type WorktreeResolver } from "./session-worktree-registry.ts";
 
 const WRITER_NAMES = ["gentle-ai-worker", "worker", "jd-fix-agent"];
 export const WRITER_EDIT_SURFACE_REJECTION =
 	"Writer tasks must include the exact Markdown heading `## Allowed edit surfaces` with narrow repository-relative paths or narrow globs, one per line. Every non-empty line belongs to the section until the next canonical Markdown heading and must be a valid surface entry. Paths containing whitespace require whole-entry backticks; begin explanatory prose under the next Markdown heading. The parent must derive or map that canonical block from the delegated task and relaunch the writer; do not accept aliases, and do not ask the human to author paths or globs.";
-const ALLOWED_EDIT_SURFACES_HEADING = /^## Allowed edit surfaces[ \t]*$/gim;
+// One heading matcher: the parser scans with the global form, and continuation
+// inheritance tests presence with the same source (review R3-003).
+const ALLOWED_EDIT_SURFACES_HEADING_LINE = /^## Allowed edit surfaces[ \t]*$/im;
+const ALLOWED_EDIT_SURFACES_HEADING = new RegExp(ALLOWED_EDIT_SURFACES_HEADING_LINE.source, "gim");
 const MARKDOWN_HEADING_LINE = /^ {0,3}#{1,6} /;
 const MARKDOWN_LIST_MARKER = /^(?:[-*+]|\d+[.)]) +/;
 
@@ -20,7 +23,9 @@ function isTaskScopedRepositoryRelativePath(value: string, backticked: boolean):
 
 // This is the same canonical parser used by both the tool hook and executor.
 // Prose cannot close the section, and repeated sections must agree exactly.
-export function allowedEditSurfaces(...values: unknown[]): string[] | undefined {
+// A rejection carries the concrete problem so the caller repairs only the
+// section instead of re-summarizing the whole task (gentle-shell#1713).
+function parseAllowedEditSurfaces(values: readonly unknown[]): { paths: string[] } | { problem: string } {
 	let expected: string[] | undefined;
 	for (const value of values) {
 		if (typeof value !== "string") continue;
@@ -28,29 +33,71 @@ export function allowedEditSurfaces(...values: unknown[]): string[] | undefined
 			const lines = value.slice((heading.index ?? 0) + heading[0].length).split(/\r?\n/);
 			const end = lines.findIndex(line => MARKDOWN_HEADING_LINE.test(line));
 			const entries = (end === -1 ? lines : lines.slice(0, end)).map(line => line.replace(/ +$/g, "")).filter(Boolean);
-			if (!entries.length) return undefined;
+			if (!entries.length) return { problem: "The section has no entries." };
 			const paths: string[] = [];
 			for (const source of entries) {
 				const line = source.replace(/^ {0,3}/, "");
 				const unlisted = line.replace(MARKDOWN_LIST_MARKER, "");
 				const quoted = unlisted.match(/^`([^`]+)`$/);
 				const path = quoted?.[1] ?? unlisted;
-				if (/^(?:[-*+]|\d+[.)])$/.test(line) || (unlisted.includes("`") && !quoted) || /\p{Cc}|\p{Zl}|\p{Zp}/u.test(source) || !isTaskScopedRepositoryRelativePath(path, !!quoted)) return undefined;
+				if (/^(?:[-*+]|\d+[.)])$/.test(line) || (unlisted.includes("`") && !quoted) || /\p{Cc}|\p{Zl}|\p{Zp}/u.test(source) || !isTaskScopedRepositoryRelativePath(path, !!quoted)) {
+					// Prose and a bad path need different repairs: moving a real surface
+					// out of the section would silently narrow the writer's scope.
+					// An unquoted entry with whitespace that would be valid when quoted is
+					// ambiguous: name both repairs instead of guessing prose.
+					const prose = /^(?:[-*+]|\d+[.)])$/.test(line) || (!quoted && /\p{White_Space}/u.test(unlisted));
+					const quotable = prose && !quoted && !unlisted.includes("`") && !/\p{Cc}|\p{Zl}|\p{Zp}/u.test(source) && isTaskScopedRepositoryRelativePath(unlisted, true);
+					const shown = (prose ? source.trim() : path).replace(/\p{Cc}|\p{Zl}|\p{Zp}/gu, " ");
+					const bounded = shown.length > 120 ? `${shown.slice(0, 120)}...` : shown;
+					return { problem: quotable
+						? `Line "${bounded}" is not a valid surface entry; if it is a path, wrap the whole entry in backticks, otherwise move it under a following Markdown heading.`
+						: prose
+							? `Line "${bounded}" is not a valid surface entry; move prose under a following Markdown heading.`
+							: `Entry "${bounded}" is not a narrow repository-relative path; remove absolute paths, \`..\` segments, root globs, and stray backticks.` };
+				}
 				paths.push(path);
 			}
 			const unique = [...new Set(paths)].sort();
-			if (expected && (expected.length !== unique.length || expected.some((path, index) => path !== unique[index]))) return undefined;
+			if (expected && (expected.length !== unique.length || expected.some((path, index) => path !== unique[index]))) return { problem: "Repeated sections list different surfaces." };
 			expected = unique;
 		}
 	}
-	return expected;
+	return expected ? { paths: expected } : { problem: "No `## Allowed edit surfaces` heading was found." };
+}
+
+export function allowedEditSurfaces(...values: unknown[]): string[] | undefined {
+	const parsed = parseAllowedEditSurfaces(values);
+	return "paths" in parsed ? parsed.paths : undefined;
 }
 
 export function rejectUnscopedBoundedWriterDispatch(input: unknown): { block: true; reason: string } | undefined {
 	if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
 	const record = input as Record<string, unknown>;
 	if (typeof record.agent !== "string" || !WRITER_NAMES.includes(record.agent)) return undefined;
-	return allowedEditSurfaces(record.task, record.context) ? undefined : { block: true, reason: WRITER_EDIT_SURFACE_REJECTION };
+	const parsed = parseAllowedEditSurfaces([record.task, record.context]);
+	if ("paths" in parsed) return undefined;
+	return { block: true, reason: `${WRITER_EDIT_SURFACE_REJECTION} ${parsed.problem} Resend the same task text unchanged except for that section; never shorten or re-summarize it.` };
+}
+
+// A continuation resumes the same delegated task, so a writer follow-up that
+// carries no section of its own inherits the surfaces its original launch was
+// admitted with. A follow-up that carries the heading is validated as written,
+// never merged, and nothing is inherited when the original had no valid section.
+// Judgment Day fix batches keep their own exact dispatch protocol.
+export function inheritAllowedEditSurfaces(agent: string, followUp: string, context: unknown, originalPrompt: string): string {
+	const hasHeading = (value: unknown) => typeof value === "string" && ALLOWED_EDIT_SURFACES_HEADING_LINE.test(value);
+	if (!isGenericBoundedWriter(agent) || hasHeading(followUp) || hasHeading(context)) return followUp;
+	const inherited = allowedEditSurfaces(originalPrompt);
+	if (!inherited) return followUp;
+	// Every inherited entry is backticked: some entries are admitted only when
+	// quoted, and quoting never changes a valid path (review R3-002).
+	return `${followUp}\n\n## Allowed edit surfaces\n${inherited.map(path => `\`${path}\``).join("\n")}\n`;
+}
+
+// Every agent admitted through the `## Allowed edit surfaces` guard, including
+// Judgment Day fix agents; only these claim surfaces at runtime admission.
+export function isBoundedWriter(name: string): boolean {
+	return WRITER_NAMES.includes(name);
 }
 
 export function isGenericBoundedWriter(name: string): boolean {
@@ -67,11 +114,37 @@ export function isDevelopmentSurface(path: string): boolean {
 	return /\.(?:[cm]?[jt]sx?|go|rs|py|java|kt|swift|c|cc|cpp|h|hpp|cs|rb|php|vue|svelte|html|css|scss|sass|sql|sh)$/i.test(normalized) || /^(?:src|lib|tests?|app|packages)\/(?:[^\s]+\/)*\*\*?(?:\/\*)?$/.test(normalized);
 }
 
-export function safeBootstrapDirectory(path: string): string | undefined {
+// Broad folders a user opens by accident. A repository there (or in HOME, or
+// above it) makes every Git call scan the user's whole tree.
+const BROAD_HOME_FOLDER = /^(?:documents|desktop|downloads|onedrive(?: - .+)?)$/i;
+const BROAD_ONEDRIVE_FOLDER = /^(?:documents|desktop)$/i;
+
+export interface BootstrapDirectoryOptions {
+	/** Defaults to the canonical home directory. */
+	readonly home?: string;
+	/** Defaults to `process.platform`; Windows paths compare case-insensitively. */
+	readonly platform?: NodeJS.Platform;
+}
+
+/** True when `path` is HOME, an ancestor of it, or a broad folder directly under it. */
+export function isHomeOrBroadUserDirectory(path: string, options: BootstrapDirectoryOptions = {}): boolean {
+	const platform = options.platform ?? process.platform;
+	const fold = (value: string) => platform === "win32" ? value.toLowerCase() : value;
+	let home: string;
+	try { home = options.home ?? realpathSync.native(homedir()); } catch { return true; }
+	const target = fold(path), canonicalHome = fold(home);
+	const towardHome = relative(target, canonicalHome);
+	if (towardHome === "" || (!isAbsolute(towardHome) && towardHome !== ".." && !towardHome.startsWith("..\\") && !towardHome.startsWith("../"))) return true;
+	const parent = dirname(target);
+	if (parent === canonicalHome) return BROAD_HOME_FOLDER.test(basename(path));
+	return dirname(parent) === canonicalHome && /^onedrive(?: - .+)?$/i.test(basename(parent)) && BROAD_ONEDRIVE_FOLDER.test(basename(path));
+}
+
+export function safeBootstrapDirectory(path: string, options: BootstrapDirectoryOptions = {}): string | undefined {
 	try {
 		if (!isAbsolute(path)) return undefined;
 		const root = realpathSync(path);
-		if (!statSync(root).isDirectory() || root === parse(root).root || root === realpathSync(homedir())) return undefined;
+		if (!statSync(root).isDirectory() || root === parse(root).root || isHomeOrBroadUserDirectory(realpathSync.native(root), options)) return undefined;
 		if (/(^|[\\/])(?:\.ssh|\.credentials|\.aws|\.gnupg|\.config|secrets|credentials|tokens|keychains)(?:[\\/]|$)|(?:^|[\\/])\.env(?:$|[./_-])/i.test(root)) return undefined;
 		return root;
 	} catch { return undefined; }

package/lib/builtin-codemode-optout.ts

@@ -0,0 +1,166 @@
+import { chmodSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join, resolve } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { gentlePiConfigHome } from "./agent-home.ts";
+
+// gentle-pi replaces Pi's replaceable builtin codemode with its compact
+// renderer (lib/codemode-renderer.ts), and Pi warns at every startup when a
+// builtin loses its tool to another extension. Pi's only per-builtin opt-out
+// is a `-builtin:<name>` entry in the settings `extensions` array. The
+// gentle-shell launcher adds it silently to homes it owns (bin/gentle-shell.mjs,
+// #1612); a user-owned Pi home only gets it after the user accepts a
+// one-time prompt, and a declined prompt is remembered per settings file.
+export const BUILTIN_CODEMODE_EXTENSION = "builtin:codemode";
+export const BUILTIN_CODEMODE_OPTOUT_ENTRY = `-${BUILTIN_CODEMODE_EXTENSION}`;
+export const BUILTIN_CODEMODE_OPTOUT_SCHEMA = "gentle-pi.builtin-codemode-optout/v1";
+
+export type BuiltinCodemodeOptOutOutcome =
+	| "no-ui"
+	| "explicit-entry"
+	| "unwritable"
+	| "declined-before"
+	| "accepted"
+	| "declined"
+	| "failed";
+
+export interface BuiltinCodemodeOptOutOptions {
+	/** Pi agent dir whose settings.json receives the entry; defaults to getAgentDir(). */
+	agentDir?: string;
+	/** gentle-pi config home holding the remembered decline; defaults to gentlePiConfigHome(). */
+	configHome?: string;
+	/** Effective (merged) settings `extensions`, e.g. from pi.getSettings(). */
+	effectiveExtensions?: unknown;
+}
+
+export interface BuiltinCodemodeOptOutContext {
+	hasUI: boolean;
+	mode: string;
+	ui: {
+		confirm(title: string, message: string): Promise<boolean>;
+		notify(message: string, type?: "info" | "warning" | "error"): void;
+	};
+}
+
+/** True when `extensions` already holds any explicit (`+`, `-`, `!`, or bare) entry for the builtin. */
+export function hasExplicitBuiltinEntry(extensions: unknown, builtin = BUILTIN_CODEMODE_EXTENSION): boolean {
+	return Array.isArray(extensions) && extensions.some((entry) => typeof entry === "string" && entry.replace(/^[+!-]/, "") === builtin);
+}
+
+// Pure: mirrors withBuiltinExtensionExcluded in bin/gentle-shell.mjs. Returns
+// `settingsText` with `-<builtin>` appended to its `extensions` array (created
+// when absent), or undefined when nothing should change — the text does not
+// parse as a JSON object, `extensions` exists but is not an array, or the
+// array already holds an explicit entry for the builtin, which is the user's
+// own decision. Keeps every other key and entry, the text's indentation, and
+// its trailing newline.
+export function withBuiltinExtensionExcluded(settingsText: string, builtin = BUILTIN_CODEMODE_EXTENSION): string | undefined {
+	let settings: unknown;
+	try {
+		settings = JSON.parse(settingsText);
+	} catch {
+		return undefined;
+	}
+	if (typeof settings !== "object" || settings === null || Array.isArray(settings)) return undefined;
+	const extensions = Object.prototype.hasOwnProperty.call(settings, "extensions") ? (settings as { extensions: unknown }).extensions : [];
+	if (!Array.isArray(extensions) || hasExplicitBuiltinEntry(extensions, builtin)) return undefined;
+	const indent = settingsText.match(/\{\r?\n([ \t]+)/)?.[1];
+	const serialized = JSON.stringify({ ...settings, extensions: [...extensions, `-${builtin}`] }, null, indent);
+	return settingsText.endsWith("\n") ? `${serialized}\n` : serialized;
+}
+
+export function builtinCodemodeOptOutStatePath(configHome = gentlePiConfigHome()): string {
+	return join(configHome, "builtin-codemode-optout.json");
+}
+
+function readIfExists(path: string): string | undefined {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+function readDeclined(configHome: string): string[] {
+	try {
+		const value: unknown = JSON.parse(readIfExists(builtinCodemodeOptOutStatePath(configHome)) ?? "null");
+		if (typeof value !== "object" || value === null || (value as { schema?: unknown }).schema !== BUILTIN_CODEMODE_OPTOUT_SCHEMA) return [];
+		const declined = (value as { declined?: unknown }).declined;
+		return Array.isArray(declined) ? declined.filter((path): path is string => typeof path === "string") : [];
+	} catch { return []; }
+}
+
+/** Same-directory rename prevents readers from seeing a partially written state file. */
+function recordDeclined(configHome: string, settingsPath: string): void {
+	const declined = readDeclined(configHome);
+	if (declined.includes(settingsPath)) return;
+	mkdirSync(configHome, { recursive: true });
+	const path = builtinCodemodeOptOutStatePath(configHome);
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	try {
+		writeFileSync(temporary, `${JSON.stringify({ schema: BUILTIN_CODEMODE_OPTOUT_SCHEMA, declined: [...declined, settingsPath] })}\n`, { flag: "wx", mode: 0o600 });
+		renameSync(temporary, path);
+	} finally {
+		try { unlinkSync(temporary); } catch { /* Rename already consumed the temporary file. */ }
+	}
+}
+
+// Writes through a symlinked settings.json to its real target, so the link
+// stays a link, with the same temp-file-then-rename and file mode as the
+// launcher's writeFileAtomically.
+function writeSettingsAtomically(path: string, data: string): void {
+	const target = realpathSync(path);
+	const mode = statSync(target).mode & 0o777;
+	const temporary = join(dirname(target), `.${basename(target)}.gentle-pi-${randomUUID()}.tmp`);
+	try {
+		writeFileSync(temporary, data, { flag: "wx" });
+		chmodSync(temporary, mode);
+		renameSync(temporary, target);
+	} finally {
+		try { unlinkSync(temporary); } catch { /* Rename already consumed the temporary file. */ }
+	}
+}
+
+function promptMessage(settingsPath: string): string {
+	return [
+		"Pi warns at startup that the builtin codemode extension was not loaded, because gentle-pi replaces it with its compact codemode renderer.",
+		`Adding "${BUILTIN_CODEMODE_OPTOUT_ENTRY}" to the "extensions" list in ${settingsPath} silences that warning from the next launch. gentle-pi keeps its compact codemode either way.`,
+		"Nothing is written unless you accept. If you decline, gentle-pi will not ask again.",
+	].join("\n\n");
+}
+
+// Asks once, in an interactive TUI only, whether to add the opt-out to the
+// agent settings.json, and writes only on acceptance. A missing settings.json
+// is never created: Pi and `pi install` own that file. Never throws.
+export async function offerBuiltinCodemodeOptOut(ctx: BuiltinCodemodeOptOutContext, options: BuiltinCodemodeOptOutOptions = {}): Promise<BuiltinCodemodeOptOutOutcome> {
+	try {
+		if (!ctx.hasUI || ctx.mode !== "tui") return "no-ui";
+		if (hasExplicitBuiltinEntry(options.effectiveExtensions)) return "explicit-entry";
+		const settingsPath = resolve(options.agentDir ?? getAgentDir(), "settings.json");
+		const configHome = options.configHome ?? gentlePiConfigHome();
+		const currentText = readIfExists(settingsPath);
+		if (currentText === undefined) return "unwritable";
+		try {
+			if (hasExplicitBuiltinEntry((JSON.parse(currentText) as { extensions?: unknown } | null)?.extensions)) return "explicit-entry";
+		} catch { /* Malformed JSON is reported as unwritable below. */ }
+		if (withBuiltinExtensionExcluded(currentText) === undefined) return "unwritable";
+		if (readDeclined(configHome).includes(settingsPath)) return "declined-before";
+
+		const accepted = (await ctx.ui.confirm("Silence Pi's builtin codemode warning?", promptMessage(settingsPath))) === true;
+		if (!accepted) {
+			recordDeclined(configHome, settingsPath);
+			ctx.ui.notify(`gentle-pi will not ask again. To silence the warning later, add "${BUILTIN_CODEMODE_OPTOUT_ENTRY}" to "extensions" in ${settingsPath}.`, "info");
+			return "declined";
+		}
+		// The dialog may have stayed open while the file changed; re-read it.
+		const freshText = readIfExists(settingsPath);
+		const newText = freshText === undefined ? undefined : withBuiltinExtensionExcluded(freshText);
+		if (newText === undefined) return "unwritable";
+		writeSettingsAtomically(settingsPath, newText);
+		ctx.ui.notify(`Added "${BUILTIN_CODEMODE_OPTOUT_ENTRY}" to ${settingsPath}. The builtin codemode warning disappears from the next launch.`, "info");
+		return "accepted";
+	} catch {
+		return "failed";
+	}
+}

package/lib/card-content-policy.ts

@@ -0,0 +1,85 @@
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { gentlePiConfigHome } from "./agent-home.ts";
+
+// The conversation card content level chosen in Gentle → Customize. `default`
+// keeps the quiet tools' result previews; `minimal` draws every quiet tool
+// card as the command alone. A missing file means default, so nobody loses the
+// previews without choosing to; a malformed or unreadable one also reads as
+// default, and the writer refuses
+// to replace it so a hand edit is never lost. There is no environment override.
+export const CARD_CONTENT_SCHEMA = "gentle-pi.card-content/v1";
+const CARD_CONTENT_FILE = "card-content.json";
+
+export const CARD_CONTENT = {
+	DEFAULT: "default",
+	MINIMAL: "minimal",
+} as const;
+
+export type CardContent = (typeof CARD_CONTENT)[keyof typeof CARD_CONTENT];
+
+interface CardContentOptions { gentlePiConfigHome?: string }
+
+export interface CardContentResolution {
+	content: CardContent;
+	source: "global_file" | "default";
+	malformed: boolean;
+	globalFile: string;
+}
+
+function isCardContent(value: unknown): value is CardContent {
+	return value === CARD_CONTENT.DEFAULT || value === CARD_CONTENT.MINIMAL;
+}
+
+export function parseCardContentFile(raw: string): CardContent | undefined {
+	try {
+		const value: unknown = JSON.parse(raw);
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+		if (Object.keys(value).length !== 2 || !("schema" in value) || value.schema !== CARD_CONTENT_SCHEMA || !("content" in value)) return undefined;
+		return isCardContent(value.content) ? value.content : undefined;
+	} catch { return undefined; }
+}
+
+export function resolveCardContent(options: CardContentOptions = {}): CardContentResolution {
+	const globalFile = join(options.gentlePiConfigHome ?? gentlePiConfigHome(), CARD_CONTENT_FILE);
+	try {
+		const content = parseCardContentFile(readFileSync(globalFile, "utf8"));
+		return { content: content ?? CARD_CONTENT.DEFAULT, source: "global_file", malformed: content === undefined, globalFile };
+	} catch (error) {
+		const missing = typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+		return { content: CARD_CONTENT.DEFAULT, source: missing ? "default" : "global_file", malformed: !missing, globalFile };
+	}
+}
+
+export function writeCardContent(content: CardContent, options: CardContentOptions = {}): string {
+	if (!isCardContent(content)) throw new TypeError("Invalid card content");
+	const home = options.gentlePiConfigHome ?? gentlePiConfigHome();
+	const current = resolveCardContent({ gentlePiConfigHome: home });
+	if (current.malformed) throw new Error(`Cannot update malformed or unreadable card content preference: ${current.globalFile}`);
+	const path = current.globalFile;
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	mkdirSync(home, { recursive: true });
+	try {
+		writeFileSync(temporary, `${JSON.stringify({ schema: CARD_CONTENT_SCHEMA, content })}\n`, { flag: "wx", mode: 0o600 });
+		renameSync(temporary, path);
+	} finally {
+		try { unlinkSync(temporary); } catch { /* Rename consumed the temporary file. */ }
+	}
+	return path;
+}
+
+// Pi loads every extension with its own module cache, so the renderers in
+// quiet-tools and the customize command in gentle-shell never share a module
+// instance. The process-wide slot keeps one live content level per process,
+// exactly like the card style slot; an unset slot reads as default.
+const CARD_CONTENT_SLOT = Symbol.for("gentle-pi.card-content");
+const contentState = globalThis as typeof globalThis & { [CARD_CONTENT_SLOT]?: unknown };
+
+export function cardContent(): CardContent {
+	return contentState[CARD_CONTENT_SLOT] === CARD_CONTENT.MINIMAL ? CARD_CONTENT.MINIMAL : CARD_CONTENT.DEFAULT;
+}
+
+export function setCardContent(content: CardContent): void {
+	contentState[CARD_CONTENT_SLOT] = content;
+}

package/lib/child-package-injection.ts

@@ -0,0 +1,62 @@
+import { isAbsolute } from "node:path";
+
+// #1690: the gentle-shell launcher injects the gentle-pi package into the
+// parent pi with `-e` instead of a settings declaration, so delegated children
+// would otherwise start without it. The launcher records the exact extension
+// set it injected in this variable; the subagent runner forwards that set to
+// every child. Kept free of launcher imports so the runner can load it cheaply.
+export const CHILD_PACKAGE_INJECTION_ENV = "GENTLE_SHELL_CHILD_PACKAGE_INJECTION";
+
+const CHILD_PACKAGE_INJECTION_VERSION = 1;
+
+export interface ChildPackageInjection {
+	// True for a launcher takeover: the parent ran with --no-extensions, so the
+	// child must too, or settings discovery would load a second gentle-pi.
+	noExtensions: boolean;
+	// Absolute extension paths, in the order the launcher passed them to `-e`.
+	extensionPaths: string[];
+}
+
+export function encodeChildPackageInjection(value: ChildPackageInjection): string {
+	return JSON.stringify({
+		version: CHILD_PACKAGE_INJECTION_VERSION,
+		noExtensions: value.noExtensions,
+		extensionPaths: value.extensionPaths,
+	});
+}
+
+// Returns undefined for an absent or invalid value and never throws: a bad
+// signal must degrade to "no forwarding", not break a child launch. The path
+// flavor is injectable so tests can check Windows paths on any platform.
+export function parseChildPackageInjection(
+	env: Record<string, string | undefined>,
+	pathFlavor: { isAbsolute(path: string): boolean } = { isAbsolute },
+): ChildPackageInjection | undefined {
+	const raw = env[CHILD_PACKAGE_INJECTION_ENV];
+	if (raw === undefined || raw.length === 0) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+	const record = parsed as Record<string, unknown>;
+	if (record.version !== CHILD_PACKAGE_INJECTION_VERSION) return undefined;
+	if (typeof record.noExtensions !== "boolean") return undefined;
+	const paths = record.extensionPaths;
+	if (!Array.isArray(paths) || paths.length === 0) return undefined;
+	const extensionPaths: string[] = [];
+	for (const path of paths) {
+		if (typeof path !== "string" || path.length === 0 || !pathFlavor.isAbsolute(path)) return undefined;
+		extensionPaths.push(path);
+	}
+	return { noExtensions: record.noExtensions, extensionPaths };
+}
+
+// Plain argv elements for a child pi: spawned without a shell, so no quoting.
+export function childPackageExtensionArgs(injection: ChildPackageInjection): string[] {
+	const args = injection.noExtensions ? ["--no-extensions"] : [];
+	for (const path of injection.extensionPaths) args.push("--extension", path);
+	return args;
+}

package/lib/codemode-renderer.ts

@@ -9,8 +9,8 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { getCapabilities, imageFallback, type Component } from "@earendil-works/pi-tui";
 import {
-	CARD_TONE, cardAwaitingResult, cardBodyRows, cardBottom, cardLine, cardRunningLine, cardTop, floatRows, markCardResult,
-	type CardRowContext, type CardTheme, type CardTone,
+	CARD_TONE, cardAwaitingResult, cardBodyRows, cardBottom, cardLine, cardRunningLine, cardStyle, cardTop, floatRows, markCardResult,
+	type CardRowContext, type CardStyle, type CardTheme, type CardTone,
 } from "./shell-card.ts";
 import { sanitizeTerminalText, stripAnsi } from "./terminal-theme.ts";
 
@@ -87,6 +87,8 @@ class CodemodeCard implements Component {
 	private readonly afterBody: boolean;
 	// The call card's render context: until a result exists, the call closes the frame.
 	private readonly row?: CardRowContext;
+	// Content and expansion belong to this component; only layout and row state can change.
+	private cachedFrame?: { width: number; style: CardStyle; running: boolean; lines: string[] };
 
 	constructor(theme: CardTheme, tone: CardTone, body: (width: number) => string[], top: boolean, hint?: string, afterBody = false, row?: CardRowContext) {
 		this.theme = theme;
@@ -102,15 +104,23 @@ class CodemodeCard implements Component {
 		const target = Math.max(0, Math.floor(width));
 		if (target === 0) return [];
 		const running = this.top && this.row !== undefined && cardAwaitingResult(this.row);
-		return floatRows(this.tone, this.theme, target, (inner) => ({
+		const style = cardStyle();
+		if (this.cachedFrame?.width === target && this.cachedFrame.style === style && this.cachedFrame.running === running) {
+			return this.cachedFrame.lines;
+		}
+		const lines = floatRows(this.tone, this.theme, target, (inner) => ({
 			head: this.top ? [cardTop({ title: "Code", glyph: "λ", body: [], tone: this.tone }, this.theme, inner, this.hint)] : [],
 			body: running ? [...this.body(inner), cardRunningLine(this.tone, this.theme, inner)] : this.body(inner),
 			bottom: this.top && !running ? undefined : cardBottom(this.tone, this.theme, inner),
 			afterHeading: !this.top && !this.afterBody,
 		}));
+		this.cachedFrame = { width: target, style, running, lines };
+		return lines;
 	}
 
-	invalidate(): void {}
+	invalidate(): void {
+		this.cachedFrame = undefined;
+	}
 }
 
 /** Replace presentation only: execute, schema and every loadout/exposure field retain their references. */

package/lib/command-palette-catalog.ts

@@ -26,7 +26,7 @@ export const COMMAND_PALETTE_CATALOG: readonly CommandPaletteCatalogGroup[] = [
 			{ command: "gentle:review-mode", label: "Review mode (receipt-driven development)" },
 			{ command: "gentle:background-subagents", label: "Background subagents" },
 			{ command: "gentle:double-esc-cancel", label: "Require double Esc to cancel" },
-			{ command: "gentle:customize", label: "Visual customization" },
+			{ command: "gentle:customize", label: "Customization · appearance + audio notifications" },
 			{ command: "gentle:animations", label: "Animation mode" },
 			{ command: "gentle:vim", label: "Vim opt-in · Pi slash commands" },
 			{ command: "gentle:telemetry", label: "Telemetry" },
@@ -41,8 +41,9 @@ export const COMMAND_PALETTE_CATALOG: readonly CommandPaletteCatalogGroup[] = [
 		title: "Session",
 		items: [
 			{ command: "gentle:yolo", label: "🚀 YOLO 🔥 session permission" },
-			{ command: "gentle:changes", label: "Browse captured changes" },
+			{ command: "gentle:changes", label: "Browse changes" },
 			{ command: "gentle:agents", label: "Subagents" },
+			{ command: "gentle:jobs", label: "Background jobs" },
 			{ command: "gentle:usage", label: "Subscription usage" },
 			{ command: "gentle:review-session-permission", label: "Review session permission" },
 		],

package/lib/context-threshold.ts

@@ -0,0 +1,26 @@
+/**
+ * Fixed product threshold for the high-context warning. The latch lives outside
+ * the notification and visual stores so both warnings share one episode.
+ */
+export const CONTEXT_HIGH_PERCENT = 90;
+
+/**
+ * One warning per high episode. `observe` returns true exactly once while usage
+ * stays at or above the threshold; a finite reading below it rearms the latch.
+ * An unknown reading (`null`, which Pi reports right after a successful
+ * compaction until the next assistant response) preserves the latch so the same
+ * episode cannot warn twice. A successful compaction or a new session calls
+ * `rearm` explicitly; a canceled or failed compaction must not, because the
+ * context was never reduced.
+ */
+export class ContextHighLatch {
+	private high = false;
+	observe(percent: number | null | undefined): boolean {
+		if (typeof percent !== "number" || !Number.isFinite(percent)) return false;
+		if (percent < CONTEXT_HIGH_PERCENT) { this.high = false; return false; }
+		if (this.high) return false;
+		this.high = true;
+		return true;
+	}
+	rearm(): void { this.high = false; }
+}