@senpi/runtime 1.1.0-dev.runtime-phase-2.20260512102629 → 1.1.0-dev.runtime-phase-2.20260514134437

package/dist/skills-manager/coordinator.js

@@ -0,0 +1,931 @@
+/**
+ * Central lifecycle manager for Senpi skills auto-update.
+ *
+ * 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.
+ *
+ * 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";
+import { cloneSkillsRepo } from "./fetcher.js";
+import { SkillsManagerStateStore } from "./state-store.js";
+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 SkillsUpdateCoordinator {
+    options;
+    store;
+    operationChain = Promise.resolve();
+    stopped = true;
+    runToken = 0;
+    state = createDefaultSkillsManagerState();
+    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 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;
+        const { logger, config } = this.options;
+        if (!config.enabled) {
+            this.stopped = true;
+            this.snapshot = this.buildSnapshot("disabled", "skills-manager-disabled");
+            logger.info("[senpi-skills-manager] disabled by config");
+            return;
+        }
+        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 {
+            await bootstrapFn(config, logger);
+        }
+        catch (err) {
+            logger.warn(`[senpi-skills-manager] bootstrap error (non-fatal): ${formatErr(err)}`);
+        }
+        this.snapshot = this.buildSnapshot("healthy", "started");
+    }
+    /**
+     * 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;
+        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
+        // releasing the queue), so this await always resolves.
+        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;
+    }
+    // ── Manual trigger methods (called by gateway RPCs) ────────────────────────
+    /**
+     * Force an immediate version check and apply for one named skill.
+     *
+     * Skips installation when the update kind is `"none"` (already current) or
+     * `"unknown"` (remote version could not be classified — e.g. the fetch
+     * failed or the remote `version` field is missing). Falling through on
+     * `"unknown"` would write `installedVersion: null` and lose tracking, so we
+     * treat it the same as `"none"` and return `updated: false`.
+     *
+     * @throws On network or install error so the gateway RPC can return ok=false.
+     */
+    async updateSkill(skillName) {
+        return this.runSerialized("updateSkill", async () => {
+            const { logger } = this.options;
+            logger.info(`[senpi-skills-manager] updateSkill invoked | skill=${skillName}`);
+            const checkVersionFn = this.resolveCheckFn();
+            let versionInfo;
+            try {
+                versionInfo = await checkVersionFn(this.options.config.skillsDir, skillName, SKILLS_RAW_BASE_URL, logger);
+            }
+            catch (err) {
+                // Version check threw (5xx, network error, timeout, body-parse failure
+                // — all now propagate from checkSkillVersion after the version-manager
+                // re-throw fix). Mirror the tick/updateAll paths and record the
+                // failure on this skill's state before rethrowing so the gateway RPC
+                // still returns ok=false to the caller.
+                const errorMessage = formatErr(err);
+                logger.warn(`[senpi-skills-manager] updateSkill — version check failed | skill=${skillName} err=${errorMessage}`);
+                this.recordCheckFailure(skillName, errorMessage);
+                await this.persistState();
+                this.snapshot = this.buildSnapshot(this.snapshot.health, "manual-update-failed", errorMessage);
+                throw err;
+            }
+            // 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). 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
+            // updated only via manual RPCs would show `lastCheckedAt: null` in the
+            // status snapshot until the next automatic tick fires (up to 60 min away).
+            const checkedState = this.state.skills[skillName] ?? createDefaultSkillState(skillName);
+            checkedState.lastCheckedAt = new Date().toISOString();
+            if (versionInfo.localVersion !== null) {
+                checkedState.installedVersion = versionInfo.localVersion;
+            }
+            // NOTE: do NOT clear failure state here. See runTick for rationale —
+            // a successful version check is not proof of operational health. Failure
+            // counters are only reset by `recordSuccess` after a successful install.
+            this.state.skills[skillName] = checkedState;
+            logger.info(`[senpi-skills-manager] updateSkill check result | skill=${skillName} local=${versionInfo.localVersion ?? "none"} remote=${versionInfo.remoteVersion ?? "unknown"} kind=${versionInfo.updateKind}`);
+            if (versionInfo.updateKind === "none" || versionInfo.updateKind === "unknown") {
+                logger.info(`[senpi-skills-manager] updateSkill skipped | skill=${skillName} reason=${versionInfo.updateKind}`);
+                // Persist so the `lastCheckedAt` timestamp survives a gateway restart
+                // even on skip paths (otherwise the next load() would see a stale null).
+                await this.persistState();
+                // Refresh snapshot so the status RPC doesn't return pre-check data.
+                this.snapshot = this.buildSnapshot(this.snapshot.health, "manual-update-skipped");
+                return { updated: false, version: versionInfo.localVersion };
+            }
+            try {
+                const installedVersion = await this.applyUpdate(skillName, versionInfo.remoteVersion);
+                logger.info(`[senpi-skills-manager] updateSkill complete | skill=${skillName} version=${installedVersion ?? "unknown"}`);
+                // Refresh snapshot so the status RPC reflects the freshly-installed version
+                // immediately, rather than waiting for the next poll tick (up to 60 min).
+                this.snapshot = this.buildSnapshot("healthy", "manual-update-complete");
+                return { updated: true, version: installedVersion };
+            }
+            catch (err) {
+                const errorMessage = formatErr(err);
+                // applyUpdate has already recorded per-skill failure state (consecutiveFailures,
+                // lastFailureAt, lastFailureReason) and persisted before throwing. We repeat
+                // persistState() here as a defensive backstop in case applyUpdate's internal
+                // persist silently failed, and also so the updated lastCheckedAt we set
+                // earlier in this method is guaranteed to reach disk on the error path.
+                await this.persistState();
+                this.snapshot = this.buildSnapshot(this.snapshot.health, "manual-update-failed", errorMessage);
+                throw err;
+            }
+        });
+    }
+    /**
+     * Force an immediate version check and apply for all discovered/configured skills.
+     * Individual failures do not abort the remaining skills.
+     *
+     * All skills share a single `git clone` — the repo is cloned once, every
+     * skill that needs an update is installed from that same checkout, then the
+     * checkout is cleaned up. A previous version called `updateSkill` in a loop,
+     * which caused one full clone per skill (N redundant clones for N skills);
+     * this mirrors the tick path's batching instead.
+     */
+    async updateAll() {
+        return this.runSerialized("updateAll", async () => {
+            const { logger, config } = this.options;
+            logger.info("[senpi-skills-manager] updateAll invoked");
+            const skillNames = await this.resolveSkillNames();
+            if (skillNames.length === 0) {
+                logger.info("[senpi-skills-manager] updateAll — no skills to check");
+                return [];
+            }
+            logger.info(`[senpi-skills-manager] updateAll — checking versions | skills=${skillNames.join(",")}`);
+            const checkVersionFn = this.resolveCheckFn();
+            // Check every skill's version in parallel — one rejection does not abort others.
+            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 = [];
+            const skillsToInstall = [];
+            for (let index = 0; index < versionChecks.length; index++) {
+                const skillName = skillNames[index];
+                const checkResult = versionChecks[index];
+                if (checkResult.status === "rejected") {
+                    const errorMessage = formatErr(checkResult.reason);
+                    logger.warn(`[senpi-skills-manager] updateAll — version check failed | skill=${skillName} err=${errorMessage}`);
+                    // Mirror runTick: rejected checks update `lastCheckedAt`, bump the
+                    // failure counter, and capture the reason. Otherwise a manual
+                    // updateAll run could swallow a per-skill check failure entirely —
+                    // the caller sees `error` in the returned array, but the snapshot
+                    // and persisted state never reflect it.
+                    this.recordCheckFailure(skillName, errorMessage);
+                    results.push({ name: skillName, updated: false, version: null, error: errorMessage });
+                    continue;
+                }
+                const { localVersion, updateKind } = checkResult.value;
+                // Mirror runTick: every successfully-checked skill gets `lastCheckedAt`
+                // updated and `installedVersion` refreshed from the local read, whether
+                // or not it proceeds to install. Otherwise skills touched only by
+                // manual RPCs would show `lastCheckedAt: null` in the status snapshot
+                // until the next automatic tick.
+                const skillState = this.state.skills[skillName] ?? createDefaultSkillState(skillName);
+                skillState.lastCheckedAt = new Date().toISOString();
+                if (localVersion !== null)
+                    skillState.installedVersion = localVersion;
+                // NOTE: do NOT clear failure state here. See runTick for rationale —
+                // a successful version check is not proof of operational health.
+                // Failure counters are only reset by `recordSuccess` after a
+                // successful install.
+                this.state.skills[skillName] = skillState;
+                // Same skip policy as updateSkill: "none" and "unknown" leave the skill alone.
+                if (updateKind === "none" || updateKind === "unknown") {
+                    logger.info(`[senpi-skills-manager] updateAll — skipping | skill=${skillName} reason=${updateKind}`);
+                    results.push({ name: skillName, updated: false, version: localVersion });
+                    continue;
+                }
+                skillsToInstall.push(skillName);
+            }
+            if (skillsToInstall.length === 0) {
+                logger.info(`[senpi-skills-manager] updateAll complete — no installs needed | checked=${skillNames.length}`);
+                // Persist so the `lastCheckedAt` timestamps we just set on every
+                // successfully-checked skill survive a gateway restart.
+                await this.persistState();
+                // No installs, but we may have learned new remote versions from the
+                // parallel checks above — refresh the snapshot so getSnapshot() doesn't
+                // return pre-check data.
+                this.snapshot = this.buildSnapshot(this.snapshot.health, "manual-update-skipped");
+                return results;
+            }
+            logger.info(`[senpi-skills-manager] updateAll — installing | count=${skillsToInstall.length} skills=${skillsToInstall.join(",")}`);
+            // Single clone, install many.
+            let installOutcomes;
+            try {
+                installOutcomes = await this.cloneAndInstallMany(skillsToInstall);
+            }
+            catch (err) {
+                const errorMessage = `clone failed: ${formatErr(err)}`;
+                logger.warn(`[senpi-skills-manager] updateAll — ${errorMessage}`);
+                for (const skillName of skillsToInstall) {
+                    results.push({ name: skillName, updated: false, version: null, error: errorMessage });
+                }
+                // Clone failure doesn't produce install outcomes per-skill, but every
+                // checked skill already had `lastCheckedAt` updated in-memory above.
+                // Persist so those timestamps survive a gateway restart.
+                await this.persistState();
+                this.snapshot = this.buildSnapshot(this.snapshot.health, "manual-update-clone-failed");
+                return results;
+            }
+            let successCount = 0;
+            let failureCount = 0;
+            for (const skillName of skillsToInstall) {
+                const outcome = this.processInstallOutcome(skillName, installOutcomes);
+                if (outcome.success) {
+                    results.push({ name: skillName, updated: true, version: outcome.version });
+                    successCount += 1;
+                }
+                else {
+                    results.push({ name: skillName, updated: false, version: null, error: outcome.error });
+                    failureCount += 1;
+                }
+            }
+            await this.persistState();
+            logger.info(`[senpi-skills-manager] updateAll complete | installed=${successCount} failed=${failureCount} checked=${skillNames.length}`);
+            // Refresh snapshot so the status RPC reflects the freshly-installed
+            // versions immediately instead of waiting for the next poll tick.
+            this.snapshot = this.buildSnapshot("healthy", "manual-update-complete");
+            return results;
+        });
+    }
+    /**
+     * Run coordinator work in a global critical section so periodic ticks and
+     * manual RPC updates never interleave at await points.
+     */
+    async runSerialized(operationName, operation) {
+        const queued = this.operationChain;
+        let releaseQueue;
+        this.operationChain = new Promise((resolve) => {
+            releaseQueue = resolve;
+        });
+        await queued;
+        this.options.logger.info(`[senpi-skills-manager] runSerialized — entering critical section | op=${operationName}`);
+        try {
+            return await operation();
+        }
+        finally {
+            this.options.logger.info(`[senpi-skills-manager] runSerialized — leaving critical section | op=${operationName}`);
+            // Release the queue so the next caller can enter. We always release even
+            // if `operation` threw — otherwise a thrown error would deadlock every
+            // subsequent call forever.
+            releaseQueue?.();
+        }
+    }
+    /**
+     * Core tick logic: resolve skill names, check versions in parallel, apply
+     * policy per skill, then run a single clone for all skills needing update.
+     */
+    async runTick() {
+        const { logger, config } = this.options;
+        const skillNames = await this.resolveSkillNames();
+        if (skillNames.length === 0) {
+            logger.info("[senpi-skills-manager] tick — no skills to check");
+            return;
+        }
+        logger.info(`[senpi-skills-manager] tick — checking versions | count=${skillNames.length} skills=${skillNames.join(",")}`);
+        const checkVersionFn = this.resolveCheckFn();
+        // Check all versions in parallel — per-skill errors are captured, not thrown.
+        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 = [];
+        let majorPendingCount = 0;
+        let upToDateCount = 0;
+        for (let index = 0; index < versionChecks.length; index++) {
+            const skillName = skillNames[index];
+            const checkResult = versionChecks[index];
+            if (checkResult.status === "rejected") {
+                const errorMessage = formatErr(checkResult.reason);
+                this.recordCheckFailure(skillName, errorMessage);
+                logger.warn(`[senpi-skills-manager] tick — version check failed | skill=${skillName} err=${errorMessage}`);
+                continue;
+            }
+            const { localVersion, remoteVersion, updateKind } = checkResult.value;
+            const skillState = this.state.skills[skillName] ?? createDefaultSkillState(skillName);
+            skillState.lastCheckedAt = new Date().toISOString();
+            if (localVersion !== null)
+                skillState.installedVersion = localVersion;
+            // NOTE: do NOT clear failure state here. A successful version check does
+            // not prove the skill is operationally healthy — it only proves the raw
+            // SKILL.md is reachable. Install failures (clone, copy, swap) reflect
+            // real operational issues; clearing them on a check-success would wipe
+            // that history mid-tick and prevent consecutiveFailures from accumulating
+            // across multiple failed install attempts. Failure state is cleared only
+            // by `recordSuccess` (called after a successful install).
+            logger.info(`[senpi-skills-manager] tick — skill=${skillName} local=${localVersion ?? "none"} remote=${remoteVersion ?? "unknown"} kind=${updateKind}`);
+            if (updateKind === "none" || updateKind === "unknown") {
+                this.state.skills[skillName] = skillState;
+                upToDateCount += 1;
+                continue;
+            }
+            if (updateKind === "major") {
+                // Major versions are never auto-applied — notify the user and let them decide.
+                await this.handleMajorAvailable(skillState, skillName, remoteVersion);
+                this.state.skills[skillName] = skillState;
+                majorPendingCount += 1;
+                continue;
+            }
+            // patch / minor — queue for install
+            skillsToInstall.push(skillName);
+            this.state.skills[skillName] = skillState;
+        }
+        logger.info(`[senpi-skills-manager] tick — triage | upToDate=${upToDateCount} majorPending=${majorPendingCount} toInstall=${skillsToInstall.length}`);
+        if (skillsToInstall.length === 0)
+            return;
+        await this.applyUpdates(skillsToInstall);
+    }
+    /**
+     * Clone the repo once and install every skill in `skillNames`.
+     * Per-skill errors are recorded in state without aborting the others.
+     * The update summary notification distinguishes successful installs from
+     * failures so the user can see exactly which skills need attention.
+     *
+     * If the clone itself fails we log and return without touching state or
+     * sending a summary — a full-clone failure is almost always a transient
+     * network/git issue that affects every skill equally, so attributing it
+     * per-skill would be misleading. The next tick retries.
+     */
+    async applyUpdates(skillNames) {
+        const { logger } = this.options;
+        logger.info(`[senpi-skills-manager] applyUpdates — batch install starting | count=${skillNames.length} skills=${skillNames.join(",")}`);
+        let installOutcomes;
+        try {
+            installOutcomes = await this.cloneAndInstallMany(skillNames);
+        }
+        catch (err) {
+            logger.warn(`[senpi-skills-manager] applyUpdates — git clone failed, skipping batch: ${formatErr(err)}`);
+            return;
+        }
+        const succeededSkillNames = [];
+        const failedSkills = [];
+        for (const skillName of skillNames) {
+            const outcome = this.processInstallOutcome(skillName, installOutcomes);
+            if (outcome.success) {
+                succeededSkillNames.push(skillName);
+                logger.info(`[senpi-skills-manager] applyUpdates — installed | skill=${skillName} version=${outcome.version ?? "unknown"}`);
+            }
+            else {
+                failedSkills.push({ name: skillName, reason: outcome.error });
+            }
+        }
+        logger.info(`[senpi-skills-manager] applyUpdates complete | installed=${succeededSkillNames.length} failed=${failedSkills.length}`);
+        await this.sendUpdateSummary(succeededSkillNames, failedSkills);
+    }
+    /**
+     * Clone the remote skills repo exactly once and install every skill in
+     * `skillNames` from that single checkout. Returns a per-skill outcome map:
+     * `{ version }` on success or `{ version: null, error }` on install failure.
+     *
+     * Throws only when the clone itself fails — per-skill install failures are
+     * captured in the map so callers can continue processing the rest.
+     *
+     * When `deps.cloneAndInstall` is supplied (unit tests), that injector is
+     * called in place of the real clone+install loop; any names missing from
+     * its returned map are treated as install failures.
+     */
+    async cloneAndInstallMany(skillNames) {
+        const { logger, config } = this.options;
+        const outcomes = new Map();
+        if (skillNames.length === 0)
+            return outcomes;
+        if (this.options.deps?.cloneAndInstall) {
+            // Injected dep for tests — receives skill names + config, returns name→version map.
+            // Names absent from the returned map are treated as failures.
+            logger.info(`[senpi-skills-manager] cloneAndInstallMany — using injected dep | skills=${skillNames.join(",")}`);
+            const versionsByName = await this.options.deps.cloneAndInstall(skillNames, config);
+            for (const skillName of skillNames) {
+                if (versionsByName.has(skillName)) {
+                    outcomes.set(skillName, {
+                        version: versionsByName.get(skillName) ?? this.latestVersions.get(skillName) ?? null,
+                    });
+                }
+                else {
+                    outcomes.set(skillName, { version: null, error: "install failed" });
+                }
+            }
+            return outcomes;
+        }
+        logger.info(`[senpi-skills-manager] cloneAndInstallMany — cloning repo | url=${SKILLS_REPO_URL} timeoutMs=120000`);
+        const { cloneDir, cleanup } = await cloneSkillsRepo(SKILLS_REPO_URL, 120_000, logger);
+        logger.info(`[senpi-skills-manager] cloneAndInstallMany — clone ready, installing | count=${skillNames.length} cloneDir=${cloneDir}`);
+        try {
+            for (const skillName of skillNames) {
+                try {
+                    // 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"}`);
+                }
+                catch (err) {
+                    const errorMessage = formatErr(err);
+                    outcomes.set(skillName, { version: null, error: errorMessage });
+                    logger.warn(`[senpi-skills-manager] cloneAndInstallMany — install failed | skill=${skillName} err=${errorMessage}`);
+                }
+            }
+        }
+        finally {
+            await cleanup();
+            logger.info("[senpi-skills-manager] cloneAndInstallMany — clone cleanup done");
+        }
+        return outcomes;
+    }
+    /**
+     * Record a successful install on in-memory skill state.
+     *
+     * Resets failure tracking — a successful end-to-end install is the only
+     * signal we treat as "operationally healthy." A successful version check
+     * alone is NOT sufficient (and intentionally does not call this), because:
+     *
+     * - The version check only proves the raw SKILL.md is reachable. It does
+     *   not exercise the clone/copy/swap pipeline that actually keeps the skill
+     *   working.
+     * - Clearing failure state on every check-success would wipe install-failure
+     *   history mid-tick: a skill failing to install on every tick would still
+     *   report `consecutiveFailures: 1` (instead of N) because each tick's
+     *   check-success reset would precede the install-failure increment.
+     *
+     * Consequence: a skill that's perpetually up-to-date but had a one-off
+     * failure in the past will retain a non-zero `consecutiveFailures` until
+     * the next install. We accept that trade-off — surfacing a stale failure
+     * counter is preferable to silently wiping real install-failure history.
+     */
+    recordSuccess(skillState, newVersion) {
+        skillState.installedVersion = newVersion;
+        skillState.lastAppliedVersion = newVersion;
+        skillState.consecutiveFailures = 0;
+        skillState.lastFailureAt = null;
+        skillState.lastFailureReason = null;
+    }
+    /**
+     * Record a version-check failure on in-memory skill state.
+     *
+     * Shared by `runTick` and `updateAll` — both need to bump
+     * `consecutiveFailures` and capture the reason when `Promise.allSettled`
+     * surfaces a rejected check. `lastCheckedAt` is updated too so the snapshot
+     * doesn't look like the skill was never polled (it was — the poll failed).
+     */
+    recordCheckFailure(skillName, errorMessage) {
+        const skillState = this.state.skills[skillName] ?? createDefaultSkillState(skillName);
+        const now = new Date().toISOString();
+        skillState.lastCheckedAt = now;
+        skillState.consecutiveFailures += 1;
+        skillState.lastFailureAt = now;
+        skillState.lastFailureReason = errorMessage;
+        this.state.skills[skillName] = skillState;
+    }
+    /**
+     * Apply one install outcome to in-memory skill state and return a compact
+     * success/failure result for the caller's bookkeeping.
+     */
+    processInstallOutcome(skillName, installOutcomes) {
+        const outcome = installOutcomes.get(skillName) ?? { version: null, error: "install result missing" };
+        const skillState = this.state.skills[skillName] ?? createDefaultSkillState(skillName);
+        if (outcome.error) {
+            skillState.consecutiveFailures += 1;
+            skillState.lastFailureAt = new Date().toISOString();
+            skillState.lastFailureReason = outcome.error;
+            this.state.skills[skillName] = skillState;
+            return { success: false, error: outcome.error };
+        }
+        this.recordSuccess(skillState, outcome.version);
+        this.state.skills[skillName] = skillState;
+        return { success: true, version: outcome.version };
+    }
+    /**
+     * Apply a single skill update (used by the manual `updateSkill` RPC path).
+     * Returns the installed version.
+     *
+     * Delegates to {@link cloneAndInstallMany} so the single-skill and batch
+     * paths share one implementation of clone+install. The per-skill install
+     * error is re-thrown here so `updateSkill` can surface it to the RPC
+     * caller via a rejected promise (batch path captures it instead).
+     */
+    async applyUpdate(skillName, remoteVersion) {
+        const { logger } = this.options;
+        logger.info(`[senpi-skills-manager] applyUpdate — starting | skill=${skillName} targetVersion=${remoteVersion ?? "unknown"}`);
+        // Clone can throw (full repo fetch failed). Unlike the batch path — which
+        // intentionally doesn't attribute a shared clone failure to individual
+        // skills — the single-skill path has an unambiguous owner, so we record
+        // the clone failure against this skill's failure counters before
+        // re-throwing to the RPC caller.
+        let installOutcomes;
+        try {
+            installOutcomes = await this.cloneAndInstallMany([skillName]);
+        }
+        catch (err) {
+            const errorMessage = `clone failed: ${formatErr(err)}`;
+            const skillState = this.state.skills[skillName] ?? createDefaultSkillState(skillName);
+            skillState.consecutiveFailures += 1;
+            const now = new Date().toISOString();
+            skillState.lastFailureAt = now;
+            skillState.lastFailureReason = errorMessage;
+            this.state.skills[skillName] = skillState;
+            await this.persistState();
+            logger.warn(`[senpi-skills-manager] applyUpdate — ${errorMessage} | skill=${skillName}`);
+            throw err;
+        }
+        // Delegate outcome bookkeeping (success or install-failure) to the shared
+        // helper so the single-skill path records failure state identically to
+        // the batch path — previously this path threw raw without ever touching
+        // consecutiveFailures / lastFailureAt / lastFailureReason, so manual
+        // updateSkill install failures were silently invisible to the snapshot.
+        const processed = this.processInstallOutcome(skillName, installOutcomes);
+        await this.persistState();
+        if (!processed.success) {
+            logger.warn(`[senpi-skills-manager] applyUpdate — install failed | skill=${skillName} err=${processed.error}`);
+            throw new Error(processed.error);
+        }
+        const installedVersion = processed.version ?? remoteVersion ?? null;
+        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.
+     *
+     * The dedup key (`lastNotifiedMajorVersion`) is only set after the notify
+     * call resolves successfully. If the notification fails (Telegram API down,
+     * transient network error, etc.) the key is left unchanged so the next tick
+     * retries delivery instead of silently suppressing it forever.
+     */
+    async handleMajorAvailable(skillState, skillName, remoteVersion) {
+        if (skillState.lastNotifiedMajorVersion === remoteVersion) {
+            this.options.logger.info(`[senpi-skills-manager] handleMajorAvailable — notification already sent, skipping | skill=${skillName} version=${remoteVersion}`);
+            return;
+        }
+        try {
+            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` +
+                // 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}`);
+        }
+        catch (err) {
+            this.options.logger.warn(`[senpi-skills-manager] failed to send major-update notification for "${skillName}": ${formatErr(err)}`);
+            // Leave dedup key unchanged — retry on next tick.
+        }
+    }
+    /**
+     * Send an aggregated notification summarising the outcome of this tick's
+     * updates. Successful installs and failures are shown in separate sections
+     * 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 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 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")}`);
+            this.options.logger.info(`[senpi-skills-manager] sendUpdateSummary — notification sent | succeeded=${succeededSkillNames.length} failed=${failedSkills.length}`);
+        }
+        catch (err) {
+            this.options.logger.warn(`[senpi-skills-manager] failed to send update summary notification: ${formatErr(err)}`);
+        }
+    }
+    /**
+     * Return the version-check function for this coordinator: either the
+     * injected `deps.checkSkillVersion` (unit tests) or the real
+     * `checkSkillVersion` with the default `fetchImpl`.
+     *
+     * Extracted so the three call sites (`updateSkill`, `updateAll`, `runTick`)
+     * don't repeat the same resolve-and-wrap lambda — a change to the real
+     * `checkSkillVersion` signature now only has to land here.
+     */
+    resolveCheckFn() {
+        return (this.options.deps?.checkSkillVersion ??
+            ((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 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;
+        }
+        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)}`);
+                }
+            }
+        }
+        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}.
+     *
+     * The snapshot is the single serialisable view of the coordinator's state
+     * consumed by gateway RPCs (`senpi.skills.status`) and any health UI. It
+     * fuses three data sources:
+     *   1. Per-skill persisted state (`this.state.skills`) — installed version,
+     *      last check time, consecutive failures, last failure reason.
+     *   2. In-memory `this.latestVersions` map — the most recent remote version
+     *      observed during a version check (may not yet be installed).
+     *   3. Caller-supplied lifecycle metadata — `health`, `lastAction`,
+     *      `lastError` describing the most recent tick / manual RPC outcome.
+     *
+     * 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
+     * state rather than stale pre-action data.
+     */
+    buildSnapshot(health, lastAction, lastError = null) {
+        const skillSnapshots = Object.values(this.state.skills).map((skillState) => ({
+            name: skillState.name,
+            installedVersion: skillState.installedVersion,
+            latestVersion: this.latestVersions.get(skillState.name) ?? null,
+            lastCheckedAt: skillState.lastCheckedAt,
+            consecutiveFailures: skillState.consecutiveFailures,
+            lastFailureReason: skillState.lastFailureReason,
+        }));
+        return {
+            enabled: this.options.config.enabled,
+            // 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,
+        };
+    }
+    async persistState() {
+        try {
+            await this.store.save(this.state);
+        }
+        catch (err) {
+            this.options.logger.warn(`[senpi-skills-manager] failed to persist state: ${formatErr(err)}`);
+        }
+    }
+}
+// `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