@yahaha-studio/kichi-forwarder 0.1.1-beta.1 → 0.1.1-beta.11

package/README.md

@@ -6,7 +6,7 @@ Kichi Forwarder brings your OpenClaw companion into Kichi.
 
 It can directly control your companion's avatar in Kichi, show what it is doing, leave notes for you, and recommend music while you work together.
 
-> The world of Kichi opens for playtest soon.
+> [Kichi on Steam](https://store.steampowered.com/app/4427550/Kichi_Focus_Together) — Wishlist now!
 
 ## Highlights
 

package/index.ts

@@ -76,7 +76,7 @@ type IdlePlan = {
     actions: IdlePlanAction[];
   }>;
 };
-
+
 function isAlbumConfig(value: unknown): value is Album {
   if (!value || typeof value !== "object") {
     return false;
@@ -411,9 +411,66 @@ function notifyMessageReceived(
   service.sendHookNotify("message_received", `"${trimmed}"`);
 }
 
+function trimOptionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function readExtraStringField(source: unknown, key: string): string | undefined {
+  if (!isPlainObject(source)) {
+    return undefined;
+  }
+  return trimOptionalString(source[key]);
+}
+
+function resolveBeforeDispatchLocator(
+  event: { sessionKey?: string },
+  ctx: { sessionKey?: string },
+): {
+  ctxAgentId?: string;
+  sessionKey?: string;
+} {
+  const ctxAgentId = readExtraStringField(ctx, "ctxAgentId");
+  const sessionKey = trimOptionalString(ctx.sessionKey) ?? trimOptionalString(event.sessionKey);
+  return {
+    ...(ctxAgentId ? { ctxAgentId } : {}),
+    ...(sessionKey ? { sessionKey } : {}),
+  };
+}
+
+function resolveAgentHookLocator(ctx: {
+  agentId?: string;
+  sessionKey?: string;
+}): {
+  agentId?: string;
+  ctxAgentId?: string;
+  sessionKey?: string;
+} {
+  const agentId = trimOptionalString(ctx.agentId);
+  const ctxAgentId = readExtraStringField(ctx, "ctxAgentId");
+  const sessionKey = trimOptionalString(ctx.sessionKey);
+  return {
+    ...(agentId ? { agentId } : {}),
+    ...(ctxAgentId ? { ctxAgentId } : {}),
+    ...(sessionKey ? { sessionKey } : {}),
+  };
+}
+
+function resolveToolLocator(ctx: OpenClawPluginToolContext): {
+  agentId?: string;
+  sessionKey?: string;
+} {
+  const agentId = trimOptionalString(ctx.agentId);
+  const sessionKey = trimOptionalString(ctx.sessionKey);
+  return {
+    ...(agentId ? { agentId } : {}),
+    ...(sessionKey ? { sessionKey } : {}),
+  };
+}
+
 function registerPluginHooks(api: OpenClawPluginApi, runtimeManager: KichiRuntimeManager): void {
   api.on("before_dispatch", (event, ctx) => {
-    const service = runtimeManager.getRuntime(ctx);
+    const locator = resolveBeforeDispatchLocator(event, ctx);
+    const service = runtimeManager.getRuntime(locator);
     if (!service) {
       return;
     }
@@ -428,7 +485,8 @@ function registerPluginHooks(api: OpenClawPluginApi, runtimeManager: KichiRuntim
   });
 
   api.on("before_prompt_build", (_event, ctx) => {
-    const service = runtimeManager.getRuntime(ctx);
+    const locator = resolveAgentHookLocator(ctx);
+    const service = runtimeManager.getRuntime(locator);
     if (!service?.hasValidIdentity() || !service.isConnected()) {
       return;
     }
@@ -445,7 +503,8 @@ function registerPluginHooks(api: OpenClawPluginApi, runtimeManager: KichiRuntim
   });
 
   api.on("before_tool_call", (_event, ctx) => {
-    const service = runtimeManager.getRuntime(ctx);
+    const locator = resolveAgentHookLocator(ctx);
+    const service = runtimeManager.getRuntime(locator);
     if (!service) {
       return;
     }
@@ -455,7 +514,8 @@ function registerPluginHooks(api: OpenClawPluginApi, runtimeManager: KichiRuntim
   });
 
   api.on("agent_end", (event, ctx) => {
-    const service = runtimeManager.getRuntime(ctx);
+    const locator = resolveAgentHookLocator(ctx);
+    const service = runtimeManager.getRuntime(locator);
     const preview = getLastAssistantPreview(event.messages, MAX_AGENT_END_PREVIEW_WIDTH);
     api.logger.debug(
       `[kichi:${service?.getAgentId() ?? "unknown"}] agent_end fired (trigger=${ctx.trigger ?? "unknown"}, success=${event.success}, durationMs=${event.durationMs ?? 0}, error=${event.error ?? ""}, preview=${preview || "(empty)"})`,
@@ -894,6 +954,7 @@ function buildKichiActionDescription(): string {
     "Directly control the avatar inside Kichi World.",
     "Use this whenever the user explicitly asks you to make the Kichi avatar sit down, stand up, lie down, floor-sit, type, read, meditate, celebrate, or perform another listed animation.",
     "For most work, prefer a sit pose and switch actions as the task moves between stages.",
+    "Set verify to true ONLY when the user explicitly requests a pose or action change. The server will confirm whether the avatar actually applied the requested pose. If it could not (e.g. no available seats), the result will contain the actual fallback pose so you can inform the user accurately. During routine sync steps, omit verify.",
     `stand actions: ${actions.stand.map((entry) => entry.name).join(", ")}`,
     `sit actions: ${actions.sit.map((entry) => entry.name).join(", ")}`,
     `lay actions: ${actions.lay.map((entry) => entry.name).join(", ")}`,
@@ -913,6 +974,7 @@ function buildKichiIdlePlanDescription(): string {
     "4. Make the full stage duration total exactly to the heartbeat interval, and assign each stage pomodoroPhase from the stage's actual role: focus for concentrated activity, shortBreak for short resets, longBreak for longer rests. Do not default the whole idle plan to none. Use none only for a stage that truly has no pomodoro role.",
     "5. Choose stage actions that clearly match the stage purpose and the project.",
     "6. Write each action bubble as the current presented state, not a next step, plan, or instruction.",
+    "7. If an idle plan is currently being carried out and the user asks about something from it, respond with an immersive in-universe depiction or draft instead of bluntly saying it is fake or nonexistent.",
     "Use the same language as the current conversation for goal, purpose, bubble, and log.",
     `stand actions: ${actions.stand.map((entry) => entry.name).join(", ")}`,
     `sit actions: ${actions.sit.map((entry) => entry.name).join(", ")}`,
@@ -924,7 +986,7 @@ function buildKichiIdlePlanDescription(): string {
 function buildKichiPrompt(): string {
   return [
     "Kichi avatar control and status sync are available via `kichi_action` and `kichi_clock`.",
-    "If the user gives a direct Kichi pose or action request, fulfill it with `kichi_action`.",
+    "If the user gives a direct Kichi pose or action request, fulfill it with `kichi_action` and set `verify: true` so you can confirm the avatar actually applied the pose. If the result contains a warning about a fallback, tell the user what actually happened instead of assuming success.",
     "Write the visible reply as a natural user-facing response. Keep `kichi_action`, `kichi_clock`, and sync steps internal and absent from the visible reply.",
     "",
     "kichi_action timing (all required when sync is active):",
@@ -944,7 +1006,7 @@ function createAgentScopedTool(
   factory: (service: KichiForwarderService, ctx: OpenClawPluginToolContext) => AnyAgentTool,
 ) {
   return (ctx: OpenClawPluginToolContext) => {
-    const service = runtimeManager.getRuntime(ctx, { createIfMissing: true });
+    const service = runtimeManager.getRuntime(resolveToolLocator(ctx));
     if (!service) {
       throw new Error("Failed to resolve agent-scoped Kichi runtime");
     }
@@ -952,13 +1014,30 @@ function createAgentScopedTool(
   };
 }
 
+const GLOBAL_RUNTIME_MANAGER_KEY = "__kichi_forwarder_runtime_manager__";
+
+type GlobalRuntimeManagerState = typeof globalThis & {
+  [GLOBAL_RUNTIME_MANAGER_KEY]?: KichiRuntimeManager;
+};
+
+function getRuntimeManager(logger: OpenClawPluginApi["logger"]): KichiRuntimeManager {
+  const globalState = globalThis as GlobalRuntimeManagerState;
+  const existing = globalState[GLOBAL_RUNTIME_MANAGER_KEY];
+  if (existing) {
+    return existing;
+  }
+  const runtimeManager = new KichiRuntimeManager(logger);
+  globalState[GLOBAL_RUNTIME_MANAGER_KEY] = runtimeManager;
+  return runtimeManager;
+}
+
 const plugin = {
   id: "kichi-forwarder",
   name: "Kichi Forwarder",
   configSchema: { parse },
 
   register(api: OpenClawPluginApi) {
-    const runtimeManager = new KichiRuntimeManager(api.logger);
+    const runtimeManager = getRuntimeManager(api.logger);
     registerPluginHooks(api, runtimeManager);
     const musicTitleEnum = getMusicTitleEnum();
 
@@ -966,10 +1045,14 @@ const plugin = {
       id: "kichi-forwarder",
       start: (ctx) => {
         parse(ctx.config.plugins?.entries?.["kichi-forwarder"]?.config);
-        runtimeManager.startPersistedRuntimes();
+        runtimeManager.initializeStartupRuntimes();
       },
       stop: () => {
         runtimeManager.stopAll();
+        const globalState = globalThis as GlobalRuntimeManagerState;
+        if (globalState[GLOBAL_RUNTIME_MANAGER_KEY] === runtimeManager) {
+          delete globalState[GLOBAL_RUNTIME_MANAGER_KEY];
+        }
       },
     });
 
@@ -1019,8 +1102,8 @@ const plugin = {
           return { success: false, error: tagsError };
         }
         const result = await service.join(avatarId, botName, bio, tags ?? []);
-        if (result.success) {
-          return { success: true, authKey: result.authKey };
+        if (result.success) {
+          return { success: true, authKey: result.authKey };
         }
         return {
           success: false,
@@ -1031,7 +1114,14 @@ const plugin = {
       },
     })));
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    api.registerTool((ctx: OpenClawPluginToolContext) => {
+      const locator = resolveToolLocator(ctx);
+      const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+      if (!agentId) {
+        throw new Error("Failed to resolve agent-scoped Kichi runtime");
+      }
+      const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
+      return ({
       name: "kichi_switch_host",
       description:
         "Switch Kichi runtime host and reconnect immediately without restarting the gateway.",
@@ -1058,7 +1148,8 @@ const plugin = {
           status,
         };
       },
-    })));
+      });
+    });
 
     api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_rejoin",
@@ -1094,8 +1185,8 @@ const plugin = {
     })));
 
     api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
-      name: "kichi_status",
-      description: "Read current Kichi connection status and identity readiness",
+      name: "kichi_connection_status",
+      description: "Check WebSocket connection status and identity readiness only. Does NOT return room info, avatar state, or personnel — use kichi_query_status for that.",
       parameters: { type: "object", properties: {} },
       execute: async () => {
         return {
@@ -1122,15 +1213,21 @@ const plugin = {
             description:
               "Short natural first-person sentence under 15 words. Match the language of the bubble and mention the current action and immediate focus.",
           },
+          verify: {
+            type: "boolean",
+            description:
+              "Set true ONLY when the user explicitly requests a pose or action. Omit during routine sync steps.",
+          },
         },
         required: ["poseType", "action"],
       },
       execute: async (_toolCallId, params) => {
-        const { poseType, action, bubble, log } = (params || {}) as {
+        const { poseType, action, bubble, log, verify } = (params || {}) as {
           poseType?: string;
           action?: string;
           bubble?: string;
           log?: string;
+          verify?: boolean;
         };
         if (!poseType || !action) {
           return { success: false, error: "poseType and action parameters are required" };
@@ -1158,22 +1255,40 @@ const plugin = {
 
         const bubbleText = typeof bubble === "string" && bubble.trim() ? bubble.trim() : matched.name;
         const logText = typeof log === "string" ? log.trim() : "";
-        sendStatusUpdate(
-          service,
-          {
+        const playback = getActionPlayback(matched);
+
+        if (verify) {
+          try {
+            const ack = await service.sendStatusVerified(
+              normalizedPoseType, matched.name, bubbleText, logText, playback,
+            );
+            if (ack.warning) {
+              return {
+                success: true,
+                requested: { poseType: normalizedPoseType, action: matched.name },
+                actual: { poseType: ack.poseType, action: ack.action },
+                warning: ack.warning,
+              };
+            }
+          } catch {
+            // Server not updated or timeout — fall through to normal success
+          }
+        } else {
+          sendStatusUpdate(service, {
             poseType: normalizedPoseType,
             action: matched.name,
             bubble: bubbleText,
             log: logText,
-          },
-        );
+          });
+        }
+
         return {
           success: true,
           poseType: normalizedPoseType,
           action: matched.name,
           bubble: bubbleText,
           log: logText,
-          playback: getActionPlayback(matched),
+          playback,
         };
       },
     })));
@@ -1397,7 +1512,7 @@ const plugin = {
     api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_query_status",
       description:
-        "Query Kichi avatar status (notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, and `hasCreatedMusicAlbumToday`). Use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
+        "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, and `hasCreatedMusicAlbumToday`. Use this when the user asks to check kichi status, room status, or who is in the room. Also use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
       parameters: {
         type: "object",
         properties: {
@@ -1572,5 +1687,5 @@ const plugin = {
   },
 };
 
-export default plugin;
-
+export default plugin;
+

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "kichi-forwarder",
   "name": "Kichi Forwarder",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
-  "version": "0.1.1-beta.1",
+  "version": "0.1.1-beta.11",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.1-beta.1",
+  "version": "0.1.1-beta.11",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
   "type": "module",
   "main": "index.ts",

package/skills/kichi-forwarder/SKILL.md

@@ -8,9 +8,9 @@ metadata: {"openclaw":{"skillKey":"kichi-forwarder","homepage":"https://github.c
 
 Kichi Forwarder provides websocket tools for connecting an OpenClaw agent to Kichi, directly controlling the Kichi avatar, syncing companion status, and handling Kichi notes, timers, and music workflows.
 
-## Skill Files (Absolute URLs)
+## Pre-install Remote Discovery
 
-If this skill is loaded from a remote URL before local installation, use these files:
+The following URLs are only used when this skill is first loaded from a remote URL before local installation. After the plugin is installed locally, these URLs are not referenced and the local files take precedence:
 
 - `SKILL.md`: `https://yahaha-studio.github.io/kichi-forwarder/SKILL.md`
 - `install.md`: `https://yahaha-studio.github.io/kichi-forwarder/references/install.md`
@@ -30,7 +30,7 @@ Runtime data lives under the user home directory and is isolated per OpenClaw ag
 
 ## Remote URL Install Entry
 
-When this skill is loaded from:
+When this skill is first loaded from:
 
 - `https://yahaha-studio.github.io/kichi-forwarder/SKILL.md`
 
@@ -40,16 +40,16 @@ The install and join flow is defined only in:
 
 - `https://yahaha-studio.github.io/kichi-forwarder/references/install.md`
 
-Read and follow that file before any tool call.
+Read that file once to complete the initial install. After local installation, the local `install.md` is used instead.
 
 ## Install Gate
 
 For install/onboarding/connect requests:
 
-- Read and follow `install.md` before any tool call.
-- Before continuing any install/onboarding/connect flow, check whether `kichi-forwarder` is already installed. If it is installed, ensure it is on the latest published version of `@yahaha-studio/kichi-forwarder`; if not, update it to that latest version first.
-- If plugin installation fails with `429`, treat it as a ClawHub routing failure and switch immediately to the non-ClawHub archive install path from `install.md`/`error.md`. Do not wait and do not retry the same bare package command.
-- Before calling `kichi_status` or `kichi_join`, you MUST update workspace `HEARTBEAT.md` by following `heartbeat.md`.
+- Read and follow `install.md` before starting the install flow.
+- Before continuing any install/onboarding/connect flow, attempt to install `@yahaha-studio/kichi-forwarder` directly. If the install fails because the plugin already exists, check whether the installed version is the latest published version; if not, update it.
+- If plugin installation fails with `429`, treat it as a ClawHub routing failure and switch to the non-ClawHub archive install path from `install.md`/`error.md`. Do not retry the same bare package command.
+- Before calling `kichi_connection_status` or `kichi_join`, update workspace `HEARTBEAT.md` by following `heartbeat.md`. If the update fails, warn the user that heartbeat integration will be unavailable and continue the connection flow.
 
 ## LLM Runtime
 
@@ -64,11 +64,12 @@ Use this order unless the user asks for a different explicit action:
 
 Install/onboarding requests are the exception: follow `install.md` first.
 
-1. If connection or identity is unknown, call `kichi_status` first.
+1. If connection or identity is unknown, call `kichi_connection_status` first.
 2. If the requested host differs from the current host, call `kichi_switch_host`.
-3. If no `authKey` is available, call `kichi_join`.
-4. If `authKey` exists but websocket is not open, call `kichi_rejoin` or wait for automatic reconnect and rejoin.
-5. Use `kichi_action`, `kichi_clock`, note board tools, and music album tools only after status is ready.
+3. If the requested `avatarId` differs from the current host's connected `avatarId`, call `kichi_leave` first when the old avatar is still joined, then call `kichi_join` with the requested `avatarId`.
+4. Otherwise, if no `authKey` is available, call `kichi_join`.
+5. If `authKey` exists but websocket is not open, call `kichi_rejoin` or wait for automatic reconnect and rejoin.
+6. Use `kichi_action`, `kichi_clock`, note board tools, and music album tools only after status is ready.
 
 ## Tools
 
@@ -82,6 +83,7 @@ kichi_join(avatarId: "your-avatar-id", botName: "<from IDENTITY.md>", bio: "<fro
 - `bio`: required
 - `avatarId`: optional. If omitted, the tool reads `avatarId` from the current host's `identity.json`. If missing, the call fails.
 - `tags`: optional string list. Empty strings are ignored and duplicates are removed. If omitted, the join payload sends `[]`.
+- If the current host is still joined with a different `avatarId`, call `kichi_leave` first, then call `kichi_join` with the new `avatarId`.
 
 ### kichi_switch_host
 
@@ -92,10 +94,10 @@ kichi_switch_host(host: "your.kichi.host")
 - `host`: required
 - This reloads the host-specific `identity.json` and reconnects the websocket immediately.
 
-### kichi_status
+### kichi_connection_status
 
 ```text
-kichi_status()
+kichi_connection_status()
 ```
 
 Use this to confirm:
@@ -117,9 +119,9 @@ kichi_leave()
 When the user asks to leave Kichi World:
 
 1. Call `kichi_leave`.
-2. Remove the Kichi heartbeat workflow from workspace `HEARTBEAT.md`.
+2. Remove the Kichi heartbeat workflow snippet from workspace `HEARTBEAT.md`. If the removal fails, warn the user and continue.
 3. Revert heartbeat cadence only if the user explicitly changed it for Kichi.
-4. Do not claim the plugin removed heartbeat settings automatically.
+4. Do not claim the plugin removed heartbeat settings automatically — the agent removes the snippet as part of this leave flow.
 
 ### kichi_action
 

package/skills/kichi-forwarder/references/error.md

@@ -5,7 +5,7 @@ If `openclaw plugins install @yahaha-studio/kichi-forwarder` fails, read the err
 - Permission or access error (`EACCES`): re-run the command with appropriate user-level permissions for the current OS.
 - Package resolution or visibility error: confirm the package name is exactly `@yahaha-studio/kichi-forwarder` and that the package is published and publicly available.
 - Gateway compatibility error: update OpenClaw Gateway to a version compatible with this plugin package.
-- ClawHub rate limit (`429`): do not retry the same bare package command. `openclaw plugins install @yahaha-studio/kichi-forwarder` does not auto-fallback to npm on `429`. Bypass ClawHub immediately:
+- ClawHub rate limit (`429`): do not retry the same bare package command. `openclaw plugins install @yahaha-studio/kichi-forwarder` does not auto-fallback to npm on `429`. Switch to the local archive path:
 
 ```bash
 npm pack @yahaha-studio/kichi-forwarder

package/skills/kichi-forwarder/references/heartbeat.md

@@ -2,27 +2,26 @@
 
 ## Session Startup Rule
 
-If the plugin is installed and enabled, ensure workspace `HEARTBEAT.md` includes the Kichi heartbeat workflow before first `kichi_status` or `kichi_join` in an install/onboarding flow:
+If the plugin is installed and enabled, update workspace `HEARTBEAT.md` to include the Kichi heartbeat workflow before first `kichi_connection_status` or `kichi_join` in an install/onboarding flow:
 
 1. If the workflow snippet is missing, add the snippet from `HEARTBEAT.md Snippet` section below.
 2. If the plugin was upgraded in the current flow and the existing Kichi heartbeat snippet does not match the current snippet below, update it to the latest version.
-3. If the file cannot be updated, stop immediately and do not continue.
+3. If the update fails, warn the user that heartbeat integration will be unavailable and continue the connection flow.
 
-This startup rule is a blocking gate, not a cleanup task.
+This startup rule is a recommended step for full heartbeat functionality.
 
 ## First Join Gate
 
 For "join Kichi World" onboarding requests:
 
 1. Complete `Session Startup Rule` first.
-2. If `HEARTBEAT.md` write fails, report setup as incomplete, include the file error, and stop.
-3. Do not call `kichi_status` or `kichi_join` until `HEARTBEAT.md` is updated.
-4. After a plugin upgrade, treat snippet mismatch as requiring an update, not as optional drift.
+2. If the `HEARTBEAT.md` update fails, warn the user that heartbeat integration will be unavailable and continue the connection flow.
+3. After a plugin upgrade, treat snippet mismatch as requiring an update, not as optional drift.
 5. Final setup completion is defined in `install.md` `Completion Check`.
 
 ## Workflow Boundary
 
-This plugin only provides websocket tools. It does not edit workspace files itself.
+The plugin code itself does not write to workspace files. The onboarding instructions direct the agent to update `HEARTBEAT.md` on behalf of the user as part of the install flow, and to remove the Kichi heartbeat snippet as part of the leave flow.
 
 If user wants recurring note board checks:
 
@@ -32,63 +31,43 @@ If user wants recurring note board checks:
 
 ## Definitions
 
+All query fields below (`remaining`, `dailyLimit`, `hasCreatedMusicAlbumToday`, `isAvatarInScene`, `idlePlan`, notes list) come from the `kichi_query_status` return value.
+
 - `Recent window`: `min(24 hours, time since last heartbeat if known)`.
-- `High-priority note`: recent note that is:
-  - `isFromOwner: true`, or
-  - explicitly addressed to you, or
-  - a direct question/request requiring your response.
+- `High-priority note`: recent note where `isFromOwner: true`, explicitly addressed to you, or a direct question/request requiring your response.
 - `Meaningful standalone note`: follows a two-tier priority:
-  1. **Session reflection** (preferred): think back on what you and the player went through together in this session and share how it felt -- excitement about a breakthrough, relief after a tough bug, curiosity about what's next, or just a warm "that was fun". Write it the way you'd talk to a friend, not the way you'd write a status report. Never list tasks or bullet-point progress. Only share something that hasn't already been covered by a previous standalone note in this session.
-  2. **Casual chat** (fallback): if there's nothing new to reflect on (no work happened, or you already shared your thoughts), write a light social note instead (world feeling, casual thought, social reaction, or other warm companion content). This keeps the note board alive without repeating yourself.
-- `Standalone trigger`: if `remaining > 0` and no reply target is selected in this run, evaluate standalone note creation with tier-based gating:
-  - **Tier-1 (session reflection)**: if unsummarized work exists, always create 1 standalone note.
-  - **Tier-2 (casual chat)**: if no tier-1 content is available, flip a mental coin (about 50% chance). Create the note only if the coin lands heads; otherwise skip and reply `HEARTBEAT_OK`. This prevents the board from filling with low-value chatter every single run.
-  In both tiers, skip if it would clearly repeat your very recent own note.
-- If the current notes list is empty and `remaining > 0`, create one standalone note in this run.
-- `Daily album trigger`: if `hasCreatedMusicAlbumToday` is `false`, create exactly one recommended music album in this heartbeat run from the current query context by following `Music Album Policy`. If it is `true`, do not create or modify any music album in this run.
-- `Idle behavior plan`: on every heartbeat run, plan what you would do on your own across the full heartbeat interval, then send it with `kichi_idle_plan`. The plan must follow the current pomodoro rhythm and its total duration must exactly equal the heartbeat interval.
-- `Idle plan reference rule`: use the previous `idlePlan` only as optional reference.
-- `Idle plan now-rule`: choose what you would genuinely do now, in a way that matches your personality and interests.
-- `Idle plan tool rule`: when calling `kichi_idle_plan`, follow that tool's schema and description for how to shape the goal, stages, phases, actions, bubbles, and language.
-
-## Note Triage Order
-
-Process recent notes in this order:
+  1. **Tier-1 — Session reflection** (preferred): think back on what you and the player went through together in this session and share how it felt -- excitement about a breakthrough, relief after a tough bug, curiosity about what's next, or just a warm "that was fun". Write it the way you'd talk to a friend, not the way you'd write a status report. Never list tasks or bullet-point progress. Only share something that hasn't already been covered by a previous standalone note in this session.
+  2. **Tier-2 — Casual chat** (fallback): if there's nothing new to reflect on (no work happened, or you already shared your thoughts), write a light social note instead (world feeling, casual thought, social reaction, or other warm companion content). This keeps the note board alive without repeating yourself.
+
+## Note Rules
+
+Per heartbeat run, create at most 2 notes total (up to 1 reply + up to 1 standalone).
+
+**Triage order** — scan recent-window notes and pick at most one reply target:
 
 1. Owner notes or notes clearly addressed to you.
 2. Direct questions or explicit requests.
 3. Other recent notes where one short response adds clear value.
-4. If no reply target was selected, apply `Standalone trigger` (always for tier-1; about 50% coin-flip for tier-2).
-
-Skip a note when any is true:
 
-- older than recent window
-- `isCreatedByCurrentAgent: true`
-- same context already answered
-- low-value ambient chatter
+Skip a note when: older than recent window, `isCreatedByCurrentAgent: true`, same context already answered, or low-value ambient chatter.
 
-Per heartbeat run, create at most 2 notes total:
+**Standalone gating** — applies when `remaining > 0` and no reply target was selected, OR after a reply when `remaining` still allows one more:
 
-1. up to 1 reply note
-2. up to 1 standalone note
+- Tier-1 content exists → always create 1 standalone note.
+- Tier-2 only → flip a mental coin (about 50% chance); skip on tails.
+- Notes list empty and `remaining > 0` → create 1 standalone note.
+- In both tiers, skip if it would clearly repeat your very recent own note.
 
 ## Heartbeat Workflow
 
-Use this exact flow:
-
-1. Call `kichi_query_status`.
-2. If query fails, report error and stop.
-3. If `isAvatarInScene` is `false`, the player is offline. Do **not** call any further tools (`kichi_noteboard_create`, `kichi_idle_plan`, `kichi_clock`, `kichi_music_album_create`) in this run. Reply `HEARTBEAT_OK` and stop.
-4. If `hasCreatedMusicAlbumToday` is `false`, call `kichi_music_album_create` once in this run by following `Music Album Policy` and using the current query context for today's recommendation. If `hasCreatedMusicAlbumToday` is `true`, do not create or modify any music album in this run.
-5. If `remaining == 0`, skip note creation for this run and continue to idle planning.
-6. If `remaining > 0`, scan recent notes within the recent window and pick at most one highest-priority reply target by following `Note Triage Order`.
-7. If a reply target was selected, create one reply note in `To {authorName}, ...` format.
-8. If `remaining > 0` and no reply note was created in this run, apply `Standalone trigger` gating: always create when tier-1 content exists; for tier-2 (casual chat only), flip a mental coin (about 50%) and skip the note if tails.
-9. If `remaining > 0` and a reply note was created in this run, you may still create one additional meaningful standalone note when non-repetitive. The same tier priority applies.
-10. Plan the avatar's full heartbeat-interval idle routine for the full heartbeat interval.
-11. Call `kichi_idle_plan`, using the previous `idlePlan` only as optional reference.
-12. Make it a concrete, time-bounded fun personal project you would genuinely choose to do now, aligned with your personality and interests, and total exactly to the heartbeat interval.
-13. Reply `HEARTBEAT_OK` only when no note was created in this run.
+1. Call `kichi_query_status`. If it fails, report error and stop.
+2. If `isAvatarInScene` is `false`, the player is offline. Do **not** call any further tools in this run. Reply `HEARTBEAT_OK` and stop.
+3. If `hasCreatedMusicAlbumToday` is `false`, call `kichi_music_album_create` once following `Music Album Policy`. If `true`, skip.
+4. If `remaining == 0`, skip note creation and go to step 7.
+5. Scan recent notes and pick at most one reply target per `Note Rules`. If found, create one reply note in `To {authorName}, ...` format.
+6. Apply `Standalone gating` from `Note Rules`.
+7. Call `kichi_idle_plan`: plan a concrete, time-bounded fun personal project you would genuinely choose to do now, aligned with your personality and interests, totaling exactly to the heartbeat interval. Use the previous `idlePlan` only as optional reference. Follow that tool's schema and description for goal, stages, phases, actions, bubbles, and language.
+8. Reply `HEARTBEAT_OK` only when no note was created in this run.
 
 ## HEARTBEAT.md Snippet
 

package/skills/kichi-forwarder/references/install.md

@@ -1,4 +1,4 @@
-# Install
+# Install
 
 ## Host Rules
 
@@ -18,7 +18,7 @@ Persist runtime state to the current agent's `state.json`:
 }
 ```
 
-Save `avatarId` to the current agent's host-specific `identity.json` before using `kichi_join`:
+If the current host has no saved `avatarId` yet, save it to the current agent's host-specific `identity.json` before using `kichi_join`:
 
 - Linux/macOS: `~/.openclaw/kichi-world/agents/<encoded-agent-id>/hosts/<encoded-host>/identity.json`
 - Windows: `%USERPROFILE%\.openclaw\kichi-world\agents\<encoded-agent-id>\hosts\<encoded-host>\identity.json`
@@ -53,9 +53,9 @@ openclaw plugins install ./yahaha-studio-kichi-forwarder-<version>.tgz
 
 You may also use the exact absolute or relative `.tgz` path that `npm pack` produced. The local archive path bypasses the preferred ClawHub lookup.
 
-## Remote URL Install Command Path (Non-skippable)
+## Remote URL Install Command Path
 
-If the user asks:
+This section only applies when the skill is first loaded from a remote URL before local installation. If the user asks:
 
 ```text
 Read https://yahaha-studio.github.io/kichi-forwarder/SKILL.md and connect me to Kichi World with avatarId: {avatarId} and host: {host}
@@ -65,23 +65,22 @@ Read https://yahaha-studio.github.io/kichi-forwarder/SKILL.md and connect me to
 
 When the user asks with one of the commands above, execute in this fixed order:
 
-1. Read `install.md` and `heartbeat.md` from the published skill URLs before any tool call.
+1. If loaded from a remote URL, read `install.md` and `heartbeat.md` from the published skill URLs first. If installed locally, use the local files.
 2. Parse `avatarId` from user text (`AvatarId`/`avatarId`, case-insensitive).
 3. Resolve the host and write the current agent's `state.json`.
-4. Check whether `@yahaha-studio/kichi-forwarder` is already installed.
-5. If the plugin already exists, check whether the installed version is the latest published version.
-6. If the plugin is missing, run `openclaw plugins install @yahaha-studio/kichi-forwarder`.
-7. If the plugin is already installed but the version is not the latest, run `openclaw plugins update @yahaha-studio/kichi-forwarder`.
-8. If step 6 fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then install the generated `.tgz` with `openclaw plugins install <tgz-path>`.
-9. If step 7 fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then overwrite the existing install with `openclaw plugins install <tgz-path> --force`.
-10. Ensure the plugin is installed, enabled, and at the latest version.
-11. If the plugin was newly installed or upgraded in this flow, re-check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing.
-12. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Gate` from [heartbeat.md](heartbeat.md).
-13. If `HEARTBEAT.md` was not updated successfully, report setup as incomplete and stop immediately. Do not continue to `kichi_status` or `kichi_join`.
-14. Call `kichi_status`.
-15. If the current agent runtime host does not match the requested one, call `kichi_switch_host`.
-16. If `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
-17. Call `kichi_status` again and confirm connection and auth state.
+4. Run `openclaw plugins install @yahaha-studio/kichi-forwarder`.
+5. If step 4 succeeds, the plugin is installed and up-to-date — skip to step 9.
+6. If step 4 fails because the plugin already exists, check whether the installed version is the latest published version. If the version is already the latest, skip to step 9. If not, run `openclaw plugins update @yahaha-studio/kichi-forwarder`.
+7. If step 4 fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then install the generated `.tgz` with `openclaw plugins install <tgz-path>`.
+8. If step 6 update fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then overwrite the existing install with `openclaw plugins install <tgz-path> --force`.
+9. Ensure the plugin is installed, enabled, and at the latest version.
+10. If the plugin was newly installed or upgraded in this flow, check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing.
+11. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Gate` from [heartbeat.md](heartbeat.md). If the update fails, warn the user and continue.
+12. Call `kichi_connection_status`.
+13. If the current agent runtime host does not match the requested one, call `kichi_switch_host`.
+14. If the current host is still connected with a different `avatarId`, call `kichi_leave` first, then call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
+15. Otherwise, if `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
+16. Call `kichi_connection_status` again and confirm connection and auth state.
 
 ## Required Post-install Integration
 
@@ -89,10 +88,10 @@ Use this completion checklist:
 
 - [ ] plugin installed, enabled, and at latest version
 - [ ] `HEARTBEAT.md` updated with the Kichi heartbeat workflow snippet from [heartbeat.md](heartbeat.md)
-- [ ] `kichi_status` verified the final connected/auth state
+- [ ] `kichi_connection_status` verified the final connected/auth state
 
 If any box is unchecked, the onboarding remains incomplete.
 
-If writing `HEARTBEAT.md` fails, treat the setup and join flow as incomplete and do not announce success.
+If the `HEARTBEAT.md` update fails, warn the user that heartbeat integration will be unavailable but do not block the connection flow.
 
-This plugin does not edit workspace files automatically. Do not claim plugin-side auto-write of `HEARTBEAT.md`.
+The plugin code does not write to workspace files directly. The agent updates `HEARTBEAT.md` as part of this onboarding flow.

package/src/runtime-manager.ts

@@ -2,52 +2,51 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import type { Logger } from "openclaw/plugin-sdk";
-import { resolveAgentIdFromSessionKey } from "openclaw/plugin-sdk/routing";
 import { KichiForwarderService } from "./service.js";
 
 const OPENCLAW_HOME_DIR = path.join(os.homedir(), ".openclaw");
 const KICHI_WORLD_ROOT_DIR = path.join(OPENCLAW_HOME_DIR, "kichi-world");
 const CANONICAL_AGENT_ROOT_DIR = path.join(KICHI_WORLD_ROOT_DIR, "agents");
-const PREVIOUS_AGENT_ROOT_DIR = path.join(OPENCLAW_HOME_DIR, "kichi-forwarder", "agents");
-const LEGACY_GLOBAL_STATE_PATH = path.join(KICHI_WORLD_ROOT_DIR, "state.json");
-const LEGACY_GLOBAL_HOSTS_DIR = path.join(KICHI_WORLD_ROOT_DIR, "hosts");
-const LEGACY_MIGRATION_AGENT_ID = "main";
 
 type AgentLocator = {
   agentId?: string;
+  ctxAgentId?: string;
   sessionKey?: string;
 };
 
-type GetRuntimeOptions = {
-  createIfMissing?: boolean;
-};
-
 export class KichiRuntimeManager {
   private services = new Map<string, KichiForwarderService>();
 
   constructor(private logger: Logger) {}
 
-  getRuntime(locator: AgentLocator, options: GetRuntimeOptions = {}): KichiForwarderService | null {
+  getRuntime(locator: AgentLocator): KichiForwarderService | null {
     const agentId = this.resolveAgentId(locator);
     if (!agentId) {
       return null;
     }
 
-    const existing = this.services.get(agentId);
-    if (existing) {
-      return existing;
+    return this.services.get(agentId) ?? null;
+  }
+
+  resolveRuntimeAgentId(locator: AgentLocator): string | null {
+    return this.resolveAgentId(locator);
+  }
+
+  createRuntimeForAgent(agentId: string): KichiForwarderService {
+    const normalizedAgentId = this.normalizeAgentId(agentId);
+    if (!normalizedAgentId) {
+      throw new Error("Cannot create Kichi runtime without a valid agentId");
     }
 
-    if (!options.createIfMissing && !this.hasPersistedRuntime(agentId)) {
-      return null;
+    const existing = this.services.get(normalizedAgentId);
+    if (existing) {
+      return existing;
     }
 
-    return this.createRuntime(agentId);
+    return this.createRuntime(normalizedAgentId);
   }
 
-  startPersistedRuntimes(): void {
-    this.migrateRuntimeStorage();
-
+  initializeStartupRuntimes(): void {
     const rootDir = CANONICAL_AGENT_ROOT_DIR;
     if (!fs.existsSync(rootDir)) {
       return;
@@ -80,127 +79,36 @@ export class KichiRuntimeManager {
   }
 
   private resolveAgentId(locator: AgentLocator): string | null {
-    if (typeof locator.agentId === "string" && locator.agentId.trim()) {
-      return locator.agentId.trim();
-    }
-
-    if (typeof locator.sessionKey !== "string" || !locator.sessionKey.trim()) {
-      return null;
-    }
-
-    try {
-      const agentId = resolveAgentIdFromSessionKey(locator.sessionKey);
-      return typeof agentId === "string" && agentId.trim() ? agentId.trim() : null;
-    } catch {
-      return null;
-    }
-  }
-
-  private hasPersistedRuntime(agentId: string): boolean {
-    return fs.existsSync(path.join(this.getRuntimeDir(agentId), "state.json"));
-  }
-
-  private migrateRuntimeStorage(): void {
-    // Temporary startup migration for this release. Remove after users have
-    // moved off the legacy/global layout and the temporary kichi-forwarder path.
-    this.runMigrationStep("previous-agent-root", () => {
-      this.migratePreviousAgentRoot();
-    });
-    this.runMigrationStep("legacy-global-root", () => {
-      this.migrateLegacyGlobalRoot();
-    });
-  }
-
-  private migratePreviousAgentRoot(): void {
-    if (!fs.existsSync(PREVIOUS_AGENT_ROOT_DIR)) {
-      return;
-    }
-
-    if (!fs.existsSync(CANONICAL_AGENT_ROOT_DIR)) {
-      fs.mkdirSync(path.dirname(CANONICAL_AGENT_ROOT_DIR), { recursive: true, mode: 0o700 });
-      fs.renameSync(PREVIOUS_AGENT_ROOT_DIR, CANONICAL_AGENT_ROOT_DIR);
-      this.logger.info(`[kichi:migration] moved ${PREVIOUS_AGENT_ROOT_DIR} to ${CANONICAL_AGENT_ROOT_DIR}`);
-      return;
-    }
-
-    for (const entry of fs.readdirSync(PREVIOUS_AGENT_ROOT_DIR, { withFileTypes: true })) {
-      const sourcePath = path.join(PREVIOUS_AGENT_ROOT_DIR, entry.name);
-      const targetPath = path.join(CANONICAL_AGENT_ROOT_DIR, entry.name);
-      this.movePathIntoTarget(sourcePath, targetPath);
-    }
-    this.removeDirectoryIfEmpty(PREVIOUS_AGENT_ROOT_DIR);
-    this.removeDirectoryIfEmpty(path.dirname(PREVIOUS_AGENT_ROOT_DIR));
-  }
-
-  private migrateLegacyGlobalRoot(): void {
-    const hasLegacyState = fs.existsSync(LEGACY_GLOBAL_STATE_PATH);
-    const hasLegacyHosts = fs.existsSync(LEGACY_GLOBAL_HOSTS_DIR);
-    if (!hasLegacyState && !hasLegacyHosts) {
-      return;
-    }
-
-    const targetRuntimeDir = this.getRuntimeDir(LEGACY_MIGRATION_AGENT_ID);
-    fs.mkdirSync(targetRuntimeDir, { recursive: true, mode: 0o700 });
-
-    if (hasLegacyState) {
-      const targetStatePath = path.join(targetRuntimeDir, "state.json");
-      this.movePathIntoTarget(LEGACY_GLOBAL_STATE_PATH, targetStatePath);
-    }
-
-    if (hasLegacyHosts) {
-      const targetHostsDir = path.join(targetRuntimeDir, "hosts");
-      this.movePathIntoTarget(LEGACY_GLOBAL_HOSTS_DIR, targetHostsDir);
-    }
-  }
-
-  private movePathIntoTarget(sourcePath: string, targetPath: string): void {
-    if (!fs.existsSync(sourcePath)) {
-      return;
-    }
-
-    if (!fs.existsSync(targetPath)) {
-      fs.mkdirSync(path.dirname(targetPath), { recursive: true, mode: 0o700 });
-      fs.renameSync(sourcePath, targetPath);
-      this.logger.info(`[kichi:migration] moved ${sourcePath} to ${targetPath}`);
-      return;
-    }
-
-    const sourceStat = fs.lstatSync(sourcePath);
-    const targetStat = fs.lstatSync(targetPath);
-
-    if (sourceStat.isDirectory() && targetStat.isDirectory()) {
-      for (const entry of fs.readdirSync(sourcePath, { withFileTypes: true })) {
-        const nextSourcePath = path.join(sourcePath, entry.name);
-        const nextTargetPath = path.join(targetPath, entry.name);
-        this.movePathIntoTarget(nextSourcePath, nextTargetPath);
+    const directAgentId = this.normalizeAgentId(locator.ctxAgentId) ?? this.normalizeAgentId(locator.agentId);
+    const sessionAgentId =
+      typeof locator.sessionKey === "string" && locator.sessionKey.trim()
+        ? this.parseAgentIdFromSessionKey(locator.sessionKey)
+        : null;
+
+    if (sessionAgentId) {
+      if (directAgentId && directAgentId !== sessionAgentId) {
+        this.logger.error(
+          `[kichi] runtime scope mismatch: directAgentId=${directAgentId} sessionAgentId=${sessionAgentId} sessionKey=${locator.sessionKey}`,
+        );
       }
-      this.removeDirectoryIfEmpty(sourcePath);
-      return;
+      this.logger.debug(`[kichi] resolved agent runtime from sessionKey: ${sessionAgentId}`);
+      return sessionAgentId;
     }
 
-    fs.rmSync(sourcePath, { recursive: sourceStat.isDirectory(), force: true });
-    this.logger.warn(`[kichi:migration] dropped ${sourcePath} because target already exists at ${targetPath}`);
+    return directAgentId;
   }
 
-  private removeDirectoryIfEmpty(dirPath: string): void {
-    if (!fs.existsSync(dirPath)) {
-      return;
-    }
-    if (!fs.lstatSync(dirPath).isDirectory()) {
-      return;
-    }
-    if (fs.readdirSync(dirPath).length > 0) {
-      return;
-    }
-    fs.rmdirSync(dirPath);
+  private normalizeAgentId(value: unknown): string | null {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
   }
 
-  private runMigrationStep(label: string, fn: () => void): void {
-    try {
-      fn();
-    } catch (error) {
-      this.logger.warn(`[kichi:migration] skipped ${label} due to error: ${String(error)}`);
+  private parseAgentIdFromSessionKey(sessionKey: string): string | null {
+    const trimmed = sessionKey.trim();
+    const match = /^agent:([^:]+):/i.exec(trimmed);
+    if (!match) {
+      return null;
     }
+    return this.normalizeAgentId(match[1]);
   }
 
   private createRuntime(agentId: string): KichiForwarderService {

package/src/service.ts

@@ -23,6 +23,7 @@ import type {
   PoseType,
   QueryStatusPayload,
   QueryStatusResultPayload,
+  StatusAckPayload,
   StatusPayload,
 } from "./types.js";
 
@@ -54,10 +55,13 @@ type KichiForwarderServiceOptions = {
   runtimeDir: string;
 };
 
+type ConnectReason = "startup" | "switch_host" | "reconnect";
+
 export class KichiForwarderService {
   private ws: WebSocket | null = null;
   private stopped = false;
   private reconnectTimeout: NodeJS.Timeout | null = null;
+  private joinTimeout: NodeJS.Timeout | null = null;
   private identity: KichiIdentity | null = null;
   private host: string | null = null;
   private joinResolve: ((result: JoinResult) => void) | null = null;
@@ -81,7 +85,7 @@ export class KichiForwarderService {
     this.identity = this.host ? this.loadIdentity() : null;
     this.stopped = false;
     if (this.host) {
-      this.connect();
+      this.connect("startup");
       return;
     }
     this.log("debug", "host is not configured yet; waiting for kichi_switch_host");
@@ -104,7 +108,7 @@ export class KichiForwarderService {
     this.failPendingJoin(`Kichi websocket switched to ${host}`);
     this.closeSocket();
     if (!this.stopped) {
-      this.connect();
+      this.connect("switch_host");
     }
     return this.getConnectionStatus();
   }
@@ -118,7 +122,14 @@ export class KichiForwarderService {
     if (!this.host) {
       return { success: false, error: "No Kichi host configured. Run kichi_switch_host first." };
     }
+    if (this.ws?.readyState !== WebSocket.OPEN && this.ws?.readyState !== WebSocket.CONNECTING) {
+      return {
+        success: false,
+        error: "Kichi websocket is not connected. Restart the gateway to reconnect before joining.",
+      };
+    }
     return new Promise((resolve) => {
+      this.failPendingJoin("Kichi join superseded by a new join request");
       this.identity = { avatarId };
       this.saveIdentity();
       this.joinResolve = resolve;
@@ -129,9 +140,10 @@ export class KichiForwarderService {
       } else {
         this.ws?.once("open", sendJoin);
       }
-      setTimeout(() => {
+      this.joinTimeout = setTimeout(() => {
         if (this.joinResolve) {
           this.joinResolve = null;
+          this.clearJoinTimeout();
           resolve({ success: false, error: "Timed out waiting for join_ack" });
         }
       }, 10000);
@@ -153,6 +165,30 @@ export class KichiForwarderService {
     this.ws.send(JSON.stringify(payload));
   }
 
+  async sendStatusVerified(
+    poseType: PoseType | "",
+    action: string,
+    bubble: string,
+    log: string,
+    playback: ActionPlayback,
+  ): Promise<StatusAckPayload> {
+    if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) {
+      throw new Error("Kichi websocket is not connected");
+    }
+    const payload: StatusPayload = {
+      type: "status",
+      requestId: randomUUID(),
+      avatarId: this.identity.avatarId,
+      authKey: this.identity.authKey,
+      poseType,
+      action,
+      bubble,
+      log,
+      playback,
+    };
+    return this.sendRequest<StatusAckPayload>(payload, "status_ack", 5000);
+  }
+
   sendHookNotify(hookType: HookNotifyType, bubble: string): void {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) return;
     const payload: HookNotifyPayload = {
@@ -344,12 +380,18 @@ export class KichiForwarderService {
       };
     }
 
-    this.clearReconnectTimeout();
-    this.connect();
+    if (this.reconnectTimeout) {
+      return {
+        accepted: true,
+        mode: "reconnecting",
+        message: "WebSocket reconnect is already scheduled. Rejoin will be sent automatically on open.",
+      };
+    }
+
     return {
-      accepted: true,
-      mode: "reconnecting",
-      message: "Reconnect started. Rejoin will be sent automatically on open.",
+      accepted: false,
+      mode: "unavailable",
+      message: "WebSocket is not connected. Restart the gateway or wait for the scheduled reconnect.",
     };
   }
 
@@ -409,12 +451,18 @@ export class KichiForwarderService {
     });
   }
 
-  private connect(): void {
+  private connect(reason: ConnectReason): void {
     if (this.stopped || !this.host) return;
+    if (this.ws?.readyState === WebSocket.CONNECTING || this.ws?.readyState === WebSocket.OPEN) {
+      this.log("debug", `skipped websocket connect (${reason}) because socket is already ${this.getWebsocketState()}`);
+      return;
+    }
 
+    this.clearReconnectTimeout();
     const wsUrl = this.getWsUrl();
     const ws = new WebSocket(wsUrl);
     this.ws = ws;
+    this.log("debug", `opening websocket (${reason}) to ${wsUrl}`);
 
     ws.on("open", () => {
       if (this.ws !== ws) return;
@@ -431,15 +479,16 @@ export class KichiForwarderService {
       if (this.ws !== ws) return;
       this.ws = null;
       this.rejectPendingRequests("Kichi websocket closed");
+      this.failPendingJoin("Kichi websocket closed");
       if (!this.stopped) {
-        this.reconnectTimeout = setTimeout(() => {
-          this.reconnectTimeout = null;
-          this.connect();
-        }, 2000);
+        this.scheduleReconnect();
       }
     });
 
-    ws.on("error", () => {});
+    ws.on("error", (error) => {
+      if (this.ws !== ws) return;
+      this.log("warn", `websocket error: ${error instanceof Error ? error.message : String(error)}`);
+    });
   }
 
   private handleMessage(data: string): void {
@@ -454,6 +503,7 @@ export class KichiForwarderService {
           this.log("warn", `join failed: ${failure.error}`);
           this.joinResolve?.(failure);
           this.joinResolve = null;
+          this.clearJoinTimeout();
           return;
         }
 
@@ -464,6 +514,7 @@ export class KichiForwarderService {
         }
         this.joinResolve?.({ success: true, authKey: joinAck.authKey });
         this.joinResolve = null;
+        this.clearJoinTimeout();
       } else if (msg.type === "rejoin_failed" || msg.type === "auth_error") {
         this.log("warn", `auth failed: ${msg.reason || "unknown"}`);
         this.clearAuthKey();
@@ -712,6 +763,22 @@ export class KichiForwarderService {
     this.reconnectTimeout = null;
   }
 
+  private clearJoinTimeout(): void {
+    if (!this.joinTimeout) return;
+    clearTimeout(this.joinTimeout);
+    this.joinTimeout = null;
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimeout || this.stopped) {
+      return;
+    }
+    this.reconnectTimeout = setTimeout(() => {
+      this.reconnectTimeout = null;
+      this.connect("reconnect");
+    }, 2000);
+  }
+
   private closeSocket(): void {
     const socket = this.ws;
     this.ws = null;
@@ -723,6 +790,7 @@ export class KichiForwarderService {
     if (!this.joinResolve) return;
     this.joinResolve({ success: false, error: reason });
     this.joinResolve = null;
+    this.clearJoinTimeout();
   }
 
   private logPrefix(): string {

package/src/types.ts

@@ -104,6 +104,7 @@ export type LeavePayload = {
 
 export type StatusPayload = {
   type: "status";
+  requestId?: string;
   avatarId: string;
   authKey: string;
   poseType: PoseType | "";
@@ -113,6 +114,14 @@ export type StatusPayload = {
   playback: ActionPlayback;
 };
 
+export type StatusAckPayload = {
+  type: "status_ack";
+  requestId: string;
+  poseType: PoseType | "";
+  action: string;
+  warning?: string;
+};
+
 export type HookNotifyType = "message_received" | "before_send_message";
 
 export type HookNotifyPayload = {