@senpi/runtime 3.0.6-dev.runtime-phase-2.20260630134511 → 3.0.6-dev.runtime-phase-2.20260630182800

package/dist/skills-manager/coordinator.js

@@ -16,17 +16,19 @@
  * 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.
+ * Each tick: take the managed skill set from the manifest
+ * (`skills-manifest.json`, the single source of truth), 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 { withClonedGroups } from "./clone-groups.js";
 import { cloneSkillsRepo } from "./fetcher.js";
+import { getManifestSkillNames, resolveSkillSource } from "./manifest.js";
+import { parseSemver } from "../runtime/auto-update/policy.js";
 import { SkillsManagerStateStore } from "./state-store.js";
-import { checkSkillVersion } from "./version-manager.js";
+import { checkSkillVersion, normalizeVersion } from "./version-manager.js";
 import { installSkill } from "./writer.js";
-import { NOTIFICATION_SKILL_LIST_TOP_N, SKILLS_RAW_BASE_URL, SKILLS_REPO_URL, TELEGRAM_NOTIFICATION_BUDGET_CHARS, } from "./constants.js";
 import { createDefaultSkillState, createDefaultSkillsManagerState, formatErr } from "./utils.js";
 export class SkillsCoordinatorUnavailableError extends Error {
     constructor(message) {
@@ -34,6 +36,37 @@ export class SkillsCoordinatorUnavailableError extends Error {
         this.name = "SkillsCoordinatorUnavailableError";
     }
 }
+/** Parse the major-version number from a SKILL.md version string, or null. */
+function majorOf(version) {
+    if (!version)
+        return null;
+    return parseSemver(normalizeVersion(version))?.major ?? null;
+}
+/**
+ * Whether a remote major is **gated** (not auto-applied by the tick).
+ *
+ * The effective ceiling is `max(maxMajor, installedMajor)` — flooring at the
+ * installed major matters because a manual `senpi skills update` applies any
+ * major, so a skill's installed major can legitimately exceed `maxMajor`; once
+ * it does, patch/minor *within* that already-installed major must keep
+ * auto-applying (you can't un-install it). Null handling:
+ * - `maxMajor` null  → floor is just `installedMajor` (gate all true majors).
+ * - `installedMajor` null (unversioned/not-installed) → floor is `maxMajor`
+ *   (so a null-local "minor" classification can't bypass the ceiling).
+ * - both null → no ceiling → not gated.
+ */
+function isMajorGated(remoteMajor, installedMajor, maxMajor) {
+    if (remoteMajor === null)
+        return false;
+    const candidates = [];
+    if (maxMajor !== null)
+        candidates.push(maxMajor);
+    if (installedMajor !== null)
+        candidates.push(installedMajor);
+    if (candidates.length === 0)
+        return false;
+    return remoteMajor > Math.max(...candidates);
+}
 export class SkillsUpdateCoordinator {
     options;
     store;
@@ -42,38 +75,11 @@ export class SkillsUpdateCoordinator {
     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.
+     * Latest remote version per skill name — populated during ticks. Read by
+     * `buildSnapshot` (status RPC) and used as the install `expectedVersion`.
      */
-    skillDescriptions = new Map();
+    latestVersions = new Map();
     constructor(options) {
         this.options = options;
         this.store = new SkillsManagerStateStore(options.stateDir, options.config.skillsDir, options.logger);
@@ -99,7 +105,7 @@ export class SkillsUpdateCoordinator {
             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)`);
+        logger.info(`[senpi-skills-manager] starting | skillsDir=${config.skillsDir.join(",")} skills=${this.resolveSkillNames().join(",")} (manifest) cadence=external (driven by auto-update)`);
         this.state = await this.store.load();
         const bootstrapFn = this.options.deps?.bootstrapSkillsIfNeeded ?? bootstrapSkillsIfNeeded;
         try {
@@ -196,9 +202,10 @@ export class SkillsUpdateCoordinator {
             const { logger } = this.options;
             logger.info(`[senpi-skills-manager] updateSkill invoked | skill=${skillName}`);
             const checkVersionFn = this.resolveCheckFn();
+            const source = this.resolveSource(skillName);
             let versionInfo;
             try {
-                versionInfo = await checkVersionFn(this.options.config.skillsDir, skillName, SKILLS_RAW_BASE_URL, logger);
+                versionInfo = await checkVersionFn(this.options.config.skillsDir, skillName, source.rawBaseUrl, logger, source.path);
             }
             catch (err) {
                 // Version check threw (5xx, network error, timeout, body-parse failure
@@ -215,11 +222,8 @@ export class SkillsUpdateCoordinator {
             }
             // Record the remote version we just learned so the snapshot's latestVersion
             // field reflects it on the next getSnapshot() call — even when no install
-            // happens (skip paths below). Local description is cached alongside so
-            // notifications (sendUpdateSummary / handleMajorAvailable) can include it.
+            // happens (skip paths below).
             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
@@ -287,7 +291,7 @@ export class SkillsUpdateCoordinator {
             this.assertManualOperationAllowed("updateAll", token);
             const { logger, config } = this.options;
             logger.info("[senpi-skills-manager] updateAll invoked");
-            const skillNames = await this.resolveSkillNames();
+            const skillNames = this.resolveSkillNames();
             if (skillNames.length === 0) {
                 logger.info("[senpi-skills-manager] updateAll — no skills to check");
                 return [];
@@ -296,10 +300,9 @@ export class SkillsUpdateCoordinator {
             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);
+                const source = this.resolveSource(skillName);
+                const versionInfo = await checkVersionFn(config.skillsDir, skillName, source.rawBaseUrl, logger, source.path);
                 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 = [];
@@ -440,7 +443,7 @@ export class SkillsUpdateCoordinator {
      */
     async runTick() {
         const { logger, config } = this.options;
-        const skillNames = await this.resolveSkillNames();
+        const skillNames = this.resolveSkillNames();
         if (skillNames.length === 0) {
             logger.info("[senpi-skills-manager] tick — no skills to check");
             return;
@@ -449,11 +452,12 @@ export class SkillsUpdateCoordinator {
         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);
+            const source = this.resolveSource(skillName);
+            const versionInfo = await checkVersionFn(config.skillsDir, skillName, source.rawBaseUrl, logger, source.path);
             this.latestVersions.set(skillName, versionInfo.remoteVersion);
-            this.previousVersions.set(skillName, versionInfo.localVersion);
-            this.skillDescriptions.set(skillName, versionInfo.remoteDescription ?? null);
-            return { name: skillName, ...versionInfo };
+            // Carry the resolved major ceiling so the triage loop can decide whether
+            // a major bump is authorized without re-resolving the source.
+            return { name: skillName, ...versionInfo, maxMajor: source.maxMajor };
         }));
         const skillsToInstall = [];
         let majorPendingCount = 0;
@@ -467,7 +471,7 @@ export class SkillsUpdateCoordinator {
                 logger.warn(`[senpi-skills-manager] tick — version check failed | skill=${skillName} err=${errorMessage}`);
                 continue;
             }
-            const { localVersion, remoteVersion, updateKind } = checkResult.value;
+            const { localVersion, remoteVersion, updateKind, maxMajor } = checkResult.value;
             const skillState = this.state.skills[skillName] ?? createDefaultSkillState(skillName);
             skillState.lastCheckedAt = new Date().toISOString();
             if (localVersion !== null)
@@ -486,14 +490,25 @@ export class SkillsUpdateCoordinator {
                 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);
+            // Enforce the `maxMajor` ceiling on the **remote major regardless of how
+            // the delta was classified** (a null local version classifies as "minor"
+            // but could still pull a remote major above the ceiling). The effective
+            // ceiling is `max(maxMajor, installedMajor)` — see `isMajorGated`.
+            const remoteMajor = majorOf(remoteVersion);
+            const ceilingExceeded = isMajorGated(remoteMajor, majorOf(localVersion), maxMajor);
+            if (ceilingExceeded) {
+                // Gated: record the newer `latestVersion` (surfaced via
+                // `senpi skills status`); the operator applies it with a manual
+                // `senpi skills update <name>` or by bumping `maxMajor` in the manifest.
+                logger.info(`[senpi-skills-manager] tick — major available, not auto-applied | skill=${skillName} local=${localVersion ?? "none"} remote=${remoteVersion ?? "unknown"} maxMajor=${maxMajor ?? "none"}`);
                 this.state.skills[skillName] = skillState;
                 majorPendingCount += 1;
                 continue;
             }
-            // patch / minor — queue for install
+            if (updateKind === "major") {
+                logger.info(`[senpi-skills-manager] tick — major within maxMajor ceiling, auto-applying | skill=${skillName} local=${localVersion ?? "none"} remote=${remoteVersion ?? "unknown"} maxMajor=${maxMajor}`);
+            }
+            // patch / minor / authorized-major — queue for install
             skillsToInstall.push(skillName);
             this.state.skills[skillName] = skillState;
         }
@@ -504,14 +519,12 @@ export class SkillsUpdateCoordinator {
     }
     /**
      * 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.
+     * Per-skill errors are recorded in state without aborting the others;
+     * outcomes are logged (no notification).
      *
-     * 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.
+     * If the clone itself fails we log and return without touching state — a
+     * full-clone failure is almost always a transient network/git issue that
+     * affects every skill equally. The next tick retries.
      */
     async applyUpdates(skillNames) {
         const { logger } = this.options;
@@ -524,20 +537,19 @@ export class SkillsUpdateCoordinator {
             logger.warn(`[senpi-skills-manager] applyUpdates — git clone failed, skipping batch: ${formatErr(err)}`);
             return;
         }
-        const succeededSkillNames = [];
-        const failedSkills = [];
+        let succeeded = 0;
+        let failed = 0;
         for (const skillName of skillNames) {
             const outcome = this.processInstallOutcome(skillName, installOutcomes);
             if (outcome.success) {
-                succeededSkillNames.push(skillName);
+                succeeded += 1;
                 logger.info(`[senpi-skills-manager] applyUpdates — installed | skill=${skillName} version=${outcome.version ?? "unknown"}`);
             }
             else {
-                failedSkills.push({ name: skillName, reason: outcome.error });
+                failed += 1;
             }
         }
-        logger.info(`[senpi-skills-manager] applyUpdates complete | installed=${succeededSkillNames.length} failed=${failedSkills.length}`);
-        await this.sendUpdateSummary(succeededSkillNames, failedSkills);
+        logger.info(`[senpi-skills-manager] applyUpdates complete | installed=${succeeded} failed=${failed}`);
     }
     /**
      * Clone the remote skills repo exactly once and install every skill in
@@ -573,16 +585,29 @@ export class SkillsUpdateCoordinator {
             }
             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) {
+        // Allowlist = the managed (manifest) set, NOT just this batch — otherwise a
+        // manual single-skill `updateSkill(name)` (batch `[name]`) would make the
+        // installSkill allowlist pass for any name, letting it install an arbitrary
+        // repo subdir outside the managed set.
+        const allowedSkills = this.resolveSkillNames();
+        // Group skills by their resolved (repo, branch, commit) and clone each group
+        // once (shared helper handles grouping + per-group clone resilience).
+        const sources = skillNames.map((name) => this.resolveSource(name));
+        await withClonedGroups(sources, cloneSkillsRepo, logger, async (cloneDir, groupSources) => {
+            logger.info(`[senpi-skills-manager] cloneAndInstallMany — clone ready, installing | count=${groupSources.length} cloneDir=${cloneDir}`);
+            for (const source of groupSources) {
+                const skillName = source.name;
                 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);
+                    await installSkill(cloneDir, skillName, config.skillsDir[0], logger, {
+                        sourcePath: source.path,
+                        allowedSkills,
+                        // Verify the freshly-installed SKILL.md matches the version the
+                        // check decided to install — rolls back on mismatch.
+                        expectedVersion: this.latestVersions.get(skillName) ?? null,
+                    });
                     const newVersion = this.latestVersions.get(skillName) ?? null;
                     outcomes.set(skillName, { version: newVersion });
                     logger.info(`[senpi-skills-manager] cloneAndInstallMany — installed | skill=${skillName} version=${newVersion ?? "unknown"}`);
@@ -593,11 +618,15 @@ export class SkillsUpdateCoordinator {
                     logger.warn(`[senpi-skills-manager] cloneAndInstallMany — install failed | skill=${skillName} err=${errorMessage}`);
                 }
             }
-        }
-        finally {
-            await cleanup();
-            logger.info("[senpi-skills-manager] cloneAndInstallMany — clone cleanup done");
-        }
+        }, (groupSources, err) => {
+            // A clone failure for one group records that group's skills as failed
+            // and continues — earlier groups' installs are preserved.
+            const errorMessage = `clone failed: ${formatErr(err)}`;
+            for (const source of groupSources) {
+                outcomes.set(source.name, { version: null, error: errorMessage });
+            }
+            logger.warn(`[senpi-skills-manager] cloneAndInstallMany — clone failed, skipping group | skills=${groupSources.map((s) => s.name).join(",")} err=${formatErr(err)}`);
+        });
         return outcomes;
     }
     /**
@@ -622,7 +651,6 @@ export class SkillsUpdateCoordinator {
      */
     recordSuccess(skillState, newVersion) {
         skillState.installedVersion = newVersion;
-        skillState.lastAppliedVersion = newVersion;
         skillState.consecutiveFailures = 0;
         skillState.lastFailureAt = null;
         skillState.lastFailureReason = null;
@@ -710,208 +738,6 @@ export class SkillsUpdateCoordinator {
         logger.info(`[senpi-skills-manager] applyUpdate complete | skill=${skillName} version=${installedVersion ?? "unknown"}`);
         return installedVersion;
     }
-    /**
-     * Format the per-skill nested-bullet block used in both notification
-     * shapes. Renders the structure suggested in PR #78 review feedback:
-     *
-     *   **skill-name**
-     *      • v1.0.0 → v2.0.0       (or "v1.0.0 (install failed)" when failed)
-     *      • description: …         (omitted when no remote description)
-     *      • error: …               (only on failure, replaces the description)
-     *
-     * **Why markdown, not HTML?**
-     * Openclaw's Telegram channel (`src/telegram/send.ts:sendMessageTelegram`)
-     * pipes outbound text through `renderTelegramHtmlText`, which defaults
-     * `textMode` to `"markdown"` — i.e. it expects the source to be markdown
-     * and runs `markdownToTelegramHtml` over it before handing the converted
-     * HTML to the Bot API with `parse_mode: "HTML"`. The `message` tool
-     * (which is what this coordinator's `notify` callback ultimately hits via
-     * `/tools/invoke`) does not expose `textMode`, so HTML written by us is
-     * treated as literal characters by the markdown step and rendered as
-     * visible `<b>` text in the chat (the actual production bug this docstring
-     * fixes — confirmed against a live notification screenshot).
-     *
-     * Using markdown source (`**bold**`, backticks) instead means the channel's
-     * markdown→HTML converter produces the correct `<b>` / `<code>` HTML
-     * payload and Telegram renders the formatting properly.
-     *
-     * @param skillName Skill identifier (rendered bold via `**name**`).
-     * @param toVersion Resolved upgraded-to version. `null` for failure rows
-     *                  where no install completed; renders as
-     *                  "vPREV (install failed)".
-     * @param errorReason Optional failure reason. When provided, replaces
-     *                    the description line with `error: …`.
-     */
-    formatSkillBlock(skillName, toVersion, errorReason = null, options = {}) {
-        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)"}`;
-        // `omitDescription` is set when the caller is rebuilding a notification
-        // in compact mode after the verbose form exceeded Telegram's per-message
-        // byte budget (see `sendUpdateSummary`'s three-tier sizing). The error
-        // line for failures is NEVER omitted — it's the actionable bit and a
-        // single line, not the source of the overflow.
-        const description = options.omitDescription
-            ? null
-            : (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;
-        // ── Three-tier size budget ────────────────────────────────────────────
-        //
-        // Telegram caps a single message at 4096 chars; if we send more, the
-        // Bot API rejects with "MESSAGE_TOO_LONG" and the user sees nothing.
-        // Discovery-mode deployments with many skills + long descriptions can
-        // realistically blow past that. Lead's review comment
-        // (PR #78 #discussion_r3247822298): always render *something* useful,
-        // never silently drop the notification.
-        //
-        // Tier 1 (default — verbose): full per-skill blocks with descriptions.
-        // Tier 2 (compact): same blocks but with description lines omitted —
-        //   keeps version transitions + error reasons, which are the
-        //   actionable bits.
-        // Tier 3 (top-N cap): if even compact mode exceeds the budget, render
-        //   only the first NOTIFICATION_SKILL_LIST_TOP_N of each section with a
-        //   "… and N more" tail.
-        //
-        // The 4000-char default budget (vs Telegram's hard 4096) leaves headroom
-        // for the gateway's markdown→HTML conversion to add wrapping tags
-        // without pushing the payload over. Both the budget and the per-section
-        // cap are env-overridable (see `constants.ts`) so operators with
-        // alternative transports or different verbosity preferences can tune
-        // them without a code change.
-        const BUDGET_CHARS = TELEGRAM_NOTIFICATION_BUDGET_CHARS;
-        const TOP_N = NOTIFICATION_SKILL_LIST_TOP_N;
-        const build = (opts) => {
-            const succeededRendered = opts.cap !== undefined
-                ? succeededSkillNames.slice(0, opts.cap)
-                : succeededSkillNames;
-            const failedRendered = opts.cap !== undefined
-                ? failedSkills.slice(0, opts.cap)
-                : failedSkills;
-            const sections = [];
-            if (succeededSkillNames.length > 0) {
-                const blocks = succeededRendered.map((name) => this.formatSkillBlock(name, this.latestVersions.get(name) ?? null, null, {
-                    omitDescription: opts.omitDescriptions,
-                }));
-                // Tail when capped: shows the omitted count so operators know the
-                // list isn't the complete picture (and can look at logs for full).
-                const tail = opts.cap !== undefined && succeededSkillNames.length > opts.cap
-                    ? `\n\n… and ${succeededSkillNames.length - opts.cap} more updated skill${succeededSkillNames.length - opts.cap === 1 ? "" : "s"} not shown`
-                    : "";
-                sections.push(`Updated:\n\n${blocks.join("\n\n")}${tail}`);
-            }
-            if (failedSkills.length > 0) {
-                const blocks = failedRendered.map(({ name, reason }) => this.formatSkillBlock(name, null, reason, {
-                    omitDescription: opts.omitDescriptions,
-                }));
-                const tail = opts.cap !== undefined && failedSkills.length > opts.cap
-                    ? `\n\n… and ${failedSkills.length - opts.cap} more failed skill${failedSkills.length - opts.cap === 1 ? "" : "s"} not shown`
-                    : "";
-                sections.push(`Failed to update:\n\n${blocks.join("\n\n")}${tail}`);
-            }
-            return `Senpi skills update:\n\n${sections.join("\n\n")}`;
-        };
-        // Tier 1: verbose
-        let message = build({ omitDescriptions: false });
-        let tier = "verbose";
-        if (message.length > BUDGET_CHARS) {
-            // Tier 2: drop descriptions
-            message = build({ omitDescriptions: true });
-            tier = "compact (descriptions omitted)";
-            if (message.length > BUDGET_CHARS) {
-                // Tier 3: cap each section to top-N
-                message = build({ omitDescriptions: true, cap: TOP_N });
-                tier = `capped (top ${TOP_N} per section, descriptions omitted)`;
-            }
-        }
-        try {
-            await this.options.notify(message);
-            this.options.logger.info(`[senpi-skills-manager] sendUpdateSummary — notification sent | succeeded=${succeededSkillNames.length} failed=${failedSkills.length} tier=${tier} messageChars=${message.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
@@ -923,50 +749,29 @@ export class SkillsUpdateCoordinator {
      */
     resolveCheckFn() {
         return (this.options.deps?.checkSkillVersion ??
-            ((skillsDirs, skillName, rawBaseUrl, logger) => checkSkillVersion(skillsDirs, skillName, rawBaseUrl, undefined, logger)));
+            ((skillsDirs, skillName, rawBaseUrl, logger, remotePath) => checkSkillVersion(skillsDirs, skillName, rawBaseUrl, undefined, logger, remotePath)));
     }
     /**
-     * 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.
+     * Resolve a skill name to its concrete source (repo/branch/path/rawBaseUrl)
+     * from the manifest, applying any plugin-config per-skill overrides. The
+     * `SENPI_SKILLS_BRANCH` / `SENPI_SKILLS_REPO_URL` env testing knobs are
+     * applied inside {@link resolveSkillSource}.
      */
-    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();
+    resolveSource(skillName) {
+        return resolveSkillSource(skillName, { overrides: this.options.config.overrides });
+    }
+    /**
+     * The managed skill set for this tick — **always the manifest** set
+     * (`skills-manifest.json`), the single source of truth. `config.skills` and
+     * directory discovery no longer define the set: the manifest does, full stop
+     * (only `enabled: false` disables the manager entirely).
+     *
+     * `deps.listManagedSkills` is a test-only seam to substitute the set without
+     * a fixture manifest on disk; production always falls through to the
+     * manifest.
+     */
+    resolveSkillNames() {
+        return this.options.deps?.listManagedSkills?.() ?? getManifestSkillNames();
     }
     /**
      * Build the point-in-time snapshot returned by {@link getSnapshot}.
@@ -987,18 +792,26 @@ export class SkillsUpdateCoordinator {
      * 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,
+        const skillSnapshots = Object.values(this.state.skills).map((skillState) => {
             // Prefer the in-memory map (freshest — populated synchronously inside
             // the current tick before `persistState` runs) and fall back to the
             // persisted field. The persisted fallback covers the post-restart
             // window where the map is empty until the first external tick fires.
-            latestVersion: this.latestVersions.get(skillState.name) ?? skillState.latestVersion ?? null,
-            lastCheckedAt: skillState.lastCheckedAt,
-            consecutiveFailures: skillState.consecutiveFailures,
-            lastFailureReason: skillState.lastFailureReason,
-        }));
+            const latestVersion = this.latestVersions.get(skillState.name) ?? skillState.latestVersion ?? null;
+            return {
+                name: skillState.name,
+                installedVersion: skillState.installedVersion,
+                latestVersion,
+                lastCheckedAt: skillState.lastCheckedAt,
+                consecutiveFailures: skillState.consecutiveFailures,
+                lastFailureReason: skillState.lastFailureReason,
+                // A major is pending when the latest observed major is **gated** — i.e.
+                // it exceeds the effective ceiling (max(maxMajor, installedMajor)) and so
+                // the tick won't auto-apply it. A major within the ceiling is omitted
+                // (it auto-applies on the next tick).
+                majorPending: isMajorGated(majorOf(latestVersion), majorOf(skillState.installedVersion), this.resolveSource(skillState.name).maxMajor),
+            };
+        });
         return {
             enabled: this.options.config.enabled,
             // Snapshot is a serializable view consumed by gateway RPCs and the CLI;
@@ -1020,18 +833,4 @@ export class SkillsUpdateCoordinator {
         }
     }
 }
-// `escapeHtml` was removed alongside the switch from HTML to markdown
-// notification source — see `formatSkillBlock` for why. The openclaw
-// Telegram channel runs `markdownToTelegramHtml` over our text and
-// handles HTML escaping itself on the converter's output. Pre-escaping
-// at this layer would double-escape (e.g. `&amp;` becomes `&amp;amp;`)
-// and corrupt the rendered output.
-//
-// Markdown-special characters (`*`, `_`, `[`, `]`, backtick) in dynamic
-// values aren't escaped either — descriptions that legitimately contain
-// these would author them as markdown intentionally; skill names in the
-// senpi-skills repo are kebab-case identifiers; error messages from
-// `formatErr` are typically prose. If a future skill description ever
-// breaks the rendering, the fix is to author the SKILL.md frontmatter
-// using proper markdown.
 //# sourceMappingURL=coordinator.js.map