@lmzhen/dsh-evolution-commands 0.20.0 → 0.22.0

package/lib/index.js

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 import z from "@deepseek-ai/schemastery";
 import { effectiveSessionPolicy } from "@lmzhen/dsh-evolution-approval";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { DEFAULT_SKILL_LIMITS, MAX_TIMER_DELAY_MS, PARAM_EXPOSURE, PARAM_GROUP_LABELS, absentHostServices, appendEvolutionEvent, applyNamespaceMigration, assertSkillsRootAliasRetired, buildLearnPrompt, canonicalWriteId, clampedNumber, classifyNamespaceMigration, composePresetEntry, elapsedSince, errorText, eventsFile, evolutionHome, evolutionRoot, isDeprecatedParamId, isMissingPath, isPresent, isUnknown, mergePresetRow, newRunRegistry, newSkillLibrary, paramSettingsId, partitionVersions, planNamespaceMigration, policyStageLimits, presetPatchText, presetRowBlock, presetRowBody, presetRowId, probeText, reportsSweepLockTarget, resolveBasePresetPatch, resolveParamId, resolveRootConfig, scopedProbeReport, sweepReports, transactIo } from "@lmzhen/dsh-evolution-core";
+import { DEFAULT_SKILL_LIMITS, MAX_TIMER_DELAY_MS, PARAM_EXPOSURE, PARAM_GROUP_LABELS, absentHostServices, appendEvolutionEvent, applyNamespaceMigration, assertSkillsRootAliasRetired, buildLearnPrompt, canonicalWriteId, clampedNumber, classifyNamespaceMigration, composePresetEntry, elapsedSince, errorText, eventsFile, evolutionHome, evolutionRoot, isDeprecatedParamId, isMissingPath, isPresent, isUnknown, liveBool, mergePresetRow, newRunRegistry, newSkillLibrary, paramSettingsId, partitionVersions, planNamespaceMigration, policyStageLimits, presetPatchText, presetRowBlock, presetRowBody, presetRowId, probeText, reportsSweepLockTarget, resolveBasePresetPatch, resolveParamId, resolveRootConfig, scopedProbeReport, sweepReports, transactIo } from "@lmzhen/dsh-evolution-core";
 import { buildEnrichment, buildMaintainFacts, enrichmentSnapshotOptions, runMaintain, snapshotFromLibrary } from "@lmzhen/dsh-evolution-maintenance";
 import { copyFileSync, existsSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -235,7 +235,7 @@ async function readPlatformView(ctx) {
 */
 /** The patch file name inside a profile directory (`packages/boot/app-boot/src/profile.ts`,
 * `PROFILE_PATCH_FILENAME`). */
-const PROFILE_PATCH_FILENAME = "cordis.patch.yml";
+const PROFILE_PATCH_FILENAME$1 = "cordis.patch.yml";
 /**
 * The profile patch this process writes into, or undefined outside a profile.
 *
@@ -251,7 +251,7 @@ function presetProfileTarget(ctx) {
 	return {
 		profile: profile.name,
 		profileDir: profile.dir,
-		patchPath: typeof profile.patchPath === "string" && profile.patchPath !== "" ? profile.patchPath : join(profile.dir, PROFILE_PATCH_FILENAME),
+		patchPath: typeof profile.patchPath === "string" && profile.patchPath !== "" ? profile.patchPath : join(profile.dir, PROFILE_PATCH_FILENAME$1),
 		bundles: Array.isArray(profile.startedBundles) ? profile.startedBundles : []
 	};
 }
@@ -314,6 +314,135 @@ function moduleGraphPath(specifier) {
 	return fileURLToPath(resolve(specifier));
 }
 //#endregion
+//#region lib/types/profiles.js
+/**
+* The ONE reader of `<home>/profiles` (G3, 0.22).
+*
+* Two very different questions used to share one bare helper: diagnostics want EVERY profile under
+* the home (doctor's cross-profile summary), while the preset-install exclusion must only ever look
+* at THIS plane — a leftover profile from the other plane's home used to make the exclusion refuse a
+* legitimate install (the two-plane split made that reachable: `~/.dsh/profiles/web` sat next
+* to `profiles/desktop`). The directory is therefore read here and nowhere else:
+* `scanProfiles` is the single `readdirSync` of it, `homeProfiles` answers the diagnostic
+* question, and `installExclusionTarget` answers the write-path one — fail-closed, because an
+* unreadable home must never read as "nothing is installed".
+*
+* @module evolution-commands/src/profiles
+*/
+/** The patch file name inside a profile directory (the platform's own spelling). */
+const PROFILE_PATCH_FILENAME = "cordis.patch.yml";
+/** The ONLY directory read of `<home>/profiles` in the family.
+* `profiles/node_modules` is a platform-created directory that never carries a manifest (S2.1), dot-entries
+* are not profiles, and a directory without `package.json` is not one either.
+* @param home - the resolved DSH home.
+* @returns the scanned entries, or the enumeration error (never a silent empty list).
+*/
+function scanProfiles(home) {
+	const root = join(home, "profiles");
+	if (!existsSync(root)) return {
+		kind: "scanned",
+		profiles: []
+	};
+	let entries;
+	try {
+		entries = readdirSync(root, { withFileTypes: true });
+	} catch (error) {
+		return {
+			kind: "unreadable",
+			error
+		};
+	}
+	const profiles = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+		if (entry.name === "node_modules") continue;
+		const dir = join(root, entry.name);
+		if (!existsSync(join(dir, "package.json"))) continue;
+		profiles.push({
+			profile: entry.name,
+			dir
+		});
+	}
+	return {
+		kind: "scanned",
+		profiles
+	};
+}
+/** Every profile directory under one home, by name — the DIAGNOSTIC question (doctor's cross-profile
+* summary). An unreadable home answers the empty list here because doctor reports the failure on its
+* own DEGRADED row; a write path must ask {@link installExclusionTarget} instead.
+* @param home - the resolved DSH home.
+* @returns one entry per profile directory carrying a manifest.
+*/
+function homeProfiles(home) {
+	const scan = scanProfiles(home);
+	return scan.kind === "scanned" ? scan.profiles : [];
+}
+/** The bundle names one profile's manifest declares.
+* @param profileDir - the profile directory.
+* @param onError - called with the read/parse failure; a torn manifest is NOT "no bundles".
+* @returns the declared bundle names (empty when the manifest is absent).
+*/
+function profileBundles(profileDir, onError) {
+	try {
+		const bundles = JSON.parse(readFileSync(join(profileDir, "package.json"), "utf8")).dsh?.profile?.bundles;
+		return Array.isArray(bundles) ? bundles.filter((name) => typeof name === "string") : [];
+	} catch (error) {
+		onError?.(error);
+		return [];
+	}
+}
+/** One optional file's text, or `''` when it is absent or unreadable.
+* @param path - the file to read.
+* @returns the text.
+*/
+function readTextOrEmpty(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return "";
+	}
+}
+/** The profile's own patch text, or `''` when it has none.
+* @param profileDir - the profile directory.
+* @returns the patch text.
+*/
+function profilePatchText(profileDir) {
+	return readTextOrEmpty(join(profileDir, PROFILE_PATCH_FILENAME));
+}
+/** Where the preset-install exclusion must look: THIS plane only, or an explicit refusal.
+*
+* The write path does NOT scan the home: the mounted profile is the whole question (its started
+* bundles plus the ones its own manifest declares — either can double-mount), and a question that
+* cannot be answered still REFUSES. That is what makes a leftover profile from the other plane
+* harmless here: it is not this plane's profile, so it is never consulted.
+* @param mounted - the mounted profile, or undefined outside a profile (a bare library mount).
+* @returns the profile to judge with its bundle rows, or the reason a refusal is mandatory.
+*/
+function installExclusionTarget(mounted) {
+	if (mounted === void 0 || mounted.dir === "") return {
+		kind: "undecidable",
+		reason: "no profile is mounted in this process, so the double-mount question cannot be answered here"
+	};
+	let manifestFailure;
+	const declared = profileBundles(mounted.dir, (error) => {
+		manifestFailure = error;
+	});
+	const manifestCode = manifestFailure?.code;
+	if (manifestFailure !== void 0 && manifestCode !== "ENOENT") return {
+		kind: "undecidable",
+		reason: "the mounted profile manifest could not be read"
+	};
+	return {
+		kind: "mounted",
+		profile: {
+			profile: mounted.profile,
+			dir: mounted.dir
+		},
+		bundles: [...mounted.bundles, ...declared]
+	};
+}
+//#endregion
 //#region lib/types/doctor.js
 /**
 * `/evolution doctor` — read-only self-check (0.3.55, WB2).
@@ -380,8 +509,10 @@ function presetIssues(presets) {
 * build-time guards cannot. Three classes, each with its own move:
 *  - a user override (the effective value is no longer the deployment's),
 *  - a deprecated alias still written in a user section (writes refuse it),
-*  - a declared user-writable parameter whose owner publishes no user layer in
-*    this composition (the registry promises a face this deployment never mounts).
+*  - a declared user-writable parameter whose owner publishes no settings namespace AT ALL
+*    (a registry fact: writes answer E-315), and
+*  - a declared user-writable parameter whose owning row this runtime does not mount
+*    (the registry promises a face this composition never carries).
 * G5: the two layers and the live rows come from the platform (`configEditor.configuration()`,
 * `pluginManager.listPlugins()`); the registry side (which spellings are deprecated, which rows
 * declare an E3 parameter) stays the family's own table. A surface that is not mounted is
@@ -411,14 +542,20 @@ function paramDivergences(platform) {
 		return issues;
 	}
 	const live = liveRowTails(platform.plugins);
-	const unreachable = PARAM_EXPOSURE.filter((entry) => entry.tier === "E3").filter((entry) => {
+	const noUserLayer = [];
+	const unmounted = [];
+	for (const entry of PARAM_EXPOSURE) {
+		if (entry.tier !== "E3") continue;
 		const namespace = paramSettingsId(entry.owner);
-		return namespace === void 0 || !live.has(namespace);
-	}).map((entry) => entry.id);
-	if (unreachable.length > 0) {
-		const shown = unreachable.slice(0, 6).join(", ");
-		const more = unreachable.length > 6 ? ` (+${unreachable.length - 6} more)` : "";
-		issues.push(`declared user-writable but unreachable here: ${shown}${more} — the owning row is not mounted in this runtime`);
+		if (namespace === void 0) noUserLayer.push(entry.id);
+		else if (!live.has(namespace)) unmounted.push(entry.id);
+	}
+	for (const [ids, sentence] of [[noUserLayer, "declared user-writable but the owner publishes no settings namespace"], [unmounted, "declared user-writable but unreachable here"]]) {
+		if (ids.length === 0) continue;
+		const shown = ids.slice(0, 6).join(", ");
+		const more = ids.length > 6 ? ` (+${ids.length - 6} more)` : "";
+		const why = sentence.includes("no settings namespace") ? "those parameters have no user layer at all (writes answer E-315) — register the owner in PARAM_NAMESPACES or move its rows to E2" : "the owning row is not mounted in this runtime";
+		issues.push(`${sentence}: ${shown}${more} — ${why}`);
 	}
 	return issues;
 }
@@ -452,22 +589,16 @@ function asMapping(value) {
 * list alone, and treating it as "no bundles" is exactly the fail-open state
 * the double-mount exclusion exists to prevent. */
 function collectEvolutionBundles(home, onReadError) {
-	const profilesDir = join(home, "profiles");
-	if (!existsSync(profilesDir)) return [];
-	const bundles = [];
-	let profileEntries;
-	try {
-		profileEntries = readdirSync(profilesDir, { withFileTypes: true });
-	} catch (error) {
-		onReadError?.(error, "profiles-dir");
-		return bundles;
+	const scan = scanProfiles(home);
+	if (scan.kind === "unreadable") {
+		onReadError?.(scan.error, "profiles-dir");
+		return [];
 	}
-	for (const profile of profileEntries) {
-		if (!profile.isDirectory()) continue;
-		if (profile.name === "node_modules" || profile.name.startsWith(".")) continue;
+	const bundles = [];
+	for (const { dir } of scan.profiles) {
 		let raw;
 		try {
-			raw = readFileSync(join(profilesDir, profile.name, "package.json"), "utf8");
+			raw = readFileSync(join(dir, "package.json"), "utf8");
 		} catch (error) {
 			if (error?.code === "ENOENT") continue;
 			onReadError?.(error, "profile-manifest");
@@ -571,62 +702,6 @@ function readAgentPresetBases$1(path) {
 		return null;
 	}
 }
-/** The bundle rows one profile manifest mounts (scope-agnostic, as written) — the target a preset
-* recompute resolves its platform base patch through.
-* @param profileDir - the profile directory.
-* @returns the bundle names; empty when the manifest is missing or torn.
-*/
-function profileBundles(profileDir) {
-	try {
-		const bundles = JSON.parse(readFileSync(join(profileDir, "package.json"), "utf8")).dsh?.profile?.bundles;
-		return Array.isArray(bundles) ? bundles.filter((name) => typeof name === "string") : [];
-	} catch {
-		return [];
-	}
-}
-/** Every profile directory under one DSH_HOME, by name.
-* @param home - resolved DSH_HOME.
-* @returns `{ profile, dir }` per directory under `profiles/` that carries a manifest.
-*/
-function profileDirectories(home) {
-	const out = [];
-	const root = join(home, "profiles");
-	let entries;
-	try {
-		entries = readdirSync(root, { withFileTypes: true });
-	} catch {
-		return out;
-	}
-	for (const entry of entries) {
-		if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
-		if (entry.name === "node_modules") continue;
-		const dir = join(root, entry.name);
-		if (!existsSync(join(dir, "package.json"))) continue;
-		out.push({
-			profile: entry.name,
-			dir
-		});
-	}
-	return out;
-}
-/** One optional file's text, or `''` when it is absent or unreadable.
-* @param path - the file to read.
-* @returns the text.
-*/
-function readTextOrEmpty(path) {
-	try {
-		return readFileSync(path, "utf8");
-	} catch {
-		return "";
-	}
-}
-/** The profile patch text, or `''` when the profile has none.
-* @param profileDir - the profile directory.
-* @returns the patch text.
-*/
-function profilePatchText(profileDir) {
-	return readTextOrEmpty(join(profileDir, PROFILE_PATCH_FILENAME));
-}
 /** Every USER-layer patch text that can carry a family preset row: each profile's own patch, then
 * the home layer (`<home>/cordis.patch.yml`), which the platform composes AFTER the profile layer
 * (`readProfilePatches` in `packages/boot/app-boot/src/profile-context.ts`). A row written there
@@ -636,7 +711,7 @@ function profilePatchText(profileDir) {
 * @returns the patch texts that exist, in profile-then-home order.
 */
 function userPatchTexts(home) {
-	const texts = profileDirectories(home).map(({ dir }) => profilePatchText(dir));
+	const texts = homeProfiles(home).map(({ dir }) => profilePatchText(dir));
 	texts.push(readTextOrEmpty(join(home, PROFILE_PATCH_FILENAME)));
 	return texts.filter((text) => text !== "");
 }
@@ -710,7 +785,7 @@ function probePresetFreshness(home, servicePresent) {
 	} catch (error) {
 		deltaFailure = `${deltaPath} could not be read (${error instanceof Error ? error.message : String(error)})`;
 	}
-	const profiles = profileDirectories(home);
+	const profiles = homeProfiles(home);
 	if (bases === null) {
 		const tablePath = basesPath ?? `${AGENT_PRESET_PACKAGE}/bases.json`;
 		return profiles.flatMap(({ profile, dir }) => {
@@ -841,6 +916,7 @@ async function legacyMigrationRow(ctx, home) {
 }
 async function diagnose(ctx, options = {}) {
 	const home = options.home ?? evolutionRoot();
+	const mounted = options.mounted;
 	const conflicts = [];
 	const bundles = collectEvolutionBundles(home, (error, scope) => {
 		const detail = error instanceof Error ? error.message : String(error);
@@ -936,6 +1012,7 @@ async function diagnose(ctx, options = {}) {
 		installForm,
 		deploymentForm,
 		bundles,
+		foreignProfiles: homeProfiles(home).filter(({ profile, dir }) => mounted === void 0 || profile !== mounted.profile && dir !== mounted.dir).map(({ profile }) => profile),
 		conflicts,
 		envIssues: env,
 		memoryIssues,
@@ -1094,6 +1171,7 @@ function renderDoctorText(report) {
 		lines.push(`preset:   ${row.base} → ${row.destination}  ${verdict}`);
 	}
 	if (report.presetIssues.length > 0) lines.push("agent presets:", ...report.presetIssues.map((line) => `  ! ${line}`));
+	if (report.foreignProfiles.length > 0) lines.push("profiles-foreign: " + report.foreignProfiles.join(", ") + " — not part of this plane: /evolution preset install ignores them, while the bundles (all profiles) line above counts them");
 	if (report.conflicts.length > 0) lines.push("conflicts:", ...report.conflicts.map((line) => `  ! ${line}`));
 	if (report.envIssues.length > 0) lines.push("env:", ...report.envIssues.map((line) => `  ! ${line}`));
 	if (report.memoryIssues.length > 0) lines.push("memory:", ...report.memoryIssues.map((line) => `  ! ${line}`));
@@ -1318,6 +1396,14 @@ const COMMAND_ENTRIES = [
 		usage: "skill undo <name> [--to v<N>]",
 		summary: "把某个技能的内容回退到某一版（默认上一版；只动内容，撤销本身也记为一版）"
 	},
+	{
+		usage: "skill pin <name>",
+		summary: "钉住一个技能：免于删除、后台审查与生命周期整理（立即生效、随时可解钉；与 skill_manage 的 pin 动作同一语义，不走审批）"
+	},
+	{
+		usage: "skill unpin <name>",
+		summary: "解钉一个技能：撤销上面的冻结（立即生效、不走审批）"
+	},
 	{
 		usage: "skills health",
 		summary: "技能库结构体检"
@@ -1400,7 +1486,7 @@ const Config = z.object({
 	skillsRoot: z.string().default(""),
 	maintainCooldownMs: z.number().min(0).default(3e4),
 	maintainTimeoutMs: z.number().min(1).default(6e5),
-	maintainHandoffOnSettle: z.boolean().default(false),
+	maintainHandoffOnSettle: z.boolean().default(false).volatile(),
 	threatExemptLabels: z.array(z.string()).default([])
 });
 /** How one run reads in `maintain status` output. */
@@ -1553,6 +1639,12 @@ function apply(ctx, rawConfig = {}) {
 	const config = rawConfig;
 	assertSkillsRootAliasRetired(rawConfig);
 	const skillsRootValue = resolveRootConfig(rawConfig).root;
+	ctx.inject(["settings"], (scope) => {
+		const settings = scope.settings;
+		if (typeof settings?.configure !== "function") return;
+		const disposer = settings.configure({ auto: false }, ctx.fiber);
+		if (typeof disposer === "function") scope.effect(() => disposer, "evolution-commands: settings presentation");
+	});
 	let runs;
 	ctx.inject(["evolutionIo"], (ioCtx) => {
 		const ioRegistry = ioCtx.get("evolutionIo");
@@ -1782,6 +1874,23 @@ function apply(ctx, rawConfig = {}) {
 				};
 				return result.ok ? ok(result.message) : err(result.message);
 			}
+			if (input === "skill pin" || input.startsWith("skill pin ") || input === "skill unpin" || input.startsWith("skill unpin ")) {
+				const pinned = !input.startsWith("skill unpin");
+				const name = input.slice(pinned ? 10 : 12).trim();
+				if (!name) return err(`Usage: /evolution skill ${pinned ? "pin" : "unpin"} <name>`);
+				const ioRegistry = ctx.get("evolutionIo");
+				if (!ioRegistry) return err("Evolution IO registry not mounted — skill pinning unavailable.");
+				const result = await newSkillLibrary({
+					config: { root: skillsRootValue },
+					io: ioRegistry.provider(),
+					ctx,
+					limits: {
+						...DEFAULT_SKILL_LIMITS,
+						...policyStageLimits(ctx.get("evolutionPolicy")?.get?.())
+					}
+				}).setPinned(name, pinned);
+				return result.ok ? ok(result.message) : err(result.message);
+			}
 			if (input === "skills health") {
 				const curator = ctx.get("evolutionCurator");
 				if (!curator) return err(errorText("e-302-curator-service-not-mounted"));
@@ -1937,7 +2046,7 @@ function apply(ctx, rawConfig = {}) {
 							}).catch((error) => {
 								ctx.logger.warn(`evolution-commands: failed to record maintain event: ${String(error)}`);
 							});
-							if (config.maintainHandoffOnSettle === true && resultRef !== void 0 && runAgent !== void 0) try {
+							if (liveBool(config.maintainHandoffOnSettle) && resultRef !== void 0 && runAgent !== void 0) try {
 								if (deliverHandoff(runAgent, createUserMessage({
 									content: [{
 										type: "text",
@@ -2096,17 +2205,17 @@ function apply(ctx, rawConfig = {}) {
 			if (presetInstall !== null || /^preset\b/.test(input)) {
 				if (presetInstall === null) return err("Unknown preset arguments: expected `preset install` or `preset install --base <name>[,<name>...]` (the names live in the agent package's bases.json). Got: " + input);
 				{
-					let installedBundles;
-					try {
-						installedBundles = collectEvolutionBundles(evolutionRoot(), (error) => {
-							throw error;
-						});
-					} catch (enumerationError) {
-						return err(`Refusing to install the layered Evolution preset: the home profile directory or one of its profile manifests could not be read (${enumerationError instanceof Error ? enumerationError.message : String(enumerationError)}) — the all/preset double-mount check could not run. Resolve access to the profiles directory and retry, or install via the layered installer, which enforces the same exclusion up front.`);
-					}
+					const mounted = presetProfileTarget(ctx);
+					const exclusion = installExclusionTarget(mounted === void 0 ? void 0 : {
+						profile: mounted.profile,
+						dir: mounted.profileDir,
+						bundles: mounted.bundles
+					});
+					if (exclusion.kind === "undecidable") return err(`Refusing to install the layered Evolution preset: ${exclusion.reason} — the all/preset double-mount check could not run. Resolve access to this profile and retry, or install via the layered installer, which enforces the same exclusion up front.`);
+					const installedBundles = exclusion.bundles;
 					const allBundle = installedBundles.find((name) => name === "dsh-evolution-all" || name.endsWith("/dsh-evolution-all"));
 					const presetBundle = installedBundles.find((name) => name === "dsh-evolution-preset" || name.endsWith("/dsh-evolution-preset"));
-					if (allBundle || presetBundle) return err(`Refusing to install the layered Evolution preset: "${allBundle ?? presetBundle}" is installed in this home — its model rows (tool-memory / tool-skill-manage / tool-session-query / skill-catalog) would double-mount with the preset's and the profile fails loud at startup. Keep ONE: remove the ${allBundle ? "evolution-all bundle" : "evolution-preset bundle"} before installing the layered preset (see /evolution doctor).`);
+					if (allBundle || presetBundle) return err(`Refusing to install the layered Evolution preset: "${allBundle ?? presetBundle}" is installed in this profile — its model rows (tool-memory / tool-skill-manage / tool-session-query / skill-catalog) would double-mount with the preset's and the profile fails loud at startup. Keep ONE: remove the ${allBundle ? "evolution-all bundle" : "evolution-preset bundle"} before installing the layered preset (see /evolution doctor).`);
 				}
 				try {
 					const source = resolveAgentPresetDir(import.meta.url);
@@ -2145,7 +2254,7 @@ function apply(ctx, rawConfig = {}) {
 						merged = next;
 					}
 					if (merged !== current) atomicWriteFiles(dirname(profile.patchPath), [{
-						name: PROFILE_PATCH_FILENAME,
+						name: PROFILE_PATCH_FILENAME$1,
 						content: presetPatchText(merged)
 					}], void 0, (message) => {
 						ctx.logger.warn(message);
@@ -2314,7 +2423,16 @@ function apply(ctx, rawConfig = {}) {
 				return ok(renderNamespaceMigration(attempt.outcome));
 			}
 			if (input === "doctor" || input === "doctor --json") {
-				const report = await diagnose(ctx, { home: evolutionRoot() });
+				const mountedForDoctor = presetProfileTarget(ctx);
+				const mounted = mountedForDoctor === void 0 ? {} : { mounted: {
+					profile: mountedForDoctor.profile,
+					dir: mountedForDoctor.profileDir,
+					bundles: mountedForDoctor.bundles
+				} };
+				const report = await diagnose(ctx, {
+					home: evolutionRoot(),
+					...mounted
+				});
 				if (input === "doctor --json") return ok(JSON.stringify(report, null, 2));
 				return ok(renderDoctorText(report));
 			}

package/lib/types/doctor.d.ts

@@ -1,4 +1,5 @@
 import { type PlatformServiceProbe, type ScopedProbeReport } from '@lmzhen/dsh-evolution-core';
+import type { MountedProfile } from './profiles.ts';
 /** P2-20 (audit): the TS-side copy of the install-target tails. The script
  * side (install-layered.mjs, verify-profile-bundles.mjs) imports the list
  * from packages/scripts/lib-family-packages.mjs; guard-scripts.spec.ts pins
@@ -79,6 +80,11 @@ export interface DoctorReport {
      * counterpart (inferred from the install form, P0-1) and may disagree on a
      * multi-profile machine; the render marks the aggregation explicitly. */
     bundles: string[];
+    /** G3 (0.22): profile directories under this home that are NOT the profile this process runs in.
+     * On a one-home-two-planes machine (or after a home clone) they are leftovers from the other
+     * plane: the write-path exclusion ignores them, while {@link bundles} still counts them — this
+     * list is what makes that difference visible instead of mysterious. */
+    foreignProfiles: string[];
     conflicts: string[];
     envIssues: string[];
     /** S0.2 (v37 P0-1): memory files carrying the platform's `{{` prompt-variable
@@ -153,6 +159,7 @@ export declare function diagnose(ctx: {
     get(name: string): unknown;
 }, options?: {
     home?: string;
+    mounted?: MountedProfile;
 }): Promise<DoctorReport>;
 export declare function renderDoctorText(report: DoctorReport): string;
 //# sourceMappingURL=doctor.d.ts.map

package/lib/types/index.d.ts

@@ -2,7 +2,7 @@
  * Human commands for the evolution family: /evolution learn|pending|curator|restore|consolidate|skills refresh.
  * @module @lmzhen/dsh-evolution-commands
  */
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context, Volatile } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { ContextFormed } from '@deepseek-ai/dsh-llm';
 declare module '@deepseek-ai/dsh-llm' {
@@ -38,8 +38,13 @@ export interface Config {
     maintainTimeoutMs?: number | undefined;
     /** G2 (0.20.0): when a scan settles successfully, hand its report to the model
      * automatically (the same pointer+protocol injection `maintain handoff` performs).
-     * Default false: the injection wakes a turn, which costs a model call. */
-    maintainHandoffOnSettle?: boolean | undefined;
+     * Default false: the injection wakes a turn, which costs a model call.
+     *
+     * `.volatile()` (0.21.0, G3): the field carries a USER LAYER, so the loader hands the live
+     * reference and the switch is read at every settle — a settings write turns it on or off without
+     * a reload. A directly constructed plugin still passes a plain boolean (the schema's default is
+     * the loader's face), so the reader accepts both. */
+    maintainHandoffOnSettle?: boolean | Volatile<boolean> | undefined;
     /** Threat-scan exemption labels for WRITE-path skill mutations (P2-18).
      * Threaded into the SkillLibrary this package constructs for `restructure`
      * (its only write path); the core-side constructor option carries the same
@@ -55,14 +60,14 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     skillsRoot: z<string, string, "defined">;
     maintainCooldownMs: z<number, number, "defined">;
     maintainTimeoutMs: z<number, number, "defined">;
-    maintainHandoffOnSettle: z<boolean, boolean, "defined">;
+    maintainHandoffOnSettle: z<boolean, boolean, "volatile-defined">;
     threatExemptLabels: z<string[], string[], "defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
     root: z<string, string, "defined">;
     skillsRoot: z<string, string, "defined">;
     maintainCooldownMs: z<number, number, "defined">;
     maintainTimeoutMs: z<number, number, "defined">;
-    maintainHandoffOnSettle: z<boolean, boolean, "defined">;
+    maintainHandoffOnSettle: z<boolean, boolean, "volatile-defined">;
     threatExemptLabels: z<string[], string[], "defined">;
 }>>, "plain">;
 export declare function apply(ctx: Context, rawConfig?: Config): void;

package/lib/types/profiles.d.ts

@@ -0,0 +1,74 @@
+/** The patch file name inside a profile directory (the platform's own spelling). */
+export declare const PROFILE_PATCH_FILENAME = "cordis.patch.yml";
+/** One profile directory under a home. */
+export interface HomeProfile {
+    /** The profile's directory name (what `--profile` spells). */
+    readonly profile: string;
+    /** Its absolute (or home-relative-joined) directory. */
+    readonly dir: string;
+}
+/** The outcome of reading `<home>/profiles`: the entries, or why they could not be read. */
+export type ProfilesScan = {
+    readonly kind: 'scanned';
+    readonly profiles: readonly HomeProfile[];
+} | {
+    readonly kind: 'unreadable';
+    readonly error: unknown;
+};
+/** The ONLY directory read of `<home>/profiles` in the family.
+ * `profiles/node_modules` is a platform-created directory that never carries a manifest (S2.1), dot-entries
+ * are not profiles, and a directory without `package.json` is not one either.
+ * @param home - the resolved DSH home.
+ * @returns the scanned entries, or the enumeration error (never a silent empty list).
+ */
+export declare function scanProfiles(home: string): ProfilesScan;
+/** Every profile directory under one home, by name — the DIAGNOSTIC question (doctor's cross-profile
+ * summary). An unreadable home answers the empty list here because doctor reports the failure on its
+ * own DEGRADED row; a write path must ask {@link installExclusionTarget} instead.
+ * @param home - the resolved DSH home.
+ * @returns one entry per profile directory carrying a manifest.
+ */
+export declare function homeProfiles(home: string): readonly HomeProfile[];
+/** The bundle names one profile's manifest declares.
+ * @param profileDir - the profile directory.
+ * @param onError - called with the read/parse failure; a torn manifest is NOT "no bundles".
+ * @returns the declared bundle names (empty when the manifest is absent).
+ */
+export declare function profileBundles(profileDir: string, onError?: (error: unknown) => void): string[];
+/** One optional file's text, or `''` when it is absent or unreadable.
+ * @param path - the file to read.
+ * @returns the text.
+ */
+export declare function readTextOrEmpty(path: string): string;
+/** The profile's own patch text, or `''` when it has none.
+ * @param profileDir - the profile directory.
+ * @returns the patch text.
+ */
+export declare function profilePatchText(profileDir: string): string;
+/** The profile this PROCESS is mounted in, as the write-path exclusion must see it. */
+export interface MountedProfile {
+    /** The mounted profile's name. */
+    readonly profile: string;
+    /** Its directory. */
+    readonly dir: string;
+    /** The bundles this plane actually STARTED (the platform's `startedBundles`). */
+    readonly bundles: readonly string[];
+}
+/** Where the preset-install exclusion must look: THIS plane only, or an explicit refusal.
+ *
+ * The write path does NOT scan the home: the mounted profile is the whole question (its started
+ * bundles plus the ones its own manifest declares — either can double-mount), and a question that
+ * cannot be answered still REFUSES. That is what makes a leftover profile from the other plane
+ * harmless here: it is not this plane's profile, so it is never consulted.
+ * @param mounted - the mounted profile, or undefined outside a profile (a bare library mount).
+ * @returns the profile to judge with its bundle rows, or the reason a refusal is mandatory.
+ */
+export declare function installExclusionTarget(mounted: MountedProfile | undefined): {
+    readonly kind: 'mounted';
+    readonly profile: HomeProfile;
+    readonly bundles: readonly string[];
+} | {
+    readonly kind: 'undecidable';
+    readonly reason: string;
+};
+//# sourceMappingURL=profiles.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-commands",
   "description": "Human commands for the evolution family (/evolution pending|curator|maintain|doctor) (community build)",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "publishConfig": {
     "access": "public"
   },
@@ -27,12 +27,12 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.4",
-    "@lmzhen/dsh-evolution-approval": "^0.20.0",
-    "@lmzhen/dsh-evolution-core": "^0.20.0",
-    "@lmzhen/dsh-evolution-maintenance": "^0.20.0"
+    "@lmzhen/dsh-evolution-approval": "^0.22.0",
+    "@lmzhen/dsh-evolution-core": "^0.22.0",
+    "@lmzhen/dsh-evolution-maintenance": "^0.22.0"
   },
   "optionalDependencies": {
-    "@lmzhen/dsh-evolution-agent-preset": "^0.20.0"
+    "@lmzhen/dsh-evolution-agent-preset": "^0.22.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",