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

package/index.ts

@@ -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)"})`,
@@ -913,6 +973,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(", ")}`,
@@ -944,7 +1005,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 +1013,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 +1044,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];
+        }
       },
     });
 
@@ -1031,7 +1113,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 +1147,8 @@ const plugin = {
           status,
         };
       },
-    })));
+      });
+    });
 
     api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_rejoin",

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.3",
   "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.3",
   "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

@@ -66,9 +66,10 @@ Install/onboarding requests are the exception: follow `install.md` first.
 
 1. If connection or identity is unknown, call `kichi_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
 

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

@@ -32,63 +32,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

@@ -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`
@@ -80,8 +80,9 @@ When the user asks with one of the commands above, execute in this fixed order:
 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.
+16. 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`.
+17. Otherwise, if `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
+18. Call `kichi_status` again and confirm connection and auth state.
 
 ## Required Post-install Integration
 

package/src/runtime-manager.ts

@@ -2,7 +2,6 @@ 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");
@@ -15,37 +14,43 @@ 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 {
+  initializeStartupRuntimes(): void {
     this.migrateRuntimeStorage();
 
     const rootDir = CANONICAL_AGENT_ROOT_DIR;
@@ -80,24 +85,36 @@ export class KichiRuntimeManager {
   }
 
   private resolveAgentId(locator: AgentLocator): string | null {
-    if (typeof locator.agentId === "string" && locator.agentId.trim()) {
-      return locator.agentId.trim();
+    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.logger.debug(`[kichi] resolved agent runtime from sessionKey: ${sessionAgentId}`);
+      return sessionAgentId;
     }
 
-    if (typeof locator.sessionKey !== "string" || !locator.sessionKey.trim()) {
-      return null;
-    }
+    return directAgentId;
+  }
 
-    try {
-      const agentId = resolveAgentIdFromSessionKey(locator.sessionKey);
-      return typeof agentId === "string" && agentId.trim() ? agentId.trim() : null;
-    } catch {
-      return null;
-    }
+  private normalizeAgentId(value: unknown): string | null {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
   }
 
-  private hasPersistedRuntime(agentId: string): boolean {
-    return fs.existsSync(path.join(this.getRuntimeDir(agentId), "state.json"));
+  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 migrateRuntimeStorage(): void {

package/src/service.ts

@@ -54,10 +54,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 +84,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 +107,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 +121,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 +139,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);
@@ -344,12 +355,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 +426,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 +454,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 +478,7 @@ export class KichiForwarderService {
           this.log("warn", `join failed: ${failure.error}`);
           this.joinResolve?.(failure);
           this.joinResolve = null;
+          this.clearJoinTimeout();
           return;
         }
 
@@ -464,6 +489,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 +738,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 +765,7 @@ export class KichiForwarderService {
     if (!this.joinResolve) return;
     this.joinResolve({ success: false, error: reason });
     this.joinResolve = null;
+    this.clearJoinTimeout();
   }
 
   private logPrefix(): string {