@lmzhen/dsh-evolution-commands 0.19.3 → 0.21.0

package/README.md

@@ -6,7 +6,7 @@ background behaviour of its own.
 
 ## Model surface
 
-- **Model-visible:** one direct token — the `/evolution learn` injection — the full learning guidance is injected as a user message in this session; everything else adds no tokens.
+- **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.
 
@@ -17,7 +17,11 @@ The full `/evolution` subcommand table is single-sourced in the family README's
 ## 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). 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.
+- **`/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").
 
@@ -25,6 +29,6 @@ The full `/evolution` subcommand table is single-sourced in the family README's
 
 ## Notes and history
 
-- P2-22 (v11) correction: this package's **only** direct model-visible token is the `/evolution learn` injection — the full learning guidance is injected as a user message in this session.
+- 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).

package/lib/index.js

@@ -380,8 +380,10 @@ function presetIssues(presets) {
 * build-time guards cannot. Three classes, each with its own move:
 *  - a user override (the effective value is no longer the deployment's),
 *  - a deprecated alias still written in a user section (writes refuse it),
-*  - a declared user-writable parameter whose owner publishes no user layer in
-*    this composition (the registry promises a face this deployment never mounts).
+*  - a declared user-writable parameter whose owner publishes no settings namespace AT ALL
+*    (a registry fact: writes answer E-315), and
+*  - a declared user-writable parameter whose owning row this runtime does not mount
+*    (the registry promises a face this composition never carries).
 * G5: the two layers and the live rows come from the platform (`configEditor.configuration()`,
 * `pluginManager.listPlugins()`); the registry side (which spellings are deprecated, which rows
 * declare an E3 parameter) stays the family's own table. A surface that is not mounted is
@@ -411,14 +413,20 @@ function paramDivergences(platform) {
 		return issues;
 	}
 	const live = liveRowTails(platform.plugins);
-	const unreachable = PARAM_EXPOSURE.filter((entry) => entry.tier === "E3").filter((entry) => {
+	const noUserLayer = [];
+	const unmounted = [];
+	for (const entry of PARAM_EXPOSURE) {
+		if (entry.tier !== "E3") continue;
 		const namespace = paramSettingsId(entry.owner);
-		return namespace === void 0 || !live.has(namespace);
-	}).map((entry) => entry.id);
-	if (unreachable.length > 0) {
-		const shown = unreachable.slice(0, 6).join(", ");
-		const more = unreachable.length > 6 ? ` (+${unreachable.length - 6} more)` : "";
-		issues.push(`declared user-writable but unreachable here: ${shown}${more} — the owning row is not mounted in this runtime`);
+		if (namespace === void 0) noUserLayer.push(entry.id);
+		else if (!live.has(namespace)) unmounted.push(entry.id);
+	}
+	for (const [ids, sentence] of [[noUserLayer, "declared user-writable but the owner publishes no settings namespace"], [unmounted, "declared user-writable but unreachable here"]]) {
+		if (ids.length === 0) continue;
+		const shown = ids.slice(0, 6).join(", ");
+		const more = ids.length > 6 ? ` (+${ids.length - 6} more)` : "";
+		const why = sentence.includes("no settings namespace") ? "those parameters have no user layer at all (writes answer E-315) — register the owner in PARAM_NAMESPACES or move its rows to E2" : "the owning row is not mounted in this runtime";
+		issues.push(`${sentence}: ${shown}${more} — ${why}`);
 	}
 	return issues;
 }
@@ -1318,6 +1326,14 @@ const COMMAND_ENTRIES = [
 		usage: "skill undo <name> [--to v<N>]",
 		summary: "把某个技能的内容回退到某一版（默认上一版；只动内容，撤销本身也记为一版）"
 	},
+	{
+		usage: "skill pin <name>",
+		summary: "钉住一个技能：免于删除、后台审查与生命周期整理（立即生效、随时可解钉；与 skill_manage 的 pin 动作同一语义，不走审批）"
+	},
+	{
+		usage: "skill unpin <name>",
+		summary: "解钉一个技能：撤销上面的冻结（立即生效、不走审批）"
+	},
 	{
 		usage: "skills health",
 		summary: "技能库结构体检"
@@ -1339,12 +1355,16 @@ const COMMAND_ENTRIES = [
 		summary: "看维护扫描：在飞的那次（含已跑多久）或某个 run 的终态"
 	},
 	{
-		usage: "maintain report <id>",
-		summary: "读某个 run 的结果正文（没有结果就明说，不装成空结果）"
+		usage: "maintain report [<id>]",
+		summary: "读某个 run 的结果正文（省略 id 取本 home 最新一条；没有结果就明说，不装成空结果）"
+	},
+	{
+		usage: "maintain handoff [<id>]",
+		summary: "把某次维护报告交给模型：注入指针与汇报协议，模型只汇报、等你确认后再动手"
 	},
 	{
-		usage: "maintain cancel <id>",
-		summary: "停掉在飞的那次维护扫描"
+		usage: "maintain cancel [<id>]",
+		summary: "停掉在飞的那次维护扫描（省略 id 仅当最新一条是本进程在跑的那次）"
 	},
 	{
 		usage: "migrate",
@@ -1396,6 +1416,7 @@ const Config = z.object({
 	skillsRoot: z.string().default(""),
 	maintainCooldownMs: z.number().min(0).default(3e4),
 	maintainTimeoutMs: z.number().min(1).default(6e5),
+	maintainHandoffOnSettle: z.boolean().default(false).volatile(),
 	threatExemptLabels: z.array(z.string()).default([])
 });
 /** How one run reads in `maintain status` output. */
@@ -1406,6 +1427,65 @@ function renderRunRecord(record) {
 	if (record.resultRef !== void 0) parts.push(`→ ${record.resultRef}`);
 	return parts.join(" ");
 }
+/** The newest MAINTENANCE run this home knows — the default when a subcommand omits its id
+* (G2/0.20.0). The registry view is newest-first and already carries the cross-plane rows. The
+* index is a file a user can hand-edit, so a row with a blank id is skipped rather than answered
+* from (review P2-7: it produced text like `Run  (succeeded) …`). `RunKind` has one member today,
+* so kind needs no filter — a second kind must add one here when it lands. */
+function newestRun(registry) {
+	return registry.runs().find((record) => record.id.trim() !== "");
+}
+/** Sentence F, ONE wording for the three id-less forms (design `10` cell 13): an index that could
+* not be read must never answer as "there is no recent run" (G2/0.20.0). */
+function unreadableIndex(note) {
+	return `The home's run index is not readable (${note ?? "unknown reason"}) — this is NOT "there is no recent run".`;
+}
+/** The explicit-id twin of {@link unreadableIndex}, worded like `maintain status` so the four
+* readers cannot drift (review P1-1). */
+function unreadableForId(id, note) {
+	return `Run ${id} is not in this process's history, and the home's run index is not readable (${note ?? "unknown reason"}) — that is NOT proof the run never happened.`;
+}
+/** The reader-facing report path: the `.md` digest beside the run's `.json` result. */
+function reportDigestPath(record) {
+	return (record.resultRef ?? join(evolutionHome(), "reports", `maintain-${record.id}.json`)).replace(/\.json$/, ".md");
+}
+/** Deliver one handoff message through the waking primitive, called ON the receiver
+* (family checklist new-consumer: N13b fails a wake primitive read into a local — the
+* 0.3.73 incident ate review prompts for six days). Falls back to the non-waking
+* `inject`, exactly like `/evolution learn`. @returns true when the receiver woke,
+* false when the message was only queued, `undefined` when neither primitive exists. */
+function deliverHandoff(agent, message) {
+	if (typeof agent.followup === "function") {
+		agent.followup(message);
+		return true;
+	}
+	if (typeof agent.inject === "function") {
+		agent.inject(message);
+		return false;
+	}
+}
+/** The model-facing handoff message (G2/0.20.0): a POINTER to the report plus the
+* report-only protocol. ONE builder shared by `maintain handoff` and the settle-time
+* automatic handoff, so the two cannot drift. Missing counts are omitted, never guessed. */
+function handoffPrompt(input) {
+	const counts = [
+		input.verdict === void 0 ? void 0 : `verdict=${input.verdict}`,
+		input.recommendationCount === void 0 ? void 0 : `${input.recommendationCount} recommendations`,
+		input.needsHumanCount === void 0 ? void 0 : `${input.needsHumanCount} of them need your user's confirmation`
+	].filter((part) => part !== void 0);
+	return [
+		`${`[evolution maintain] The maintenance report for run ${input.runId} is ready: ${input.reportPath}`}${counts.length === 0 ? "" : ` (${counts.join(", ")}; each item has a stable [n] id)`}.`,
+		"",
+		"This turn is REPORT-ONLY. Read the file, then tell your user what it found and what it proposes — one line",
+		"per item: [n] | what would change | which skills | why (the finding) | undo | needs-your-confirmation?",
+		"Lead with the items that need confirmation. Do NOT edit, restructure, archive or rename anything in this",
+		"turn, and start no other skill work: your user must approve which items to carry out. When they reply by [n]",
+		"ids, carry out ONLY the approved items, one at a time, and read each item's undo line before you touch",
+		"anything; if an item has no undo line, treat it as irreversible and ask first. Apply every change through",
+		"the skill-writing tool (skill_manage) — never edit SKILL.md or its support files with generic file tools:",
+		"an out-of-band edit leaves no version in skill history and no audit record."
+	].join("\n");
+}
 /**
 * Write one run's result to its ONE home: `<evolutionHome>/reports/maintain-<id>.json`
 * plus the `.md` digest, then sweep that window.
@@ -1475,7 +1555,8 @@ async function readRunReport(io, record) {
 		const parsed = JSON.parse(probed.value);
 		return {
 			kind: "present",
-			text: `${`Maintenance run ${record.id} — ${record.state}${record.failure === void 0 ? "" : ` (${record.failure})`}`}\n${typeof parsed.text === "string" && parsed.text.trim() !== "" ? parsed.text : renderRunRecord(record)}`
+			text: `${`Maintenance run ${record.id} — ${record.state}${record.failure === void 0 ? "" : ` (${record.failure})`}`}\n${typeof parsed.text === "string" && parsed.text.trim() !== "" ? parsed.text : renderRunRecord(record)}`,
+			report: parsed
 		};
 	} catch (error) {
 		return {
@@ -1484,10 +1565,29 @@ async function readRunReport(io, record) {
 		};
 	}
 }
+/**
+* Read a switch that may be a live settings reference.
+*
+* The loader hands a `.volatile()` field as `{ get() }` and the value is read at USE time; a
+* directly constructed plugin passes a plain boolean (the schema is the loader's face — the same
+* split the numeric knobs document as their second clamp layer). A single-form read is wrong
+* either way: `=== true` is never true for a reference, and `?.get()` ignores the plain value.
+* @param value - the configured switch, in either form, or undefined.
+* @returns the switch; undefined reads as off.
+*/
+function liveFlag(value) {
+	return typeof value === "boolean" ? value : value?.get() ?? false;
+}
 function apply(ctx, rawConfig = {}) {
 	const config = rawConfig;
 	assertSkillsRootAliasRetired(rawConfig);
 	const skillsRootValue = resolveRootConfig(rawConfig).root;
+	ctx.inject(["settings"], (scope) => {
+		const settings = scope.settings;
+		if (typeof settings?.configure !== "function") return;
+		const disposer = settings.configure({ auto: false }, ctx.fiber);
+		if (typeof disposer === "function") scope.effect(() => disposer, "evolution-commands: settings presentation");
+	});
 	let runs;
 	ctx.inject(["evolutionIo"], (ioCtx) => {
 		const ioRegistry = ioCtx.get("evolutionIo");
@@ -1717,6 +1817,23 @@ function apply(ctx, rawConfig = {}) {
 				};
 				return result.ok ? ok(result.message) : err(result.message);
 			}
+			if (input === "skill pin" || input.startsWith("skill pin ") || input === "skill unpin" || input.startsWith("skill unpin ")) {
+				const pinned = !input.startsWith("skill unpin");
+				const name = input.slice(pinned ? 10 : 12).trim();
+				if (!name) return err(`Usage: /evolution skill ${pinned ? "pin" : "unpin"} <name>`);
+				const ioRegistry = ctx.get("evolutionIo");
+				if (!ioRegistry) return err("Evolution IO registry not mounted — skill pinning unavailable.");
+				const result = await newSkillLibrary({
+					config: { root: skillsRootValue },
+					io: ioRegistry.provider(),
+					ctx,
+					limits: {
+						...DEFAULT_SKILL_LIMITS,
+						...policyStageLimits(ctx.get("evolutionPolicy")?.get?.())
+					}
+				}).setPinned(name, pinned);
+				return result.ok ? ok(result.message) : err(result.message);
+			}
 			if (input === "skills health") {
 				const curator = ctx.get("evolutionCurator");
 				if (!curator) return err(errorText("e-302-curator-service-not-mounted"));
@@ -1751,7 +1868,7 @@ function apply(ctx, rawConfig = {}) {
 					agent.followup(message);
 					woke = true;
 				} else if (typeof agent.inject === "function") agent.inject(message);
-				else return err(errorText("e-305-the-invocation-agent-exposes"));
+				else return err(errorText("e-305-the-invocation-agent-exposes", { a1: "this learn request" }));
 				const eventIo = ctx.get("evolutionIo")?.provider();
 				if (eventIo) appendEvolutionEvent(eventIo, eventsFile(evolutionRoot()), {
 					type: "learn",
@@ -1812,6 +1929,7 @@ function apply(ctx, rawConfig = {}) {
 				}
 				const runHome = evolutionHome();
 				const runRoot = evolutionRoot();
+				const runAgent = invocationAgent;
 				const handle = await registry.begin("maintain");
 				(async () => {
 					try {
@@ -1842,7 +1960,11 @@ function apply(ctx, rawConfig = {}) {
 							runId: handle.id,
 							...outcome.ok ? {
 								verdict: outcome.verdict,
-								recommendationCount: outcome.recommendationCount
+								recommendationCount: outcome.recommendationCount,
+								items: outcome.items,
+								notes: outcome.notes,
+								forcedHuman: outcome.forcedHuman,
+								needsHumanCount: outcome.needsHumanCount
 							} : {},
 							...outcome.ok ? {} : { failure: handle.signal.aborted ? "cancelled: the scan was stopped before it settled" : outcome.error ?? "Maintenance scan failed." },
 							startedAt: handle.startedAt,
@@ -1857,16 +1979,44 @@ function apply(ctx, rawConfig = {}) {
 							...resultRef === void 0 ? {} : { resultRef },
 							...outcome.ok ? {} : { failure: handle.signal.aborted ? "cancelled: the scan was stopped before it settled" : outcome.error ?? "Maintenance scan failed." }
 						});
-						if (outcome.ok) appendEvolutionEvent(ioRegistry.provider(), eventsFile(runRoot), {
-							type: "maintain",
-							source: "manual",
-							runId: handle.id,
-							verdict: outcome.verdict,
-							recommendations: outcome.recommendationCount
-						}).catch((error) => {
-							ctx.logger.warn(`evolution-commands: failed to record maintain event: ${String(error)}`);
-						});
-						else ctx.logger.warn(`evolution-commands: maintenance run ${handle.id} produced no plan (${outcome.error ?? "unknown reason"})`);
+						if (outcome.ok) {
+							appendEvolutionEvent(ioRegistry.provider(), eventsFile(runRoot), {
+								type: "maintain",
+								source: "manual",
+								runId: handle.id,
+								verdict: outcome.verdict,
+								recommendations: outcome.recommendationCount
+							}).catch((error) => {
+								ctx.logger.warn(`evolution-commands: failed to record maintain event: ${String(error)}`);
+							});
+							if (liveFlag(config.maintainHandoffOnSettle) && resultRef !== void 0 && runAgent !== void 0) try {
+								if (deliverHandoff(runAgent, createUserMessage({
+									content: [{
+										type: "text",
+										text: handoffPrompt({
+											runId: handle.id,
+											reportPath: reportDigestPath({
+												id: handle.id,
+												resultRef
+											}),
+											verdict: outcome.verdict,
+											recommendationCount: outcome.recommendationCount,
+											needsHumanCount: outcome.needsHumanCount
+										})
+									}],
+									source: {
+										kind: "evolution-commands",
+										form: "notice",
+										summary: "maintenance report handoff (auto)"
+									}
+								})) === void 0) ctx.logger.warn(`evolution-commands: the automatic report handoff for run ${handle.id} could not be delivered — this host exposes neither followup nor inject; the report is at ${reportDigestPath({
+									id: handle.id,
+									resultRef
+								})}`);
+							} catch (error) {
+								ctx.logger.warn(`evolution-commands: automatic report handoff failed (${String(error)})`);
+							}
+						} else ctx.logger.warn(`evolution-commands: maintenance run ${handle.id} produced no plan (${outcome.error ?? "unknown reason"})`);
 					} catch (error) {
 						const aborted = handle.signal.aborted;
 						const failure = aborted ? "cancelled: the scan was stopped before it settled" : `Maintenance scan failed: ${error instanceof Error ? error.message : String(error)}`;
@@ -1905,15 +2055,22 @@ function apply(ctx, rawConfig = {}) {
 				const recent = all.filter((record) => record.state !== "running").slice(0, 5);
 				return ok([live.length === 0 ? "No maintenance run in flight." : `In flight:\n${live.map(renderRunRecord).join("\n")}`, recent.length === 0 ? "" : `Recent:\n${recent.map(renderRunRecord).join("\n")}`].filter((part) => part !== "").join("\n"));
 			}
-			const maintainReport = /^maintain\s+report\s+(\S+)\s*$/.exec(input);
+			const maintainReport = /^maintain\s+report(?:\s+(\S+))?\s*$/.exec(input);
 			if (maintainReport) {
 				const registry = runs;
 				if (!registry) return err("Evolution IO registry not mounted — run results unavailable.");
-				await syncRuns(registry);
+				const synced = await syncRuns(registry);
 				const wanted = maintainReport[1];
-				if (wanted === void 0) return err("maintain report needs a run id: /evolution maintain report <id>.");
-				const record = registry.find(wanted);
-				if (!record) return err(`No run ${wanted} in this home — /evolution maintain status lists the recent ones.`);
+				if (wanted === void 0 && !synced.ok) return err(unreadableIndex(synced.note));
+				const record = wanted === void 0 ? newestRun(registry) : registry.find(wanted);
+				if (!record) {
+					if (wanted !== void 0) {
+						if (!synced.ok) return err(unreadableForId(wanted, synced.note));
+						return err(`No run ${wanted} in this home — /evolution maintain status lists the recent ones.`);
+					}
+					return err("No maintenance run recorded in this home yet — /evolution maintain starts one.");
+				}
+				if (wanted === void 0 && record.state === "running") return err(`The newest run ${record.id} is still running — its report appears when it settles; /evolution maintain status ${record.id} shows where it is.`);
 				const ioRegistry = ctx.get("evolutionIo");
 				if (!ioRegistry) return err("Evolution IO registry not mounted — run results unavailable.");
 				const probed = await readRunReport(ioRegistry.provider(), record);
@@ -1921,22 +2078,72 @@ function apply(ctx, rawConfig = {}) {
 				if (probed.kind === "unknown") return err(`Run ${record.id} has a report that could not be read (${probed.reason}) — this is not "no result".`);
 				return ok(probed.text);
 			}
-			const maintainCancel = /^maintain\s+cancel\s+(\S+)\s*$/.exec(input);
+			const maintainCancel = /^maintain\s+cancel(?:\s+(\S+))?\s*$/.exec(input);
 			if (maintainCancel) {
 				const registry = runs;
 				if (!registry) return err("Evolution IO registry not mounted — run cancellation unavailable.");
-				await syncRuns(registry);
+				const synced = await syncRuns(registry);
 				const wanted = maintainCancel[1];
-				if (wanted === void 0) return err("maintain cancel needs a run id: /evolution maintain cancel <id>.");
-				const record = registry.find(wanted);
-				if (!record) return err(`No run ${wanted} in this home — /evolution maintain status lists the recent ones.`);
+				if (wanted === void 0 && !synced.ok) return err(unreadableIndex(synced.note));
+				const record = wanted === void 0 ? newestRun(registry) : registry.find(wanted);
+				if (!record) {
+					if (wanted !== void 0) {
+						if (!synced.ok) return err(unreadableForId(wanted, synced.note));
+						return err(`No run ${wanted} in this home — /evolution maintain status lists the recent ones.`);
+					}
+					return err("No maintenance run recorded in this home yet — /evolution maintain starts one.");
+				}
+				const idlessHint = wanted === void 0 ? " Pass an id to cancel a specific run: /evolution maintain status lists them." : "";
 				if (!registry.cancel(record.id)) {
 					if (record.state === "running") return err(`Run ${record.id} is running in ANOTHER process sharing this home — it can only be cancelled there.`);
-					return err(`Run ${record.id} is already ${record.state} — nothing to cancel.`);
+					return err(`Run ${record.id} is already ${record.state} — nothing to cancel.${idlessHint}`);
 				}
 				return ok(`Maintenance run ${record.id} cancelled — the scan stops at its next checkpoint. /evolution maintain status ${record.id} shows the terminal state.`);
 			}
-			if (/^maintain\b/.test(input)) return err("Unknown maintain arguments: expected `maintain`, `maintain --timeout <ms>` / `maintain --timeout=<ms>`, `maintain status [<id>]`, `maintain report <id>` or `maintain cancel <id>`. Got: " + input);
+			const maintainHandoff = /^maintain\s+handoff(?:\s+(\S+))?\s*$/.exec(input);
+			if (maintainHandoff) {
+				const registry = runs;
+				if (!registry) return err("Evolution IO registry not mounted — the report cannot be handed over.");
+				const synced = await syncRuns(registry);
+				const wanted = maintainHandoff[1];
+				if (wanted === void 0 && !synced.ok) return err(unreadableIndex(synced.note));
+				const record = wanted === void 0 ? newestRun(registry) : registry.find(wanted);
+				if (!record) {
+					if (wanted !== void 0) {
+						if (!synced.ok) return err(unreadableForId(wanted, synced.note));
+						return err(`No run ${wanted} in this home — /evolution maintain status lists the recent ones.`);
+					}
+					return err("No maintenance run recorded in this home yet — /evolution maintain starts one.");
+				}
+				if (wanted === void 0 && record.state === "running") return err(`The newest run ${record.id} is still running — its report appears when it settles; /evolution maintain status ${record.id} shows where it is.`);
+				const ioRegistry = ctx.get("evolutionIo");
+				if (!ioRegistry) return err("Evolution IO registry not mounted — the report cannot be handed over.");
+				const probed = await readRunReport(ioRegistry.provider(), record);
+				if (probed.kind === "missing") return err(`Run ${record.id} (${record.state}) has NO result: no report was written${record.failure === void 0 ? "" : ` (${record.failure})`}.`);
+				if (probed.kind === "unknown") return err(`Run ${record.id} has a report that could not be read (${probed.reason}) — this is not "no result".`);
+				const missingAgent = agentMissing("handoff");
+				if (missingAgent) return missingAgent;
+				const woke = deliverHandoff(invocationAgent, createUserMessage({
+					content: [{
+						type: "text",
+						text: handoffPrompt({
+							runId: record.id,
+							reportPath: reportDigestPath(record),
+							verdict: probed.report.verdict,
+							recommendationCount: probed.report.recommendationCount,
+							needsHumanCount: probed.report.needsHumanCount
+						})
+					}],
+					source: {
+						kind: "evolution-commands",
+						form: "notice",
+						summary: "maintenance report handoff"
+					}
+				}));
+				if (woke === void 0) return err(errorText("e-305-the-invocation-agent-exposes", { a1: "this maintenance handoff" }));
+				return ok(woke ? `Handed run ${record.id} to the model — report: ${reportDigestPath(record)}. It will read the file and follow the action lines.` : `Handed run ${record.id} to the model, queued — this host exposes no wake-up channel, so it is read on your next message.`);
+			}
+			if (/^maintain\b/.test(input)) return err("Unknown maintain arguments: expected `maintain`, `maintain --timeout <ms>` / `maintain --timeout=<ms>`, `maintain status [<id>]`, `maintain report [<id>]`, `maintain handoff [<id>]` or `maintain cancel [<id>]`. 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>[,<name>...]` (the names live in the agent package's bases.json). Got: " + input);

package/lib/types/index.d.ts

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

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