gentle-pi 4.2.0 → 4.4.0

package/lib/gentle-shell-bundled.ts

@@ -1,7 +1,7 @@
 import { lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { request as httpRequest } from "node:http";
 import { createConnection } from "node:net";
-import { dirname, posix, win32 } from "node:path";
+import { dirname, isAbsolute, posix, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // The launcher in a bundled install (S5, S8): pure decisions over an injected
@@ -27,6 +27,46 @@ export interface BundledInstall {
 
 type Env = Record<string, string | undefined>;
 
+/**
+ * Builds the detached shared server's environment without retaining session scratch.
+ * Windows Node can reintroduce an omitted TEMP from its parent, so use the
+ * original stable ancestor there; POSIX omits scratch temp settings instead.
+ */
+export function sharedEngramEnv(base: Env, platform: string = process.platform): Env {
+	const path = pathFor(platform);
+	const env: Env = {};
+	const scratch = (value: string) => /^(gp|ga)[A-Za-z0-9]{6}$/.test(path.basename(path.normalize(value)));
+	let stableTemp: string | undefined;
+	let tempKey: string | undefined;
+	for (const [key, value] of Object.entries(base)) {
+		const name = platform === "win32" ? key.toUpperCase() : key;
+		if (name.startsWith("ENGRAM_") || name === "GH_TOKEN" || name === "GITHUB_TOKEN") continue;
+		if (["TMPDIR", "TMP", "TEMP"].includes(name) && value !== undefined && scratch(value)) {
+			if (platform !== "win32") continue;
+			// A drive-relative or root-relative path depends on ambient state.
+			const root = win32.parse(value).root;
+			if (!/^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/][^\\/]+[\\/]?)$/.test(root) || value.split(/[\\/]/).includes("..")) {
+				throw new Error("An absolute Windows scratch temp path is required for shared Engram.");
+			}
+			let stable = win32.normalize(value);
+			while (scratch(stable)) {
+				const parent = win32.dirname(stable);
+				if (parent === stable) throw new Error("An absolute Windows scratch temp path is required for shared Engram.");
+				stable = parent;
+			}
+			env[key] = stable;
+			stableTemp ??= stable;
+		} else {
+			env[key] = value;
+		}
+		if (name === "TEMP") tempKey = key;
+	}
+	// Keep an existing custom TEMP, even if TMP/TMPDIR chose another root.
+	if (stableTemp !== undefined && (tempKey === undefined || env[tempKey] === undefined)) env[tempKey ?? "TEMP"] = stableTemp;
+	env.ENGRAM_NO_UPDATE_CHECK = "1";
+	return env;
+}
+
 // The same rules scripts/bundled-install.mjs writes versions and markers with.
 const VERSION_ID = /^[0-9A-Za-z][0-9A-Za-z.-]*$/;
 const VERSION_MARKER = ".gentle-shell-version";
@@ -175,6 +215,29 @@ export function bundledGentlePiConfigHome(env: Env): string | undefined {
 	return prefix === undefined ? undefined : bundledPiConfigDir(prefix);
 }
 
+// #2201: the standalone launcher gives Pi this variable in its isolated home
+// only, naming the config folder next to the agent dir (standaloneConfigHome:
+// ~/.gentle-shell/gentle-ai by default). It is launcher-owned, never
+// GENTLE_PI_CONFIG_HOME: Gentle AI 4.0.0 reads that one as the parent of its
+// own gentle-ai folder, and the agent's shell would pass it to any gentle-ai.
+export const GENTLE_SHELL_CONFIG_HOME_ENV = "GENTLE_SHELL_CONFIG_HOME";
+
+// gentle-pi's config home, the one rule every reader shares: a bundled
+// prefix's folder, then an explicit GENTLE_PI_CONFIG_HOME, then the launcher's
+// marker (absolute only), then ~/.pi/gentle-ai. Empty values count as unset.
+// `launcherMarker: false` is for install-level state written outside a session
+// (the main channel's channel.json, builds and dev-binary.json): the installer
+// and `gentle-shell upgrade` never see the marker, so their readers ignore it.
+export function resolveGentlePiConfigHome(env: Env, home: string, options: { launcherMarker?: boolean; platform?: string } = {}): string {
+	const path = pathFor(options.platform ?? process.platform);
+	const bundled = bundledGentlePiConfigHome(env);
+	if (bundled !== undefined) return bundled;
+	if (env.GENTLE_PI_CONFIG_HOME) return env.GENTLE_PI_CONFIG_HOME;
+	const marker = env[GENTLE_SHELL_CONFIG_HOME_ENV];
+	if (options.launcherMarker !== false && marker && path.isAbsolute(marker)) return marker;
+	return path.join(home, ".pi", "gentle-ai");
+}
+
 // The exact Pi of the version (S8): the Pi the version's package.json pins,
 // installed inside the version folder with Pi's own bin entry. Never another Pi.
 export function bundledPi(install: BundledInstall, input: { platform: string; fs: BundledFs }): BundledPi {
@@ -209,13 +272,14 @@ export function bundledPi(install: BundledInstall, input: { platform: string; fs
 // Gentle AI's variables, never set here because the agent's shell would pass
 // them to a gentle-ai the user runs), and the published Engram as
 // gentle-engram's ENGRAM_BIN unless the user chose one. With a memory decision
-// (S2, S6): the startup policy, and ENGRAM_BIN is the verified core only when
-// memory is allowed locally; otherwise the Shell-owned guard, so no provider,
-// whatever loaded it, runs an Engram binary against an unverified store.
+// (S2, S6): the startup policy, and ENGRAM_BIN is the Shell-owned guard, so no
+// provider, whatever loaded it, runs an Engram binary against a store; allowed
+// memory reaches the shared server through ENGRAM_URL only.
 export const ENGRAM_COMPANION_SOURCE = "npm:gentle-engram@0.4.2";
-export const ENGRAM_RECOVERY_NOTICE = "Engram memory disabled: Shell could not verify safe store or server reuse. Matching versions or updating alone do not prove compatibility. Reuse requires a server with verified /compatibility evidence or matching Shell-provisioned store identity. Back up existing Engram data before manual changes; do not delete it or bypass the safety check. Shell rechecks on every launch and remains usable without memory.";
+export const ENGRAM_RECOVERY_NOTICE = "Engram memory disabled: Shell could not verify safe server reuse. Matching versions or updating alone do not prove compatibility. Reuse requires a server on 127.0.0.1:7437 with verified /compatibility evidence; Shell never stops or replaces a server already listening there. Back up existing Engram data before manual changes; do not delete it or bypass the safety check. Shell rechecks on every launch and remains usable without memory.";
+export const ENGRAM_START_FAILED_NOTICE = "Engram memory disabled for this launch: Shell could not start the shared Engram server, or it did not report ready in time. Restart Shell to retry; if another program holds 127.0.0.1:7437, stop it first. Shell remains usable without memory.";
+export const ENGRAM_NEWER_SCHEMA_NOTICE = "Engram memory disabled: ~/.engram was migrated by a newer Engram than Shell's bundled core, so Shell will not start a server on it. Start that newer Engram's server yourself (engram serve); Shell reuses a running server with verified /compatibility evidence. Back up the store; do not delete or downgrade it. Shell remains usable without memory.";
 // `gentle-shell setup` publishes the verified core (ensureEngram) on every run.
-export const ENGRAM_PROVISION_FAILED_NOTICE = "Engram memory disabled for this launch: Shell could not provision a new Engram store identity, so it cannot vouch for that store. Restart Shell to retry. If Shell keeps reporting unknown compatibility and ~/.engram holds only .instance-id files, back it up and remove it, then restart Shell. Shell remains usable without memory.";
 export const ENGRAM_CORE_MISSING_NOTICE = "Engram memory disabled: the bundled Engram core is not installed yet. Run 'gentle-shell setup' to install the verified core, then restart Shell. Shell remains usable without memory.";
 // The first Engram release whose server answers GET /compatibility (PR #1792).
 export const ENGRAM_COMPATIBILITY_MIN_VERSION = "3.4.0";
@@ -236,13 +300,14 @@ function outdatedServerVersion(version: string | undefined): string | undefined
 // The default endpoint gentle-engram uses without ENGRAM_URL or ENGRAM_PORT.
 export const ENGRAM_DEFAULT_PORT = 7437;
 export const ENGRAM_DEFAULT_URL = `http://127.0.0.1:${ENGRAM_DEFAULT_PORT}`;
-const ENGRAM_SELECTIONS = ["ENGRAM_BIN", "ENGRAM_URL", "ENGRAM_DATA_DIR", "ENGRAM_PORT", "ENGRAM_DATABASE_URL"];
+const ENGRAM_SELECTIONS = ["ENGRAM_BIN", "ENGRAM_URL", "ENGRAM_DATA_DIR", "ENGRAM_PORT", "ENGRAM_SOCKET", "ENGRAM_DATABASE_URL", "ENGRAM_SERVER_MODE"];
 const HEX32 = /^[a-f0-9]{32}$/;
 
 export type EngramProbe = { kind: "refused" } | { kind: "unknown" } | { kind: "listening"; compatible: boolean; healthInstanceId?: string; healthVersion?: string };
-// `fresh`: Shell provisions a new store this run and may record its provenance.
-// `url`: a running server verified through /compatibility, reached explicitly.
-export type EngramStartup = { policy: "allow" | "disabled"; notice?: string; url?: string; fresh?: true };
+// `url`: the shared server, reached explicitly once /compatibility verified it.
+// `spawn`: nothing listens yet; Shell starts the bundled core's server and must
+// see it verified before Pi starts, or memory is disabled for that launch.
+export type EngramStartup = { policy: "allow" | "disabled"; notice?: string; url?: string; spawn?: true };
 
 // Without an invalid policy or an explicit Engram selection, the default
 // endpoint may be probed; an explicit selection is never contacted.
@@ -252,26 +317,24 @@ export function engramProbeAllowed(env: Env): boolean {
 }
 
 // Evidence only: never run an executable, open SQLite or infer compatibility
-// from versions. `provenance` means Shell's own record matched the store
-// (directory, .instance-id, core digest) and its header showed no newer schema.
-// A server version only selects the wording of a disabled decision.
-export function classifyEngramStartup(input: { env: Env; store: "absent" | "present" | "unknown"; endpoint: EngramProbe; core: boolean;
-	coreVersion: string; provenance?: { instanceId: string } }): EngramStartup {
+// from versions. Like other agents' hooks, Shell shares the global server: a
+// verified listener is reused, and with nothing listening the verified bundled
+// core starts one on Engram's defaults, unless the default store's header
+// (`userVersion`) shows a newer schema than that core's. A listener that does
+// not verify is never replaced. A server version only selects the wording.
+export function classifyEngramStartup(input: { env: Env; endpoint: EngramProbe; core: boolean; coreVersion: string; userVersion?: number }): EngramStartup {
 	if (!engramProbeAllowed(input.env)) return { policy: "disabled", notice: ENGRAM_RECOVERY_NOTICE };
 	const endpoint = input.endpoint;
-	const outdated = endpoint.kind === "listening" && !endpoint.compatible ? outdatedServerVersion(endpoint.healthVersion) : undefined;
-	const unknown: EngramStartup = { policy: "disabled", notice: outdated === undefined ? ENGRAM_RECOVERY_NOTICE : engramOutdatedServerNotice(outdated) };
 	if (endpoint.kind === "listening" && endpoint.compatible) return { policy: "allow", url: ENGRAM_DEFAULT_URL };
-	if (endpoint.kind === "refused" && input.store === "absent") {
-		return input.core ? { policy: "allow", fresh: true } : { policy: "disabled", notice: ENGRAM_CORE_MISSING_NOTICE };
+	if (endpoint.kind === "refused") {
+		if (!input.core) return { policy: "disabled", notice: ENGRAM_CORE_MISSING_NOTICE };
+		if (input.userVersion !== undefined && !engramHeaderAllows(input.userVersion, bundledEngramSchema(input.coreVersion))) {
+			return { policy: "disabled", notice: ENGRAM_NEWER_SCHEMA_NOTICE };
+		}
+		return { policy: "allow", url: ENGRAM_DEFAULT_URL, spawn: true };
 	}
-	const own = input.provenance;
-	if (own === undefined || !input.core || input.store !== "present") return unknown;
-	// Shell's own store, created by this exact core: offline, the provider starts
-	// that core; a running server must be that store and that exact core.
-	if (endpoint.kind === "refused") return { policy: "allow" };
-	if (endpoint.kind === "listening" && endpoint.healthInstanceId === own.instanceId && endpoint.healthVersion === input.coreVersion) return { policy: "allow" };
-	return unknown;
+	const outdated = endpoint.kind === "listening" ? outdatedServerVersion(endpoint.healthVersion) : undefined;
+	return { policy: "disabled", notice: outdated === undefined ? ENGRAM_RECOVERY_NOTICE : engramOutdatedServerNotice(outdated) };
 }
 
 // The exact contract a startup-verified store reports (Engram GET /compatibility).
@@ -331,8 +394,8 @@ export async function probeEngramEndpoint(input: { port?: number; timeoutMs?: nu
 	return { kind: "listening", compatible: false, healthInstanceId: identified ? body.instance_id : undefined, healthVersion: identified ? body.version : undefined };
 }
 
-// Shell's own record of a store it provisioned fresh with the verified core.
-// Written only after Shell itself provisioned the store's identity, before Pi starts.
+// Shell's record of a store an earlier Shell provisioned with its bundled core,
+// read only by the explicit `gentle-shell memory migrate` recovery.
 export type EngramProvenance = { schema: 1; dataDir: string; instanceId: string; coreSha256: string };
 
 export function engramProvenancePath(prefix: string, platform: string = process.platform): string {
@@ -346,14 +409,10 @@ export function parseEngramProvenance(text: string | undefined): EngramProvenanc
 	return { schema: 1, dataDir: record.dataDir, instanceId: record.instanceId, coreSha256: record.coreSha256 };
 }
 
-export function engramProvenanceMatches(record: EngramProvenance | undefined, observed: { dataDir: string; instanceId?: string; coreSha256?: string }): boolean {
-	return record !== undefined && record.dataDir === observed.dataDir && record.instanceId === observed.instanceId && record.coreSha256 === observed.coreSha256;
-}
-
 // The bundled core's own schema (SQLite user_version), verified from the
-// tagged sources v3.3.2 and v3.4.0: internal/store/store.go `const schemaVersion = 1`.
+// tagged sources v3.3.2, v3.4.0 and v3.5.2: internal/store/store.go `const schemaVersion = 1`.
 // A pin without a verified entry leaves the header check unavailable.
-const BUNDLED_ENGRAM_SCHEMA: Record<string, number> = { "3.3.2": 1, "3.4.0": 1 };
+const BUNDLED_ENGRAM_SCHEMA: Record<string, number> = { "3.3.2": 1, "3.4.0": 1, "3.5.2": 1 };
 
 export function bundledEngramSchema(coreVersion: string): number | undefined {
 	return Object.hasOwn(BUNDLED_ENGRAM_SCHEMA, coreVersion) ? BUNDLED_ENGRAM_SCHEMA[coreVersion] : undefined;
@@ -423,8 +482,7 @@ export function bundledChildEnv(base: Env, input: { node: string; cli: string; p
 		return env;
 	}
 	if (memory.url !== undefined) env.ENGRAM_URL = memory.url;
-	const local = memory.policy === "allow" && memory.url === undefined ? input.engram : undefined;
-	env.ENGRAM_BIN = local ?? input.guard;
+	env.ENGRAM_BIN = input.guard;
 	return env;
 }
 
@@ -455,6 +513,58 @@ export function withBundledNpmCommand(settingsText: string | undefined, command:
 	return { status: "write", text: settingsText === undefined || settingsText.endsWith("\n") ? `${serialized}\n` : serialized };
 }
 
+export type BundledNpmCommandRemoval = { status: "unchanged" } | { status: "malformed" } | { status: "removed"; text: string };
+
+// settings.json without `npmCommand`: every other key kept in order and the
+// file's indentation and final newline kept.
+function settingsWithoutNpmCommand(settingsText: string, settings: Record<string, unknown>): string {
+	const indent = settingsText.match(/\{\r?\n([ \t]+)/)?.[1] ?? "  ";
+	const { npmCommand: _removed, ...rest } = settings;
+	const serialized = JSON.stringify(rest, null, indent);
+	return settingsText.endsWith("\n") ? `${serialized}\n` : serialized;
+}
+
+// The agent home's settings.json without a `npmCommand` naming the prefix a
+// bundled self-uninstall removed (gentle-shell-uninstall.ts): one absolute
+// entry inside `withinRemoved` drops the whole key, every other key kept in
+// order and the file's indentation and final newline kept. A file that is not
+// a JSON object is never rewritten; a command naming nothing inside it stays.
+export function withoutBundledNpmCommand(settingsText: string | undefined, withinRemoved: (path: string) => boolean): BundledNpmCommandRemoval {
+	if (settingsText === undefined) return { status: "unchanged" };
+	const settings = parseJson(settingsText);
+	if (typeof settings !== "object" || settings === null || Array.isArray(settings)) return { status: "malformed" };
+	const current = settings.npmCommand;
+	if (!Array.isArray(current) || !current.some((part) => typeof part === "string" && isAbsolute(part) && withinRemoved(part))) return { status: "unchanged" };
+	return { status: "removed", text: settingsWithoutNpmCommand(settingsText, settings) };
+}
+
+// An `npmCommand` a bundled install wrote (scripts/bundled-install.mjs
+// bundledNpmCommand, with npm-cli.js and --prefix in earlier releases): our
+// node in runtime/node-<v>, then npm's settings and cache flags, and
+// --update-notifier=false last. A command the user chose never matches, even
+// when its program is missing.
+export function isBundledNpmCommand(command: readonly unknown[]): boolean {
+	const [node] = command;
+	return typeof node === "string" && /[\\/]runtime[\\/]node-[^\\/]+[\\/](node\.exe|bin[\\/]node)$/.test(node)
+		&& ["--userconfig=", "--globalconfig=", "--cache="].every((flag) => command.some((part) => typeof part === "string" && part.startsWith(flag)))
+		&& command[command.length - 1] === "--update-notifier=false";
+}
+
+// The agent home's settings.json without an `npmCommand` a bundled install
+// wrote whose executable (its first entry) no longer exists, as after a
+// bundled self-uninstall that kept the home (#2469): Pi runs that command for
+// every package install, so a key naming a deleted node.exe fails them all
+// with ENOENT. A command whose executable exists, that names no absolute
+// path, or that the user set themselves is never touched.
+export function withoutMissingBundledNpmCommand(settingsText: string | undefined, exists: (path: string) => boolean): BundledNpmCommandRemoval {
+	if (settingsText === undefined) return { status: "unchanged" };
+	const settings = parseJson(settingsText);
+	if (typeof settings !== "object" || settings === null || Array.isArray(settings)) return { status: "malformed" };
+	const executable = Array.isArray(settings.npmCommand) ? settings.npmCommand[0] : undefined;
+	if (typeof executable !== "string" || !isAbsolute(executable) || exists(executable) || !isBundledNpmCommand(settings.npmCommand as unknown[])) return { status: "unchanged" };
+	return { status: "removed", text: settingsWithoutNpmCommand(settingsText, settings) };
+}
+
 export interface BundledUpdatePlan {
 	// Pi's own update was asked for: redirect it to `gentle-shell upgrade`.
 	self: boolean;

package/lib/gentle-shell-import-pi.ts

@@ -0,0 +1,233 @@
+import { chmodSync, closeSync, linkSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { detectJsonFormatting } from "./gentle-shell-launcher.ts";
+
+// `gentle-shell home import-pi`: a one-time, opt-in copy of the user's pi
+// sign-ins and MCP servers into a separate Gentle Shell home, as an
+// alternative to --link. Only the files and settings keys below are read;
+// packages, extensions, caches, AGENTS.md and sessions are never copied, so
+// the target home keeps its own provisioning. Nothing is ever overwritten and
+// the source is only read.
+
+// auth.json holds OAuth tokens and API keys: always private in the copy.
+const IMPORTED_FILES: readonly { name: string; mode?: number }[] = [
+	{ name: "auth.json", mode: 0o600 },
+	{ name: "mcp.json" },
+];
+
+// Pi 1.2.0's own settings for the default model (SettingsManager
+// get/setDefaultProvider, DefaultModel, DefaultThinkingLevel).
+export const IMPORTED_SETTINGS_KEYS: readonly string[] = ["defaultProvider", "defaultModel", "defaultThinkingLevel"];
+
+export interface ImportPiFs {
+	// lstat: a symbolic link is "other", never followed.
+	kind: (path: string) => "missing" | "file" | "dir" | "other";
+	mode: (path: string) => number;
+	readText: (path: string) => string;
+	// Creates `to` with exactly `mode`; throws when it already exists.
+	copyNew: (from: string, to: string, mode: number) => void;
+	// Temp file next to `path`, then a rename onto it.
+	writeAtomic: (path: string, text: string) => void;
+}
+
+export type ImportPiStatus = "copied" | "would copy" | "present" | "not found" | "skipped" | "failed";
+
+export interface ImportPiItem {
+	item: string;
+	status: ImportPiStatus;
+	// The copy's mode, or why the item was skipped or failed. Never file content.
+	detail?: string;
+}
+
+export interface ImportPiResult {
+	items: ImportPiItem[];
+	failed: boolean;
+}
+
+function tempPathFor(path: string): string {
+	return join(dirname(path), `.${basename(path)}.gentle-shell-${process.pid}.tmp`);
+}
+
+function removeQuietly(path: string): void {
+	try {
+		unlinkSync(path);
+	} catch {
+		// Nothing left to clean up.
+	}
+}
+
+function writeTemp(path: string, data: string | Buffer, mode: number): string {
+	const temp = tempPathFor(path);
+	const fd = openSync(temp, "wx", mode);
+	try {
+		try {
+			writeFileSync(fd, data);
+		} finally {
+			closeSync(fd);
+		}
+		chmodSync(temp, mode); // the umask must not change the mode
+	} catch (error) {
+		// A partial copy may hold credentials: never leave it behind.
+		removeQuietly(temp);
+		throw error;
+	}
+	return temp;
+}
+
+export const nodeImportPiFs: ImportPiFs = {
+	kind: (path) => {
+		try {
+			const stat = lstatSync(path);
+			if (stat.isSymbolicLink()) return "other";
+			return stat.isFile() ? "file" : stat.isDirectory() ? "dir" : "other";
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing";
+			throw error;
+		}
+	},
+	mode: (path) => lstatSync(path).mode & 0o777,
+	readText: (path) => readFileSync(path, "utf8"),
+	copyNew: (from, to, mode) => {
+		const temp = writeTemp(to, readFileSync(from), mode);
+		try {
+			linkSync(temp, to); // EEXIST instead of replacing a file that appeared meanwhile
+		} finally {
+			removeQuietly(temp);
+		}
+	},
+	writeAtomic: (path, text) => {
+		const mode = lstatSync(path, { throwIfNoEntry: false })?.mode;
+		const temp = writeTemp(path, text, mode === undefined ? 0o600 : mode & 0o777);
+		try {
+			renameSync(temp, path);
+		} catch (error) {
+			removeQuietly(temp);
+			throw error;
+		}
+	},
+};
+
+function reason(error: unknown): string {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return typeof code === "string" ? code : error instanceof Error ? error.message : String(error);
+}
+
+function parseObject(text: string): Record<string, unknown> | undefined {
+	try {
+		const value: unknown = JSON.parse(text.replace(/^\uFEFF/, ""));
+		return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function importFile(name: string, mode: number | undefined, input: { source: string; target: string; dryRun: boolean; fs: ImportPiFs }): ImportPiItem {
+	const { fs } = input;
+	const from = join(input.source, name);
+	const to = join(input.target, name);
+	// Classification can throw too (ENOTDIR under a file): one failed item, never an aborted report.
+	try {
+		const kind = fs.kind(from);
+		if (kind === "missing") return { item: name, status: "not found" };
+		if (kind !== "file") return { item: name, status: "skipped", detail: "not a regular file" };
+		if (fs.kind(to) !== "missing") return { item: name, status: "present" };
+		const copyMode = mode ?? fs.mode(from);
+		const detail = `${copyMode.toString(8).padStart(4, "0")}`;
+		if (input.dryRun) return { item: name, status: "would copy", detail };
+		fs.copyNew(from, to, copyMode);
+		return { item: name, status: "copied", detail };
+	} catch (error) {
+		return { item: name, status: "failed", detail: reason(error) };
+	}
+}
+
+function importSettings(input: { source: string; target: string; dryRun: boolean; fs: ImportPiFs }): ImportPiItem[] {
+	try {
+		return planAndWriteSettings(input);
+	} catch (error) {
+		// An unreadable settings.json stays one failed item, never an aborted report.
+		return [{ item: "settings.json", status: "failed", detail: reason(error) }];
+	}
+}
+
+function planAndWriteSettings(input: { source: string; target: string; dryRun: boolean; fs: ImportPiFs }): ImportPiItem[] {
+	const { fs } = input;
+	const from = join(input.source, "settings.json");
+	const to = join(input.target, "settings.json");
+	const sourceKind = fs.kind(from);
+	if (sourceKind === "missing") return [{ item: "settings.json", status: "not found" }];
+	if (sourceKind !== "file") return [{ item: "settings.json", status: "skipped", detail: "not a regular file" }];
+	const source = parseObject(fs.readText(from));
+	if (source === undefined) return [{ item: "settings.json", status: "skipped", detail: `${from} is not a JSON object` }];
+	const targetKind = fs.kind(to);
+	if (targetKind !== "missing" && targetKind !== "file") return [{ item: "settings.json", status: "skipped", detail: `${to} is not a regular file` }];
+	const targetText = targetKind === "missing" ? undefined : fs.readText(to);
+	const target = targetText === undefined ? {} : parseObject(targetText);
+	if (target === undefined) return [{ item: "settings.json", status: "skipped", detail: `${to} is not a JSON object` }];
+
+	const items: ImportPiItem[] = [];
+	const added: Record<string, unknown> = {};
+	for (const key of IMPORTED_SETTINGS_KEYS) {
+		const item = `settings.json ${key}`;
+		if (!Object.hasOwn(source, key)) items.push({ item, status: "not found" });
+		else if (Object.hasOwn(target, key)) items.push({ item, status: "present" });
+		else if (typeof source[key] !== "string") items.push({ item, status: "skipped", detail: "not a string" });
+		else {
+			added[key] = source[key];
+			items.push({ item, status: input.dryRun ? "would copy" : "copied" });
+		}
+	}
+	if (input.dryRun || Object.keys(added).length === 0) return items;
+	try {
+		// Keep the target's own indentation and trailing-newline style.
+		const style = targetText === undefined ? { indent: undefined, trailingNewline: true } : detectJsonFormatting(targetText);
+		const body = JSON.stringify({ ...target, ...added }, null, style.indent ?? 2);
+		fs.writeAtomic(to, style.trailingNewline ? `${body}\n` : body);
+		return items;
+	} catch (error) {
+		const detail = reason(error);
+		return items.map((entry) => (entry.status === "copied" ? { ...entry, status: "failed", detail } : entry));
+	}
+}
+
+// Copies what the target lacks. A dry run reads the same files and writes
+// nothing. The caller has already made sure `target` is a home this launcher
+// owns (and exists, unless this is a dry run).
+export function importPi(input: { source: string; target: string; dryRun: boolean; fs?: ImportPiFs }): ImportPiResult {
+	const options = { ...input, fs: input.fs ?? nodeImportPiFs };
+	const items = IMPORTED_FILES.map((file) => importFile(file.name, file.mode, options));
+	items.push(...importSettings(options));
+	return { items, failed: items.some((item) => item.status === "failed") };
+}
+
+function describe(item: ImportPiItem): string {
+	switch (item.status) {
+		case "copied":
+		case "would copy":
+			return item.detail !== undefined && item.item === "auth.json" ? `${item.status} (${item.detail})` : item.status;
+		case "present":
+			return "already present, kept";
+		case "not found":
+			return "not found";
+		case "skipped":
+			return `skipped: ${item.detail}`;
+		case "failed":
+			return `failed: ${item.detail}`;
+	}
+}
+
+export function formatImportPiReport(result: ImportPiResult, context: { source: string; target: string; dryRun: boolean }): string[] {
+	const lines = [
+		context.dryRun
+			? `Dry run: would import from ${context.source} into ${context.target} (nothing is written)`
+			: `Importing from ${context.source} into ${context.target}`,
+	];
+	for (const item of result.items) lines.push(`  ${item.item}: ${describe(item)}`);
+	const count = (...statuses: ImportPiStatus[]) => result.items.filter((item) => statuses.includes(item.status)).length;
+	const imported = count("copied", "would copy");
+	const rest = `${count("present")} already present, ${count("not found")} not found, ${count("skipped")} skipped`;
+	if (result.failed) lines.push(`Import failed for ${count("failed")} item(s); ${count("copied")} copied and kept. ${rest}.`);
+	else if (imported === 0) lines.push(`Nothing to import: ${rest}.`);
+	else lines.push(`${context.dryRun ? "Would import" : "Imported"} ${imported} item(s); ${rest}.`);
+	return lines;
+}