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

package/dist/skills-manager/coordinator.js

@@ -0,0 +1,757 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+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;
+    timer = null;
+    operationChain = Promise.resolve();
+    stopped = true;
+    runToken = 0;
+    state = createDefaultSkillsManagerState();
+    snapshot;
+    /** Latest remote version per skill name — populated during ticks. */
+    latestVersions = 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. */
+    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} pollInterval=${config.pollIntervalMinutes}m skills=${config.skills.join(",") || "(discover)"}`);
+        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");
+        // 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.
+     */
+    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
+        // releasing the queue), so this await always resolves.
+        await inFlight;
+        this.options.logger.info("[senpi-skills-manager] stopped");
+    }
+    /** 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).
+            this.latestVersions.set(skillName, versionInfo.remoteVersion);
+            // 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);
+                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;
+        });
+    }
+    // ── 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.
+     */
+    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);
+            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 {
+                    await installSkill(cloneDir, skillName, config.skillsDir, 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;
+    }
+    /**
+     * 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 {
+            await this.options.notify(`Senpi skill "${skillName}" has a major update available: v${remoteVersion}.\n` +
+                `Major updates are not applied automatically.\n` +
+                `Run: openclaw senpi skills update ${skillName}`);
+            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.
+     */
+    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")}`);
+        }
+        if (failedSkills.length > 0) {
+            const failureLines = failedSkills.map(({ name, reason }) => `  • ${name}: ${reason}`);
+            sections.push(`Failed to update:\n${failureLines.join("\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 ??
+            ((skillsDir, skillName, rawBaseUrl, logger) => checkSkillVersion(skillsDir, 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`.
+     */
+    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();
+        }
+        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 [];
+        }
+    }
+    /**
+     * 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.
+     *
+     * `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
+     * 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,
+            skillsDir: this.options.config.skillsDir,
+            health,
+            lastAction,
+            lastError,
+            skills: skillSnapshots,
+            nextCheckAt: this.snapshot?.nextCheckAt ?? null,
+        };
+    }
+    async persistState() {
+        try {
+            await this.store.save(this.state);
+        }
+        catch (err) {
+            this.options.logger.warn(`[senpi-skills-manager] failed to persist state: ${formatErr(err)}`);
+        }
+    }
+}
+//# sourceMappingURL=coordinator.js.map