@clawling/clawchat-plugin-openclaw 2026.7.1 → 2026.7.2-1

package/dist/src/runtime.js

@@ -11,7 +11,7 @@ import { RefreshManager } from "./refresh-manager.js";
 import { runOpenclawClawlingLogin, } from "./login.runtime.js";
 import { CHANNEL_ID, effectiveOutputVisibility, effectiveGroupCommandMode, effectiveGroupMode, hasOpenclawClawlingConnectCredentials, resolveOpenclawClawlingAccount, } from "./config.js";
 import { dispatchOpenclawClawlingInbound } from "./inbound.js";
-import { PendingConsentStore, handleOwnerConsentReply, readEffectiveSkillVersions, resolveBundledSkillsDir, resolveManagedSkillsDir, runSkillUpdateCheck, } from "./skill-update.js";
+import { PendingConsentStore, handleOwnerConsentReply, managedSkillExists, readLocalSkillState, resolveBundledSkillsDir, resolveManagedSkillsDir, runSkillUpdateCheck, } from "./skill-update.js";
 import { fetchInboundMedia } from "./media-runtime.js";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.js";
 import { runWithTerminalClawChatSendScope } from "./terminal-send.js";
@@ -1762,6 +1762,10 @@ export async function startOpenclawClawlingGateway(params) {
     // The bundled `./skills` dir is READ-ONLY here: a first-boot fallback for the
     // "current installed version" only — never written (it lives in node_modules
     // → may be read-only and is clobbered on `openclaw plugins update`).
+    // Update detection converges on raw sha256 (readLocalSkillState), not the
+    // frontmatter version, so a same-version content fix still applies; a
+    // manifest `removed` id tombstones the LOCAL managed copy (never bundled)
+    // via removeManagedSkill, deleting only ids the official manifest names.
     const skillUpdateConsent = new PendingConsentStore();
     const managedSkillsDir = resolveManagedSkillsDir();
     let bundledSkillsDir = null;
@@ -1771,14 +1775,29 @@ export async function startOpenclawClawlingGateway(params) {
     catch (err) {
         log?.info?.(`[${accountId}] clawchat-plugin-openclaw skill-update: bundled skills dir not resolvable (using managed-only current): ${err instanceof Error ? err.message : String(err)}`);
     }
-    const sendOwnerSkillMessage = async (text) => {
+    // A usr_... id is not a valid chat_id — member-backend rejects it with
+    // "invalid conversation id" and msghub never acks the send. Proactive owner
+    // messages must be addressed to the direct conversation recorded at
+    // activation (parity with the hermes adapter's _owner_direct_chat_id).
+    const resolveOwnerDirectConversationId = () => {
         const ownerUserId = account.ownerUserId?.trim();
         if (!ownerUserId)
+            return null;
+        const conversationId = store
+            ?.getActivationConversation?.({ platform: "openclaw", accountId })
+            ?.conversationId?.trim();
+        return conversationId || null;
+    };
+    const sendOwnerSkillMessage = async (text) => {
+        const conversationId = resolveOwnerDirectConversationId();
+        if (!conversationId) {
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw skill-update owner message skipped: no activation conversation recorded`);
             return;
+        }
         await sendOpenclawClawlingText({
             client,
             account,
-            to: { chatId: ownerUserId, chatType: "direct" },
+            to: { chatId: conversationId, chatType: "direct" },
             text,
             log,
         });
@@ -1790,10 +1809,10 @@ export async function startOpenclawClawlingGateway(params) {
             return;
         }
         // Effective current = managed copy if present, else bundled (host precedence).
-        const localVersions = await readEffectiveSkillVersions(managedSkillsDir, bundledSkillsDir);
         await runSkillUpdateCheck({
             ownerUserId,
-            localVersions,
+            readLocalState: (id) => readLocalSkillState(managedSkillsDir, bundledSkillsDir, id),
+            hasManagedSkill: (id) => managedSkillExists(managedSkillsDir, id),
             fetchFn: globalThis.fetch,
             store: skillUpdateConsent,
             sendOwnerMessage: sendOwnerSkillMessage,
@@ -2408,16 +2427,16 @@ export async function startOpenclawClawlingGateway(params) {
         },
     });
     const forwardGroupApprovalSlashToOwner = async (turn) => {
-        const ownerUserId = account.ownerUserId?.trim();
-        if (!ownerUserId) {
-            log?.error?.(`[${accountId}] clawchat-plugin-openclaw group approval command suppressed reason=missing_owner_user_id chat_id=${turn.peer.id} msg=${turn.messageId}`);
+        const ownerConversationId = resolveOwnerDirectConversationId();
+        if (!ownerConversationId) {
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw group approval command suppressed reason=missing_owner_conversation chat_id=${turn.peer.id} msg=${turn.messageId}`);
             return "skipped";
         }
         try {
             await sendOpenclawClawlingText({
                 client,
                 account,
-                to: { chatId: ownerUserId, chatType: "direct" },
+                to: { chatId: ownerConversationId, chatType: "direct" },
                 text: groupOwnerAttentionText(turn.peer.id, turn.rawBody),
                 log,
             });

package/dist/src/skill-update.js

@@ -29,8 +29,12 @@ import { fileURLToPath } from "node:url";
  *   implementation in `@clawling/clawchat-plugin-install-cli`
  *   (`packages/core/src/skills/check-update.ts`). That package is
  *   workspace-private, so the logic is duplicated here rather than imported.
- * - Strict semver compare mirrors the reference `parseComparableVersion`
- *   (`X.Y[.Z[.W]][-buildnum]`).
+ * - Update detection converges on raw sha256 comparison: ANY byte difference
+ *   from the official source (or a missing local file) is an update —
+ *   upgrade, rollback, or same-version content fix alike. The strict semver
+ *   compare (`parseComparableVersion` / `isVersionOlder`, still ported from
+ *   the reference `parseComparableVersion`, `X.Y[.Z[.W]][-buildnum]`) is kept
+ *   only for consent-prompt display wording, not for the `hasUpdate` decision.
  * - All network IO goes through an injected `FetchLike`; tests never touch the
  *   real network.
  *
@@ -151,7 +155,25 @@ export function parseSkillsManifest(text) {
             skills[target][skillId] = asEntry(entry, `${target}.${skillId}`);
         }
     }
-    return { schema: 1, skills };
+    const removed = {};
+    if (data.removed !== undefined) {
+        if (!data.removed || typeof data.removed !== "object" || Array.isArray(data.removed)) {
+            throw new Error("skills manifest `removed` must be an object");
+        }
+        for (const [target, ids] of Object.entries(data.removed)) {
+            if (!Array.isArray(ids) || !ids.every((i) => typeof i === "string" && i.trim())) {
+                throw new Error(`skills manifest removed[${target}] must be a list of skill ids`);
+            }
+            const cleaned = ids.map((i) => i.trim());
+            for (const id of cleaned) {
+                if (skills[target]?.[id]) {
+                    throw new Error(`skill ${target}.${id} is in both skills and removed`);
+                }
+            }
+            removed[target] = cleaned;
+        }
+    }
+    return { schema: 1, skills, removed };
 }
 async function fetchText(url, fetchFn) {
     let response;
@@ -167,9 +189,10 @@ async function fetchText(url, fetchFn) {
     return response.text();
 }
 /**
- * Read the official manifest for the `openclaw` target and compare each skill's
- * offered version against the locally installed `current` map. A skill missing
- * from `current` is reported as `hasUpdate: true`.
+ * Read the official manifest for the `openclaw` target and compare each
+ * skill's offered content (sha256) against its effective local state, read
+ * on demand via `readLocalState`. Any sha256 mismatch — or no local state at
+ * all — is reported as `hasUpdate: true`.
  */
 export async function checkSkillUpdate(options) {
     const ref = options.ref ?? DEFAULT_SKILLS_REF;
@@ -181,11 +204,14 @@ export async function checkSkillUpdate(options) {
     }
     const results = [];
     for (const [skillId, entry] of Object.entries(targetSkills)) {
-        const current = options.current[skillId] ?? null;
-        const hasUpdate = current === null ? true : isVersionOlder(current, entry.version);
+        const state = await options.readLocalState(skillId);
+        // sha convergence: any byte difference from the official source (or a
+        // missing local file) is an update — upgrade, rollback, or same-version
+        // content fix alike.
+        const hasUpdate = !state || state.sha256 !== entry.sha256;
         results.push({
             skillId,
-            current,
+            current: state?.version ?? null,
             latest: entry.version,
             hasUpdate,
             path: entry.path,
@@ -193,7 +219,12 @@ export async function checkSkillUpdate(options) {
             bytes: entry.bytes,
         });
     }
-    return { ref, results, hasUpdate: results.some((r) => r.hasUpdate) };
+    return {
+        ref,
+        results,
+        hasUpdate: results.some((r) => r.hasUpdate),
+        removedIds: manifest.removed[SKILL_TARGET] ?? [],
+    };
 }
 /**
  * Download one skill markdown file and integrity-check it against the manifest
@@ -230,52 +261,41 @@ export function parseSkillFrontmatterVersion(markdown) {
     const raw = (versionLine[1] ?? "").trim().replace(/^["']|["']$/g, "");
     return raw || null;
 }
-/** Read one skill's frontmatter `version` from `<dir>/<skillId>/SKILL.md`. */
-async function readSingleSkillVersion(dir, skillId) {
+async function readSkillStateFromDir(dir, skillId) {
     try {
-        const md = await fs.readFile(path.join(dir, skillId, "SKILL.md"), "utf8");
-        return parseSkillFrontmatterVersion(md);
+        const buf = await fs.readFile(path.join(dir, skillId, "SKILL.md"));
+        return {
+            version: parseSkillFrontmatterVersion(buf.toString("utf8")),
+            sha256: crypto.createHash("sha256").update(buf).digest("hex"),
+        };
     }
     catch {
-        return null; // missing / unreadable
+        return null;
     }
 }
 /**
- * Read the installed version of each requested skill from a SINGLE directory
- * (`<skillsDir>/<skillId>/SKILL.md`). Missing files / missing frontmatter
- * version are simply omitted (treated as "not installed" → update available).
+ * Effective local state of ONE skill, mirroring the host's managed-over-bundled
+ * precedence: managed copy if present, else bundled, else null. Called per
+ * remote manifest entry so dynamically delivered extra skills are hashed too
+ * (a static bundled-id list would misreport extras as never-installed).
  */
-export async function readLocalSkillVersions(skillsDir, skillIds = OPENCLAW_SKILL_IDS) {
-    const versions = {};
-    for (const skillId of skillIds) {
-        const version = await readSingleSkillVersion(skillsDir, skillId);
-        if (version)
-            versions[skillId] = version;
-    }
-    return versions;
+export async function readLocalSkillState(managedDir, bundledDir, skillId) {
+    const managed = await readSkillStateFromDir(managedDir, skillId);
+    if (managed)
+        return managed;
+    if (bundledDir)
+        return readSkillStateFromDir(bundledDir, skillId);
+    return null;
 }
-/**
- * Read the EFFECTIVE installed version of each skill, mirroring the host's
- * managed-over-bundled precedence (`src/skills/loading/workspace.ts:1220-1239`,
- * managed=3 > bundled=2): use the managed copy's frontmatter `version` when
- * `<managedDir>/<id>/SKILL.md` exists, otherwise fall back to the bundled
- * copy's. A skill present in neither is omitted (→ update available).
- */
-export async function readEffectiveSkillVersions(managedDir, bundledDir, skillIds = OPENCLAW_SKILL_IDS) {
-    const versions = {};
-    for (const skillId of skillIds) {
-        const managed = await readSingleSkillVersion(managedDir, skillId);
-        if (managed) {
-            versions[skillId] = managed;
-            continue;
-        }
-        if (bundledDir) {
-            const bundled = await readSingleSkillVersion(bundledDir, skillId);
-            if (bundled)
-                versions[skillId] = bundled;
-        }
+/** True when `<managedDir>/<skillId>/SKILL.md` exists (removal precondition). */
+export async function managedSkillExists(managedDir, skillId) {
+    try {
+        await fs.access(path.join(managedDir, skillId, "SKILL.md"));
+        return true;
+    }
+    catch {
+        return false;
     }
-    return versions;
 }
 /**
  * Resolve OpenClaw's state directory, mirroring the host `src/utils.ts:132-154`:
@@ -359,6 +379,18 @@ export async function atomicWriteSkill(skillsDir, skillId, content) {
         throw err;
     }
 }
+/**
+ * Delete a tombstoned managed skill: remove `<skillsDir>/<skillId>/SKILL.md`
+ * (the host chokidar-watches the dir; the unlink triggers a snapshot rebuild
+ * that drops the registration) and best-effort remove the now-empty dir.
+ * Deletion is the ONE legitimate delete of a skill path, and ONLY for ids the
+ * official manifest explicitly tombstones. Idempotent.
+ */
+export async function removeManagedSkill(skillsDir, skillId) {
+    const dir = path.join(skillsDir, skillId);
+    await fs.rm(path.join(dir, "SKILL.md"), { force: true });
+    await fs.rmdir(dir).catch(() => { });
+}
 const AFFIRM_TOKENS = new Set([
     "更新",
     "更新吧",
@@ -438,7 +470,20 @@ export class PendingConsentStore {
     }
 }
 function describeUpdate(u) {
-    return `「${u.skillId}」v${u.current ?? "无"} → v${u.target}`;
+    if (u.current === null)
+        return `「${u.skillId}」v无 → v${u.target}`;
+    let cmp = -1;
+    try {
+        cmp = compareVersions(u.current, u.target);
+    }
+    catch {
+        cmp = -1; // unparsable local version — show as a plain update
+    }
+    if (cmp === 0)
+        return `「${u.skillId}」v${u.target}(内容修订)`;
+    if (cmp > 0)
+        return `「${u.skillId}」v${u.current} → v${u.target}(回滚)`;
+    return `「${u.skillId}」v${u.current} → v${u.target}`;
 }
 /**
  * Step ③–⑤ (plan §2): on `clawchat.skill.update.check`, check the official
@@ -453,23 +498,25 @@ export async function runSkillUpdateCheck(options) {
         return null;
     }
     const outcome = await checkSkillUpdate({
-        current: options.localVersions,
+        readLocalState: options.readLocalState,
         ...(options.ref ? { ref: options.ref } : {}),
         ...(options.base ? { base: options.base } : {}),
         fetchFn: options.fetchFn,
     });
     const updates = outcome.results
         .filter((r) => r.hasUpdate)
-        .map((r) => ({
-        skillId: r.skillId,
-        current: r.current,
-        target: r.latest,
-        path: r.path,
-        sha256: r.sha256,
-        bytes: r.bytes,
-    }));
-    if (updates.length === 0) {
-        options.log?.info?.("clawchat skill-update check: no updates available");
+        .map((r) => ({ skillId: r.skillId, current: r.current, target: r.latest, path: r.path, sha256: r.sha256, bytes: r.bytes }));
+    const removals = [];
+    for (const skillId of outcome.removedIds) {
+        if (OPENCLAW_SKILL_IDS.includes(skillId)) {
+            options.log?.info?.(`clawchat skill-update: ignoring tombstone for bundled skill ${skillId}`);
+            continue;
+        }
+        if (await options.hasManagedSkill(skillId))
+            removals.push({ skillId });
+    }
+    if (updates.length === 0 && removals.length === 0) {
+        options.log?.info?.("clawchat skill-update check: nothing to converge");
         return null;
     }
     const now = (options.now ?? Date.now)();
@@ -478,13 +525,19 @@ export async function runSkillUpdateCheck(options) {
         ref: outcome.ref,
         ...(options.base ? { base: options.base } : {}),
         updates,
+        removals,
         createdAt: now,
         expiresAt: now + (options.timeoutMs ?? DEFAULT_CONSENT_TIMEOUT_MS),
     };
     options.store.set(record);
-    const text = `我的技能有更新:${updates.map(describeUpdate).join(";")}。回复「更新」确认,「取消」忽略。`;
+    const segments = [];
+    if (updates.length > 0)
+        segments.push(`我的技能有更新:${updates.map(describeUpdate).join(";")}`);
+    if (removals.length > 0)
+        segments.push(`以下技能将下线移除:${removals.map((r) => `「${r.skillId}」`).join("、")}`);
+    const text = `${segments.join(";")}。回复「更新」确认,「取消」忽略。`;
     await options.sendOwnerMessage(text);
-    options.log?.info?.(`clawchat skill-update check: asked owner for consent on ${updates.map((u) => u.skillId).join(",")}`);
+    options.log?.info?.(`clawchat skill-update check: asked owner for consent on updates=[${updates.map((u) => u.skillId).join(",")}] removals=[${removals.map((r) => r.skillId).join(",")}]`);
     return record;
 }
 /**
@@ -516,22 +569,23 @@ export async function handleOwnerConsentReply(options) {
         return true;
     }
     // verdict === "affirm"
-    const readLocalVersion = options.readLocalVersion ??
+    const readLocalSha = options.readLocalSha ??
         (async (skillId) => {
             try {
-                const md = await fs.readFile(path.join(options.skillsDir, skillId, "SKILL.md"), "utf8");
-                return parseSkillFrontmatterVersion(md);
+                const buf = await fs.readFile(path.join(options.skillsDir, skillId, "SKILL.md"));
+                return crypto.createHash("sha256").update(buf).digest("hex");
             }
             catch {
                 return null;
             }
         });
     const applied = [];
+    const removed = [];
     try {
         for (const update of pending.updates) {
-            // Idempotency: skip a skill already at the target version on disk.
-            const onDisk = await readLocalVersion(update.skillId);
-            if (onDisk === update.target) {
+            // Idempotency: skip a skill whose on-disk bytes already match the target.
+            const onDisk = await readLocalSha(update.skillId);
+            if (onDisk === update.sha256) {
                 applied.push(update);
                 continue;
             }
@@ -544,6 +598,18 @@ export async function handleOwnerConsentReply(options) {
             applied.push(update);
             options.log?.info?.(`clawchat skill-update: applied ${update.skillId} -> v${update.target} (atomic overwrite)`);
         }
+        for (const removal of pending.removals) {
+            // Defensive re-guard: bundled skills must never be deleted, even though
+            // runSkillUpdateCheck already filters them out of removal candidates.
+            // Unreachable in the normal flow; kept as a cheap safety net.
+            if (OPENCLAW_SKILL_IDS.includes(removal.skillId)) {
+                options.log?.info?.(`clawchat skill-update: skipped removal of bundled skill ${removal.skillId} (defensive re-guard)`);
+                continue;
+            }
+            await removeManagedSkill(options.skillsDir, removal.skillId);
+            removed.push(removal);
+            options.log?.info?.(`clawchat skill-update: removed tombstoned skill ${removal.skillId}`);
+        }
     }
     catch (err) {
         // Keep the pending record so the owner can retry with another "更新"; report
@@ -553,7 +619,11 @@ export async function handleOwnerConsentReply(options) {
         return true;
     }
     options.store.clear();
-    const summary = applied.map((u) => `「${u.skillId}」v${u.target}`).join("、");
-    await options.sendOwnerMessage(`✅ 已更新到 ${summary}`);
+    const segments = [];
+    if (applied.length > 0)
+        segments.push(`已更新到 ${applied.map((u) => `「${u.skillId}」v${u.target}`).join("、")}`);
+    if (removed.length > 0)
+        segments.push(`已移除 ${removed.map((r) => `「${r.skillId}」`).join("、")}`);
+    await options.sendOwnerMessage(`✅ ${segments.join(";")}`);
     return true;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.7.1",
+  "version": "2026.7.2-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/src/runtime.ts

@@ -38,7 +38,8 @@ import { dispatchOpenclawClawlingInbound, type IngestTurnParams } from "./inboun
 import {
   PendingConsentStore,
   handleOwnerConsentReply,
-  readEffectiveSkillVersions,
+  managedSkillExists,
+  readLocalSkillState,
   resolveBundledSkillsDir,
   resolveManagedSkillsDir,
   runSkillUpdateCheck,
@@ -2154,6 +2155,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // The bundled `./skills` dir is READ-ONLY here: a first-boot fallback for the
   // "current installed version" only — never written (it lives in node_modules
   // → may be read-only and is clobbered on `openclaw plugins update`).
+  // Update detection converges on raw sha256 (readLocalSkillState), not the
+  // frontmatter version, so a same-version content fix still applies; a
+  // manifest `removed` id tombstones the LOCAL managed copy (never bundled)
+  // via removeManagedSkill, deleting only ids the official manifest names.
   const skillUpdateConsent = new PendingConsentStore();
   const managedSkillsDir = resolveManagedSkillsDir();
   let bundledSkillsDir: string | null = null;
@@ -2166,13 +2171,30 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       }`,
     );
   }
-  const sendOwnerSkillMessage = async (text: string): Promise<void> => {
+  // A usr_... id is not a valid chat_id — member-backend rejects it with
+  // "invalid conversation id" and msghub never acks the send. Proactive owner
+  // messages must be addressed to the direct conversation recorded at
+  // activation (parity with the hermes adapter's _owner_direct_chat_id).
+  const resolveOwnerDirectConversationId = (): string | null => {
     const ownerUserId = account.ownerUserId?.trim();
-    if (!ownerUserId) return;
+    if (!ownerUserId) return null;
+    const conversationId = store
+      ?.getActivationConversation?.({ platform: "openclaw", accountId })
+      ?.conversationId?.trim();
+    return conversationId || null;
+  };
+  const sendOwnerSkillMessage = async (text: string): Promise<void> => {
+    const conversationId = resolveOwnerDirectConversationId();
+    if (!conversationId) {
+      log?.info?.(
+        `[${accountId}] clawchat-plugin-openclaw skill-update owner message skipped: no activation conversation recorded`,
+      );
+      return;
+    }
     await sendOpenclawClawlingText({
       client,
       account,
-      to: { chatId: ownerUserId, chatType: "direct" },
+      to: { chatId: conversationId, chatType: "direct" },
       text,
       log,
     });
@@ -2186,10 +2208,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       return;
     }
     // Effective current = managed copy if present, else bundled (host precedence).
-    const localVersions = await readEffectiveSkillVersions(managedSkillsDir, bundledSkillsDir);
     await runSkillUpdateCheck({
       ownerUserId,
-      localVersions,
+      readLocalState: (id) => readLocalSkillState(managedSkillsDir, bundledSkillsDir, id),
+      hasManagedSkill: (id) => managedSkillExists(managedSkillsDir, id),
       fetchFn: globalThis.fetch,
       store: skillUpdateConsent,
       sendOwnerMessage: sendOwnerSkillMessage,
@@ -2886,10 +2908,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   });
 
   const forwardGroupApprovalSlashToOwner = async (turn: IngestTurnParams): Promise<IngestTurnResult> => {
-    const ownerUserId = account.ownerUserId?.trim();
-    if (!ownerUserId) {
+    const ownerConversationId = resolveOwnerDirectConversationId();
+    if (!ownerConversationId) {
       log?.error?.(
-        `[${accountId}] clawchat-plugin-openclaw group approval command suppressed reason=missing_owner_user_id chat_id=${turn.peer.id} msg=${turn.messageId}`,
+        `[${accountId}] clawchat-plugin-openclaw group approval command suppressed reason=missing_owner_conversation chat_id=${turn.peer.id} msg=${turn.messageId}`,
       );
       return "skipped";
     }
@@ -2897,7 +2919,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       await sendOpenclawClawlingText({
         client,
         account,
-        to: { chatId: ownerUserId, chatType: "direct" },
+        to: { chatId: ownerConversationId, chatType: "direct" },
         text: groupOwnerAttentionText(turn.peer.id, turn.rawBody),
         log,
       });

package/src/skill-update.ts

@@ -30,8 +30,12 @@ import { fileURLToPath } from "node:url";
  *   implementation in `@clawling/clawchat-plugin-install-cli`
  *   (`packages/core/src/skills/check-update.ts`). That package is
  *   workspace-private, so the logic is duplicated here rather than imported.
- * - Strict semver compare mirrors the reference `parseComparableVersion`
- *   (`X.Y[.Z[.W]][-buildnum]`).
+ * - Update detection converges on raw sha256 comparison: ANY byte difference
+ *   from the official source (or a missing local file) is an update —
+ *   upgrade, rollback, or same-version content fix alike. The strict semver
+ *   compare (`parseComparableVersion` / `isVersionOlder`, still ported from
+ *   the reference `parseComparableVersion`, `X.Y[.Z[.W]][-buildnum]`) is kept
+ *   only for consent-prompt display wording, not for the `hasUpdate` decision.
  * - All network IO goes through an injected `FetchLike`; tests never touch the
  *   real network.
  *
@@ -138,6 +142,9 @@ export interface SkillManifestEntry {
 export interface SkillsManifest {
   schema: number;
   skills: Record<string, Record<string, SkillManifestEntry>>;
+  /** Tombstoned skill ids per target. An adapter deletes its LOCAL copy of an
+   * id ONLY when it appears here — absence from `skills` alone never deletes. */
+  removed: Record<string, string[]>;
 }
 
 export interface SkillUpdate {
@@ -156,6 +163,8 @@ export interface CheckSkillUpdateOutcome {
   ref: string;
   results: SkillUpdate[];
   hasUpdate: boolean;
+  /** Tombstoned skill ids for this target, straight from `manifest.removed`. */
+  removedIds: string[];
 }
 
 function skillsBase(base: string | undefined, ref: string): string {
@@ -222,7 +231,25 @@ export function parseSkillsManifest(text: string): SkillsManifest {
       skills[target][skillId] = asEntry(entry, `${target}.${skillId}`);
     }
   }
-  return { schema: 1, skills };
+  const removed: SkillsManifest["removed"] = {};
+  if (data.removed !== undefined) {
+    if (!data.removed || typeof data.removed !== "object" || Array.isArray(data.removed)) {
+      throw new Error("skills manifest `removed` must be an object");
+    }
+    for (const [target, ids] of Object.entries(data.removed as Record<string, unknown>)) {
+      if (!Array.isArray(ids) || !ids.every((i) => typeof i === "string" && (i as string).trim())) {
+        throw new Error(`skills manifest removed[${target}] must be a list of skill ids`);
+      }
+      const cleaned = ids.map((i) => (i as string).trim());
+      for (const id of cleaned) {
+        if (skills[target]?.[id]) {
+          throw new Error(`skill ${target}.${id} is in both skills and removed`);
+        }
+      }
+      removed[target] = cleaned;
+    }
+  }
+  return { schema: 1, skills, removed };
 }
 
 async function fetchText(url: string, fetchFn: FetchLike): Promise<string> {
@@ -239,17 +266,22 @@ async function fetchText(url: string, fetchFn: FetchLike): Promise<string> {
 }
 
 export interface CheckSkillUpdateOptions {
-  /** Locally installed versions: `{ "<skillId>": "<version>" }`. */
-  current: Record<string, string>;
+  /**
+   * Effective local state of one skill (managed-over-bundled), or null when
+   * not installed. Called once per remote manifest entry — remote-driven, so
+   * dynamically delivered extras are covered too.
+   */
+  readLocalState: (skillId: string) => Promise<LocalSkillState | null>;
   ref?: string;
   base?: string;
   fetchFn: FetchLike;
 }
 
 /**
- * Read the official manifest for the `openclaw` target and compare each skill's
- * offered version against the locally installed `current` map. A skill missing
- * from `current` is reported as `hasUpdate: true`.
+ * Read the official manifest for the `openclaw` target and compare each
+ * skill's offered content (sha256) against its effective local state, read
+ * on demand via `readLocalState`. Any sha256 mismatch — or no local state at
+ * all — is reported as `hasUpdate: true`.
  */
 export async function checkSkillUpdate(
   options: CheckSkillUpdateOptions,
@@ -264,11 +296,14 @@ export async function checkSkillUpdate(
 
   const results: SkillUpdate[] = [];
   for (const [skillId, entry] of Object.entries(targetSkills)) {
-    const current = options.current[skillId] ?? null;
-    const hasUpdate = current === null ? true : isVersionOlder(current, entry.version);
+    const state = await options.readLocalState(skillId);
+    // sha convergence: any byte difference from the official source (or a
+    // missing local file) is an update — upgrade, rollback, or same-version
+    // content fix alike.
+    const hasUpdate = !state || state.sha256 !== entry.sha256;
     results.push({
       skillId,
-      current,
+      current: state?.version ?? null,
       latest: entry.version,
       hasUpdate,
       path: entry.path,
@@ -276,7 +311,12 @@ export async function checkSkillUpdate(
       bytes: entry.bytes,
     });
   }
-  return { ref, results, hasUpdate: results.some((r) => r.hasUpdate) };
+  return {
+    ref,
+    results,
+    hasUpdate: results.some((r) => r.hasUpdate),
+    removedIds: manifest.removed[SKILL_TARGET] ?? [],
+  };
 }
 
 /**
@@ -318,58 +358,50 @@ export function parseSkillFrontmatterVersion(markdown: string): string | null {
   return raw || null;
 }
 
-/** Read one skill's frontmatter `version` from `<dir>/<skillId>/SKILL.md`. */
-async function readSingleSkillVersion(dir: string, skillId: string): Promise<string | null> {
-  try {
-    const md = await fs.readFile(path.join(dir, skillId, "SKILL.md"), "utf8");
-    return parseSkillFrontmatterVersion(md);
-  } catch {
-    return null; // missing / unreadable
-  }
+export interface LocalSkillState {
+  /** Frontmatter `version` of the effective file, or null when unparsable. */
+  version: string | null;
+  /** Lowercase hex sha256 of the effective file's raw bytes. */
+  sha256: string;
 }
 
-/**
- * Read the installed version of each requested skill from a SINGLE directory
- * (`<skillsDir>/<skillId>/SKILL.md`). Missing files / missing frontmatter
- * version are simply omitted (treated as "not installed" → update available).
- */
-export async function readLocalSkillVersions(
-  skillsDir: string,
-  skillIds: readonly string[] = OPENCLAW_SKILL_IDS,
-): Promise<Record<string, string>> {
-  const versions: Record<string, string> = {};
-  for (const skillId of skillIds) {
-    const version = await readSingleSkillVersion(skillsDir, skillId);
-    if (version) versions[skillId] = version;
+async function readSkillStateFromDir(dir: string, skillId: string): Promise<LocalSkillState | null> {
+  try {
+    const buf = await fs.readFile(path.join(dir, skillId, "SKILL.md"));
+    return {
+      version: parseSkillFrontmatterVersion(buf.toString("utf8")),
+      sha256: crypto.createHash("sha256").update(buf).digest("hex"),
+    };
+  } catch {
+    return null;
   }
-  return versions;
 }
 
 /**
- * Read the EFFECTIVE installed version of each skill, mirroring the host's
- * managed-over-bundled precedence (`src/skills/loading/workspace.ts:1220-1239`,
- * managed=3 > bundled=2): use the managed copy's frontmatter `version` when
- * `<managedDir>/<id>/SKILL.md` exists, otherwise fall back to the bundled
- * copy's. A skill present in neither is omitted (→ update available).
+ * Effective local state of ONE skill, mirroring the host's managed-over-bundled
+ * precedence: managed copy if present, else bundled, else null. Called per
+ * remote manifest entry so dynamically delivered extra skills are hashed too
+ * (a static bundled-id list would misreport extras as never-installed).
  */
-export async function readEffectiveSkillVersions(
+export async function readLocalSkillState(
   managedDir: string,
   bundledDir: string | null,
-  skillIds: readonly string[] = OPENCLAW_SKILL_IDS,
-): Promise<Record<string, string>> {
-  const versions: Record<string, string> = {};
-  for (const skillId of skillIds) {
-    const managed = await readSingleSkillVersion(managedDir, skillId);
-    if (managed) {
-      versions[skillId] = managed;
-      continue;
-    }
-    if (bundledDir) {
-      const bundled = await readSingleSkillVersion(bundledDir, skillId);
-      if (bundled) versions[skillId] = bundled;
-    }
+  skillId: string,
+): Promise<LocalSkillState | null> {
+  const managed = await readSkillStateFromDir(managedDir, skillId);
+  if (managed) return managed;
+  if (bundledDir) return readSkillStateFromDir(bundledDir, skillId);
+  return null;
+}
+
+/** True when `<managedDir>/<skillId>/SKILL.md` exists (removal precondition). */
+export async function managedSkillExists(managedDir: string, skillId: string): Promise<boolean> {
+  try {
+    await fs.access(path.join(managedDir, skillId, "SKILL.md"));
+    return true;
+  } catch {
+    return false;
   }
-  return versions;
 }
 
 /**
@@ -458,6 +490,19 @@ export async function atomicWriteSkill(
   }
 }
 
+/**
+ * Delete a tombstoned managed skill: remove `<skillsDir>/<skillId>/SKILL.md`
+ * (the host chokidar-watches the dir; the unlink triggers a snapshot rebuild
+ * that drops the registration) and best-effort remove the now-empty dir.
+ * Deletion is the ONE legitimate delete of a skill path, and ONLY for ids the
+ * official manifest explicitly tombstones. Idempotent.
+ */
+export async function removeManagedSkill(skillsDir: string, skillId: string): Promise<void> {
+  const dir = path.join(skillsDir, skillId);
+  await fs.rm(path.join(dir, "SKILL.md"), { force: true });
+  await fs.rmdir(dir).catch(() => {});
+}
+
 // ---------------------------------------------------------------------------
 // Conservative consent parsing.
 // ---------------------------------------------------------------------------
@@ -530,11 +575,16 @@ export interface PendingSkillTarget {
   bytes: number;
 }
 
+export interface PendingSkillRemoval {
+  skillId: string;
+}
+
 export interface PendingSkillUpdate {
   ownerUserId: string;
   ref: string;
   base?: string;
   updates: PendingSkillTarget[];
+  removals: PendingSkillRemoval[];
   createdAt: number;
   expiresAt: number;
 }
@@ -576,8 +626,13 @@ export interface SkillUpdateLog {
 
 export interface RunSkillUpdateCheckOptions {
   ownerUserId: string;
-  /** Locally installed versions, `{ "<skillId>": "<version>" }`. */
-  localVersions: Record<string, string>;
+  /**
+   * Effective local state of one skill (managed-over-bundled), or null when
+   * not installed. See {@link CheckSkillUpdateOptions.readLocalState}.
+   */
+  readLocalState: (skillId: string) => Promise<LocalSkillState | null>;
+  /** True when `<managedDir>/<skillId>/SKILL.md` exists (removal precondition). */
+  hasManagedSkill: (skillId: string) => Promise<boolean>;
   fetchFn: FetchLike;
   ref?: string;
   base?: string;
@@ -589,7 +644,16 @@ export interface RunSkillUpdateCheckOptions {
 }
 
 function describeUpdate(u: PendingSkillTarget): string {
-  return `「${u.skillId}」v${u.current ?? "无"} → v${u.target}`;
+  if (u.current === null) return `「${u.skillId}」v无 → v${u.target}`;
+  let cmp = -1;
+  try {
+    cmp = compareVersions(u.current, u.target);
+  } catch {
+    cmp = -1; // unparsable local version — show as a plain update
+  }
+  if (cmp === 0) return `「${u.skillId}」v${u.target}(内容修订)`;
+  if (cmp > 0) return `「${u.skillId}」v${u.current} → v${u.target}(回滚)`;
+  return `「${u.skillId}」v${u.current} → v${u.target}`;
 }
 
 /**
@@ -608,7 +672,7 @@ export async function runSkillUpdateCheck(
   }
 
   const outcome = await checkSkillUpdate({
-    current: options.localVersions,
+    readLocalState: options.readLocalState,
     ...(options.ref ? { ref: options.ref } : {}),
     ...(options.base ? { base: options.base } : {}),
     fetchFn: options.fetchFn,
@@ -616,17 +680,19 @@ export async function runSkillUpdateCheck(
 
   const updates: PendingSkillTarget[] = outcome.results
     .filter((r) => r.hasUpdate)
-    .map((r) => ({
-      skillId: r.skillId,
-      current: r.current,
-      target: r.latest,
-      path: r.path,
-      sha256: r.sha256,
-      bytes: r.bytes,
-    }));
-
-  if (updates.length === 0) {
-    options.log?.info?.("clawchat skill-update check: no updates available");
+    .map((r) => ({ skillId: r.skillId, current: r.current, target: r.latest, path: r.path, sha256: r.sha256, bytes: r.bytes }));
+
+  const removals: PendingSkillRemoval[] = [];
+  for (const skillId of outcome.removedIds) {
+    if ((OPENCLAW_SKILL_IDS as readonly string[]).includes(skillId)) {
+      options.log?.info?.(`clawchat skill-update: ignoring tombstone for bundled skill ${skillId}`);
+      continue;
+    }
+    if (await options.hasManagedSkill(skillId)) removals.push({ skillId });
+  }
+
+  if (updates.length === 0 && removals.length === 0) {
+    options.log?.info?.("clawchat skill-update check: nothing to converge");
     return null;
   }
 
@@ -636,15 +702,19 @@ export async function runSkillUpdateCheck(
     ref: outcome.ref,
     ...(options.base ? { base: options.base } : {}),
     updates,
+    removals,
     createdAt: now,
     expiresAt: now + (options.timeoutMs ?? DEFAULT_CONSENT_TIMEOUT_MS),
   };
   options.store.set(record);
 
-  const text = `我的技能有更新:${updates.map(describeUpdate).join(";")}。回复「更新」确认,「取消」忽略。`;
+  const segments: string[] = [];
+  if (updates.length > 0) segments.push(`我的技能有更新:${updates.map(describeUpdate).join(";")}`);
+  if (removals.length > 0) segments.push(`以下技能将下线移除:${removals.map((r) => `「${r.skillId}」`).join("、")}`);
+  const text = `${segments.join(";")}。回复「更新」确认,「取消」忽略。`;
   await options.sendOwnerMessage(text);
   options.log?.info?.(
-    `clawchat skill-update check: asked owner for consent on ${updates.map((u) => u.skillId).join(",")}`,
+    `clawchat skill-update check: asked owner for consent on updates=[${updates.map((u) => u.skillId).join(",")}] removals=[${removals.map((r) => r.skillId).join(",")}]`,
   );
   return record;
 }
@@ -664,8 +734,8 @@ export interface HandleOwnerConsentReplyOptions {
    */
   skillsDir: string;
   sendOwnerMessage: (text: string) => Promise<void>;
-  /** Re-read the on-disk version of a skill for idempotency checks. */
-  readLocalVersion?: (skillId: string) => Promise<string | null>;
+  /** Re-read the on-disk sha of a managed skill for idempotency checks. */
+  readLocalSha?: (skillId: string) => Promise<string | null>;
   log?: SkillUpdateLog;
 }
 
@@ -703,23 +773,24 @@ export async function handleOwnerConsentReply(
   }
 
   // verdict === "affirm"
-  const readLocalVersion =
-    options.readLocalVersion ??
+  const readLocalSha =
+    options.readLocalSha ??
     (async (skillId: string) => {
       try {
-        const md = await fs.readFile(path.join(options.skillsDir, skillId, "SKILL.md"), "utf8");
-        return parseSkillFrontmatterVersion(md);
+        const buf = await fs.readFile(path.join(options.skillsDir, skillId, "SKILL.md"));
+        return crypto.createHash("sha256").update(buf).digest("hex");
       } catch {
         return null;
       }
     });
 
   const applied: PendingSkillTarget[] = [];
+  const removed: PendingSkillRemoval[] = [];
   try {
     for (const update of pending.updates) {
-      // Idempotency: skip a skill already at the target version on disk.
-      const onDisk = await readLocalVersion(update.skillId);
-      if (onDisk === update.target) {
+      // Idempotency: skip a skill whose on-disk bytes already match the target.
+      const onDisk = await readLocalSha(update.skillId);
+      if (onDisk === update.sha256) {
         applied.push(update);
         continue;
       }
@@ -733,9 +804,21 @@ export async function handleOwnerConsentReply(
       );
       await atomicWriteSkill(options.skillsDir, update.skillId, content);
       applied.push(update);
-      options.log?.info?.(
-        `clawchat skill-update: applied ${update.skillId} -> v${update.target} (atomic overwrite)`,
-      );
+      options.log?.info?.(`clawchat skill-update: applied ${update.skillId} -> v${update.target} (atomic overwrite)`);
+    }
+    for (const removal of pending.removals) {
+      // Defensive re-guard: bundled skills must never be deleted, even though
+      // runSkillUpdateCheck already filters them out of removal candidates.
+      // Unreachable in the normal flow; kept as a cheap safety net.
+      if ((OPENCLAW_SKILL_IDS as readonly string[]).includes(removal.skillId)) {
+        options.log?.info?.(
+          `clawchat skill-update: skipped removal of bundled skill ${removal.skillId} (defensive re-guard)`,
+        );
+        continue;
+      }
+      await removeManagedSkill(options.skillsDir, removal.skillId);
+      removed.push(removal);
+      options.log?.info?.(`clawchat skill-update: removed tombstoned skill ${removal.skillId}`);
     }
   } catch (err) {
     // Keep the pending record so the owner can retry with another "更新"; report
@@ -746,7 +829,9 @@ export async function handleOwnerConsentReply(
   }
 
   options.store.clear();
-  const summary = applied.map((u) => `「${u.skillId}」v${u.target}`).join("、");
-  await options.sendOwnerMessage(`✅ 已更新到 ${summary}`);
+  const segments: string[] = [];
+  if (applied.length > 0) segments.push(`已更新到 ${applied.map((u) => `「${u.skillId}」v${u.target}`).join("、")}`);
+  if (removed.length > 0) segments.push(`已移除 ${removed.map((r) => `「${r.skillId}」`).join("、")}`);
+  await options.sendOwnerMessage(`✅ ${segments.join(";")}`);
   return true;
 }