@clawling/clawchat-plugin-openclaw 2026.10.25-1 → 2026.10.31-1

package/dist/src/api-client.js

@@ -117,6 +117,105 @@ export async function authRefresh(opts, params) {
         clearTimeout(timer);
     }
 }
+// A URL starts at an anchored, length-capped scheme. Its authority runs to the
+// first whitespace or `/?#`, and userinfo is everything before the authority's
+// last `@` (fetch accepts quotes, `<`, `>`, backticks and extra `@` there), with
+// no length cap so long credentials fail closed. The host after that `@` ends at
+// quotes and angle brackets as well, and only `scheme://userinfo@host[:port]` is
+// rewritten; scanning continues right after it (or after the scheme when there
+// is no userinfo), so adjacent and embedded URLs are still checked. Redaction is
+// conservative: text glued to a credentialed URL up to a later `@` may be
+// dropped with it. Every search is bounded by one authority, so server-supplied
+// text is processed in linear time.
+const URL_SCHEME = /(?<![a-z0-9+.-])[a-z][a-z0-9+.-]{0,31}:\/\//gi;
+const AUTHORITY_END = /[\s/?#]/g;
+const HOST_END = /[\s"'<>`]/;
+function stripUserinfoFromAuthority(scheme, authority) {
+    try {
+        const url = new URL(`${scheme}${authority}`);
+        return url.host ? `${scheme}${url.host}` : "[redacted-url]";
+    }
+    catch {
+        return "[redacted-url]";
+    }
+}
+function stripUrlUserinfo(text) {
+    let out = "";
+    let copied = 0;
+    for (const scheme of text.matchAll(URL_SCHEME)) {
+        const start = scheme.index ?? 0;
+        if (start < copied)
+            continue;
+        const authorityStart = start + scheme[0].length;
+        AUTHORITY_END.lastIndex = authorityStart;
+        const authorityEnd = AUTHORITY_END.exec(text)?.index ?? text.length;
+        const authority = text.slice(authorityStart, authorityEnd);
+        const at = authority.lastIndexOf("@");
+        if (at < 0)
+            continue;
+        const hostLength = authority.slice(at + 1).search(HOST_END);
+        const hostEnd = hostLength < 0 ? authorityEnd : authorityStart + at + 1 + hostLength;
+        out += text.slice(copied, start) + stripUserinfoFromAuthority(scheme[0], text.slice(authorityStart, hostEnd));
+        copied = hostEnd;
+    }
+    return out + text.slice(copied);
+}
+/** Replaces refresh diagnostic text when the configured base URL carries
+ * credentials: their echoes take too many forms (spaces, no scheme, escaping,
+ * percent-encoding, truncation) to remove reliably, so the free text is not
+ * shown at all. Callers keep the HTTP status and error kind around it. */
+export const REFRESH_DIAGNOSTIC_WITHHELD = "(diagnostic text withheld: base URL contains credentials)";
+/** Replaces refresh diagnostic text when redaction itself fails (fail closed). */
+export const REFRESH_DIAGNOSTIC_FAILED = "(diagnostic text withheld: redaction failed)";
+/** True when a URL carries userinfo: the parser reports a username or
+ * password, or its authority (up to the first `/?#\`) contains `@`. An
+ * unparseable URL containing `@` anywhere counts too (fail closed). */
+export function urlHasUserinfo(url) {
+    if (!url)
+        return false;
+    try {
+        const parsed = new URL(url);
+        if (parsed.username || parsed.password)
+            return true;
+    }
+    catch {
+        if (url.includes("@"))
+            return true;
+    }
+    const schemeEnd = url.indexOf("://");
+    const rest = schemeEnd < 0 ? url : url.slice(schemeEnd + 3);
+    const authorityLength = rest.search(/[/?#\\]/);
+    return (authorityLength < 0 ? rest : rest.slice(0, authorityLength)).includes("@");
+}
+/** Refresh diagnostics use the media redactor's credential patterns, plus exact
+ * in-scope tokens of 8+ characters (shorter values would mangle ordinary words;
+ * real tokens are far longer). Keep this at the first conversion to display text.
+ * URL userinfo is also removed before diagnostics reach display text. When the
+ * configured base URL carries credentials the whole text is replaced with
+ * REFRESH_DIAGNOSTIC_WITHHELD; any failure returns REFRESH_DIAGNOSTIC_FAILED.
+ * This never throws and never falls back to the original text. */
+export function redactRefreshDiagnostics(text, tokens = [], baseUrl) {
+    try {
+        if (urlHasUserinfo(baseUrl))
+            return REFRESH_DIAGNOSTIC_WITHHELD;
+        return redactRefreshText(String(text), tokens);
+    }
+    catch {
+        return REFRESH_DIAGNOSTIC_FAILED;
+    }
+}
+function redactRefreshText(text, tokens) {
+    for (const token of tokens) {
+        const value = token?.trim();
+        if (value && value.length >= 8)
+            text = text.split(value).join("[redacted]");
+    }
+    // JSON body snippets may contain an escaped diagnostic string.
+    return stripUrlUserinfo(text.replace(/\\"/g, '"'))
+        .replace(/\b(bearer)\s+[A-Za-z0-9._~+/=-]+/gi, "$1 [redacted]")
+        .replace(/("?\b(?:authorization|access[_-]?token|refresh[_-]?token|token|api[_-]?key|apikey|password|passwd|secret|signature|x-amz-signature|x-amz-credential)\b"?\s*[:=]\s*)"?[^"',\s&}]+"?/gi, '$1"[redacted]"')
+        .replace(/\beyJ[A-Za-z0-9._~+/=-]{10,}/g, "[redacted]");
+}
 async function authRefreshAttempt(baseUrl, fetchImpl, params, signal) {
     let res;
     try {
@@ -136,7 +235,7 @@ async function authRefreshAttempt(baseUrl, fetchImpl, params, signal) {
         // Network error / timeout / DNS — TRANSIENT (no rotation committed).
         return {
             kind: "transient",
-            message: `refresh fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+            message: `refresh fetch failed: ${redactRefreshDiagnostics(err instanceof Error ? err.message : String(err), [params.refreshToken, params.accessToken], baseUrl)}`,
         };
     }
     if (res.status !== 200) {
@@ -150,7 +249,12 @@ async function authRefreshAttempt(baseUrl, fetchImpl, params, signal) {
                 const message = (typeof parsed.msg === "string" && parsed.msg) ||
                     (typeof parsed.message === "string" && parsed.message) ||
                     `refresh http ${res.status} code=10003`;
-                return { kind: "permanent", code: CODE_INVALID_REFRESH, message };
+                const detail = redactRefreshDiagnostics(message, [params.refreshToken, params.accessToken], baseUrl);
+                return {
+                    kind: "permanent",
+                    code: CODE_INVALID_REFRESH,
+                    message: detail === REFRESH_DIAGNOSTIC_WITHHELD ? `refresh http ${res.status} code=10003 ${detail}` : detail,
+                };
             }
         }
         catch {
@@ -159,7 +263,7 @@ async function authRefreshAttempt(baseUrl, fetchImpl, params, signal) {
         return {
             kind: "transient",
             status: res.status,
-            message: `refresh http ${res.status} ${text.slice(0, 200)}`,
+            message: `refresh http ${res.status} ${redactRefreshDiagnostics(text, [params.refreshToken, params.accessToken], baseUrl).slice(0, 200)}`,
         };
     }
     const text = await res.text().catch(() => "");
@@ -171,9 +275,10 @@ async function authRefreshAttempt(baseUrl, fetchImpl, params, signal) {
         parsed = undefined;
     }
     const code = typeof parsed?.code === "number" ? parsed.code : Number.NaN;
-    const message = (typeof parsed?.msg === "string" && parsed.msg) ||
+    const detail = redactRefreshDiagnostics((typeof parsed?.msg === "string" && parsed.msg) ||
         (typeof parsed?.message === "string" && parsed.message) ||
-        `code=${code}`;
+        `code=${code}`, [params.refreshToken, params.accessToken], baseUrl);
+    const message = detail === REFRESH_DIAGNOSTIC_WITHHELD ? `code=${code} ${detail}` : detail;
     if (!Number.isFinite(code)) {
         // 200 with no usable envelope — treat as transient (do not auto-logout).
         return { kind: "transient", status: 200, message: "refresh: missing numeric code" };
@@ -365,6 +470,17 @@ export function createOpenclawClawlingApiClient(opts) {
         }
         return obj;
     }
+    function parseAvatarUploadResult(data, path) {
+        const obj = data;
+        if (!obj ||
+            typeof obj.url !== "string" ||
+            obj.url === "" ||
+            typeof obj.mime !== "string" ||
+            typeof obj.size !== "number") {
+            throw new ClawlingApiError("api", "invalid upload response: missing required avatar fields", { path });
+        }
+        return { url: obj.url, size: obj.size, mime: obj.mime };
+    }
     function isLivewareView(v) {
         if (!v || typeof v !== "object" || Array.isArray(v))
             return false;
@@ -718,7 +834,8 @@ export function createOpenclawClawlingApiClient(opts) {
             });
             const fd = new FormData();
             fd.set("file", file);
-            return await call("POST", "/v1/files/upload-url", { body: fd });
+            const data = await call("POST", "/v1/files/upload-url", { body: fd });
+            return parseAvatarUploadResult(data, "/v1/files/upload-url");
         },
         async reportPlugin(input, opts) {
             const path = opts?.authenticated

package/dist/src/host-tools-guard.js

@@ -15,8 +15,8 @@ import { clawChatDbPathForStateDir, getClawChatStore } from "./storage.js";
 import { resolveOwnerIdentity } from "./owner-identity.js";
 import { getRegisteredClawChatToolNames } from "./tools.js";
 import { APPROVAL_ROUTE_WARNINGS, listActiveAccountIds, resolveApprovalRoute, storedIdentityLookup, } from "./approval-route.js";
-import { bindOrchestrationOriginCall, bindAwaitingTurnRun, grantsForRun, readTurnGrantRun, isOwnerSideRun, isNonOwnerSideSession, hasUnattributedTurn, requestOriginForRun, bindToolRequestCall } from "./turn-grants.js";
-import { GRANT_BLOCK_MESSAGE, GRANT_INTERSECTION_BLOCK_MESSAGE, GRANT_ASK_DENIED_MESSAGE, GRANT_DENIED_MESSAGE, GRANT_ASK_UNAVAILABLE_MESSAGE, GRANT_NOT_AVAILABLE_MESSAGE, GRANT_CROSS_SESSION_MESSAGE, evaluateToolGrant, isCompiledGrants, } from "./tool-grants.js";
+import { bindOrchestrationOriginCall, bindAwaitingTurnRun, grantsForRun, readTurnGrantRun, isOwnerSideRun, isNonOwnerSideSession, isNonOwnerBoundRun, hasOwnerDowngradingOverlap, ownerDowngradeTrigger, hasUnattributedTurn, requestOriginForRun, bindToolRequestCall } from "./turn-grants.js";
+import { OWNER_DOWNGRADED_MESSAGE, GRANT_BLOCK_MESSAGE, GRANT_INTERSECTION_BLOCK_MESSAGE, GRANT_ASK_DENIED_MESSAGE, GRANT_DENIED_MESSAGE, GRANT_ASK_UNAVAILABLE_MESSAGE, GRANT_NOT_AVAILABLE_MESSAGE, GRANT_CROSS_SESSION_MESSAGE, evaluateToolGrant, isCompiledGrants, } from "./tool-grants.js";
 import { AUTHORIZATION_TOOLS, OWNER_ONLY_TOOLS, OWNER_TURN_STRICT_TOOLS, WIDGET_OWNER_ONLY_MESSAGE, TOOL_CAPABILITIES, canonicalToolName, hostToolTargetsCurrentSession, isCrossChatCall, resolveCrossChatGate } from "./tool-capabilities.js";
 import { recordTurnArtifactCall, registerTurnArtifacts } from "./turn-artifacts.js";
 export const BLOCK_MESSAGE = "This tool is not available here: only your owner's direct chat may use host tools on this machine. Do not try to reach them another way; answer without them, or tell the person to ask your owner.";
@@ -59,8 +59,22 @@ export function hasLocalPathArgument(value, field = "") {
         return value.some(item => hasLocalPathArgument(item, field));
     return Boolean(value && typeof value === "object" && Object.entries(value).some(([key, item]) => hasLocalPathArgument(item, PATH_FIELD.test(field) ? field : key)));
 }
+const ownerDowngradedDecision = () => ({ block: true, blockReason: OWNER_DOWNGRADED_MESSAGE, reasonCode: "owner-downgraded" });
+function ownerOverlapDowngraded(input, includeNotices = false) {
+    const parsed = parseClawChatSessionKey(input.sessionKey);
+    return Boolean(parsed && classifyChat({ ...parsed, ownerDirectConversationId: input.ownerDirectConversationId }) === "owner"
+        && input.ownerUserId?.trim() && input.senderId === input.ownerUserId
+        && (includeNotices ? isNonOwnerSideSession(input.sessionKey)
+            : !isNonOwnerBoundRun(input.sessionKey, input.runId) && hasOwnerDowngradingOverlap(input.sessionKey)));
+}
 /** Pure decision for one tool call. `undefined` lets the call run. */
 export function decideHostToolCall(input) {
+    const decision = decideHostToolCallInner(input);
+    return decision && "block" in decision && (ownerOverlapDowngraded(input)
+        || (OWNER_ONLY_TOOLS.includes(canonicalToolName(input.toolName)) && ownerOverlapDowngraded(input, true)))
+        ? ownerDowngradedDecision() : decision;
+}
+function decideHostToolCallInner(input) {
     if (input.toolName === "clawchat_tool_request") {
         const origin = input.sessionKey ? requestOriginForRun(input.sessionKey, input.runId) : undefined;
         const parsed = parseClawChatSessionKey(input.sessionKey);
@@ -102,7 +116,12 @@ export function decideHostToolCall(input) {
     // cannot start local turns in other sessions (cross-session). Under that
     // audited premise, only the owner can initiate a snapshot-free turn here.
     // A new host tool missing from the audit could break it; keep it current.
-    if ((ownerTurn && !isNonOwnerSideSession(input.sessionKey))
+    // Plugin notices in flight (no third-party text) keep that access only for
+    // a run the host attributes to the owner; the notice's own run never gets it.
+    const ownerExempt = ownerTurn && !isNonOwnerBoundRun(input.sessionKey, input.runId)
+        && (!isNonOwnerSideSession(input.sessionKey) || (!hasOwnerDowngradingOverlap(input.sessionKey)
+            && Boolean(input.ownerUserId?.trim()) && input.senderId === input.ownerUserId));
+    if (ownerExempt
         || (parsed.kind === "group" && isOwnerSideRun(input.sessionKey, input.runId)))
         return undefined;
     const publicTools = nonOwnerToolAllowlist(input.publicTools);
@@ -322,6 +341,25 @@ export function registerHostToolsGuard(api, options = {}) {
             return { ready: false, reason: "not-applied" };
         }
     };
+    const loggedOwnerDowngrades = new Set();
+    // A downgraded owner run has no request origin; tell it the truth instead of the
+    // generic refusal. Every other origin-less call keeps the plain block.
+    const ownerRequestDowngraded = (sessionKey, runId, requester) => {
+        try {
+            const accountId = clawChatSessionAccountId(sessionKey);
+            if (!accountId || !requester?.senderId || (requester.channel && requester.channel !== CHANNEL_ID))
+                return false;
+            const account = resolveOpenclawClawlingAccount(readLiveConfig(), accountId);
+            const ownerUserId = options.ownerUserId ? options.ownerUserId(accountId)
+                : resolveOwnerIdentity(openStore(), accountId, account.ownerUserId).ownerUserId;
+            return ownerOverlapDowngraded({ toolName: "clawchat_tool_request", params: {}, sessionKey, runId,
+                senderId: requester.senderId, ownerUserId: ownerUserId ?? undefined,
+                ownerDirectConversationId: lookupOwnerConversation(accountId), registeredTools: new Set() });
+        }
+        catch {
+            return false;
+        }
+    };
     api.on("before_tool_call", (event, sdkCtx) => {
         // `requester` is host 2026.8.1+ (the floor); the development SDK types predate it.
         const ctx = sdkCtx;
@@ -339,6 +377,8 @@ export function registerHostToolsGuard(api, options = {}) {
                 }
                 if (event.toolName === "clawchat_tool_request") {
                     const origin = sessionKey ? requestOriginForRun(sessionKey, runId) : undefined;
+                    if (!origin && sessionKey && ownerRequestDowngraded(sessionKey, runId, ctx.requester))
+                        return ownerDowngradedDecision();
                     if (!origin || !sessionKey || !ctx.requester?.senderId
                         || (ctx.requester.channel && ctx.requester.channel !== CHANNEL_ID)
                         || (ctx.requester.accountId && normalizeOpenclawClawlingAccountId(ctx.requester.accountId) !== origin.accountId)
@@ -445,14 +485,12 @@ export function registerHostToolsGuard(api, options = {}) {
                 const account = resolveOpenclawClawlingAccount(readLiveConfig(), accountId);
                 nonOwnerToolAllowlist(account.publicTools, api.logger);
                 let ownerUserId = null;
-                if (AUTHORIZATION_TOOLS.includes(event.toolName) || OWNER_ONLY_TOOLS.includes(canonicalToolName(event.toolName))) {
-                    try {
-                        ownerUserId = options.ownerUserId ? options.ownerUserId(accountId)
-                            : resolveOwnerIdentity(openStore(), accountId, account.ownerUserId).ownerUserId;
-                    }
-                    catch { /* A missing owner identity cannot authorize grant tools. */ }
+                try {
+                    ownerUserId = options.ownerUserId ? options.ownerUserId(accountId)
+                        : resolveOwnerIdentity(openStore(), accountId, account.ownerUserId).ownerUserId;
                 }
-                return decideHostToolCall({
+                catch { /* Missing identity cannot authorize management or identify an owner downgrade. */ }
+                const input = {
                     toolName: event.toolName,
                     params: event.params ?? {},
                     sessionKey,
@@ -467,7 +505,8 @@ export function registerHostToolsGuard(api, options = {}) {
                     ownerUserId: ownerUserId ?? undefined,
                     senderId: requester?.senderId,
                     approvalRoute: approvalRoute(accountId, [...grantsForRun(sessionKey, runId).values()].includes("ask")),
-                });
+                };
+                return decideHostToolCall(input);
             }
             catch {
                 warn("handler-exception");
@@ -475,8 +514,18 @@ export function registerHostToolsGuard(api, options = {}) {
             }
         })();
         const result = decision && "block" in decision && OWNER_ONLY_TOOLS.includes(canonicalToolName(event.toolName))
-            && decision.reasonCode !== "owner-turn-only"
+            && decision.reasonCode !== "owner-turn-only" && decision.reasonCode !== "owner-downgraded"
             ? { block: true, reasonCode: "owner-turn-only", blockReason: OWNER_TURN_STRICT_TOOLS.includes(canonicalToolName(event.toolName)) ? WIDGET_OWNER_ONLY_MESSAGE : ownerOnlyMessage(false) } : decision;
+        if (result && "block" in result && result.reasonCode === "owner-downgraded" && ctx?.sessionKey) {
+            const runId = ctx.runId ?? event.runId;
+            const key = JSON.stringify([ctx.sessionKey.trim().toLowerCase(), runId]);
+            if (!loggedOwnerDowngrades.has(key)) {
+                if (loggedOwnerDowngrades.size >= 256)
+                    loggedOwnerDowngrades.clear();
+                loggedOwnerDowngrades.add(key);
+                api.logger.info(`owner_downgrade reason=overlap trigger=${ownerDowngradeTrigger(ctx.sessionKey)}`);
+            }
+        }
         recordTurnArtifactCall(event, ctx, result === undefined || "requireApproval" in result);
         return result;
     });

package/dist/src/liveware-cli.js

@@ -1,9 +1,22 @@
 import fs from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
 import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
 import { normalizeOpenclawClawlingAccountId } from "./config.js";
 export const LIVEWARE_BASE_URL = "https://media.clawling.chat/liveware/";
+// The trust anchor is this package, not the download host. Updating the CLI
+// requires updating these hashes in a plugin release.
+export const LIVEWARE_CLI_PIN = {
+    build: "2026-09-21",
+    sha256: {
+        "liveware-darwin-amd64": "28c63d371115889cd8ebeed916af0d5ede62e10016ae34a8984de31ec49d00fe",
+        "liveware-darwin-arm64": "eebc9f9a881f9a4da3eb81559290581f0054d15b94eb8c0d2dd21e9472169765",
+        "liveware-linux-amd64": "bbbf7c0b74e5633cf869ea3af78997d5ec0f57f3253f1fb3c3cdd75ead5cebba",
+        "liveware-linux-arm64": "691b79a8f346e10780e8270d9b759bd749d1df5a3d08bf033c66765c470d6a15",
+        "liveware-windows-amd64.exe": "b5fe6fa02cf23d0101af20cc3f8c936ac5d6f32a13896bc1c14622089e3504a1",
+    },
+};
 // A non-default User-Agent is required: the CDN (Cloudflare) returns 403 for
 // known scripting/default UAs, so download requests must identify themselves.
 const LIVEWARE_USER_AGENT = "clawchat-liveware-installer";
@@ -92,7 +105,7 @@ export function platformAssets(plat = process.platform, arch = process.arch) {
     const cpu = arch === "x64" ? "amd64" : arch === "arm64" ? "arm64" : null;
     if (!os || !cpu)
         return null;
-    // Windows only ships an amd64 build, published with a .exe suffix.
+    // Only the Windows amd64 build is supported here, with a .exe suffix.
     if (os === "windows") {
         if (cpu !== "amd64")
             return null;
@@ -116,59 +129,233 @@ function findOnPath(name) {
     }
     return null;
 }
-/**
- * Resolve the liveware executable to invoke:
- *  1. on PATH        → "liveware" (let the OS resolve it)
- *  2. downloaded dir → absolute path
- *  3. otherwise      → null
- */
+const managedVerifications = new Map();
+function fileIdentity(stat) {
+    return [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+}
+/** PATH is user-managed; downloaded executables must pass the package pin.
+ * Successful hashes are reused only while the full stat identity is unchanged. */
 export function resolveLivewarePath(stateDir) {
     const name = livewareBinaryName();
     if (findOnPath(name))
         return name;
-    const local = path.join(livewareDir(stateDir), name);
+    const assets = platformAssets();
+    const digest = assets && LIVEWARE_CLI_PIN.sha256[assets.liveware];
+    if (!digest)
+        return null;
+    const local = path.resolve(livewareDir(stateDir), name);
     try {
         fs.accessSync(local, fs.constants.X_OK);
+        const stat = fs.statSync(local);
+        if (!stat.isFile())
+            return null;
+        const cached = managedVerifications.get(local);
+        if (cached?.digest === digest && cached.identity === fileIdentity(stat))
+            return local;
+        managedVerifications.delete(local);
+        // Hash an open descriptor so the memo identifies the bytes actually read.
+        const file = fs.openSync(local, "r");
+        let identity;
+        let actualDigest;
+        try {
+            identity = fileIdentity(fs.fstatSync(file));
+            actualDigest = sha256(fs.readFileSync(file));
+            if (identity !== fileIdentity(fs.fstatSync(file)))
+                return null;
+        }
+        finally {
+            fs.closeSync(file);
+        }
+        if (actualDigest !== digest || identity !== fileIdentity(fs.statSync(local)))
+            return null;
+        managedVerifications.set(local, { identity, digest });
         return local;
     }
     catch {
+        managedVerifications.delete(local);
         return null;
     }
 }
-async function downloadTo(url, dest) {
-    const res = await fetch(url, { headers: { "user-agent": LIVEWARE_USER_AGENT } });
-    if (!res.ok)
-        throw new Error(`download ${url} failed: HTTP ${res.status}`);
-    const buf = Buffer.from(await res.arrayBuffer());
-    if (buf.length === 0)
-        throw new Error(`download ${url} returned empty body`);
-    const tmp = `${dest}.tmp`;
-    await fs.promises.writeFile(tmp, buf);
-    await fs.promises.chmod(tmp, 0o755);
-    await fs.promises.rename(tmp, dest);
+class DownloadError extends Error {
+    retryable;
+    constructor(message, retryable) {
+        super(message);
+        this.retryable = retryable;
+    }
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+// Processes can race safely: rename only publishes verified bytes, and failure
+// cleanup re-verifies the file it actually quarantined rather than an old read.
+const livewareInstalls = new Map();
+async function syncDirectory(dir) {
+    try {
+        const file = await fs.promises.open(dir, "r");
+        try {
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch { /* Best effort directory durability across platforms/filesystems. */ }
+}
+async function readManagedFile(target) {
+    let file;
+    try {
+        file = await fs.promises.open(target, "r");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    try {
+        const before = fileIdentity(await file.stat());
+        const bytes = await file.readFile();
+        const after = fileIdentity(await file.stat());
+        return { identity: after, digest: before === after ? sha256(bytes) : null };
+    }
+    finally {
+        await file.close();
+    }
+}
+async function quarantineRejectedCache(target, digest) {
+    // Each attempt takes a fresh hash/identity, including after a failed download.
+    // A changed target is re-verified rather than moved using a stale decision.
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const snapshot = await readManagedFile(target);
+        if (!snapshot || snapshot.digest === digest)
+            return;
+        if (snapshot.digest === null)
+            continue;
+        const rejected = path.join(path.dirname(target), `.${path.basename(target)}.${randomUUID()}.rejected`);
+        try {
+            if (fileIdentity(await fs.promises.lstat(target)) !== snapshot.identity)
+                continue;
+            await fs.promises.rename(target, rejected);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        try {
+            // Recheck what moved: publication can still race the final lstat/rename.
+            if ((await readManagedFile(rejected))?.digest === digest) {
+                try {
+                    await fs.promises.link(rejected, target);
+                }
+                catch (err) {
+                    if (err.code !== "EEXIST")
+                        throw err;
+                }
+            }
+        }
+        finally {
+            await fs.promises.unlink(rejected);
+            await syncDirectory(path.dirname(target));
+        }
+        return;
+    }
+    throw new Error("liveware CLI cache kept changing during quarantine; skipping removal");
+}
+async function downloadTo(url, dest, digest, fetchImpl, timeoutMs) {
+    const tmp = `${dest}.${randomUUID()}.tmp`;
+    try {
+        // The signal remains active during arrayBuffer(), covering the entire body.
+        let buf;
+        try {
+            const res = await fetchImpl(url, {
+                headers: { "user-agent": LIVEWARE_USER_AGENT }, signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (!res.ok) {
+                await res.body?.cancel().catch(() => { });
+                throw new DownloadError(`liveware download HTTP ${res.status}`, res.status === 429 || (res.status >= 500 && res.status < 600));
+            }
+            buf = Buffer.from(await res.arrayBuffer());
+        }
+        catch (err) {
+            if (err instanceof DownloadError)
+                throw err;
+            throw new DownloadError(`liveware download request failed: ${String(err)}`, true);
+        }
+        if (sha256(buf) !== digest)
+            throw new DownloadError("liveware download SHA-256 mismatch", false);
+        const file = await fs.promises.open(tmp, "wx", 0o600);
+        try {
+            await file.writeFile(buf);
+            await file.chmod(0o755);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await fs.promises.rename(tmp, dest);
+        await syncDirectory(path.dirname(dest));
+    }
+    finally {
+        await fs.promises.rm(tmp, { force: true });
+    }
+}
+async function installLivewareCli(target, asset, digest, opts) {
+    const dir = path.dirname(target);
+    const isVerified = async () => (await readManagedFile(target))?.digest === digest;
+    if (await isVerified())
+        return;
+    // Quarantine only the unchanged file we just hashed as invalid. Execution
+    // independently verifies the managed copy, even if cleanup is unavailable.
+    await quarantineRejectedCache(target, digest);
+    if (await isVerified())
+        return;
+    await fs.promises.mkdir(dir, { recursive: true });
+    const delay = opts.delay ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    try {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                await downloadTo(LIVEWARE_BASE_URL + asset, target, digest, opts.fetchImpl ?? fetch, opts.timeoutMs ?? 120_000);
+                break;
+            }
+            catch (err) {
+                if (attempt === 1 || !(err instanceof DownloadError) || !err.retryable)
+                    throw err;
+                await delay(2_000);
+            }
+        }
+    }
+    catch (err) {
+        await quarantineRejectedCache(target, digest);
+        throw err;
+    }
+    opts.log?.debug?.(`clawchat-plugin-openclaw: liveware CLI downloaded to ${dir}`);
 }
 /**
- * Startup hook: ensure the liveware CLI is available, downloading it when not.
- * Fire-and-forget — never throws; logs and returns on any failure.
+ * Startup verifies the managed cache; per-tool resolution memoizes verified file identities.
+ * User-managed PATH executables take precedence and are not hashed.
+ * Never throws: a failed install is logged and skipped.
  */
 export async function ensureLivewareCli(opts = {}) {
     const { stateDir, log } = opts;
     try {
-        const name = livewareBinaryName();
+        const platform = opts.platform ?? process.platform;
+        const name = livewareBinaryName(platform);
         if (findOnPath(name))
-            return; // PATH wins
-        const dir = livewareDir(stateDir);
-        const target = path.join(dir, name);
-        if (fs.existsSync(target))
             return;
-        const assets = platformAssets();
-        if (!assets) {
-            log?.warn?.(`clawchat-plugin-openclaw: unsupported platform ${process.platform}/${process.arch}; skipping liveware download`);
+        const target = path.resolve(livewareDir(stateDir), name);
+        const assets = platformAssets(platform, opts.arch ?? process.arch);
+        const digest = assets && LIVEWARE_CLI_PIN.sha256[assets.liveware];
+        if (!assets || !digest) {
+            log?.warn?.(`clawchat-plugin-openclaw: unsupported or unpinned platform ${platform}/${opts.arch ?? process.arch}; skipping liveware download`);
             return;
         }
-        await fs.promises.mkdir(dir, { recursive: true });
-        await downloadTo(LIVEWARE_BASE_URL + assets.liveware, path.join(dir, name));
-        log?.debug?.(`clawchat-plugin-openclaw: liveware CLI downloaded to ${dir}`);
+        let install = livewareInstalls.get(target);
+        if (!install) {
+            install = installLivewareCli(target, assets.liveware, digest, opts)
+                .finally(() => { livewareInstalls.delete(target); });
+            livewareInstalls.set(target, install);
+        }
+        await install;
     }
     catch (err) {
         log?.warn?.(`clawchat-plugin-openclaw: liveware CLI download skipped: ${String(err)}`);

package/dist/src/liveware-sample.js

@@ -690,7 +690,7 @@ export function loadIntroText(appDir, language) {
 const DEFAULT_SAMPLE_PORT = 43110;
 const RESTART_WINDOW_MS = 30 * 60 * 1000;
 const MAX_RESTARTS_PER_WINDOW = 5;
-const INTRO_RETRY_DELAY_MS = 30_000;
+const INTRO_RETRY_DELAYS_MS = [2_000, 5_000, 10_000, 30_000];
 const INTRO_MAX_TRIES = 20;
 // Backoff for transient start() failures (template CDN 429s, network blips):
 // a one-shot bootstrap would otherwise stay dormant until the next restart.
@@ -1130,8 +1130,8 @@ export class LivewareSampleSupervisor {
         }
     }
     /** Deliver the intro chat message; retries while the WS client is not ready. */
-    async deliverIntro(tryIndex = 0) {
-        if (this.stopped)
+    async deliverIntro(tryIndex = 0, generation = this.generation) {
+        if (this.stopped || generation !== this.generation)
             return;
         const { deps } = this;
         let delivered = false;
@@ -1142,6 +1142,8 @@ export class LivewareSampleSupervisor {
         catch (err) {
             deps.log?.debug?.(`liveware-sample: intro send error: ${String(err)}`);
         }
+        if (this.stopped || generation !== this.generation)
+            return;
         if (delivered) {
             deps.store.markLivewareSampleIntroSent({ platform: deps.platform, accountId: deps.accountId });
             return;
@@ -1150,6 +1152,6 @@ export class LivewareSampleSupervisor {
             deps.log?.debug?.("liveware-sample: intro not delivered; will retry next boot");
             return;
         }
-        this.schedule(() => { void this.deliverIntro(tryIndex + 1); }, INTRO_RETRY_DELAY_MS);
+        this.schedule(() => { void this.deliverIntro(tryIndex + 1, generation); }, INTRO_RETRY_DELAYS_MS[Math.min(tryIndex, INTRO_RETRY_DELAYS_MS.length - 1)]);
     }
 }