gentle-pi 3.5.1 → 3.7.0

package/lib/inprocess-reviewer.ts

@@ -9,7 +9,11 @@
 // the caller's "provider/id" selection through pi's live model registry,
 // authenticates through the registry's own resolver, and completes exactly
 // one frozen prompt as a single user message — no systemPrompt, no tools, no
-// session, no extension hooks.
+// session, and none of pi's tool/skill/prompt extension hooks. Extension
+// *providers* are the opposite: they are explicitly in scope. Reading the
+// earlier "no extension hooks" wording as "no extension providers" is what
+// produced gentle-shell#1304, where every extension-registered model was
+// unreachable, so the distinction is stated here rather than implied.
 //
 // Every I/O seam is injected (`registry`, `complete`, `now`), so this module
 // runs under tests with no network and no pi process. gentle-pi#311 P2 wires
@@ -22,18 +26,32 @@ import { SAFE_MODEL_ID_PATTERN } from "./model-routing-authority.ts";
 
 // ---------------------------------------------------------------------------
 // Registry seam — a structural subset of pi's live ModelRegistry
-// (@earendil-works/pi-coding-agent core/model-registry.ts). Only `find` and
-// `getApiKeyAndHeaders` are needed here; the real registry's resolved auth
-// carries extra optional fields (`baseUrl`, `env`) that this narrower shape
-// simply ignores.
+// (@earendil-works/pi-coding-agent core/model-registry.ts). `find` and
+// `getApiKeyAndHeaders` are required. `getProvider` is optional and selects
+// the dispatch path: when present, the completion goes through the composed
+// provider it returns (which is what reaches extension-registered providers);
+// when absent, it falls back to `deps.complete`, so a test double with no
+// composition layer still satisfies the seam. The real registry's resolved
+// auth carries extra optional fields (`baseUrl`, `env`) that this narrower
+// shape simply ignores.
 // ---------------------------------------------------------------------------
 
+/**
+ * The single method this module needs from a resolved provider. pi's
+ * `Provider.streamSimple` returns an `AssistantMessageEventStream`; only its
+ * `result()` is consumed here, so the seam asks for nothing more.
+ */
+export interface InProcessReviewerProvider {
+	streamSimple(model: Model<Api>, context: Context, options?: SimpleStreamOptions): { result(): Promise<AssistantMessage> };
+}
+
 export interface InProcessReviewerRegistry {
 	find(provider: string, modelId: string): Model<Api> | undefined;
 	getApiKeyAndHeaders(model: Model<Api>): Promise<
 		| { readonly ok: true; readonly apiKey?: string; readonly headers?: ProviderHeaders }
 		| { readonly ok: false; readonly error: string }
 	>;
+	getProvider?(provider: string): InProcessReviewerProvider | undefined;
 }
 
 export const INPROCESS_REVIEWER_FAILURE = {
@@ -180,6 +198,33 @@ export async function runInProcessReviewer(request: InProcessReviewerRequest, de
 		);
 	}
 
+	// pi's composed provider is the only layer that honors extension-registered
+	// providers (core/provider-composer.ts: `extension.streamSimple` when
+	// `model.api === extension.api`). pi-ai's `completeSimple` resolves against
+	// its own builtin-only registry and throws for any extension api, so a seam
+	// that carries `getProvider` is always preferred; a seam without it at all
+	// (a test double with no composition layer) still uses `deps.complete`.
+	// A registry that has `getProvider` yet owns no provider for a model its
+	// own `find` just resolved is incoherent: refuse, never route past it.
+	//
+	// The lookup deliberately uses `parsed.provider` — the key `find` was
+	// called with — and not `model.provider`, which is a field of the object
+	// `find` returned. In pi's registry both reads hit one provider map
+	// (core/model-runtime.ts `getProvider`/`getModel` -> pi-ai models.ts, where
+	// `getModels(provider)` returns [] for an unknown id), so a resolved model
+	// always has a provider under its own key and this branch is unreachable by
+	// construction. Keying on the returned field instead would make that
+	// guarantee depend on every provider's `getModels()` echoing its own id,
+	// which a native or OAuth-modified extension provider is free not to do.
+	const provider = deps.registry.getProvider?.(parsed.provider);
+	if (deps.registry.getProvider !== undefined && provider === undefined) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.MODEL_NOT_FOUND,
+			`The model registry resolved ${JSON.stringify(request.selection)} for ${request.routingKey} but owns no provider for ${JSON.stringify(parsed.provider)}; reassign ${request.routingKey} to a model whose provider the interactive pi can actually dispatch.`,
+			{ provider: parsed.provider, api: model.api },
+		);
+	}
+
 	const auth = await deps.registry.getApiKeyAndHeaders(model);
 	// Negation narrowing (`!auth.ok`) does not eliminate the `ok: true` arm of
 	// this discriminated union under this project's `strict: false` tsconfig;
@@ -245,9 +290,12 @@ export async function runInProcessReviewer(request: InProcessReviewerRequest, de
 		return undefined;
 	};
 
+	// `SimpleStreamOptions` is identical on both paths; only the return shape
+	// differs (an event stream versus a promise), hence `.result()` — which is
+	// exactly what pi-ai's own compat layer does with the same stream.
 	let assistant: AssistantMessage;
 	try {
-		assistant = await deps.complete(model, context, options);
+		assistant = provider === undefined ? await deps.complete(model, context, options) : await provider.streamSimple(model, context, options).result();
 	} catch (error) {
 		return abortRefusal() ?? refuse(INPROCESS_REVIEWER_FAILURE.PROVIDER_FAILED, `Reviewer completion failed for ${request.routingKey}: ${sanitizeErrorExcerpt(error)}`);
 	}

package/lib/native-review-cli.ts

@@ -1032,6 +1032,22 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// closed START/STATUS fields this row negotiates. riskEvidence and hint
 	// remain dark; neither is proven to reach Pi's negotiated START path.
 	"3.5.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 }),
+	// v3.6.0 repeats 3.5.0: the published provider contract bundle is
+	// byte-identical at 1.2.0, both binaries advertise capabilities/v2.6
+	// with only build-identity differences, and no review-integration schema
+	// changed between the v3.5.0 and v3.6.0 tags. riskEvidence and hint
+	// remain dark; neither is proven to reach Pi's negotiated START path.
+	"3.6.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 }),
+	// v3.6.1 repeats 3.6.0: published provider-contract archives are byte-identical
+	// (SHA-256 547b68e172cc87aa297309d61624e5fc2c24d407a494b53eeb5a2b053904352c).
+	// The published v3.6.1 binary advertises capabilities/v2.6, and the tag diff
+	// changes no review-integration schema or capability source. riskEvidence and
+	// hint remain dark because neither is proven in Pi's negotiated START path.
+	"3.6.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 }),
+	// v3.7.0 repeats 3.6.1: the published provider-contract tar remains SHA-256
+	// 547b68e172cc87aa297309d61624e5fc2c24d407a494b53eeb5a2b053904352c
+	// at contract 1.2.0. No new negotiated capability is asserted.
+	"3.7.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 }),
 });
 
 export interface NativeReviewProcessDiagnostics {

package/lib/session-change-capture.ts

@@ -7,6 +7,12 @@ import { resolveSessionWorktree, type WorktreeResolver } from "./session-worktre
 import { SessionChanges, readChangeSnapshot, sameSnapshot, textSnapshot, isSessionChangeEvidence,
 	SESSION_CHANGE_ENTRY, SESSION_CHANGE_EVENT, SESSION_CHANGE_RELAY, type SessionChangeEvidence, type ChangeSnapshot } from "./session-changes.ts";
 
+const foreignPublishers = new WeakMap<ExtensionAPI, (sessionId: string, evidence: SessionChangeEvidence) => void>();
+/** Internal authenticated handoff from a successful child tool callback, never a model message or public event. */
+export function publishForeignSessionChange(pi: ExtensionAPI, sessionId: string, evidence: SessionChangeEvidence): void {
+	foreignPublishers.get(pi)?.(sessionId, evidence);
+}
+
 interface Pending { sessionId: string; inputPath: string; path: string; root: string; relativePath: string; before: ChangeSnapshot; toolName: string; evidence?: SessionChangeEvidence }
 const normalized = (text: string) => text.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
 const unknown = (): ChangeSnapshot => ({ kind: "unavailable", reason: "Tool snapshots could not be verified; diff unavailable." });
@@ -23,6 +29,9 @@ export function installSessionChangeCapture(pi: ExtensionAPI, env: NodeJS.Proces
 		const notice = store.takeNotice();
 		pi.events.emit(SESSION_CHANGE_EVENT, { sessionId: store.sessionId, ...(notice ? { notice } : {}) });
 	};
+	foreignPublishers.set(pi, (sessionId, evidence) => {
+		if (!child && current?.sessionManager.getSessionId() === sessionId && isSessionChangeEvidence(evidence)) publish(evidence);
+	});
 	pi.on("session_start", (_event, ctx) => {
 		pending.clear(); current = ctx;
 		store = new SessionChanges(ctx.sessionManager.getSessionId(), ctx.sessionManager.getEntries());
@@ -84,5 +93,5 @@ export function installSessionChangeCapture(pi: ExtensionAPI, env: NodeJS.Proces
 			try { publish(item.evidence); } catch { /* Preserve the tool's outcome. */ }
 		}
 	});
-	pi.on("session_shutdown", () => { pending.clear(); current = undefined; store = undefined; off(); });
+	pi.on("session_shutdown", () => { pending.clear(); current = undefined; store = undefined; foreignPublishers.delete(pi); off(); });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gentle-pi",
-	"version": "3.5.1",
+	"version": "3.7.0",
 	"description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
 	"license": "MIT",
 	"type": "module",

package/runtime/gentle-shell-launcher.mjs

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

package/runtime/native-review-cli.mjs

@@ -1033,6 +1033,22 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// closed START/STATUS fields this row negotiates. riskEvidence and hint
 	// remain dark; neither is proven to reach Pi's negotiated START path.
 	"3.5.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 }),
+	// v3.6.0 repeats 3.5.0: the published provider contract bundle is
+	// byte-identical at 1.2.0, both binaries advertise capabilities/v2.6
+	// with only build-identity differences, and no review-integration schema
+	// changed between the v3.5.0 and v3.6.0 tags. riskEvidence and hint
+	// remain dark; neither is proven to reach Pi's negotiated START path.
+	"3.6.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 }),
+	// v3.6.1 repeats 3.6.0: published provider-contract archives are byte-identical
+	// (SHA-256 547b68e172cc87aa297309d61624e5fc2c24d407a494b53eeb5a2b053904352c).
+	// The published v3.6.1 binary advertises capabilities/v2.6, and the tag diff
+	// changes no review-integration schema or capability source. riskEvidence and
+	// hint remain dark because neither is proven in Pi's negotiated START path.
+	"3.6.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 }),
+	// v3.7.0 repeats 3.6.1: the published provider-contract tar remains SHA-256
+	// 547b68e172cc87aa297309d61624e5fc2c24d407a494b53eeb5a2b053904352c
+	// at contract 1.2.0. No new negotiated capability is asserted.
+	"3.7.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 }),
 });
 
 

package/scripts/gentle-ai-installer.mjs

@@ -36,7 +36,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 = "3.5.0";
+export const INSTALLER_VERSION = "3.7.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",
@@ -45,10 +45,10 @@ export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH = "github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai";
 export const GENTLE_AI_WINDOWS_SOURCE_MODULE = "github.com/gentleman-programming/gentle-ai/v3";
 export const GENTLE_AI_WINDOWS_SOURCE_TAG = `v${INSTALLER_VERSION}`;
-// `go mod download -json github.com/gentleman-programming/gentle-ai/v3@v3.5.0`
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v3@v3.7.0`
 // with GOSUMDB=sum.golang.org reports this exact module SumDB checksum, and the
-// tag resolves to commit 0b335e43, the published v3.5.0 release head.
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:3y+Nb7CtgGB3ne3bSNxkzV6j19etkOnGDXIiuv7tMp8=";
+// tag resolves to commit 6dee8f833aec9e46015759c5065a9035795d9af1, the published v3.7.0 release head.
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:MQbzHlLdPklUQn0rVE9Mz94UygHsN2OPe7xMfPn9aGw=";
 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";
@@ -67,7 +67,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 v3.5.0 digests are pinned from the published release:
+// still holds it. The v3.7.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.
@@ -109,15 +109,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 v3.5.0 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v3.7.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_3.5.0_darwin_amd64.tar.gz", "483b8363cc2b717d224ee7a15c834ed518854c31a1d79d84b6ea0551fd7905cf", "06e5ce2936f0b0579fa382b5cd59cf42c23b07404b162d9ff9a036dd107093a4", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_3.5.0_darwin_arm64.tar.gz", "d7a5c233ce23e8fc2ce917ed3e6a2e643655e6e8322fddb3c522324d4cf8ae52", "ec7757fe13f6cd5c9dffa6466d75c5cd68992eac44e684d330c838282c5e2e7e", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_3.5.0_linux_amd64.tar.gz", "3ea016622981f5e4f4a80632fb9c4673149c98f4e5cecc4b979b41bda758ba4a", "7a4202f75c8b90056f0ecd8fceaaef9efe407abc6f98bb42a3ee1e5ad69eb197", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_3.5.0_linux_arm64.tar.gz", "aca1997b3ae8439c17883cde39c3ba577ae38352ad6be1d1c4b2c6bc428c4505", "4d81f356f6e221bc5730a280bae049df8315232a2470089993200577e36e97cc", "gentle-ai"),
+	"darwin/amd64": asset("gentle-ai_3.7.0_darwin_amd64.tar.gz", "e55ff3ee06258a90e9195c0e3a593b85f6d79cc439e9e6c04b2596725120a610", "aa30a940e3b75ac218249b3f92d17afd2b972f833258e8212175a73d8e76d5bf", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_3.7.0_darwin_arm64.tar.gz", "66eb5740c4506cb2cfd1cc5207439c61cfe07678854f4ac7c83027a95a0e666a", "ca726cf3f9a523dc0112aa113beb634cda389e8b47edc5851254c32979bee89e", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_3.7.0_linux_amd64.tar.gz", "a730a61a43758f04cc9a4ac644945cc0e8652a1e33d6997a0a3d3f0044d2fff5", "002d09fd2b9628a29986a660c1f51f8a5042ff7fd54c8ab15b7b27de96c6cccc", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_3.7.0_linux_arm64.tar.gz", "a3a3d3a974f3d9b67d935fe9e306ae83c305da4ec1baed4a5319c10b044cd0eb", "e29546c51d8d65528bf565239ed3fc174da73c5fa3e861e64f20f84b16f28f26", "gentle-ai"),
 });
 
 // A pinned asset is either a signed archive or, for a prerelease pin only,