@lmzhen/dsh-evolution-commands 0.32.4 → 0.32.6

package/README.md

@@ -1,34 +1,11 @@
 # @lmzhen/dsh-evolution-commands
 
-Human commands for the evolution family: it registers the `/evolution …` command surface
-and its help text, and drives the other rows from a command. It adds no automatic
-background behaviour of its own.
+Host command surface for the `/evolution` namespace: diagnostics, pending approvals, curator operations, maintenance, skill history, parameters, merge dispatch, migration, and preset installation.
 
-## Model surface
+The canonical user command reference is [docs/commands.md](../../docs/commands.md); the package map and preset-install spelling live in [packages/README.md](../README.md). Do not maintain a second command table here.
 
-- **Model-visible:** two direct tokens, both injected as user messages in this session — the `/evolution learn` injection (the full learning guidance) and the `maintain handoff` injection (a one-line POINTER to a finished maintenance report plus a report-only protocol: read the file, report per item, change nothing until the operator approves). **Command output never reaches model history**: `/evolution maintain` and every other subcommand answer in the client only. Everything else adds no tokens.
-- **Prompt prefix / KV cache:** independent of request-prefix construction — it does not alter the assembled prompt or tool list; family rules: `packages/README.md` §"Model-visible prompt prefix and the KV cache".
-- **Mount it?** yes — the `evolution-commands` row, carried by the `evolution-host`, `evolution-all` and `evolution-preset` bundles.
+The command row ships with `all`, `host`, and `preset`. If the platform `commands` service is absent, the `/evolution` namespace is not registered.
 
-## Command reference
+Under a layered/variant installation, original-preset sessions still see the management commands even though they do not carry the family model rows. That accepted difference and the mutual-exclusion rules are single-sourced in [INSTALL.md](../INSTALL.md).
 
-The full `/evolution` subcommand table is single-sourced in the family README's **Command reference** section (`packages/README.md` in the source repository; it is named here instead of linked because a repo-relative markdown link out of this package would be dead inside the npm published tree). It is rendered from the subcommand registry (`src/registry.ts`, the same single source as the `/evolution` input-declaration hint and the bare-command help output), and `tests/registry.spec.ts` (T-WD2) pins that rendered table byte-for-byte.
-
-## Known limitations
-
-- No known durable consumer gaps at this time. Runtime contracts are covered by package and boundary tests.
-- **`/evolution maintain` runs in the BACKGROUND (0.19.0).** The command answers with a run id and the scan keeps working: read it with `/evolution maintain report [<id>]` (a run that produced nothing answers "no result" instead of an empty plan) or `/evolution maintain status [<id>]` (in flight plus the recent terminal states). Since 0.20.0 the id may be **omitted** on `report`, `cancel` and `handoff`: it then means the newest run in this home, and an unreadable `runs.json` answers "the run index is not readable" for that form rather than guessing. The run's lifetime belongs to this plugin through `evolution-core`'s run registry, **not** to the request that started it: the desktop shell ends a request at ~305 s (measured four times) while the same scan completes in 949.7 s on the web plane, and `maintainTimeoutMs` (default 600000) bounds the run itself. **Cancelling the request no longer stops the scan** — use `/evolution maintain cancel <id>`, or unmount the row. The plan is written once at settle to `<evolutionHome>/reports/maintain-<runId>.{json,md}`, under the same per-home reports window the curator's reports use.
-- **`maintain handoff` is a SOFT gate (0.20.0, accepted).** The injected protocol asks the model to report and wait for the user's reply, and "what was approved" lives only in that conversation — the family keeps no approval record of its own. Escalate to the existing `evolution-approval` channel when unattended bulk skill edits, a multi-person audit trail, or non-repudiation become requirements.
-- **`maintain handoff` reports a run whose state is not `succeeded` as "ready" when a report file exists (0.20.0, accepted).** A failed or cancelled run writes the same `.json`/`.md` pair (the failure text is the report), so the injection fires and the protocol's first line — read the file — is what tells the model what happened. Tightening it to `succeeded` only is a behavior choice, not a defect fix.
-- **The injected pointer names the `.md` digest without re-probing it (0.20.0, accepted).** `reportDigestPath` swaps the `.json` suffix; the writer emits both files in one settle, so a hand-deleted `.md` beside a live `.json` would name a missing file.
-- **The id-less forms repeat the same resolve skeleton three times (0.20.0, recorded).** `report`, `cancel` and `handoff` each run `syncRuns` → id-less `newestRun` → three-state error reporting; the wording is shared through `unreadableIndex`/`unreadableForId`, the skeleton is not. Extracting one resolver is the next batch's refactor.
-- **Cross-plane run state is eventual, and the shared index is the truth for runs this process does not own (0.19.1).** Two hosts sharing one `DSH_HOME` (the desktop app and a `dsh web` plane) read and write `evolution/runs.json` together. `begin()` resolves only after its row is in that index, so a plane reading the answer "started" finds the run; a run another plane owns is re-read at this plane's **next** read, and it stops being live in exactly two ways — its owner settled it (that terminal state is adopted) or its owner died (converged to `failed(orphan)`, with the reason spelled out). Runs this process owns keep memory as the truth. No timer and no heartbeat sits behind this: 0.19.0 skipped ids it already knew, which left an observing plane reporting `running` forever and refusing its own `maintain` until it restarted. The rule is monotonic on BOTH sides (0.19.2): the read side adopts a terminal row, and the write side never puts a row this process does not own back to `running` over the terminal state its owner wrote — so a settled run cannot be resurrected by this plane's own later write. Two hosts sharing one home must be on the SAME machine: `isProcessAlive(pid)` does not cross machines. Structurally (0.19.3) a row has **exactly one writer — the process that started it**: this process's rows live in its own map, every other row is whatever the index says (rebuilt on each read), and a settled row is **never** shown as running again — a stale writer that puts `running` back is refused on read and repaired on the next write.
-- **① variant form: the `/evolution …` command face is visible in every session** (accepted, not fixed). 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).
-
-## Notes and history
-
-- P2-22 (v11) correction: this package's direct model-visible tokens are the `/evolution learn` injection (the full learning guidance) and — since 0.20.0 — the `maintain handoff` injection (a report pointer plus the report-only protocol). Both are injected as user messages in this session; see **Model surface** above for the current count.
-- **① variant form: the `/evolution …` command face is visible in every session** (accepted, not fixed: 0.3.78).
-- The injection goes through the agent's waking primitive (`followup`, falling back to `inject` when the host lacks it), **called on the agent instance**: the platform's `Agent.followup` is a prototype method (`this.send(...)`), so a detached reference throws and queues nothing (0.3.73 fix; the same shape is pinned by rule N13b in `packages/scripts/verify-arch-guards.mjs`, which masks comments and string literals before matching and self-tests its detector at startup).
+The old `consolidate` command is retired; use `merge` for skill merging.

package/lib/index.js

@@ -1,5 +1,5 @@
 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, buildExtractPlanFromLibrary, buildLearnPrompt, canonicalWriteId, clampedNumber, classifyNamespaceMigration, classifySessionEvent, createSubagentChannel, elapsedSince, errorText, eventsFile, evolutionHome, evolutionRoot, hostSurface, isDeprecatedParamId, isPresent, isRecord, isUnknown, liveBool, newRunRegistry, newSkillLibrary, ownerDecisionText, paramSettingsId, partitionVersions, planNamespaceMigration, policyStageLimits, probeMtime, probeText, proposalFromPlan, reportsSweepLockTarget, resolveParamId, resolveRootConfig, scopedPackageName, scopedProbeReport, sweepReports, transactIo, writeProposalReport } from "@lmzhen/dsh-evolution-core";
+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, PARAM_NAMESPACES, PLATFORM_LINE, REVIEWER_PRESET_ID, absentHostServices, appendEvolutionEvent, applyNamespaceMigration, asRecord, assertSkillsRootAliasRetired, atomicWriteFiles, authorityFrom, buildExtractPlanFromLibrary, buildLearnPrompt, canonicalWriteId, clampedNumber, classifyNamespaceMigration, classifySessionEvent, createSubagentChannel, elapsedSince, errorText, eventsFile, evolutionHome, evolutionRoot, hostSurface, isDeprecatedParamId, isPresent, isRecord, isUnknown, liveBool, newRunRegistry, newSkillLibrary, ownerDecisionText, paramSettingsId, partitionVersions, planNamespaceMigration, policyStageLimits, probeMtime, probeText, proposalFromPlan, registerOwnerSettings, reportsSweepLockTarget, resolveParamId, resolveRootConfig, scopedPackageName, scopedProbeReport, sweepReports, transactIo, unwrapLive, writeProposalReport } 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";
@@ -29,9 +29,10 @@ import { processScopeViolations } from "@lmzhen/dsh-evolution-state-storage";
 */
 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-history": { command: "/evolution skill undo <name> [--to v<N>]（查看：/evolution skill history <name>）" },
 	"skill-health": { command: "/evolution skills refresh（健康行：/evolution doctor）" },
 	merge: { command: "/evolution merge status / pending / approve <id> / report" },
+	settings: { command: "/evolution policy set <id> <value>（查看：/evolution policy）" },
 	diagnostics: {
 		command: "/evolution doctor",
 		platformCli: "dsh --json /evolution doctor"
@@ -486,6 +487,150 @@ function makeDiagnosticsRoutes(getInputs) {
 	}];
 }
 //#endregion
+//#region lib/types/settings-route.js
+/**
+* Family settings data plane.
+*
+* The platform RPC only serves its own namespace allowlist, so the browser cannot
+* reach family namespaces through /api/settings.* even though the underlying
+* settings service has them registered. These exact routes reuse the SAME
+* provider (describe/mutate), so storage, schema validation, revision conflicts
+* and redaction stay platform-owned; only the transport is family-scoped.
+* @module @lmzhen/dsh-evolution-commands/settings-route
+*/
+const FAMILY_NAMESPACES = new Set(Object.keys(PARAM_NAMESPACES));
+function normaliseValue(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
+	const out = {};
+	for (const [key, field] of Object.entries(value)) {
+		const live = unwrapLive(field);
+		out[key] = live === void 0 ? field : live;
+	}
+	return out;
+}
+function snapshotOf(provider, descriptor) {
+	if (descriptor === void 0) return {
+		status: "unavailable",
+		writable: false,
+		value: void 0,
+		user: void 0,
+		base: void 0,
+		revision: void 0,
+		reason: "not-served"
+	};
+	return {
+		status: "ready",
+		writable: provider.writable,
+		value: normaliseValue(descriptor.value),
+		user: descriptor.user,
+		base: descriptor.base,
+		revision: descriptor.revision
+	};
+}
+function providerOf(getProvider) {
+	return getProvider();
+}
+/**
+* @param getProvider - resolves the live platform settings provider per request.
+* @returns exact routes for family settings describe/mutate.
+*/
+function makeSettingsRoutes(getProvider) {
+	return [{
+		path: HOST_ROUTES.settings.describe,
+		methods: ["GET"],
+		requestBody: "buffered",
+		fetch: async (request) => {
+			if (request.method !== "GET") return methodNotAllowed(["GET"]);
+			const provider = providerOf(getProvider);
+			if (provider === void 0) return json(503, {
+				ok: false,
+				error: "settings-service-unavailable"
+			});
+			try {
+				const namespaces = provider.describe({ redactSecrets: true }).filter((item) => FAMILY_NAMESPACES.has(item.ns)).map((item) => ({
+					ns: item.ns,
+					...snapshotOf(provider, item)
+				}));
+				return json(200, {
+					ok: true,
+					data: {
+						writable: provider.writable,
+						namespaces
+					}
+				});
+			} catch (error) {
+				return json(500, {
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				});
+			}
+		}
+	}, {
+		path: HOST_ROUTES.settings.mutate,
+		methods: ["POST"],
+		requestBody: "buffered",
+		fetch: async (request) => {
+			if (request.method !== "POST") return methodNotAllowed(["POST"]);
+			const provider = providerOf(getProvider);
+			if (provider === void 0) return json(503, {
+				ok: false,
+				error: "settings-service-unavailable"
+			});
+			let body;
+			try {
+				body = await request.json();
+			} catch {
+				return json(400, {
+					ok: false,
+					error: "invalid-json"
+				});
+			}
+			if (typeof body !== "object" || body === null) return json(400, {
+				ok: false,
+				error: "invalid-body"
+			});
+			const { ns, ops, expectedRevision } = body;
+			if (typeof ns !== "string" || !FAMILY_NAMESPACES.has(ns)) return json(400, {
+				ok: false,
+				error: "namespace-not-allowed"
+			});
+			if (!Array.isArray(ops) || ops.length === 0) return json(400, {
+				ok: false,
+				error: "ops-required"
+			});
+			if (expectedRevision !== void 0 && typeof expectedRevision !== "number") return json(400, {
+				ok: false,
+				error: "invalid-revision"
+			});
+			try {
+				await provider.mutate(ns, ops, expectedRevision);
+				const descriptor = provider.describe({ redactSecrets: true }).find((item) => item.ns === ns);
+				return json(200, {
+					ok: true,
+					data: {
+						writable: provider.writable,
+						namespaces: [{
+							ns,
+							...snapshotOf(provider, descriptor)
+						}]
+					}
+				});
+			} catch (error) {
+				if (error?.code === "SETTINGS_CONFLICT") return json(409, {
+					ok: false,
+					error: "settings-conflict",
+					actual: error.actual,
+					expected: error.expected
+				});
+				return json(400, {
+					ok: false,
+					error: 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.
@@ -2512,6 +2657,7 @@ async function readRunReport(io, record) {
 	}
 }
 function apply(ctx, rawConfig = {}) {
+	registerOwnerSettings(ctx, "evolution-commands", Config);
 	const config = rawConfig;
 	assertSkillsRootAliasRetired(rawConfig);
 	const skillsRootValue = resolveRootConfig(rawConfig).root;
@@ -3529,7 +3675,7 @@ function apply(ctx, rawConfig = {}) {
 	ctx.inject(["settings"], () => {
 		runMigrationOnce();
 	});
-	registerHostRoutes(ctx, () => makeDiagnosticsRoutes(() => assembleDoctorInputs(ctx, { runs: doctorRuns() })));
+	registerHostRoutes(ctx, () => [...makeDiagnosticsRoutes(() => assembleDoctorInputs(ctx, { runs: doctorRuns() })), ...makeSettingsRoutes(() => ctx.get("settings"))]);
 	(async () => {
 		const loader = ctx.root.loader;
 		try {

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

@@ -16,7 +16,7 @@ export interface CommandFallbackHint {
     readonly platformCli?: string;
 }
 /** The four Host surfaces (keyed exactly like the frozen `COMMAND_FALLBACK_SURFACES`). */
-export type CommandFallbackSurface = 'approval' | 'skill-history' | 'skill-health' | 'merge' | 'diagnostics';
+export type CommandFallbackSurface = 'approval' | 'skill-history' | 'skill-health' | 'merge' | 'diagnostics' | 'settings';
 /**
  * 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.

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

@@ -0,0 +1,27 @@
+import type { ConnectionFetchRouteLike } from '@lmzhen/dsh-evolution-core/http-routes';
+interface SettingsDescriptorLike {
+    ns: string;
+    value?: unknown;
+    user?: Record<string, unknown>;
+    base?: unknown;
+    revision?: number;
+    applies?: 'live' | 'restart';
+}
+interface SettingsProviderLike {
+    readonly writable: boolean;
+    describe(options?: {
+        redactSecrets?: boolean;
+    }): SettingsDescriptorLike[];
+    mutate(ns: string, ops: readonly {
+        op: 'set' | 'unset';
+        path: readonly string[];
+        value?: unknown;
+    }[], expectedRevision?: number): Promise<void>;
+}
+/**
+ * @param getProvider - resolves the live platform settings provider per request.
+ * @returns exact routes for family settings describe/mutate.
+ */
+export declare function makeSettingsRoutes(getProvider: () => SettingsProviderLike | undefined): ConnectionFetchRouteLike[];
+export {};
+//# sourceMappingURL=settings-route.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.32.4",
+  "version": "0.32.6",
   "publishConfig": {
     "access": "public"
   },
@@ -27,13 +27,13 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.5",
-    "@lmzhen/dsh-evolution-approval": "^0.32.4",
-    "@lmzhen/dsh-evolution-core": "^0.32.4",
-    "@lmzhen/dsh-evolution-maintenance": "^0.32.4",
-    "@lmzhen/dsh-evolution-state-storage": "^0.32.4"
+    "@lmzhen/dsh-evolution-approval": "^0.32.6",
+    "@lmzhen/dsh-evolution-core": "^0.32.6",
+    "@lmzhen/dsh-evolution-maintenance": "^0.32.6",
+    "@lmzhen/dsh-evolution-state-storage": "^0.32.6"
   },
   "optionalDependencies": {
-    "@lmzhen/dsh-evolution-agent-preset": "^0.32.4"
+    "@lmzhen/dsh-evolution-agent-preset": "^0.32.6"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5",