gentle-pi 4.1.0 → 4.3.0

package/assets/orchestrator-writer.md

@@ -2,7 +2,9 @@
 
 Parent Pi session only. Load it when the Writer rule fires or an explicitly activated Judgment Day fix batch is dispatched; small tasks never need it. The Writer rule fires on a named reason (parallel units, the context backstop), never on size alone or a price ratio: a large task without a reason stays inline, following its logbook. Configured per-agent models (`subagents.json` `model_profiles`) still apply to every writer it launches. Each writer prompt requires the self-review of the Parallel review protocol in `orchestrator-verification.md`. A reason holds only when the launch delivers it:
 
-- **Parallelism**: with the Background subagent policy on, launch every disjoint unit in the same turn via `subagent_run` with `mode: "background"`, then wait for all completions before the Seam check; serial launches void the reason: if units cannot launch together, work inline.
+- **Invariants**: each writer prompt names the existing helpers its unit must reuse for shared state (for example the function that adds an entry other commands also add) and the invariants they keep; units built in parallel cannot see each other, so this is the only place they learn them.
+- **Size threshold**: a subagent costs one to two minutes of reading and setup before it writes anything; delegate a unit only when it needs several minutes of work (several files or roughly 100+ changed lines). Several small independent changes are faster inline, one after another.
+- **Parallelism**: a unit is one independent piece of behavior with its own code, tests, and docs; never split one behavior into a test writer, a docs writer, and inline code, and never delegate a unit that depends on another unit still in progress. With the Background subagent policy on, launch every independent unit in the same turn via `subagent_run` with `mode: "background"`, then wait for all completions before the Seam check; serial launches void the reason: if units cannot launch together, work inline.
 
 #### Allowed edit surfaces (MANDATORY)
 
@@ -15,6 +17,8 @@ Before launching a bounded writer (`gentle-ai-worker`, a user-configured `worker
 - pre-existing untracked targets the writer may write, listed explicitly;
 - nothing beyond the delegated task — a surface wider than the task is the same defect as no surface at all.
 
+Test scratch stays outside the worktree (`mktemp -d`), never in the repository (nor caches or `TMPDIR`); state needed inside uses an excluded path the test removes. The runtime owns session scratch; `/gentle:scratch` lists or cleans recorded clones and worktrees.
+
 If the surface genuinely cannot be derived, do not launch the writer or ask the human to author paths. Derive a candidate set first — the exact paths this task would touch — and present that enumerated list as an approve/decline choice under the Lossless Blocking Prompts rules in `orchestrator-prompts.md`. A free-text question asking which paths or globs to authorize is never a valid escalation: computing it is the parent's job.
 
 Relay a writer's `interaction_required` payload about edit surfaces the same way: present its derived candidate paths as the choice, and add or drop paths only on the human's explicit instruction.

package/assets/orchestrator.md

@@ -14,6 +14,8 @@ You are a COORDINATOR, not the default executor for substantial work. Maintain o
 
 Keep synthesis short by default: decision, outcome, next action. Expand only when the user asks or the situation requires detail.
 
+Batch independent tool calls in one turn (parallel calls or one multi-file command). Never spend a turn only on a `todo` or status update.
+
 ## Language Boundary
 
 Reply-language style and the active persona's Spanish variant are defined once in the identity/harness section above (its `Current persona mode:` line). The rules below are delegation/artifact-scoped and not restated there:
@@ -32,7 +34,7 @@ A task is **small** when all three hold:
 2. **Contained risk** — no high-risk item below.
 3. **Resumable from the diff** — resume test: if the session stopped now, someone could finish from the original request and `git diff` alone.
 
-The number of files, commands or tests, fixes, or a requested `todo` list never decides size. A task is **large** only when the resume test fails (several sessions, external waits, separate deliverables, requirements compaction could lose); large tasks get ODD tracking and workers only by the Writer rule, else inline.
+The number of files, commands or tests, fixes, or a requested `todo` list never decides size. A task is **large** only when the resume test fails (several sessions, external waits, deliverables the user wants apart (never several features asked at once), requirements compaction could lose); large tasks get ODD tracking and workers only by the Writer rule, else inline.
 
 Small path: inline (parent; `bash_background` policy); observe RED inline before the fix; run the focused test and the suite inline, once each. No explore, worker, or verifier; no feature document, mirror, or commits unless the user asks; `todo` optional. It needs no lazy asset.
 
@@ -40,8 +42,6 @@ Small path: inline (parent; `bash_background` policy); observe RED inline before
 
 **Risk line**: close every code change, small path or delegated, with `Risk: item N (reason)` or `Risk: none` per the list; any item → Verification rule.
 
-ODD (Default Workflow, harness section above) is mandatory on every request, with the harness's applicable test-first policy (RED, GREEN, refactor); detail: `orchestrator-delegation.md`, `orchestrator-memory.md`.
-
 ## Delegation Rules
 
 Core question: does this inflate parent context without need?
@@ -50,19 +50,19 @@ Before launching bounded writer (`gentle-ai-worker` or `worker`), derive nonempt
 
 ## Mechanisms
 
-Mandatory Delegation Triggers — each mechanism turns on only by its own trigger and is then mandatory (prefer `subagent_run`; role missing/unusable: native `Agent`, same read-only constraints; report fallback). When it resolves, re-evaluate task size.
+Delegation Triggers — each mechanism turns on only when its own trigger condition truly holds, and only then is it mandatory; no trigger holds by default, and when in doubt work inline (prefer `subagent_run`; role missing/unusable: native `Agent`, same read-only constraints; report fallback). When it resolves, re-evaluate task size.
 
 1. **Ask** — open product or design decision → one focused question; stop and wait.
 2. **Evidence-budget rule** — understanding needs more than one read batch or >~5 sequential lookups → one `gentle-ai-explore`, handoff at most ~2k tokens with `path:line` evidence; one spot check only; never for reading before an inline write.
-3. **Verification rule** — high risk → independent `gentle-ai-verify` after the change's own checks (`orchestrator-verification.md`); otherwise checks run inline.
+3. **Verification rule** — only a named high-risk item (assess `escalate`) → independent `gentle-ai-verify`; else inline; runtime admission, gates/overengineering: `orchestrator-verification.md`.
 4. **Track** — large task → feature document, Engram mirror, `todo`, work-unit commits (`orchestrator-tracking.md`, `orchestrator-memory.md`).
-5. **Writer rule** — never by file count or a large task alone; only for a reason (`orchestrator-writer.md`): 2+ independent units, disjoint files, each heavier than a subagent start, launched together in background, else inline; Context backstop.
+5. **Writer rule** — never by file count or a large task alone; only for a reason (`orchestrator-writer.md`): 2+ independent units of behavior (separate features or fixes that do not depend on each other), each heavier than a subagent start (a subagent spends one to two minutes reading before it writes, so a unit qualifies only when it needs several minutes of work: several files or roughly 100+ changed lines; a small change to one module or one command is done inline even when several such changes are independent), launched together in background, else inline; Context backstop. Tests, docs, and code of the same behavior are one unit, never separate writers; a delivery that depends on an earlier one is not independent.
 6. **Incident rule** — diagnose wrong cwd/worktree/git/tooling incidents separately before resuming.
-7. **Context backstop** — parent context past ~150k tokens → delegate the next bounded unit. Bound command output (counts, `--stat`, `tail`).
+7. **Context backstop** — when the runtime signals it → delegate the next unit needing several steps. Bound command output (counts, `--stat`, `tail`).
 
 {{GENTLE_PI_BACKGROUND_POLICY}}; rules: delegation background-subagents block.
 
-Per-action table, Work Routing Ladder, Canonical Workflows: `orchestrator-delegation.md`; blocking-prompt relays and provider defects: `orchestrator-prompts.md`.
+Per-action table, Work Routing Ladder, Canonical Workflows: `orchestrator-delegation-reference.md`; blocking-prompt relays and provider defects: `orchestrator-prompts.md`.
 
 ## Memory Contract
 
@@ -83,7 +83,7 @@ This package injects the mirrored provider-bundle review execution contract into
 ## Safety
 
 - An eligible interactive Pi host may resolve `gentle-ai.review-integration.consent/v3` before the envelope reaches the model. Permission: host-owned. If `gentle_review` returns the envelope unresolved, it is still the original provider-owned two-choice contract. Use `ask_user_choice` exactly or relay losslessly and stop. Never add the host action to a decoded or relayed provider envelope.
-- Never commit unless the user explicitly asks.
+- Never commit unless the user explicitly asks, except the work-unit commits authorized large ODD implementation makes on its feature branch (ODD step 6).
 - Ask before destructive git operations, publishing, or irreversible file changes.
 - Parallel writers only with disjoint Allowed edit surfaces (runtime-enforced) or isolated worktrees.
 - Keep session work inside the project root and registered same-clone worktrees; ask before any read or write outside it, naming the absolute path. Grants are per-target, per-session, never blanket: in-project scripts naming outside paths are not standing consent.

package/bin/engram-guard

@@ -5,5 +5,5 @@
 # local Engram data only by running ENGRAM_BIN, so failing here stops them
 # before any store is opened, created or migrated. It never runs Engram and
 # never reads or writes Engram data; the notice is printed as data, not run.
-printf '%s\n' "${ENGRAM_STARTUP_NOTICE:-Engram memory is disabled by Gentle Shell: Engram store compatibility could not be verified. Back up your Engram data, update Engram, restart its server and Shell, then recheck.}" >&2
+printf '%s\n' "${ENGRAM_STARTUP_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.}" >&2
 exit 78

package/bin/gentle-shell.mjs

@@ -9,6 +9,7 @@ import {
 	chmodSync,
 	closeSync,
 	constants as fsConstants,
+	copyFileSync,
 	existsSync,
 	fstatSync,
 	lstatSync,
@@ -50,22 +51,31 @@ import {
 	parseRawLauncherConfig,
 	planSpawn,
 	POST_INSTALL_REMOVAL_SOURCES,
+	withLauncherPackagesExcluded,
 	postInstallRemovals,
 	provisionedEntry,
+	migrateStandaloneConfig,
 	recordProvisioned,
 	resolveHome,
 	resolvePiRuntime,
 	restoreJsonField,
+	separateHomeHint,
 	shellQuote,
+	standaloneConfigHome,
+	userPiHome,
 } from "../runtime/gentle-shell-launcher.mjs";
+import { formatImportPiReport, importPi } from "../runtime/gentle-shell-import-pi.mjs";
 import {
 	BUNDLED_VERIFY_ENV,
 	bundledEngramSchema,
 	classifyEngramStartup,
 	ENGRAM_COMPANION_SOURCE,
+	ENGRAM_CORE_CHANGED_NOTICE,
+	ENGRAM_PRIVATE_REQUIRED_NOTICE,
 	ENGRAM_PROVISION_FAILED_NOTICE,
 	ENGRAM_RECOVERY_NOTICE,
 	engramHeaderAllows,
+	GENTLE_SHELL_CONFIG_HOME_ENV,
 	engramProbeAllowed,
 	engramProvenanceMatches,
 	engramProvenancePath,
@@ -74,6 +84,7 @@ import {
 	probeEngramEndpoint,
 	sqliteHeaderUserVersion,
 	supportsEngramStartupPolicy,
+	supportsEngramSessionOwned,
 	bundledChildEnv,
 	bundledPi,
 	bundledSetupEnv,
@@ -95,6 +106,7 @@ import {
 import { bundledGentleAiPaths, GENTLE_AI_VERSION, gentleAiBinaryPath, gentleAiIsolationEnv, PackageLocalGentleAiBinaryMissingError } from "../runtime/gentle-ai-binary.mjs";
 import { DEFAULT_THEME_NAME, installIsolatedTuiModeSetting } from "../scripts/install-tui-mode-setting.mjs";
 import { artifactFor, engramPinVersion } from "../scripts/installer-downloads.mjs";
+import { migrateBundledEngram, migrationPending, supportsBundledSessionOwned, MIGRATION_PENDING_NOTICE, MIGRATION_USAGE } from "../scripts/bundled-engram-migration.mjs";
 import { shouldCheckStartupUpdate, findStartupUpdate } from "../runtime/gentle-shell-startup-update.mjs";
 import { promptStartupUpdate } from "../runtime/gentle-shell-update-panel.mjs";
 import { applyStartupChoice, omitStartupVersion, resolveStartupRelaunch } from "../runtime/gentle-shell-startup-flow.mjs";
@@ -268,24 +280,31 @@ function ownEngramStore(observed, core) {
 // of the default endpoint. No Engram executable, SQLite, identity repair, or
 // contact with an explicitly selected endpoint.
 async function classifyBundledMemory() {
+	if (migrationPending(bundledInstall.root)) return { policy: "disabled", notice: MIGRATION_PENDING_NOTICE };
 	const core = verifiedBundledCore();
 	const decision = { env: process.env, core: core !== undefined, coreVersion: engramPinVersion };
 	if (!engramProbeAllowed(process.env)) return classifyEngramStartup({ ...decision, store: "unknown", endpoint: { kind: "unknown" } });
 	const observed = observeEngramStore();
 	const endpoint = await probeEngramEndpoint();
-	return classifyEngramStartup({ ...decision, store: observed.store, endpoint, provenance: ownEngramStore(observed, core) });
-}
-
-// Verified read-only in Engram v3.3.2: `engram instance-id` first runs a GitHub
-// update check that sends GH_TOKEN or GITHUB_TOKEN (cmd/engram/main.go:742-744,
-// 835-847; internal/version/check.go:23-24,60-70,171-176) unless
-// ENGRAM_NO_UPDATE_CHECK is set (check.go:19,49-51,114-117). It then resolves the
-// default ~/.engram (main.go:749-765) and runs EnsureInstanceID
-// (internal/store/instance.go:15-79): the data dir, `.instance-id.lock` (waits
-// up to 60s, internal/store/migration_lock.go:29-76) and `.instance-id`. It
-// returns (main.go:767-775) before orphan migration (main.go:779) and opens no
-// database. The timeout stays below that lock wait: a held lock means a
-// concurrent creator, and memory then stays off for the launch.
+	const result = classifyEngramStartup({ ...decision, store: observed.store, endpoint, provenance: ownEngramStore(observed, core) });
+	if (result.policy === "disabled" && endpoint.kind === "refused" && observed.store === "present" && core) {
+		// Wording only: an unreadable record or core keeps the generic notice and
+		// must never abort startup.
+		try {
+			const record = parseEngramProvenance(readSmallRegularFile(engramProvenancePath(bundledInstall.root, process.platform), 4096));
+			if (record?.dataDir === observed.dataDir && record.instanceId === observed.instanceId && record.coreSha256 !== sha256File(core)) {
+				return { ...result, notice: ENGRAM_CORE_CHANGED_NOTICE };
+			}
+		} catch { /* Keep the generic disabled notice. */ }
+	}
+	return result;
+}
+
+// Verified with the published Engram v3.4.0 darwin-arm64 binary in an isolated
+// HOME: `instance-id` creates only `.instance-id.lock` and `.instance-id`,
+// without a database. Keep update checks suppressed and GitHub tokens removed
+// for this provisioning invocation. The timeout stays below the identity lock
+// wait: a held lock means a concurrent creator, so memory stays off that launch.
 const ENGRAM_PROVISION_TIMEOUT_MS = 15000;
 
 // A fresh launch's store identity, provisioned by Shell itself with the verified
@@ -338,6 +357,7 @@ async function ensureEngramCompanion(home, runtime, stdio, timeoutMs) {
 	if (!Array.isArray(packages)) return { ok: false, exitCode: 1, message: "gentle-shell: cannot verify Engram startupPolicy from non-array packages" };
 	let pinned = false;
 	let local = false;
+	let localOwned = true;
 	let npmSelected = false;
 	for (const entry of packages) {
 		const source = typeof entry === "string" ? entry : entry?.source;
@@ -351,9 +371,10 @@ async function ensureEngramCompanion(home, runtime, stdio, timeoutMs) {
 			return { ok: false, exitCode: 1, message: `gentle-shell: selected companion ${source} lacks engram.startupPolicy=1; update it and recheck (selection preserved)` };
 		}
 		local = true;
+		localOwned &&= supportsEngramSessionOwned(readJsonIfExists(join(selected, "package.json")));
 	}
-	if (local && !npmSelected) return { ok: true };
-	if (pinned && supportsEngramStartupPolicy(readJsonIfExists(metadata))) return { ok: true };
+	if (local && !npmSelected) return { ok: true, sessionOwned: localOwned };
+	if (pinned && supportsEngramStartupPolicy(readJsonIfExists(metadata))) return { ok: true, sessionOwned: localOwned && supportsEngramSessionOwned(readJsonIfExists(metadata)) };
 	process.stderr.write(`gentle-shell: installing policy-capable companion ${ENGRAM_COMPANION_SOURCE} through Pi\n`);
 	const result = await spawnAndWait(runtime.command, [...runtime.args, "install", ENGRAM_COMPANION_SOURCE], buildSetupEnv(home, runtime), stdio, timeoutMs);
 	let declared = false;
@@ -364,7 +385,7 @@ async function ensureEngramCompanion(home, runtime, stdio, timeoutMs) {
 	if (!result.ok || result.timedOut || !declared || !supportsEngramStartupPolicy(readJsonIfExists(metadata))) {
 		return { ok: false, exitCode: 1, message: "gentle-shell: companion installation did not establish engram.startupPolicy=1; the Engram guard still keeps unverified stores closed. Repair gentle-engram, then restart Shell." };
 	}
-	return { ok: true };
+	return { ok: true, sessionOwned: localOwned && supportsEngramSessionOwned(readJsonIfExists(metadata)) };
 }
 
 // The bundled children's environment (bundledChildEnv), with the pinned Engram
@@ -632,6 +653,42 @@ function handleHomeCommand(commandArgs) {
 	process.exit(0);
 }
 
+// `gentle-shell [home selectors] home import-pi [--dry-run]`: copies the
+// user's pi sign-ins, MCP servers and default model into the resolved
+// separate home (lib/gentle-shell-import-pi.ts). A home that is new or empty
+// is first bootstrapped exactly as a first launch would, so the files this
+// adds never make it look foreign to auto-provisioning (homeIsForeign).
+async function handleImportPiCommand(args) {
+	const options = args.commandArgs.slice(1);
+	if (options.some((option) => option !== "--dry-run")) fail("gentle-shell home import-pi accepts only --dry-run. Run 'gentle-shell --help'.", 2);
+	const dryRun = options.includes("--dry-run");
+	let home = resolveHome({ args, env: process.env, homedir: homedir(), config: loadConfig() });
+	if (home.mode === "path") home = { ...home, dir: resolvePath(home.dir) };
+	const source = resolvePath(userPiHome(process.env, homedir()));
+	const refusal = "Choose a separate home with --isolated or --home <path>.";
+	if (home.mode === "link") {
+		fail(`gentle-shell home import-pi: the selected home is your pi home itself (--link), so there is nothing to import. ${refusal}`, 1);
+	}
+	if ([source, join(homedir(), ".pi", "agent")].some((piHome) => safeRealpath(piHome) === safeRealpath(home.dir))) {
+		fail(`gentle-shell home import-pi: ${home.dir} is your pi home itself, so there is nothing to import. ${refusal}`, 1);
+	}
+	if (homeNeedsBootstrap(home.dir)) {
+		if (dryRun) {
+			process.stdout.write(`Would prepare ${home.dir} as a new Gentle Shell home\n`);
+		} else {
+			try {
+				await bootstrapOwnedHome(home);
+			} catch (error) {
+				fail(`gentle-shell home import-pi: could not prepare ${home.dir} (${error.message}); nothing was imported`, 1);
+			}
+			process.stdout.write(`Prepared ${home.dir} as a new Gentle Shell home\n`);
+		}
+	}
+	const result = importPi({ source, target: home.dir, dryRun });
+	for (const line of formatImportPiReport(result, { source, target: home.dir, dryRun })) process.stdout.write(`${line}\n`);
+	process.exitCode = result.failed ? 1 : 0;
+}
+
 // Test/development-only override for the setup subcommand's gentle-ai
 // executable path. Lets a test point at a stub script (or a deliberately
 // missing path) without touching the real pinned .gentle-ai/v<version>/gentle-ai
@@ -804,12 +861,18 @@ function buildSetupEnv(home, runtime, piLauncherDir) {
 		const env = bundledSetupEnv({ ...bundledEnv, PI_CODING_AGENT_DIR: home.dir, GENTLE_PI_AGENT_HOME: home.dir }, { dirs: bundledSetupDirs, platform: process.platform });
 		return gentleAiIsolationEnv(env, { packageRoot });
 	}
-	return {
+	const env = {
 		...process.env,
 		PI_CODING_AGENT_DIR: home.dir,
 		GENTLE_PI_AGENT_HOME: home.dir,
 		PATH: [...(piLauncherDir ? [piLauncherDir] : []), dirname(runtime.command), process.env.PATH ?? ""].join(delimiter),
 	};
+	// #2201: the isolated home's own config folder, given to Gentle AI the
+	// bundled way (gentleAiIsolationEnv); never an outer session's marker.
+	const configHome = standaloneConfigHome(home);
+	if (configHome === undefined) delete env[GENTLE_SHELL_CONFIG_HOME_ENV];
+	else env[GENTLE_SHELL_CONFIG_HOME_ENV] = configHome;
+	return gentleAiIsolationEnv(env, { packageRoot });
 }
 
 // Gentle AI requires a `pi` on its PATH and runs `pi install npm:gentle-pi`
@@ -852,15 +915,34 @@ function sharedPersonaPath() {
 	return join(homedir(), ".pi", "gentle-ai", "persona.json");
 }
 
-// The persona files a setup run may rewrite. Bundled (S9): the prefix's own,
-// which a Gentle AI with GENTLE_AI_PI_CONFIG_DIR (gentle-ai #5462) writes, and
-// still the user's, which a pinned Gentle AI without it writes; restoring an
-// unchanged file does nothing.
-function setupPersonaPaths() {
-	if (!bundledInstall) return [sharedPersonaPath()];
-	return [join(bundledGentleAiPaths(bundledInstall.root, process.platform).piConfig, "persona.json"), sharedPersonaPath()];
+// The persona files a setup run may rewrite. Bundled (S9) and the standalone
+// isolated home (#2201): its own config folder's, which a Gentle AI with
+// GENTLE_AI_PI_CONFIG_DIR (gentle-ai #5462) writes, and still the user's,
+// which a pinned Gentle AI without it writes; restoring an unchanged file
+// does nothing.
+function setupPersonaPaths(home) {
+	if (bundledInstall) return [join(bundledGentleAiPaths(bundledInstall.root, process.platform).piConfig, "persona.json"), sharedPersonaPath()];
+	const configHome = standaloneConfigHome(home);
+	return configHome === undefined ? [sharedPersonaPath()] : [join(configHome, "persona.json"), sharedPersonaPath()];
 }
 
+// The real filesystem behind migrateStandaloneConfig (#2201).
+const configMigrationFs = {
+	kind: (path) => {
+		try {
+			const stat = lstatSync(path);
+			return stat.isDirectory() ? "dir" : stat.isFile() ? "file" : "other";
+		} catch {
+			return "missing";
+		}
+	},
+	list: (path) => readdirSync(path),
+	mkdirPrivate: (path) => {
+		mkdirSync(path, { recursive: true, mode: 0o700 });
+	},
+	copyNew: (from, to) => copyFileSync(from, to, fsConstants.COPYFILE_EXCL),
+};
+
 // Bundled setup (S9): the pinned Engram GENTLE_AI_ENGRAM_BIN names, published
 // once in runtime/ (verified, never brew or the user's PATH). A failure stops
 // setup rather than let Gentle AI acquire another Engram.
@@ -1139,8 +1221,10 @@ async function runSetupFlow(home, runtime, { dryRun, stdio, timeoutMs }) {
 
 	const setupArgs = ["install", "--agent", "pi", "--scope", "global", ...(dryRun ? ["--dry-run"] : [])];
 	const piLauncherDir = writeSetupPiLauncher(runtime);
-	const env = buildSetupEnv(home, runtime, piLauncherDir);
-	const personaSnapshots = setupPersonaPaths().map((path) => [path, safely("snapshot your Pi persona file", path, undefined, () => snapshotFile(path))]);
+	// #2143: a Gentle AI with package exclusion never installs the launcher-owned
+	// gentle-pi; an older one ignores this and runPostInstallCleanup removes it.
+	const env = withLauncherPackagesExcluded(buildSetupEnv(home, runtime, piLauncherDir));
+	const personaSnapshots = setupPersonaPaths(home).map((path) => [path, safely("snapshot your Pi persona file", path, undefined, () => snapshotFile(path))]);
 	const statePath = sharedGentleAiStatePath();
 	const originalStateText = safely("read your Gentle AI state file", statePath, undefined, () => readParsableJsonText(statePath));
 	// Theme restore (never for --link — that home is the user's own
@@ -1392,6 +1476,25 @@ function writeHomeOwnershipMarker(home) {
 	writeFileSync(homeOwnershipMarkerPath(home), `${content}\n`, "utf8");
 }
 
+// The isolated/--home bootstrap: the first launch's own (main, below) and
+// `home import-pi`'s before it adds files to a new or empty home.
+async function bootstrapOwnedHome(home) {
+	// 0700: under umask 002 a default mode would leave ~/.gentle-shell group-writable,
+	// which the bundled install's prefix claim must tighten or refuse.
+	mkdirSync(home.dir, { recursive: true, mode: 0o700 });
+	await installIsolatedTuiModeSetting(home.dir);
+	writeHomeOwnershipMarker(home); // R3-001: lets a failed first auto-provision attempt still be retried later
+}
+
+function homeNeedsBootstrap(dir) {
+	if (!existsSync(dir)) return true;
+	try {
+		return isDirectory(dir) && readdirSync(dir).length === 0;
+	} catch {
+		return false;
+	}
+}
+
 // `homeHadContentBeforeBootstrap` must be read by the caller (main, below)
 // before the isolated/--home bootstrap runs: that bootstrap itself creates
 // and seeds a brand-new directory (settings.json with tuiMode, and now the
@@ -1782,16 +1885,32 @@ async function main() {
 	const args = parseLauncherArgs(process.argv.slice(2));
 	if (args.error !== undefined) fail(`${args.error}\nRun 'gentle-shell --help' for usage.`, 2);
 	if (args.help) {
-		process.stdout.write(`${helpText()}\nBundled Engram safety: memory opens only a fresh, verified or Shell-provisioned store; otherwise ENGRAM_BIN\nis Shell's guard and memory stays off. Back up data, update Engram, restart its server and Shell, then recheck.\nAn explicit ENGRAM_BIN or ENGRAM_URL is kept and bypasses the guard.\n`);
+		process.stdout.write("Pi updates: update reinstalls the verified supplier of the Pi this launcher runs (a global Pi, or the\nShell package whose adjacent peer it is, at the same Shell version) and reads the resulting Pi version back.\nUnknown ownership refuses without installing; update --extensions-only stays Pi-only.\nPrefix-bundled Pi updates with gentle-shell upgrade.\n");
+		process.stdout.write(`${helpText()}\nBundled Engram safety: memory opens only a fresh, verified or Shell-provisioned store; otherwise ENGRAM_BIN\nis Shell's guard and memory stays off. Matching versions or updating alone do not prove compatibility.\nReuse requires a server with verified /compatibility evidence or matching Shell-provisioned store identity.\nBack up existing data before manual changes; do not delete it or bypass the safety check.\nShell rechecks on every launch and remains usable without memory.\nAn explicit ENGRAM_BIN or ENGRAM_URL is kept and bypasses the guard.\n`);
 		process.exit(0);
 	}
 	if (args.command === "home") {
-		handleHomeCommand(args.commandArgs);
+		if (args.commandArgs[0] === "import-pi") await handleImportPiCommand(args);
+		else handleHomeCommand(args.commandArgs);
 		return;
 	}
 	// The verification input applies to `--version` only (scripts/bundled-install.mjs upgradeBundled).
 	const verifying = args.version && args.command === undefined ? process.env[BUNDLED_VERIFY_ENV] : undefined;
 	const bundled = resolveBundledInstall({ packageRoot, platform: process.platform, fs: bundledFs, verifying });
+	if (args.command === "memory") {
+		if (args.commandArgs.length !== 2 || args.commandArgs[0] !== "migrate" || args.commandArgs[1] !== "--confirm-quiescent") {
+			process.stderr.write(MIGRATION_USAGE);
+			process.exitCode = 2;
+			return;
+		}
+		if (!bundled) fail("gentle-shell: memory migrate requires a prefix-bundled installation", 1);
+		bundledInstall = bundled;
+		const result = migrateBundledEngram({ prefix: bundled.root, core: verifiedBundledCore(), home: homedir(), env: process.env });
+		process.stdout.write(result.stdout);
+		process.stderr.write(result.stderr);
+		process.exitCode = result.code;
+		return;
+	}
 	if (args.command === "upgrade") {
 		if (bundled) process.exitCode = await handleBundledUpgrade(bundled, args.commandArgs);
 		else await handleUpgradeCommand(args.commandArgs);
@@ -1847,7 +1966,11 @@ async function main() {
 	});
 	if (versionProbe.error) fail(`Could not run the pi runtime at "${runtime.command}": ${versionProbe.error.message}`, 1);
 	const versionCheck = checkPiVersion(versionProbe.stdout ?? "");
-	if (!versionCheck.ok) fail(versionCheck.message, 1);
+	// A managed self update is how an old Pi gets replaced, so the minimum-version
+	// gate must not block it; everything else still requires the minimum.
+	const managedSelfUpdate = !bundled && args.piSubcommand === "update" && versionCheck.version !== undefined
+		&& (await import("../scripts/pi-update.mjs")).managedUpdatePlan(args.passthrough).self;
+	if (!versionCheck.ok && !managedSelfUpdate) fail(versionCheck.message, 1);
 
 	if (args.version) {
 		process.stdout.write(`${describeVersion({ gentlePiVersion: ownPackageVersion(), piVersion: versionCheck.version, home })}\n`);
@@ -1869,6 +1992,15 @@ async function main() {
 			if (next.note) process.stderr.write(`${next.note}\n`);
 		}
 		passthrough = plan.piArgs;
+	} else if (args.piSubcommand === "update") {
+		const { managedUpdatePlan, updateSelectedPi } = await import("../scripts/pi-update.mjs");
+		const plan = managedUpdatePlan(args.passthrough);
+		if (plan.self) {
+			process.exitCode = await updateSelectedPi({ runtime, packageRoot, platform: process.platform, currentVersion: versionCheck.version, cwd: tmpdir(),
+				adapters: await packageManagerAdapters(), out: (line) => process.stdout.write(`${line}\n`) });
+			if (plan.piArgs === undefined) return;
+		}
+		passthrough = plan.piArgs;
 	}
 
 	// Home-ownership signal for auto-provisioning (S9, homeIsForeign): must be
@@ -1888,12 +2020,22 @@ async function main() {
 	// Isolated-home bootstrap: only on a home gentle-shell has not seen before
 	// (link never bootstraps — it reuses the user's own pi agent home as-is).
 	if ((home.mode === "isolated" || home.mode === "path") && !existsSync(home.dir)) {
-		// 0700: under umask 002 a default mode would leave ~/.gentle-shell group-writable,
-		// which the bundled install's prefix claim must tighten or refuse.
-		mkdirSync(home.dir, { recursive: true, mode: 0o700 });
-		await installIsolatedTuiModeSetting(home.dir);
-		writeHomeOwnershipMarker(home); // R3-001: lets a failed first auto-provision attempt still be retried later
-		process.stderr.write(`gentle-shell: using a separate home at ${home.dir}. Run 'gentle-shell --link' to reuse your pi sign-ins and chats.\n`);
+		await bootstrapOwnedHome(home);
+		const piSignIns = existsSync(join(userPiHome(process.env, homedir()), "auth.json"));
+		process.stderr.write(`${separateHomeHint(home, { piSignIns })}\n`);
+	}
+
+	// #2201: the standalone isolated home's own config folder, seeded once from
+	// the shared ~/.pi/gentle-ai. Not when an explicit GENTLE_PI_CONFIG_HOME
+	// decides the config home; never blocks the launch.
+	const configHome = bundled || process.env.GENTLE_PI_CONFIG_HOME ? undefined : standaloneConfigHome(home);
+	if (configHome !== undefined) {
+		try {
+			const migration = migrateStandaloneConfig({ source: join(homedir(), ".pi", "gentle-ai"), target: configHome, fs: configMigrationFs });
+			for (const line of migration.lines) process.stderr.write(`${line}\n`);
+		} catch (error) {
+			process.stderr.write(`gentle-shell: could not prepare ${configHome} (${error.message}); continuing\n`);
+		}
 	}
 
 	if (bundled) {
@@ -2043,6 +2185,16 @@ async function main() {
 			// could not be verified is reported, never a reason to stop Shell.
 			const companion = await ensureEngramCompanion(home, runtime, ["ignore", 2, 2], 10000);
 			if (!companion.ok) process.stderr.write(`${companion.message}\n`);
+			if (bundledMemory.policy === "allow" && !bundledMemory.url) {
+				const mode = process.env.ENGRAM_SERVER_MODE;
+				if (mode !== undefined && mode !== "session-owned") {
+					bundledMemory = { policy: "disabled", notice: "Engram memory disabled: explicit ENGRAM_SERVER_MODE is invalid for a local bundled server; unset it or select exactly session-owned. Your selection has not been overridden." };
+				} else {
+					bundledMemory = companion.ok && companion.sessionOwned && supportsBundledSessionOwned(verifiedBundledCore(), process.env)
+						? { ...bundledMemory, owned: true }
+						: { policy: "disabled", notice: ENGRAM_PRIVATE_REQUIRED_NOTICE };
+				}
+			}
 			// A fresh store's identity and provenance exist before Pi starts, or
 			// memory stays off: Pi never runs with allow without a written record.
 			if (bundledMemory.fresh && !provisionEngramStore()) bundledMemory = { policy: "disabled", notice: ENGRAM_PROVISION_FAILED_NOTICE };
@@ -2061,6 +2213,7 @@ async function main() {
 		passthrough: [...managedHerdrExtensionArgs(home, args), ...passthrough],
 		piSubcommand: args.piSubcommand,
 		baseEnv: bundledEnv ?? process.env,
+		bundled: Boolean(bundled),
 		homedir: homedir(),
 		// The spawn below sets no cwd, so pi runs in the launcher's own.
 		cwd: process.cwd(),

package/contracts/review-provider-contract-mirror/provider-contract.lock.json

@@ -1,16 +1,17 @@
 {
   "schema": "gentle-pi.review-provider-contract-mirror-lock/v1",
   "acquisition": "field-test-local",
-  "contract_semver": "1.3.0",
+  "contract_semver": "1.4.0",
   "source": {
     "kind": "archive",
-    "archive_sha256": "b04b6b75d1a446c942a816fbf92932d16f8c3d3001f93159dee2a92bbf2ebe44"
+    "archive_sha256": "9d2927a84ba9a596f69029e3f854b16f86ca4c8b32cc5d63683764ccf2fb394b"
   },
-  "tree_sha256": "a2b95892ec8f10340d8d1bb4fc805f9c92db000f58b60b382ff859d312fdc023",
+  "tree_sha256": "aab5ab7fe7ee6bb180d8bbce21c034cebb0c0d284afcc8664a9b3bb57323c35d",
   "entries": {
-    "README.md": "18baab5ee79aefd0bc62a28da0dadcf2162544f57a940c5b859cd6bc4932a085",
-    "manifest.json": "4e335a987e053dac42425ffe31628253eb43dd26f1235085fa90b200bce13d13",
+    "README.md": "3a655c2f19aee02636da062f0cae7a189b7e5f691c8ba8010f2ed50e5d8e8d70",
+    "manifest.json": "d2b5765e28df5b2459848379e91a27beb806916fabc96207060ad1cc5e911972",
     "orchestration/pi.md": "2d7ddd99f1c739a97f4a6b3929e5e2bdddcbf69aed69356395038d90bca25b2f",
+    "routing/pi.md": "1c7466e2333c08e386b4b5afb081531146d181030692463431e7695df7f90690",
     "schemas/lens.schema.json": "9b8a2354a570888486015434501b66b51441a3baf5bf858635e4fff56b2e8298",
     "schemas/refuter.schema.json": "36f8267c6c3f04600b8f1cb77df70d90858611af822cc81922efd6b3502fb646",
     "schemas/targeted-validator.schema.json": "40e397195bdfbc6782fc3090f20c5be082e4d14d2855314f99ecb8506133eddc",
@@ -19,8 +20,8 @@
     "vectors/targeted-validator.json": "7b5a5165e3a913863fb98d2ba5387811860c21333b5c37e6ed3b4e0d121cf2fa"
   },
   "generated": {
-    "generated/provider-capabilities.baseline.json": "f439a3f83394219dae5257a88f112eba5e67f9d4e566eb6d9f3f5608b727c1f7",
-    "generated/provider-roles.baseline.json": "71982937962834120b8304c795bf0e90c04b262a4293c6b96bf423b68a5781e0"
+    "generated/provider-capabilities.baseline.json": "bca708f5f67f506b4acb2cfdcb775b02a51468579fc7d6b4d169785ff411a215",
+    "generated/provider-roles.baseline.json": "aa36ec6f7469ac6faab756eec681f68f234cbadc1e12b345a93c6c34aa01f7aa"
   },
   "runtimes": [
     "claude-code",

package/contracts/review-provider-contract-mirror/{v1.3.0 → v1.4.0}/bundle/README.md

@@ -19,4 +19,11 @@ It carries no executable content, same as every other file in this bundle: a
 runtime mirrors and delivers the text as-is and still relies on Go for every
 review decision, prompt, receipt, and delivery gate.
 
+## Routing
+
+manifest.json's routing array lists, for closed runtimes only, one
+routing/<runtime>.md file: the exact ODD implementation-routing block Gentle
+AI renders for that runtime, whose prompt Gentle AI does not install. It is
+data only as well: a runtime mirrors and delivers the text as-is.
+
 Go remains the admission authority for prompts, results, receipts, and delivery gates.

package/contracts/review-provider-contract-mirror/{v1.3.0 → v1.4.0}/bundle/manifest.json

@@ -1,6 +1,6 @@
 {
   "schema": "gentle-ai.review-provider-contract-bundle/v1",
-  "contract_semver": "1.3.0",
+  "contract_semver": "1.4.0",
   "transport_capability": "gentle-ai.provider-transport/v1",
   "runtimes": [
     "claude-code",
@@ -10,7 +10,7 @@
   ],
   "readme": {
     "path": "README.md",
-    "sha256": "18baab5ee79aefd0bc62a28da0dadcf2162544f57a940c5b859cd6bc4932a085"
+    "sha256": "3a655c2f19aee02636da062f0cae7a189b7e5f691c8ba8010f2ed50e5d8e8d70"
   },
   "roles": [
     {
@@ -70,5 +70,14 @@
         "sha256": "2d7ddd99f1c739a97f4a6b3929e5e2bdddcbf69aed69356395038d90bca25b2f"
       }
     }
+  ],
+  "routing": [
+    {
+      "runtime": "pi",
+      "file": {
+        "path": "routing/pi.md",
+        "sha256": "1c7466e2333c08e386b4b5afb081531146d181030692463431e7695df7f90690"
+      }
+    }
   ]
 }