@lmzhen/dsh-evolution-commands 0.3.80 → 0.3.82

package/lib/index.js

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 import z from "@deepseek-ai/schemastery";
 import { effectiveSessionPolicy } from "@lmzhen/dsh-evolution-approval";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { MAX_TIMER_DELAY_MS, appendEvolutionEvent, assertSkillsRootAliasRetired, buildLearnPrompt, clampedNumber, composePresetComposition, eventsFile, evolutionRoot, newSkillLibrary, resolveRootConfig } from "@lmzhen/dsh-evolution-core";
+import { MAX_TIMER_DELAY_MS, appendEvolutionEvent, assertSkillsRootAliasRetired, buildLearnPrompt, clampedNumber, composePresetComposition, eventsFile, evolutionRoot, isMissingPath, newSkillLibrary, resolveRootConfig, scopedProbeReport } from "@lmzhen/dsh-evolution-core";
 import { buildEnrichment, buildMaintainFacts, runMaintain, snapshotFromLibrary } from "@lmzhen/dsh-evolution-maintenance";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -323,8 +323,9 @@ async function diagnose(ctx, options = {}) {
 	if (host && preset) conflicts.push("evolution-host and evolution-preset are installed together — the infra rows double-mount. Keep ONE.");
 	if (full && presetDirInstalled) conflicts.push(`evolution-all and the layered Evolution preset (${layeredArtifactLabel}) are both present — the model rows double-mount. Keep ONE (use layered without all, or drop the preset).`);
 	if (preset && presetDirInstalled) conflicts.push(`evolution-preset and the layered Evolution preset (${layeredArtifactLabel}) are both present — the model rows double-mount (the preset bundle carries the same model rows as all). Keep ONE (drop the preset bundle, or remove the layered preset).`);
+	const reviewMounted = full || host || preset;
 	const services = {
-		review: full || host || preset,
+		review: reviewMounted,
 		curator: has("evolutionCurator"),
 		approval: has("evolutionApproval"),
 		skillUsage: has("skillUsage"),
@@ -333,10 +334,13 @@ async function diagnose(ctx, options = {}) {
 	let pendingCount = null;
 	let executingCount = null;
 	const approvalService = ctx.get("evolutionApproval");
-	if (approvalService?.list) try {
-		const rows = await approvalService.list("pending");
+	const approvalList = approvalService?.list?.bind(approvalService);
+	if (approvalList !== void 0) try {
+		const pendingProbe = await probeBounded(() => approvalList("pending"), "approval pending listing");
+		const rows = pendingProbe.ok ? pendingProbe.value : void 0;
 		pendingCount = Array.isArray(rows) ? rows.length : null;
-		const executing = await approvalService.list("executing");
+		const executingProbe = await probeBounded(() => approvalList("executing"), "approval executing listing");
+		const executing = executingProbe.ok ? executingProbe.value : void 0;
 		executingCount = Array.isArray(executing) ? executing.length : null;
 	} catch {
 		pendingCount = null;
@@ -346,6 +350,10 @@ async function diagnose(ctx, options = {}) {
 	const deploymentForm = installForm === "layered" ? "variant" : installForm === "full" || installForm === "preset" ? "attach" : installForm === "host" ? "host-only" : installForm === "preset-only" ? "preset-only" : "none";
 	const mountConflicts = conflicts.filter((row) => !row.includes("DEGRADED"));
 	const undecidable = mountConflicts.length !== conflicts.length;
+	const scopedProbe = {
+		rows: undecidable ? null : reviewMounted ? ["evolution-review", "skill-usage"] : [],
+		...scopedProbeReport()
+	};
 	const actions = [];
 	if (mountConflicts.length > 0) actions.push("Resolve the conflict first: keep exactly one of evolution-all / evolution-host / evolution-preset / layered.");
 	else if (undecidable) actions.push("The install form is UNDECIDABLE (see the DEGRADED row above): an unreadable profiles directory or profile manifest hides whatever is installed, so this report must not add or remove a bundle. Fix the reported read failure, then re-run /evolution doctor.");
@@ -357,7 +365,12 @@ async function diagnose(ctx, options = {}) {
 	if (services.review && !services.curator) actions.push("Curator service is not mounted — automatic curation is off; verify the host/all bundle row set is complete.");
 	if (pendingCount === null && services.approval) actions.push("Approval service is mounted but pending listing failed — check the evolution state service.");
 	const memoryIssues = memoryInterpolationIssues(home);
+	const budgetIssues = memoryBudgetIssues(ctx);
+	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 (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;
@@ -370,18 +383,126 @@ async function diagnose(ctx, options = {}) {
 		conflicts,
 		envIssues: env,
 		memoryIssues,
+		budgetIssues,
+		queryIssues,
 		services,
 		pendingCount,
 		executingCount,
 		presetFreshness,
+		scopedProbe,
 		actions
 	};
 }
+/**
+* S2-12③ (FLOW5-4): the memory budget is configured in TWO places —
+* `memory-files`' `memoryCharLimit`/`userCharLimit` (what the STORE enforces)
+* and `evolution-policy`'s `memoryChars`/`userChars` (what the review PLANS
+* against; `memory-files` follows the policy only for an UNSET limit). A
+* disagreement therefore means an explicit contradiction, or a `memory-files`
+* row mounted before the policy existed — either way the reviewer budgets ops
+* the store will refuse. Read-only, like every other doctor row.
+*
+* @param ctx - the runtime service view (`get(name)`).
+* @returns one message per disagreeing surface; empty when not comparable.
+*/
+/** S4 review (source-first pass) R-1: how long a diagnostic probe may wait.
+* Doctor must ANSWER even when the thing it probes is blocked — the failure it
+* reports (a concurrent writer stalling the corpus) is exactly the one that
+* would otherwise hang the command forever. */
+const PROBE_TIMEOUT_MS = 5e3;
+/**
+* Bound a diagnostic probe. A never-settling service is a FINDING, not a hang:
+* the probe reports it like any other failure.
+*
+* Takes a THUNK, not a promise (review R-2): a mounted-but-broken service can
+* throw synchronously, and `probeBounded(Promise.resolve(service.list()))` would
+* let that throw escape the probe — crashing the command instead of reporting.
+*
+* @param work - the probe's work, invoked inside the guard.
+* @param label - the surface being probed (named in the finding).
+* @returns the value, or a message describing the failure/timeout.
+*/
+async function probeBounded(work, label) {
+	let started;
+	try {
+		started = work();
+	} catch (error) {
+		return {
+			ok: false,
+			message: `${label} failed: ${error instanceof Error ? error.message : String(error)}`
+		};
+	}
+	let timer;
+	const timeout = new Promise((resolve) => {
+		timer = setTimeout(() => {
+			resolve({
+				ok: false,
+				message: `${label} did not answer within ${PROBE_TIMEOUT_MS}ms — the corpus is blocked (a concurrent writer can stall the observation) or the service is wedged; isolate the most recently written session and re-run`
+			});
+		}, PROBE_TIMEOUT_MS);
+	});
+	const settled = started.then((value) => ({
+		ok: true,
+		value
+	}), (error) => ({
+		ok: false,
+		message: `${label} failed: ${error instanceof Error ? error.message : String(error)}`
+	}));
+	const outcome = await Promise.race([settled, timeout]);
+	if (timer !== void 0) clearTimeout(timer);
+	return outcome;
+}
+/**
+* S4/P-1+P-2 (platform report P-1/P-2, family mitigation) — the session-query
+* index can fail AS A WHOLE: a concurrent writer leaves the persistence
+* observation unstable ('did not stabilize after one retry') and ONE
+* header-conflicting session aborts the same try block, which the tool surface
+* folds into 'storage is unavailable'. Doctor cannot read the index's row count
+* or the last stabilization result (the platform exposes no such API — recorded
+* in the platform report), but it CAN exercise the corpus listing and report the
+* verbatim failure with the actionable half: isolate the offending session.
+*
+* @param ctx - the runtime service view (`get(name)`).
+* @returns one or two messages; empty when the service is absent or healthy.
+*/
+async function sessionQueryIssues(ctx) {
+	const service = ctx.get("sessionQuery");
+	const list = service?.listSessions?.bind(service);
+	if (list === void 0) return [];
+	const outcome = await probeBounded(() => list(), "session-query listing");
+	if (!outcome.ok) return [outcome.message, "isolate the offending session — move it OUT of the corpus with a manifest (never delete it) and re-run; the platform already retries the observation once, so retrying first is not the answer"];
+	return Array.isArray(outcome.value) ? [] : ["session-query answered a listing with a non-list value — the service is mounted but not honouring its read contract"];
+}
+function memoryBudgetIssues(ctx) {
+	const budget = ctx.get("evolutionMemoryBudget");
+	const policy = ctx.get("evolutionPolicy")?.get?.();
+	if (budget === void 0 || policy === void 0) return [];
+	const issues = [];
+	if (budget.memoryCharLimit !== void 0 && policy.memoryChars !== void 0 && budget.memoryCharLimit !== policy.memoryChars) issues.push(`store enforces memoryCharLimit=${budget.memoryCharLimit} (source: ${budget.memorySource ?? "unknown"}) while evolution-policy declares memoryChars=${policy.memoryChars} — the review plans against the policy value and the store refuses what exceeds its own`);
+	if (budget.userCharLimit !== void 0 && policy.userChars !== void 0 && budget.userCharLimit !== policy.userChars) issues.push(`store enforces userCharLimit=${budget.userCharLimit} (source: ${budget.userSource ?? "unknown"}) while evolution-policy declares userChars=${policy.userChars} — same divergence as the memory limit`);
+	return issues;
+}
+/** S0-4 (v43 G-1 / J-1): the scoped-row reconciliation line. The verdict is the
+* runtime witness, the row set is what this home installs, and the two forms are
+* spelled out because they read identically in the numbers (`never-hit`) while
+* needing opposite responses: under the host-only form nothing can ever match,
+* under the variant form the match arrives with the first Evolution-preset
+* session.
+* @param check - the report's scoped-row check.
+* @returns one line, or the earlier diagnostic when either half is unknown. */
+function scopedProbeLine(check) {
+	if (check.rows === null) return `scoped rows: (undecidable), probe=${check.verdict} — a DEGRADED bundle read hides which bundles are installed, so the scoped rows cannot be reconciled with the probe`;
+	if (check.rows.length === 0) return `scoped rows: (none mounted), probe=${check.verdict} — no installed bundle carries the session-scoped rows (evolution-review / skill-usage), so the gate is inactive here`;
+	const rows = check.rows.map((row) => `${row}=on`).join("/");
+	const detail = check.verdict === "hit" ? `${check.hits} scoped evaluation(s) carried the family tools` : check.verdict === "never-hit" ? `${check.misses} scoped evaluation(s) resolved false — review injection and skill-usage telemetry are inert for every session observed; HOST-ONLY installs reach this because tool-memory / tool-skill-manage are not dependencies of evolution-host, VARIANT installs only match once a session runs the Evolution preset` : "the gate has not evaluated a session in this process yet — no session event has reached it since startup";
+	return `scoped rows: ${rows}, probe=${check.verdict} (${detail})`;
+}
 function renderDoctorText(report) {
 	const lines = [
 		`Evolution doctor — install form: ${report.installForm} (deployment: ${report.deploymentForm})`,
 		`bundles (all profiles): ${report.bundles.length > 0 ? report.bundles.join(", ") : "(none)"}`,
 		`services: review=${report.services.review} (inferred from bundles, all profiles) curator=${report.services.curator} approval=${report.services.approval} skillUsage=${report.services.skillUsage} io=${report.services.io}`,
+		scopedProbeLine(report.scopedProbe),
 		`pending: ${report.pendingCount === null ? "unknown" : report.pendingCount}`,
 		`executing: ${report.executingCount === null ? "unknown" : report.executingCount}`
 	];
@@ -393,6 +514,8 @@ function renderDoctorText(report) {
 	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.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.join("\n");
 }
@@ -516,6 +639,15 @@ function apply(ctx, rawConfig = {}) {
 					kind: "error",
 					text
 				});
+				const invocationAgent = invocation.agent;
+				const agentMissing = (need) => invocationAgent === void 0 ? err(`E-305: this invocation carries no agent — \`${need}\` needs a session-backed call (run it from a session in the GUI or the CLI).`) : void 0;
+				const unreplayableWriteRefusal = (what) => {
+					if (approval === void 0) return void 0;
+					const session = invocationAgent?.session;
+					const sessionPolicy = effectiveSessionPolicy(ctx, session);
+					if (!(approval.isEnabled !== false && sessionPolicy !== "never" && approval.stageForeground !== false)) return void 0;
+					return err(`E-306: this deployment stages foreground writes, but \`/evolution ${what}\` is not replayable through the skill runner — there is nothing to stage. Run it from a session whose approval policy is 'never', or set \`stageForeground: false\` on the evolution-approval row, then repeat the command.`);
+				};
 				const approval = ctx.get("evolutionApproval");
 				const pendingMatch = /^pending(?: --detail)?$/.exec(input);
 				if (pendingMatch) {
@@ -628,6 +760,8 @@ function apply(ctx, rawConfig = {}) {
 				if (input === "restore" || input.startsWith("restore ")) {
 					const tail = input.slice(7).trim();
 					if (tail !== "") return err(`\`restore\` takes no arguments (got "${tail}"). Use \`restore\` for a whole-tree rollback, or \`skill restore <name>\` for one skill.`);
+					const restoreRefusal = unreplayableWriteRefusal("restore");
+					if (restoreRefusal) return restoreRefusal;
 					const curator = ctx.get("evolutionCurator");
 					const result = curator ? await curator.restoreSnapshot() : {
 						ok: false,
@@ -636,6 +770,8 @@ function apply(ctx, rawConfig = {}) {
 					return result.ok ? ok(result.message) : err(result.message);
 				}
 				if (input.startsWith("consolidate ")) {
+					const consolidateRefusal = unreplayableWriteRefusal("consolidate");
+					if (consolidateRefusal) return consolidateRefusal;
 					const planTail = /\s--plan\s+(\S+)\s*$/.exec(input) ?? null;
 					const planRunId = planTail?.[1] ?? void 0;
 					const [target, ...sources] = (planTail ? input.slice(0, planTail.index) : input).slice(12).trim().split(/\s+/).filter(Boolean);
@@ -651,6 +787,8 @@ function apply(ctx, rawConfig = {}) {
 				if (input.startsWith("skill restore ")) {
 					const name = input.slice(14).trim();
 					if (!name) return err("Usage: /evolution skill restore <name>");
+					const skillRestoreRefusal = unreplayableWriteRefusal("skill restore");
+					if (skillRestoreRefusal) return skillRestoreRefusal;
 					const curator = ctx.get("evolutionCurator");
 					const result = curator ? await curator.restore(name) : {
 						ok: false,
@@ -685,9 +823,15 @@ function apply(ctx, rawConfig = {}) {
 							summary: "learn request"
 						}
 					});
-					const woke = typeof invocation.agent.followup === "function";
-					if (woke) invocation.agent.followup(message);
-					else invocation.agent.inject(message);
+					const missingAgent = agentMissing("learn");
+					if (missingAgent) return missingAgent;
+					const agent = invocationAgent;
+					let woke = false;
+					if (typeof agent.followup === "function") {
+						agent.followup(message);
+						woke = true;
+					} else if (typeof agent.inject === "function") agent.inject(message);
+					else return err("E-305: the invocation agent exposes neither `followup` nor `inject` — this learn request has no delivery channel.");
 					const eventIo = ctx.get("evolutionIo")?.provider();
 					if (eventIo) appendEvolutionEvent(eventIo, eventsFile(evolutionRoot()), {
 						type: "learn",
@@ -848,9 +992,9 @@ function apply(ctx, rawConfig = {}) {
 					const ioRegistry = ctx.get("evolutionIo");
 					if (!ioRegistry) return err("Evolution IO registry not mounted — restructure unavailable.");
 					if (approval) {
-						const session = invocation.agent.session;
+						const session = invocationAgent?.session;
 						const sessionPolicy = effectiveSessionPolicy(ctx, session);
-						if (approval.isEnabled !== false && sessionPolicy !== "never" && approval.stageForeground !== false && !approval.hasRunner("skill")) return err("Restructure cannot be staged: no skill replay runner is registered — mount the tool-skill-manage row (evolution-agent preset, or evolution-all) or disable evolution-approval.");
+						if (session !== void 0 && approval.isEnabled !== false && sessionPolicy !== "never" && approval.stageForeground !== false && !approval.hasRunner("skill")) return err("Restructure cannot be staged: no skill replay runner is registered — mount the tool-skill-manage row (evolution-agent preset, or evolution-all) or disable evolution-approval.");
 						const decision = await approval.request({
 							kind: "skill",
 							summary: `/evolution restructure ${name}${planRunId ? ` (plan ${planRunId})` : ""}`,
@@ -867,8 +1011,10 @@ function apply(ctx, rawConfig = {}) {
 								libraryOrigin: "foreground"
 							},
 							origin: "foreground",
-							...session.id ? { sessionId: session.id } : {},
-							session,
+							...session !== void 0 ? {
+								sessionId: session.id,
+								session
+							} : {},
 							...sessionPolicy !== void 0 ? { sessionPolicy } : {}
 						});
 						if (decision.action === "staged") return ok(`${decision.message}${planRunId ? `\n[audit] plan=${planRunId}` : ""}`);
@@ -966,7 +1112,7 @@ const defaultFs = {
 		try {
 			return statSync(path).mtimeMs;
 		} catch (error) {
-			if (error.code === "ENOENT" || error.code === "ENOTDIR") return null;
+			if (isMissingPath(error)) return null;
 			throw error;
 		}
 	}

package/lib/types/doctor.d.ts

@@ -1,3 +1,4 @@
+import { type ScopedProbeReport } from '@lmzhen/dsh-evolution-core';
 /** G3-② (B2): one delivered preset variant compared against a fresh generation.
  * "absent" is the user simply not using that base (never an action); "unknown"
  * is a comparison that could not run, kept distinct from a verified "fresh". */
@@ -10,6 +11,29 @@ export interface PresetFreshnessRow {
     /** Why the comparison could not run — set on unknown rows only. */
     detail?: string;
 }
+/** S0-4 (v43 G-1 / J-1): the session-scoped rows against the runtime witness.
+ *
+ * The gate has two halves nobody reconciled: the bundle turns `sessionScoped` on
+ * for `evolution-review` and `skill-usage`, and the runtime witness knows
+ * whether ANY session ever saw the family's model tools. `never-hit` with the
+ * rows mounted is a finding — the host-only form mounts no model row at all
+ * (tool-memory / tool-skill-manage are devDependencies of evolution-host) and an
+ * overlay may disable either row, so review injection and skill-usage telemetry
+ * run for nobody. `idle` claims nothing: the gate simply has not been asked yet
+ * in this process. Read-only, like every other row of this report. */
+export interface ScopedProbeCheck {
+    /** The scoped rows the installed bundles mount (`evolution-review`,
+     * `skill-usage`); empty when no bundle is installed, and null when a DEGRADED
+     * bundle read makes the set undecidable — an unreadable manifest is not
+     * evidence of absence (the INST-01 / S2.1 discipline). */
+    rows: string[] | null;
+    /** The runtime witness, verbatim (`scopedProbeReport()`). */
+    verdict: ScopedProbeReport['verdict'];
+    /** Scoped gate evaluations that resolved true. */
+    hits: number;
+    /** Scoped gate evaluations that resolved false. */
+    misses: number;
+}
 export interface DoctorReport {
     /** OPT-23 (2026-09): `preset-only` — the delivered Evolution preset
      * artifact exists but NO profile carries an evolution bundle (e.g. the
@@ -39,6 +63,14 @@ export interface DoctorReport {
      * 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. */
+    queryIssues: string[];
+    /** S2-12③ (FLOW5-4): the memory budget's two configuration surfaces disagree —
+     * `memory-files`' store limit vs `evolution-policy`'s planning value. Empty
+     * when either surface is absent (nothing to compare) or they agree. */
+    budgetIssues: string[];
     services: {
         review: boolean;
         curator: boolean;
@@ -56,6 +88,10 @@ export interface DoctorReport {
      * upgrade leaves a file describing a platform that no longer exists. Read-only:
      * a stale snapshot is reported, never repaired. */
     presetFreshness: PresetFreshnessRow[];
+    /** S0-4 (v43 G-1 / J-1): the scoped rows × the probe witness, so a deployment
+     * whose cross-session consumers are inert for every session stops looking
+     * healthy. See {@link ScopedProbeCheck}. */
+    scopedProbe: ScopedProbeCheck;
     actions: string[];
 }
 /** Profile bundle rows for evolution-family packages across all profiles.

package/package.json

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