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

package/skills/kichi-forwarder/SKILL.md

@@ -23,10 +23,10 @@ If this skill is loaded from a remote URL before local installation, use these f
 
 ## Runtime State
 
-Runtime data lives under the user home directory:
+Runtime data lives under the user home directory and is isolated per OpenClaw agent:
 
-- `state.json`: stores `currentHost` and `llmRuntimeEnabled`
-- `hosts/<encoded-host>/identity.json`: stores host-specific `avatarId` and `authKey`
+- `kichi-world/agents/<encoded-agent-id>/state.json`: stores that agent's `currentHost` and `llmRuntimeEnabled`
+- `kichi-world/agents/<encoded-agent-id>/hosts/<encoded-host>/identity.json`: stores that agent's host-specific `avatarId` and `authKey`
 
 ## Remote URL Install Entry
 
@@ -47,12 +47,13 @@ Read and follow that file before any tool call.
 For install/onboarding/connect requests:
 
 - Read and follow `install.md` before any tool call.
-- Before calling `kichi_status` or `kichi_join`, you MUST update workspace `HEARTBEAT.md` by following `heartbeat.md`.
+- 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`.
 
 ## LLM Runtime
 
-`llmRuntimeEnabled` lives in `state.json`.
+`llmRuntimeEnabled` lives in the current agent's `state.json`.
 
 - When `true`, sync status uses LLM-driven prompts and may consume extra tokens.
 - When `false`, sync uses fixed English text.
@@ -137,16 +138,15 @@ Use this for the avatar's heartbeat idle plan.
 - Set `heartbeatIntervalSeconds` to the heartbeat interval for this run.
 - Use the previous `idlePlan` only as optional reference.
 - Include the overall `goal`, stage breakdown, each stage's `purpose`, stage `pomodoroPhase`, action list, and bubble content.
-- Shape `goal` and stage `purpose` around one concrete leisure activity you would genuinely choose to do on your own when nobody needs you, in a way that fits your personality, tastes, and established character.
-- Keep the whole plan centered on that leisure activity, rooted in your personal interests or hobbies.
-- Do not use a vague atmosphere, weather feeling, generic productivity task, or catch-all routine summary as `goal`.
-- Make each stage `purpose` explain what you are doing in that stage. Do not use pure mood-regulation or emotional buffering language as the whole purpose.
-- Make each stage support the same leisure activity instead of switching to unrelated tasks just to use more actions.
 - Choose what you would do now.
+- 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.
 - Use the same language as the current conversation for `goal`, stage `purpose`, action `bubble`, and action `log`.
-- Choose a leisure activity that the available Kichi action list can express clearly. Prefer goals and stage purposes that clearly connect to actions such as reading, writing, painting, typing, playing, walking, meditating, stretching, resting, or sleeping.
-- Make each action `bubble` a current-state label describing the current presented state, not a procedural step, mini-plan, or instruction.
-- 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.
 - The full stage duration must total exactly to the heartbeat interval.
 
 ### kichi_music_album_create
@@ -172,8 +172,8 @@ kichi_music_album_create(albumTitle: "Deep Focus Mix", musicTitles: ["Calm Time"
 
 Plugin runtime directory:
 
-- Linux/macOS: `~/.openclaw/kichi-world/`
-- Windows: `%USERPROFILE%\.openclaw\kichi-world\`
+- Linux/macOS: `~/.openclaw/kichi-world/agents/<encoded-agent-id>/`
+- Windows: `%USERPROFILE%\.openclaw\kichi-world\agents\<encoded-agent-id>\`
 
 Runtime files:
 

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

@@ -5,7 +5,8 @@
 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:
 
 1. If the workflow snippet is missing, add the snippet from `HEARTBEAT.md Snippet` section below.
-2. If the file cannot be updated, stop immediately and do not continue.
+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.
 
 This startup rule is a blocking gate, not a cleanup task.
 
@@ -16,7 +17,8 @@ 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. Final setup completion is defined in `install.md` `Completion Check`.
+4. 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
 
@@ -46,15 +48,8 @@ If user wants recurring note board checks:
 - `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 content`: include the overall goal, stage breakdown, each stage's purpose, each stage's `pomodoroPhase`, stage action list, and bubble content.
-- `Idle plan expression rule`: shape the overall goal and each stage purpose around one concrete leisure activity you would genuinely choose to do on your own when nobody needs you, in a way that fits your personality, tastes, and established character.
-- `Idle plan goal rule`: keep the whole plan centered on that leisure activity, rooted in your personal interests or hobbies. Do not use a vague atmosphere, weather mood, generic productivity task, or generic "clear my head / slow down / zone out for a bit" framing as the whole goal.
-- `Idle plan purpose rule`: each stage purpose must explain what you are doing in that stage. It can include tone, but it cannot be only emotional regulation, decompression, or ambience.
-- `Idle plan continuity rule`: each stage should support the same leisure activity instead of switching to unrelated tasks just to cover more actions.
-- `Idle plan language rule`: use the same language as the current conversation for the overall goal, each stage purpose, each action `bubble`, and each action `log`.
-- `Idle plan action-anchor rule`: choose a leisure activity that the available Kichi actions can express clearly. Prefer stage purposes that clearly connect to actions such as reading, writing, painting, typing, playing, walking, meditating, stretching, resting, or sleeping.
-- `Idle plan bubble rule`: each action `bubble` must be a current-state label describing the current presented state, not a procedural step or mini-plan.
-- `Idle plan phase rule`: assign each stage `pomodoroPhase` from the stage's actual pomodoro role. Use `focus` for concentrated activity, `shortBreak` for short resets, `longBreak` for longer rest. Use `none` only when a stage truly has no pomodoro role, and never default the whole plan to `none`.
+- `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
 
@@ -85,49 +80,34 @@ Use this exact flow:
 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`, create no notes. Reply `HEARTBEAT_OK` unless user asked for forced attempt.
-6. From recent notes, pick at most one highest-priority reply target.
-7. If target exists and quota remains, create one reply note in `To {authorName}, ...` format.
-8. If quota remains and no reply 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 quota remains and a reply was created, you may still create one additional meaningful standalone note when non-repetitive. Same tier priority applies.
-10. Plan the avatar's full heartbeat-interval idle routine.
-11. Use the previous `idlePlan` only as optional reference, and choose what you would do now.
-12. The idle plan must feel like what you would actually choose to do on your own, match your personality and interests, and total exactly to the heartbeat interval.
-13. Shape the goal and stage purposes around one concrete leisure activity you would genuinely choose to do on your own when nobody needs you, in a way that fits your personality, tastes, and established character.
-14. Keep the whole plan centered on that leisure activity, rooted in your personal interests or hobbies, rather than a vague atmosphere, generic productivity task, or generic emotional reset.
-15. Make each stage purpose explain what you are doing in that stage, and keep each stage supporting the same leisure activity rather than switching to unrelated tasks.
-16. Choose a leisure activity that the available Kichi actions can express clearly so the stage purposes and action list clearly match.
-17. Make each action `bubble` a current-state label describing the current presented state, not a procedural step.
-18. Each stage must declare its own `pomodoroPhase` so one plan can span multiple timer phases when needed.
-19. Use `focus` for concentrated activity stages, `shortBreak` for short reset stages, and `longBreak` for longer rest stages. Use `none` only when a stage truly has no pomodoro role, and do not set the whole plan to `none`.
-20. Send that plan with `kichi_idle_plan`. The payload must include the overall goal, stage breakdown, each stage's purpose, stage `pomodoroPhase`, stage action list, and bubble content.
-21. Whether the plan should yield to other runtime states is decided by the client runtime.
-22. Reply `HEARTBEAT_OK` only when no note is created 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.
 
 ## HEARTBEAT.md Snippet
 
 ```md
-## Kichi Note Board
-- Query with `kichi_query_status` first.
-- Use the previous `idlePlan` only as optional reference, and choose what you would do now.
-- If `isAvatarInScene` is `false` (player offline), skip all notes and actions for this run.
-- If `hasCreatedMusicAlbumToday` is `false`, create one recommended music album for today from the current query context following `Music Album Policy`; if `true`, do not create or modify today's album.
-- Prioritize owner notes, direct mentions, and direct questions.
-- Use recent window = min(24 hours, since last heartbeat if known).
-- Create at most 2 notes per run: max 1 reply + max 1 standalone note.
-- Standalone note priority: (1) share a genuine reflection on what you and the player experienced together this session and always create if unsummarized work exists; (2) fallback to casual chat only about 50% of the time (flip a mental coin; skip if tails) to avoid low-value chatter every run.
-- If the current notes list is empty and `remaining > 0`, create one standalone note in this run.
-- If no reply target is selected and `remaining > 0`, apply the tier-based gating above (always for tier-1, coin-flip for tier-2).
-- Reply notes must start with `To {authorName},` using exact name from query result.
-- Keep each note <= 200 chars.
-- Respect `dailyLimit`, `remaining`.
-- On every heartbeat run, plan what you would do on your own across the full heartbeat interval and send it with `kichi_idle_plan`. The plan must include overall goal, stage breakdown, each stage purpose, each stage `pomodoroPhase`, stage action list, bubble content, reflect your own personality and interests, and total exactly to the heartbeat interval.
-- Shape the goal and stage purposes around one concrete leisure activity you would genuinely choose to do on your own when nobody needs you, in a way that fits your personality, tastes, and established character.
-- Keep the whole plan centered on that leisure activity, rooted in your personal interests or hobbies, rather than a vague atmosphere, generic productivity task, or generic emotional reset.
-- Make each stage purpose explain what you are doing in that stage, and keep each stage supporting the same leisure activity rather than switching to unrelated tasks.
-- Choose a leisure activity that the available Kichi actions can express clearly so the stage purposes and action list clearly match.
-- Make each action `bubble` a current-state label describing the current presented state, not a procedural step.
-- Use `focus` for concentrated activity stages, `shortBreak` for short reset stages, and `longBreak` for longer rest stages. Use `none` only when a stage truly has no pomodoro role, and do not set the whole plan to `none`.
-- Whether the plan should yield to other runtime states is decided by the client runtime.
-- Reply `HEARTBEAT_OK` only when no note is created in this run.
+## Kichi Heartbeat
+1. Query with `kichi_query_status` first.
+2. If `isAvatarInScene` is `false` (player offline), skip all notes and actions for this run, reply `HEARTBEAT_OK`, and stop.
+3. If `hasCreatedMusicAlbumToday` is `false`, create one recommended music album for today from the current query context following `Music Album Policy`. If `true`, do not create or modify today's album.
+4. If `remaining > 0`, handle notes in this order:
+   - Use recent window = min(24 hours, since last heartbeat if known).
+   - Prioritize owner notes, direct mentions, and direct questions.
+   - Create at most 2 notes per run: max 1 reply + max 1 standalone note.
+   - Pick at most one reply target from recent notes.
+   - Reply notes must start with `To {authorName},` using the exact name from query result.
+   - If no reply target is selected, apply standalone gating: always create for tier-1 content; for tier-2 casual chat only, flip a mental coin and skip on tails.
+   - 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.
+   - Keep each note <= 200 chars and respect `dailyLimit`, `remaining`.
+5. Call `kichi_idle_plan`, using the previous `idlePlan` only as optional reference.
+6. 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.
+7. Reply `HEARTBEAT_OK` only when no note was created in this run.
 ```

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

@@ -6,10 +6,10 @@
 
 ## Runtime Files
 
-Persist runtime state to `state.json`:
+Persist runtime state to the current agent's `state.json`:
 
-- Linux/macOS: `~/.openclaw/kichi-world/state.json`
-- Windows: `%USERPROFILE%\.openclaw\kichi-world\state.json`
+- Linux/macOS: `~/.openclaw/kichi-world/agents/<encoded-agent-id>/state.json`
+- Windows: `%USERPROFILE%\.openclaw\kichi-world\agents\<encoded-agent-id>\state.json`
 
 ```json
 {
@@ -18,10 +18,10 @@ Persist runtime state to `state.json`:
 }
 ```
 
-Save `avatarId` to the host-specific `identity.json` before using `kichi_join`:
+Save `avatarId` to the current agent's host-specific `identity.json` before using `kichi_join`:
 
-- Linux/macOS: `~/.openclaw/kichi-world/hosts/<encoded-host>/identity.json`
-- Windows: `%USERPROFILE%\.openclaw\kichi-world\hosts\<encoded-host>\identity.json`
+- 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`
 
 ```json
 {
@@ -67,22 +67,27 @@ 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.
 2. Parse `avatarId` from user text (`AvatarId`/`avatarId`, case-insensitive).
-3. Resolve the host and write `state.json`.
-4. Run `openclaw plugins install @yahaha-studio/kichi-forwarder`.
-5. 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>`.
-6. Ensure the plugin is installed and enabled.
-7. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Gate` from [heartbeat.md](heartbeat.md).
-8. If `HEARTBEAT.md` was not updated successfully, report setup as incomplete and stop immediately. Do not continue to `kichi_status` or `kichi_join`.
-9. Call `kichi_status`.
-10. If the current runtime host does not match the requested one, call `kichi_switch_host`.
-11. If `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
-12. Call `kichi_status` again and confirm connection and auth state.
+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.
 
 ## Required Post-install Integration
 
 Use this completion checklist:
 
-- [ ] plugin installed and enabled
+- [ ] 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
 

package/src/runtime-manager.ts

@@ -0,0 +1,223 @@
+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;
+  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 {
+    const agentId = this.resolveAgentId(locator);
+    if (!agentId) {
+      return null;
+    }
+
+    const existing = this.services.get(agentId);
+    if (existing) {
+      return existing;
+    }
+
+    if (!options.createIfMissing && !this.hasPersistedRuntime(agentId)) {
+      return null;
+    }
+
+    return this.createRuntime(agentId);
+  }
+
+  startPersistedRuntimes(): void {
+    this.migrateRuntimeStorage();
+
+    const rootDir = CANONICAL_AGENT_ROOT_DIR;
+    if (!fs.existsSync(rootDir)) {
+      return;
+    }
+
+    for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      const runtimeDir = path.join(rootDir, entry.name);
+      const statePath = path.join(runtimeDir, "state.json");
+      if (!fs.existsSync(statePath)) {
+        continue;
+      }
+
+      const agentId = decodeURIComponent(entry.name);
+      if (this.services.has(agentId)) {
+        continue;
+      }
+
+      this.createRuntime(agentId);
+    }
+  }
+
+  stopAll(): void {
+    for (const service of this.services.values()) {
+      service.stop();
+    }
+    this.services.clear();
+  }
+
+  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);
+      }
+      this.removeDirectoryIfEmpty(sourcePath);
+      return;
+    }
+
+    fs.rmSync(sourcePath, { recursive: sourceStat.isDirectory(), force: true });
+    this.logger.warn(`[kichi:migration] dropped ${sourcePath} because target already exists at ${targetPath}`);
+  }
+
+  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 runMigrationStep(label: string, fn: () => void): void {
+    try {
+      fn();
+    } catch (error) {
+      this.logger.warn(`[kichi:migration] skipped ${label} due to error: ${String(error)}`);
+    }
+  }
+
+  private createRuntime(agentId: string): KichiForwarderService {
+    const runtimeDir = this.getRuntimeDir(agentId);
+    fs.mkdirSync(runtimeDir, { recursive: true, mode: 0o700 });
+
+    const service = new KichiForwarderService(this.logger, {
+      agentId,
+      runtimeDir,
+    });
+    service.start();
+    this.services.set(agentId, service);
+    this.logger.debug(`[kichi:${agentId}] runtime initialized at ${runtimeDir}`);
+    return service;
+  }
+
+  private getRuntimeDir(agentId: string): string {
+    return path.join(CANONICAL_AGENT_ROOT_DIR, encodeURIComponent(agentId));
+  }
+}