@lmzhen/dsh-evolution-commands 0.3.76 → 0.3.78

package/README.md

@@ -29,5 +29,11 @@ Independent of request-prefix construction. This package does not alter the asse
 
 
 - No known durable consumer gaps at this time. Runtime contracts are covered by package and boundary tests.
+- **① variant form: the `/evolution …` command face is visible in every session**
+  (accepted, not fixed — 0.3.78). Commands are registered in scope layers, and the
+  family registers once on the host plane, so a session on a platform original
+  preset still lists the management-only subcommands even though no automatic
+  family behaviour reaches it. The difference and its reasoning are single-sourced
+  in `INSTALL.md` ("Known difference").
 
 **Runtime invariant:** No companion is published. The platform auto-assembles nothing and the family mounts no `<pkg>/invariant` cordis row, so a companion here would never execute (v37 S2.1 / I-3).

package/lib/index.js

@@ -102,6 +102,165 @@ function memoryInterpolationIssues(home) {
 	}
 	return issues;
 }
+/** G3-② (B2): the family delta container. An optionalDependency of this
+* package, so resolution may legitimately fail; every failure degrades to
+* "unknown" — the doctor never throws.
+* Platform anchor: agentPresets.read(id) — preset/agent-presets/src/index.ts:501. */
+const AGENT_PRESET_PACKAGE = "@lmzhen/dsh-evolution-agent-preset";
+/** Resolve one asset the package declares in its exports map.
+* @param asset - bases.json or agent.cordis.yml.
+* @returns the file path, or null when the package is not installed. */
+function resolveAgentPresetAsset(asset) {
+	try {
+		return fileURLToPath(import.meta.resolve(`${AGENT_PRESET_PACKAGE}/${asset}`));
+	} catch {
+		return null;
+	}
+}
+/** The base rows of bases.json: the comparison iterates the same table the
+* installer reads, so doctor cannot check a different set of variants.
+* @param path - resolved bases.json.
+* @returns the rows, or null when the table is unreadable or malformed. */
+function readAgentPresetBases$1(path) {
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		if (!Array.isArray(parsed.bases)) return null;
+		const rows = [];
+		for (const raw of parsed.bases) {
+			const entry = raw;
+			if (typeof entry.name !== "string" || typeof entry.id !== "string") return null;
+			rows.push({
+				name: entry.name,
+				id: entry.id
+			});
+		}
+		return rows.length > 0 ? rows : null;
+	} catch {
+		return null;
+	}
+}
+/** Preset directories already on disk, used to keep an installed variant
+* VISIBLE when the base table itself could not be read.
+* @param root - the .agent-presets directory.
+* @returns the directory names; empty when nothing is installed. */
+function installedPresetIds(root) {
+	const ids = [];
+	let entries;
+	try {
+		entries = readdirSync(root, { withFileTypes: true });
+	} catch {
+		return ids;
+	}
+	for (const entry of entries) if (entry.isDirectory()) ids.push(entry.name);
+	return ids;
+}
+/**
+* G3-② (B2): recompute what a fresh generation would write for every
+* installed variant and compare it byte-for-byte with the file on disk.
+*
+* The recomputation goes through composePresetComposition — the SAME rule
+* /evolution preset install and install-layered.mjs apply (collision guard +
+* row-overrides.json), so doctor cannot disagree with the installer about what
+* "fresh" means. Read-only by contract: the snapshot is never rewritten.
+* @param home - resolved DSH_HOME.
+* @param registry - the platform agent-preset registry, undefined when unmounted.
+* @returns one row per base in the family bases.json.
+*/
+async function probePresetFreshness(home, registry) {
+	const presetsRoot = join(home, ".agent-presets");
+	const basesPath = resolveAgentPresetAsset("bases.json");
+	const deltaPath = resolveAgentPresetAsset("agent.cordis.yml");
+	const bases = basesPath === null ? null : readAgentPresetBases$1(basesPath);
+	let delta = null;
+	let deltaFailure = `${AGENT_PRESET_PACKAGE}/agent.cordis.yml could not be resolved — is the family agent-preset package installed?`;
+	if (deltaPath !== null) try {
+		delta = readFileSync(deltaPath, "utf8");
+	} catch (error) {
+		deltaFailure = `${deltaPath} could not be read (${error instanceof Error ? error.message : String(error)})`;
+	}
+	if (bases === null) {
+		const tablePath = basesPath ?? `${AGENT_PRESET_PACKAGE}/bases.json`;
+		return installedPresetIds(presetsRoot).map((id) => ({
+			base: id,
+			destination: join(presetsRoot, id),
+			status: "unknown",
+			detail: `the family base table could not be read (${tablePath}) — a fresh generation cannot be recomputed`
+		}));
+	}
+	const rows = [];
+	for (const base of bases) {
+		const destination = join(presetsRoot, base.id);
+		const compositionPath = join(destination, "agent.cordis.yml");
+		if (!existsSync(compositionPath)) {
+			rows.push({
+				base: base.name,
+				destination,
+				status: "absent"
+			});
+			continue;
+		}
+		if (registry === void 0) {
+			rows.push({
+				base: base.name,
+				destination,
+				status: "unknown",
+				detail: "the platform agent-preset registry is not mounted, so the runtime composition cannot be read"
+			});
+			continue;
+		}
+		if (delta === null) {
+			rows.push({
+				base: base.name,
+				destination,
+				status: "unknown",
+				detail: deltaFailure
+			});
+			continue;
+		}
+		let platform;
+		try {
+			platform = await registry.read(base.name);
+		} catch (error) {
+			rows.push({
+				base: base.name,
+				destination,
+				status: "unknown",
+				detail: `the runtime composition for base "${base.name}" could not be read (${error instanceof Error ? error.message : String(error)})`
+			});
+			continue;
+		}
+		let fresh;
+		try {
+			fresh = composePresetComposition(platform, delta);
+		} catch (error) {
+			rows.push({
+				base: base.name,
+				destination,
+				status: "unknown",
+				detail: `a fresh generation refused to compose (${error instanceof Error ? error.message : String(error)})`
+			});
+			continue;
+		}
+		let onDisk;
+		try {
+			onDisk = readFileSync(compositionPath, "utf8");
+		} catch (error) {
+			rows.push({
+				base: base.name,
+				destination,
+				status: "unknown",
+				detail: `${compositionPath} could not be read (${error instanceof Error ? error.message : String(error)})`
+			});
+			continue;
+		}
+		rows.push({
+			base: base.name,
+			destination,
+			status: fresh === onDisk ? "fresh" : "differs"
+		});
+	}
+	return rows;
+}
 /**
 * Diagnose the deployment. `ctx` supplies service presence (a bare stub with
 * only `get` is enough); `home` defaults to the evolution root so tests can
@@ -115,6 +274,7 @@ async function diagnose(ctx, options = {}) {
 		conflicts.push(scope === "profiles-dir" ? `the home profiles directory could not be enumerated (${detail}) — bundle-based install-form and conflict checks are DEGRADED and may miss installed bundles` : `a profile manifest could not be read or parsed (${detail}) — this profile's bundle rows are UNKNOWN, so the install-form and conflict checks are DEGRADED and may miss installed bundles`);
 	});
 	const has = (name) => ctx.get(name) !== void 0;
+	const presetFreshness = await probePresetFreshness(home, ctx.get("agentPresets"));
 	const full = bundles.some((name) => tailOf(name) === "dsh-evolution-all");
 	const host = bundles.some((name) => tailOf(name) === "dsh-evolution-host");
 	const preset = bundles.some((name) => tailOf(name) === "dsh-evolution-preset");
@@ -145,6 +305,7 @@ async function diagnose(ctx, options = {}) {
 		executingCount = null;
 	}
 	const installForm = full ? "full" : preset ? "preset" : layered ? "layered" : host ? "host" : presetDirInstalled ? "preset-only" : "none";
+	const deploymentForm = installForm === "layered" ? "variant" : installForm === "full" || installForm === "preset" ? "attach" : installForm === "host" ? "host-only" : installForm === "preset-only" ? "preset-only" : "none";
 	const mountConflicts = conflicts.filter((row) => !row.includes("DEGRADED"));
 	const undecidable = mountConflicts.length !== conflicts.length;
 	const actions = [];
@@ -152,7 +313,7 @@ async function diagnose(ctx, options = {}) {
 	else if (undecidable) actions.push("The install form is UNDECIDABLE (see the DEGRADED row above): an unreadable profiles directory or profile manifest hides whatever is installed, so this report must not add or remove a bundle. Fix the reported read failure, then re-run /evolution doctor.");
 	else if (installForm === "none") actions.push("Install the default full bundle: dsh plugin --profile web add @lmzhen/dsh-evolution-all");
 	else if (installForm === "preset-only") actions.push("The Evolution preset is delivered but no profile mounts an evolution bundle — re-add @lmzhen/dsh-evolution-host for the layered layout (do NOT add all on top of the preset: that double-mounts the model rows), or remove .agent-presets/evolution if the layered layout is no longer wanted.");
-	else if (installForm === "layered") actions.push("Model tools follow the Evolution preset per session; add @lmzhen/dsh-evolution-all instead if every session should have them.");
+	else if (installForm === "layered") actions.push("Variant form (session opt-in): model tools follow the Evolution preset, and a session on a platform original preset carries no family rows; add @lmzhen/dsh-evolution-all instead if every session should have them.");
 	const env = envIssues();
 	if (env.length > 0) actions.push("Fix the DSH_EVOLUTION_* variable listed above.");
 	if (services.review && !services.curator) actions.push("Curator service is not mounted — automatic curation is off; verify the host/all bundle row set is complete.");
@@ -160,8 +321,13 @@ async function diagnose(ctx, options = {}) {
 	const memoryIssues = memoryInterpolationIssues(home);
 	if (memoryIssues.length > 0) actions.push("Rewrite the memory entries listed above (or run a build with the render-time neutralization) — they broke prompt assembly on older builds.");
 	if ((executingCount ?? 0) > 0) actions.push(`${executingCount} staged write(s) are EXECUTING (an approve crashed mid-run — or one is still in flight). Inspect with /evolution pending: if you started the approve, verify the landed write and do not reject it; only reject after verifying no write is intended.`);
+	for (const row of presetFreshness) {
+		if (row.status !== "differs") continue;
+		actions.push(`Preset variant ${row.destination} DIFFERS from a fresh generation — it is an install-time snapshot; re-run the installer (/evolution preset install) to regenerate`);
+	}
 	return {
 		installForm,
+		deploymentForm,
 		bundles,
 		conflicts,
 		envIssues: env,
@@ -169,17 +335,23 @@ async function diagnose(ctx, options = {}) {
 		services,
 		pendingCount,
 		executingCount,
+		presetFreshness,
 		actions
 	};
 }
 function renderDoctorText(report) {
 	const lines = [
-		`Evolution doctor — install form: ${report.installForm}`,
+		`Evolution doctor — install form: ${report.installForm} (deployment: ${report.deploymentForm})`,
 		`bundles (all profiles): ${report.bundles.length > 0 ? report.bundles.join(", ") : "(none)"}`,
 		`services: review=${report.services.review} (inferred from bundles, all profiles) curator=${report.services.curator} approval=${report.services.approval} skillUsage=${report.services.skillUsage} io=${report.services.io}`,
 		`pending: ${report.pendingCount === null ? "unknown" : report.pendingCount}`,
 		`executing: ${report.executingCount === null ? "unknown" : report.executingCount}`
 	];
+	for (const row of report.presetFreshness) {
+		if (row.status === "absent") continue;
+		const verdict = row.status === "fresh" ? "fresh — a fresh generation matches this file byte-for-byte" : row.status === "differs" ? "DIFFERS from a fresh generation — it is an install-time snapshot; re-run the installer (/evolution preset install) to regenerate" : `unknown — a fresh generation could not be recomputed (${row.detail ?? "reason not recorded"})`;
+		lines.push(`preset:   ${row.destination}  ${verdict}`);
+	}
 	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}`));
@@ -242,8 +414,8 @@ const COMMAND_ENTRIES = [
 		summary: "run a maintenance scan (--facts: 0-token preview)"
 	},
 	{
-		usage: "preset install [--base <name>]",
-		summary: "generate the Evolution agent preset into the user root (bases from the agent package's bases.json)"
+		usage: "preset install [--base <name>[,<name>...]]",
+		summary: "generate one Evolution agent preset per named base into the user root (bases from the agent package's bases.json)"
 	},
 	{
 		usage: "restructure <name> \"<heading>\" <to_file> [--plan <runId>]",
@@ -555,7 +727,7 @@ function apply(ctx, rawConfig = {}) {
 				if (/^maintain\b/.test(input)) return err("Unknown maintain arguments: expected bare `maintain`, `maintain --timeout <ms>` or `maintain --timeout=<ms>` (a positive integer). Got: " + input);
 				const presetInstall = /^preset install(?: --base (\S+))?$/.exec(input);
 				if (presetInstall !== null || /^preset\b/.test(input)) {
-					if (presetInstall === null) return err("Unknown preset arguments: expected `preset install` or `preset install --base <name>` (the names live in the agent package's bases.json). Got: " + 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 {
@@ -572,27 +744,43 @@ function apply(ctx, rawConfig = {}) {
 					try {
 						const source = resolveAgentPresetDir(import.meta.url);
 						const table = readAgentPresetBases(source);
-						const requested = presetInstall[1] ?? table.defaultBase;
-						const base = table.entries.find((entry) => entry.name === requested);
-						if (base === void 0) return err(`Unknown agent-preset base "${requested}" — ${join(source, "bases.json")} lists ${table.entries.map((entry) => entry.name).join(", ")}`);
-						const target = join(evolutionRoot(), ".agent-presets", base.id);
+						const requestedRaw = presetInstall[1] ?? table.defaultBase;
+						const requested = [...new Set(requestedRaw.split(",").map((part) => part.trim()).filter((part) => part !== ""))];
+						if (requested.length === 0) return err(`No agent-preset base named — ${join(source, "bases.json")} lists ${table.entries.map((entry) => entry.name).join(", ")}`);
+						const selected = [];
+						for (const name of requested) {
+							const entry = table.entries.find((candidate) => candidate.name === name);
+							if (entry === void 0) return err(`Unknown agent-preset base "${name}" — ${join(source, "bases.json")} lists ${table.entries.map((candidate) => candidate.name).join(", ")}`);
+							selected.push(entry);
+						}
+						const rawBases = JSON.parse(readFileSync(join(source, "bases.json"), "utf8"));
 						const deltaPath = join(source, "agent.cordis.yml");
-						const presetPath = join(source, base.metadata);
-						if (!existsSync(deltaPath) || !existsSync(presetPath)) return err(`Preset file missing from ${source} — is the dsh-evolution-agent-preset package installed?`);
+						if (!existsSync(deltaPath)) return err(`Preset file missing from ${source} — is the dsh-evolution-agent-preset package installed?`);
 						const registry = ctx.get("agentPresets");
 						if (!registry) return err("Agent preset registry not mounted — cannot compose the Evolution preset against the runtime standard.");
-						const composition = composePresetComposition(await registry.read(base.name), readFileSync(deltaPath, "utf8"));
-						mkdirSync(target, { recursive: true });
-						atomicWriteFiles(target, [{
-							name: "agent.cordis.yml",
-							content: composition
-						}, {
-							name: base.metadata,
-							content: readFileSync(presetPath)
-						}], void 0, (message) => {
-							ctx.logger.warn(message);
-						});
-						return ok(`Evolution agent preset installed to ${target} (runtime ${base.name} + delta). Restart the session switcher to select it.`);
+						const written = [];
+						for (const base of selected) {
+							const ability = rawBases.bases?.find((candidate) => candidate.name === base.name);
+							if (typeof ability?.unsupported === "string") return err(`Base "${base.name}" is registered as UNSUPPORTED: ${ability.unsupported}`);
+							const requiredService = ability?.requires?.service;
+							if (typeof requiredService === "string" && ctx.get(requiredService) === void 0) return err(`Base "${base.name}" requires the "${requiredService}" service, which this deployment does not provide — the generated preset would refuse to mount.`);
+							const target = join(evolutionRoot(), ".agent-presets", base.id);
+							const presetPath = join(source, base.metadata);
+							if (!existsSync(presetPath)) return err(`Preset file missing from ${source} — is the dsh-evolution-agent-preset package installed?`);
+							const composition = composePresetComposition(await registry.read(base.name), readFileSync(deltaPath, "utf8"));
+							mkdirSync(target, { recursive: true });
+							atomicWriteFiles(target, [{
+								name: "agent.cordis.yml",
+								content: composition
+							}, {
+								name: base.metadata,
+								content: readFileSync(presetPath)
+							}], void 0, (message) => {
+								ctx.logger.warn(message);
+							});
+							written.push(`${base.name} → ${target}`);
+						}
+						return ok(`Evolution agent preset installed (${written.join("; ")}). Restart the session switcher to select it.`);
 					} catch (error) {
 						return err(`Preset install failed: ${error instanceof Error ? error.message : String(error)}`);
 					}
@@ -727,8 +915,9 @@ const defaultFs = {
 	mtime: (path) => {
 		try {
 			return statSync(path).mtimeMs;
-		} catch {
-			return null;
+		} catch (error) {
+			if (error.code === "ENOENT" || error.code === "ENOTDIR") return null;
+			throw error;
 		}
 	}
 };

package/lib/types/doctor.d.ts

@@ -1,3 +1,15 @@
+/** G3-② (B2): one delivered preset variant compared against a fresh generation.
+ * "absent" is the user simply not using that base (never an action); "unknown"
+ * is a comparison that could not run, kept distinct from a verified "fresh". */
+export interface PresetFreshnessRow {
+    /** Agent-preset base name (the id the platform registry read() takes). */
+    base: string;
+    /** Install destination <home>/.agent-presets/<base.id> that was compared. */
+    destination: string;
+    status: 'fresh' | 'differs' | 'absent' | 'unknown';
+    /** Why the comparison could not run — set on unknown rows only. */
+    detail?: string;
+}
 export interface DoctorReport {
     /** OPT-23 (2026-09): `preset-only` — the delivered Evolution preset
      * artifact exists but NO profile carries an evolution bundle (e.g. the
@@ -6,6 +18,13 @@ export interface DoctorReport {
      * installing `all` — which double-mounts the preset's model rows (the
      * exact conflict this report flags). */
     installForm: 'full' | 'host' | 'preset' | 'layered' | 'preset-only' | 'none';
+    /** The PRODUCT form the install form implies (0.3.77, C axis). `variant` =
+     * session-level opt-in: the model tools live in the Evolution preset, so a
+     * session on any platform original preset carries none of the family and the
+     * cross-session consumers skip it (config `sessionScoped`). `attach` =
+     * profile-level: the model rows sit at profile root and every session carries
+     * them. The two are mutually exclusive install targets (E-33). */
+    deploymentForm: 'variant' | 'attach' | 'host-only' | 'preset-only' | 'none';
     /** Aggregated across ALL profiles under `home` (N13, v12): doctor answers
      * "is any profile carrying an evolution bundle / which install forms exist"
      * — not "what this runtime mounted". `services.review` is the runtime-side
@@ -31,6 +50,12 @@ export interface DoctorReport {
     /** v23 (AP-2): claimed-but-crashed records — the only state that needs an
      * operator action (reject) to clear; surfaced separately from pending. */
     executingCount: number | null;
+    /** G3-② (B2): how the delivered preset variants compare with what a fresh
+     * generation would write against THIS runtime platform. A variant embeds the
+     * platform composition of its install day, so a platform change or a family
+     * upgrade leaves a file describing a platform that no longer exists. Read-only:
+     * a stale snapshot is reported, never repaired. */
+    presetFreshness: PresetFreshnessRow[];
     actions: string[];
 }
 /** Profile bundle rows for evolution-family packages across all profiles.

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.3.76",
+  "version": "0.3.78",
   "publishConfig": {
     "access": "public"
   },
@@ -27,12 +27,12 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-approval": "^0.3.76",
-    "@lmzhen/dsh-evolution-core": "^0.3.76",
-    "@lmzhen/dsh-evolution-maintenance": "^0.3.76"
+    "@lmzhen/dsh-evolution-approval": "^0.3.78",
+    "@lmzhen/dsh-evolution-core": "^0.3.78",
+    "@lmzhen/dsh-evolution-maintenance": "^0.3.78"
   },
   "optionalDependencies": {
-    "@lmzhen/dsh-evolution-agent-preset": "^0.3.76"
+    "@lmzhen/dsh-evolution-agent-preset": "^0.3.78"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",