@lmzhen/dsh-evolution-commands 0.26.15 → 0.27.0

package/lib/index.js

@@ -1,13 +1,470 @@
 import { createRequire } from "node:module";
+import { DEFAULT_SKILL_LIMITS, DIAGNOSTICS_FACT_KEYS, DIAGNOSTICS_RUNTIME_KEYS, DIAGNOSTICS_VIEW_SCHEMA_VERSION, EVOLUTION_PRESET_IDS, MAINTAINER_PRESET_ID, MAX_TIMER_DELAY_MS, PARAM_EXPOSURE, PARAM_GROUP_LABELS, PLATFORM_LINE, REVIEWER_PRESET_ID, absentHostServices, appendEvolutionEvent, applyNamespaceMigration, asRecord, assertSkillsRootAliasRetired, atomicWriteFiles, authorityFrom, buildLearnPrompt, canonicalWriteId, clampedNumber, classifyNamespaceMigration, classifySessionEvent, createSubagentChannel, elapsedSince, errorText, eventsFile, evolutionHome, evolutionRoot, hostSurface, isDeprecatedParamId, isPresent, isRecord, isUnknown, liveBool, newRunRegistry, newSkillLibrary, paramSettingsId, partitionVersions, planNamespaceMigration, policyStageLimits, probeMtime, probeText, reportsSweepLockTarget, resolveParamId, resolveRootConfig, scopedPackageName, scopedProbeReport, sweepReports, transactIo } from "@lmzhen/dsh-evolution-core";
+import { HOST_ROUTES, json, methodNotAllowed, registerHostRoutes } from "@lmzhen/dsh-evolution-core/http-routes";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 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, asRecord, assertSkillsRootAliasRetired, atomicWriteFiles, buildLearnPrompt, canonicalWriteId, clampedNumber, classifyNamespaceMigration, composePresetEntry, elapsedSince, errorText, eventsFile, evolutionHome, evolutionRoot, isDeprecatedParamId, isPresent, isRecord, 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 { composePresetEntry, mergePresetRow, presetPatchText, presetRowBlock, presetRowBody, presetRowId, resolveBasePresetPatch } from "@lmzhen/dsh-evolution-core/composition";
 import { buildEnrichment, buildMaintainFacts, enrichmentSnapshotOptions, runMaintain, snapshotFromLibrary } from "@lmzhen/dsh-evolution-maintenance";
-import { preferProvider } from "@lmzhen/dsh-evolution-io";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+//#region lib/types/command-fallback.js
+/**
+* G6/W8: the command-face fallback for every Host data-plane surface.
+*
+* The browser panels depend on the platform's `connection` carrier (exact Fetch routes). When that
+* carrier is absent (headless host, E-325) or a panel answer is missing, the operator is owed the
+* equivalent command — the SAME use case, not a different implementation. This table is the ONE
+* home of those pairs; the INSTALL runbook and the client `fallbacks.generated.ts` are generated
+* from it (W7), and a spec pins its key set to HOST_ROUTES' four surfaces.
+*
+* Not exported from the package: this is a command-side contract, not a plugin API (W8 §2).
+* @module @lmzhen/dsh-evolution-commands/command-fallback
+*/
+/**
+* One entry per Host surface. The command column names the same service methods the routes call,
+* so the answers (and refusal sentences) match the panel.
+*/
+const COMMAND_FALLBACKS = {
+	approval: { command: "/evolution pending … /evolution approve <id> … /evolution reject <id> … /evolution release <id>" },
+	"skill-history": { command: "/evolution restore <name> [v]（查看：/evolution skills history <name>）" },
+	"skill-health": { command: "/evolution skills refresh（健康行：/evolution doctor）" },
+	diagnostics: {
+		command: "/evolution doctor",
+		platformCli: "dsh --json /evolution doctor"
+	}
+};
+//#endregion
+//#region lib/types/doctor-view.js
+const FACT_HOMES = {
+	"platform-line": "README.md（兼容线声明）",
+	"family-version": "README.md（家族版本）",
+	"install-form": "packages/INSTALL.md（安装形态与验证状态）",
+	"preset-ids": "evolution-core/README.md（preset id 冻结表）",
+	"readonly-contract": "evolution-review/README.md（只读契约）",
+	"upgrade-order": "packages/INSTALL.md（升级 runbook）",
+	"fallback-map": "packages/INSTALL.md（命令兜底表）"
+};
+const FACT_LABELS = {
+	"platform-line": "平台兼容线",
+	"family-version": "家族版本",
+	"install-form": "安装形态",
+	"preset-ids": "受限 preset id",
+	"readonly-contract": "只读契约",
+	"upgrade-order": "升级顺序",
+	"fallback-map": "命令兜底"
+};
+const RUNTIME_LABELS = {
+	"subagent-channel": "子代理通道",
+	"restricted-preset": "受限 preset",
+	"host-surface": "Host 数据面",
+	"session-fold": "会话事件 fold 单入口",
+	"platform-services": "平台服务探测",
+	runs: "运行登记",
+	"platform-pairing": "平台/家族配对",
+	"install-form-detected": "实际安装形态"
+};
+function factsOf(inputs) {
+	const values = {
+		"platform-line": inputs.platformLine.version + "（floor " + inputs.platformLine.floor + "）",
+		"family-version": inputs.familyVersion,
+		"install-form": inputs.form.id + "（" + inputs.form.confidence + "；证据：" + inputs.form.evidence.join("、") + "）",
+		"preset-ids": REVIEWER_PRESET_ID + " / " + MAINTAINER_PRESET_ID + "（家族 preset 集合：" + EVOLUTION_PRESET_IDS.join(", ") + "）",
+		"readonly-contract": REVIEWER_PRESET_ID + " 的工具集由 restrictor allow 集合决定；维护行同构（" + MAINTAINER_PRESET_ID + "）",
+		"upgrade-order": "先升平台 → 再升家族 → 最后发布（见 INSTALL runbook）",
+		"fallback-map": Object.keys(COMMAND_FALLBACKS).join("、") + "（每面的命令见 INSTALL 命令兜底表）"
+	};
+	return DIAGNOSTICS_FACT_KEYS.map((key) => ({
+		key,
+		label: FACT_LABELS[key] ?? key,
+		value: values[key] ?? "unknown",
+		home: FACT_HOMES[key] ?? "README.md"
+	})).sort((a, b) => a.key.localeCompare(b.key));
+}
+function channelRow(channels) {
+	const unavailable = [channels.review, channels.maintenance].filter((state) => state.kind === "unavailable");
+	if (unavailable.length === 0) return {
+		key: "subagent-channel",
+		label: RUNTIME_LABELS["subagent-channel"] ?? "子代理通道",
+		status: "ok",
+		detail: "reviewer/maintainer 通道均可用（spawn provider + agentPreset 能力）"
+	};
+	const reasons = unavailable.map((state) => state.code + ": " + state.reason);
+	return {
+		key: "subagent-channel",
+		label: RUNTIME_LABELS["subagent-channel"] ?? "子代理通道",
+		status: "warn",
+		detail: reasons.join("；"),
+		remedy: "显式子代理运行会标记为不可用（不会静默退回 inject）；运行 /evolution doctor 查看修复指引。"
+	};
+}
+function presetRow(presets) {
+	const entries = [presets.reviewer, presets.maintainer];
+	if (entries.every((entry) => entry === void 0)) return {
+		key: "restricted-preset",
+		label: RUNTIME_LABELS["restricted-preset"] ?? "受限 preset",
+		status: "unknown",
+		detail: "agentPresets 未挂载或未暴露 list()，无法探测受限 preset。",
+		remedy: "挂载 agentPresets（随平台 Web 组合）后运行 /evolution doctor。"
+	};
+	const broken = entries.filter((entry) => entry !== void 0 && entry.broken !== void 0);
+	const missing = entries.filter((entry) => entry === void 0 || !entry.registered);
+	if (broken.length > 0) return {
+		key: "restricted-preset",
+		label: RUNTIME_LABELS["restricted-preset"] ?? "受限 preset",
+		status: "fail",
+		detail: errorText("e-324-restricted-preset-unavailable", { a1: broken.map((entry) => entry.broken ?? "").join("；") }),
+		remedy: "重载插件行使 ensureRestrictedPreset 重新注册；运行 /evolution doctor 查看 preset id 与 allow 集合。"
+	};
+	if (missing.length > 0) return {
+		key: "restricted-preset",
+		label: RUNTIME_LABELS["restricted-preset"] ?? "受限 preset",
+		status: "warn",
+		detail: "受限 preset 尚未注册（首次显式子代理运行时创建）。",
+		remedy: "运行一次审阅/维护，或在挂载后运行 /evolution doctor。"
+	};
+	return {
+		key: "restricted-preset",
+		label: RUNTIME_LABELS["restricted-preset"] ?? "受限 preset",
+		status: "ok",
+		detail: REVIEWER_PRESET_ID + " / " + MAINTAINER_PRESET_ID + " 均已注册"
+	};
+}
+function hostRow(host, count) {
+	if (!host.mounted) {
+		const fallback = COMMAND_FALLBACKS.approval.command.split(" … ")[0] ?? "";
+		return {
+			key: "host-surface",
+			label: RUNTIME_LABELS["host-surface"] ?? "Host 数据面",
+			status: "warn",
+			detail: errorText("e-325-host-data-plane-unavailable") + "（" + (host.reason ?? "unknown") + "）",
+			remedy: "改用命令面完成同等操作：" + fallback + " 等；运行 /evolution doctor 查看已挂载服务。"
+		};
+	}
+	const remote = host.deploymentAllowsRemote === true ? "允许远程权限（平台准入策略原样报告）" : "仅本机权限（平台准入策略原样报告）";
+	const mounted = count === void 0 ? "已挂载" : "已挂载 " + String(count.mounted) + "/" + String(count.total);
+	return {
+		key: "host-surface",
+		label: RUNTIME_LABELS["host-surface"] ?? "Host 数据面",
+		status: "ok",
+		detail: mounted + "；" + remote
+	};
+}
+function pairingRow(inputs) {
+	switch (inputs.platformPairing ?? "unknown") {
+		case "in-window": return {
+			key: "platform-pairing",
+			label: RUNTIME_LABELS["platform-pairing"] ?? "平台/家族配对",
+			status: "ok",
+			detail: "宿主版本 " + String(inputs.hostVersion) + " 在兼容窗口 " + inputs.platformLine.version + " 内"
+		};
+		case "host-newer": return {
+			key: "platform-pairing",
+			label: RUNTIME_LABELS["platform-pairing"] ?? "平台/家族配对",
+			status: "warn",
+			detail: "宿主 patch 线已更新（" + String(inputs.hostVersion) + "，家族声明 " + inputs.platformLine.version + "）。",
+			remedy: "按升级 runbook 先升平台线再升家族。"
+		};
+		case "out-of-window": return {
+			key: "platform-pairing",
+			label: RUNTIME_LABELS["platform-pairing"] ?? "平台/家族配对",
+			status: "fail",
+			detail: "宿主版本 " + String(inputs.hostVersion) + " 落在兼容窗口（floor " + inputs.platformLine.floor + "）外。",
+			remedy: "先升/降平台到兼容窗口，再重载家族。"
+		};
+		case "unknown": return {
+			key: "platform-pairing",
+			label: RUNTIME_LABELS["platform-pairing"] ?? "平台/家族配对",
+			status: "unknown",
+			detail: inputs.hostVersion === void 0 ? "读不到宿主版本。" : "无法判定版本窗口。",
+			remedy: "在宿主会话里运行 /evolution doctor。"
+		};
+	}
+}
+function runtimeOf(inputs) {
+	const missing = inputs.missingServices ?? [];
+	const fold = inputs.sessionFoldClassifierPresent !== false;
+	return [
+		channelRow(inputs.channels),
+		presetRow(inputs.presets),
+		hostRow(inputs.host, inputs.hostRouteCount),
+		fold ? {
+			key: "session-fold",
+			label: RUNTIME_LABELS["session-fold"] ?? "会话事件 fold 单入口",
+			status: "ok",
+			detail: "classifySessionEvent/isIgnorableEvent 存在：model 消费，plugin-record/unknown 忽略。"
+		} : {
+			key: "session-fold",
+			label: RUNTIME_LABELS["session-fold"] ?? "会话事件 fold 单入口",
+			status: "fail",
+			detail: "分类器缺失，无法证明单一 fold 入口。",
+			remedy: "升级家族（classifySessionEvent 是 core 根导出）。"
+		},
+		missing.length === 0 ? {
+			key: "platform-services",
+			label: RUNTIME_LABELS["platform-services"] ?? "平台服务探测",
+			status: "ok",
+			detail: "探测表中的服务均已挂载"
+		} : {
+			key: "platform-services",
+			label: RUNTIME_LABELS["platform-services"] ?? "平台服务探测",
+			status: "warn",
+			detail: "缺少：" + missing.join("、"),
+			remedy: "安装行（evolution-host/evolution-all）或检查 profile 行。"
+		},
+		inputs.runs.orphaned > 0 ? {
+			key: "runs",
+			label: RUNTIME_LABELS.runs ?? "运行登记",
+			status: "warn",
+			detail: "running=" + String(inputs.runs.running) + "，orphaned=" + String(inputs.runs.orphaned),
+			remedy: "运行 /evolution runs 收敛遗留运行。"
+		} : {
+			key: "runs",
+			label: RUNTIME_LABELS.runs ?? "运行登记",
+			status: "ok",
+			detail: "running=" + String(inputs.runs.running) + "，orphaned=0"
+		},
+		pairingRow(inputs),
+		inputs.form.confidence === "declared" ? {
+			key: "install-form-detected",
+			label: RUNTIME_LABELS["install-form-detected"] ?? "实际安装形态",
+			status: "ok",
+			detail: inputs.form.id + "（声明）"
+		} : {
+			key: "install-form-detected",
+			label: RUNTIME_LABELS["install-form-detected"] ?? "实际安装形态",
+			status: "warn",
+			detail: inputs.form.id + "（推断：" + inputs.form.evidence.join("、") + "）",
+			remedy: "在 profile 里显式声明安装行，核对 INSTALL 的形态表。"
+		}
+	].sort((a, b) => a.key.localeCompare(b.key));
+}
+/**
+* Build the frozen DiagnosticsView. Pure; never throws.
+* @param inputs - everything the 7+8 rows read (assembleDoctorInputs probes the live host).
+*/
+function buildDoctorView(inputs) {
+	return {
+		schemaVersion: DIAGNOSTICS_VIEW_SCHEMA_VERSION,
+		generatedAt: inputs.now.toISOString(),
+		facts: factsOf(inputs),
+		runtime: runtimeOf(inputs)
+	};
+}
+/** A safe view for a host whose inputs could not be assembled: every row names the failure. */
+function unavailableDoctorView(now, reason) {
+	const facts = DIAGNOSTICS_FACT_KEYS.map((key) => ({
+		key,
+		label: FACT_LABELS[key] ?? key,
+		value: "unknown",
+		home: FACT_HOMES[key] ?? "README.md"
+	}));
+	const runtime = DIAGNOSTICS_RUNTIME_KEYS.map((key) => ({
+		key,
+		label: RUNTIME_LABELS[key] ?? key,
+		status: "unknown",
+		detail: "无法装配 doctor 输入：" + reason,
+		remedy: "运行 /evolution doctor 重试；若持续失败，检查宿主日志。"
+	}));
+	return {
+		schemaVersion: DIAGNOSTICS_VIEW_SCHEMA_VERSION,
+		generatedAt: now.toISOString(),
+		facts: facts.sort((a, b) => a.key.localeCompare(b.key)),
+		runtime: runtime.sort((a, b) => a.key.localeCompare(b.key))
+	};
+}
+/** The family version this build carries (nearest package.json above the running module). */
+function familyVersion() {
+	try {
+		let dir = dirname(fileURLToPath(import.meta.url));
+		for (let hops = 0; hops < 32; hops += 1) {
+			const manifest = join(dir, "package.json");
+			if (existsSync(manifest)) {
+				const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+				if (typeof parsed.version === "string") return parsed.version;
+			}
+			const parent = dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+		}
+	} catch {}
+	return "unknown";
+}
+/** The soft service probe list for the platform-services row. */
+const SERVICES_PROBED = [
+	"connection",
+	"agentPresets",
+	"subagents",
+	"commands",
+	"settings"
+];
+/** The host's own version, read from the installed platform manifest (soft: absent = unknown). */
+function hostRuntimeVersion() {
+	for (const packageName of ["@deepseek-ai/dsh-app-boot", "@deepseek-ai/dsh"]) try {
+		const manifest = createRequire(import.meta.url).resolve(packageName + "/package.json");
+		const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+		if (typeof parsed.version === "string" && parsed.version !== "") return parsed.version;
+	} catch {}
+}
+/** The family bundles the platform reports (soft probe: a host without the manager answers []). */
+async function installedFamilyBundles(ctx) {
+	const listed = await ctx.get("pluginManager")?.listBundles?.();
+	if (!Array.isArray(listed)) return [];
+	const names = [];
+	for (const entry of listed) {
+		if (typeof entry !== "object" || entry === null) continue;
+		const name = entry.name;
+		if (typeof name === "string" && name.includes("dsh-evolution-")) names.push(name);
+	}
+	return names;
+}
+/**
+* Assemble the view inputs through the live Context's soft probes.
+*
+* Every probe is optional: an absent service becomes a row value (unknown/warn), never a throw. The
+* channel probe uses W5's own `createSubagentChannel` state machinery, so the doctor reports the
+* SAME availability the review/maintenance runs would see.
+* @param ctx - the host context.
+* @param extras - call-site facts the context cannot answer (runs, host version, install form).
+*/
+async function assembleDoctorInputs(ctx, extras = {}) {
+	const get = (name) => ctx.get(name);
+	const channel = createSubagentChannel(ctx);
+	const probeChannel = async (kind) => {
+		try {
+			return await channel.prepare({
+				kind,
+				allow: ["skill"]
+			});
+		} catch (error) {
+			return {
+				kind: "unavailable",
+				code: "E-323",
+				reason: error instanceof Error ? error.message : String(error)
+			};
+		}
+	};
+	const [review, maintenance] = await Promise.all([probeChannel("reviewer"), probeChannel("maintainer")]);
+	const presetsService = get("agentPresets");
+	let listed = [];
+	try {
+		const value = await presetsService?.list?.();
+		if (Array.isArray(value)) listed = value;
+	} catch {
+		listed = [];
+	}
+	const presetOf = (id) => {
+		if (listed.length === 0) return void 0;
+		const entry = listed.find((candidate) => candidate.id === id);
+		if (entry === void 0) return {
+			id,
+			registered: false
+		};
+		return {
+			id,
+			registered: true,
+			...typeof entry.broken === "string" ? { broken: entry.broken } : {}
+		};
+	};
+	const bundles = await installedFamilyBundles(ctx);
+	const hasAll = bundles.some((name) => name.endsWith("dsh-evolution-all"));
+	const hasPreset = bundles.some((name) => name.endsWith("dsh-evolution-preset"));
+	const hasHost = bundles.some((name) => name.endsWith("dsh-evolution-host"));
+	const hasFamilyPreset = listed.some((entry) => typeof entry.id === "string" && EVOLUTION_PRESET_IDS.includes(entry.id));
+	const detectedForm = hasAll || hasPreset ? {
+		id: "M1",
+		evidence: [hasAll ? "bundle dsh-evolution-all installed" : "bundle dsh-evolution-preset installed"],
+		confidence: "declared"
+	} : hasHost ? hasFamilyPreset ? {
+		id: "M4",
+		evidence: ["bundle dsh-evolution-host installed", "family agent preset registered"],
+		confidence: "declared"
+	} : {
+		id: "M3",
+		evidence: ["bundle dsh-evolution-host installed"],
+		confidence: "declared"
+	} : {
+		id: "M3",
+		evidence: ["no family bundle was reported by the platform manager"],
+		confidence: "inferred"
+	};
+	const platformVersion = hostRuntimeVersion();
+	const missingServices = SERVICES_PROBED.filter((name) => get(name) === void 0);
+	const host = hostSurface(ctx);
+	const hostMounted = host.available;
+	return {
+		now: extras.now ?? /* @__PURE__ */ new Date(),
+		platformLine: {
+			version: PLATFORM_LINE.version,
+			floor: PLATFORM_LINE.floor
+		},
+		familyVersion: familyVersion(),
+		hostVersion: extras.hostVersion ?? platformVersion,
+		form: extras.form ?? detectedForm,
+		probes: {
+			agentPresets: get("agentPresets") !== void 0,
+			connection: get("connection") !== void 0
+		},
+		channels: {
+			review,
+			maintenance
+		},
+		presets: {
+			reviewer: presetOf(REVIEWER_PRESET_ID),
+			maintainer: presetOf(MAINTAINER_PRESET_ID)
+		},
+		host: {
+			mounted: hostMounted,
+			...hostMounted ? {} : { reason: host.reason },
+			...host.available ? { deploymentAllowsRemote: host.allowsRemoteAuthorities } : {}
+		},
+		runs: extras.runs ?? {
+			running: 0,
+			orphaned: 0
+		},
+		missingServices,
+		sessionFoldClassifierPresent: typeof classifySessionEvent === "function",
+		platformPairing: extras.platformPairing ?? (platformVersion === void 0 ? "unknown" : platformVersion === PLATFORM_LINE.version ? "in-window" : "host-newer")
+	};
+}
+//#endregion
+//#region lib/types/diagnostics-route.js
+/**
+* G6/W8: the diagnostics Host route — the browser face of the SAME DiagnosticsView the CLI prints.
+*
+* Registration belongs to W6 (`registerHostRoutes` is called by the commands plugin's apply), so
+* this module only supplies the handler. A failed input assembly is NOT a transport error: the
+* handler answers an all-unknown view naming the failure, because doctor must never throw (W8 §6).
+* @module @lmzhen/dsh-evolution-commands/diagnostics-route
+*/
+/**
+* Build the diagnostics route over one input producer.
+* @param getInputs - assembles the live view inputs (soft probes; may reject).
+* @returns the exact Fetch route for `HOST_ROUTES.diagnostics.view`.
+*/
+function makeDiagnosticsRoutes(getInputs) {
+	return [{
+		path: HOST_ROUTES.diagnostics.view,
+		methods: ["GET"],
+		requestBody: "buffered",
+		fetch: async (request) => {
+			if (request.method !== "GET") return methodNotAllowed(["GET"]);
+			try {
+				return json(200, {
+					ok: true,
+					data: buildDoctorView(await getInputs())
+				});
+			} catch (error) {
+				return json(200, {
+					ok: true,
+					data: unavailableDoctorView(/* @__PURE__ */ new Date(), error instanceof Error ? error.message : String(error))
+				});
+			}
+		}
+	}];
+}
+//#endregion
 //#region lib/types/migration.js
 /**
 * G3 (caller half): find the legacy settings document and run the namespace migration.
@@ -53,15 +510,18 @@ async function runNamespaceMigration(run) {
 		await settings.update(rowId, patch);
 	};
 	if (settings.describe === void 0 || settings.update === void 0) return NOTHING;
+	let seen;
 	for (const source of legacySettingsPaths(run.home)) {
 		const text = await run.io.readText(source);
 		if (text === null) continue;
 		const plan = planNamespaceMigration(text);
-		if (plan.entries.length === 0) return {
-			source,
-			plan,
-			report: void 0
-		};
+		if (plan.entries.length === 0) {
+			seen ??= {
+				source,
+				plan
+			};
+			continue;
+		}
 		return {
 			source,
 			plan,
@@ -72,7 +532,11 @@ async function runNamespaceMigration(run) {
 			})
 		};
 	}
-	return NOTHING;
+	return seen === void 0 ? NOTHING : {
+		source: seen.source,
+		plan: seen.plan,
+		report: void 0
+	};
 }
 /**
 * Read the legacy document and report what is still unmigrated.
@@ -86,11 +550,24 @@ async function runNamespaceMigration(run) {
 async function readLegacyDocumentState(run) {
 	const settings = run.settings;
 	if (settings?.describe === void 0) return void 0;
+	let seen;
 	for (const source of legacySettingsPaths(run.home)) {
 		const text = await run.io.readText(source);
 		if (text === null) continue;
 		const plan = planNamespaceMigration(text);
-		const read = (rowId) => settings.describe?.({ redactSecrets: false }).find((entry) => entry.ns === rowId);
+		if (plan.entries.length === 0) {
+			seen ??= {
+				source,
+				plan
+			};
+			continue;
+		}
+		return stateOf(source, plan);
+	}
+	return seen === void 0 ? void 0 : stateOf(seen.source, seen.plan);
+	/** The doctor-facing state of ONE document, judged against the seat. */
+	function stateOf(source, plan) {
+		const read = (rowId) => settings?.describe?.({ redactSecrets: false }).find((entry) => entry.ns === rowId);
 		const decided = classifyNamespaceMigration(plan, read);
 		return {
 			source,
@@ -625,39 +1102,12 @@ function envIssues() {
 	if (query && !SESSION_QUERY_MODES.has(query)) issues.push(`DSH_EVOLUTION_SESSION_QUERY="${query}" is not one of startup|first-search|never — the patch normalizes it to 'startup' silently; set it to a listed mode.`);
 	return issues;
 }
-/** S0.2 (v37 P0-1): memory files that still carry the platform's `{{` prompt
-* variable syntax. The platform interpolates EVERY `systemPrompt.context` text
-* once per model step and throws on an unknown/malformed reference, so one such
-* entry used to fail every turn of every session under this home. Current
-* builds neutralize the injected text (`MemoryStore.renderContext`), which is
-* why this is a residual-risk report instead of a hard failure: an older
-* still-running process is still bricked, and an operator may prefer to clean
-* the file. Read-only; an unreadable file is skipped (the doctor never throws).
-* @param home - resolved DSH_HOME.
-* @returns one message per affected memory file.
-*/
-function memoryInterpolationIssues(home) {
-	const issues = [];
-	for (const file of ["MEMORY.md", "USER.md"]) {
-		const path = join(home, "memories", file);
-		if (!existsSync(path)) continue;
-		let raw;
-		try {
-			raw = readFileSync(path, "utf8");
-		} catch {
-			continue;
-		}
-		const hits = raw.split("{{").length - 1;
-		if (hits > 0) issues.push(`${file}: ${hits} "{{" occurrence(s) — the platform interpolates this syntax in prompt context and throws on an unknown reference, so a build without the render-time neutralization fails every later turn; rewrite the affected entries`);
-	}
-	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: `packages/boot/app-boot/src/profile.ts` — a family preset is a ROW in the
 * profile's own patch layer there (`PROFILE_PATCH_FILENAME`), never a preset directory. */
-const AGENT_PRESET_PACKAGE = "@lmzhen/dsh-evolution-agent-preset";
+const AGENT_PRESET_PACKAGE = scopedPackageName("dsh-evolution-agent-preset", import.meta.url);
 /** 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. */
@@ -995,20 +1445,19 @@ async function diagnose(ctx, options = {}) {
 	if (presetIssueRows.length > 0) actions.push("Resolve the agent-preset finding above: a broken preset composes no session, and a row two presets declare is resolved by layer order (keep the declaration in one preset).");
 	const legacy = await legacyMigrationRow(ctx, home);
 	if (legacy.state === "pending") actions.push(`The legacy settings document still holds ${legacy.pending.length} family value(s) — /evolution migrate moves them onto their rows (the document itself is left alone, so nothing is lost)`);
-	const memoryIssues = memoryInterpolationIssues(home);
 	const budgetIssues = memoryBudgetIssues(ctx);
 	const paramIssues = paramDivergences(platform);
 	const queryIssues = await sessionQueryIssues(ctx);
 	if (queryIssues.length > 0) actions.push("Session search is degraded: isolate the session named above (or wait for the platform fix described in the family maintenance notes) before retrying the same query");
 	if (paramIssues.length > 0) actions.push("Review the parameter divergences above: /evolution params shows every row with its source, /evolution policy set writes a user value, and a declared-but-unreachable row needs its owning plugin row mounted in this profile.");
 	if (budgetIssues.length > 0) actions.push("Align the memory budget: leave memory-files memoryCharLimit/userCharLimit UNSET so the store follows evolution-policy, or set both surfaces to the same value (the review plans against the policy value while the store enforces its own)");
-	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 (scopedProbe.rows !== null && scopedProbe.rows.length > 0 && scopedProbe.verdict === "never-hit") actions.push("The session-scoped rows are mounted but the family-tool probe has never matched in this process — review injection and skill-usage telemetry skipped every session observed. HOST-ONLY install: the model rows (tool-memory / tool-skill-manage) sit in evolution-host devDependencies, so no session carries them; install a bundle that mounts them (see INSTALL.md). VARIANT install: only a session on the Evolution preset matches, so open one — a session on a platform original preset is the intended skip, not a fault. Either way, check that no profile overlay disables those two rows.");
 	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 a verified orphan (this build: S2-P2-22), /evolution release <id> returns it to the pending window instead.`);
 	for (const row of presetFreshness) {
 		if (row.status !== "differs") continue;
 		actions.push(`Preset row for base "${row.base}" in ${row.destination} DIFFERS from a fresh generation — it is an install-time snapshot; re-run the installer (/evolution preset install) to regenerate`);
 	}
+	const view = buildDoctorView(await assembleDoctorInputs(ctx));
 	return {
 		installForm,
 		deploymentForm,
@@ -1016,7 +1465,6 @@ async function diagnose(ctx, options = {}) {
 		foreignProfiles: homeProfiles(home).filter(({ profile, dir }) => mounted === void 0 || profile !== mounted.profile && dir !== mounted.dir).map(({ profile }) => profile),
 		conflicts,
 		envIssues: env,
-		memoryIssues,
 		budgetIssues,
 		paramIssues,
 		queryIssues,
@@ -1032,7 +1480,8 @@ async function diagnose(ctx, options = {}) {
 		presetIssues: presetIssueRows,
 		dormantBundles,
 		serviceSource: reviewRow === void 0 ? "bundles" : "platform",
-		actions
+		actions,
+		view
 	};
 }
 /**
@@ -1175,13 +1624,35 @@ function renderDoctorText(report) {
 	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}`));
 	if (report.budgetIssues.length > 0) lines.push("memory budget:", ...report.budgetIssues.map((line) => `  ! ${line}`));
 	if (report.paramIssues.length > 0) lines.push("parameters:", ...report.paramIssues.map((line) => `  ! ${line}`));
 	if (report.queryIssues.length > 0) lines.push("session search:", ...report.queryIssues.map((line) => `  ! ${line}`));
 	if (report.actions.length > 0) lines.push("next steps:", ...report.actions.map((line) => `  → ${line}`));
 	return lines.filter((line) => line !== null).join("\n");
 }
+/**
+* G6/W8 tail: render the frozen DiagnosticsView as the doctor's diagnostics section.
+*
+* This is the ONE text face of the 7+8 rows: the same object `--json` and the diagnostics route
+* answer, so the three readers cannot disagree. Legacy install/conflict sections keep their own
+* renderer until the remaining W8-S7 rewrite lands.
+* @param view - the assembled view.
+* @returns the section text (ends with a newline).
+*/
+function renderDiagnosticsText(view) {
+	const lines = [];
+	lines.push("诊断（schema v" + String(view.schemaVersion) + "，生成于 " + view.generatedAt + "）：");
+	lines.push("  事实：");
+	for (const fact of view.facts) lines.push("  - " + fact.label + "：" + fact.value + "（出处：" + fact.home + "）");
+	lines.push("  运行时：");
+	for (const row of view.runtime) {
+		const status = row.status === "ok" ? "正常" : row.status === "warn" ? "注意" : row.status === "fail" ? "异常" : "未知";
+		const detail = row.detail === void 0 ? "" : "：" + row.detail;
+		const remedy = row.remedy === void 0 ? "" : "；下一步：" + row.remedy;
+		lines.push("  - [" + status + "] " + row.label + detail + remedy);
+	}
+	return lines.join("\n") + "\n";
+}
 //#endregion
 //#region lib/types/params.js
 /**
@@ -1368,10 +1839,20 @@ function flagsOf(name) {
 	const entry = COMMAND_ENTRIES.find((candidate) => entryName(candidate) === name);
 	return entry === void 0 ? [] : entryFlags(entry);
 }
-/** C7 shape, DERIVED: the subcommand name is the first token of `usage` (variants use `|`). */
+/**
+* C7 shape, DERIVED: the entry IDENTITY key, and it is HIERARCHICAL (E-08).
+*
+* The key used to be the first token alone, and `flagsOf` finds an entry with `.find(...)` - the FIRST
+* match - so `maintain handoff` / `maintain cancel` and `skill restore` / `skill history` / `skill undo` /
+* `skill pin` all derived the SAME key as their parent and every flag lookup silently saw the parent entry
+* only (nine collisions). A bare parent (`maintain [--timeout]`) keeps its one-token key, so parent lookups
+* still resolve: the one call site that named an entry by a name the key no longer produced was the preset
+* dispatch branch, and it now asks for the entry own key (`preset install`).
+*/
 function entryName(entry) {
-	const [head = ""] = entry.usage.split(" ");
-	return head.split("|")[0] ?? "";
+	const [head = "", second = ""] = entry.usage.split(" ");
+	const name = head.split("|")[0] ?? "";
+	return /^[a-z][a-z-]*$/.test(second) && !second.startsWith("--") ? name + " " + second : name;
 }
 /** C7 shape, DERIVED: the flags a `usage` declares, in the form `--flag` (value flags keep their name). */
 function entryFlags(entry) {
@@ -1841,7 +2322,7 @@ function apply(ctx, rawConfig = {}) {
 		const ioRegistry = ioCtx.get("evolutionIo");
 		if (!ioRegistry) return;
 		const registry = newRunRegistry({
-			io: preferProvider(ioRegistry, ["fs"]),
+			io: ioRegistry.provider(),
 			home: evolutionHome(),
 			warn: (message) => {
 				ctx.logger.warn(message);
@@ -1859,6 +2340,22 @@ function apply(ctx, rawConfig = {}) {
 			runs = void 0;
 		}, "evolution-commands.run-registry");
 	});
+	/** G6/W8: the run-registry snapshot the diagnostics `runs` row reads (one owner: the registry). */
+	const doctorRuns = () => {
+		try {
+			const running = (runs?.runs() ?? []).filter((record) => record.state === "running").length;
+			const active = runs?.inFlight();
+			return {
+				running,
+				orphaned: Math.max(0, running - (active === void 0 ? 0 : 1))
+			};
+		} catch {
+			return {
+				running: 0,
+				orphaned: 0
+			};
+		}
+	};
 	ctx.inject(["commands"], (commandCtx) => {
 		const commands = commandCtx.commands;
 		const commandBody = { run: async (invocation) => {
@@ -2072,8 +2569,9 @@ function apply(ctx, rawConfig = {}) {
 				const ioRegistry = ctx.get("evolutionIo");
 				if (!ioRegistry) return err("未挂载 evolution-io 注册表：无法固定或取消固定技能。");
 				const result = await newSkillLibrary({
+					authority: authorityFrom({ origin: "foreground" }),
 					config: { root: skillsRootValue },
-					io: preferProvider(ioRegistry, ["fs"]),
+					io: ioRegistry.provider(),
 					ctx,
 					limits: {
 						...DEFAULT_SKILL_LIMITS,
@@ -2149,8 +2647,9 @@ function apply(ctx, rawConfig = {}) {
 				const ioRegistry = ctx.get("evolutionIo");
 				if (!ioRegistry) return err("未挂载 evolution-io 注册表：维护事实不可用。");
 				const library = newSkillLibrary({
+					authority: authorityFrom({ origin: "foreground" }),
 					config: { root: skillsRootValue },
-					io: preferProvider(ioRegistry, ["fs"])
+					io: ioRegistry.provider()
 				});
 				const enrichment = await buildEnrichment(ctx, library);
 				const readFailures = [];
@@ -2162,7 +2661,7 @@ function apply(ctx, rawConfig = {}) {
 					}
 				});
 				if (snapshots.length === 0 && readFailures.length > 0) return err(`维护扫描读不出 ${readFailures.length} 个已登记技能（${readFailures.slice(0, 10).join(", ")}${readFailures.length > 10 ? ", …" : ""}），且一个技能都没读到：技能库未被审计。请修好读不出的技能（或它们的目录名）后重新扫描`);
-				if (snapshots.length === 0 && skillsRootValue !== "" && !await preferProvider(ioRegistry, ["fs"]).exists(skillsRootValue)) return err(`维护扫描发现技能库为空，但配置的技能根目录不存在（${skillsRootValue}）：请把 skillsRoot 指向真实目录（字面量 \`~\` 不会被展开），然后重新扫描`);
+				if (snapshots.length === 0 && skillsRootValue !== "" && !await ioRegistry.provider().exists(skillsRootValue)) return err(`维护扫描发现技能库为空，但配置的技能根目录不存在（${skillsRootValue}）：请把 skillsRoot 指向真实目录（字面量 \`~\` 不会被展开），然后重新扫描`);
 				if (snapshots.length === 0) return ok("维护扫描：技能库为空，无需处理。");
 				const { facts } = buildMaintainFacts(snapshots, enrichment.usageObservedValue, void 0);
 				return ok(`维护事实（零 token 预览）：\n${facts}`);
@@ -2179,9 +2678,8 @@ function apply(ctx, rawConfig = {}) {
 				if (!synced.ok) ctx.logger.warn(`evolution-commands: ${synced.note ?? "run index unreadable"} — the in-flight guard cannot see other processes' runs`);
 				else if (synced.note !== void 0) ctx.logger.warn(`evolution-commands: ${synced.note}`);
 				const ioRegistry = ctx.get("evolutionIo");
-				const subagents = ctx.get("subagents");
 				if (!ioRegistry) return err("未挂载 evolution-io 注册表：维护扫描不可用。");
-				if (!subagents) return err("未挂载子智能体服务：维护扫描不可用。");
+				const channel = createSubagentChannel(ctx);
 				const running = registry.inFlight();
 				if (running) {
 					const elapsed = Math.max(1, Math.round((Date.now() - running.startedAt) / 1e3));
@@ -2202,20 +2700,21 @@ function apply(ctx, rawConfig = {}) {
 				(async () => {
 					try {
 						const library = newSkillLibrary({
+							authority: authorityFrom({ origin: "foreground" }),
 							config: { root: skillsRootValue },
-							io: preferProvider(ioRegistry, ["fs"])
+							io: ioRegistry.provider()
 						});
 						const enrichment = await buildEnrichment(ctx, library);
 						const outcome = await runMaintain({
 							library,
-							subagents,
+							channel,
 							parent: invocation.agent,
 							evolutionPolicy: { get: () => ctx.get("evolutionPolicy")?.get() },
 							tools: { get: (name) => ctx.get("tools")?.get(name) },
 							logger: { warn: (message) => {
 								ctx.logger.warn(message);
 							} },
-							rootExists: skillsRootValue === "" ? void 0 : () => preferProvider(ioRegistry, ["fs"]).exists(skillsRootValue),
+							rootExists: skillsRootValue === "" ? void 0 : () => ioRegistry.provider().exists(skillsRootValue),
 							skillRoot: skillsRootValue
 						}, {
 							timeoutMs: runTimeoutMs,
@@ -2224,7 +2723,7 @@ function apply(ctx, rawConfig = {}) {
 							enrichment: () => enrichment
 						});
 						const endedAt = Date.now();
-						const resultRef = await writeMaintainReport(preferProvider(ioRegistry, ["fs"]), {
+						const resultRef = await writeMaintainReport(ioRegistry.provider(), {
 							runId: handle.id,
 							...outcome.ok ? {
 								verdict: outcome.verdict,
@@ -2241,6 +2740,15 @@ function apply(ctx, rawConfig = {}) {
 						}, (message) => {
 							ctx.logger.warn(message);
 						}, runHome);
+						if (resultRef !== void 0) {
+							if (!isPresent(await probeMtime(ioRegistry.provider(), resultRef))) {
+								await registry.settle(handle.id, {
+									state: "failed",
+									failure: "the maintain report file is missing at settle time (write/io race) — the scan result was not persisted."
+								});
+								return;
+							}
+						}
 						const state = outcome.ok ? "succeeded" : handle.signal.aborted ? "cancelled" : "failed";
 						await registry.settle(handle.id, {
 							state,
@@ -2248,7 +2756,7 @@ function apply(ctx, rawConfig = {}) {
 							...outcome.ok ? {} : { failure: handle.signal.aborted ? "cancelled: the scan was stopped before it settled" : outcome.error ?? "Maintenance scan failed." }
 						});
 						if (outcome.ok) {
-							appendEvolutionEvent(preferProvider(ioRegistry, ["fs"]), eventsFile(runRoot), {
+							appendEvolutionEvent(ioRegistry.provider(), eventsFile(runRoot), {
 								type: "maintain",
 								source: "manual",
 								runId: handle.id,
@@ -2341,7 +2849,7 @@ function apply(ctx, rawConfig = {}) {
 				if (wanted === void 0 && record.state === "running") return err(`最新一次运行 ${record.id} 仍在进行：它结束后才会出报告；用 /evolution maintain status ${record.id} 查看进度。`);
 				const ioRegistry = ctx.get("evolutionIo");
 				if (!ioRegistry) return err("未挂载 evolution-io 注册表：无法查看运行结果。");
-				const probed = await readRunReport(preferProvider(ioRegistry, ["fs"]), record);
+				const probed = await readRunReport(ioRegistry.provider(), record);
 				if (probed.kind === "missing") return err(`运行 ${record.id}（${record.state}）没有结果：没有写出报告${record.failure === void 0 ? "" : `（${record.failure}）`}。`);
 				if (probed.kind === "unknown") return err(`运行 ${record.id} 有报告但读不出来（${probed.reason}）：这「不是」没有结果。`);
 				return ok(probed.text);
@@ -2386,7 +2894,7 @@ function apply(ctx, rawConfig = {}) {
 				if (wanted === void 0 && record.state === "running") return err(`最新一次运行 ${record.id} 仍在进行：它结束后才会出报告；用 /evolution maintain status ${record.id} 查看进度。`);
 				const ioRegistry = ctx.get("evolutionIo");
 				if (!ioRegistry) return err("未挂载 evolution-io 注册表：无法交付报告。");
-				const probed = await readRunReport(preferProvider(ioRegistry, ["fs"]), record);
+				const probed = await readRunReport(ioRegistry.provider(), record);
 				if (probed.kind === "missing") return err(`运行 ${record.id}（${record.state}）没有结果：没有写出报告${record.failure === void 0 ? "" : `（${record.failure}）`}。`);
 				if (probed.kind === "unknown") return err(`运行 ${record.id} 有报告但读不出来（${probed.reason}）：这「不是」没有结果。`);
 				const missingAgent = agentMissing("handoff");
@@ -2413,7 +2921,7 @@ function apply(ctx, rawConfig = {}) {
 			}
 			if (/^maintain\b/.test(input)) return err("未知的 maintain 参数：应为 `maintain`、`maintain --timeout <ms>` / `maintain --timeout=<ms>`、`maintain status [<id>]`、`maintain report [<id>]`、`maintain handoff [<id>]` 或 `maintain cancel [<id>]`。实际收到：" + input);
 			const presetParsed = parseSubcommand(input);
-			const presetInstall = isParseFailure(presetParsed) || presetParsed.name !== "preset" ? null : presetParsed.positionals[0] === "install" && presetParsed.positionals.length === 1 && [...presetParsed.flags.keys()].every((flag) => flagsOf("preset").includes("--" + flag)) ? presetParsed : false;
+			const presetInstall = isParseFailure(presetParsed) || presetParsed.name !== "preset" ? null : presetParsed.positionals[0] === "install" && presetParsed.positionals.length === 1 && [...presetParsed.flags.keys()].every((flag) => flagsOf("preset install").includes("--" + flag)) ? presetParsed : false;
 			if (presetInstall !== null && presetInstall !== false) {
 				{
 					const mounted = presetProfileTarget(ctx);
@@ -2525,8 +3033,9 @@ function apply(ctx, rawConfig = {}) {
 					if (decision.action === "staged") return ok(`${decision.message}${planRunId ? `\n[audit] plan=${planRunId}` : ""}`);
 				}
 				const result = await newSkillLibrary({
+					authority: authorityFrom({ origin: "foreground" }),
 					config: { root: skillsRootValue },
-					io: preferProvider(ioRegistry, ["fs"]),
+					io: ioRegistry.provider(),
 					ctx,
 					threatExemptLabels: config.threatExemptLabels,
 					limits: {
@@ -2664,8 +3173,8 @@ function apply(ctx, rawConfig = {}) {
 					home: evolutionRoot(),
 					...mounted
 				});
-				if (input === "doctor --json") return ok(JSON.stringify(report, null, 2));
-				return ok(renderDoctorText(report));
+				if (input === "doctor --json") return ok(JSON.stringify(report.view, null, 2));
+				return ok(renderDoctorText(report) + "\n" + renderDiagnosticsText(report.view));
 			}
 			if (input === "" || input === "help") return ok(`自进化：记忆、技能、会话回顾、技能整理——状态、待批准写入与维护。\n${renderHelpText()}`);
 			return err(`/evolution ${input} 不是本构建能应答的子命令（已知子命令但缺参数也会落到这里）。\n${renderHint()}`);
@@ -2727,6 +3236,7 @@ function apply(ctx, rawConfig = {}) {
 	ctx.inject(["settings"], () => {
 		runMigrationOnce();
 	});
+	registerHostRoutes(ctx, () => makeDiagnosticsRoutes(() => assembleDoctorInputs(ctx, { runs: doctorRuns() })));
 	(async () => {
 		const loader = ctx.root.loader;
 		try {
@@ -2783,7 +3293,8 @@ function resolveAgentPresetDir(importMetaUrl) {
 	const overlayCandidate = join(dirname(fileURLToPath(importMetaUrl)), "..", "..", "evolution-agent");
 	if (existsSync(join(overlayCandidate, "agent.cordis.yml")) && existsSync(join(overlayCandidate, "bases.json"))) return overlayCandidate;
 	try {
-		return dirname(createRequire(importMetaUrl).resolve("@lmzhen/dsh-evolution-agent-preset/package.json"));
+		const agentPresetPackage = scopedPackageName("dsh-evolution-agent-preset", importMetaUrl);
+		return dirname(createRequire(importMetaUrl).resolve(agentPresetPackage + "/package.json"));
 	} catch {
 		return overlayCandidate;
 	}

package/lib/types/command-fallback.d.ts

@@ -0,0 +1,27 @@
+/**
+ * G6/W8: the command-face fallback for every Host data-plane surface.
+ *
+ * The browser panels depend on the platform's `connection` carrier (exact Fetch routes). When that
+ * carrier is absent (headless host, E-325) or a panel answer is missing, the operator is owed the
+ * equivalent command — the SAME use case, not a different implementation. This table is the ONE
+ * home of those pairs; the INSTALL runbook and the client `fallbacks.generated.ts` are generated
+ * from it (W7), and a spec pins its key set to HOST_ROUTES' four surfaces.
+ *
+ * Not exported from the package: this is a command-side contract, not a plugin API (W8 §2).
+ * @module @lmzhen/dsh-evolution-commands/command-fallback
+ */
+/** One surface's command-face path(s): the family command, plus the platform CLI when one exists. */
+export interface CommandFallbackHint {
+    readonly command: string;
+    readonly platformCli?: string;
+}
+/** The four Host surfaces (keyed exactly like the frozen `COMMAND_FALLBACK_SURFACES`). */
+export type CommandFallbackSurface = 'approval' | 'skill-history' | 'skill-health' | 'diagnostics';
+/**
+ * One entry per Host surface. The command column names the same service methods the routes call,
+ * so the answers (and refusal sentences) match the panel.
+ */
+export declare const COMMAND_FALLBACKS: Readonly<Record<CommandFallbackSurface, CommandFallbackHint>>;
+/** The ordered surface ids (the frozen W1 set). */
+export declare const COMMAND_FALLBACK_SURFACES: readonly CommandFallbackSurface[];
+//# sourceMappingURL=command-fallback.d.ts.map

package/lib/types/diagnostics-route.d.ts

@@ -0,0 +1,9 @@
+import type { ConnectionFetchRouteLike } from '@lmzhen/dsh-evolution-core/http-routes';
+import { type DoctorInputs } from './doctor-view.ts';
+/**
+ * Build the diagnostics route over one input producer.
+ * @param getInputs - assembles the live view inputs (soft probes; may reject).
+ * @returns the exact Fetch route for `HOST_ROUTES.diagnostics.view`.
+ */
+export declare function makeDiagnosticsRoutes(getInputs: () => Promise<DoctorInputs>): ConnectionFetchRouteLike[];
+//# sourceMappingURL=diagnostics-route.d.ts.map

package/lib/types/doctor-view.d.ts

@@ -0,0 +1,98 @@
+/**
+ * G6/W8: `buildDoctorView` — the ONE producer of DiagnosticsView.
+ *
+ * CLI `--json`, the diagnostics route (W6) and the client diagnostics card (W7) all call this
+ * function, so they cannot drift: 7 facts (declared/derived values, homes named) + 8 runtime rows
+ * (measured state, never rendered as ok when unreadable). The function is pure and NEVER throws: a
+ * missing/undecidable provider becomes an `unknown`/`warn`/`fail` row with a remedy, because a
+ * doctor that fails to answer is worse than one that names its blind spots.
+ * @module @lmzhen/dsh-evolution-commands/doctor-view
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ChannelState, type DiagnosticsView } from '@lmzhen/dsh-evolution-core';
+/** The install form the running profile was classified as (W8 §2 runtime install-form-detected). */
+export type InstallFormId = 'M1' | 'M2' | 'M3' | 'M4';
+/** One preset's probe result (reviewer/maintainer). */
+export interface PresetFacts {
+    readonly registered: boolean;
+    readonly broken?: string | undefined;
+    readonly id?: string | undefined;
+}
+/** The platform/connection pairing verdict. */
+export type PlatformPairing = 'in-window' | 'host-newer' | 'out-of-window' | 'unknown';
+/**
+ * Every input the view reads. Callers assemble it (assembleDoctorInputs does the soft probing);
+ * tests drive each branch directly.
+ */
+export interface DoctorInputs {
+    readonly now: Date;
+    readonly platformLine: {
+        readonly version: string;
+        readonly floor: string;
+    };
+    readonly familyVersion: string;
+    readonly hostVersion?: string | undefined;
+    readonly form: {
+        readonly id: InstallFormId;
+        readonly evidence: readonly string[];
+        readonly confidence: 'declared' | 'inferred';
+    };
+    readonly probes: {
+        readonly agentPresets: boolean;
+        readonly connection: boolean;
+    };
+    readonly channels: {
+        readonly review: ChannelState;
+        readonly maintenance: ChannelState;
+    };
+    readonly presets: {
+        readonly reviewer?: PresetFacts | undefined;
+        readonly maintainer?: PresetFacts | undefined;
+    };
+    readonly host: {
+        readonly mounted: boolean;
+        readonly reason?: string | undefined;
+        readonly deploymentAllowsRemote?: boolean | undefined;
+    };
+    readonly runs: {
+        readonly running: number;
+        readonly orphaned: number;
+    };
+    readonly missingServices?: readonly string[] | undefined;
+    readonly sessionFoldClassifierPresent?: boolean | undefined;
+    readonly platformPairing?: PlatformPairing | undefined;
+    /** Human-facing total of registered host routes, when the carrier reports one (12 today). */
+    readonly hostRouteCount?: {
+        readonly mounted: number;
+        readonly total: number;
+    } | undefined;
+}
+/**
+ * Build the frozen DiagnosticsView. Pure; never throws.
+ * @param inputs - everything the 7+8 rows read (assembleDoctorInputs probes the live host).
+ */
+export declare function buildDoctorView(inputs: DoctorInputs): DiagnosticsView;
+/** A safe view for a host whose inputs could not be assembled: every row names the failure. */
+export declare function unavailableDoctorView(now: Date, reason: string): DiagnosticsView;
+/** The family version this build carries (nearest package.json above the running module). */
+export declare function familyVersion(): string;
+/**
+ * Assemble the view inputs through the live Context's soft probes.
+ *
+ * Every probe is optional: an absent service becomes a row value (unknown/warn), never a throw. The
+ * channel probe uses W5's own `createSubagentChannel` state machinery, so the doctor reports the
+ * SAME availability the review/maintenance runs would see.
+ * @param ctx - the host context.
+ * @param extras - call-site facts the context cannot answer (runs, host version, install form).
+ */
+export declare function assembleDoctorInputs(ctx: Context, extras?: {
+    readonly runs?: {
+        readonly running: number;
+        readonly orphaned: number;
+    } | undefined;
+    readonly hostVersion?: string | undefined;
+    readonly form?: DoctorInputs['form'] | undefined;
+    readonly platformPairing?: PlatformPairing | undefined;
+    readonly now?: Date | undefined;
+}): Promise<DoctorInputs>;
+//# sourceMappingURL=doctor-view.d.ts.map

package/lib/types/doctor.d.ts

@@ -1,4 +1,5 @@
 import { type PlatformServiceProbe, type ScopedProbeReport } from '@lmzhen/dsh-evolution-core';
+import type { DiagnosticsView } 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
@@ -87,12 +88,6 @@ export interface DoctorReport {
     foreignProfiles: string[];
     conflicts: string[];
     envIssues: string[];
-    /** S0.2 (v37 P0-1): memory files carrying the platform's `{{` prompt-variable
-     * syntax. Residual-risk detector — current builds neutralize the INJECTED text
-     * (`MemoryStore.renderContext`), but a still-running older build fails every
-     * pre-step of every session under this home, and an operator may want to clean
-     * the file regardless. */
-    memoryIssues: string[];
     /** S4/P-1+P-2 (platform gap, family mitigation): the session-query corpus
      * listing failed — reported verbatim, with the isolation recipe. Empty when the
      * service is absent or answering. */
@@ -146,6 +141,9 @@ export interface DoctorReport {
     /** G5: where the review row's presence came from: the live entry, or the aggregate inference. */
     serviceSource: 'platform' | 'bundles';
     actions: string[];
+    /** G6/W8 tail: the frozen DiagnosticsView (7 facts + 8 runtime rows) — the SAME object the
+     * diagnostics route and the client card render; `--json` emits it and the text renderer prints it. */
+    readonly view: DiagnosticsView;
 }
 /** Profile bundle rows for evolution-family packages across all profiles.
  *
@@ -162,4 +160,14 @@ export declare function diagnose(ctx: {
     mounted?: MountedProfile;
 }): Promise<DoctorReport>;
 export declare function renderDoctorText(report: DoctorReport): string;
+/**
+ * G6/W8 tail: render the frozen DiagnosticsView as the doctor's diagnostics section.
+ *
+ * This is the ONE text face of the 7+8 rows: the same object `--json` and the diagnostics route
+ * answer, so the three readers cannot disagree. Legacy install/conflict sections keep their own
+ * renderer until the remaining W8-S7 rewrite lands.
+ * @param view - the assembled view.
+ * @returns the section text (ends with a newline).
+ */
+export declare function renderDiagnosticsText(view: DiagnosticsView): string;
 //# sourceMappingURL=doctor.d.ts.map

package/lib/types/registry.d.ts

@@ -19,7 +19,16 @@ export interface CommandEntry {
 }
 /** The flags the TABLE declares for one subcommand (name → `--flag`), DERIVED from its usage. */
 export declare function flagsOf(name: string): string[];
-/** C7 shape, DERIVED: the subcommand name is the first token of `usage` (variants use `|`). */
+/**
+ * C7 shape, DERIVED: the entry IDENTITY key, and it is HIERARCHICAL (E-08).
+ *
+ * The key used to be the first token alone, and `flagsOf` finds an entry with `.find(...)` - the FIRST
+ * match - so `maintain handoff` / `maintain cancel` and `skill restore` / `skill history` / `skill undo` /
+ * `skill pin` all derived the SAME key as their parent and every flag lookup silently saw the parent entry
+ * only (nine collisions). A bare parent (`maintain [--timeout]`) keeps its one-token key, so parent lookups
+ * still resolve: the one call site that named an entry by a name the key no longer produced was the preset
+ * dispatch branch, and it now asks for the entry own key (`preset install`).
+ */
 export declare function entryName(entry: CommandEntry): string;
 /** C7 shape, DERIVED: the flags a `usage` declares, in the form `--flag` (value flags keep their name). */
 export declare function entryFlags(entry: CommandEntry): string[];

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.26.15",
+  "version": "0.27.0",
   "publishConfig": {
     "access": "public"
   },
@@ -26,21 +26,23 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.4",
-    "@lmzhen/dsh-evolution-approval": "^0.26.15",
-    "@lmzhen/dsh-evolution-core": "^0.26.15",
-    "@lmzhen/dsh-evolution-maintenance": "^0.26.15"
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "@lmzhen/dsh-evolution-approval": "^0.27.0",
+    "@lmzhen/dsh-evolution-core": "^0.27.0",
+    "@lmzhen/dsh-evolution-maintenance": "^0.27.0"
   },
   "optionalDependencies": {
-    "@lmzhen/dsh-evolution-agent-preset": "^0.26.15"
+    "@lmzhen/dsh-evolution-agent-preset": "^0.27.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-commands": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.2.0-rc.1",
-    "@lmzhen/dsh-evolution-io": "^0.26.15"
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-commands": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.2.1-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-commands": "^0.2.0-rc.1"
+    "@deepseek-ai/dsh-commands": "^0.2.1-rc.1"
+  },
+  "engines": {
+    "dsh": ">=0.2.1-rc.1 <0.2.2-0"
   }
 }