gentle-pi 3.5.1 → 3.7.0

package/extensions/gentle-ai.ts

@@ -1,6 +1,5 @@
 import { consumeReviewMutation, pendingReviewMutation, recordReviewMutation } from "../lib/review-reminder-receipt.ts";
 import { resolveSessionWorktree } from "../lib/session-worktree-registry.ts";
-import { OddRuntimeDelegationGate } from "../lib/odd-runtime-delegation-gate.ts";
 import { resolveResearchCapabilities, renderResearchCapabilities } from "../lib/sdd-research-capabilities.ts";
 import { declareReviewRelayHandshake } from "../lib/review-relay-contract.ts";
 import { execFileSync } from "node:child_process";
@@ -8,12 +7,10 @@ import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import {
 	existsSync,
 	lstatSync,
-	mkdtempSync,
 	mkdirSync,
 	readdirSync,
 	readFileSync,
 	realpathSync,
-	rmSync,
 	writeFileSync,
 } from "node:fs";
 import {
@@ -23,7 +20,7 @@ import {
 	readdir,
 	writeFile,
 } from "node:fs/promises";
-import { homedir, tmpdir } from "node:os";
+import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
@@ -197,7 +194,7 @@ import {
 	nativeReviewLegacyQuarantineAuthorization,
 	nativeReviewReconcileAuthorization,
 	nativeReviewRecoverAuthorization,
-	normalizeNativeReviewCwd,
+
 	NativeReviewCliError,
 	nativeUntrackedSelection,
 	NativeReviewConsentBindingError,
@@ -2439,24 +2436,6 @@ function builtinAgentDirs(cwd: string): string[] {
 	];
 }
 
-function listBuiltinAgentNames(cwd: string): Set<string> {
-	return new Set(
-		builtinAgentDirs(cwd).flatMap((dir) =>
-			listAgentsFromDir(dir, "builtin").map((agent) => agent.name),
-		),
-	);
-}
-
-async function listBuiltinAgentNamesAsync(cwd: string): Promise<Set<string>> {
-	const names = new Set<string>();
-	for (const dir of builtinAgentDirs(cwd)) {
-		for (const agent of await listAgentsFromDirAsync(dir, "builtin")) {
-			names.add(agent.name);
-		}
-	}
-	return names;
-}
-
 function listDiscoverableAgents(cwd: string): AgentEntry[] {
 	const builtinDirs = builtinAgentDirs(cwd);
 	const agents = [
@@ -2837,7 +2816,20 @@ function describeModelConfig(cwd: string, config: AgentModelConfig): string[] {
 }
 
 async function getPiModelOptions(ctx: ExtensionContext): Promise<string[]> {
-	const models = await ctx.modelRegistry.getAvailable();
+	const registry = ctx.modelRegistry;
+	if (!registry) {
+		return [...MODEL_CONTROL_OPTIONS];
+	}
+	let raw: unknown;
+	try {
+		raw = await registry.getAvailable();
+	} catch {
+		return [...MODEL_CONTROL_OPTIONS];
+	}
+	if (!Array.isArray(raw)) {
+		return [...MODEL_CONTROL_OPTIONS];
+	}
+	const models = raw as { provider: string; id: string }[];
 	const modelIds = models
 		.map((model) => normalizeModelId(`${model.provider}/${model.id}`))
 		.filter((model): model is string => model !== undefined)
@@ -4164,7 +4156,14 @@ async function switchLiveOrchestrator(ctx: ExtensionContext, live: LiveSession,
 	const reference = parseOrchestratorModelRef(entry.model);
 	if (reference === undefined) return "";
 	const label = `${reference.provider}/${reference.model}`;
-	const model = ctx.modelRegistry.find(reference.provider, reference.model);
+	const registry = ctx.modelRegistry;
+	if (!registry) {
+		if (ctx.hasUI && ctx.ui.notify) {
+			ctx.ui.notify("Model registry unavailable; this session keeps its current model.", "warning");
+		}
+		return `\nModel registry unavailable; this session keeps its current model.`;
+	}
+	const model = registry.find(reference.provider, reference.model);
 	if (model === undefined) return `\n${label} is not in the model catalog; this session keeps its current model.`;
 	let switched = false;
 	try {
@@ -5145,14 +5144,6 @@ function isReviewTransition(value: string): value is ReviewTransition {
 	return Object.values(REVIEW_TRANSITION).some((transition) => transition === value);
 }
 
-function isGraphV1JudgmentDayLineage(cwd: string, lineageId: string): boolean {
-	try {
-		return ReviewTransactionStore.forRepository(cwd).read(lineageId).mode === REVIEW_MODE.JUDGMENT_DAY;
-	} catch {
-		return false;
-	}
-}
-
 interface NativeStartPreAuthorityRejection {
 	lineage_created: false;
 	mutation_performed: false;
@@ -8699,6 +8690,9 @@ export const __testing = {
 	readSddChangeFlag,
 	resetTelemetryTriggerGuardForTesting,
 	createGentleAiExtension: createGentleAiExtensionForTesting,
+	getPiModelOptions,
+	MODEL_CONTROL_OPTIONS,
+	switchLiveOrchestrator,
 };
 
 export interface GentleAiRuntimeDependencies {
@@ -8759,11 +8753,6 @@ function createGentleAiExtensionForTesting(
 	const candidateViews = dependencies.candidateViews === undefined ? new CandidateViewRegistry() : dependencies.candidateViews;
 	const herdrLifecycle = createHerdrConfirmationLifecycle(pi.events);
 	const permissionEnvironment = dependencies.processEnv ?? process.env;
-	const oddDelegationGate = new OddRuntimeDelegationGate();
-	const oddSessionId = (ctx: ExtensionContext): string => {
-		try { return ctx.sessionManager.getSessionId(); }
-		catch { return ""; }
-	};
 
 	const setReviewSessionPermissionStatus = (context: ExtensionContext, active: boolean): void => {
 		try {
@@ -9169,10 +9158,6 @@ function createGentleAiExtensionForTesting(
 		const retiredSync = readAgentStartNames(event).includes("sdd-sync") || /\bSDD sync executor\b/i.test(event.systemPrompt ?? "");
 		const isSddAgent = retiredSync || isSddAgentStartEvent(event);
 		const isNamedAgent = isNamedAgentStartEvent(event);
-		oddDelegationGate.start(
-			oddSessionId(ctx),
-			!isNamedAgent && !isSddAgent && permissionEnvironment.GENTLE_PI_AGENTS_CHILD !== "1",
-		);
 		const subagentDepthKey = pendingReviewConsentSessionKey(ctx, pendingReviewConsentFallbackKey);
 		if (isSddAgent || isNamedAgent) {
 			processAgentEndSubagentDepth.set(subagentDepthKey, (processAgentEndSubagentDepth.get(subagentDepthKey) ?? 0) + 1);
@@ -9282,7 +9267,6 @@ function createGentleAiExtensionForTesting(
 	// consent, or chooses a partial candidate. Durable own-mutation receipts
 	// gate STATUS and consume only the generation captured before that await.
 	pi.on("agent_end", async (_event, ctx) => {
-		oddDelegationGate.endChild(oddSessionId(ctx));
 		if (nativeReviewCli?.reviewMode === undefined || nativeReviewCli.targetStatus === undefined) return;
 		if (ctx.hasUI !== true || !reminderSessionActive) return;
 		const sessionKey = pendingReviewConsentSessionKey(ctx, pendingReviewConsentFallbackKey);
@@ -9318,7 +9302,6 @@ function createGentleAiExtensionForTesting(
 	pi.on("tool_result", (event, ctx) => {
 		if (!reminderSessionActive || event.isError !== false || (event.toolName !== "write" && event.toolName !== "edit")) return;
 		if (!isRecord(event.input) || typeof event.input.path !== "string" || !event.input.path.trim()) return;
-		oddDelegationGate.recordSuccess(oddSessionId(ctx), event.toolName, event.input, ctx.cwd);
 		try {
 			const root = resolveSessionWorktree(event.input.path, ctx.cwd)?.root;
 			if (root) recordReviewMutation(pi, ctx.sessionManager, root, { source: "direct", toolName: event.toolName, toolCallId: event.toolCallId });
@@ -9332,10 +9315,6 @@ function createGentleAiExtensionForTesting(
 			event.input,
 		);
 		if (sensitivePathDenied) return sensitivePathDenied;
-		const oddDelegationDenied = oddDelegationGate.beforeTool(
-			oddSessionId(ctx), event.toolName, event.input, ctx.cwd, readActiveToolNames(pi),
-		);
-		if (oddDelegationDenied) return oddDelegationDenied;
 		if (event.toolName === "subagent_run") {
 			const sddAgent = sddDispatchAgentName(event.input);
 			if (sddAgent === "invalid") {

package/lib/agents-runner.ts

@@ -166,6 +166,9 @@ export interface TaskRequest {
 	// Untrusted narrowing intent; paths come only from matching host provenance.
 	researchSelection?: unknown;
 	extensionPaths?: string[];
+	// Synchronous admission recheck at dequeue, before any OS spawn. Throws fail
+	// only this task; unlike onLaunch, it must never persist Changes evidence.
+	beforeSpawn?: () => void;
 	// Captures the originating session; invoked only after successful OS spawn.
 	onLaunch?: () => void;
 	/** Default off. Parent owns policy before opting into bounded local buffering,
@@ -489,6 +492,12 @@ export class AgentRunner {
 	// A child that cannot start (missing pi, bad cwd) fails only its task:
 	// spawn exceptions and process errors settle without uncaught host errors.
 	private launch(id: string, request: TaskRequest): void {
+		try { request.beforeSpawn?.(); }
+		catch (error) {
+			this.store.update(id, { status: TASK_STATUS.RUNNING, startedAt: this.deps.now(), lastStep: "starting" });
+			this.finish(id, TASK_STATUS.FAILED, `could not start pi: ${error instanceof Error ? error.message : String(error)}`);
+			return;
+		}
 		const detached = this.processControl.platform !== "win32";
 		const hasParentPermissionChannel = request.authorizeParentStandingReviewPermission !== undefined;
 		const permissionChannelStdio = this.processControl.platform === "win32" ? "overlapped" : "pipe";

package/lib/foreign-target-grants.ts

@@ -0,0 +1,32 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { WorktreeIdentity } from "./session-worktree-registry.ts";
+
+// Deliberately ephemeral: no session entries or disk persistence can restore consent.
+export class ForeignTargetGrants {
+	private readonly grants = new Map<string, Set<string>>();
+	private manager?: ExtensionContext["sessionManager"];
+	private sessionId?: string;
+
+	async authorize(ctx: Pick<ExtensionContext, "sessionManager" | "hasUI" | "ui">, target: WorktreeIdentity, options: { continuation?: boolean; signal?: AbortSignal } = {}): Promise<void> {
+		if (options.signal?.aborted) throw new Error("Foreign clone authorization aborted.");
+		const id = ctx.sessionManager.getSessionId();
+		if (!id) throw new Error("Foreign target requires an active session identity.");
+		if (this.manager !== ctx.sessionManager || this.sessionId !== id) {
+			this.grants.clear();
+			this.manager = ctx.sessionManager;
+			this.sessionId = id;
+		}
+		if (this.grants.get(id)?.has(target.commonDir)) return;
+		if (options.continuation) throw new Error("Foreign clone continuation grant was lost; start a new explicit launch.");
+		if (!ctx.hasUI || !ctx.ui?.confirm || await ctx.ui.confirm("Authorize foreign clone subagent", `Launch a subagent in ${target.root}? Git common directory: ${target.commonDir}. This grant applies only to this live session and clone.`) !== true) throw new Error("Foreign clone requires interactive human consent before launch.");
+		if (options.signal?.aborted) throw new Error("Foreign clone authorization aborted.");
+		if (ctx.sessionManager !== this.manager || ctx.sessionManager.getSessionId() !== id) throw new Error("Session identity changed during foreign clone authorization.");
+		const grants = this.grants.get(id) ?? new Set<string>();
+		grants.add(target.commonDir);
+		this.grants.set(id, grants);
+	}
+
+	assertCurrent(ctx: Pick<ExtensionContext, "sessionManager">, target: WorktreeIdentity): void {
+		if (ctx.sessionManager !== this.manager || !this.sessionId || ctx.sessionManager.getSessionId() !== this.sessionId || !this.grants.get(this.sessionId)?.has(target.commonDir)) throw new Error("Foreign clone grant is no longer live.");
+	}
+}

package/lib/gentle-shell-launcher.ts

@@ -4,7 +4,7 @@ import { join, resolve as resolvePath } from "node:path";
 // env/fs/exec. `bin/gentle-shell.mjs` (T2) wires these into the real process,
 // filesystem and child process so this module stays fully unit-testable.
 
-export type LauncherCommand = "home";
+export type LauncherCommand = "home" | "setup";
 
 // pi's own package-management subcommands (see pi's cli/args.ts printHelp
 // "Commands" list): each is dispatched by pi itself, before pi's own flag
@@ -62,6 +62,8 @@ export function parseLauncherArgs(argv: string[]): ParsedLauncherArgs {
 	let help = false;
 	let version = false;
 	let error: string | undefined;
+	let command: LauncherCommand | undefined;
+	let commandArgs: string[] = [];
 	let piSubcommand: PiSubcommand | undefined;
 	const passthrough: string[] = [];
 
@@ -131,6 +133,18 @@ export function parseLauncherArgs(argv: string[]): ParsedLauncherArgs {
 			i += 1;
 			continue;
 		}
+		// Unlike `home`, `setup` is not restricted to argv[0]: it accepts the
+		// home selectors (--link, --isolated, --home <dir>) ahead of it, same
+		// as a pi subcommand would, so it provisions whichever home those
+		// selectors resolve to. It is only recognised as the FIRST non-flag
+		// token — once a pi subcommand (or any other passthrough token) has
+		// already started, a later "setup" is just an ordinary passthrough
+		// argument, same as "home" is.
+		if (arg === "setup" && command === undefined && passthrough.length === 0) {
+			command = "setup";
+			commandArgs = argv.slice(i + 1);
+			break;
+		}
 		if (passthrough.length === 0 && isPiSubcommand(arg)) {
 			piSubcommand = arg;
 		}
@@ -147,7 +161,7 @@ export function parseLauncherArgs(argv: string[]): ParsedLauncherArgs {
 		}
 	}
 
-	return { link, isolated, home, packageRoot, help, version, command: undefined, commandArgs: [], passthrough, piSubcommand, error };
+	return { link, isolated, home, packageRoot, help, version, command, commandArgs, passthrough, piSubcommand, error };
 }
 
 // --- home resolution -------------------------------------------------------
@@ -200,6 +214,20 @@ export function resolveHome(input: ResolveHomeInput): ResolvedHome {
 	return { mode: "isolated", dir: isolatedDir(env, homedir), source: "default" };
 }
 
+// The flags that reproduce `home`'s resolved mode on a later `gentle-shell
+// <flags> ...` invocation — used by remediation messages (e.g. "run
+// `gentle-shell <flags> remove <source>`") so they point at the exact home
+// setup provisioned instead of silently defaulting to the isolated home.
+// Mirrors the three ResolvedHome modes one-to-one: "link" needs --link
+// (PI_CODING_AGENT_DIR-derived dirs aren't reproducible as a literal path),
+// "path" needs its --home <dir>, and "isolated" needs nothing since it's
+// gentle-shell's own default when no selector is given.
+export function homeSelectorFlags(home: ResolvedHome): string[] {
+	if (home.mode === "link") return ["--link"];
+	if (home.mode === "path") return ["--home", home.dir];
+	return [];
+}
+
 export function launcherConfigPath(homedir: string): string {
 	return join(homedir, ".gentle-shell", "config.json");
 }
@@ -228,6 +256,88 @@ export function parseLauncherConfig(text: string): LauncherConfig | undefined {
 	return { mode: "path", dir: home };
 }
 
+// --- provisioning marker (S7 auto-provision) --------------------------------
+
+// Raw config.json shape as actually stored on disk: a plain object that may
+// carry `home` (see LauncherConfig above), `provisioned`, and any other key
+// a future feature adds. Unlike parseLauncherConfig's discriminated
+// LauncherConfig, these helpers operate on (and return) the whole object so
+// a write never drops a field it does not itself understand — notably
+// another home's provisioned marker when `gentle-shell home ...` persists a
+// mode change.
+export type RawLauncherConfig = Record<string, unknown>;
+
+// Tolerant like parseLauncherConfig: a missing, malformed, or foreign
+// config.json resolves to an empty object rather than throwing, so a caller
+// can always merge into (and write back) whatever it finds.
+export function parseRawLauncherConfig(text: string | undefined): RawLauncherConfig {
+	if (text === undefined) return {};
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return {};
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+	return parsed as RawLauncherConfig;
+}
+
+export interface ProvisionedEntry {
+	gentleAi: string;
+	// Optional: a marker written before gentle-pi version tracking (S8) has
+	// no `gentlePi` field at all. needsProvisioning below treats that
+	// omission as "needs provisioning" rather than trusting or crashing on it.
+	gentlePi?: string;
+	at: string;
+}
+
+function isProvisionedEntry(value: unknown): value is ProvisionedEntry {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value as Record<string, unknown>;
+	if (typeof record.gentleAi !== "string" || typeof record.at !== "string") return false;
+	return record.gentlePi === undefined || typeof record.gentlePi === "string";
+}
+
+// Tolerant read of config.provisioned: a missing, non-object, or malformed
+// map (or a malformed individual entry) is dropped rather than thrown, same
+// tolerance policy as parseLauncherConfig above.
+function provisionedMap(config: RawLauncherConfig): Record<string, ProvisionedEntry> {
+	const value = config.provisioned;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return {};
+	const map: Record<string, ProvisionedEntry> = {};
+	for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+		if (isProvisionedEntry(entry)) map[key] = entry;
+	}
+	return map;
+}
+
+// The provisioning record for `homeDir` (the caller passes a realpath, so
+// two different-looking paths to the same home never diverge), or undefined
+// when that home has never been auto- or manually provisioned.
+export function provisionedEntry(config: RawLauncherConfig, homeDir: string): ProvisionedEntry | undefined {
+	return provisionedMap(config)[homeDir];
+}
+
+// True when `homeDir` has never been provisioned, was provisioned with a
+// gentle-ai pin other than `pin`, or was provisioned against a gentle-pi
+// other than `gentlePiVersion` (the running launcher's own version, from its
+// package.json) — the signal bin/gentle-shell.mjs uses to decide whether a
+// plain launch should run the setup flow automatically before starting pi.
+// A marker written before gentle-pi version tracking existed has no
+// `gentlePi` field, which never strictly-equals a real version string, so it
+// always counts as needing provisioning too — see ProvisionedEntry above.
+export function needsProvisioning(config: RawLauncherConfig, homeDir: string, pin: string, gentlePiVersion: string): boolean {
+	const entry = provisionedEntry(config, homeDir);
+	return entry === undefined || entry.gentleAi !== pin || entry.gentlePi !== gentlePiVersion;
+}
+
+// Returns a new config object recording `homeDir` as provisioned at `pin`
+// and `gentlePiVersion`, preserving every other key — including every other
+// home's provisioned entry — unchanged. Never mutates `config`.
+export function recordProvisioned(config: RawLauncherConfig, homeDir: string, pin: string, gentlePiVersion: string, now: string): RawLauncherConfig {
+	return { ...config, provisioned: { ...provisionedMap(config), [homeDir]: { gentleAi: pin, gentlePi: gentlePiVersion, at: now } } };
+}
+
 // --- pi runtime resolution ---------------------------------------------------
 
 export type PiRuntimeKind = "env" | "bundled" | "path";
@@ -298,6 +408,25 @@ export function checkPiVersion(output: string, minimum: string = MIN_PI_VERSION)
 	return { ok: true, version };
 }
 
+// --- setup subcommand's gentle-ai pin gate -----------------------------------
+
+// The first gentle-ai release that honors PI_CODING_AGENT_DIR in its own
+// `install --agent pi` provisioning. `gentle-shell setup` spawns the
+// package-local pinned gentle-ai with PI_CODING_AGENT_DIR set to the
+// resolved home; an older pin ignores that variable and silently provisions
+// the caller's real ~/.pi/agent instead, so setup must refuse to run it.
+export const MIN_SETUP_GENTLE_AI_VERSION = "3.6.0";
+
+export function isSetupCapablePin(version: string, minimum: string = MIN_SETUP_GENTLE_AI_VERSION): boolean {
+	const match = VERSION_PATTERN.exec(version);
+	if (!match) return false;
+	const minimumMatch = VERSION_PATTERN.exec(minimum);
+	if (!minimumMatch) throw new Error(`invalid minimum version "${minimum}"`);
+	const found: [number, number, number] = [Number(match[1]), Number(match[2]), Number(match[3])];
+	const wanted: [number, number, number] = [Number(minimumMatch[1]), Number(minimumMatch[2]), Number(minimumMatch[3])];
+	return compareVersions(found, wanted) >= 0;
+}
+
 // --- packaging drift guard -----------------------------------------------------
 
 export interface PackageJsonPeerShape {
@@ -400,6 +529,61 @@ export function settingsDeclareGentlePi(settingsText: string | undefined): boole
 	return packages.some(packageEntryDeclaresGentlePi);
 }
 
+// gentle-ai's own managed Pi stack still installs
+// npm:@juicesharp/rpiv-ask-user-question, which conflicts with gentle-pi's
+// first-party ask_user_question tool: Pi tool names are exclusive, so a
+// second provider for the same name fails the whole load (see
+// extensions/ask-user-question.ts). Tracked upstream as gentle-ai #4820 and
+// gentle-shell #1277; the gentle-ai fix lands separately, so `gentle-shell
+// setup` (bin/gentle-shell.mjs) must remove it from the provisioned home
+// itself.
+//
+// gentle-ai's managed Pi stack also always declares npm:gentle-pi itself.
+// That declaration must never survive setup either, for an unrelated reason:
+// this launcher always loads its own gentle-pi (its own package root, or a
+// take-over), never the one gentle-ai's stack installs, so leaving the
+// declaration in place would silently let the home drift onto whatever
+// gentle-pi npm last installed — or, for a developer running from a source
+// checkout, onto the published npm package — instead of the running
+// launcher's own copy. See docs/readme-reference.md's "setup" section.
+//
+// Table of every package `setup` removes after gentle-ai finishes, so a
+// future addition only needs a new row here.
+const POST_INSTALL_REMOVAL_PACKAGES: readonly { readonly name: string; readonly source: string }[] = [
+	{ name: "@juicesharp/rpiv-ask-user-question", source: "npm:@juicesharp/rpiv-ask-user-question" },
+	{ name: "gentle-pi", source: "npm:gentle-pi" },
+];
+
+// The known removal sources, exposed so a `--dry-run` caller can report what
+// setup would remove *if* gentle-ai's install declares it, without reading
+// settings.json itself: a dry run writes nothing, so settings.json
+// afterwards would only reflect whatever pre-existed the run, not what the
+// (skipped) install would have declared. See runPostInstallCleanup in
+// bin/gentle-shell.mjs.
+export const POST_INSTALL_REMOVAL_SOURCES: readonly string[] = POST_INSTALL_REMOVAL_PACKAGES.map((entry) => entry.source);
+
+// Scans a settings.json `packages` list (same string/object-source parsing
+// as settingsDeclareGentlePi/findGentlePiDeclaration above) for any entry
+// whose npm package name matches POST_INSTALL_REMOVAL_PACKAGES, at any
+// version spec. Returns each match's canonical unversioned source, deduped,
+// in the order those packages first appear in `packages` — never the
+// declared (possibly versioned) source text, since the caller always removes
+// the bare package.
+export function postInstallRemovals(settingsText: string | undefined): string[] {
+	const packages = parseSettingsPackages(settingsText);
+	if (packages === undefined) return [];
+
+	const found: string[] = [];
+	for (const entry of packages) {
+		const source = entrySource(entry);
+		if (source === undefined || packageSourceKind(source) !== "npm") continue;
+		const name = npmPackageName(source);
+		const match = POST_INSTALL_REMOVAL_PACKAGES.find((candidate) => candidate.name === name);
+		if (match !== undefined && !found.includes(match.source)) found.push(match.source);
+	}
+	return found;
+}
+
 export type GentlePiDeclaration = { kind: "npm" } | { kind: "path"; dir: string };
 
 export interface FindGentlePiDeclarationOptions {
@@ -789,6 +973,20 @@ export function quoteForCmdExe(token: string): string {
 	return `"${token.replace(/"/g, '\\"')}"`;
 }
 
+const POSIX_SHELL_SPECIAL_CHARS = /[\s"'`\\$&|;<>(){}*?[\]!#~]/;
+
+// POSIX/bash single-quote shell quoting for a copy-pasteable command
+// bin/gentle-shell.mjs prints to stderr (e.g. the setup remediation
+// command): wraps a token in single quotes when it is empty or contains
+// whitespace or a shell metacharacter, escaping an embedded single quote as
+// `'\''` (close quote, escaped literal quote, reopen quote) — inside single
+// quotes nothing else needs escaping, unlike cmd.exe's `"`-based quoting
+// (quoteForCmdExe above).
+export function shellQuote(value: string): string {
+	if (value.length > 0 && !POSIX_SHELL_SPECIAL_CHARS.test(value)) return value;
+	return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
 export interface PlanSpawnInput {
 	command: string;
 	args: string[];
@@ -809,6 +1007,115 @@ export function planSpawn(input: PlanSpawnInput): SpawnPlan {
 	return { command, args, shell: false };
 }
 
+// --- JSON field restore --------------------------------------------------
+
+// Detects the indentation unit and trailing-newline presence of a JSON text,
+// so restoreJsonField below can re-serialize as close to the original
+// formatting as practical instead of imposing its own. `indent` is
+// `undefined` for compact (no-whitespace) JSON, matching what
+// `JSON.stringify(value)` (no third argument) produces.
+function detectJsonFormatting(text: string): { indent: string | undefined; trailingNewline: boolean } {
+	const match = text.match(/\{\r?\n([ \t]+)/);
+	return { indent: match ? match[1] : undefined, trailingNewline: text.endsWith("\n") };
+}
+
+function jsonValuesEqual(a: unknown, b: unknown): boolean {
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+
+// Pure JSON merge: restores `field` in `currentText` back to whatever it was
+// in `originalText`, keeping every other field exactly as `currentText` left
+// it, and formatting the result to match `originalText`'s indentation and
+// trailing newline. Used by bin/gentle-shell.mjs's setup flow to restore
+// `managed_asset_digest` in the user's shared `~/.gentle-ai/state.json` after
+// the pinned gentle-ai spawn rewrites it (the same shared-file problem
+// persona.json has — see sharedPersonaPath/snapshotFile/restoreFile in
+// bin/gentle-shell.mjs — but state.json also carries fields the pinned
+// gentle-ai is supposed to update, like installed_agents, so this restores
+// only the one field instead of the whole file).
+//
+// Returns the new text, or `undefined` when either text fails to parse as a
+// JSON object, or the field's presence and value are already identical on
+// both sides (nothing to restore). Never called by the caller when
+// `originalText` comes from a file that did not exist before the spawn —
+// there is nothing to restore a nonexistent file back to.
+export function restoreJsonField(originalText: string, currentText: string, field: string): string | undefined {
+	let originalValue: unknown;
+	let currentValue: unknown;
+	try {
+		originalValue = JSON.parse(originalText);
+		currentValue = JSON.parse(currentText);
+	} catch {
+		return undefined;
+	}
+	if (
+		typeof originalValue !== "object" ||
+		originalValue === null ||
+		Array.isArray(originalValue) ||
+		typeof currentValue !== "object" ||
+		currentValue === null ||
+		Array.isArray(currentValue)
+	) {
+		return undefined;
+	}
+	const originalObj = originalValue as Record<string, unknown>;
+	const currentObj = currentValue as Record<string, unknown>;
+	const hadField = Object.prototype.hasOwnProperty.call(originalObj, field);
+	const hasFieldNow = Object.prototype.hasOwnProperty.call(currentObj, field);
+	const unchanged = hadField === hasFieldNow && (!hadField || jsonValuesEqual(originalObj[field], currentObj[field]));
+	if (unchanged) return undefined;
+
+	let restored: Record<string, unknown>;
+	if (hadField) {
+		restored = { ...currentObj, [field]: originalObj[field] };
+	} else {
+		restored = { ...currentObj };
+		delete restored[field];
+	}
+
+	const { indent, trailingNewline } = detectJsonFormatting(originalText);
+	const serialized = JSON.stringify(restored, null, indent);
+	return trailingNewline ? `${serialized}\n` : serialized;
+}
+
+// Pure JSON merge: forces `field` in `currentText` to `value`, but only when
+// `originalText` (the state from before whatever wrote `currentText`) did not
+// declare that field at all — never overriding a value the original already
+// had, in either direction. Keeps every other field exactly as `currentText`
+// left it, and formats the result to match `currentText`'s own indentation
+// and trailing newline (unlike restoreJsonField above, which matches the
+// *original*'s formatting — here `currentText` is what the other writer just
+// produced, so its own convention is respected instead of imposed on).
+// Used by bin/gentle-shell.mjs's setup flow so a home gentle-shell provisions
+// ends up with the maintainer's default theme unless the home (or the user)
+// already had an opinion about it, even when gentle-ai's own managed install
+// writes a *different* default theme into settings.json.
+//
+// Returns the new text, or `undefined` when either text fails to parse as a
+// JSON object, the original text already declared `field` (nothing to
+// force), or the current value already equals `value` (nothing to change).
+export function forceJsonFieldIfAbsentInOriginal(originalText: string, currentText: string, field: string, value: unknown): string | undefined {
+	let originalValue: unknown;
+	let currentValue: unknown;
+	try {
+		originalValue = JSON.parse(originalText);
+		currentValue = JSON.parse(currentText);
+	} catch {
+		return undefined;
+	}
+	if (typeof originalValue !== "object" || originalValue === null || Array.isArray(originalValue)) return undefined;
+	if (typeof currentValue !== "object" || currentValue === null || Array.isArray(currentValue)) return undefined;
+	const originalObj = originalValue as Record<string, unknown>;
+	const currentObj = currentValue as Record<string, unknown>;
+	if (Object.prototype.hasOwnProperty.call(originalObj, field)) return undefined;
+	if (jsonValuesEqual(currentObj[field], value)) return undefined;
+
+	const forced = { ...currentObj, [field]: value };
+	const { indent, trailingNewline } = detectJsonFormatting(currentText);
+	const serialized = JSON.stringify(forced, null, indent);
+	return trailingNewline ? `${serialized}\n` : serialized;
+}
+
 // --- reporting ---------------------------------------------------------------
 
 export interface DescribeVersionInput {
@@ -829,6 +1136,7 @@ export function helpText(): string {
 	return [
 		"Usage: gentle-shell [options] [-- pi-args...]",
 		"       gentle-shell home [link|isolated|<path>]",
+		"       gentle-shell [home selectors] setup [--dry-run]",
 		"",
 		"Opens pi with the Gentle Shell package loaded, without touching your",
 		"vanilla pi installation.",
@@ -844,6 +1152,10 @@ export function helpText(): string {
 		"",
 		"Commands:",
 		"  home             Print or persist the effective home mode (link, isolated, or a path).",
+		"  setup            Provision the resolved home with the gentle-ai companion packages",
+		"                   (runs the package-local gentle-ai 'install --agent pi --scope global').",
+		"                   Accepts --dry-run, forwarded to gentle-ai. Accepts a home selector",
+		"                   (--link, --isolated, --home <dir>) before it.",
 		"",
 		"Managing packages:",
 		"  gentle-shell install npm:<pkg>   Run pi's own 'install' against the resolved home.",