@senpi/runtime 1.1.0-dev.runtime-phase-2.20260513122539 → 1.1.0-dev.runtime-phase-2.20260514144638

package/dist/skills-manager/coordinator.js

@@ -1,14 +1,24 @@
 /**
  * Central lifecycle manager for Senpi skills auto-update.
  *
- * Mirrors AutoUpdateCoordinator from src/runtime/auto-update/coordinator.ts:
- * same runToken + stopped + running triple for thread-safety, same
- * self-managed setTimeout loop, same injectable-dependency pattern for
- * testability.
+ * Mirrors AutoUpdateCoordinator from src/runtime/auto-update/coordinator.ts
+ * for thread-safety (runToken + stopped + running triple) and uses the same
+ * injectable-dependency pattern for testability.
  *
- * On start(): bootstrap missing skills then schedule the first poll.
- * Each tick(): resolve skill names, check remote versions in parallel,
- * auto-apply patch/minor, notify on major (deduped), skip on none/unknown.
+ * Scheduling: this coordinator does not own a timer. Ticks fire from
+ * outside — currently from auto-update's `onTickComplete` hook in
+ * `src/index.ts`, which calls {@link SkillsUpdateCoordinator.runTickOnce}
+ * after every auto-update cycle. Skills-manager therefore inherits the
+ * `autoUpdate.pollIntervalMinutes` cadence and the same failure-backoff
+ * cadence.
+ *
+ * On start(): load persisted state, bootstrap any missing skills, mark
+ * health as healthy. The first tick fires on the next external invocation
+ * of `runTickOnce()`.
+ *
+ * Each tick: resolve skill names (configured list or discovery), check
+ * remote versions in parallel, auto-apply patch/minor, notify on major
+ * (deduped by version), skip on none/unknown.
  */
 import { readdir } from "node:fs/promises";
 import { bootstrapSkillsIfNeeded } from "./bootstrap.js";
@@ -18,10 +28,15 @@ import { checkSkillVersion } from "./version-manager.js";
 import { installSkill } from "./writer.js";
 import { SKILLS_RAW_BASE_URL, SKILLS_REPO_URL } from "./constants.js";
 import { createDefaultSkillState, createDefaultSkillsManagerState, formatErr } from "./utils.js";
+export class SkillsCoordinatorUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SkillsCoordinatorUnavailableError";
+    }
+}
 export class SkillsUpdateCoordinator {
     options;
     store;
-    timer = null;
     operationChain = Promise.resolve();
     stopped = true;
     runToken = 0;
@@ -29,12 +44,51 @@ export class SkillsUpdateCoordinator {
     snapshot;
     /** Latest remote version per skill name — populated during ticks. */
     latestVersions = new Map();
+    /**
+     * Local (pre-install) version per skill name — populated during ticks
+     * and manual RPC paths from `SkillVersionInfo.localVersion`. Used by the
+     * update-summary and major-available notifications to render the
+     * `prev → new` transition. Captured *before* the install runs so the
+     * value still reflects the on-disk version at the time the user chose to
+     * update; reading `state.skills[name].installedVersion` instead would
+     * surface the *post-install* version (recorded by `recordSuccess`) and
+     * collapse the transition to `vX -> vX`.
+     */
+    previousVersions = new Map();
+    /**
+     * Cached short descriptions parsed from each skill's **remote** SKILL.md
+     * frontmatter — i.e. the description for the upcoming/current remote
+     * version, not whatever's installed locally. Used to enrich
+     * update-summary and major-available notifications with a one-line
+     * "About:" so the user gets context for the version the message is
+     * actually announcing.
+     *
+     * Populated during tick / updateSkill / updateAll alongside
+     * `latestVersions`; absent / null entries simply omit the line from the
+     * notification.
+     *
+     * Using the remote description (rather than the local one) keeps the
+     * notification description in sync with the version number it sits next
+     * to — e.g. when notifying about a major bump v1 → v2, the "About:" line
+     * reflects the v2 description, even if the v1 local copy on disk is
+     * stale or worded differently.
+     */
+    skillDescriptions = new Map();
     constructor(options) {
         this.options = options;
         this.store = new SkillsManagerStateStore(options.stateDir, options.config.skillsDir, options.logger);
         this.snapshot = this.buildSnapshot("disabled", "not-started");
     }
-    /** Load persisted state, bootstrap missing skills, and schedule the first poll. */
+    /**
+     * Load persisted state and bootstrap missing skills. Does **not** schedule
+     * a poll loop — skills-manager runs off the auto-update coordinator's
+     * `onTickComplete` hook (see `src/index.ts`), which invokes
+     * {@link runTickOnce} on whatever cadence auto-update is configured with.
+     *
+     * Calling `start()` is still required even in the externally-scheduled
+     * mode so bootstrap, state load, and the "ready" snapshot all happen
+     * before the first external tick fires.
+     */
     async start() {
         this.runToken += 1;
         this.stopped = false;
@@ -45,7 +99,7 @@ export class SkillsUpdateCoordinator {
             logger.info("[senpi-skills-manager] disabled by config");
             return;
         }
-        logger.info(`[senpi-skills-manager] starting | skillsDir=${config.skillsDir} pollInterval=${config.pollIntervalMinutes}m skills=${config.skills.join(",") || "(discover)"}`);
+        logger.info(`[senpi-skills-manager] starting | skillsDir=${config.skillsDir.join(",")} skills=${config.skills.join(",") || "(discover)"} cadence=external (driven by auto-update)`);
         this.state = await this.store.load();
         const bootstrapFn = this.options.deps?.bootstrapSkillsIfNeeded ?? bootstrapSkillsIfNeeded;
         try {
@@ -55,23 +109,21 @@ export class SkillsUpdateCoordinator {
             logger.warn(`[senpi-skills-manager] bootstrap error (non-fatal): ${formatErr(err)}`);
         }
         this.snapshot = this.buildSnapshot("healthy", "started");
-        // First tick fires after 1 s (Math.max(1_000, 0) floor in scheduleNext)
-        this.scheduleNext(0, this.runToken);
     }
     /**
-     * Cancel the next scheduled poll, prevent in-flight ticks from rescheduling,
-     * and wait for any currently-executing tick or manual RPC to finish so the
-     * caller can rely on no async work still touching state after `stop()`
-     * resolves. Without this drain, a caller `await coordinator.stop()` could
-     * proceed to e.g. delete the state dir while a tick mid-write fires.
+     * Stop the coordinator: prevent any new ticks from being processed, and
+     * wait for any in-flight tick or manual RPC to finish so the caller can
+     * rely on no async work still touching state after `stop()` resolves.
+     *
+     * Since scheduling is now external (auto-update's `onTickComplete` hook),
+     * there's no internal timer to cancel — `stop()` just flips the `stopped`
+     * flag (which `runTickOnce` checks) and drains the serialised operation
+     * queue. The auto-update hook itself becomes a no-op for stopped
+     * coordinators since `runTickOnce` returns early.
      */
     async stop() {
         this.runToken += 1;
         this.stopped = true;
-        if (this.timer) {
-            clearTimeout(this.timer);
-            this.timer = null;
-        }
         const inFlight = this.operationChain;
         this.options.logger.info("[senpi-skills-manager] stop requested — draining in-flight operations");
         // operationChain never rejects (runSerialized catches via try/finally before
@@ -79,6 +131,47 @@ export class SkillsUpdateCoordinator {
         await inFlight;
         this.options.logger.info("[senpi-skills-manager] stopped");
     }
+    /**
+     * Public one-shot tick entry point. Called externally on whatever cadence
+     * the host wires up — currently from the auto-update coordinator's
+     * `onTickComplete` hook in `src/index.ts`, which fires after each
+     * auto-update version check completes (success or failure).
+     *
+     * Replaces the previous internal `tick()` + `scheduleNext()` pair: the
+     * coordinator no longer owns a timer of its own. Manual RPCs
+     * (`senpi.skills.update`, `senpi.skills.updateAll`) remain independent of
+     * this path.
+     *
+     * Returns early as a no-op when:
+     * - The coordinator has been stopped (e.g. plugin teardown).
+     * - The runToken has rolled (e.g. a stop/start cycle invalidated this call).
+     * - The coordinator was disabled at start time (config.enabled === false).
+     *
+     * Tick errors are logged + recorded on the snapshot but never thrown —
+     * the caller (auto-update) must not have its own scheduling disturbed by
+     * a transient skills-manager failure.
+     */
+    async runTickOnce() {
+        const token = this.runToken;
+        if (this.stopped || !this.options.config.enabled)
+            return;
+        await this.runSerialized("tick", async () => {
+            if (this.stopped || token !== this.runToken)
+                return;
+            this.options.logger.info("[senpi-skills-manager] tick started (external trigger)");
+            try {
+                await this.runTick();
+                await this.persistState();
+                this.snapshot = this.buildSnapshot("healthy", "tick-complete");
+            }
+            catch (err) {
+                this.options.logger.warn(`[senpi-skills-manager] tick error: ${formatErr(err)}`);
+                this.snapshot = this.buildSnapshot("degraded", "tick-error", formatErr(err));
+                // No internal backoff — the next external tick (from auto-update's
+                // own poll loop / backoff) will retry on its own cadence.
+            }
+        });
+    }
     /** Return the latest point-in-time snapshot for gateway RPCs. */
     getSnapshot() {
         return this.snapshot;
@@ -96,7 +189,10 @@ export class SkillsUpdateCoordinator {
      * @throws On network or install error so the gateway RPC can return ok=false.
      */
     async updateSkill(skillName) {
+        const token = this.runToken;
+        this.assertManualOperationAllowed("updateSkill");
         return this.runSerialized("updateSkill", async () => {
+            this.assertManualOperationAllowed("updateSkill", token);
             const { logger } = this.options;
             logger.info(`[senpi-skills-manager] updateSkill invoked | skill=${skillName}`);
             const checkVersionFn = this.resolveCheckFn();
@@ -119,8 +215,11 @@ export class SkillsUpdateCoordinator {
             }
             // Record the remote version we just learned so the snapshot's latestVersion
             // field reflects it on the next getSnapshot() call — even when no install
-            // happens (skip paths below).
+            // happens (skip paths below). Local description is cached alongside so
+            // notifications (sendUpdateSummary / handleMajorAvailable) can include it.
             this.latestVersions.set(skillName, versionInfo.remoteVersion);
+            this.previousVersions.set(skillName, versionInfo.localVersion);
+            this.skillDescriptions.set(skillName, versionInfo.remoteDescription ?? null);
             // Mirror runTick: every skill whose version we just checked gets its
             // `lastCheckedAt` updated (and `installedVersion` refreshed from the local
             // read) regardless of whether it proceeds to install. Without this, skills
@@ -177,7 +276,10 @@ export class SkillsUpdateCoordinator {
      * this mirrors the tick path's batching instead.
      */
     async updateAll() {
+        const token = this.runToken;
+        this.assertManualOperationAllowed("updateAll");
         return this.runSerialized("updateAll", async () => {
+            this.assertManualOperationAllowed("updateAll", token);
             const { logger, config } = this.options;
             logger.info("[senpi-skills-manager] updateAll invoked");
             const skillNames = await this.resolveSkillNames();
@@ -191,6 +293,8 @@ export class SkillsUpdateCoordinator {
             const versionChecks = await Promise.allSettled(skillNames.map(async (skillName) => {
                 const versionInfo = await checkVersionFn(config.skillsDir, skillName, SKILLS_RAW_BASE_URL, logger);
                 this.latestVersions.set(skillName, versionInfo.remoteVersion);
+                this.previousVersions.set(skillName, versionInfo.localVersion);
+                this.skillDescriptions.set(skillName, versionInfo.remoteDescription ?? null);
                 return { name: skillName, ...versionInfo };
             }));
             const results = [];
@@ -284,41 +388,6 @@ export class SkillsUpdateCoordinator {
             return results;
         });
     }
-    // ── Private scheduling ─────────────────────────────────────────────────────
-    scheduleNext(delayMs, token) {
-        if (this.stopped || token !== this.runToken)
-            return;
-        if (this.timer)
-            clearTimeout(this.timer);
-        const waitMs = Math.max(1_000, delayMs);
-        const nextCheckAt = new Date(Date.now() + waitMs).toISOString();
-        this.snapshot = { ...this.snapshot, nextCheckAt };
-        this.timer = setTimeout(() => {
-            void this.tick(token);
-        }, waitMs);
-    }
-    async tick(token) {
-        if (this.stopped || token !== this.runToken)
-            return;
-        await this.runSerialized("tick", async () => {
-            if (this.stopped || token !== this.runToken)
-                return;
-            this.options.logger.info("[senpi-skills-manager] tick started");
-            try {
-                await this.runTick();
-                await this.persistState();
-                this.snapshot = this.buildSnapshot("healthy", "tick-complete");
-                const nextDelayMs = this.options.config.pollIntervalMinutes * 60_000;
-                this.scheduleNext(nextDelayMs, token);
-            }
-            catch (err) {
-                this.options.logger.warn(`[senpi-skills-manager] tick error: ${formatErr(err)}`);
-                this.snapshot = this.buildSnapshot("degraded", "tick-error", formatErr(err));
-                // 5-minute backoff on full-tick failure (e.g. network completely down)
-                this.scheduleNext(5 * 60_000, token);
-            }
-        });
-    }
     /**
      * Run coordinator work in a global critical section so periodic ticks and
      * manual RPC updates never interleave at await points.
@@ -342,6 +411,23 @@ export class SkillsUpdateCoordinator {
             releaseQueue?.();
         }
     }
+    /**
+     * Manual gateway RPCs (`updateSkill`, `updateAll`) are only valid while the
+     * coordinator is actively running and enabled. This prevents pre-start calls
+     * (e.g. when SENPI_RUNTIME_API_DISABLED=true skipped start()) from persisting
+     * the constructor-default empty state over a valid on-disk state file.
+     */
+    assertManualOperationAllowed(operationName, token = null) {
+        if (!this.options.config.enabled) {
+            throw new SkillsCoordinatorUnavailableError(`[senpi-skills-manager] ${operationName} rejected: skills manager is disabled`);
+        }
+        if (this.stopped) {
+            throw new SkillsCoordinatorUnavailableError(`[senpi-skills-manager] ${operationName} rejected: coordinator is not running`);
+        }
+        if (token !== null && token !== this.runToken) {
+            throw new SkillsCoordinatorUnavailableError(`[senpi-skills-manager] ${operationName} rejected: coordinator lifecycle changed`);
+        }
+    }
     /**
      * Core tick logic: resolve skill names, check versions in parallel, apply
      * policy per skill, then run a single clone for all skills needing update.
@@ -359,6 +445,8 @@ export class SkillsUpdateCoordinator {
         const versionChecks = await Promise.allSettled(skillNames.map(async (skillName) => {
             const versionInfo = await checkVersionFn(config.skillsDir, skillName, SKILLS_RAW_BASE_URL, logger);
             this.latestVersions.set(skillName, versionInfo.remoteVersion);
+            this.previousVersions.set(skillName, versionInfo.localVersion);
+            this.skillDescriptions.set(skillName, versionInfo.remoteDescription ?? null);
             return { name: skillName, ...versionInfo };
         }));
         const skillsToInstall = [];
@@ -484,7 +572,10 @@ export class SkillsUpdateCoordinator {
         try {
             for (const skillName of skillNames) {
                 try {
-                    await installSkill(cloneDir, skillName, config.skillsDir, logger);
+                    // Writes always target the *primary* dir (first entry in the
+                    // search path). Secondary dirs are read-only mirrors — we'd never
+                    // overwrite them on a tick or manual update.
+                    await installSkill(cloneDir, skillName, config.skillsDir[0], logger);
                     const newVersion = this.latestVersions.get(skillName) ?? null;
                     outcomes.set(skillName, { version: newVersion });
                     logger.info(`[senpi-skills-manager] cloneAndInstallMany — installed | skill=${skillName} version=${newVersion ?? "unknown"}`);
@@ -612,6 +703,58 @@ export class SkillsUpdateCoordinator {
         logger.info(`[senpi-skills-manager] applyUpdate complete | skill=${skillName} version=${installedVersion ?? "unknown"}`);
         return installedVersion;
     }
+    /**
+     * Format the per-skill nested-bullet block used in both notification
+     * shapes. Renders the structure suggested in PR #78 review feedback:
+     *
+     *   **skill-name**
+     *      • v1.0.0 → v2.0.0       (or "v1.0.0 (install failed)" when failed)
+     *      • description: …         (omitted when no remote description)
+     *      • error: …               (only on failure, replaces the description)
+     *
+     * **Why markdown, not HTML?**
+     * Openclaw's Telegram channel (`src/telegram/send.ts:sendMessageTelegram`)
+     * pipes outbound text through `renderTelegramHtmlText`, which defaults
+     * `textMode` to `"markdown"` — i.e. it expects the source to be markdown
+     * and runs `markdownToTelegramHtml` over it before handing the converted
+     * HTML to the Bot API with `parse_mode: "HTML"`. The `message` tool
+     * (which is what this coordinator's `notify` callback ultimately hits via
+     * `/tools/invoke`) does not expose `textMode`, so HTML written by us is
+     * treated as literal characters by the markdown step and rendered as
+     * visible `<b>` text in the chat (the actual production bug this docstring
+     * fixes — confirmed against a live notification screenshot).
+     *
+     * Using markdown source (`**bold**`, backticks) instead means the channel's
+     * markdown→HTML converter produces the correct `<b>` / `<code>` HTML
+     * payload and Telegram renders the formatting properly.
+     *
+     * @param skillName Skill identifier (rendered bold via `**name**`).
+     * @param toVersion Resolved upgraded-to version. `null` for failure rows
+     *                  where no install completed; renders as
+     *                  "vPREV (install failed)".
+     * @param errorReason Optional failure reason. When provided, replaces
+     *                    the description line with `error: …`.
+     */
+    formatSkillBlock(skillName, toVersion, errorReason = null) {
+        const prev = this.previousVersions.get(skillName) ?? null;
+        const versionLine = errorReason !== null
+            ? `   • ${prev !== null ? `v${prev} ` : ""}(install failed)`
+            : `   • ${prev !== null ? `v${prev} → ` : ""}${toVersion !== null ? `v${toVersion}` : "(unknown)"}`;
+        const description = this.skillDescriptions.get(skillName) ?? null;
+        const trailingLine = errorReason !== null
+            ? `   • error: ${errorReason}`
+            : description
+                ? `   • description: ${description}`
+                : null;
+        // Skill name line: bold only, no leading bullet — the bold acts as the
+        // visual anchor for the block, and the nested bullets below already
+        // convey "these belong to this skill". A leading `•` on the heading
+        // looked redundant in production.
+        const lines = [`**${skillName}**`, versionLine];
+        if (trailingLine)
+            lines.push(trailingLine);
+        return lines.join("\n");
+    }
     /**
      * Send a one-way Telegram notification for a pending major update, deduped
      * by version.
@@ -627,9 +770,19 @@ export class SkillsUpdateCoordinator {
             return;
         }
         try {
-            await this.options.notify(`Senpi skill "${skillName}" has a major update available: v${remoteVersion}.\n` +
+            const block = this.formatSkillBlock(skillName, remoteVersion);
+            await this.options.notify(`Senpi skills update — major available:\n\n` +
+                `${block}\n\n` +
                 `Major updates are not applied automatically.\n` +
-                `Run: openclaw senpi skills update ${skillName}`);
+                // Inline code via markdown backticks — the channel's markdown→HTML
+                // step converts these to `<code>` so the install command renders
+                // in monospace. Skill names in the senpi-skills repo are
+                // kebab-case identifiers (no backtick chars), so no escaping is
+                // needed here in practice.
+                `Run: \`openclaw senpi skills update ${skillName}\`\n\n` +
+                // Yes/no CTA — operator-friendly framing, intentionally short.
+                // Replies are routed to the agent layer, not to this coordinator.
+                `Want help with the upgrade? Reply yes or no.`);
             skillState.lastNotifiedMajorVersion = remoteVersion;
             this.options.logger.info(`[senpi-skills-manager] handleMajorAvailable — major-update notification sent | skill=${skillName} version=${remoteVersion}`);
         }
@@ -644,21 +797,39 @@ export class SkillsUpdateCoordinator {
      * so the user can tell which skills still need attention. Sections with no
      * entries are omitted. If neither section has entries, no notification is
      * sent.
+     *
+     * Format (markdown source — see `formatSkillBlock` for why markdown
+     * rather than HTML):
+     *
+     *   Senpi skills update:
+     *
+     *   Updated:
+     *
+     *   **skill-a**
+     *      • v1.0.0 → v1.0.1
+     *      • description: …
+     *
+     *   **skill-b**
+     *      • v2.0.0 → v2.0.1
+     *      • description: …
+     *
+     *   Failed to update:
+     *
+     *   **skill-c**
+     *      • v1.0.0 (install failed)
+     *      • error: clone failed: …
      */
     async sendUpdateSummary(succeededSkillNames, failedSkills) {
         if (succeededSkillNames.length === 0 && failedSkills.length === 0)
             return;
         const sections = [];
         if (succeededSkillNames.length > 0) {
-            const successLines = succeededSkillNames.map((name) => {
-                const latestVersion = this.latestVersions.get(name);
-                return `  • ${name}${latestVersion ? ` -> v${latestVersion}` : ""}`;
-            });
-            sections.push(`Updated:\n${successLines.join("\n")}`);
+            const blocks = succeededSkillNames.map((name) => this.formatSkillBlock(name, this.latestVersions.get(name) ?? null));
+            sections.push(`Updated:\n\n${blocks.join("\n\n")}`);
         }
         if (failedSkills.length > 0) {
-            const failureLines = failedSkills.map(({ name, reason }) => `  • ${name}: ${reason}`);
-            sections.push(`Failed to update:\n${failureLines.join("\n")}`);
+            const blocks = failedSkills.map(({ name, reason }) => this.formatSkillBlock(name, null, reason));
+            sections.push(`Failed to update:\n\n${blocks.join("\n\n")}`);
         }
         try {
             await this.options.notify(`Senpi skills update:\n\n${sections.join("\n\n")}`);
@@ -679,31 +850,50 @@ export class SkillsUpdateCoordinator {
      */
     resolveCheckFn() {
         return (this.options.deps?.checkSkillVersion ??
-            ((skillsDir, skillName, rawBaseUrl, logger) => checkSkillVersion(skillsDir, skillName, rawBaseUrl, undefined, logger)));
+            ((skillsDirs, skillName, rawBaseUrl, logger) => checkSkillVersion(skillsDirs, skillName, rawBaseUrl, undefined, logger)));
     }
     /**
      * Resolve the list of skill names to check this tick.
      * Uses `config.skills` when non-empty; otherwise discovers all immediate
-     * subdirectories of `skillsDir`.
+     * subdirectories across every dir in the `skillsDir` search path,
+     * deduped by name and sorted.
+     *
+     * Per-dir read errors (other than ENOENT) are logged but do not abort the
+     * scan — a misconfigured secondary dir cannot mask skills present in the
+     * primary.
      */
     async resolveSkillNames() {
         if (this.options.config.skills.length > 0) {
             return this.options.config.skills;
         }
-        try {
-            const entries = await readdir(this.options.config.skillsDir, { withFileTypes: true });
-            return entries
-                .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
-                .map((entry) => entry.name)
-                .sort();
+        const seen = new Set();
+        let anySucceeded = false;
+        for (const dir of this.options.config.skillsDir) {
+            try {
+                const entries = await readdir(dir, { withFileTypes: true });
+                anySucceeded = true;
+                for (const entry of entries) {
+                    if (entry.isDirectory() && !entry.name.startsWith(".")) {
+                        seen.add(entry.name);
+                    }
+                }
+            }
+            catch (err) {
+                // ENOENT for a dir that hasn't been created yet is benign — only
+                // log the noisier failure modes so operators can diagnose them.
+                if (err.code !== "ENOENT") {
+                    this.options.logger.warn(`[senpi-skills-manager] resolveSkillNames — failed to read skillsDir, continuing | dir=${dir} err=${formatErr(err)}`);
+                }
+            }
         }
-        catch (err) {
-            // Missing / unreadable skillsDir — log so the operator can diagnose
-            // (previously failed silently, which made "no skills checked" indistinguishable
-            // from "skillsDir configured wrong" in the logs).
-            this.options.logger.warn(`[senpi-skills-manager] resolveSkillNames — failed to read skillsDir | dir=${this.options.config.skillsDir} err=${formatErr(err)}`);
-            return [];
+        if (!anySucceeded && seen.size === 0) {
+            // Every configured dir failed to read (or none exist). Previously the
+            // single-dir version warned in this case; preserve that signal so
+            // "no skills checked" is still distinguishable from "skillsDir
+            // configured wrong" in the logs.
+            this.options.logger.warn(`[senpi-skills-manager] resolveSkillNames — no readable skills dirs | dirs=${this.options.config.skillsDir.join(",")}`);
         }
+        return Array.from(seen).sort();
     }
     /**
      * Build the point-in-time snapshot returned by {@link getSnapshot}.
@@ -718,9 +908,6 @@ export class SkillsUpdateCoordinator {
      *   3. Caller-supplied lifecycle metadata — `health`, `lastAction`,
      *      `lastError` describing the most recent tick / manual RPC outcome.
      *
-     * `nextCheckAt` is preserved from the previous snapshot so callers always
-     * see a valid ETA even on transient rebuilds (e.g. mid-tick error paths).
-     *
      * This is called at every state-mutating boundary (start, tick complete,
      * tick error, manual update complete, manual update skipped, manual update
      * clone failed, stop/disable) so the next RPC response reflects the latest
@@ -737,12 +924,14 @@ export class SkillsUpdateCoordinator {
         }));
         return {
             enabled: this.options.config.enabled,
-            skillsDir: this.options.config.skillsDir,
+            // Snapshot is a serializable view consumed by gateway RPCs and the CLI;
+            // hand callers a defensive copy so their downstream mutations (e.g.
+            // sorting, push for display) can't poison the live config.
+            skillsDir: [...this.options.config.skillsDir],
             health,
             lastAction,
             lastError,
             skills: skillSnapshots,
-            nextCheckAt: this.snapshot?.nextCheckAt ?? null,
         };
     }
     async persistState() {
@@ -754,4 +943,18 @@ export class SkillsUpdateCoordinator {
         }
     }
 }
+// `escapeHtml` was removed alongside the switch from HTML to markdown
+// notification source — see `formatSkillBlock` for why. The openclaw
+// Telegram channel runs `markdownToTelegramHtml` over our text and
+// handles HTML escaping itself on the converter's output. Pre-escaping
+// at this layer would double-escape (e.g. `&amp;` becomes `&amp;amp;`)
+// and corrupt the rendered output.
+//
+// Markdown-special characters (`*`, `_`, `[`, `]`, backtick) in dynamic
+// values aren't escaped either — descriptions that legitimately contain
+// these would author them as markdown intentionally; skill names in the
+// senpi-skills repo are kebab-case identifiers; error messages from
+// `formatErr` are typically prose. If a future skill description ever
+// breaks the rendering, the fix is to author the SKILL.md frontmatter
+// using proper markdown.
 //# sourceMappingURL=coordinator.js.map