@clawling/clawchat-plugin-openclaw 2026.10.13-1 → 2026.10.19-1

package/dist/src/approval-route.js

@@ -7,7 +7,7 @@
 // would answer in the chat the turn came from — the group — so the plugin
 // manages one exact block instead: `mode: "targets"`, one target (the owner's
 // direct chat on the one ClawChat account), and a `sessionFilter` that matches
-// ClawChat group sessions only.
+// ClawChat sessions.
 //
 // The plugin writes that block only when the host has none, and later rewrites
 // or removes only a block of exactly that shape. Any other `approvals.plugin`
@@ -16,9 +16,11 @@
 // config holds the managed block for this account and its current owner chat.
 import fs from "node:fs";
 import path from "node:path";
+import { HOST_FLOOR, hostAtLeast } from "./host-version.js";
 import { CHANNEL_ID, listOpenclawClawlingAccountIds, resolveOpenclawClawlingAccount } from "./config.js";
-/** Substring of every ClawChat group session key (`agent:<id>:<channel>:group:<chat>`). */
-export const APPROVAL_SESSION_FILTER = `:${CHANNEL_ID}:group:`;
+/** Substring of every ClawChat session key. */
+export const APPROVAL_SESSION_FILTER = `:${CHANNEL_ID}:`;
+const LEGACY_APPROVAL_SESSION_FILTER = `:${CHANNEL_ID}:group:`;
 function isRec(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -79,7 +81,7 @@ export function readApprovalsPluginState(cfg) {
     if (block.enabled !== true || block.mode !== "targets")
         return { kind: "foreign" };
     const filter = block.sessionFilter;
-    if (!Array.isArray(filter) || filter.length !== 1 || filter[0] !== APPROVAL_SESSION_FILTER) {
+    if (!Array.isArray(filter) || filter.length !== 1 || ![APPROVAL_SESSION_FILTER, LEGACY_APPROVAL_SESSION_FILTER].includes(filter[0])) {
         return { kind: "foreign" };
     }
     const targets = block.targets;
@@ -94,7 +96,8 @@ export function readApprovalsPluginState(cfg) {
     const accountId = typeof target.accountId === "string" ? target.accountId.trim() : "";
     if (!to || !accountId)
         return { kind: "foreign" };
-    return { kind: "managed", target: { to, accountId } };
+    return { kind: "managed", target: { to, accountId },
+        ...(filter[0] === LEGACY_APPROVAL_SESSION_FILTER ? { needsMigration: true } : {}) };
 }
 /**
  * The target the managed block should hold now, or `null` when none should
@@ -126,7 +129,7 @@ export function planApprovalsPluginWrite(current, desired) {
     if (current.kind === "managed" && norm(current.target.accountId) !== norm(desired.accountId)) {
         return { action: "remove" };
     }
-    if (current.kind === "managed" &&
+    if (current.kind === "managed" && !current.needsMigration &&
         norm(current.target.to) === norm(desired.to) &&
         norm(current.target.accountId) === norm(desired.accountId)) {
         return { action: "none" };
@@ -166,13 +169,34 @@ export function resolveApprovalRoute(input) {
     const state = readApprovalsPluginState(input.liveConfig);
     if (state.kind === "foreign")
         return { ready: false, reason: "foreign-config" };
-    if (state.kind !== "managed" ||
+    if (state.kind !== "managed" || state.needsMigration ||
         norm(state.target.accountId) !== norm(input.accountId) ||
         norm(state.target.to) !== norm(owner)) {
         return { ready: false, reason: "not-applied" };
     }
     return { ready: true, target: state.target };
 }
+/** Establishability, independent of whether an ask row has triggered reconciliation yet.
+ * Plugin approvals are separate from exec approvals (agent-tools.before-tool-call.approval.ts).
+ * A foreign/disabled forwarding block cannot be taken over by this plugin.
+ */
+export function canAskEachTime(accountId, input) {
+    try {
+        if (!hostAtLeast(input.hostVersion, HOST_FLOOR))
+            return false;
+        const desired = desiredApprovalTarget({ activeAccountIds: input.activeAccountIds,
+            approveAccountIds: [accountId], ownerConversation: id => id === accountId ? input.ownerConversationId : null });
+        if (!desired.target)
+            return false;
+        const state = readApprovalsPluginState(input.liveConfig);
+        if (state.kind === "foreign" || (state.kind === "managed" && norm(state.target.accountId) !== norm(accountId)))
+            return false;
+        return input.canWriteConfig || resolveApprovalRoute({ ...input, accountId, approve: true }).ready;
+    }
+    catch {
+        return false;
+    }
+}
 export const APPROVAL_ROUTE_WARNINGS = {
     "not-approve": "",
     "multiple-accounts": "non-owner-host-tools approve needs exactly one ClawChat account on this gateway; group host-tool calls stay blocked",
@@ -193,7 +217,17 @@ export async function reconcileApprovalsPlugin(params) {
         knownActive: params.knownActive,
         hasStoredIdentity: params.hasStoredIdentity,
     });
-    const approveIds = active.filter((id) => resolveOpenclawClawlingAccount(cfg, id).nonOwnerHostTools === "approve");
+    const approveIds = active.filter((id) => {
+        const account = resolveOpenclawClawlingAccount(cfg, id);
+        if (account.nonOwnerHostTools === "approve")
+            return true;
+        try {
+            return account.toolGrants === "on" && params.hasActiveAskGrant?.(id) === true;
+        }
+        catch {
+            return false;
+        }
+    });
     const desired = desiredApprovalTarget({
         activeAccountIds: active,
         approveAccountIds: approveIds,
@@ -209,7 +243,7 @@ export async function reconcileApprovalsPlugin(params) {
     if (planned.action === "none")
         return "none";
     const guardKey = planned.action === "set"
-        ? `set:${norm(planned.target.accountId)}:${norm(planned.target.to)}`
+        ? `set:${APPROVAL_SESSION_FILTER}:${norm(planned.target.accountId)}:${norm(planned.target.to)}`
         : "remove";
     try {
         if (params.writeGuard?.seen(guardKey)) {

package/dist/src/channel.setup.js

@@ -16,6 +16,7 @@ const CLEAR_BASE_FIELDS = [
     "forwardThinking",
     "forwardToolCalls",
     "richInteractions",
+    "tool-grants",
     "enabled",
 ];
 /**

package/dist/src/clawchat-memory.js

@@ -1,9 +1,219 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import os from "node:os";
 import { randomUUID } from "node:crypto";
 import { getDefaultGroupBioPrompt, getDefaultOwnerBehaviorPrompt } from "./plugin-prompts.js";
 const metadataStart = "<!-- clawchat:metadata:start -->";
 const metadataEnd = "<!-- clawchat:metadata:end -->";
+/** Exported so callers/tests can set a shorter bounded wait when needed. */
+export const CLAWCHAT_MEMORY_LOCK_TIMING = {
+    timeoutMs: 5_000,
+    retryMs: 25,
+    staleMs: 600_000,
+};
+const memoryFileLockQueue = new Map();
+const heldMemoryLockTokens = new Set();
+async function unlinkMemoryLockArtifact(filePath) {
+    await fs.unlink(filePath).catch(error => {
+        if (error.code !== "ENOENT")
+            throw error;
+    });
+}
+let memoryLockTestHooks;
+/** @internal Deterministic interleavings for tests; undefined in production. */
+export function __setClawChatMemoryLockTestHooks(hooks) {
+    memoryLockTestHooks = hooks;
+}
+async function readMemoryLockState(filePath, staleMs) {
+    try {
+        const stat = await fs.lstat(filePath);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`Unsafe clawchat memory lock: ${filePath}`);
+        const content = await fs.readFile(filePath, "utf8");
+        let payload = {};
+        try {
+            const parsed = JSON.parse(content);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                payload = parsed;
+        }
+        catch { /* Legacy or malformed payloads can only expire by age. */ }
+        const timestamp = typeof payload.timestamp === "number" && Number.isFinite(payload.timestamp)
+            ? Math.max(payload.timestamp, stat.mtimeMs) : stat.mtimeMs;
+        let stale = Date.now() - timestamp > staleMs;
+        const { pid, token, host } = payload;
+        if (host === os.hostname() && typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0) {
+            if (pid === process.pid && typeof token === "string" && !heldMemoryLockTokens.has(token))
+                stale = true;
+            try {
+                process.kill(pid, 0);
+            }
+            catch (error) {
+                if (error.code === "ESRCH")
+                    stale = true;
+            }
+        }
+        return { content, stale };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function removeMemoryGuardIfMatching(guardPath, expected) {
+    try {
+        if (await fs.readFile(guardPath, "utf8") === expected)
+            await unlinkMemoryLockArtifact(guardPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+/** Only the guard itself uses a double read without another guard. A crashed
+ * guard holder can leave a second-order recovery race; do not recursively lock.
+ */
+async function reclaimStaleMemoryGuard(guardPath, staleMs) {
+    const initial = await readMemoryLockState(guardPath, staleMs);
+    if (initial?.stale)
+        await removeMemoryGuardIfMatching(guardPath, initial.content);
+}
+async function withMemoryReclaimGuard(lockPath, deadline, fn) {
+    const guardPath = `${lockPath}.reclaim`;
+    const token = randomUUID();
+    const tempPath = `${guardPath}.${token}.tmp`;
+    const content = JSON.stringify({ pid: process.pid, host: os.hostname(), timestamp: Date.now(), token });
+    const { retryMs, staleMs } = CLAWCHAT_MEMORY_LOCK_TIMING;
+    let owned = false;
+    try {
+        try {
+            await fs.writeFile(tempPath, content, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            for (;;) {
+                heldMemoryLockTokens.add(token);
+                try {
+                    await fs.link(tempPath, guardPath);
+                    owned = true;
+                    break;
+                }
+                catch (error) {
+                    heldMemoryLockTokens.delete(token);
+                    if (error.code !== "EEXIST")
+                        throw error;
+                    await reclaimStaleMemoryGuard(guardPath, staleMs);
+                    if (Date.now() >= deadline)
+                        return false;
+                    await new Promise(resolve => setTimeout(resolve, Math.min(retryMs, Math.max(0, deadline - Date.now()))));
+                }
+            }
+        }
+        finally {
+            await unlinkMemoryLockArtifact(tempPath);
+        }
+        await fn();
+        return true;
+    }
+    finally {
+        try {
+            if (owned)
+                await removeMemoryGuardIfMatching(guardPath, content);
+        }
+        finally {
+            heldMemoryLockTokens.delete(token);
+        }
+    }
+}
+/** Invariant: only delete lockPath inside its reclaim guard. Creation uses
+ * exclusive link, so a guarded re-read equal to expected can only unlink that
+ * same generation. Never move a live lock out of the way to inspect it.
+ */
+async function removeMatchingMemoryLock(lockPath, expected) {
+    // A guard timeout must not turn a completed mutation into a reported failure.
+    // Leave the lock behind; dropping its held token lets later b/c recovery clean it.
+    await withMemoryReclaimGuard(lockPath, Date.now() + CLAWCHAT_MEMORY_LOCK_TIMING.timeoutMs, async () => {
+        const current = await readMemoryLockState(lockPath, CLAWCHAT_MEMORY_LOCK_TIMING.staleMs);
+        if (current?.content === expected)
+            await unlinkMemoryLockArtifact(lockPath);
+    });
+}
+/** @internal Exported for concurrent-reclaimer tests; mutations use the lock wrapper. */
+export async function reclaimStaleClawChatMemoryLock(lockPath, staleMs, deadline = Date.now() + CLAWCHAT_MEMORY_LOCK_TIMING.timeoutMs) {
+    const initial = await readMemoryLockState(lockPath, staleMs);
+    if (!initial?.stale)
+        return;
+    await memoryLockTestHooks?.afterStaleRead?.();
+    await withMemoryReclaimGuard(lockPath, deadline, async () => {
+        const current = await readMemoryLockState(lockPath, staleMs);
+        if (current?.content === initial.content && current.stale)
+            await unlinkMemoryLockArtifact(lockPath);
+    });
+}
+/** All mutations of a safe target share this queue and same-directory lockfile. */
+export async function withClawChatMemoryFileLock(targetPath, fn) {
+    const previous = memoryFileLockQueue.get(targetPath) ?? Promise.resolve();
+    let releaseQueue;
+    const queued = new Promise(resolve => { releaseQueue = resolve; });
+    memoryFileLockQueue.set(targetPath, queued);
+    await previous;
+    const lockPath = path.join(path.dirname(targetPath), `.${path.basename(targetPath)}.lock`);
+    const token = randomUUID();
+    const tempPath = `${lockPath}.${token}.tmp`;
+    const content = JSON.stringify({ pid: process.pid, host: os.hostname(), timestamp: Date.now(), token });
+    const { timeoutMs, retryMs, staleMs } = CLAWCHAT_MEMORY_LOCK_TIMING;
+    let owned = false;
+    try {
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        const deadline = Date.now() + timeoutMs;
+        try {
+            await fs.writeFile(tempPath, content, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            for (;;) {
+                // Register before publishing, so a same-process reclaimer cannot mistake
+                // the just-published token for one left behind by a recycled pid.
+                heldMemoryLockTokens.add(token);
+                try {
+                    await fs.link(tempPath, lockPath);
+                    owned = true;
+                    break;
+                }
+                catch (error) {
+                    heldMemoryLockTokens.delete(token);
+                    if (error.code !== "EEXIST")
+                        throw error;
+                    await reclaimStaleClawChatMemoryLock(lockPath, staleMs, deadline);
+                    if (Date.now() >= deadline)
+                        throw new Error(`Timed out acquiring clawchat memory lock: ${targetPath}`);
+                    await new Promise(resolve => setTimeout(resolve, Math.min(retryMs, Math.max(0, deadline - Date.now()))));
+                }
+            }
+        }
+        finally {
+            await unlinkMemoryLockArtifact(tempPath);
+        }
+        const assertHeld = async () => {
+            try {
+                if (await fs.readFile(lockPath, "utf8") === content)
+                    return;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            throw new Error(`Lost clawchat memory lock: ${targetPath}`);
+        };
+        return await fn(assertHeld);
+    }
+    finally {
+        try {
+            if (owned)
+                await removeMatchingMemoryLock(lockPath, content);
+        }
+        finally {
+            heldMemoryLockTokens.delete(token);
+            releaseQueue();
+            if (memoryFileLockQueue.get(targetPath) === queued)
+                memoryFileLockQueue.delete(targetPath);
+        }
+    }
+}
 function assertValidTargetId(target) {
     if (target.targetType !== "owner" && target.targetType !== "user" && target.targetType !== "group") {
         throw new Error("Invalid clawchat memory targetType");
@@ -265,12 +475,13 @@ async function readExistingClawChatMemoryFile(root, target) {
     }
     return { targetPath, exists: true, parsed: parseClawChatMemoryRaw(raw), raw };
 }
-async function writeFileAtomically(targetPath, content) {
+async function writeFileAtomically(targetPath, content, assertHeld) {
     const dir = path.dirname(targetPath);
     await fs.mkdir(dir, { recursive: true });
     const tempPath = path.join(dir, `.${path.basename(targetPath)}.${randomUUID()}.tmp`);
     try {
         await fs.writeFile(tempPath, content, "utf8");
+        await assertHeld();
         await fs.rename(tempPath, targetPath);
     }
     catch (error) {
@@ -359,50 +570,65 @@ export async function searchClawChatMemory(root, params, options = {}) {
 }
 export async function deleteClawChatMemoryFile(root, target) {
     const targetPath = await ensureClawChatMemoryTargetSafe(root, target);
-    await fs.unlink(targetPath).catch((error) => {
-        if (error.code !== "ENOENT") {
-            throw error;
-        }
+    await withClawChatMemoryFileLock(targetPath, async (assertHeld) => {
+        await ensureClawChatMemoryTargetSafe(root, target);
+        await assertHeld();
+        await fs.unlink(targetPath).catch((error) => {
+            if (error.code !== "ENOENT")
+                throw error;
+        });
     });
 }
 export async function writeClawChatMemoryBody(root, target, mode, content) {
     if (mode !== "append" && mode !== "replace") {
         throw new Error("Invalid clawchat memory write mode");
     }
-    const file = await readExistingClawChatMemoryFile(root, target);
-    let rawBody = file.parsed.rawBody;
-    if (mode === "replace") {
-        rawBody = content;
-    }
-    else {
-        if (content.length === 0) {
-            throw new Error("clawchat memory append content must be non-empty");
-        }
-        if (rawBody.length === 0 || rawBody.endsWith("\n") || rawBody.endsWith("\r") || content.startsWith("\n") || content.startsWith("\r")) {
-            rawBody = `${rawBody}${content}`;
+    const targetPath = await ensureClawChatMemoryTargetSafe(root, target);
+    await withClawChatMemoryFileLock(targetPath, async (assertHeld) => {
+        const file = await readExistingClawChatMemoryFile(root, target);
+        let rawBody = file.parsed.rawBody;
+        if (mode === "replace") {
+            rawBody = content;
         }
         else {
-            rawBody = `${rawBody}\n${content}`;
+            if (content.length === 0) {
+                throw new Error("clawchat memory append content must be non-empty");
+            }
+            if (rawBody.length === 0 || rawBody.endsWith("\n") || rawBody.endsWith("\r") || content.startsWith("\n") || content.startsWith("\r")) {
+                rawBody = `${rawBody}${content}`;
+            }
+            else {
+                rawBody = `${rawBody}\n${content}`;
+            }
         }
-    }
-    await writeFileAtomically(file.targetPath, formatRawMemoryFile(file.parsed, rawBody));
+        await writeFileAtomically(file.targetPath, formatRawMemoryFile(file.parsed, rawBody), assertHeld);
+    });
 }
 export async function editClawChatMemoryBody(root, target, oldText, newText) {
     const normalizedOldText = normalizeLineEndings(oldText);
     if (normalizedOldText.length === 0) {
         throw new Error("clawchat memory edit oldText must be non-empty");
     }
-    const file = await readExistingClawChatMemoryFile(root, target);
-    const { normalized: body, rawBoundaries } = normalizeWithRawBoundaryMap(file.parsed.rawBody);
-    const firstIndex = body.indexOf(normalizedOldText);
-    if (firstIndex === -1 || body.indexOf(normalizedOldText, firstIndex + 1) !== -1) {
-        throw new Error("clawchat memory edit requires exactly one oldText match");
-    }
-    const updatedRawBody = `${file.parsed.rawBody.slice(0, rawBoundaries[firstIndex])}${normalizeLineEndings(newText)}${file.parsed.rawBody.slice(rawBoundaries[firstIndex + normalizedOldText.length])}`;
-    await writeFileAtomically(file.targetPath, formatRawMemoryFile(file.parsed, updatedRawBody));
+    const targetPath = await ensureClawChatMemoryTargetSafe(root, target);
+    await withClawChatMemoryFileLock(targetPath, async (assertHeld) => {
+        const file = await readExistingClawChatMemoryFile(root, target);
+        const { normalized: body, rawBoundaries } = normalizeWithRawBoundaryMap(file.parsed.rawBody);
+        const firstIndex = body.indexOf(normalizedOldText);
+        if (firstIndex === -1 || body.indexOf(normalizedOldText, firstIndex + 1) !== -1) {
+            throw new Error("clawchat memory edit requires exactly one oldText match");
+        }
+        const updatedRawBody = `${file.parsed.rawBody.slice(0, rawBoundaries[firstIndex])}${normalizeLineEndings(newText)}${file.parsed.rawBody.slice(rawBoundaries[firstIndex + normalizedOldText.length])}`;
+        await writeFileAtomically(file.targetPath, formatRawMemoryFile(file.parsed, updatedRawBody), assertHeld);
+    });
 }
 export async function writeClawChatMetadata(root, target, metadata) {
-    const file = await readExistingClawChatMemoryFile(root, target);
-    const metadataToWrite = metadataWithInitialDefaults(target, file.exists, metadata);
-    await writeFileAtomically(file.targetPath, `${formatMetadataBlock(metadataToWrite)}${rawBodySuffixForMetadataReplacement(file.parsed)}`);
+    const targetPath = await ensureClawChatMemoryTargetSafe(root, target);
+    await withClawChatMemoryFileLock(targetPath, async (assertHeld) => {
+        const file = await readExistingClawChatMemoryFile(root, target);
+        const updated = typeof metadata === "function" ? metadata(file.parsed.metadata, file.exists) : metadata;
+        if (updated === null)
+            return;
+        const metadataToWrite = metadataWithInitialDefaults(target, file.exists, updated);
+        await writeFileAtomically(file.targetPath, `${formatMetadataBlock(metadataToWrite)}${rawBodySuffixForMetadataReplacement(file.parsed)}`, assertHeld);
+    });
 }

package/dist/src/clawchat-metadata.js

@@ -211,13 +211,17 @@ export async function pullGroupMetadata(params) {
                 throw new Error("ClawChat participant metadata pull requires getUserProfile");
             const profile = await getUser(mapped.userId);
             const fetched = userMetadataFromProfile(profile, mapped.userId);
-            if (existing.exists && !fetched.profile_type)
-                continue;
-            const metadata = existing.exists
-                ? { ...existing.metadata, profile_type: fetched.profile_type }
-                : fetched;
-            await writeClawChatMetadata(params.memoryRoot, { targetType: "user", targetId: mapped.userId }, metadata);
-            writes.push({ targetType: "user", targetId: mapped.userId });
+            let written = false;
+            await writeClawChatMetadata(params.memoryRoot, { targetType: "user", targetId: mapped.userId }, (current, exists) => {
+                // The network request stays outside the lock. Recheck the latest file
+                // so a concurrent refresh cannot lose fields or its profile_type.
+                if (exists && (current.profile_type || !fetched.profile_type))
+                    return null;
+                written = true;
+                return exists ? { ...current, profile_type: fetched.profile_type } : fetched;
+            });
+            if (written)
+                writes.push({ targetType: "user", targetId: mapped.userId });
         }
         catch (error) {
             failures.push({ targetType: "user", targetId: mapped.userId, error: errorMessage(error) });

package/dist/src/client-ownership.js

@@ -0,0 +1,147 @@
+const ownersKey = Symbol.for("clawchat-plugin-openclaw.wsClientOwners");
+const refreshKey = Symbol.for("clawchat-plugin-openclaw.refreshCoordination");
+const processState = globalThis;
+// The host can load another module generation without stopping the old task.
+const owners = processState[ownersKey] ??= new Map();
+const refreshStates = processState[refreshKey] ??= new Map();
+export const REFRESH_CHAIN_LIMIT = 1024;
+export const REFRESH_LOCK_TIMEOUT_MS = 60_000;
+function refreshState(accountId) {
+    let state = refreshStates.get(accountId);
+    if (!state) {
+        state = { children: new Map(), queue: [], locked: false, generation: 0 };
+        refreshStates.set(accountId, state);
+    }
+    return state;
+}
+export function acquireRefreshLock(accountId, warn = console.warn) {
+    const state = refreshState(accountId);
+    return new Promise((resolve) => {
+        const grant = () => {
+            state.locked = true;
+            const generation = ++state.generation;
+            let released = false;
+            const release = Object.assign(() => {
+                if (released)
+                    return;
+                released = true;
+                clearTimeout(state.timer);
+                state.timer = undefined;
+                const next = state.queue.shift();
+                if (next)
+                    next();
+                else
+                    state.locked = false;
+            }, {
+                isHeld: () => !released && state.locked && state.generation === generation && refreshStates.get(accountId) === state,
+            });
+            state.timer = setTimeout(() => {
+                try {
+                    warn(`[${accountId}] clawchat-plugin-openclaw refresh lock timed out; releasing queued refreshes`);
+                }
+                finally {
+                    release();
+                }
+            }, REFRESH_LOCK_TIMEOUT_MS);
+            state.timer.unref?.();
+            resolve(release);
+        };
+        if (state.locked)
+            state.queue.push(grant);
+        else
+            grant();
+    });
+}
+// Only persisted results belong in the chain. Unrelated activation lineages
+// have independent parents and cannot replace one another's descendants.
+export function recordRotation(accountId, parentRefreshToken, tokens) {
+    const { children } = refreshState(accountId);
+    if (children.has(parentRefreshToken))
+        return;
+    children.set(parentRefreshToken, { ...tokens });
+    while (children.size > REFRESH_CHAIN_LIMIT) {
+        // Splice out the oldest parent's child instead of dropping the parent: a
+        // host config snapshot can keep pointing at that root for the whole run,
+        // and the root must still reach the newest descendant.
+        const root = children.keys().next().value;
+        const child = children.get(root);
+        const grandchild = children.get(child.refreshToken);
+        if (!grandchild || child.refreshToken === root) {
+            children.delete(root);
+            continue;
+        }
+        children.delete(child.refreshToken);
+        children.set(root, grandchild);
+    }
+}
+export function childOf(accountId, refreshToken) {
+    const tokens = refreshToken ? refreshStates.get(accountId)?.children.get(refreshToken) : undefined;
+    return tokens ? { ...tokens } : undefined;
+}
+export function tipOf(accountId, refreshToken) {
+    const seen = new Set();
+    let tip;
+    for (let depth = 0; refreshToken && depth < REFRESH_CHAIN_LIMIT; depth++) {
+        seen.add(refreshToken);
+        const child = childOf(accountId, refreshToken);
+        if (!child || seen.has(child.refreshToken))
+            break;
+        tip = child;
+        refreshToken = child.refreshToken;
+    }
+    return tip;
+}
+export function isAncestor(accountId, ancestor, descendant) {
+    if (!ancestor || !descendant)
+        return false;
+    const seen = new Set();
+    for (let depth = 0; depth < REFRESH_CHAIN_LIMIT && !seen.has(ancestor); depth++) {
+        seen.add(ancestor);
+        const child = childOf(accountId, ancestor);
+        if (!child)
+            return false;
+        if (child.refreshToken === descendant)
+            return true;
+        ancestor = child.refreshToken;
+    }
+    return false;
+}
+export function snapshotClientOwner(accountId) {
+    return owners.get(accountId);
+}
+export function ownerChangedSince(accountId, snapshot) {
+    return owners.get(accountId) !== snapshot;
+}
+export function claimClientLease(accountId, close) {
+    const previous = owners.get(accountId);
+    const replacedPrevious = Boolean(previous?.close);
+    const owner = { close };
+    // A synchronous claim from the old close callback must supersede this one.
+    owners.set(accountId, owner);
+    try {
+        previous?.close?.();
+    }
+    catch {
+        // A failed shutdown must not prevent the replacement from taking ownership.
+    }
+    return {
+        replacedPrevious,
+        isCurrent: () => owners.get(accountId) === owner,
+        release() {
+            // Retain the latest identity so a delayed re-enter can detect replacement
+            // even after the replacement itself has shut down.
+            if (owners.get(accountId) === owner) {
+                owner.close = undefined;
+            }
+        },
+    };
+}
+export function resetClientOwnershipForTests() {
+    owners.clear();
+    resetRefreshCoordinationForTests();
+}
+export function resetRefreshCoordinationForTests() {
+    for (const state of refreshStates.values())
+        clearTimeout(state.timer);
+    refreshStates.clear();
+}

package/dist/src/config.js

@@ -91,6 +91,8 @@ export const openclawClawlingAccountConfigSchema = {
         "note-cap-turn": { type: "integer" },
         "delta-budget-chars": { type: "integer" },
         "non-owner-host-tools": { type: "string", enum: ["off", "approve"] },
+        "tool-grants": { type: "string", enum: ["on", "off"] },
+        "public-tools": { type: "array", items: { type: "string" } },
         reconnect: {
             type: "object",
             additionalProperties: false,
@@ -519,6 +521,8 @@ export function resolveOpenclawClawlingAccount(cfg, accountId, env = process.env
         noteCapTurn: readSessionInt(channel, "note-cap-turn"),
         deltaBudgetChars: readSessionInt(channel, "delta-budget-chars"),
         nonOwnerHostTools: parseNonOwnerHostTools(channel["non-owner-host-tools"]),
+        toolGrants: channel["tool-grants"] === "off" ? "off" : "on",
+        publicTools: channel["public-tools"],
         allowFrom: [],
         reconnect: readReconnect(channel.reconnect),
         heartbeat: readHeartbeat(channel.heartbeat),