gentle-pi 4.2.0 → 4.4.0

package/runtime/gentle-shell-uninstall.mjs

@@ -1,7 +1,9 @@
 // Generated by scripts/build-runtime-modules.mjs. Do not edit.
-import { lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmdirSync, rmSync } from "node:fs";
+import { lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { createInterface } from "node:readline";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { withoutBundledNpmCommand } from "./gentle-shell-bundled.mjs";
 import { isolatedDir, launcherConfigPath, parseRawLauncherConfig, provisionedEntry, userPiHome } from "./gentle-shell-launcher.mjs";
 
 // `gentle-shell self-uninstall`: removes what Gentle Shell itself created, then
@@ -264,6 +266,14 @@ async function planSelfUninstall(input                    , configHome        ,
 		{ path: gentleAiState, label: "Gentle AI's state", inside: true },
 	];
 	const defaultConfigHome = canonical(join(homedir, ".pi", "gentle-ai"));
+	// #2201: the standalone launcher keeps the isolated home's config in a
+	// gentle-ai folder next to it (standaloneConfigHome). Next to the default
+	// home it lies inside ~/.gentle-shell and is Gentle Shell's by location;
+	// next to a GENTLE_SHELL_HOME it may be anyone's, so it is only listed.
+	// When GENTLE_PI_CONFIG_HOME names it, the config home's rules apply instead.
+	const defaultHome = resolve(isolated) === resolve(join(homedir, ".gentle-shell", "agent"));
+	const ownConfig = join(dirname(isolated), "gentle-ai");
+	const ownConfigSeparate = comparable(canonical(ownConfig), platform) !== comparable(canonical(configHome), platform);
 	const candidates = [
 		{
 			who: env.GENTLE_SHELL_HOME ? `GENTLE_SHELL_HOME points at ${isolated}` : `The isolated home ${isolated}`,
@@ -279,6 +289,12 @@ async function planSelfUninstall(input                    , configHome        ,
 			allowedInsidePi: defaultConfigHome,
 		},
 		{ who: `The launcher folder ${shellDirectory}`, path: shellDirectory, guards, allowedInsidePi: undefined },
+		...(defaultHome && ownConfigSeparate ? [{
+			who: `Gentle Shell's config folder ${ownConfig}`,
+			path: ownConfig,
+			guards: [...guards, { path: configHome, label: "the Gentle AI config home", inside: true }],
+			allowedInsidePi: undefined,
+		}] : []),
 	];
 	for (const candidate of candidates) {
 		const real = canonical(candidate.path);
@@ -313,11 +329,14 @@ async function planSelfUninstall(input                    , configHome        ,
 
 	// The default isolated home is Gentle Shell's by location; a GENTLE_SHELL_HOME
 	// directory only with the launcher's ownership marker or setup record.
-	const defaultHome = resolve(isolated) === resolve(join(homedir, ".gentle-shell", "agent"));
 	const owned = defaultHome || inspect(join(isolated, HOME_OWNERSHIP_MARKER), "file") === "ok"
 		|| provisionedEntry(launcherConfig, isolatedReal) !== undefined;
 	if (owned || inspect(isolated, "dir") !== "ok") consider({ path: isolated, label: "isolated home: its sign-ins, chats and settings", kind: "dir" });
 	else plan.kept.push(`${isolated}: not created by Gentle Shell (no ${HOME_OWNERSHIP_MARKER} marker or setup record)`);
+	if (defaultHome && ownConfigSeparate) consider({ path: ownConfig, label: "Gentle Shell's own configuration: profiles, banner and other preferences", kind: "dir" });
+	else if (ownConfigSeparate && inspect(ownConfig, "dir") !== "missing") {
+		plan.kept.push(`${ownConfig}: next to GENTLE_SHELL_HOME, so it may not be Gentle Shell's; remove it yourself if it holds only Gentle Shell settings`);
+	}
 	consider({ path: configPath, label: "launcher settings", kind: "file" });
 
 	for (const name of SHARED_CONFIG_FILES) {
@@ -762,6 +781,18 @@ function printBundledPlan(plan             , input                           , o
 	}
 }
 
+/** Replaces `path`'s text through a same-directory temporary file, so a crash never leaves it half-written. */
+function writeTextAtomically(path        , text        )       {
+	const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+	try {
+		writeFileSync(temporary, text);
+		renameSync(temporary, path);
+	} catch (error) {
+		try { unlinkSync(temporary); } catch { /* The temporary file is best effort. */ }
+		throw error;
+	}
+}
+
 /**
  * Runs `gentle-shell self-uninstall` for the bundled install at `root`. Exit
  * codes as runSelfUninstall: 0 done or dry run, 1 refused, cancelled or failed,
@@ -821,6 +852,24 @@ export async function runBundledSelfUninstall(input                           )
 	} catch {
 		// A leftover empty folder is harmless.
 	}
+	// A home that stays must not keep Pi pointed at the npm this uninstall removed
+	// (#2469): an `npmCommand` naming the prefix fails every later `pi install`
+	// with ENOENT naming the deleted node.exe.
+	if (!confirmation.includeShared) {
+		const settingsPath = join(plan.shellHome, "agent", "settings.json");
+		let settingsText                    ;
+		try { settingsText = readFileSync(settingsPath, "utf8"); } catch { settingsText = undefined; }
+		const removal = withoutBundledNpmCommand(settingsText, (path) => within(root, path, platform));
+		if (removal.status === "removed") {
+			try {
+				writeTextAtomically(settingsPath, removal.text);
+				out(`Removed npmCommand from ${settingsPath}: it named the removed install.`);
+			} catch (error) {
+				err(`gentle-shell self-uninstall: could not remove npmCommand from ${settingsPath}: ${error instanceof Error ? error.message : String(error)}`);
+				err(`Pi package installs keep failing until the npmCommand naming ${root} is deleted from it.`);
+			}
+		}
+	}
 	if (plan.held.length > 0) {
 		try {
 			if (!input.deferRemoval) throw new Error("no deferred removal on this system");

package/runtime/native-review-cli.mjs

@@ -124,6 +124,7 @@ export const NATIVE_REVIEW_ERROR_CODE = {
 
 
 
+
 export const NATIVE_REVIEW_MODE_OPERATION = {
 	STATUS: "status",
 	ENABLE: "enable",
@@ -202,10 +203,10 @@ export const NATIVE_REVIEW_MODE_SCOPE = {
 // stream while still succeeding. That last qualifier is what keeps this list
 // honest: v2.4.0 deleted reviewConsentSkippedDefaultProvenance ("Reviews are
 // on by default; this was never explicitly chosen. ..."), which used to ride
-// with the skip notice whenever the resolved mode source was `default`. Under
-// opt-in receipt-driven development a default-source clone is refused long
-// before the consent ceremony runs, so the pinned binary can no longer emit
-// that line and it is removed here rather than left as dead tolerance. Multi-
+// with the skip notice whenever the resolved mode source was `default`. Reviews
+// are on by default again since gentle-ai v4.0.0, but the pinned binary no
+// longer has that function and cannot emit the line, so it is removed here
+// rather than left as dead tolerance. Multi-
 // line stderr is still expected in principle — these are separate Fprintln
 // calls, never one joined string — which is why membership is per line.
 export const REVIEW_CONSENT_NOTICES = Object.freeze([
@@ -1083,6 +1084,20 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// b04b6b75d1a446c942a816fbf92932d16f8c3d3001f93159dee2a92bbf2ebe44.
 	// No new negotiated capability identity is asserted.
 	"4.1.1": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v4.2.0 repeats 4.1.1: the published binary still advertises
+	// capabilities/v2.6 under review-integration/v2. The provider contract moved
+	// from 1.3.0 to 1.4.0 (routing/pi.md, gentle-ai#5536), with published
+	// tarball SHA-256
+	// 9d2927a84ba9a596f69029e3f854b16f86ca4c8b32cc5d63683764ccf2fb394b.
+	// No new negotiated capability identity is asserted.
+	"4.2.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v4.3.1 repeats 4.2.0: the published binary still advertises
+	// capabilities/v2.6 under review-integration/v2, and the provider contract
+	// stays at 1.4.0, with published tarball SHA-256
+	// 58450471280aeb357443d6a28c819132d8c8eb78dd25b12bac64296b2f8c27c2.
+	// The v4.3.0 tag has no release and is never pinned.
+	// No new negotiated capability identity is asserted.
+	"4.3.1": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 

package/runtime/review-risk-assessment.mjs

@@ -268,8 +268,9 @@ export const VERIFICATION_TIER = {
 // ---------------------------------------------------------------------------
 // Agent-raised risk (gentle-shell#1494). The agent that made the change may
 // raise its risk to high by citing one item of the high-risk list in the
-// always-on Task Size section; it can never lower a tier. Lowering stays with
-// the deterministic native assessment.
+// always-on Task Size section; it can never lower a tier. That escalation is
+// the only way a plan gets an independent verifier: a native high or a failed
+// assessment informs but never adds one by itself.
 // ---------------------------------------------------------------------------
 
 export const HIGH_RISK_ITEMS = Object.freeze({
@@ -306,10 +307,17 @@ export function decodeAgentRiskEscalation(value         )                      {
 	return Object.freeze({ item: item                , reason });
 }
 
-/** Raises passive or medium to high when the agent escalated; never lowers. */
-export function escalatedRisk(risk                  , escalation                                 )                   {
-	if (escalation === undefined) return risk;
-	return risk === VERIFICATION_TIER.PASSIVE || risk === VERIFICATION_TIER.MEDIUM ? VERIFICATION_TIER.HIGH : risk;
+/**
+ * The risk tier the verification plan follows. The independent verifier is
+ * for concrete occasions only: the plan is high only when the agent escalated
+ * a named Task Size high-risk item. Without an escalation a native passive
+ * stays passive, and every other native tier -- medium, high, or unassessable
+ * (a failed or unavailable assessment) -- is medium: it informs, but adds no
+ * verifier by itself. The native tier stays visible to callers as `nativeRisk`.
+ */
+export function verificationRisk(nativeRisk                  , escalation                                 )                   {
+	if (escalation !== undefined) return VERIFICATION_TIER.HIGH;
+	return nativeRisk === VERIFICATION_TIER.PASSIVE ? VERIFICATION_TIER.PASSIVE : VERIFICATION_TIER.MEDIUM;
 }
 
 export const RDD_LINE = {
@@ -357,6 +365,8 @@ export const NATIVE_REVIEW_OUTCOME = {
 
 
 
+
+
 
 
 
@@ -367,7 +377,7 @@ export const NATIVE_REVIEW_OUTCOME = {
  * naming which branch fired, up to and including the word "and"; the
  * tier-specific clause is appended after it.
  */
-function riskGatedPlan(gatePrefix        , risk                  , writerProfile               )                   {
+function riskGatedPlan(gatePrefix        , risk                  )                   {
 	if (risk === VERIFICATION_TIER.PASSIVE) {
 		return Object.freeze({
 			writerSelfVerification: false,
@@ -377,26 +387,22 @@ function riskGatedPlan(gatePrefix        , risk                  , writerProfile
 		});
 	}
 
-	if (risk === VERIFICATION_TIER.MEDIUM) {
-		const smallModelBias = writerProfile === WRITER_PROFILE.SMALL;
+	if (risk === VERIFICATION_TIER.HIGH) {
 		return Object.freeze({
 			writerSelfVerification: true,
 			structuralReadbackOnly: false,
-			independentVerifier: smallModelBias,
-			reason: smallModelBias
-				? `${gatePrefix} the native assessment reports medium risk, but the small-model bias raises it one tier to high for verification purposes: the writer self-verifies and a separate independent verifier also runs.`
-				: `${gatePrefix} the native assessment reports medium risk with a large writer profile: the writer's self-verification stands and no separate verifier is required.`,
+			independentVerifier: true,
+			reason: `${gatePrefix} an agent escalation names a Task Size high-risk item: the writer self-verifies and a separate independent verifier runs.`,
 		});
 	}
 
-	// high or unassessable.
+	// medium, or an unassessable tier that did not go through verificationRisk:
+	// both inform only.
 	return Object.freeze({
 		writerSelfVerification: true,
 		structuralReadbackOnly: false,
-		independentVerifier: true,
-		reason: risk === VERIFICATION_TIER.UNASSESSABLE
-			? `${gatePrefix} the native risk assessment could not be produced, so the candidate is treated as high risk: the writer self-verifies and a separate independent verifier always runs.`
-			: `${gatePrefix} the native assessment reports high risk: the writer self-verifies and a separate independent verifier always runs.`,
+		independentVerifier: false,
+		reason: `${gatePrefix} no Task Size high-risk item was escalated: the writer's self-verification stands and no separate verifier runs, whatever the native tier or the model that wrote the change.`,
 	});
 }
 
@@ -417,24 +423,23 @@ function nonClosedOutcomeClause(outcome                     )         {
 
 /**
  * Computes who verifies a delegated writer's change. Verification follows the
- * native risk tier whatever the RDD line and native review outcome
+ * plan risk tier whatever the RDD line and native review outcome
  * (verify-always-rdd-high S1, superseding the gentle-pi#662/#668 on-path): the
  * native review is an additional outside view and never replaces or skips the
  * tier's verification. `nativeReviewOutcome` only shapes the reason text.
  *
+ * `risk` is the plan risk from `verificationRisk`; `writerProfile` is never
+ * consulted, so the model or effort that wrote the change never adds a
+ * verifier.
+ *
  * - `passive`: structural readback by the parent only; no verifier, no tests.
- * - `medium`: the writer self-verifies; a separate independent verifier runs
- *   only when `writerProfile` is `"small"` -- the small-model bias raises the
- *   tier by one for verification purposes (medium -> high). An unknown or
- *   omitted writer profile resolves to `"small"` before it reaches this
- *   function (see `resolveWriterProfile`), so an unrecognized profile never
- *   lowers a tier below what a known small model would get.
- * - `high` or `unassessable` (a failed or unrecognized native assessment is
- *   always treated as high): the writer self-verifies and an independent
- *   verifier always runs.
+ * - `medium` (also an `unassessable` tier passed directly): the writer
+ *   self-verifies; no separate verifier.
+ * - `high` (only through an agent escalation naming a Task Size high-risk
+ *   item): the writer self-verifies and an independent verifier runs.
  */
 export function verificationPlan(input                       )                   {
-	const { rddLine, risk, writerProfile } = input;
+	const { rddLine, risk } = input;
 
 	if (rddLine === RDD_LINE.ON) {
 		const outcome = input.nativeReviewOutcome ?? NATIVE_REVIEW_OUTCOME.UNKNOWN;
@@ -444,14 +449,13 @@ export function verificationPlan(input                       )
 		return riskGatedPlan(
 			`receipt-driven development is on and ${clause}; the native review is an additional outside view that never replaces verification, so the risk-gated path applies exactly as receipt-driven development off, and`,
 			risk,
-			writerProfile,
 		);
 	}
 
 	// rddLine is "off" or "unknown" here -- both gate on the native risk
 	// assessment identically, so an unknown RDD line never lowers a tier, and
 	// neither line ever consults nativeReviewOutcome.
-	return riskGatedPlan(`receipt-driven development is ${rddLine} and`, risk, writerProfile);
+	return riskGatedPlan(`receipt-driven development is ${rddLine} and`, risk);
 }
 
 // ---------------------------------------------------------------------------
@@ -476,15 +480,16 @@ export function verificationPlan(input                       )
 const SMALL_MODEL_ID_TOKEN = /(?:^|[-_./:\s])mini(?:$|[-_./:\s])/i;
 
 /**
- * A writer profile counts as a "small model" for the medium-risk bias when:
+ * A writer profile counts as a "small model" (reported by ASSESS as
+ * `writerProfile`; it never changes the verification plan) when:
  * - its resolved effort is `low`, or
  * - its resolved model id carries `mini` as a whole token (see
  *   `SMALL_MODEL_ID_TOKEN`), or
  * - it carries NO signal at all -- no profile object, or a profile with
  *   neither a model id nor a resolved effort. An unknown or omitted writer
- *   profile fails closed to small rather than defaulting to large, so a
- *   caller that cannot resolve the writer's profile never gets a weaker
- *   verification plan than a known small model would (gentle-pi#662).
+ *   profile fails closed to small rather than defaulting to large. The
+ *   result is reported in the assessment only: the verification plan never
+ *   reads the writer profile, so it cannot add or remove a verifier.
  *
  * A profile that carries a model id or an effort, just not a matching one
  * (for example `{model: {id: "claude-sonnet-5"}, thinking: "high"}`), is
@@ -502,9 +507,9 @@ export function isSmallWriterProfile(profile
 }
 
 /**
- * Maps a resolved writer profile to the `writerProfile` input `verificationPlan`
- * expects. An unknown or omitted profile never lowers a tier: it resolves to
- * `"small"`, exactly like `isSmallWriterProfile` (gentle-pi#662).
+ * Maps a resolved writer profile to the reported `writerProfile`. An unknown
+ * or omitted profile resolves to `"small"`, exactly like
+ * `isSmallWriterProfile` (gentle-pi#662).
  */
 export function resolveWriterProfile(profile                                    )                {
 	return isSmallWriterProfile(profile) ? WRITER_PROFILE.SMALL : WRITER_PROFILE.LARGE;

package/scripts/build-runtime-modules.mjs

@@ -22,6 +22,7 @@ const sources = [
 	"gentle-shell-startup-flow",
 	"gentle-shell-resume-hint",
 	"gentle-shell-uninstall",
+	"gentle-shell-import-pi",
 ];
 const header = "// Generated by scripts/build-runtime-modules.mjs. Do not edit.\n";
 

package/scripts/bundled-engram-migration.mjs

@@ -0,0 +1,119 @@
+// Explicit bundled-store recovery. The provider owns catalog validation and
+// migration; Shell owns promotion and its core-bound provenance. Never called
+// from ordinary startup or upgrade.
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { engramProbeAllowed, engramProvenancePath, parseEngramProvenance } from "../runtime/gentle-shell-bundled.mjs";
+
+export const MIGRATION_USAGE = "Usage: gentle-shell memory migrate --confirm-quiescent\nStop every Engram client before running this command.\n";
+export const MIGRATION_PENDING_NOTICE = "Engram memory disabled: an incomplete memory migration needs recovery. Keep every Engram client stopped, retain the original backup, and follow docs/bundled-install.md#recovering-an-interrupted-migration. Do not remove the migration marker or create a new store before recovery.";
+export const migrationMarkerPath = (prefix) => join(prefix, "config", "engram-migration.json");
+export function migrationPending(prefix) {
+	try { lstatSync(migrationMarkerPath(prefix)); return true; }
+	catch (error) { return error.code !== "ENOENT"; }
+}
+function regularText(path, limit) {
+	const info = lstatSync(path);
+	if (!info.isFile() || info.size > limit) throw new Error("unsafe migration metadata");
+	return readFileSync(path, "utf8");
+}
+const digest = (path) => createHash("sha256").update(readFileSync(path)).digest("hex");
+// Durably record a file or a directory entry change. Windows cannot open a
+// directory for fsync; there NTFS metadata journaling covers the renames.
+function syncPath(path, directory = false) {
+	if (directory && process.platform === "win32") return;
+	const fd = openSync(path, "r");
+	try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+function coreHelp(core, env) {
+	// Older cores route unknown commands through legacy startup. Inspect their
+	// config-free help in an isolated home, never try an unknown data command.
+	const scratch = mkdtempSync(join(tmpdir(), "gentle-engram-capability-"));
+	try {
+		const probe = spawnSync(core, ["--help"], {
+			cwd: scratch, env: { ...env, HOME: scratch, USERPROFILE: scratch, ENGRAM_DATA_DIR: join(scratch, "store") },
+			encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000, maxBuffer: 65536, windowsHide: true,
+		});
+		return !probe.error && !probe.signal && probe.status === 0 && probe.stderr === "" ? probe.stdout.split("\n").map((line) => line.trim()) : [];
+	} finally { rmSync(scratch, { recursive: true, force: true }); }
+}
+function supportsMigration(core, env) {
+	return coreHelp(core, env).includes("migrate-copy --data-dir <absolute-source> --output-dir <new-absolute-destination> --confirm-quiescent --json");
+}
+
+export function migrateBundledEngram({ prefix, core, home, env }) {
+	let markerOwned = false;
+	let promotionStarted = false;
+	let output;
+	let backup;
+	try {
+		if (!core) throw new Error("the verified bundled core is unavailable; run gentle-shell setup first");
+		if (!engramProbeAllowed(env)) throw new Error("explicit Engram selections or a disabled startup policy must be resolved before bundled migration");
+		if (migrationPending(prefix)) throw new Error(MIGRATION_PENDING_NOTICE);
+		const source = join(realpathSync(home), ".engram");
+		if (!lstatSync(source).isDirectory() || realpathSync(source) !== source) throw new Error("the source must be a regular default store directory");
+		const provenancePath = engramProvenancePath(prefix);
+		const original = regularText(provenancePath, 4096);
+		const record = parseEngramProvenance(original);
+		const identity = regularText(join(source, ".instance-id"), 128).trim();
+		if (!record || record.dataDir !== source || record.instanceId !== identity) throw new Error("the store does not match Shell's recorded identity; it cannot be adopted");
+		const coreHash = digest(core);
+		const childEnv = Object.fromEntries(Object.entries(env).filter(([key]) => !key.startsWith("ENGRAM_") && key !== "GH_TOKEN" && key !== "GITHUB_TOKEN"));
+		childEnv.ENGRAM_NO_UPDATE_CHECK = "1";
+		if (!supportsMigration(core, childEnv)) throw new Error("the bundled core does not support migrate-copy; wait for a supporting published bundle. The source and provenance are unchanged");
+		const suffix = randomUUID();
+		output = `${source}.migrating-${suffix}`;
+		backup = `${source}.before-${suffix}`;
+		const marker = migrationMarkerPath(prefix);
+		mkdirSync(dirname(marker), { recursive: true, mode: 0o700 });
+		// A recorded refusal precedes copying/promotion. A killed launcher must not
+		// mistake the rename gap for a fresh install and provision an empty store.
+		writeFileSync(marker, `${JSON.stringify({ source, output, backup, originalProvenance: record })}\n`, { flag: "wx", mode: 0o600 });
+		markerOwned = true;
+		syncPath(marker);
+		syncPath(dirname(marker), true);
+		const result = spawnSync(core, ["migrate-copy", "--data-dir", source, "--output-dir", output, "--confirm-quiescent", "--json"], {
+			env: childEnv, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000, maxBuffer: 16384, windowsHide: true,
+		});
+		if (result.error || result.signal) throw new Error("the provider failed or timed out; no source promotion was attempted");
+		if (result.status !== 0) throw new Error(`the provider rejected migration (exit ${result.status}): ${result.stderr.trim().slice(0, 2048) || "no diagnostic"}`);
+		if (result.stderr !== "") throw new Error("unexpected provider diagnostic with success evidence");
+		let proof;
+		try { proof = JSON.parse(result.stdout); } catch { throw new Error("invalid provider migration evidence"); }
+		if (!proof || proof.migration_completed !== true || proof.source_dir !== source || proof.output_dir !== output || proof.instance_id !== identity) {
+			throw new Error("provider migration evidence does not match the requested store and copy");
+		}
+		if (!lstatSync(output).isDirectory() || realpathSync(output) !== output ||
+			regularText(join(output, ".instance-id"), 128).trim() !== identity ||
+			regularText(join(source, ".instance-id"), 128).trim() !== identity ||
+			regularText(provenancePath, 4096) !== original || digest(core) !== coreHash) {
+			throw new Error("store, provenance or bundled core changed during migration");
+		}
+		// The original is retained, not deleted. From this point any failure keeps
+		// the marker: recovery must reconcile both paths before another launch.
+		promotionStarted = true;
+		renameSync(source, backup);
+		renameSync(output, source);
+		syncPath(dirname(source), true);
+		const temporary = `${provenancePath}.${suffix}.tmp`;
+		writeFileSync(temporary, `${JSON.stringify({ schema: 1, dataDir: source, instanceId: identity, coreSha256: coreHash })}\n`, { flag: "wx", mode: 0o600 });
+		syncPath(temporary);
+		renameSync(temporary, provenancePath);
+		syncPath(dirname(provenancePath), true);
+		// Only a durable promotion and provenance may release the fail-closed marker.
+		rmSync(marker);
+		// The migration is complete; a failed final sync must not report failure.
+		try { syncPath(dirname(marker), true); } catch { /* Best effort. */ }
+		return { code: 0, stdout: `${JSON.stringify({ status: "migrated", instance_id: identity, backup_dir: backup })}\n`, stderr: "" };
+	} catch (error) {
+		if (markerOwned && !promotionStarted) {
+			try { rmSync(migrationMarkerPath(prefix)); } catch { /* Keep the fail-closed marker. */ }
+		}
+		const retained = output ? ` Any partial copy at ${output} is retained; do not use it.` : "";
+		const recovery = promotionStarted ? ` Promotion may be incomplete; original backup: ${backup}. ${MIGRATION_PENDING_NOTICE}` : "";
+		return { code: 1, stdout: "", stderr: `gentle-shell: memory migration failed: ${error.message}.${retained}${recovery}\n` };
+	}
+}

package/scripts/gentle-ai-installer.mjs

@@ -37,7 +37,7 @@ const WINDOWS_SYSTEM_ROOT = "C:\\Windows";
 // version check below) derives from this constant instead of repeating the
 // literal, so a pin bump cannot leave a stale copy behind. See
 // scripts/install-gentle-ai.mjs for the incident that motivated this.
-export const INSTALLER_VERSION = "4.1.1";
+export const INSTALLER_VERSION = "4.3.1";
 export const RELEASE_BASE_URL = `https://github.com/Gentleman-Programming/gentle-ai/releases/download/v${INSTALLER_VERSION}/`;
 export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 	SIGNED_RELEASE_ASSET: "signed-release-asset",
@@ -46,11 +46,11 @@ export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH = "github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai";
 export const GENTLE_AI_WINDOWS_SOURCE_MODULE = "github.com/gentleman-programming/gentle-ai/v4";
 export const GENTLE_AI_WINDOWS_SOURCE_TAG = `v${INSTALLER_VERSION}`;
-// `go mod download -json github.com/gentleman-programming/gentle-ai/v4@v4.1.1`
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v4@v4.3.1`
 // with GOSUMDB=sum.golang.org reports this exact module SumDB checksum, and the
-// tag resolves to commit 898d3976e8049a7238eaa7de60bff325c30d2b3d, the published v4.1.1 release head.
+// tag resolves to commit 2dba7784114fff57864519c4c0d067e952a8c98b, the published v4.3.1 release head.
 // v4.0.0 moved the Go module path to the /v4 major-version suffix.
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:+WmZ2IvIOiJ8qtHa7wsjnYKNasem+PByeOZ6HIjoAL8=";
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:00p8dnjJrhYFq1Qikk2oY6K/UXIty9A/IBUUOUiX9XA=";
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE = `${GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH}@${GENTLE_AI_WINDOWS_SOURCE_TAG}`;
 export const GENTLE_AI_WINDOWS_MINIMUM_GO_VERSION = "1.25.10";
 export const GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE_CODE = "GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE";
@@ -69,7 +69,7 @@ export class GentleAiInstallerError extends Error {
 // Sentinel used while a re-pinned gentle-ai release is not yet published. A
 // sentinel digest can never match a real SHA-256, so installation fails closed,
 // and verify-package-files.mjs refuses to pack/publish while any digest below
-// still holds it. The v4.1.1 digests are pinned from the published release:
+// still holds it. The v4.3.1 digests are pinned from the published release:
 // archive sha256 values verified against the minisign-signed checksums.txt and
 // freshly computed hashes; binary sha256 values computed from the extracted
 // executables.
@@ -111,15 +111,15 @@ async function downloadPinnedGentleAiAsset(asset, destination, options) {
 }
 
 // Windows is absent from signed release archives on purpose. gentle-ai stopped
-// distributing unsigned Windows builds in c4b764d0, so v4.1.1 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v4.3.1 publishes signed
 // Darwin/Linux archives only. Windows x64/arm64 uses the separately verified
 // exact-tag Go SumDB source-build path below; restore archive rows only when
 // upstream ships signed Windows assets.
 export const GENTLE_AI_RELEASE_ASSETS = Object.freeze({
-	"darwin/amd64": asset("gentle-ai_4.1.1_darwin_amd64.tar.gz", "f2e9aebfba3056e88a8d7c7193e4e8c04282dc126d5eaa2216bc807deadecffd", "82351dd86bf7323c6a5b9e9e68b3cc2893a65a4df04fbdf1ef1801cabf5d2338", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_4.1.1_darwin_arm64.tar.gz", "8093dced37130cb26534d81663013f81d9039342e33f00b8c85aa5319aa7eea9", "6362e3641b87ae2b41a8dd7695dad4cf47457ee86c9f63792e474476bfdb6b6a", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_4.1.1_linux_amd64.tar.gz", "57869ebcdba5ba9942493ab413bbc15d146e2451c4dca3eaafcf163fcbd646b4", "7c638c8467efc7036e0ec6b8a1d9080a5e9a64f7ae6cbc6074fce577f789b7fe", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_4.1.1_linux_arm64.tar.gz", "5f8fa38573eea0f2110902f0996aa0b008aac58dc0f9a6abbdf301dcbc93f4eb", "76a36a73d6905a16221496ffe9a193bd79e17951463d711cd03abf370349ef55", "gentle-ai"),
+	"darwin/amd64": asset("gentle-ai_4.3.1_darwin_amd64.tar.gz", "6cf57fee0574daef2abed07f54a355fec3b93ac8f01733dc6c4d3674f1746112", "ca44c3fce186b63a7e7ad455c338133ba1982f4a13485301ce4d66edb73d2928", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_4.3.1_darwin_arm64.tar.gz", "13e8828447f9081465ee0c35a61b24fb49296d51a310c6999227e2aed178956b", "749d08062b0dec13681678a1a1c018613d223ddcca47b5f27681b1d8ab5d14c2", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_4.3.1_linux_amd64.tar.gz", "04ec685c56b42c29dff6db10fc7dc2c730217dc9c96736e53ad2acf3226dafb7", "86248792bde3fe5e9ca93b128c07e7caa6a5b31fac0f9fc84b5b3011b123cb90", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_4.3.1_linux_arm64.tar.gz", "99e7d313a2ff85eaf23a6415e9b3aae67bf74c2fa169b21b93070ada7613f6a0", "df3580506bb5ea63cc4ef5ccebe8b68cfedf66b72f3b51f84ff393183d8cea2b", "gentle-ai"),
 });
 
 // A pinned asset is either a signed archive or, for a prerelease pin only,

package/scripts/installer-downloads.mjs

@@ -44,15 +44,15 @@ export const goPinVersion = go.version;
 // checksums.txt and GitHub's asset digests; every archive was downloaded and
 // re-hashed before pinning. GitHub serves the assets from its asset hosts.
 const engram = Object.freeze({
-	version: "3.4.0",
+	version: "3.5.2",
 	redirectHosts: Object.freeze(["objects.githubusercontent.com", "release-assets.githubusercontent.com"]),
 	archives: Object.freeze({
-		"darwin-arm64": ["darwin_arm64.tar.gz", "d0aa59c9a83d17ae3fc7f5dd31fdab6a26fd8c00fc5e692195753cd0719294f7", 7470202],
-		"darwin-x64": ["darwin_amd64.tar.gz", "3c5bdc73d226af5629cf4f4a781e223142e37c1ebb443c4b596f2e284352e381", 7961674],
-		"linux-x64": ["linux_amd64.tar.gz", "715fda625556e46d65ddb4526bb7f88a3fee5339ca3c44ce44cc652f17fa57f1", 7821191],
-		"linux-arm64": ["linux_arm64.tar.gz", "3309e9c0bbb539d183fd5aa9f9a13cd7aa0e81ec2512b5bedefb8b2bdd35b3e5", 7176726],
-		"win32-x64": ["windows_amd64.zip", "3065736ec7ff8137eb3fc607275f542ea13bb743a5157318c8a8770f11ce3289", 8021225],
-		"win32-arm64": ["windows_arm64.zip", "7463872a85a5e5434cf958bdffc71dda1926bced30d3b6b38c80fec9bb98fbba", 7231641],
+		"darwin-arm64": ["darwin_arm64.tar.gz", "43d398b2fe3327a4a6436c26b2a17d3285ba80bf2f11a22d0796ea2a7fd2b78c", 7749520],
+		"darwin-x64": ["darwin_amd64.tar.gz", "aea28ebf461a4ea86c52b793c29311539d7123875354ed7411eae982fc82ec87", 8181300],
+		"linux-x64": ["linux_amd64.tar.gz", "106a43ca8f43a27c2c260a6787151c3be6d91c5ed3d5e454e6140527adf92e01", 8064598],
+		"linux-arm64": ["linux_arm64.tar.gz", "b0ba49cf5a7d5af436c9744a9a0d638b3f9ebb2a7321c8736d30e96305c2993c", 7472279],
+		"win32-x64": ["windows_amd64.zip", "ba56a36d37b2da85fcb1581bbdbed9ae1ee690e642aab8dbe1e18209bf264afe", 8272809],
+		"win32-arm64": ["windows_arm64.zip", "df5acc5dd6ee407d484074e570c77a79567c0b8dccf55e25ae25a644c1e7db5f", 7530282],
 	}),
 });
 /** The Engram version the bundled install publishes under runtime/. */

package/scripts/installer-preflight.mjs

@@ -248,9 +248,11 @@ export function planPreflight(inventory, { channel = "release" } = {}) {
 	record("gentleAi", classify(inventory.gentleAi, requirements.gentleAi, (o) => o.compatible, true), requirements.gentleAi);
 	const needsNative = tools.gentleAi.status === "unavailable";
 	// The main channel builds Gentle AI from source on every platform.
-	// gentle-pi's postinstall may build Gentle AI from source on Windows, so a
-	// Windows release update needs Go like an installation; main always does.
-	const windowsBuild = platform === "win32" && (update !== null || (needsNative && !npmCurrent));
+	// gentle-pi's postinstall always builds Gentle AI from source on Windows, even
+	// next to an installed gentle-ai, so installing or updating the Shell needs Go,
+	// as does provisioning a missing native binary; main always does.
+	const installsShell = tools.shell.status === "unavailable";
+	const windowsBuild = platform === "win32" && (update !== null || (!npmCurrent && (installsShell || needsNative)));
 	const goStatus = windowsBuild || main ? classify(inventory.go, requirements.go) : "not-required";
 	if (goStatus === "unavailable" || goStatus === "incompatible" || goStatus === "unknown") {
 		// A missing, older or unreadable Go is left as it is: the build gets the

package/scripts/installer-server.mjs

@@ -170,6 +170,9 @@ export const guidance = Object.freeze({
 	setupRateLimit: "`gentle-shell setup` could not finish because GitHub's limit for anonymous API requests was reached on this network. Wait up to an hour, then run the installer again.",
 	// A failed acquire-go whose detail names a Go folder the installer did not publish.
 	goDestinationConflict: `A Go folder from an earlier, interrupted installer run is in the way, and the installer never replaces a folder it cannot prove it published. Remove that folder (shown below), then run the installer again. Nothing was installed.`,
+	// A failed install whose detail shows Windows refused to start the gentle-ai.exe gentle-pi's postinstall built.
+	codeIntegrityBlocked: "Windows refused to run the Gentle AI program (gentle-ai.exe) that the installation builds on this computer, most likely because Smart App Control or another code integrity policy blocks unsigned programs. " +
+		"Windows offers no exception for a single program. Keep using Gentle Shell in WSL, or turn Smart App Control off in Windows Security and run the installer again; on Windows 11 it cannot be turned back on without reinstalling Windows.",
 	// A failed persist-path whose detail shows pnpm could not tell the shell (POSIX SHELL missing or unsupported).
 	persistPathShell: "`pnpm setup` could not tell which shell profile to edit because the SHELL environment variable is missing or names an unsupported shell. Open a regular terminal and run the installer again, or add `$PNPM_HOME/bin` to your PATH yourself.",
 	fallback: "The installation stopped for an unexpected reason. Nothing else will run; check the terminal and run the installer again.",
@@ -186,16 +189,20 @@ function setupDetail(value) {
 const rateLimited = (detail) => /rate limit/i.test(detail) || (/GitHub API/i.test(detail) && /\b403\b/.test(detail));
 const unknownShell = (detail) => /ERR_PNPM_(?:UNKNOWN|UNSUPPORTED)_SHELL/.test(detail);
 const goConflict = (detail) => detail.startsWith("Conflicting Go destination: ");
+// libuv reports a CreateProcess refusal it has no code for, such as a Windows code integrity block
+// (Smart App Control, event 3077), as spawn UNKNOWN.
+const codeIntegrityBlocked = (detail) => /\bspawn UNKNOWN\b/.test(detail);
 // The main channel's typed error when GitHub refused the latest main commit with HTTP 403.
 const githubLimited = (detail) => rateLimited(detail) || (/\bmain-commit-unavailable\b/.test(detail) && /\bHTTP 403\b/.test(detail));
 // Fixed steps whose sanitized last error line may reach the browser.
 // The bundled steps send a detail only for a migration (its error message); a new install's send none.
 const bundledDetail = Object.fromEntries(["claim-prefix", "copy-npm-settings", "install-runtime", "activate-version", "write-launcher", "verify-launcher", "bundled-path"]
 	.map((step) => [step, () => false]));
-const detailSteps = Object.freeze({ ...bundledDetail, "shell-setup": rateLimited, "install-version": () => false, "persist-path": unknownShell, "acquire-go": goConflict,
-	"install-global": githubLimited, "install-shell-main": githubLimited, "build-gentle-ai-main": githubLimited, "update-shell": githubLimited });
+const detailSteps = Object.freeze({ ...bundledDetail, "shell-setup": rateLimited, "install-version": codeIntegrityBlocked, "persist-path": unknownShell, "acquire-go": goConflict,
+	"install-global": (detail) => githubLimited(detail) || codeIntegrityBlocked(detail), "install-shell-main": githubLimited, "build-gentle-ai-main": githubLimited, "update-shell": githubLimited });
+// A step whose detail can match more than one pattern names its guidance by detail.
 const detailGuidance = Object.freeze({ "shell-setup": "setupRateLimit", "persist-path": "persistPathShell", "acquire-go": "goDestinationConflict",
-	"install-global": "githubRateLimit", "install-shell-main": "githubRateLimit", "build-gentle-ai-main": "githubRateLimit", "update-shell": "githubRateLimit" });
+	"install-version": "codeIntegrityBlocked", "install-global": (detail) => (githubLimited(detail) ? "githubRateLimit" : "codeIntegrityBlocked"), "install-shell-main": "githubRateLimit", "build-gentle-ai-main": "githubRateLimit", "update-shell": "githubRateLimit" });
 
 const ID = /^[a-z][a-z0-9-]{0,63}$/;
 function identifier(value, fallback = "unknown") {
@@ -543,7 +550,10 @@ function outcomeView(result) {
 		const detail = step ? setupDetail(result.detail) : null;
 		if (detail) {
 			view.detail = detail;
-			if (detailSteps[step](detail)) view.guidance = guidance[detailGuidance[step]];
+			if (detailSteps[step](detail)) {
+				const key = detailGuidance[step];
+				view.guidance = guidance[typeof key === "function" ? key(detail) : key];
+			}
 		}
 	} else {
 		view.guidance = guidance.outcomes[result.outcome];