gentle-pi 3.7.0 → 4.1.0

package/lib/bounded-writer-admission.ts

@@ -0,0 +1,220 @@
+import { realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+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.";
+// 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+[.)]) +/;
+
+function isTaskScopedRepositoryRelativePath(value: string, backticked: boolean): boolean {
+	const normalized = value.replace(/\\/g, "/");
+	if (!normalized || isAbsolute(value) || /^(?:[A-Za-z]:|\/|~)/.test(normalized) || /\p{Cc}|\p{Zl}|\p{Zp}/u.test(normalized) || (/\p{White_Space}/u.test(normalized) && !backticked)) return false;
+	const path = normalized.replace(/^(?:\.\/)+/, "");
+	if (!path || path === "." || path.startsWith("/") || path.split("/").some(segment => segment === "..")) return false;
+	return !/[?*\[\]{}]/.test(path.split("/")[0]);
+}
+
+// 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.
+// 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;
+		for (const heading of value.matchAll(ALLOWED_EDIT_SURFACES_HEADING)) {
+			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 { 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)) {
+					// 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 { problem: "Repeated sections list different surfaces." };
+			expected = unique;
+		}
+	}
+	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;
+	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 {
+	return name === "gentle-ai-worker" || name === "worker";
+}
+
+// Source authorization is structural, never inferred from task prose. Deliberately
+// exclude documentation, memory, harness metadata and configuration-only scopes.
+export function isDevelopmentSurface(path: string): boolean {
+	const normalized = path.replace(/\\/g, "/").replace(/^(?:\.\/)+/, "");
+	if (normalized.split("/").some(part => /^(?:\.|\.\.|odd|docs?|memory|secrets|credentials|tokens|keychains|\.pi|\.agents|\.atl|\.git|\.config|\.ssh|\.aws|\.gnupg|\.credentials)$/i.test(part))) return false;
+	if (/(^|\/)\w[\w.-]*\.config\.[cm]?[jt]s$/i.test(normalized)) return false;
+	if (/(^|\/)\.env(?:$|[./_-])|\.(?:pem|key|p12|pfx)$/i.test(normalized)) return false;
+	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);
+}
+
+// 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 || 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; }
+}
+
+export function sourcePathWithinProject(path: string, cwd: string): string | undefined {
+	const root = safeBootstrapDirectory(cwd);
+	if (!root) return undefined;
+	try {
+		const file = realpathSync(resolve(cwd, path.replace(/^@/, "").replace(/^~(?=\/|$)/, homedir())));
+		const within = relative(root, file);
+		if (isAbsolute(within) || within === ".." || within.startsWith("../") || within.startsWith("..\\") || !isDevelopmentSurface(within)) return undefined;
+		return root;
+	} catch { return undefined; }
+}
+
+// Capture synchronously before startup's first await. Once a clone is observed,
+// its absence or replacement is drift, never permission to initialize again.
+export function sessionRepositoryAuthority(cwd: string, resolver: WorktreeResolver = resolveSessionWorktree): () => boolean {
+	const initial = resolver(cwd, cwd);
+	let established = initial && { ...initial };
+	return () => {
+		const current = resolver(cwd, cwd);
+		if (established) return current?.root === established.root && current?.commonDir === established.commonDir;
+		if (current) established = { ...current };
+		return true;
+	};
+}
+
+interface SessionOwner { getSessionId(): string; getCwd?(): string }
+type Preparation = (root: string, current: () => boolean, signal?: AbortSignal) => Promise<boolean>;
+interface Binding { id: string; cwd: string; prepare: Preparation; current(): boolean; pending?: Promise<boolean> }
+const preparations = new WeakMap<SessionOwner, Binding>();
+const preparationOwners = new WeakSet<SessionOwner>();
+
+// Session-bound callback, not a target authorization cache. Native policy and
+// metadata checks remain in the native extension. Unbind only our incarnation.
+export function bindSessionRepositoryPreparation(manager: SessionOwner, cwd: string, prepare: Preparation, live: () => boolean): () => void {
+	const authorityCurrent = sessionRepositoryAuthority(cwd);
+	const binding: Binding = { id: manager.getSessionId(), cwd, prepare, current: () => live() && manager.getSessionId() === binding.id && (manager.getCwd?.() ?? cwd) === cwd && authorityCurrent() };
+	preparationOwners.add(manager);
+	preparations.set(manager, binding);
+	return () => { if (preparations.get(manager) === binding) preparations.delete(manager); };
+}
+
+// Pin the exact incarnation before awaiting native mode. An absent binding is
+// compatible only for never-bound callers, not a previously revoked owner.
+export function captureBoundSessionRepositoryAuthority(manager: SessionOwner, cwd: string): () => boolean {
+	const binding = preparations.get(manager);
+	const id = manager.getSessionId();
+	return () => manager.getSessionId() === id && (manager.getCwd?.() ?? cwd) === cwd &&
+		preparations.get(manager) === binding && (binding
+			? binding.cwd === cwd && binding.current()
+			: !preparationOwners.has(manager));
+}
+
+export function boundSessionRepositoryAuthorityCurrent(manager: SessionOwner, cwd: string): boolean {
+	return captureBoundSessionRepositoryAuthority(manager, cwd)();
+}
+
+export async function prepareBoundSessionRepository(manager: SessionOwner, cwd: string, signal?: AbortSignal): Promise<boolean> {
+	const binding = preparations.get(manager);
+	const current = () => preparations.get(manager) === binding && !!binding?.current() && !signal?.aborted;
+	if (!binding || binding.cwd !== cwd || !current()) return false;
+	const root = safeBootstrapDirectory(cwd);
+	if (!root) return false;
+	if (!binding.pending) {
+		binding.pending = binding.prepare(root, current, signal);
+		binding.pending.finally(() => { binding.pending = undefined; }).catch(() => {});
+	}
+	try { return await binding.pending && current() && safeBootstrapDirectory(cwd) === root; }
+	catch { return false; }
+}

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/card-style-policy.ts

@@ -0,0 +1,60 @@
+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";
+import { CARD_STYLE, type CardStyle } from "./shell-card.ts";
+
+// The conversation card style chosen in Gentle → Customize. A missing file
+// means the borderless float style; a malformed or unreadable one also reads
+// as float, and the writer refuses to replace it so a hand edit is never lost.
+// There is no environment override.
+export const CARD_STYLE_SCHEMA = "gentle-pi.card-style/v1";
+const CARD_STYLE_FILE = "card-style.json";
+interface CardStyleOptions { gentlePiConfigHome?: string }
+export interface CardStyleResolution {
+	style: CardStyle;
+	source: "global_file" | "default";
+	malformed: boolean;
+	globalFile: string;
+}
+
+function isCardStyle(value: unknown): value is CardStyle {
+	return value === CARD_STYLE.NEON || value === CARD_STYLE.FLOAT;
+}
+
+export function parseCardStyleFile(raw: string): CardStyle | 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_STYLE_SCHEMA || !("style" in value)) return undefined;
+		return isCardStyle(value.style) ? value.style : undefined;
+	} catch { return undefined; }
+}
+
+export function resolveCardStyle(options: CardStyleOptions = {}): CardStyleResolution {
+	const globalFile = join(options.gentlePiConfigHome ?? gentlePiConfigHome(), CARD_STYLE_FILE);
+	try {
+		const style = parseCardStyleFile(readFileSync(globalFile, "utf8"));
+		return { style: style ?? CARD_STYLE.FLOAT, source: "global_file", malformed: style === undefined, globalFile };
+	} catch (error) {
+		const missing = typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+		return { style: CARD_STYLE.FLOAT, source: missing ? "default" : "global_file", malformed: !missing, globalFile };
+	}
+}
+
+export function writeCardStyle(style: CardStyle, options: CardStyleOptions = {}): string {
+	if (!isCardStyle(style)) throw new TypeError("Invalid card style");
+	const home = options.gentlePiConfigHome ?? gentlePiConfigHome();
+	const current = resolveCardStyle({ gentlePiConfigHome: home });
+	if (current.malformed) throw new Error(`Cannot update malformed or unreadable card style preference: ${current.globalFile}`);
+	const path = current.globalFile;
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	mkdirSync(home, { recursive: true });
+	try {
+		writeFileSync(temporary, `${JSON.stringify({ schema: CARD_STYLE_SCHEMA, style })}\n`, { flag: "wx", mode: 0o600 });
+		renameSync(temporary, path);
+	} finally {
+		try { unlinkSync(temporary); } catch { /* Rename consumed the temporary file. */ }
+	}
+	return path;
+}