gentle-pi 4.2.0 → 4.3.0

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,125 @@
+// 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 supportsBundledSessionOwned(core, env) {
+	if (!core) return false;
+	const clean = Object.fromEntries(Object.entries(env).filter(([key]) => !key.startsWith("ENGRAM_") && key !== "GH_TOKEN" && key !== "GITHUB_TOKEN"));
+	try { return coreHelp(core, { ...clean, ENGRAM_NO_UPDATE_CHECK: "1" }).some((line) => /^serve --session-owned(?:\s|$)/.test(line)); }
+	catch { return false; }
+}
+
+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.2.0";
 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.2.0`
 // 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 4acaf4241beae1e0c977c92dfe406a270f8d40de, the published v4.2.0 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:J8EluS7QrfM+m3vmQlF26B/shZRjD6rBfsKtrABL5mc=";
 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.2.0 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.2.0 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.2.0_darwin_amd64.tar.gz", "8f6a91e0f99cac3aea138705d7d222ea342f53a47602d48cb01488952a1c12f8", "784855e99f1bc45579f01420c923b7dc1dc6d63492cdc0174a9a32e611849e57", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_4.2.0_darwin_arm64.tar.gz", "d5e9a6521de5f08a393635f083f64dc7afc1b8e97884f7aab5ae5eb1f17c7f37", "8ea490287ef796848b0d305cf2b26265e360d3f400efc016972844498fb87097", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_4.2.0_linux_amd64.tar.gz", "552c1642fd10f5d96cfe9bb1cc3b66b30eb47d3074cc7ca0559b598eb086defc", "9212c7b16ea9abfe93e3a16b29d8390e7762b5c07730cf05df1f3e7892ff96a4", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_4.2.0_linux_arm64.tar.gz", "2bebe91b8808ce48d86c4d3700d098e37cb6b0658f196c666d9deeeb7c7c1a7a", "e1b88bd3dcdc8a15ddbcaf8731fd44561f05b06fbcb59d9385bbe82c4b96b5c4", "gentle-ai"),
 });
 
 // A pinned asset is either a signed archive or, for a prerelease pin only,

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];

package/scripts/main-channel.mjs

@@ -35,9 +35,10 @@ export class MainChannelError extends Error {
 	}
 }
 
-/** Same config home as the dev-binary override: GENTLE_PI_CONFIG_HOME or ~/.pi/gentle-ai. */
+/** Same config home as the dev-binary override: a nonempty GENTLE_PI_CONFIG_HOME or ~/.pi/gentle-ai.
+ * Install-level state, so never the standalone launcher's per-home marker (#2201). */
 export function configHome({ env, home }) {
-	return env.GENTLE_PI_CONFIG_HOME ?? join(home, ".pi", "gentle-ai");
+	return env.GENTLE_PI_CONFIG_HOME || join(home, ".pi", "gentle-ai");
 }
 export function channelStatePath(ctx) {
 	return join(configHome(ctx), "channel.json");

package/scripts/run-test-suite.mjs

@@ -30,6 +30,10 @@ export async function runStage(stage) {
 		return !normalizedKey.startsWith("GIT_") && !normalizedKey.startsWith("GENTLE_PI_AGENTS_") && normalizedKey !== "GENTLE_PI_CONFIG_HOME";
 	})) : process.env;
 	if (configHome) env.GENTLE_PI_CONFIG_HOME = configHome;
+	// Unit fixtures also get a private temp dir, removed with the stage, so a
+	// fixture that leaves a subagent unfinished cannot leave its TMPDIR behind.
+	const unitTmp = configHome ? mkdtempSync(join(tmpdir(), "gentle-pi-unit-tmp-")) : undefined;
+	if (unitTmp) env.TMPDIR = unitTmp;
 	try {
 		return await new Promise((resolve) => {
 			const child = spawn(stage.command, { shell: true, stdio: "inherit", env });
@@ -41,6 +45,7 @@ export async function runStage(stage) {
 		});
 	} finally {
 		if (configHome) rmSync(configHome, { recursive: true, force: true });
+		if (unitTmp) rmSync(unitTmp, { recursive: true, force: true });
 	}
 }
 

package/scripts/verify-package-files.mjs

@@ -53,6 +53,7 @@ export const requiredPaths = [
   "scripts/npm-pack-result.mjs",
   "assets/orchestrator.md",
   "assets/orchestrator-delegation.md",
+  "assets/orchestrator-delegation-reference.md",
   "assets/orchestrator-tracking.md",
   "assets/orchestrator-verification.md",
   "assets/orchestrator-writer.md",
@@ -81,6 +82,7 @@ export const requiredPaths = [
   "docs/review-integration.md",
   "extensions/gentle-ai.ts",
   "extensions/resume-hint.ts",
+  "extensions/session-scratch.ts",
   "extensions/skill-registry.ts",
   "lib/child-package-injection.ts",
   "lib/gentle-ai-binary.ts",
@@ -90,6 +92,7 @@ export const requiredPaths = [
   "lib/gentle-shell-update-panel.ts",
   "lib/gentle-shell-startup-flow.ts",
   "lib/gentle-shell-resume-hint.ts",
+  "lib/gentle-shell-import-pi.ts",
   "lib/native-review-cli.ts",
   "lib/status-timing-diagnostics.ts",
   "lib/provider-contract-bundle.ts",
@@ -98,6 +101,7 @@ export const requiredPaths = [
   "lib/review-relay-contract.ts",
   "lib/agent-assets.ts",
   "lib/telemetry-trigger.ts",
+  "lib/session-scratch.ts",
 	"runtime/child-package-injection.mjs",
 	"runtime/gentle-ai-binary.mjs",
 	"runtime/gentle-shell-launcher.mjs",
@@ -107,6 +111,7 @@ export const requiredPaths = [
 	"runtime/gentle-shell-startup-flow.mjs",
 	"runtime/gentle-shell-resume-hint.mjs",
 	"runtime/gentle-shell-uninstall.mjs",
+	"runtime/gentle-shell-import-pi.mjs",
 	"runtime/native-review-cli.mjs",
 	"runtime/status-timing-diagnostics.mjs",
 	"runtime/review-integration-v2.mjs",
@@ -131,17 +136,18 @@ export const requiredPaths = [
   // exact bytes are pinned by the lock-driven scripts/check-provider-contract.mjs
   // drift check, which runs in the same pnpm test flow.
   "contracts/review-provider-contract-mirror/provider-contract.lock.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/README.md",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/manifest.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/orchestration/pi.md",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/schemas/lens.schema.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/schemas/refuter.schema.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/schemas/targeted-validator.schema.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/vectors/lens.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/vectors/refuter.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/vectors/targeted-validator.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/generated/provider-capabilities.baseline.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/generated/provider-roles.baseline.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/README.md",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/manifest.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/orchestration/pi.md",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/routing/pi.md",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/schemas/lens.schema.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/schemas/refuter.schema.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/schemas/targeted-validator.schema.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/vectors/lens.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/vectors/refuter.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/vectors/targeted-validator.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/generated/provider-capabilities.baseline.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/generated/provider-roles.baseline.json",
   "prompts/skill-creation.md",
   "skills/_shared/review-ledger-contract.md",
   "skills/branch-pr/SKILL.md",
@@ -395,7 +401,7 @@ async function main() {
   });
 
   if (driftedContracts.length > 0) {
-    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v4.1.1 runtime's vendored Gentle AI contract artifacts:");
+    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v4.2.0 runtime's vendored Gentle AI contract artifacts:");
     for (const drift of driftedContracts) console.error(`- ${drift.relativePath}: expected ${drift.expected}, got ${drift.actual}`);
     process.exit(1);
   }
@@ -440,7 +446,7 @@ async function main() {
     process.exit(1);
   }
 
-  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v4.1.1 runtime).`);
+  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v4.2.0 runtime).`);
 }
 
 const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;

package/skills/gentle-ai/SKILL.md

@@ -17,7 +17,7 @@ When asked who or what you are, answer as el Gentleman: a Pi-specific coding-age
 - Size every task by the orchestrator's Task Size section: understood, contained risk, and resumable from the original request plus `git diff`. Counts of files, commands, tests, or fixes never decide it. Track only large work in its task document and mirror.
 - For behavior changes with applicable runnable deterministic tests and a clear expected outcome, use test-first by default: observe RED, GREEN, relevant alternate cases, then REFACTOR and record evidence. Test presence alone does not establish applicability. For passive documentation, non-testable changes, an unavailable runner, or no meaningful RED, state why and run proportionate ordinary functional or structural verification. Never invent RED/GREEN, skip checks, or require a chat/TUI toggle.
 - Keep one parent session responsible for orchestration; child subagents should receive concrete phase work and must not spawn more subagents.
-- Parent-only delegation triggers fire one mechanism at a time: an open decision (ask), understanding beyond the evidence budget (explore), high risk (independent verifier), a large task (track), a writer reason (parallel units or context), tooling/worktree incidents, or a parent context past the context backstop.
+- Parent-only delegation triggers fire one mechanism at a time: an open decision (ask), understanding beyond the evidence budget (explore), a named high-risk item (independent verifier, through assess `escalate`), a large task (track), a writer reason (parallel units or context), tooling/worktree incidents, or a parent context past the context backstop.
 - Parallel writers only with disjoint Allowed edit surfaces (runtime-enforced) or isolated worktrees.
 - Forecast review workload before large changes; ask before producing oversized or multi-area diffs.
 - Keep dangerous-command safety independent and authoritative.
@@ -45,9 +45,9 @@ Hard delegation triggers:
 
 - **Evidence-budget rule**: read inline only when the evidence fits one parallel batch of at most 3 calls, ~10k tokens (grep and line ranges, never whole large files). When understanding needs more reading or more than ~5 sequential lookups, delegate one explorer that returns a handoff of at most ~2k tokens with `path:line` evidence. Never force delegation for a small targeted question; do not re-read what the handoff covered beyond one spot check.
 - **Writer rule**: a writer only for a reason (parallel units launched together, or context); size and file count never fire it.
-- **Verification rule**: a high-risk change gets an independent verifier; otherwise the change's own focused test and suite run inline.
+- **Verification rule**: a change that touches a named high-risk item gets an independent verifier (assess `escalate`); otherwise the change's own focused test and suite run inline.
 - **Incident rule**: after wrong cwd, accidental worktree/repo mutation, merge recovery, confusing test command, or environment workaround, diagnose separately.
-- **Context backstop**: when the parent context passes ~150k tokens, pause and delegate the next bounded unit of work to a non-review subagent. Keep command output bounded (counts, `--stat`, `tail`).
+- **Context backstop**: when the runtime signals the context backstop (measured parent context past the smaller of an absolute cap and a fraction of the model's context window), pause and delegate the next bounded unit that needs several steps to a non-review subagent; small edits stay inline. Keep command output bounded (counts, `--stat`, `tail`).
 
 ## Review Lens Selection
 

package/skills/work-unit-commits/SKILL.md

@@ -18,7 +18,7 @@ Use it for:
 - Turning a large change into chained or stacked PRs.
 - Keeping reviewer cognitive load healthy.
 - Applying SDD tasks without accidentally producing a PR above 400 changed lines.
-- Closing an ODD task with a work-unit commit.
+- Committing ODD work in reviewable slices of about 400 authored changed lines.
 
 ## Critical Rules
 
@@ -80,11 +80,13 @@ Each SDD work unit should map cleanly to a commit or PR with:
 
 ## ODD Relationship
 
-Every ODD task closes with at least one work-unit commit:
+ODD commits work units in reviewable slices of about 400 authored changed lines, not one commit per task:
 
+- A slice holds one or more whole tasks with their tests and docs; the last slice closes the feature.
+- A unit whose Risk line names a high-risk item gets its own commit, so native review takes it alone.
 - The native review candidate is that commit, or the PR slice it belongs to when review is deferred, evaluated against the previous reviewed boundary.
 - The running authored line count from work-unit commits feeds the same delivery-strategy vocabulary as SDD.
-- The feature document records the commit identity and, once a delivery strategy applies, the slice boundaries.
+- The feature document records the commit that holds each task and, once a delivery strategy applies, the slice boundaries.
 
 ## Commands