feat: schedule cache, workflow-aligned prompts, dispatchInbound wakeup

1. ScheduleCache: local cache of today's schedule, synced every 5 min
   from HF backend via new getDaySchedule() API

2. Wakeup prompts updated to reference daily-routine skill workflows
   (task-handson, plan-schedule, slot-complete)

3. Agent wakeup via dispatchInboundMessageWithDispatcher (in-process)
   - Same mechanism as Discord plugin
   - Creates unique session per slot: agent:{agentId}:hf-calendar:slot-{slotId}
   - No WebSocket, CLI, or cron dependency
   - Verified working on test environment

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

README.md

@@ -1,107 +1,84 @@
 # HarborForge OpenClaw Plugin
 
-OpenClaw plugin that exposes OpenClaw-side metadata to the HarborForge Monitor, provides an optional local Monitor bridge, drives the HarborForge Calendar scheduler, and can optionally install the `hf` CLI.
+OpenClaw 插件：向 HarborForge Monitor 暴露 OpenClaw 侧元数据，并提供可选的本地桥接能力；安装时也可顺带安装 `hf` CLI。
 
-Part of the [HarborForge](../README.md) platform.
+## 当前状态
 
-- Role: OpenClaw integration layer for HarborForge (registered plugin id: `harbor-forge`).
+- 插件注册名：`harbor-forge`
-- Talks to the HarborForge backend (`backendUrl`, default `https://monitor.hangman-lab.top`) for Calendar APIs.
+- 旧 sidecar `server/` 架构已移除
-- Talks to a local HarborForge.Monitor bridge over `127.0.0.1:<monitor_port>` (no fixed default; commonly `9100`).
+- 监控桥接走本地 `monitor_port`
+- 安装脚本支持 `--install-cli`
+- `skills/hf/` 仅在 `--install-cli` 时一并安装
 
-## Current State
+## 项目结构
-
-- Plugin registration id: `harbor-forge` (was `harborforge-monitor`)
-- Plugin version: `0.2.0` (package manifests); telemetry reports `pluginVersion` `0.3.1`
-- Legacy sidecar `server/` architecture removed — telemetry is served directly by the plugin
-- Monitor bridge runs over the local `monitor_port`
-- Calendar scheduler integration (PLG-CAL-001 / 002 / 004)
-- Installer supports `--install-cli` and an optional managed Monitor (`--install-monitor`)
-- `skills/hf/` is installed only with `--install-cli`
-
-## Project Structure
 
 ```text
 HarborForge.OpenclawPlugin/
 ├── package.json
 ├── README.md
-├── docs/                         # design notes (calendar, monitor connector)
 ├── plugin/
-│   ├── openclaw.plugin.json      # plugin manifest + config schema
+│   ├── openclaw.plugin.json
-│   ├── index.ts                  # plugin entry, tool registration
+│   ├── index.ts
-│   ├── tsconfig.json
 │   ├── core/
-│   │   ├── config.ts             # config defaults / resolution
+│   │   ├── config.ts
-│   │   ├── managed-monitor.ts    # optionally spawn HarborForge.Monitor
+│   │   ├── managed-monitor.ts
-│   │   ├── monitor-bridge.ts     # client for the Monitor bridge
+│   │   └── monitor-bridge.ts
-│   │   └── openclaw-agents.ts    # enumerate OpenClaw agents
-│   ├── calendar/                 # Calendar scheduler + bridge
-│   │   ├── index.ts
-│   │   ├── scheduler.ts
-│   │   ├── calendar-bridge.ts
-│   │   └── types.ts
 │   ├── hooks/
 │   │   ├── gateway-start.ts
 │   │   └── gateway-stop.ts
 │   └── package.json
 ├── skills/
 │   └── hf/
-│       └── SKILL.md              # installed only with --install-cli
+│       └── SKILL.md
 └── scripts/
     └── install.mjs
 ```
 
-## Installation
+## 安装
 
-### Standard Install
+### 普通安装
 
 ```bash
 node scripts/install.mjs
 ```
 
-This will:
+这会：
-- Build and install the OpenClaw plugin
+- 构建并安装 OpenClaw 插件
-- Copy regular skills
+- 复制常规 skills
-- **Not** install the `hf` binary
+- **不会**安装 `hf` 二进制
-- **Not** copy `skills/hf/`
+- **不会**复制 `skills/hf/`
 
-### Plugin + `hf` CLI
+### 安装插件 + `hf` CLI
 
 ```bash
 node scripts/install.mjs --install-cli
 ```
 
-This additionally:
+这会额外：
-- Builds `HarborForge.Cli` (`go build ./cmd/hf`)
+- 构建 `HarborForge.Cli`
-- Installs `hf` to `<openclaw>/bin/hf` (default `~/.openclaw/bin/hf`) and `chmod +x`
+- 安装 `hf` 到 `~/.openclaw/bin/hf`
-- Copies `skills/hf/` into the OpenClaw skills directory
+- `chmod +x ~/.openclaw/bin/hf`
+- 复制 `skills/hf/` 到 OpenClaw profile skills 目录
 
-### Common Options
+### 常用选项
 
 ```bash
-# Build only (no install / config)
+# 仅构建
 node scripts/install.mjs --build-only
 
-# Install only, skip dependency checks
+# 指定 OpenClaw profile
-node scripts/install.mjs --skip-check
-
-# Specify OpenClaw profile path (also honors OPENCLAW_PATH env)
 node scripts/install.mjs --openclaw-profile-path /custom/path/.openclaw
 
-# Build and install a managed HarborForge.Monitor binary alongside the plugin
+# 详细日志
-node scripts/install.mjs --install-monitor yes --monitor-branch main
-
-# Verbose logs
 node scripts/install.mjs --verbose
 
-# Uninstall (plugin, config entries, hf binary, managed monitor)
+# 卸载
 node scripts/install.mjs --uninstall
 ```
 
-The installer also updates OpenClaw config (`plugins.load.paths`, `plugins.allow`, `plugins.entries.harbor-forge.enabled`) via `openclaw config`.
+## 配置
 
-## Configuration
+编辑 `~/.openclaw/openclaw.json`：
-
-Edit `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -117,9 +94,7 @@ Edit `~/.openclaw/openclaw.json`:
           "monitor_port": 9100,
           "reportIntervalSec": 30,
           "httpFallbackIntervalSec": 60,
-          "logLevel": "info",
+          "logLevel": "info"
-          "calendarEnabled": true,
-          "calendarHeartbeatIntervalSec": 60
         }
       }
     }
@@ -127,72 +102,51 @@ Edit `~/.openclaw/openclaw.json`:
 }
 ```
 
-Then restart:
+然后重启：
 
 ```bash
 openclaw gateway restart
 ```
 
-## Config Options
+## 配置项
 
-| Option | Type | Default | Description |
+| 选项 | 类型 | 默认值 | 说明 |
-|--------|------|---------|-------------|
+|------|------|--------|------|
-| `enabled` | boolean | `true` | Enable the plugin |
+| `enabled` | boolean | `true` | 是否启用插件 |
-| `backendUrl` | string | `https://monitor.hangman-lab.top` | HarborForge backend base URL (Monitor + Calendar APIs) |
+| `backendUrl` | string | `https://monitor.hangman-lab.top` | HarborForge Monitor 后端地址 |
-| `identifier` | string | hostname | Server / claw identifier |
+| `identifier` | string | 主机名 | 服务器标识符 |
-| `apiKey` | string | (none) | Server API key from the HarborForge Monitor admin panel |
+| `apiKey` | string | 无 | HarborForge Monitor 生成的服务器 API Key |
-| `monitor_port` | number | (none) | Local bridge port; plugin talks to HarborForge.Monitor via `127.0.0.1:<monitor_port>` |
+| `monitor_port` | number | 无 | 本地桥接端口；插件通过 `127.0.0.1:<monitor_port>` 与 HarborForge.Monitor 通信 |
-| `reportIntervalSec` | number | `30` | Metadata push interval (seconds) |
+| `reportIntervalSec` | number | `30` | 报告间隔（秒） |
-| `httpFallbackIntervalSec` | number | `60` | HTTP heartbeat interval when WS unavailable |
+| `httpFallbackIntervalSec` | number | `60` | HTTP 回退间隔（秒） |
-| `logLevel` | string | `info` | Log level: `debug` / `info` / `warn` / `error` |
+| `logLevel` | string | `info` | 日志级别：`debug` / `info` / `warn` / `error` |
-| `calendarEnabled` | boolean | `true` | Enable Calendar scheduler integration (PLG-CAL-001) |
-| `calendarHeartbeatIntervalSec` | number | `60` | Calendar heartbeat interval (seconds) |
-| `calendarApiKey` | string | (none) | API key for Calendar API auth; falls back to `apiKey` / `X-Agent-ID` |
-| `managedMonitor` | string | (none) | Absolute path to a HarborForge.Monitor binary; if set, gateway start/stop hooks spawn/stop it |
 
-## Local Monitor Bridge
+## 本地桥接说明
 
-When the plugin has `monitor_port` configured and HarborForge.Monitor uses the same `MONITOR_PORT`:
+当插件配置了 `monitor_port`，并且 HarborForge.Monitor 也使用相同的 `MONITOR_PORT` 时：
 
-- Monitor serves a local bridge on `127.0.0.1:<MONITOR_PORT>`
+- Monitor 在 `127.0.0.1:<MONITOR_PORT>` 提供本地桥接服务
-- The plugin probes `GET /health`
+- 插件可探测 `GET /health`
-- The plugin tool `harborforge_monitor_telemetry` reads `GET /telemetry`
+- 插件工具 `harborforge_monitor_telemetry` 可读取 `GET /telemetry`
-- The plugin pushes OpenClaw metadata (version, plugin version, agents) via `POST /openclaw` on the `reportIntervalSec` cadence, enriching Monitor heartbeats
+- 如果桥接端口未配置或不可达，插件仍可正常运行
-- If the bridge port is unconfigured or unreachable, the plugin still works normally
 
-This link is an **optional enhancement**, not a precondition for the plugin to start or for Monitor heartbeats.
+也就是说，这条链路是**可选增强**，不是插件启动或 Monitor 心跳的前置条件。
 
-## Managed Monitor
+## 插件提供的信息
 
-If `managedMonitor` points to an installed HarborForge.Monitor binary, the `gateway_start` hook spawns it (passing `--backend-url`, `--identifier`, `--api-key`, `--monitor-port`, `--report-interval`, `--log-level` from the plugin config) and `gateway_stop` terminates it. Use `install.mjs --install-monitor yes` to build and wire this automatically.
+### OpenClaw 元数据
+- OpenClaw version
+- plugin version
+- 标识符 / 主机名
+- 时间戳
 
-## Calendar Scheduler
+### 系统快照
+- uptime
+- memory total/free/used/usagePercent
+- load avg1/avg5/avg15
+- platform
 
-When `calendarEnabled` is true, on gateway start the plugin starts a Calendar scheduler that heartbeats the backend (`/calendar/agent/heartbeat`, `/calendar/agent/status`, `/calendar/agent/notify`) to receive and run scheduled TimeSlots, waking/spawning agents via the OpenClaw `spawn` API (with a notification fallback). Scheduler state is persisted to a state file; gateway restarts can be requested by the backend (PLG-CAL-004).
+## 开发
-
-## Tools Provided
-
-| Tool | Description |
-|------|-------------|
-| `harborforge_status` | Plugin status, resolved config, Monitor bridge health, calendar status, telemetry snapshot |
-| `harborforge_telemetry` | Current system telemetry snapshot from this host |
-| `harborforge_monitor_telemetry` | Query the Monitor bridge for host hardware telemetry |
-| `harborforge_calendar_status` | Calendar scheduler status and current slot |
-| `harborforge_calendar_complete` | Complete the current calendar slot with actual duration |
-| `harborforge_calendar_abort` | Abort the current calendar slot |
-| `harborforge_calendar_pause` | Pause the current calendar slot |
-| `harborforge_calendar_resume` | Resume the paused calendar slot |
-| `harborforge_restart_status` | Check whether a gateway restart is pending |
-
-### Telemetry Snapshot Fields
-
-- `identifier`, `hostname`, `platform`, `timestamp`
-- `uptime`
-- `memory`: `total` / `free` / `used` / `usagePercent`
-- `load`: `avg1` / `avg5` / `avg15`
-- `openclaw`: `version` / `pluginVersion`
-
-## Development
 
 ```bash
 cd plugin
@@ -200,16 +154,14 @@ npm install
 npm run build
 ```
 
-The build runs `tsc` and emits `dist/` (`dist/index.js` is the plugin entry).
+## 依赖
-
-## Dependencies
 
 - Node.js 18+
 - OpenClaw Gateway
-- Go 1.20+ (only for `--install-cli` / `--install-monitor`)
+- Go 1.20+（仅 `--install-cli` 需要）
 
-## Tips
+## 相关提示
 
-- After installing `hf`, add `~/.openclaw/bin` to your `PATH`
+- 安装 `hf` 后，建议把 `~/.openclaw/bin` 加到 `PATH`
-- When an agent uses `hf`, try `hf --help-brief` first
+- Agent 使用 `hf` 时，优先试 `hf --help-brief`
-- For the full command tree, see `hf --help`
+- 完整命令树看 `hf --help`

REFACTOR_PLAN.md

@@ -0,0 +1,118 @@
+# CalendarScheduler Refactor Plan (v2)
+
+> Updated 2026-04-19 based on architecture discussion with hang
+
+## Current Issues
+
+1. `process.env.AGENT_ID` doesn't exist in plugins subprocess — always 'unknown'
+2. Heartbeat is per-agent but should be per-claw-instance (global)
+3. Scheduler only handles one agent — should manage all agents on this instance
+4. wakeAgent used api.spawn (non-existent) → now uses dispatchInboundMessage (verified)
+
+## Target Design
+
+### Plugin State
+
+```typescript
+// Local schedule cache: { agentId → [slots] }
+const schedules: Map<string, CalendarSlotResponse[]> = new Map();
+```
+
+### Sync Flow (every 5 min)
+
+```
+1. GET /calendar/sync?claw_identifier=xxx
+   - First call: server returns full { agentId → [slots] }
+   - Subsequent: server returns diff since last sync
+2. Update local schedules map
+3. Scan schedules for due slots:
+   for each agentId in schedules:
+     if has slot where scheduled_at <= now && status == not_started:
+       getAgentStatus(agentId, clawIdentifier) → busy?
+       if not busy → wakeAgent(agentId)
+```
+
+### Heartbeat (every 60s)
+
+Simplified to liveness ping only:
+```
+POST /monitor/server/heartbeat
+  claw_identifier: xxx
+  → server returns empty/ack
+```
+
+No slot data in heartbeat response.
+
+### Wake Flow
+
+```
+dispatchInboundMessage:
+  SessionKey: agent:{agentId}:hf-wakeup
+  Body: "You have due slots. Follow the hf-wakeup workflow of skill hf-hangman-lab to proceed. Only reply WAKEUP_OK in this session."
+
+Agent reads workflow → calls hf tools → sets own status to busy
+```
+
+### Agent ID Resolution
+
+- **Sync**: agentId comes from server response (dict keys)
+- **Wake**: agentId from local schedules dict key
+- **Tool calls by agent**: agentId from tool ctx (same as padded-cell)
+
+## Backend API Changes Needed
+
+### New: GET /calendar/sync
+
+```
+GET /calendar/sync?claw_identifier=xxx
+Headers: X-Claw-Identifier
+
+Response (first call):
+{
+  "full": true,
+  "schedules": {
+    "developer": [slot1, slot2, ...],
+    "operator": [slot3, ...]
+  },
+  "syncToken": "abc123"
+}
+
+Response (subsequent, with ?since=abc123):
+{
+  "full": false,
+  "diff": [
+    { "op": "add", "agent": "developer", "slot": {...} },
+    { "op": "update", "agent": "developer", "slotId": 5, "patch": {...} },
+    { "op": "remove", "agent": "operator", "slotId": 3 }
+  ],
+  "syncToken": "def456"
+}
+```
+
+### Existing: POST /calendar/agent/status
+
+Keep as-is but ensure it accepts agentId + clawIdentifier as params:
+```
+POST /calendar/agent/status
+  { agent_id, claw_identifier, status }
+```
+
+## Implementation Order
+
+1. Backend: Add /calendar/sync endpoint
+2. Plugin: Replace CalendarBridgeClient single-agent design with multi-agent
+3. Plugin: Replace CalendarScheduler with new sync+check loop
+4. Plugin: wakeAgent uses dispatchInboundMessage (done)
+5. Plugin: Tool handlers get agentId from ctx (like padded-cell)
+
+## Files to Change
+
+### Backend (HarborForge.Backend)
+- New route: `/calendar/sync`
+- New service: schedule diff tracking per claw_identifier
+
+### Plugin
+- `plugin/calendar/calendar-bridge.ts` — remove agentId binding, add sync()
+- `plugin/calendar/scheduler.ts` — rewrite to multi-agent sync+check
+- `plugin/calendar/schedule-cache.ts` — already exists, adapt to multi-agent
+- `plugin/index.ts` — update wakeAgent, getAgentStatus to accept agentId

plugin/calendar/calendar-bridge.ts

@@ -169,6 +169,74 @@ export class CalendarBridgeClient {
     return this.sendBoolean('POST', url, body);
   }
 
+  /**
+   * Fetch the full day schedule for this agent.
+   *
+   * Unlike heartbeat() which only returns pending (NOT_STARTED/DEFERRED) slots,
+   * this returns ALL slots for the given date, enabling the plugin to maintain
+   * a complete local view of today's schedule.
+   *
+   * @param date  Date string in YYYY-MM-DD format
+   * @returns Array of all slots for the day, or null if unreachable
+   */
+  async getDaySchedule(date: string): Promise<CalendarSlotResponse[] | null> {
+    const url = `${this.baseUrl}/calendar/day?date=${encodeURIComponent(date)}`;
+    try {
+      const response = await this.fetchJson<{ slots: CalendarSlotResponse[] }>(url, {
+        method: 'GET',
+        headers: {
+          'X-Agent-ID': this.config.agentId,
+          'X-Claw-Identifier': this.config.clawIdentifier,
+        },
+      });
+      return response?.slots ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Sync today's schedules for all agents on this claw instance.
+   *
+   * Returns { agentId → slots[] } for all agents with matching claw_identifier.
+   * This is the primary data source for the multi-agent schedule cache.
+   */
+  async syncSchedules(): Promise<{ schedules: Record<string, any[]>; date: string } | null> {
+    const url = `${this.baseUrl}/calendar/sync`;
+    try {
+      const response = await this.fetchJson<{ schedules: Record<string, any[]>; date: string }>(url, {
+        method: 'GET',
+        headers: {
+          'X-Claw-Identifier': this.config.clawIdentifier,
+        },
+      });
+      return response;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get a specific agent's status.
+   *
+   * @param agentId  The agent ID to query
+   */
+  async getAgentStatus(agentId: string): Promise<string | null> {
+    const url = `${this.baseUrl}/calendar/agent/status?agent_id=${encodeURIComponent(agentId)}`;
+    try {
+      const response = await this.fetchJson<{ status: string }>(url, {
+        method: 'GET',
+        headers: {
+          'X-Agent-ID': agentId,
+          'X-Claw-Identifier': this.config.clawIdentifier,
+        },
+      });
+      return response?.status ?? null;
+    } catch {
+      return null;
+    }
+  }
+
   // -------------------------------------------------------------------------
   // Internal helpers
   // -------------------------------------------------------------------------

plugin/calendar/index.ts

@@ -31,3 +31,4 @@
 export * from './types';
 export * from './calendar-bridge';
 export * from './scheduler';
+export * from './schedule-cache';

plugin/calendar/schedule-cache.ts

@@ -0,0 +1,101 @@
+/**
+ * Multi-agent local schedule cache.
+ *
+ * Maintains today's schedule for all agents on this claw instance.
+ * Synced periodically from HF backend via /calendar/sync endpoint.
+ */
+
+export interface CachedSlot {
+  id: number | null;
+  virtual_id: string | null;
+  slot_type: string;
+  estimated_duration: number;
+  scheduled_at: string;
+  status: string;
+  priority: number;
+  event_type: string | null;
+  event_data: Record<string, unknown> | null;
+  [key: string]: unknown;
+}
+
+export class MultiAgentScheduleCache {
+  /** { agentId → slots[] } */
+  private schedules: Map<string, CachedSlot[]> = new Map();
+  private lastSyncAt: Date | null = null;
+  private cachedDate: string | null = null;
+
+  /**
+   * Replace cache with data from /calendar/sync response.
+   */
+  sync(date: string, schedules: Record<string, CachedSlot[]>): void {
+    if (this.cachedDate !== date) {
+      this.schedules.clear();
+    }
+    this.cachedDate = date;
+
+    for (const [agentId, slots] of Object.entries(schedules)) {
+      this.schedules.set(agentId, slots);
+    }
+    this.lastSyncAt = new Date();
+  }
+
+  /**
+   * Get agents that have due (overdue or current) slots.
+   * Returns [agentId, dueSlots[]] pairs.
+   */
+  getAgentsWithDueSlots(now: Date): Array<{ agentId: string; slots: CachedSlot[] }> {
+    const results: Array<{ agentId: string; slots: CachedSlot[] }> = [];
+
+    for (const [agentId, slots] of this.schedules) {
+      const due = slots.filter((s) => {
+        if (s.status !== 'not_started' && s.status !== 'deferred') return false;
+        const scheduledAt = this.parseScheduledTime(s.scheduled_at);
+        return scheduledAt !== null && scheduledAt <= now;
+      });
+
+      if (due.length > 0) {
+        // Sort by priority descending
+        due.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+        results.push({ agentId, slots: due });
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Get all agent IDs in the cache.
+   */
+  getAgentIds(): string[] {
+    return Array.from(this.schedules.keys());
+  }
+
+  /**
+   * Get slots for a specific agent.
+   */
+  getAgentSlots(agentId: string): CachedSlot[] {
+    return this.schedules.get(agentId) ?? [];
+  }
+
+  /**
+   * Get cache status for debugging.
+   */
+  getStatus(): { agentCount: number; totalSlots: number; lastSyncAt: string | null; cachedDate: string | null } {
+    let totalSlots = 0;
+    for (const slots of this.schedules.values()) totalSlots += slots.length;
+    return {
+      agentCount: this.schedules.size,
+      totalSlots,
+      lastSyncAt: this.lastSyncAt?.toISOString() ?? null,
+      cachedDate: this.cachedDate,
+    };
+  }
+
+  private parseScheduledTime(scheduledAt: string): Date | null {
+    if (/^\d{2}:\d{2}(:\d{2})?$/.test(scheduledAt)) {
+      if (!this.cachedDate) return null;
+      return new Date(`${this.cachedDate}T${scheduledAt}Z`);
+    }
+    const d = new Date(scheduledAt);
+    return isNaN(d.getTime()) ? null : d;
+  }
+}

plugin/calendar/scheduler.ts

@@ -19,6 +19,7 @@
 import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { CalendarBridgeClient } from './calendar-bridge';
+import { ScheduleCache } from './schedule-cache';
 import {
   CalendarSlotResponse,
   SlotStatus,
@@ -44,6 +45,8 @@ export interface CalendarSchedulerConfig {
   };
   /** Heartbeat interval in milliseconds (default: 60000) */
   heartbeatIntervalMs?: number;
+  /** Schedule sync interval in milliseconds (default: 300000 = 5 min) */
+  syncIntervalMs?: number;
   /** Enable verbose debug logging */
   debug?: boolean;
   /** Directory for state persistence (default: plugin data dir) */
@@ -95,8 +98,10 @@ interface SchedulerState {
   currentSlot: CalendarSlotResponse | null;
   /** Last heartbeat timestamp */
   lastHeartbeatAt: Date | null;
-  /** Interval handle for cleanup */
+  /** Heartbeat interval handle */
   intervalHandle: ReturnType<typeof setInterval> | null;
+  /** Schedule sync interval handle */
+  syncIntervalHandle: ReturnType<typeof setInterval> | null;
   /** Set of slot IDs that have been deferred in current session */
   deferredSlotIds: Set<string>;
   /** Whether agent is currently processing a slot */
@@ -117,10 +122,13 @@ export class CalendarScheduler {
   private config: Required<CalendarSchedulerConfig>;
   private state: SchedulerState;
   private stateFilePath: string;
+  /** Local cache of today's full schedule, synced periodically from backend */
+  private scheduleCache: ScheduleCache = new ScheduleCache();
 
   constructor(config: CalendarSchedulerConfig) {
     this.config = {
       heartbeatIntervalMs: 60000, // 1 minute default
+      syncIntervalMs: 300_000,    // 5 minutes default
       debug: false,
       stateDir: this.getDefaultStateDir(),
       ...config,
@@ -133,6 +141,7 @@ export class CalendarScheduler {
       currentSlot: null,
       lastHeartbeatAt: null,
       intervalHandle: null,
+      syncIntervalHandle: null,
       deferredSlotIds: new Set(),
       isProcessing: false,
       isRestartPending: false,
@@ -327,14 +336,21 @@ export class CalendarScheduler {
     this.state.isRestartPending = false;
     this.config.logger.info('Calendar scheduler started');
 
-    // Run initial heartbeat immediately
+    // Run initial sync + heartbeat immediately
+    this.runSync();
     this.runHeartbeat();
 
-    // Schedule periodic heartbeats
+    // Schedule periodic heartbeats (slot execution checks)
     this.state.intervalHandle = setInterval(
       () => this.runHeartbeat(),
       this.config.heartbeatIntervalMs
     );
+
+    // Schedule periodic schedule sync (full day schedule refresh)
+    this.state.syncIntervalHandle = setInterval(
+      () => this.runSync(),
+      this.config.syncIntervalMs
+    );
   }
 
   /**
@@ -348,10 +364,41 @@ export class CalendarScheduler {
       clearInterval(this.state.intervalHandle);
       this.state.intervalHandle = null;
     }
+    if (this.state.syncIntervalHandle) {
+      clearInterval(this.state.syncIntervalHandle);
+      this.state.syncIntervalHandle = null;
+    }
 
     this.config.logger.info('Calendar scheduler stopped');
   }
 
+  /**
+   * Sync today's full schedule from backend into local cache.
+   * Runs every syncIntervalMs (default: 5 min).
+   * Catches new slots assigned by other agents or the manager.
+   */
+  async runSync(): Promise<void> {
+    if (!this.state.isRunning || this.state.isRestartPending) return;
+
+    const today = new Date().toISOString().slice(0, 10);
+    try {
+      const slots = await this.config.bridge.getDaySchedule(today);
+      if (slots) {
+        this.scheduleCache.sync(today, slots);
+        this.logDebug(`Schedule synced: ${slots.length} slots for ${today}`);
+      }
+    } catch (err) {
+      this.config.logger.warn(`Schedule sync failed: ${String(err)}`);
+    }
+  }
+
+  /**
+   * Get the local schedule cache (for status reporting / tools).
+   */
+  getScheduleCache(): ScheduleCache {
+    return this.scheduleCache;
+  }
+
   /**
    * Execute a single heartbeat cycle.
    * Fetches pending slots and handles execution logic.
@@ -611,13 +658,11 @@ Task Code: ${code}
 Estimated Duration: ${duration} minutes
 Slot Type: ${slot.slot_type}
 Priority: ${slot.priority}
+Working Sessions: ${jobData.working_sessions?.join(', ') || 'none recorded'}
 
-Please focus on this task for the allocated time. When you finish or need to pause,
+Follow the daily-routine skill's task-handson workflow to execute this task.
-report your progress back to the calendar system.
+Use harborforge_calendar_complete when finished, or harborforge_calendar_pause to pause.
-
+Before going idle, check for overdue slots as described in the slot-complete workflow.`;
-Working sessions: ${jobData.working_sessions?.join(', ') || 'none recorded'}
-
-Start working on ${code} now.`;
   }
 
   /**
@@ -630,19 +675,15 @@ Start working on ${code} now.`;
     switch (sysData.event) {
       case 'ScheduleToday':
         return `System Event: Schedule Today
-
-Please review today's calendar and schedule any pending tasks or planning activities.
 Estimated time: ${slot.estimated_duration} minutes.
 
-Check your calendar and plan the day's work.`;
+Follow the daily-routine skill's plan-schedule workflow to plan today's work.`;
 
       case 'SummaryToday':
         return `System Event: Daily Summary
-
-Please provide a summary of today's activities and progress.
 Estimated time: ${slot.estimated_duration} minutes.
 
-Review what was accomplished and prepare end-of-day notes.`;
+Review today's completed, deferred, and abandoned slots. Write a summary to your daily note (memory/YYYY-MM-DD.md).`;
 
       case 'ScheduledGatewayRestart':
         return `System Event: Scheduled Gateway Restart

plugin/core/openclaw-agents.ts

@@ -1,8 +1,3 @@
-import { execFile } from 'child_process';
-import { promisify } from 'util';
-
-const execFileAsync = promisify(execFile);
-
 export interface OpenClawAgentInfo {
   name: string;
   isDefault?: boolean;
@@ -14,70 +9,38 @@ export interface OpenClawAgentInfo {
   routing?: string;
 }
 
-export async function listOpenClawAgents(logger?: { debug?: (...args: any[]) => void; warn?: (...args: any[]) => void }): Promise<OpenClawAgentInfo[]> {
+export async function listOpenClawAgents(_logger?: { debug?: (...args: any[]) => void; warn?: (...args: any[]) => void }): Promise<OpenClawAgentInfo[]> {
-  try {
+  return [];
-    const { stdout } = await execFileAsync('openclaw', ['agents', 'list'], {
-      timeout: 15000,
-      maxBuffer: 1024 * 1024,
-    });
-    return parseOpenClawAgents(stdout);
-  } catch (err) {
-    logger?.warn?.('Failed to run `openclaw agents list`', err);
-    return [];
-  }
 }
 
 export function parseOpenClawAgents(text: string): OpenClawAgentInfo[] {
   const lines = text.split(/\r?\n/);
   const out: OpenClawAgentInfo[] = [];
   let current: OpenClawAgentInfo | null = null;
-
+  const push = () => { if (current) out.push(current); current = null; };
-  const push = () => {
-    if (current) out.push(current);
-    current = null;
-  };
-
   for (const raw of lines) {
     const line = raw.trimEnd();
-    if (!line.trim() || line.startsWith('Agents:') || line.startsWith('Routing rules map') || line.startsWith('Channel status reflects')) continue;
+    if (!line.trim() || line.startsWith("Agents:") || line.startsWith("Routing rules map") || line.startsWith("Channel status reflects")) continue;
-    if (line.startsWith('- ')) {
+    if (line.startsWith("- ")) {
       push();
       const m = line.match(/^-\s+(.+?)(?:\s+\((default)\))?$/);
-      current = {
+      current = { name: m?.[1] || line.slice(2).trim(), isDefault: m?.[2] === "default" };
-        name: m?.[1] || line.slice(2).trim(),
-        isDefault: m?.[2] === 'default',
-      };
       continue;
     }
     if (!current) continue;
     const trimmed = line.trim();
-    const idx = trimmed.indexOf(':');
+    const idx = trimmed.indexOf(":");
     if (idx === -1) continue;
     const key = trimmed.slice(0, idx).trim();
     const value = trimmed.slice(idx + 1).trim();
     switch (key) {
-      case 'Identity':
+      case "Identity": current.identity = value; break;
-        current.identity = value;
+      case "Workspace": current.workspace = value; break;
-        break;
+      case "Agent dir": current.agentDir = value; break;
-      case 'Workspace':
+      case "Model": current.model = value; break;
-        current.workspace = value;
+      case "Routing rules": { const n = Number(value); current.routingRules = Number.isFinite(n) ? n : undefined; break; }
-        break;
+      case "Routing": current.routing = value; break;
-      case 'Agent dir':
+      default: break;
-        current.agentDir = value;
-        break;
-      case 'Model':
-        current.model = value;
-        break;
-      case 'Routing rules': {
-        const n = Number(value);
-        current.routingRules = Number.isFinite(n) ? n : undefined;
-        break;
-      }
-      case 'Routing':
-        current.routing = value;
-        break;
-      default:
-        break;
     }
   }
   push();

plugin/index.ts

@@ -14,7 +14,7 @@
 import { hostname, freemem, totalmem, uptime, loadavg, platform } from 'os';
 import { getPluginConfig } from './core/config';
 import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge';
-import { listOpenClawAgents } from './core/openclaw-agents';
+import type { OpenClawAgentInfo } from './core/openclaw-agents';
 import { registerGatewayStartHook } from './hooks/gateway-start';
 import { registerGatewayStopHook } from './hooks/gateway-stop';
 import {
@@ -32,6 +32,12 @@ interface PluginAPI {
     warn: (...args: any[]) => void;
   };
   version?: string;
+  runtime?: {
+    version?: string;
+    config?: {
+      loadConfig?: () => any;
+    };
+  };
   config?: Record<string, unknown>;
   pluginConfig?: Record<string, unknown>;
   on: (event: string, handler: () => void) => void;
@@ -62,6 +68,13 @@ export default {
       return getPluginConfig(api);
     }
 
+    /** Resolve agent ID from env, config, or fallback. */
+    function resolveAgentId(): string {
+      if (process.env.AGENT_ID) return process.env.AGENT_ID;
+      const cfg = api.runtime?.config?.loadConfig?.();
+      return cfg?.agents?.list?.[0]?.id ?? cfg?.agents?.defaults?.id ?? 'unknown';
+    }
+
     /**
      * Get the monitor bridge client if monitor_port is configured.
      */
@@ -96,7 +109,7 @@ export default {
           avg15: load[2],
         },
         openclaw: {
-          version: api.version || 'unknown',
+          version: api.runtime?.version || api.version || 'unknown',
           pluginVersion: '0.3.1', // Bumped for PLG-CAL-004
         },
         timestamp: new Date().toISOString(),
@@ -118,10 +131,21 @@ export default {
       const bridgeClient = getBridgeClient();
       if (!bridgeClient) return;
 
+      let agentNames: string[] = [];
+      try {
+        const cfg = api.runtime?.config?.loadConfig?.();
+        const agentsList = cfg?.agents?.list;
+        if (Array.isArray(agentsList)) {
+          agentNames = agentsList
+            .map((a: any) => typeof a === 'string' ? a : a?.name)
+            .filter(Boolean);
+        }
+      } catch { /* non-fatal */ }
+
       const meta: OpenClawMeta = {
-        version: api.version || 'unknown',
+        version: api.runtime?.version || api.version || 'unknown',
         plugin_version: '0.3.1',
-        agents: await listOpenClawAgents(logger),
+        agents: agentNames.map(name => ({ name })),
       };
 
       const ok = await bridgeClient.pushOpenClawMeta(meta);
@@ -151,7 +175,7 @@ export default {
 
       // Fallback: query backend for agent status
       const live = resolveConfig();
-      const agentId = process.env.AGENT_ID || 'unknown';
+      const agentId = resolveAgentId();
       try {
         const response = await fetch(`${live.backendUrl}/calendar/agent/status?agent_id=${agentId}`, {
           headers: {
@@ -171,56 +195,51 @@ export default {
     }
 
     /**
-     * Wake/spawn agent with task context for slot execution.
+     * Wake agent via dispatchInboundMessage — same mechanism used by Discord plugin.
-     * This is the callback invoked by CalendarScheduler when a slot is ready.
+     * Direct in-process call, no WebSocket or CLI needed.
      */
-    async function wakeAgent(context: AgentWakeContext): Promise<boolean> {
+    async function wakeAgent(agentId: string): Promise<boolean> {
-      logger.info(`Waking agent for slot: ${context.taskDescription}`);
+      logger.info(`Waking agent ${agentId}: has due slots`);
+
+      const sessionKey = `agent:${agentId}:hf-wakeup`;
 
       try {
-        // Method 1: Use OpenClaw spawn API if available (preferred)
+        const sdkPath = 'openclaw/plugin-sdk/reply-runtime';
-        if (api.spawn) {
+        const { dispatchInboundMessageWithDispatcher } = await import(
-          const result = await api.spawn({
+          /* webpackIgnore: true */ sdkPath
-            task: context.prompt,
+        );
-            timeoutSeconds: context.slot.estimated_duration * 60, // Convert to seconds
-          });
 
-          if (result?.sessionId) {
+        const cfg = api.runtime?.config?.loadConfig?.();
-            logger.info(`Agent spawned for calendar slot: session=${result.sessionId}`);
+        if (!cfg) {
-
+          logger.error('Cannot load OpenClaw config for dispatch');
-            // Track session completion
+          return false;
-            trackSessionCompletion(result.sessionId, context);
-            return true;
-          }
         }
 
-        // Method 2: Send notification/alert to wake agent (fallback)
+        const wakeupMessage = `You have due slots. Follow the \`hf-wakeup\` workflow of skill \`hf-hangman-lab\` to proceed. Only reply \`WAKEUP_OK\` in this session.`;
-        // This relies on the agent's heartbeat to check for notifications
-        logger.warn('OpenClaw spawn API not available, using notification fallback');
 
-        // Send calendar wakeup notification via backend
+        const result = await dispatchInboundMessageWithDispatcher({
-        const live = resolveConfig();
+          ctx: {
-        const agentId = process.env.AGENT_ID || 'unknown';
+            Body: wakeupMessage,
-
+            SessionKey: sessionKey,
-        const notifyResponse = await fetch(`${live.backendUrl}/calendar/agent/notify`, {
+            From: 'harborforge-calendar',
-          method: 'POST',
+            Provider: 'harborforge',
-          headers: {
+          },
-            'Content-Type': 'application/json',
+          cfg,
-            'X-Agent-ID': agentId,
+          dispatcherOptions: {
-            'X-Claw-Identifier': live.identifier || hostname(),
+            deliver: async (payload: any) => {
+              const text = (payload.text || '').trim();
+              logger.info(`Agent ${agentId} wakeup reply: ${text.slice(0, 100)}`);
+            },
           },
-          body: JSON.stringify({
-            agent_id: agentId,
-            message: context.prompt,
-            slot_id: context.slot.id || context.slot.virtual_id,
-            task_description: context.taskDescription,
-          }),
         });
 
-        return notifyResponse.ok;
+        logger.info(`Agent ${agentId} dispatched: ${result?.status || 'ok'}`);
+        return true;
 
-      } catch (err) {
+      } catch (err: any) {
-        logger.error('Failed to wake agent:', err);
+        const msg = err?.message || err?.code || String(err);
+        const stack = err?.stack?.split('\n').slice(0, 3).join(' | ') || '';
+        logger.error(`Failed to dispatch agent for slot: ${msg} ${stack}`);
         return false;
       }
     }
@@ -262,27 +281,69 @@ export default {
      */
     function startCalendarScheduler(): void {
       const live = resolveConfig();
-      const agentId = process.env.AGENT_ID || 'unknown';
 
-      // Create calendar bridge client
+      // Create bridge client (claw-instance level, not per-agent)
       const calendarBridge = createCalendarBridgeClient(
         api,
         live.backendUrl || 'https://monitor.hangman-lab.top',
-        agentId
+        'unused' // agentId no longer needed at bridge level
       );
 
-      // Create and start scheduler
+      // Multi-agent sync + check loop
-      calendarScheduler = createCalendarScheduler({
+      const { MultiAgentScheduleCache } = require('./calendar/schedule-cache') as typeof import('./calendar/schedule-cache');
-        bridge: calendarBridge,
+      const scheduleCache = new MultiAgentScheduleCache();
-        getAgentStatus,
-        wakeAgent,
-        logger,
-        heartbeatIntervalMs: 60000, // 1 minute
-        debug: live.logLevel === 'debug',
-      });
 
-      calendarScheduler.start();
+      const SYNC_INTERVAL_MS = 300_000; // 5 min
-      logger.info('Calendar scheduler started');
+      const CHECK_INTERVAL_MS = 30_000; // 30 sec
+
+      // Sync: pull all agent schedules from backend
+      async function runSync() {
+        try {
+          const result = await calendarBridge.syncSchedules();
+          if (result) {
+            scheduleCache.sync(result.date, result.schedules);
+            const status = scheduleCache.getStatus();
+            logger.info(`Schedule synced: ${status.agentCount} agents, ${status.totalSlots} slots`);
+          }
+        } catch (err) {
+          logger.warn(`Schedule sync failed: ${String(err)}`);
+        }
+      }
+
+      // Check: find agents with due slots and wake them
+      async function runCheck() {
+        const now = new Date();
+        const agentsWithDue = scheduleCache.getAgentsWithDueSlots(now);
+
+        for (const { agentId } of agentsWithDue) {
+          // Check if agent is busy
+          const status = await calendarBridge.getAgentStatus(agentId);
+          if (status === 'busy' || status === 'offline' || status === 'exhausted') {
+            continue;
+          }
+
+          // Wake the agent
+          await wakeAgent(agentId);
+        }
+      }
+
+      // Initial sync
+      runSync();
+
+      // Start intervals
+      const syncHandle = setInterval(runSync, SYNC_INTERVAL_MS);
+      const checkHandle = setInterval(runCheck, CHECK_INTERVAL_MS);
+
+      // Store handles for cleanup (reuse calendarScheduler variable)
+      (calendarScheduler as any) = {
+        stop() {
+          clearInterval(syncHandle);
+          clearInterval(checkHandle);
+          logger.info('Calendar scheduler stopped');
+        },
+      };
+
+      logger.info('Calendar scheduler started (multi-agent sync mode)');
     }
 
     /**