@botcord/daemon 0.2.20 → 0.2.22

package/dist/agent-workspace.d.ts

@@ -31,16 +31,22 @@ export interface WorkspaceSeed {
     savedAt?: string;
 }
 /**
- * Idempotently create the per-agent CODEX_HOME directory and link the
- * user's codex `auth.json` into it. Does NOT write an initial `AGENTS.md`
- * — the codex adapter writes it fresh per turn from `systemContext`.
+ * Idempotently create the per-agent CODEX_HOME directory, link the
+ * user's codex `auth.json` into it, and seed the bundled BotCord skills
+ * under `<dir>/skills/` so the codex runtime (which sees this as
+ * `CODEX_HOME`, not the user's `~/.codex`) can discover them. Does NOT
+ * write an initial `AGENTS.md` — the codex adapter writes it fresh per
+ * turn from `systemContext`.
  */
 export declare function ensureAgentCodexHome(agentId: string): string;
 /**
  * Idempotently create the per-agent HERMES_HOME and HERMES workspace
  * directories. Writes a stub `.env` inside HERMES_HOME so hermes-acp's
  * `_load_env` does not log "No .env found" on every spawn; users can edit
- * this file to add API keys / model overrides.
+ * this file to add API keys / model overrides. Also seeds the bundled
+ * BotCord skills under `<hermes-home>/skills/` so hermes-acp's skill
+ * loader (which only sees this isolated HERMES_HOME, not `~/.hermes`)
+ * can discover them.
  */
 export declare function ensureAgentHermesWorkspace(agentId: string): {
     hermesHome: string;

package/dist/agent-workspace.js

@@ -304,21 +304,28 @@ function isSymlink(p) {
     }
 }
 /**
- * Idempotently create the per-agent CODEX_HOME directory and link the
- * user's codex `auth.json` into it. Does NOT write an initial `AGENTS.md`
- * — the codex adapter writes it fresh per turn from `systemContext`.
+ * Idempotently create the per-agent CODEX_HOME directory, link the
+ * user's codex `auth.json` into it, and seed the bundled BotCord skills
+ * under `<dir>/skills/` so the codex runtime (which sees this as
+ * `CODEX_HOME`, not the user's `~/.codex`) can discover them. Does NOT
+ * write an initial `AGENTS.md` — the codex adapter writes it fresh per
+ * turn from `systemContext`.
  */
 export function ensureAgentCodexHome(agentId) {
     const dir = agentCodexHomeDir(agentId);
     mkdirTolerant(dir);
     linkCodexAuth(dir);
+    seedCodexSkills(dir);
     return dir;
 }
 /**
  * Idempotently create the per-agent HERMES_HOME and HERMES workspace
  * directories. Writes a stub `.env` inside HERMES_HOME so hermes-acp's
  * `_load_env` does not log "No .env found" on every spawn; users can edit
- * this file to add API keys / model overrides.
+ * this file to add API keys / model overrides. Also seeds the bundled
+ * BotCord skills under `<hermes-home>/skills/` so hermes-acp's skill
+ * loader (which only sees this isolated HERMES_HOME, not `~/.hermes`)
+ * can discover them.
  */
 export function ensureAgentHermesWorkspace(agentId) {
     const hermesHome = agentHermesHomeDir(agentId);
@@ -329,15 +336,20 @@ export function ensureAgentHermesWorkspace(agentId) {
         "# Add e.g. HERMES_INFERENCE_PROVIDER=openrouter, OPENROUTER_API_KEY=...\n");
     seedHermesConfig(hermesHome);
     mergeHermesProviderEnv(path.join(hermesHome, ".env"));
+    seedHermesAgentSkills(hermesHome);
     return { hermesHome, hermesWorkspace };
 }
 /**
- * Bundled Claude Code skills shipped inside `@botcord/cli/skills/`. Seeded
- * into every agent workspace so the spawned `claude` runtime (which loads
- * `.claude/` via `--setting-sources project`) can discover the BotCord CLI
- * skill without any manual setup.
+ * Bundled BotCord skills shipped inside `@botcord/cli/skills/`. Skill
+ * content (SKILL.md + helper scripts) is runtime-agnostic; only the
+ * discovery path differs:
+ *   - Claude Code: `<workspace>/.claude/skills/<name>/`
+ *   - Codex:       `<codex-home>/skills/<name>/`
+ *   - Hermes:      `<hermes-home>/skills/<name>/`
+ * Seeded fresh per `ensureAgent*` call (force-overwrite) so daemon
+ * upgrades propagate.
  */
-const BUNDLED_CC_SKILLS = ["botcord", "botcord-user-guide"];
+const BUNDLED_SKILLS = ["botcord", "botcord-user-guide"];
 function resolveBundledCliSkillsRoot() {
     try {
         const pkgJsonPath = require.resolve("@botcord/cli/package.json");
@@ -349,23 +361,21 @@ function resolveBundledCliSkillsRoot() {
     }
 }
 /**
- * Copy daemon-owned Claude Code skills into the workspace. Re-copied on every
- * `ensureAgentWorkspace` call (force-overwrite) so daemon upgrades propagate;
- * users wanting custom skills should pick a different directory name under
- * `.claude/skills/` — those are not touched here.
+ * Copy bundled skill directories into `destSkillsDir`, force-overwriting
+ * any prior copy of each named skill. Other entries in `destSkillsDir`
+ * are left alone so user-authored skills survive. Best-effort: silently
+ * skips on copy failure or when the bundled CLI isn't resolvable.
  */
-function seedClaudeCodeSkills(workspace) {
+function copyBundledSkills(destSkillsDir) {
     const sourceRoot = resolveBundledCliSkillsRoot();
     if (!sourceRoot)
         return;
-    const skillsDir = path.join(workspace, ".claude", "skills");
-    mkdirTolerant(path.join(workspace, ".claude"));
-    mkdirTolerant(skillsDir);
-    for (const name of BUNDLED_CC_SKILLS) {
+    mkdirTolerant(destSkillsDir);
+    for (const name of BUNDLED_SKILLS) {
         const src = path.join(sourceRoot, name);
         if (!existsSync(src))
             continue;
-        const dst = path.join(skillsDir, name);
+        const dst = path.join(destSkillsDir, name);
         try {
             cpSync(src, dst, { recursive: true, force: true, dereference: true });
         }
@@ -374,6 +384,34 @@ function seedClaudeCodeSkills(workspace) {
         }
     }
 }
+/**
+ * Seed Claude Code's `.claude/skills/` discovery dir under the agent
+ * workspace. The `claude` adapter spawns with `--setting-sources project`
+ * so this dir is auto-discovered.
+ */
+function seedClaudeCodeSkills(workspace) {
+    mkdirTolerant(path.join(workspace, ".claude"));
+    copyBundledSkills(path.join(workspace, ".claude", "skills"));
+}
+/**
+ * Seed Codex's `<CODEX_HOME>/skills/` discovery dir. The codex adapter
+ * sets `CODEX_HOME=<agent>/codex-home/`, isolating per-agent skills from
+ * the user's global `~/.codex/skills/` — so skills must be seeded here
+ * for Codex agents to discover them.
+ */
+function seedCodexSkills(codexHome) {
+    copyBundledSkills(path.join(codexHome, "skills"));
+}
+/**
+ * Seed Hermes's `<HERMES_HOME>/skills/` discovery dir. hermes-acp's
+ * skill loader scans `$HERMES_HOME/skills/` (primary) plus any
+ * `skills.external_dirs` from config; the daemon points hermes-acp at
+ * the per-agent `<hermes-home>/`, so the user's global
+ * `~/.hermes/skills/` is invisible — bundled skills must be seeded here.
+ */
+function seedHermesAgentSkills(hermesHome) {
+    copyBundledSkills(path.join(hermesHome, "skills"));
+}
 /**
  * Idempotently create the agent's home / workspace / state directories and
  * seed the workspace Markdown files. Existing files are never overwritten —

package/dist/daemon.js

@@ -253,6 +253,32 @@ export async function startDaemon(opts) {
             text: msg.text,
         });
     };
+    // Boot-seeded per-agent caches (`credentialPathByAgentId`,
+    // `hubUrlByAgentId`, `displayNameByAgent`, `scBuilders`) are scoped to
+    // the agents present at startup. Without this hook, agents added later
+    // via `provision_agent` or openclaw-adoption stay missing from those
+    // caches until the next daemon restart — `room-context-fetcher` then
+    // logs `daemon.room-context.no-credentials` on every turn for the new
+    // agent and the system context loses its `[BotCord Room]` block (member
+    // names, rule, role).
+    const onAgentInstalled = (info) => {
+        // Re-provision (e.g. credential rotation) overwrites in place so the
+        // next room-context fetch re-loads the BotCordClient against the new
+        // credential file.
+        credentialPathByAgentId.set(info.agentId, info.credentialsFile);
+        if (info.hubUrl)
+            hubUrlByAgentId.set(info.agentId, info.hubUrl);
+        if (info.displayName)
+            displayNameByAgent.set(info.agentId, info.displayName);
+        if (!scBuilders.has(info.agentId)) {
+            scBuilders.set(info.agentId, createDaemonSystemContextBuilder({
+                agentId: info.agentId,
+                activityTracker,
+                roomContextBuilder,
+                loopRiskBuilder,
+            }));
+        }
+    };
     const gateway = new Gateway({
         config: gwConfig,
         sessionStorePath: opts.sessionStorePath ?? SESSIONS_PATH,
@@ -299,6 +325,7 @@ export async function startDaemon(opts) {
             const adopted = await adoptDiscoveredOpenclawAgents({
                 gateway,
                 cfg: opts.config,
+                onAgentInstalled,
             });
             if (adopted.adopted.length > 0 ||
                 adopted.failed.length > 0 ||
@@ -325,7 +352,7 @@ export async function startDaemon(opts) {
             userId: userAuth.current.userId,
             hubUrl: userAuth.current.hubUrl,
         });
-        const provisioner = createProvisioner({ gateway, policyResolver });
+        const provisioner = createProvisioner({ gateway, policyResolver, onAgentInstalled });
         controlChannel = new ControlChannel({
             auth: userAuth,
             handle: provisioner,

package/dist/gateway/channels/botcord.js

@@ -225,7 +225,10 @@ export function createBotCordChannel(options) {
         const eligible = [];
         if (msgs.length === 0) {
             logDrain();
-            return;
+            // Defensive: if Hub returns 0 messages, refuse to honor has_more=true.
+            // A stuck cursor on the Hub side could otherwise produce an unbounded
+            // poll loop here (count=0 with has_more=true on every iteration).
+            return { hasMore: false };
         }
         // First pass: ack duplicates/skipped messages so Hub stops requeueing,
         // and collect eligible messages preserving poll order. Grouping by
@@ -261,7 +264,7 @@ export function createBotCordChannel(options) {
         }
         if (eligible.length === 0) {
             logDrain();
-            return;
+            return { hasMore: Boolean(resp.has_more) };
         }
         // Group by `(room_id, topic)`. Insertion order is the poll order, so
         // iterating the map yields groups with the same external chronology.
@@ -275,6 +278,13 @@ export function createBotCordChannel(options) {
             else
                 groups.set(key, [msg]);
         }
+        // Emit groups in parallel: each `(room_id, topic)` group is an independent
+        // conversation thread, and the dispatcher already keys its per-turn queue
+        // by `(channel, accountId, roomId, threadId)` (see `buildQueueKey` in
+        // dispatcher.ts). Awaiting groups serially here forced a slow turn in
+        // room A to block room B's turn from starting; running them concurrently
+        // lets the dispatcher's per-room queues actually run in parallel.
+        const emitTasks = [];
         for (const group of groups.values()) {
             const normalized = normalizeInboxBatch(group, {
                 channelId: options.id,
@@ -301,18 +311,18 @@ export function createBotCordChannel(options) {
                     },
                 },
             };
-            try {
-                await emit(envelope);
+            emitTasks.push(emit(envelope).then(() => {
                 emittedGroups += 1;
-            }
-            catch (err) {
+            }, (err) => {
                 log.error("botcord emit threw", {
                     hubMsgIds: hubIds,
                     err: String(err),
                 });
-            }
+            }));
         }
+        await Promise.all(emitTasks);
         logDrain();
+        return { hasMore: Boolean(resp.has_more) };
     }
     function startWsLoop(client, ctx) {
         const { abortSignal, log, emit, setStatus } = ctx;
@@ -354,11 +364,16 @@ export function createBotCordChannel(options) {
             processing = true;
             try {
                 let currentTrigger = trigger;
+                let hasMore = false;
                 do {
                     pendingUpdate = false;
-                    await drainInbox(client, emit, log, currentTrigger);
-                    currentTrigger = "coalesced_inbox_update";
-                } while (pendingUpdate && running);
+                    const result = await drainInbox(client, emit, log, currentTrigger);
+                    hasMore = result.hasMore;
+                    // Prefer `has_more_continue` when this iteration is chained because
+                    // the previous poll capped at INBOX_POLL_LIMIT — distinguishes a
+                    // backlog drain from a coalesced ws_inbox_update drain in logs.
+                    currentTrigger = hasMore ? "has_more_continue" : "coalesced_inbox_update";
+                } while ((pendingUpdate || hasMore) && running);
             }
             catch (err) {
                 log.error("botcord inbox drain failed", { err: String(err) });

package/dist/gateway/dispatcher.js

@@ -159,6 +159,17 @@ export class Dispatcher {
         // Inbound transcript record — always before observers / gates so we have a
         // grounded turnId for any downstream attention_skipped / dropped / etc.
         this.emitInbound(turnId, msg);
+        this.log.info("dispatcher: inbound received", {
+            agentId: msg.accountId,
+            roomId: msg.conversation.id,
+            topicId: msg.conversation.threadId ?? null,
+            turnId,
+            messageId: msg.id,
+            senderId: msg.sender.id,
+            senderKind: msg.sender.kind,
+            mode,
+            textPreview: logPreview(rawText),
+        });
         // Notify the optional observer (activity tracking, metrics, etc.) as soon
         // as the dispatcher owns the message. Errors must not abort the turn.
         if (this.onInbound) {
@@ -274,7 +285,14 @@ export class Dispatcher {
         const myGen = q.cancelGen;
         const prev = q.current;
         if (prev) {
-            this.log.info("dispatcher: cancelling previous turn", { queueKey });
+            this.log.info("dispatcher: cancelling previous turn", {
+                agentId: msg.accountId,
+                roomId: msg.conversation.id,
+                topicId: msg.conversation.threadId ?? null,
+                turnId,
+                prevTurnId: prev.turnId,
+                queueKey,
+            });
             // Record the supersede BEFORE aborting so the prev turn's finalize sees
             // the abort reason (TurnSupersededError) and skips writing turn_error.
             this.transcript.write({
@@ -295,7 +313,13 @@ export class Dispatcher {
         // already fired its own abort + runTurn, or be mid-await itself. If so,
         // drop out silently — the newest turn is the only one that should run.
         if (myGen !== q.cancelGen) {
-            this.log.info("dispatcher: cancel-previous superseded", { queueKey });
+            this.log.info("dispatcher: cancel-previous superseded", {
+                agentId: msg.accountId,
+                roomId: msg.conversation.id,
+                topicId: msg.conversation.threadId ?? null,
+                turnId,
+                queueKey,
+            });
             // We didn't run the turn; emit dropped so the caller's inbound has a
             // matching path record. supersededBy is unknown at this layer (newer
             // arrival owns its own bump) — leave null.
@@ -529,10 +553,24 @@ export class Dispatcher {
                 dispatched.truncated = { composedText: true };
             this.transcript.write(dispatched);
         }
+        this.log.info("dispatcher: dispatched to runtime", {
+            agentId: msg.accountId,
+            roomId: msg.conversation.id,
+            topicId: msg.conversation.threadId ?? null,
+            turnId,
+            runtime: route.runtime,
+            cwd: route.cwd,
+            ...(mergedFromTurnIds.length > 0 ? { mergedFromTurns: mergedFromTurnIds.length } : {}),
+            composedPreview: logPreview(text),
+        });
         // Hard-cap turn with a timeout.
         const timer = setTimeout(() => {
             slot.timedOut = true;
             this.log.warn("dispatcher: turn timed out", {
+                agentId: msg.accountId,
+                roomId: msg.conversation.id,
+                topicId: msg.conversation.threadId ?? null,
+                turnId,
                 queueKey,
                 timeoutMs: this.turnTimeoutMs,
             });
@@ -860,12 +898,15 @@ export class Dispatcher {
                         text: `⚠️ Runtime timeout after ${Math.round(this.turnTimeoutMs / 60000)} minute(s); aborted`,
                         replyTo: msg.id,
                         traceId: msg.trace?.id ?? null,
-                    });
+                    }, turnId);
                 }
                 else {
                     this.log.warn("dispatcher: timeout in non-owner-chat room — error reply suppressed", {
+                        agentId: msg.accountId,
+                        roomId: msg.conversation.id,
+                        topicId: msg.conversation.threadId ?? null,
+                        turnId,
                         queueKey,
-                        conversationId: msg.conversation.id,
                         timeoutMs: this.turnTimeoutMs,
                     });
                 }
@@ -874,6 +915,10 @@ export class Dispatcher {
             if (threw) {
                 const errMsg = threw instanceof Error ? threw.message : String(threw);
                 this.log.error("dispatcher: runtime threw", {
+                    agentId: msg.accountId,
+                    roomId: msg.conversation.id,
+                    topicId: msg.conversation.threadId ?? null,
+                    turnId,
                     queueKey,
                     runtime: route.runtime,
                     error: errMsg,
@@ -898,12 +943,15 @@ export class Dispatcher {
                         text: `⚠️ Runtime error: ${truncate(errMsg, 500)}`,
                         replyTo: msg.id,
                         traceId: msg.trace?.id ?? null,
-                    });
+                    }, turnId);
                 }
                 else {
                     this.log.warn("dispatcher: runtime error in non-owner-chat room — error reply suppressed", {
+                        agentId: msg.accountId,
+                        roomId: msg.conversation.id,
+                        topicId: msg.conversation.threadId ?? null,
+                        turnId,
                         queueKey,
-                        conversationId: msg.conversation.id,
                     });
                 }
                 return;
@@ -987,8 +1035,11 @@ export class Dispatcher {
                 // already; whatever it left in the runtime's final assistant text is
                 // discarded so it doesn't leak into the room.
                 this.log.debug("dispatcher: non-owner-chat — discarding result.text (agent must use botcord_send)", {
+                    agentId: msg.accountId,
+                    roomId: msg.conversation.id,
+                    topicId: msg.conversation.threadId ?? null,
+                    turnId,
                     queueKey,
-                    conversationId: msg.conversation.id,
                     replyTextLen: replyText.length,
                 });
                 this.emitOutbound({
@@ -1019,7 +1070,7 @@ export class Dispatcher {
                 text: replyText,
                 replyTo: msg.id,
                 traceId: msg.trace?.id ?? null,
-            });
+            }, turnId);
             this.emitOutbound({
                 turnId,
                 msg,
@@ -1049,15 +1100,18 @@ export class Dispatcher {
             resolveDone();
         }
     }
-    async sendReply(channel, outbound) {
+    async sendReply(channel, outbound, turnId) {
         try {
             await channel.send({ message: outbound, log: this.log });
         }
         catch (err) {
             const error = err instanceof Error ? err.message : String(err);
             this.log.warn("dispatcher: channel.send failed", {
+                agentId: outbound.accountId,
+                roomId: outbound.conversationId,
+                topicId: outbound.threadId ?? null,
+                ...(turnId ? { turnId } : {}),
                 channel: outbound.channel,
-                conversationId: outbound.conversationId,
                 error,
             });
             return { ok: false, error };
@@ -1068,7 +1122,10 @@ export class Dispatcher {
             }
             catch (err) {
                 this.log.warn("dispatcher: onOutbound threw — continuing", {
-                    conversationId: outbound.conversationId,
+                    agentId: outbound.accountId,
+                    roomId: outbound.conversationId,
+                    topicId: outbound.threadId ?? null,
+                    ...(turnId ? { turnId } : {}),
                     error: err instanceof Error ? err.message : String(err),
                 });
             }
@@ -1105,6 +1162,19 @@ export class Dispatcher {
         this.transcript.write(rec);
     }
     emitOutbound(args) {
+        const durationMs = Date.now() - args.startedAt;
+        this.log.info("dispatcher: outbound emitted", {
+            agentId: args.msg.accountId,
+            roomId: args.msg.conversation.id,
+            topicId: args.msg.conversation.threadId ?? null,
+            turnId: args.turnId,
+            runtime: args.runtime,
+            deliveryStatus: args.deliveryStatus,
+            ...(args.deliveryReason ? { deliveryReason: args.deliveryReason } : {}),
+            durationMs,
+            replyPreview: logPreview(args.finalText.text),
+            ...(typeof args.costUsd === "number" ? { costUsd: args.costUsd } : {}),
+        });
         if (!this.transcript.enabled)
             return;
         const rec = {
@@ -1116,7 +1186,7 @@ export class Dispatcher {
             topicId: args.msg.conversation.threadId ?? null,
             runtime: args.runtime,
             runtimeSessionId: args.runtimeSessionId,
-            durationMs: Date.now() - args.startedAt,
+            durationMs,
             finalText: args.finalText.text,
             deliveryStatus: args.deliveryStatus,
             deliveryReason: args.deliveryReason,
@@ -1168,3 +1238,12 @@ function resolveQueueMode(route, kind) {
 function truncate(s, max) {
     return s.length <= max ? s : s.slice(0, max) + "…";
 }
+/**
+ * Single-line preview of a multi-line user/agent text, capped at `max` chars.
+ * Used to embed message/reply previews in daemon.log lines without bloating
+ * each line into multi-line JSON. Full text lives in transcripts.
+ */
+function logPreview(s, max = 120) {
+    const flat = s.replace(/\s+/g, " ").trim();
+    return flat.length <= max ? flat : flat.slice(0, max) + "…";
+}

package/dist/index.js

@@ -735,6 +735,17 @@ function cmdTranscriptTail(args) {
     const file = transcriptFilePath(defaultTranscriptRoot(), agent, room, topic);
     if (!existsSync(file)) {
         console.error(`no transcript at ${file}`);
+        let cfg = null;
+        try {
+            cfg = loadConfig();
+        }
+        catch {
+            // ignore — config may simply not exist yet
+        }
+        const enabled = resolveTranscriptEnabled(process.env.BOTCORD_TRANSCRIPT, cfg?.transcript?.enabled === true);
+        if (!enabled) {
+            console.error("hint: transcripts are disabled (default-off). Run `botcord-daemon transcript enable` and restart the daemon, then send a new message.");
+        }
         process.exit(1);
     }
     const follow = args.flags.f === true || args.flags.follow === true;

package/dist/provision.d.ts

@@ -2,6 +2,28 @@ import { BotCordClient, type AgentIdentitySnapshot, type ControlAck, type Contro
 import type { Gateway } from "./gateway/index.js";
 import type { PolicyResolverLike } from "./gateway/policy-resolver.js";
 import { type DaemonConfig } from "./config.js";
+/**
+ * Information passed to {@link OnAgentInstalledHook} after a successful
+ * provision. Mirrors the credential fields the daemon's per-agent caches
+ * (`credentialPathByAgentId`, `hubUrlByAgentId`, `displayNameByAgent`) read at
+ * boot — fired again here so hot-provisioned agents land in those caches
+ * without waiting for a daemon restart.
+ */
+export interface InstalledAgentInfo {
+    agentId: string;
+    credentialsFile: string;
+    hubUrl: string;
+    displayName?: string;
+    runtime?: string;
+}
+/**
+ * Hook fired after `installLocalAgent` / `installExistingOpenclawBinding`
+ * finish successfully. Synchronous on purpose — the caller updates a few
+ * in-memory maps and we don't want a slow hook to delay the control-frame
+ * ack. Throwing from the hook is treated as a programmer error and
+ * surfaced; rollback of the install is the caller's responsibility.
+ */
+export type OnAgentInstalledHook = (info: InstalledAgentInfo) => void;
 /** Options accepted by {@link createProvisioner}. */
 export interface ProvisionerOptions {
     /** Live gateway handle used to hot-plug channels. */
@@ -19,6 +41,15 @@ export interface ProvisionerOptions {
      * extra round-trip.
      */
     policyResolver?: PolicyResolverLike;
+    /**
+     * Optional hook called after each successful agent install (whether via
+     * `provision_agent` or `installExistingOpenclawBinding`). The daemon
+     * wires this to write the new agent into its boot-seeded caches —
+     * without it, `room-context-fetcher` keeps emitting
+     * `daemon.room-context.no-credentials` for hot-provisioned agents until
+     * the next restart.
+     */
+    onAgentInstalled?: OnAgentInstalledHook;
 }
 /** The value a frame handler returns (minus the `id` which the channel fills in). */
 type AckBody = Omit<ControlAck, "id">;
@@ -47,6 +78,7 @@ export declare function adoptDiscoveredOpenclawAgents(ctx: {
     cfg?: DaemonConfig;
     timeoutMs?: number;
     probe?: WsEndpointProbeFn;
+    onAgentInstalled?: OnAgentInstalledHook;
 }): Promise<AdoptDiscoveredOpenclawAgentsResult>;
 /**
  * Append `agentId` to the daemon config if not already present. Returns a

package/dist/provision.js

@@ -23,6 +23,7 @@ export function createProvisioner(opts) {
     const gateway = opts.gateway;
     const register = opts.register ?? BotCordClient.register;
     const policyResolver = opts.policyResolver;
+    const onAgentInstalled = opts.onAgentInstalled;
     return async (frame) => {
         daemonLog.debug("provision.dispatch", { type: frame.type, id: frame.id });
         switch (frame.type) {
@@ -66,7 +67,7 @@ export function createProvisioner(opts) {
                     runtime: pickRuntime(params) ?? null,
                     name: params.name ?? null,
                 });
-                const agent = await provisionAgent(params, { gateway, register });
+                const agent = await provisionAgent(params, { gateway, register, onAgentInstalled });
                 // Seed the policy resolver from the optional `defaultAttention` /
                 // `attentionKeywords` fields (PR3, control-frame.ts). Hub builds that
                 // don't yet emit these stay backwards-compatible — the resolver just
@@ -331,6 +332,32 @@ async function installLocalAgent(credentials, ctx) {
         }
         throw err;
     }
+    // Update the daemon's boot-seeded per-agent caches in place. Without this
+    // a hot-provisioned agent keeps missing `credentialPathByAgentId` /
+    // `hubUrlByAgentId` / `displayNameByAgent` until the next daemon restart,
+    // and `room-context-fetcher` logs `daemon.room-context.no-credentials` on
+    // every turn for it (so the system-context loses the room block — member
+    // names, rule, role).
+    if (ctx.onAgentInstalled) {
+        try {
+            ctx.onAgentInstalled({
+                agentId: credentials.agentId,
+                credentialsFile,
+                hubUrl: credentials.hubUrl,
+                ...(credentials.displayName ? { displayName: credentials.displayName } : {}),
+                ...(credentials.runtime ? { runtime: credentials.runtime } : {}),
+            });
+        }
+        catch (err) {
+            // Hook misbehavior must not fail the install — the agent is already
+            // on disk + in the gateway. Surface it loudly so the daemon owner
+            // notices the cache is out of sync.
+            daemonLog.error("provision.onAgentInstalled threw — caches may be stale", {
+                agentId: credentials.agentId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
     daemonLog.info("agent provisioned", {
         agentId: credentials.agentId,
         credentialsFile,
@@ -382,6 +409,27 @@ async function installExistingOpenclawBinding(agentId, ctx) {
         });
     }
     upsertManagedRouteForCredentials(credentials, cfg, ctx.gateway);
+    // Same cache-warmup as `installLocalAgent` — re-binding an existing
+    // openclaw agent at runtime should also land it in the daemon's
+    // per-agent maps, otherwise room-context lookups stay broken until
+    // restart.
+    if (ctx.onAgentInstalled) {
+        try {
+            ctx.onAgentInstalled({
+                agentId: credentials.agentId,
+                credentialsFile,
+                hubUrl: credentials.hubUrl,
+                ...(credentials.displayName ? { displayName: credentials.displayName } : {}),
+                ...(credentials.runtime ? { runtime: credentials.runtime } : {}),
+            });
+        }
+        catch (err) {
+            daemonLog.error("provision.onAgentInstalled threw — caches may be stale", {
+                agentId: credentials.agentId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
     return {
         agentId: credentials.agentId,
         hubUrl: credentials.hubUrl,
@@ -528,6 +576,7 @@ function findCredentialsByOpenclaw(gateway, openclawAgent) {
 export async function adoptDiscoveredOpenclawAgents(ctx) {
     const register = ctx.register ?? BotCordClient.register;
     const cfg = ctx.cfg ?? loadConfig();
+    const onAgentInstalled = ctx.onAgentInstalled;
     const result = {
         adopted: [],
         skipped: [],
@@ -601,12 +650,14 @@ export async function adoptDiscoveredOpenclawAgents(ctx) {
                     const credentials = await materializeCredentials(params, freshCfg, {
                         gateway: ctx.gateway,
                         register,
+                        ...(onAgentInstalled ? { onAgentInstalled } : {}),
                     }, undefined);
                     const installed = await installLocalAgent(credentials, {
                         gateway: ctx.gateway,
                         register,
                         cfg: freshCfg,
                         source: "adopted-openclaw",
+                        ...(onAgentInstalled ? { onAgentInstalled } : {}),
                     });
                     result.adopted.push(installed.agentId);
                 }