@lmzhen/dsh-evolution-curator 0.1.0-rc.37 → 0.1.0-rc.39

package/README.md

@@ -28,4 +28,10 @@ Independent of request-prefix construction. This package does not alter the asse
 
 - `archive` never deletes: skills move to `.archive/` with a `.archive-reason` marker.
 - `restore(name)` (service) / `/evolution skill restore <name>` brings one archived skill back to the active root and resets its usage state.
-- `consolidate(target, sources)` (service) / `/evolution consolidate` merges source bodies into the target, archives the sources with an absorbed-into marker, and folds their usage records into `archived` state. Both operations snapshot the skill tree first (`pre-consolidate` / `pre-restore`).
+- `consolidate(target, sources)` (service) / `/evolution consolidate` merges source bodies into the target, archives the sources with an absorbed-into marker, and folds their usage records into `archived` state. Both operations snapshot the full state first (`pre-consolidate` / `pre-restore`).
+- `restoreSnapshot` (service) / `/evolution restore` rolls the FULL state back to the latest snapshot: active tree, usage/suppression sidecars, `.archive/` and the curator state carried in the snapshot (`curator-state.json`), so the interval gate does not immediately re-fire after a rollback. The restore itself is undoable — the pre-rollback safety snapshot preserves the current tree plus its state.
+
+## Automatic scheduling
+
+- `autoStart` (default true) arms an hourly interval check plus a deferred catch-up check `bootGraceSeconds` (default 10) after host boot. Both decide due-ness from the **persisted** `lastRunAt`, so a restart with an overdue schedule runs the first pass within the boot grace instead of waiting a full interval. `bootGraceSeconds: 0` disables the deferral (not recommended: the check may run against a half-mounted host). All scheduling gates — interval, idle, first-run deferral, and the reentrancy guard — remain inside `run()`.
+- `autoStart: false` disables both automatic checks; `/evolution curator run` (manual, gate-skipping) still works.

package/lib/index.js

@@ -35,6 +35,7 @@ var EvolutionCurator = class extends Service {
 		pruneBuiltins: z.boolean().default(false),
 		referencedSkillNames: z.array(z.string()).default([]),
 		autoStart: z.boolean().default(true),
+		bootGraceSeconds: z.number().default(10),
 		curatorReviewMaxTokens: z.number().default(2048)
 	});
 	skills;
@@ -51,9 +52,12 @@ var EvolutionCurator = class extends Service {
 	manageUnmanaged;
 	pruneBuiltins;
 	referencedSkillNames;
+	bootGraceSeconds;
 	curatorReviewMaxTokens;
 	lastRun = 0;
 	timer;
+	bootCheck;
+	running = false;
 	constructor(ctx, config = {}) {
 		super(ctx, "evolutionCurator");
 		this.io = evolutionIoAdapter(() => ctx.evolutionIo.provider());
@@ -70,6 +74,7 @@ var EvolutionCurator = class extends Service {
 		this.manageUnmanaged = config.manageUnmanaged ?? false;
 		this.pruneBuiltins = config.pruneBuiltins ?? false;
 		this.referencedSkillNames = new Set(config.referencedSkillNames ?? []);
+		this.bootGraceSeconds = config.bootGraceSeconds ?? 10;
 		this.curatorReviewMaxTokens = config.curatorReviewMaxTokens ?? 2048;
 		this.lastRun = Date.now();
 		this.ctx.effect(() => {
@@ -89,14 +94,30 @@ var EvolutionCurator = class extends Service {
 	}
 	start() {
 		if (!this.enabled || this.timer) return;
-		this.timer = setInterval(() => {
-			if (Date.now() - this.lastRun >= this.lifecycle().intervalHours * 36e5) this.run();
-		}, 3600 * 1e3);
+		this.bootCheck = setTimeout(() => {
+			this.bootCheck = void 0;
+			this.autoCheck();
+		}, this.bootGraceSeconds * 1e3);
+		this.bootCheck.unref();
+		this.timer = setInterval(() => void this.autoCheck(), 3600 * 1e3);
 		this.timer.unref();
 	}
 	stop() {
 		if (this.timer) clearInterval(this.timer);
 		this.timer = void 0;
+		if (this.bootCheck) clearTimeout(this.bootCheck);
+		this.bootCheck = void 0;
+	}
+	/**
+	* One automatic schedule check: run a pass when the persisted curator state
+	* (falling back to the in-memory clock for state-less compositions) is at
+	* least one interval old. All gates — interval, idle, first-run defer,
+	* reentrancy — stay inside `run()`, so this method only decides whether to
+	* wake it, and never duplicates gate logic.
+	*/
+	async autoCheck() {
+		const last = (await this.curatorStateService()?.loadCuratorState())?.lastRunAt ?? this.lastRun;
+		if (Date.now() - last >= this.lifecycle().intervalHours * 36e5) await this.run();
 	}
 	/**
 	* Optional Hermes-curator LLM pass. The model may only NOMINATE pruning and
@@ -151,6 +172,47 @@ var EvolutionCurator = class extends Service {
 			return empty;
 		}
 	}
+	/** Optional curator-state service (evolution-state-json / storage-domain). */
+	curatorStateService() {
+		return this.ctx.get("evolutionState");
+	}
+	/**
+	* Full-state snapshot: the skills tree plus the current curator state as an
+	* `extras/curator-state.json` side file. Every pre-mutation snapshot in the
+	* curator goes through here so a later `restoreSnapshot()` can rewind both
+	* the tree and the state (Hermes curator_backup backs up `.curator_state`).
+	*/
+	async snapshotFull(reason = "pre-mutation") {
+		const state = await this.curatorStateService()?.loadCuratorState();
+		const extras = state === null || state === void 0 ? [] : [{
+			name: "curator-state.json",
+			content: JSON.stringify(state, null, 2)
+		}];
+		return await this.skills.snapshotAll(reason, extras);
+	}
+	/**
+	* Full-state rollback: restore the latest snapshot's tree/sidecars/archive
+	* AND the curator state it carried. The pre-rollback safety snapshot keeps
+	* the current tree plus current state (as extras), so the rollback itself
+	* is reversible.
+	*/
+	async restoreSnapshot() {
+		const stateService = this.curatorStateService();
+		const currentState = await stateService?.loadCuratorState();
+		const extras = currentState === null || currentState === void 0 ? [] : [{
+			name: "curator-state.json",
+			content: JSON.stringify(currentState, null, 2)
+		}];
+		const result = await this.skills.restoreLatestSnapshot(extras);
+		if (!result.ok) return result;
+		const stateExtra = result.extras?.find((extra) => extra.name === "curator-state.json");
+		if (stateExtra && stateService) try {
+			await stateService.saveCuratorState(JSON.parse(stateExtra.content));
+		} catch (error) {
+			this.ctx.logger.warn(`evolution-curator: failed to restore curator state: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		return result;
+	}
 	skippedReport(runId, startedAt) {
 		return buildCuratorRunReport({
 			runId,
@@ -169,12 +231,29 @@ var EvolutionCurator = class extends Service {
 	* explicit `/evolution curator run` always executes (manual-run semantics):
 	* `dryRun` computes the lifecycle and the LLM nominations but performs no
 	* mutation, reports what WOULD happen, and does not push out the next run.
+	* Reentrant calls (autoStart timer + manual command at the same instant) are
+	* skipped with an explicit `already-running` outcome.
 	*/
 	async run(options = {}) {
+		if (this.running) return {
+			stale: [],
+			archived: [],
+			errors: [],
+			report: this.skippedReport("already-running", (/* @__PURE__ */ new Date()).toISOString()),
+			skipped: "already-running"
+		};
+		this.running = true;
+		try {
+			return await this.runCore(options);
+		} finally {
+			this.running = false;
+		}
+	}
+	async runCore(options = {}) {
 		const { ignoreGates = false, dryRun = false } = options;
 		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 		const runId = randomUUID();
-		const stateService = this.ctx.get("evolutionState");
+		const stateService = this.curatorStateService();
 		const lifecycle = this.lifecycle();
 		const persisted = await stateService?.loadCuratorState();
 		if (!ignoreGates && persisted && Date.now() - persisted.lastRunAt < lifecycle.intervalHours * 36e5) return {
@@ -210,7 +289,7 @@ var EvolutionCurator = class extends Service {
 		const root = this.skills.root;
 		const rawUsage = await loadUsage(root, this.io);
 		const usage = dryRun ? new Map([...rawUsage].map(([name, record]) => [name, { ...record }])) : rawUsage;
-		const snapshotPath = dryRun ? void 0 : await this.skills.snapshotAll("pre-curator-run");
+		const snapshotPath = dryRun ? void 0 : await this.snapshotFull("pre-curator-run");
 		const suppressedNames = new Set(await loadSuppressedNames(root, this.io));
 		const { bundledNames, treeNames } = await this.seedBaseline(usage);
 		const result = computeLifecycleTransitions(usage, {
@@ -501,7 +580,7 @@ var EvolutionCurator = class extends Service {
 			ok: false,
 			message: `Skill(s) excluded from lifecycle management: ${blocked.join(", ")}`
 		};
-		await this.skills.snapshotAll("pre-consolidate");
+		await this.snapshotFull("pre-consolidate");
 		const result = await this.skills.consolidate(target, sources);
 		if (!result.ok) return result;
 		const usage = await loadUsage(this.skills.root, this.io);
@@ -518,7 +597,7 @@ var EvolutionCurator = class extends Service {
 	* and reset its usage state, keeping the recoverable-archive invariant.
 	*/
 	async restore(name) {
-		await this.skills.snapshotAll("pre-restore");
+		await this.snapshotFull("pre-restore");
 		const result = await this.skills.restoreFromArchive(name);
 		if (!result.ok) return result;
 		const usage = await loadUsage(this.skills.root, this.io);

package/lib/types/index.d.ts

@@ -33,6 +33,8 @@ export interface Config {
     referencedSkillNames?: string[];
     /** Start the interval timer on context ready (auto-curation). Default true. */
     autoStart?: boolean;
+    /** Seconds between host boot and the first automatic schedule check (restart catch-up). */
+    bootGraceSeconds?: number;
     /** Max tokens for the optional LLM nomination pass. */
     curatorReviewMaxTokens?: number;
 }
@@ -82,13 +84,24 @@ export declare class EvolutionCurator extends Service {
     private readonly manageUnmanaged;
     private readonly pruneBuiltins;
     private readonly referencedSkillNames;
+    private readonly bootGraceSeconds;
     private readonly curatorReviewMaxTokens;
     private lastRun;
     private timer;
+    private bootCheck;
+    private running;
     constructor(ctx: Context, config?: Config);
     private lifecycle;
     start(): void;
     stop(): void;
+    /**
+     * One automatic schedule check: run a pass when the persisted curator state
+     * (falling back to the in-memory clock for state-less compositions) is at
+     * least one interval old. All gates — interval, idle, first-run defer,
+     * reentrancy — stay inside `run()`, so this method only decides whether to
+     * wake it, and never duplicates gate logic.
+     */
+    private autoCheck;
     /**
      * Optional Hermes-curator LLM pass. The model may only NOMINATE pruning and
      * consolidation; every move stays a control-plane operation and each
@@ -98,17 +111,41 @@ export declare class EvolutionCurator extends Service {
     recommend(candidates: string[], options?: {
         dryRun?: boolean;
     }): Promise<CuratorNominations>;
+    /** Optional curator-state service (evolution-state-json / storage-domain). */
+    private curatorStateService;
+    /**
+     * Full-state snapshot: the skills tree plus the current curator state as an
+     * `extras/curator-state.json` side file. Every pre-mutation snapshot in the
+     * curator goes through here so a later `restoreSnapshot()` can rewind both
+     * the tree and the state (Hermes curator_backup backs up `.curator_state`).
+     */
+    snapshotFull(reason?: string): Promise<string>;
+    /**
+     * Full-state rollback: restore the latest snapshot's tree/sidecars/archive
+     * AND the curator state it carried. The pre-rollback safety snapshot keeps
+     * the current tree plus current state (as extras), so the rollback itself
+     * is reversible.
+     */
+    restoreSnapshot(): Promise<SkillActionResult & {
+        extras?: Array<{
+            name: string;
+            content: string;
+        }>;
+    }>;
     private skippedReport;
     /**
      * Run one curator pass. `ignoreGates` skips the interval and idle gates so an
      * explicit `/evolution curator run` always executes (manual-run semantics):
      * `dryRun` computes the lifecycle and the LLM nominations but performs no
      * mutation, reports what WOULD happen, and does not push out the next run.
+     * Reentrant calls (autoStart timer + manual command at the same instant) are
+     * skipped with an explicit `already-running` outcome.
      */
     run(options?: {
         ignoreGates?: boolean;
         dryRun?: boolean;
     }): Promise<CuratorRunOutcome>;
+    private runCore;
     /**
      * Seed baseline records for tree skills the sidecar has not seen yet, so
      * their inactivity clock starts now (first-sight defer) and bundled skills

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-curator",
   "description": "Deterministic skill lifecycle and recovery (community build)",
-  "version": "0.1.0-rc.37",
+  "version": "0.1.0-rc.39",
   "publishConfig": {
     "access": "public"
   },
@@ -33,20 +33,20 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.37"
+    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.39"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.37",
-    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.37"
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.39",
+    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.39"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.37",
-    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.37",
-    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.37"
+    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.39",
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.39",
+    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.39"
   }
 }