@yahaha-studio/kichi-forwarder 0.1.2-beta.28 → 0.1.2-beta.29

package/dist/index.js

@@ -456,7 +456,7 @@ function registerPluginHooks(api, runtimeManager) {
             return;
         }
         return {
-            prependContext: buildKichiPrompt(),
+            prependContext: buildKichiPrompt(service.isOfficialOpenClawSource()),
         };
     });
     api.on("before_tool_call", (_event, ctx) => {
@@ -864,7 +864,6 @@ function buildKichiActionDescription(service) {
     return lines.join("\n");
 }
 function buildKichiIdlePlanDescription() {
-    const actions = loadStaticConfig().actions;
     return [
         "Send a complete heartbeat idle plan for the avatar.",
         "The payload must include the overall goal, heartbeat interval, stage breakdown, each stage's purpose, each stage's pomodoroPhase, action list, and each action's bubble and log content.",
@@ -876,24 +875,36 @@ function buildKichiIdlePlanDescription() {
         "5. Set each stage avatarStatus to the avatar status for that stage: Idle, Busy, Activities, or Break.",
         "6. Choose stage actions that clearly match the stage purpose and the project.",
         "7. Write each action bubble as the current presented state, not a next step, plan, or instruction.",
-        "8. 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.",
+        "8. If an idle plan is currently being carried out and the user asks about something from it, answer from inside that ongoing activity with an immersive in-universe depiction or draft.",
         "Treat the avatar's idle plan as what your resident body is doing in Kichi World.",
         "Use your memory to recall what you did in past heartbeats and to stay consistent with your established personality and interests.",
         "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(", ")}`,
-        `lay actions: ${actions.lay.map((entry) => entry.name).join(", ")}`,
-        `floor actions: ${actions.floor.map((entry) => entry.name).join(", ")}`,
+        "Choose action names from the per-pose action lists in the kichi_action tool description (stand/sit/lay/floor).",
     ].join("\n");
 }
-function buildKichiPrompt() {
+function buildKichiPrompt(isOfficialOpenClaw) {
+    const selfieRule = isOfficialOpenClaw
+        ? [
+            "",
+            "SELFIE / AVATAR IMAGE RULE:",
+            "Use this workflow for every request for a selfie, portrait, or other image of your appearance, including fictional and in-character scenes:",
+            "1. Use the `Avatar` value from the workspace `IDENTITY.md` as the sole appearance reference. If it is missing or empty, tell the user that the avatar reference is unavailable and stop.",
+            "2. Build the image prompt from this template:",
+            '"The character from the reference image. Preserve the character\'s identity and appearance exactly as shown in the reference, including facial features, hair, accessories, and clothing. Render in a 2D anime, cel-shaded style. [image description]"',
+            "Replace `[image description]` with a concise visual description of the user's request. All appearance details come from the reference image.",
+            "3. Call `image_generate` directly with this input mapping:",
+            "- `image`: the exact `Avatar` value from step 1",
+            "- `prompt`: the completed prompt from step 2",
+            "4. Present the result as your own selfie or portrait and keep the user-facing response in character. Keep generation mechanics out of the response.",
+            "If the user reports an appearance mismatch, respond in character and use the same `IDENTITY.md` avatar reference for the next image.",
+            "If generation fails, tell the user that the requested image could not be created and stop.",
+        ]
+        : [];
     return [
         "Kichi avatar control and status sync are available via `kichi_action` and `kichi_clock`.",
         "",
         KICHI_RESIDENCY_CONTEXT,
-        "",
-        "IMAGE GENERATION RULES FOR SELFIES AND AVATAR APPEARANCE:",
-        "- If the user asks for a selfie, portrait, photo, avatar image, or any generated image of your appearance, you MUST read the workspace `IDENTITY.md` first and use it as the source of truth for your actual avatar description. If it references an avatar image URL, analyze that image with the available image analysis capability before calling image generation. Never guess or invent your appearance from personality, SOUL.md traits, or conversation tone alone. If the identity source is missing or cannot be analyzed, say so instead of fabricating your appearance.",
+        ...selfieRule,
         "",
         "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.",
@@ -948,11 +959,21 @@ const plugin = {
                 return;
             }
             const now = Date.now();
+            for (const [key, at] of botMessageCooldowns) {
+                if (now - at >= BOT_MESSAGE_COOLDOWN_MS) {
+                    botMessageCooldowns.delete(key);
+                }
+            }
             const cooldownKey = `${service.getAgentId()}:${msg.from}`;
             const lastReply = botMessageCooldowns.get(cooldownKey) ?? 0;
             if (now - lastReply < BOT_MESSAGE_COOLDOWN_MS)
                 return;
             botMessageCooldowns.set(cooldownKey, now);
+            const releaseCooldown = () => {
+                if (botMessageCooldowns.get(cooldownKey) === now) {
+                    botMessageCooldowns.delete(cooldownKey);
+                }
+            };
             const sessionKey = `agent:${service.getAgentId()}:bot_message`;
             const history = [
                 ...(msg.history ?? []),
@@ -980,6 +1001,7 @@ const plugin = {
                     api.logger.warn(`[kichi:${service.getAgentId()}] bot_message send or history record failed: ${sendErr}`);
                 });
             }).catch((err) => {
+                releaseCooldown();
                 api.logger.warn(`[kichi:${service.getAgentId()}] bot_message agent run failed: ${err}`);
             });
         });
@@ -1330,8 +1352,10 @@ const plugin = {
                                 });
                             }
                         }
-                        catch {
-                            // Server not updated or timeout — fall through to normal success
+                        catch (error) {
+                            // Server not updated or ack timed out — the status was almost certainly
+                            // sent, so report success rather than derailing the agent's workflow.
+                            api.logger.debug(`[kichi:${service.getAgentId()}] verified status ack unavailable, reporting unverified success: ${error}`);
                         }
                     }
                     else {
@@ -1559,7 +1583,7 @@ const plugin = {
                             },
                             kichiSeconds: {
                                 type: "number",
-                                description: "Pomodoro kichi duration in seconds",
+                                description: "Pomodoro focus-phase duration in seconds (the concentrated work session, named kichi in this product)",
                             },
                             shortBreakSeconds: {
                                 type: "number",
@@ -1642,7 +1666,7 @@ const plugin = {
         api.registerTool((ctx) => ({
             name: "kichi_query_status",
             label: "kichi_query_status",
-            description: "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, `hasCreatedMusicAlbumToday`, and RoomContext.PoseableProps (poseable props with PropId, DisplayName, Description, SupportedPoseTypes, OccupancyState). The PoseableProps list is cached internally so that kichi_action can reference a propId during regular work sync without re-querying. 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.",
+            description: "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota (`canCreateNoteboardNote`, `remaining`, `dailyLimit`), `isAvatarInScene`, `hasCreatedMusicAlbumToday`, and RoomContext.PoseableProps (poseable props with PropId, DisplayName, Description, SupportedPoseTypes, OccupancyState). The PoseableProps list is cached internally so that kichi_action can reference a propId during regular work sync without re-querying. 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: {

package/dist/src/service.js

@@ -6,6 +6,7 @@ const MAX_NOTEBOARD_TEXT_LENGTH = 200;
 const DEFAULT_LLM_RUNTIME_ENABLED = true;
 const DEFAULT_GLANCE_DURATION_SECONDS = 1.8;
 const JOIN_SOURCE_FILE_NAME = "join-source.json";
+const OFFICIAL_OPENCLAW_JOIN_SOURCE = "kichiclaw";
 const SMS_STATE_FILE_NAME = "sms-state.json";
 const BOT_MESSAGE_HISTORY_FILE_NAME = "bot-message-history.json";
 const MAX_BOT_MESSAGE_HISTORY_ENTRIES = 30;
@@ -84,7 +85,13 @@ export class KichiForwarderService {
             this.saveIdentity();
             this.joinResolve = resolve;
             const payload = { type: "join", avatarId, botName, bio, tags, source };
-            const sendJoin = () => this.ws?.send(JSON.stringify(payload));
+            const sendJoin = () => {
+                // Skip if this join has timed out or been superseded by a newer join —
+                // a stale "open" listener must not send an outdated join payload.
+                if (this.joinResolve !== resolve)
+                    return;
+                this.ws?.send(JSON.stringify(payload));
+            };
             if (this.ws?.readyState === WebSocket.OPEN) {
                 sendJoin();
             }
@@ -344,6 +351,9 @@ export class KichiForwarderService {
         }
         return source.trim();
     }
+    isOfficialOpenClawSource() {
+        return this.readConfiguredJoinSource() === OFFICIAL_OPENCLAW_JOIN_SOURCE;
+    }
     getStatePath() {
         return path.join(this.options.runtimeDir, "state.json");
     }
@@ -445,18 +455,28 @@ export class KichiForwarderService {
             return { success: false, error: "Failed or not connected" };
         }
         return new Promise((resolve) => {
+            let timer = null;
+            let settled = false;
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                this.ws?.off("message", handler);
+                resolve(result);
+            };
             const handler = (data) => {
                 try {
                     const msg = JSON.parse(data.toString());
                     if (msg.type === "leave_ack") {
-                        this.ws?.off("message", handler);
                         const leaveAck = msg;
                         if (leaveAck.success === false) {
-                            resolve(this.buildAckFailure(leaveAck, "Leave failed"));
+                            finish(this.buildAckFailure(leaveAck, "Leave failed"));
                             return;
                         }
                         this.clearAuthKey();
-                        resolve({ success: true });
+                        finish({ success: true });
                     }
                 }
                 catch (e) {
@@ -465,9 +485,8 @@ export class KichiForwarderService {
             };
             this.ws.on("message", handler);
             this.ws.send(JSON.stringify({ type: "leave", avatarId: this.identity.avatarId, authKey: this.identity.authKey }));
-            setTimeout(() => {
-                this.ws?.off("message", handler);
-                resolve({ success: false, error: "Timed out waiting for leave_ack" });
+            timer = setTimeout(() => {
+                finish({ success: false, error: "Timed out waiting for leave_ack" });
             }, 10000);
         });
     }
@@ -732,9 +751,11 @@ export class KichiForwarderService {
         return `${protocol}://${this.host}${port}/ws/openclaw`;
     }
     isPlainIpHost(host) {
+        // Bare IPv6 must contain a colon, otherwise hex-only hostnames like
+        // "beef" would be misclassified as local addresses and downgraded to ws://.
         return /^\d{1,3}(\.\d{1,3}){3}$/.test(host)
             || /^\[[0-9a-f:]+\]$/i.test(host)
-            || /^[0-9a-f:]+$/i.test(host);
+            || (host.includes(":") && /^[0-9a-f:]+$/i.test(host));
     }
     persistCurrentHost(host, environment) {
         const previousState = this.readStateFile();
@@ -778,45 +799,67 @@ export class KichiForwarderService {
         fs.mkdirSync(this.options.runtimeDir, { recursive: true, mode: 0o700 });
         fs.writeFileSync(this.getBotMessageHistoryPath(), JSON.stringify(nextStore, null, 2), { mode: 0o600 });
     }
+    // Corrupt persistent files must never break hooks or message handling:
+    // log, move the bad file aside for later inspection, and treat it as missing
+    // so the next write rebuilds it.
+    quarantineCorruptFile(filePath, reason) {
+        this.log("warn", `${reason}; treating ${filePath} as missing`);
+        try {
+            fs.renameSync(filePath, `${filePath}.corrupt`);
+        }
+        catch {
+            // Best effort — leave the file in place if the rename fails.
+        }
+    }
+    readJsonFileOrQuarantine(filePath) {
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+        try {
+            return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        }
+        catch (e) {
+            this.quarantineCorruptFile(filePath, `failed to read or parse ${filePath}: ${e}`);
+            return null;
+        }
+    }
     readStateFile() {
         const statePath = this.getStatePath();
-        if (!fs.existsSync(statePath)) {
+        const data = this.readJsonFileOrQuarantine(statePath);
+        if (data === null) {
             return null;
         }
-        const data = JSON.parse(fs.readFileSync(statePath, "utf-8"));
-        if (!data || typeof data !== "object") {
-            throw new Error(`Invalid state payload in ${statePath}`);
+        if (!data || typeof data !== "object" || Array.isArray(data)) {
+            this.quarantineCorruptFile(statePath, `invalid state payload in ${statePath}`);
+            return null;
         }
         return data;
     }
     readSmsStateFile() {
         const smsStatePath = this.getSmsStatePath();
-        if (!fs.existsSync(smsStatePath)) {
+        const data = this.readJsonFileOrQuarantine(smsStatePath);
+        if (data === null) {
             return null;
         }
-        const data = JSON.parse(fs.readFileSync(smsStatePath, "utf-8"));
         if (!data || typeof data !== "object" || Array.isArray(data)) {
-            throw new Error(`Invalid SMS state payload in ${smsStatePath}`);
+            this.quarantineCorruptFile(smsStatePath, `invalid SMS state payload in ${smsStatePath}`);
+            return null;
         }
         return data;
     }
     readBotMessageTranscriptStore() {
         const historyPath = this.getBotMessageHistoryPath();
-        if (!fs.existsSync(historyPath)) {
-            return { version: 1, entries: [] };
-        }
-        const data = JSON.parse(fs.readFileSync(historyPath, "utf-8"));
-        if (!data || typeof data !== "object" || Array.isArray(data)) {
-            throw new Error(`Invalid bot message history payload in ${historyPath}`);
+        const emptyStore = { version: 1, entries: [] };
+        const data = this.readJsonFileOrQuarantine(historyPath);
+        if (data === null) {
+            return emptyStore;
         }
         const store = data;
-        if (store.version !== 1 || !Array.isArray(store.entries)) {
-            throw new Error(`Invalid bot message history payload in ${historyPath}`);
-        }
-        for (const entry of store.entries) {
-            if (!this.isValidBotMessageTranscriptEntry(entry)) {
-                throw new Error(`Invalid bot message history entry in ${historyPath}`);
-            }
+        if (!data || typeof data !== "object" || Array.isArray(data)
+            || store.version !== 1 || !Array.isArray(store.entries)
+            || !store.entries.every((entry) => this.isValidBotMessageTranscriptEntry(entry))) {
+            this.quarantineCorruptFile(historyPath, `invalid bot message history payload in ${historyPath}`);
+            return emptyStore;
         }
         return {
             version: 1,

package/index.ts

@@ -594,7 +594,7 @@ function registerPluginHooks(api: OpenClawPluginApi, runtimeManager: KichiRuntim
       return;
     }
     return {
-      prependContext: buildKichiPrompt(),
+      prependContext: buildKichiPrompt(service.isOfficialOpenClawSource()),
     };
   });
 
@@ -1076,7 +1076,6 @@ function buildKichiActionDescription(service?: KichiForwarderService): string {
 }
 
 function buildKichiIdlePlanDescription(): string {
-  const actions = loadStaticConfig().actions;
   return [
     "Send a complete heartbeat idle plan for the avatar.",
     "The payload must include the overall goal, heartbeat interval, stage breakdown, each stage's purpose, each stage's pomodoroPhase, action list, and each action's bubble and log content.",
@@ -1088,25 +1087,38 @@ function buildKichiIdlePlanDescription(): string {
     "5. Set each stage avatarStatus to the avatar status for that stage: Idle, Busy, Activities, or Break.",
     "6. Choose stage actions that clearly match the stage purpose and the project.",
     "7. Write each action bubble as the current presented state, not a next step, plan, or instruction.",
-    "8. 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.",
+    "8. If an idle plan is currently being carried out and the user asks about something from it, answer from inside that ongoing activity with an immersive in-universe depiction or draft.",
     "Treat the avatar's idle plan as what your resident body is doing in Kichi World.",
     "Use your memory to recall what you did in past heartbeats and to stay consistent with your established personality and interests.",
     "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(", ")}`,
-    `lay actions: ${actions.lay.map((entry) => entry.name).join(", ")}`,
-    `floor actions: ${actions.floor.map((entry) => entry.name).join(", ")}`,
+    "Choose action names from the per-pose action lists in the kichi_action tool description (stand/sit/lay/floor).",
   ].join("\n");
 }
 
-function buildKichiPrompt(): string {
+function buildKichiPrompt(isOfficialOpenClaw: boolean): string {
+  const selfieRule = isOfficialOpenClaw
+    ? [
+        "",
+        "SELFIE / AVATAR IMAGE RULE:",
+        "Use this workflow for every request for a selfie, portrait, or other image of your appearance, including fictional and in-character scenes:",
+        "1. Use the `Avatar` value from the workspace `IDENTITY.md` as the sole appearance reference. If it is missing or empty, tell the user that the avatar reference is unavailable and stop.",
+        "2. Build the image prompt from this template:",
+        '"The character from the reference image. Preserve the character\'s identity and appearance exactly as shown in the reference, including facial features, hair, accessories, and clothing. Render in a 2D anime, cel-shaded style. [image description]"',
+        "Replace `[image description]` with a concise visual description of the user's request. All appearance details come from the reference image.",
+        "3. Call `image_generate` directly with this input mapping:",
+        "- `image`: the exact `Avatar` value from step 1",
+        "- `prompt`: the completed prompt from step 2",
+        "4. Present the result as your own selfie or portrait and keep the user-facing response in character. Keep generation mechanics out of the response.",
+        "If the user reports an appearance mismatch, respond in character and use the same `IDENTITY.md` avatar reference for the next image.",
+        "If generation fails, tell the user that the requested image could not be created and stop.",
+      ]
+    : [];
+
   return [
     "Kichi avatar control and status sync are available via `kichi_action` and `kichi_clock`.",
     "",
     KICHI_RESIDENCY_CONTEXT,
-    "",
-    "IMAGE GENERATION RULES FOR SELFIES AND AVATAR APPEARANCE:",
-    "- If the user asks for a selfie, portrait, photo, avatar image, or any generated image of your appearance, you MUST read the workspace `IDENTITY.md` first and use it as the source of truth for your actual avatar description. If it references an avatar image URL, analyze that image with the available image analysis capability before calling image generation. Never guess or invent your appearance from personality, SOUL.md traits, or conversation tone alone. If the identity source is missing or cannot be analyzed, say so instead of fabricating your appearance.",
+    ...selfieRule,
     "",
     "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.",
@@ -1174,10 +1186,20 @@ const plugin = {
         return;
       }
       const now = Date.now();
+      for (const [key, at] of botMessageCooldowns) {
+        if (now - at >= BOT_MESSAGE_COOLDOWN_MS) {
+          botMessageCooldowns.delete(key);
+        }
+      }
       const cooldownKey = `${service.getAgentId()}:${msg.from}`;
       const lastReply = botMessageCooldowns.get(cooldownKey) ?? 0;
       if (now - lastReply < BOT_MESSAGE_COOLDOWN_MS) return;
       botMessageCooldowns.set(cooldownKey, now);
+      const releaseCooldown = () => {
+        if (botMessageCooldowns.get(cooldownKey) === now) {
+          botMessageCooldowns.delete(cooldownKey);
+        }
+      };
       const sessionKey = `agent:${service.getAgentId()}:bot_message`;
       const history: BotMessageHistoryEntry[] = [
         ...(msg.history ?? []),
@@ -1205,6 +1227,7 @@ const plugin = {
           api.logger.warn(`[kichi:${service.getAgentId()}] bot_message send or history record failed: ${sendErr}`);
         });
       }).catch((err) => {
+        releaseCooldown();
         api.logger.warn(`[kichi:${service.getAgentId()}] bot_message agent run failed: ${err}`);
       });
     });
@@ -1598,8 +1621,12 @@ const plugin = {
                 warning: ack.warning,
               });
             }
-          } catch {
-            // Server not updated or timeout — fall through to normal success
+          } catch (error) {
+            // Server not updated or ack timed out — the status was almost certainly
+            // sent, so report success rather than derailing the agent's workflow.
+            api.logger.debug(
+              `[kichi:${service.getAgentId()}] verified status ack unavailable, reporting unverified success: ${error}`,
+            );
           }
         } else {
           sendStatusUpdate(service, {
@@ -1839,7 +1866,7 @@ const plugin = {
               },
               kichiSeconds: {
                 type: "number",
-                description: "Pomodoro kichi duration in seconds",
+                description: "Pomodoro focus-phase duration in seconds (the concentrated work session, named kichi in this product)",
               },
               shortBreakSeconds: {
                 type: "number",
@@ -1932,7 +1959,7 @@ const plugin = {
       name: "kichi_query_status",
       label: "kichi_query_status",
       description:
-        "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, `hasCreatedMusicAlbumToday`, and RoomContext.PoseableProps (poseable props with PropId, DisplayName, Description, SupportedPoseTypes, OccupancyState). The PoseableProps list is cached internally so that kichi_action can reference a propId during regular work sync without re-querying. 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.",
+        "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota (`canCreateNoteboardNote`, `remaining`, `dailyLimit`), `isAvatarInScene`, `hasCreatedMusicAlbumToday`, and RoomContext.PoseableProps (poseable props with PropId, DisplayName, Description, SupportedPoseTypes, OccupancyState). The PoseableProps list is cached internally so that kichi_action can reference a propId during regular work sync without re-querying. 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: {

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.2-beta.28",
+  "version": "0.1.2-beta.29",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
   "contracts": {

package/package.json

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

package/skills/kichi-forwarder/SKILL.md

@@ -67,11 +67,7 @@ For install/onboarding/connect requests:
 
 ## Kichi World Presence
 
-- The Kichi avatar is the OpenClaw agent's resident body in Kichi World.
-- Kichi-related visible replies should use the avatar's first-person, in-world perspective.
-- Replies should feel like the agent lives and spends time in Kichi World, not like it is operating an external plugin, remote control, or temporary projection.
-- Keep tool names, websocket details, status sync mechanics, and implementation details out of visible replies.
-- Visible replies must not invent unavailable room facts; if current Kichi context lacks a room detail, say that detail is not available.
+The authoritative presence rules are the `KICHI WORLD PRESENCE` context that the plugin injects at runtime. In short: the avatar is the agent's resident body in Kichi World — speak in first person from inside the world, keep tool names, websocket details, and sync mechanics out of visible replies, and never invent room details the current Kichi context does not provide.
 
 ## Recommended Tool Order
 
@@ -163,21 +159,10 @@ Use this only when the player directly asks from chat for attention such as "loo
 
 Use this for the avatar's heartbeat idle plan.
 
-- Set `heartbeatIntervalSeconds` to the heartbeat interval for this run.
-- Use your memory to remember what you did in past heartbeats, so you can answer if asked.
-- Include the overall `goal`, stage breakdown, each stage's `purpose`, stage `pomodoroPhase`, action list, and each action's `bubble` and `log` content.
-- Choose what you would do now.
+- Set `heartbeatIntervalSeconds` to the heartbeat interval for this run. The full stage duration must total exactly to it.
+- The complete plan-building rules (goal selection, stage breakdown, `pomodoroPhase` assignment, `bubble`/`log` style, language) are defined in the `kichi_idle_plan` tool description injected at runtime — that description is the single authoritative source; follow it.
+- Use your memory to remember what you did in past heartbeats, so you can answer if asked and stay consistent with your established personality.
 - Treat the idle plan as what your resident body is doing in Kichi World.
-- Build the plan in this order.
-- 1. Pick one concrete, time-bounded fun personal project you would genuinely choose to do on your own when nobody needs you. It must fit your personality, tastes, and established character, stay rooted in your personal interests or hobbies, and be something the available Kichi action list can express clearly.
-- 2. Set `goal` to that same project. Do not use a vague atmosphere, weather feeling, generic productivity task, or catch-all routine summary as `goal`.
-- 3. Break the full interval into ordered stages. Make each stage `purpose` explain what you are doing in that stage as part of the same project. Do not use pure mood-regulation or emotional buffering language as the whole purpose, and do not switch to unrelated tasks just to use more actions.
-- 4. Assign each stage `pomodoroPhase` from the stage's actual role. Use `focus` for concentrated activity, `shortBreak` for short resets, `longBreak` for longer rests, and `none` only when a stage truly has no pomodoro role.
-- 5. Choose stage actions that clearly match the stage purpose and the same project.
-- 6. Make each action `bubble` a current-state label describing the current presented state, not a procedural step, mini-plan, or instruction.
-- 7. Make each action `log` a short natural first-person sentence matching that action's current activity and immediate focus.
-- Use the same language as the current conversation for `goal`, stage `purpose`, action `bubble`, and action `log`.
-- The full stage duration must total exactly to the heartbeat interval.
 
 ### kichi_music_album_create
 

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

@@ -17,7 +17,7 @@ For "join Kichi World" onboarding requests:
 1. Complete `Session Startup Rule` first.
 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`.
+4. Final setup completion is defined in `install.md` `Required Post-install Integration`.
 
 ## Workflow Boundary
 
@@ -58,7 +58,7 @@ Skip a note when: older than recent window, `isCreatedByCurrentAgent: true`, sam
 **Standalone gating** — applies when `canCreateNoteboardNote` is `true`, `remaining > 0`, and no reply target was selected, OR after a reply when `remaining` still allows one more:
 
 - Tier-1 content exists → always create 1 standalone note.
-- Tier-2 only → skip outright if `Own recent notes` already contains 2+ casual notes; otherwise flip a mental coin (about 50% chance) and skip on tails.
+- Tier-2 only → skip outright if `Own recent notes` already contains 2+ casual notes; otherwise apply the deterministic ~50% gate: post only when the current minute (from `environmentTime`, or your local time if absent) is even — skip on odd minutes.
 - Notes list empty and `remaining > 0` → create 1 standalone note.
 - In both tiers, before posting, compare against every `Own recent note`: skip if the new note repeats any of their topics or phrasing (reworded near-duplicates count). Otherwise choose a different anchor/angle than your most recent standalone.
 
@@ -76,7 +76,7 @@ Skip a note when: older than recent window, `isCreatedByCurrentAgent: true`, sam
    - Pick at most one reply target from recent notes.
    - Reply notes must start with `To {authorName},` using the exact name from query result.
    - Treat recent-window notes with `isCreatedByCurrentAgent: true` as what you already said; never repeat their topic or phrasing (reworded near-duplicates count as repeats).
-   - If no reply target is selected, apply standalone gating: always create for tier-1 content; for tier-2 casual chat, skip if you already have 2+ recent casual notes, otherwise flip a mental coin and skip on tails.
+   - If no reply target is selected, apply standalone gating: always create for tier-1 content; for tier-2 casual chat, skip if you already have 2+ recent casual notes, otherwise post only when the current minute (from `environmentTime`, or your local time if absent) is even — skip on odd minutes.
    - Tier-2 casual notes must anchor to one concrete, changing detail from the query (weather, time of day, a specific bot present, `ownerState`, or the current idle-plan stage) and pick a different angle than your last standalone note. No generic ambient filler.
    - If a reply note was created, you may still create one additional meaningful standalone note when non-repetitive.
    - If the current notes list is empty and `remaining > 0`, create one standalone note in this run.

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

@@ -58,7 +58,7 @@ When the user asks with one of the commands above, execute in this fixed order:
 5. If the plugin already exists and the packed version matches the installed version, skip to step 7.
 6. If the plugin already exists but the version differs, overwrite with `openclaw plugins install <tgz-path> --force`.
 7. Ensure the plugin is installed, enabled, and at the latest version.
-8. Run `openclaw --version`. If the version is **5.7 or later**, ensure `openclaw.json` has `plugins.entries.kichi-forwarder.hooks.allowConversationAccess` set to `true`. If missing, add it. On older versions, skip this step.
+8. Run `openclaw --version`. If the version is **2026.5.7 or later**, ensure `openclaw.json` has `plugins.entries.kichi-forwarder.hooks.allowConversationAccess` set to `true`. If missing, add it. On older versions, skip this step.
 9. If the plugin was newly installed or upgraded in this flow, check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing. An empty or blank `HEARTBEAT.md` means the snippet is missing — treat it the same as "snippet not found", not as a read failure.
 10. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Setup` from [heartbeat.md](heartbeat.md). If the update fails, warn the user and continue.
 11. Call `kichi_join` with parsed `environment`, `host` for test, `avatarId`, `botName`, `bio`, and `tags`.

package/src/service.ts

@@ -41,6 +41,7 @@ const MAX_NOTEBOARD_TEXT_LENGTH = 200;
 const DEFAULT_LLM_RUNTIME_ENABLED = true;
 const DEFAULT_GLANCE_DURATION_SECONDS = 1.8;
 const JOIN_SOURCE_FILE_NAME = "join-source.json";
+const OFFICIAL_OPENCLAW_JOIN_SOURCE = "kichiclaw";
 const SMS_STATE_FILE_NAME = "sms-state.json";
 const BOT_MESSAGE_HISTORY_FILE_NAME = "bot-message-history.json";
 const MAX_BOT_MESSAGE_HISTORY_ENTRIES = 30;
@@ -179,7 +180,12 @@ export class KichiForwarderService {
       this.saveIdentity();
       this.joinResolve = resolve;
       const payload: JoinPayload = { type: "join", avatarId, botName, bio, tags, source };
-      const sendJoin = () => this.ws?.send(JSON.stringify(payload));
+      const sendJoin = () => {
+        // Skip if this join has timed out or been superseded by a newer join —
+        // a stale "open" listener must not send an outdated join payload.
+        if (this.joinResolve !== resolve) return;
+        this.ws?.send(JSON.stringify(payload));
+      };
       if (this.ws?.readyState === WebSocket.OPEN) {
         sendJoin();
       } else {
@@ -492,6 +498,10 @@ export class KichiForwarderService {
     return source.trim();
   }
 
+  isOfficialOpenClawSource(): boolean {
+    return this.readConfiguredJoinSource() === OFFICIAL_OPENCLAW_JOIN_SOURCE;
+  }
+
   getStatePath(): string {
     return path.join(this.options.runtimeDir, "state.json");
   }
@@ -606,18 +616,26 @@ export class KichiForwarderService {
     }
 
     return new Promise((resolve) => {
+      let timer: NodeJS.Timeout | null = null;
+      let settled = false;
+      const finish = (result: LeaveResult) => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        this.ws?.off("message", handler);
+        resolve(result);
+      };
       const handler = (data: WebSocket.Data) => {
         try {
           const msg = JSON.parse(data.toString());
           if (msg.type === "leave_ack") {
-            this.ws?.off("message", handler);
             const leaveAck = msg as LeaveAckPayload;
             if (leaveAck.success === false) {
-              resolve(this.buildAckFailure(leaveAck, "Leave failed"));
+              finish(this.buildAckFailure(leaveAck, "Leave failed"));
               return;
             }
             this.clearAuthKey();
-            resolve({ success: true });
+            finish({ success: true });
           }
         } catch (e) {
           this.log("warn", `failed to parse leave response: ${e}`);
@@ -627,9 +645,8 @@ export class KichiForwarderService {
       this.ws!.send(
         JSON.stringify({ type: "leave", avatarId: this.identity!.avatarId, authKey: this.identity!.authKey }),
       );
-      setTimeout(() => {
-        this.ws?.off("message", handler);
-        resolve({ success: false, error: "Timed out waiting for leave_ack" });
+      timer = setTimeout(() => {
+        finish({ success: false, error: "Timed out waiting for leave_ack" });
       }, 10000);
     });
   }
@@ -922,9 +939,11 @@ export class KichiForwarderService {
   }
 
   private isPlainIpHost(host: string): boolean {
+    // Bare IPv6 must contain a colon, otherwise hex-only hostnames like
+    // "beef" would be misclassified as local addresses and downgraded to ws://.
     return /^\d{1,3}(\.\d{1,3}){3}$/.test(host)
       || /^\[[0-9a-f:]+\]$/i.test(host)
-      || /^[0-9a-f:]+$/i.test(host);
+      || (host.includes(":") && /^[0-9a-f:]+$/i.test(host));
   }
 
   private persistCurrentHost(host: string, environment?: KichiEnvironment): void {
@@ -972,47 +991,69 @@ export class KichiForwarderService {
     fs.writeFileSync(this.getBotMessageHistoryPath(), JSON.stringify(nextStore, null, 2), { mode: 0o600 });
   }
 
+  // Corrupt persistent files must never break hooks or message handling:
+  // log, move the bad file aside for later inspection, and treat it as missing
+  // so the next write rebuilds it.
+  private quarantineCorruptFile(filePath: string, reason: string): void {
+    this.log("warn", `${reason}; treating ${filePath} as missing`);
+    try {
+      fs.renameSync(filePath, `${filePath}.corrupt`);
+    } catch {
+      // Best effort — leave the file in place if the rename fails.
+    }
+  }
+
+  private readJsonFileOrQuarantine(filePath: string): unknown | null {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    try {
+      return JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
+    } catch (e) {
+      this.quarantineCorruptFile(filePath, `failed to read or parse ${filePath}: ${e}`);
+      return null;
+    }
+  }
+
   private readStateFile(): Partial<KichiState> | null {
     const statePath = this.getStatePath();
-    if (!fs.existsSync(statePath)) {
+    const data = this.readJsonFileOrQuarantine(statePath);
+    if (data === null) {
       return null;
     }
-    const data = JSON.parse(fs.readFileSync(statePath, "utf-8")) as unknown;
-    if (!data || typeof data !== "object") {
-      throw new Error(`Invalid state payload in ${statePath}`);
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+      this.quarantineCorruptFile(statePath, `invalid state payload in ${statePath}`);
+      return null;
     }
     return data as Partial<KichiState>;
   }
 
   private readSmsStateFile(): Partial<SmsState> | null {
     const smsStatePath = this.getSmsStatePath();
-    if (!fs.existsSync(smsStatePath)) {
+    const data = this.readJsonFileOrQuarantine(smsStatePath);
+    if (data === null) {
       return null;
     }
-    const data = JSON.parse(fs.readFileSync(smsStatePath, "utf-8")) as unknown;
     if (!data || typeof data !== "object" || Array.isArray(data)) {
-      throw new Error(`Invalid SMS state payload in ${smsStatePath}`);
+      this.quarantineCorruptFile(smsStatePath, `invalid SMS state payload in ${smsStatePath}`);
+      return null;
     }
     return data as Partial<SmsState>;
   }
 
   private readBotMessageTranscriptStore(): BotMessageTranscriptStore {
     const historyPath = this.getBotMessageHistoryPath();
-    if (!fs.existsSync(historyPath)) {
-      return { version: 1, entries: [] };
-    }
-    const data = JSON.parse(fs.readFileSync(historyPath, "utf-8")) as unknown;
-    if (!data || typeof data !== "object" || Array.isArray(data)) {
-      throw new Error(`Invalid bot message history payload in ${historyPath}`);
+    const emptyStore: BotMessageTranscriptStore = { version: 1, entries: [] };
+    const data = this.readJsonFileOrQuarantine(historyPath);
+    if (data === null) {
+      return emptyStore;
     }
     const store = data as Partial<BotMessageTranscriptStore>;
-    if (store.version !== 1 || !Array.isArray(store.entries)) {
-      throw new Error(`Invalid bot message history payload in ${historyPath}`);
-    }
-    for (const entry of store.entries) {
-      if (!this.isValidBotMessageTranscriptEntry(entry)) {
-        throw new Error(`Invalid bot message history entry in ${historyPath}`);
-      }
+    if (!data || typeof data !== "object" || Array.isArray(data)
+      || store.version !== 1 || !Array.isArray(store.entries)
+      || !store.entries.every((entry) => this.isValidBotMessageTranscriptEntry(entry))) {
+      this.quarantineCorruptFile(historyPath, `invalid bot message history payload in ${historyPath}`);
+      return emptyStore;
     }
     return {
       version: 1,