fix: wake dedupe + inline slot context + complete contracts.tools

Three issues making HF→agent wakeup unusable in practice, surfaced by DinD sim end-to-end test (recruiter agent + slot for 招募 manager task): 1. **Plugin re-woke the same slot every 30s.** The inline runCheck only destructured agentId from scheduleCache.getAgentsWithDueSlots() and dropped the slots array, then called wakeAgent without recording the wake. The simplified inline scheduler also never PATCHes slot status server-side from not_started→ongoing, so the next 30s check sees the slot still due and wakes again. After 4 wakes the agent's wakeup session was full of WAKEUP_OK noise. Fix: keep slots in runCheck, add an in-memory wakedSlotKeys set keyed by (agentId, slotId|virtual_id|scheduled_at). Dedupe on this set; clear it inside the sync interval (fresh wake budget per sync). Server-side slot transition still TODO (requires re-introducing the CalendarScheduler class path or PATCH /calendar/slots/.../agent-update here); the dedupe at least stops the wake spam. 2. **Wakeup message had no slot context.** The wakeup body just said 'follow hf-wakeup workflow' with no slot id/event_data/task_code. The agent then had to call harborforge_calendar_status to learn anything — which itself is broken in the simplified scheduler (it queries a CalendarScheduler instance that never gets created). Fix: pass dueSlots into wakeAgent and inline the highest-priority slot's {slot_id, scheduled_at, priority, slot_type, event_data} as a JSON block in the wakeup message. The agent reads event_data. task_code directly and routes via workflow_lookup without any round-trip. Per PLG-CAL-001 docs in hf-hangman-lab SKILL.md, this is the documented contract; we are bringing the message in line. 3. **contracts.tools listed 5 of the 9 registered tools.** Manifest had harborforge_status/telemetry/monitor_telemetry/calendar_status/ calendar_complete. Code also registers calendar_abort, calendar_pause, calendar_resume, harborforge_restart_status. With the new OpenClaw plugin host enforcement (same gotcha that bit Meridian — see zhi/Meridian#2), undeclared tools are silently dropped from the agent's tool list, so abort/pause/resume cannot be called by the agent. plugin doctor was emitting: 'plugin tool is undeclared (harbor-forge): harborforge_calendar_abort' for each missing tool. Fix: add the 4 missing tool names to contracts.tools. Also use api.config as the primary config source in wakeAgent (current public API), falling back to runtime.config.loadConfig() for older hosts — same pattern as the Meridian fix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Merge docs/readme-refresh into main
2026-05-20 12:02:25 +01:00 · 2026-05-16 17:55:57 +01:00 · 2026-05-16 17:50:01 +01:00 · 2026-05-08 08:29:35 +00:00 · 2026-05-08 08:28:58 +00:00 · 2026-05-01 07:23:25 +00:00
27 changed files with 3630 additions and 738 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,8 @@
+plugin/node_modules/
+plugin/dist/
+plugin/**/*.js
+plugin/**/*.js.map
+plugin/**/*.d.ts
+plugin/**/*.d.ts.map
+# Hand-written ambient declarations are tracked; only compiled .d.ts above is ignored.
+!plugin/openclaw-sdk.d.ts
--- a/README.md
+++ b/README.md
@@ -1,145 +1,198 @@
 # HarborForge OpenClaw Plugin

-OpenClaw 插件，将服务器遥测数据流式传输到 HarborForge Monitor。
+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.

-## 项目结构
+Part of the [HarborForge](../README.md) platform.

-```
+- Role: OpenClaw integration layer for HarborForge (registered plugin id: `harbor-forge`).
+- Talks to the HarborForge backend (`backendUrl`, default `https://monitor.hangman-lab.top`) for Calendar APIs.
+- Talks to a local HarborForge.Monitor bridge over `127.0.0.1:<monitor_port>` (no fixed default; commonly `9100`).
+
+## 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                 # 根 package.json
-├── README.md                    # 本文档
-├── plugin/                      # OpenClaw 插件代码
-│   ├── openclaw.plugin.json     # 插件定义
-│   ├── index.ts                 # 插件入口
-│   ├── package.json             # 插件依赖
-│   └── tsconfig.json            # TypeScript 配置
-├── server/                      # Sidecar 服务器
-│   └── telemetry.mjs            # 遥测数据收集和发送
-├── skills/                      # OpenClaw 技能
-│   └── (技能文件)
+├── package.json
+├── README.md
+├── docs/                         # design notes (calendar, monitor connector)
+├── plugin/
+│   ├── openclaw.plugin.json      # plugin manifest + config schema
+│   ├── index.ts                  # plugin entry, tool registration
+│   ├── tsconfig.json
+│   ├── core/
+│   │   ├── config.ts             # config defaults / resolution
+│   │   ├── managed-monitor.ts    # optionally spawn HarborForge.Monitor
+│   │   ├── monitor-bridge.ts     # client for the Monitor bridge
+│   │   └── 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
 └── scripts/
-    └── install.mjs              # 安装脚本
+    └── install.mjs
 ```

-## 架构
+## Installation

-```
-┌─────────────────────────────────────────────────┐
-│  OpenClaw Gateway                               │
-│  ┌───────────────────────────────────────────┐  │
-│  │  HarborForge.OpenclawPlugin/plugin/       │  │
-│  │  - 生命周期管理 (启动/停止)                 │  │
-│  │  - 配置管理                                │  │
-│  └───────────────────────────────────────────┘  │
-│              │                                   │
-│              ▼ 启动 telemetry server             │
-│  ┌───────────────────────────────────────────┐  │
-│  │  HarborForge.OpenclawPlugin/server/       │  │
-│  │  - 独立 Node 进程                          │  │
-│  │  - 收集系统指标                            │  │
-│  │  - 收集 OpenClaw 状态                      │  │
-│  │  - 发送到 HarborForge Monitor              │  │
-│  └───────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────┘
-                        │
-                        ▼ HTTP/WebSocket
-              ┌─────────────────────┐
-              │ HarborForge Monitor │
-              └─────────────────────┘
-```
-
-## 安装
-
-### 快速安装
+### Standard Install

 ```bash
-# 克隆仓库
-git clone https://git.hangman-lab.top/zhi/HarborForge.OpenclawPlugin.git
-cd HarborForge.OpenclawPlugin
-
-# 运行安装脚本
 node scripts/install.mjs
 ```

-### 开发安装
+This will:
+- Build and install the OpenClaw plugin
+- Copy regular skills
+- **Not** install the `hf` binary
+- **Not** copy `skills/hf/`
+
+### Plugin + `hf` CLI

 ```bash
-# 仅构建不安装
-node scripts/install.mjs --build-only
-
-# 指定 OpenClaw 路径
-node scripts/install.mjs --openclaw-profile-path /custom/path/.openclaw
-
-# 详细输出
-node scripts/install.mjs --verbose
+node scripts/install.mjs --install-cli
 ```

-## 配置
+This additionally:
+- Builds `HarborForge.Cli` (`go build ./cmd/hf`)
+- Installs `hf` to `<openclaw>/bin/hf` (default `~/.openclaw/bin/hf`) and `chmod +x`
+- Copies `skills/hf/` into the OpenClaw skills directory

-1. 在 HarborForge Monitor 中注册服务器，获取 `challengeUuid`
+### Common Options

-2. 编辑 `~/.openclaw/openclaw.json`:
+```bash
+# Build only (no install / config)
+node scripts/install.mjs --build-only
+
+# Install only, skip dependency checks
+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
+
+Edit `~/.openclaw/openclaw.json`:

 ```json
 {
  "plugins": {
-    "harborforge-monitor": {
-      "enabled": true,
-      "backendUrl": "https://monitor.hangman-lab.top",
-      "identifier": "my-server-01",
-      "challengeUuid": "your-challenge-uuid-here",
-      "reportIntervalSec": 30,
-      "httpFallbackIntervalSec": 60,
-      "logLevel": "info"
+    "entries": {
+      "harbor-forge": {
+        "enabled": true,
+        "config": {
+          "enabled": true,
+          "backendUrl": "https://monitor.hangman-lab.top",
+          "identifier": "my-server-01",
+          "apiKey": "your-api-key-here",
+          "monitor_port": 9100,
+          "reportIntervalSec": 30,
+          "httpFallbackIntervalSec": 60,
+          "logLevel": "info",
+          "calendarEnabled": true,
+          "calendarHeartbeatIntervalSec": 60
+        }
+      }
    }
  }
 }
 ```

-3. 重启 OpenClaw Gateway:
+Then restart:

 ```bash
 openclaw gateway restart
 ```

-## 配置选项
+## Config Options

-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `enabled` | boolean | `true` | 是否启用插件 |
-| `backendUrl` | string | `https://monitor.hangman-lab.top` | Monitor 后端地址 |
-| `identifier` | string | 自动检测 hostname | 服务器标识符 |
-| `challengeUuid` | string | 必填 | 注册挑战 UUID |
-| `reportIntervalSec` | number | `30` | 报告间隔（秒） |
-| `httpFallbackIntervalSec` | number | `60` | HTTP 回退间隔（秒） |
-| `logLevel` | string | `"info"` | 日志级别: debug/info/warn/error |
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable the plugin |
+| `backendUrl` | string | `https://monitor.hangman-lab.top` | HarborForge backend base URL (Monitor + Calendar APIs) |
+| `identifier` | string | hostname | Server / claw identifier |
+| `apiKey` | string | (none) | Server API key from the HarborForge Monitor admin panel |
+| `monitor_port` | number | (none) | Local bridge port; plugin talks to HarborForge.Monitor via `127.0.0.1:<monitor_port>` |
+| `reportIntervalSec` | number | `30` | Metadata push interval (seconds) |
+| `httpFallbackIntervalSec` | number | `60` | HTTP heartbeat interval when WS unavailable |
+| `logLevel` | string | `info` | Log level: `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

-### 系统指标
- CPU 使用率 (%)
- 内存使用率 (%)、已用/总量 (MB)
- 磁盘使用率 (%)、已用/总量 (GB)
- 交换分区使用率 (%)
- 系统运行时间 (秒)
- 1分钟平均负载
- 平台 (linux/darwin/win32)
- 主机名
+When the plugin has `monitor_port` configured and HarborForge.Monitor uses the same `MONITOR_PORT`:

-### OpenClaw 指标
- OpenClaw 版本
- Agent 数量
- Agent 列表 (id, name, status)
+- Monitor serves a local bridge on `127.0.0.1:<MONITOR_PORT>`
+- The plugin probes `GET /health`
+- The plugin tool `harborforge_monitor_telemetry` reads `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.

-```bash
-node scripts/install.mjs --uninstall
-```
+## 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.

-### 构建插件
+## Calendar Scheduler
+
+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
@@ -147,21 +200,16 @@ npm install
 npm run build
 ```

-### 本地测试 telemetry server
+The build runs `tsc` and emits `dist/` (`dist/index.js` is the plugin entry).

-```bash
-cd server
-HF_MONITOR_CHALLENGE_UUID=test-uuid \
-HF_MONITOR_BACKEND_URL=http://localhost:8000 \
-HF_MONITOR_LOG_LEVEL=debug \
-node telemetry.mjs
-```
-
-## 依赖
+## Dependencies

 - Node.js 18+
 - OpenClaw Gateway
+- Go 1.20+ (only for `--install-cli` / `--install-monitor`)

-## 文档
+## Tips

- [监控连接器规划](./docs/monitor-server-connector-plan.md) - 原始设计文档
+- After installing `hf`, add `~/.openclaw/bin` to your `PATH`
+- When an agent uses `hf`, try `hf --help-brief` first
+- For the full command tree, see `hf --help`
--- a/REFACTOR_PLAN.md
+++ b/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
--- a/docs/PLG-CAL-001-calendar-heartbeat-format.md
+++ b/docs/PLG-CAL-001-calendar-heartbeat-format.md
@@ -0,0 +1,261 @@
+# PLG-CAL-001 — Calendar Heartbeat Format Specification
+
+> **Task:** HarborForge OpenclawPlugin / Monitor 联动  
+> **Subtask:** PLG-CAL-001 — 插件侧定义 Calendar 心跳请求格式  
+> **Status:** ✅ Implemented (types + client + spec)  
+> **Date:** 2026-04-01
+
+---
+
+## Overview
+
+This document specifies the request/response format for the Calendar heartbeat
+communication between the OpenClaw HarborForge plugin and the HarborForge backend.
+
+Heartbeat direction: **Plugin → Backend**
+
+The plugin sends a heartbeat every minute (aligned with the existing Monitor
+heartbeat interval). The backend returns today's pending TimeSlots for the agent.
+
+---
+
+## 1. How `claw_identifier` is Determined
+
+`claw_identifier` identifies the server/claw instance. It is the same value used
+in the Monitor heartbeat system (`MonitoredServer.identifier`).
+
+**Priority order:**
+
+1. **`config.identifier`** — if set in the plugin config (`harbor-forge.identifier`)
+2. **`os.hostname()`** — auto-detected from the machine hostname (fallback)
+
+```typescript
+// In plugin/calendar/calendar-bridge.ts
+const clawIdentifier = baseConfig.identifier || hostname();
+```
+
+---
+
+## 2. How `agent_id` is Determined
+
+`agent_id` is the OpenClaw agent identifier (`$AGENT_ID`).
+
+- Set by OpenClaw at agent startup as an environment variable
+- The plugin reads it via `process.env.AGENT_ID`
+- Globally unique within a single OpenClaw gateway deployment
+
+```typescript
+// In plugin/index.ts (caller)
+const agentId = process.env.AGENT_ID || 'unknown';
+```
+
+---
+
+## 3. Heartbeat Request
+
+**Endpoint:** `GET /calendar/agent/heartbeat`
+
+### Headers
+
+| Header | Value | Notes |
+|--------|-------|-------|
+| `Content-Type` | `application/json` | Always set |
+| `X-Agent-ID` | `$AGENT_ID` | OpenClaw agent identifier |
+| `X-Claw-Identifier` | `claw_identifier` | Server identifier |
+
+### Request Body (JSON)
+
+```json
+{
+  "claw_identifier": "srv1390517",
+  "agent_id": "developer"
+}
+```
+
+### Field Definitions
+
+| Field | Type | Source | Notes |
+|-------|------|--------|-------|
+| `claw_identifier` | string | Plugin config or `hostname()` | Identifies the OpenClaw server instance |
+| `agent_id` | string | `process.env.AGENT_ID` | Identifies the agent session |
+
+---
+
+## 4. Heartbeat Response
+
+### Success (HTTP 200)
+
+```json
+{
+  "slots": [
+    {
+      "id": 42,
+      "virtual_id": null,
+      "user_id": 1,
+      "date": "2026-04-01",
+      "slot_type": "work",
+      "estimated_duration": 30,
+      "scheduled_at": "09:00:00",
+      "started_at": null,
+      "attended": false,
+      "actual_duration": null,
+      "event_type": "job",
+      "event_data": {
+        "type": "Task",
+        "code": "TASK-123"
+      },
+      "priority": 50,
+      "status": "not_started",
+      "plan_id": null
+    }
+  ],
+  "agent_status": "idle",
+  "message": "2 slots pending"
+}
+```
+
+### Field Definitions
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `slots` | `CalendarSlotResponse[]` | Pending slots, sorted by `priority` DESC |
+| `agent_status` | `AgentStatusValue` | Current backend-observed agent status |
+| `message` | string (optional) | Human-readable summary |
+
+### `CalendarSlotResponse` Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `number \| null` | Real slot DB id. `null` for virtual slots. |
+| `virtual_id` | `string \| null` | `plan-{plan_id}-{date}`. `null` for real slots. |
+| `user_id` | number | Owner HarborForge user id |
+| `date` | string | ISO date `YYYY-MM-DD` |
+| `slot_type` | `SlotType` | `work \| on_call \| entertainment \| system` |
+| `estimated_duration` | number | Minutes (1-50) |
+| `scheduled_at` | string | ISO time `HH:MM:SS` |
+| `started_at` | `string \| null` | Actual start time when slot begins |
+| `attended` | boolean | `true` once agent begins the slot |
+| `actual_duration` | `number \| null` | Real minutes when slot finishes |
+| `event_type` | `EventType \| null` | `job \| entertainment \| system_event` |
+| `event_data` | object \| null | See §4a below |
+| `priority` | number | 0-99, higher = more urgent |
+| `status` | `SlotStatus` | `not_started \| deferred \| ...` |
+| `plan_id` | `number \| null` | Source plan if materialized from SchedulePlan |
+
+### §4a — `event_data` Shapes
+
+**When `event_type == "job"`:**
+```json
+{
+  "type": "Task",
+  "code": "TASK-42",
+  "working_sessions": ["session-id-1"]
+}
+```
+
+**When `event_type == "system_event"`:**
+```json
+{
+  "event": "ScheduleToday"
+}
+```
+Valid events: `ScheduleToday | SummaryToday | ScheduledGatewayRestart`
+
+---
+
+## 5. Slot Update Requests (Plugin → Backend after execution)
+
+After attending / finishing / deferring a slot, the plugin calls:
+
+**Real slot:** `PATCH /calendar/slots/{slot_id}/agent-update`
+**Virtual slot:** `PATCH /calendar/slots/virtual/{virtual_id}/agent-update`
+
+### Headers
+
+Same as heartbeat (see §3).
+
+### Request Body
+
+```json
+{
+  "status": "ongoing",
+  "started_at": "09:02:31",
+  "actual_duration": null
+}
+```
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `status` | `SlotStatus` | **Required** | New status after agent action |
+| `started_at` | string | On attending | ISO time `HH:MM:SS` |
+| `actual_duration` | number | On finishing | Real minutes |
+
+### Status Transition Values
+
+| Action | `status` value |
+|--------|---------------|
+| Agent begins slot | `ongoing` |
+| Agent finishes slot | `finished` |
+| Agent defers slot | `deferred` |
+| Agent aborts slot | `aborted` |
+| Agent pauses slot | `paused` |
+
+---
+
+## 6. Backend Endpoint Summary
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/calendar/agent/heartbeat` | X-Agent-ID + X-Claw-Identifier | Fetch pending slots for today |
+| PATCH | `/calendar/slots/{id}/agent-update` | X-Agent-ID + X-Claw-Identifier | Update real slot status |
+| PATCH | `/calendar/slots/virtual/{vid}/agent-update` | X-Agent-ID + X-Claw-Identifier | Update virtual slot status |
+| POST | `/calendar/agent/status` | X-Agent-ID + X-Claw-Identifier | Report agent status change |
+
+---
+
+## 7. Error Handling
+
+- **Backend unreachable:** Plugin logs warning, returns `null` from heartbeat.  
+  Agent continues to operate without Calendar integration.
+- **Invalid credentials (401/403):** Logged as error. No retry on same interval.
+- **Rate limiting (429):** Plugin should mark agent as `Exhausted` and not retry
+  until the `Retry-After` header indicates.
+
+---
+
+## 8. TypeScript Reference
+
+Full type definitions are in `plugin/calendar/types.ts`:
+
+```typescript
+// Request
+interface CalendarHeartbeatRequest {
+  claw_identifier: string;
+  agent_id: string;
+}
+
+// Response
+interface CalendarHeartbeatResponse {
+  slots: CalendarSlotResponse[];
+  agent_status: AgentStatusValue;
+  message?: string;
+}
+
+// Slot update
+interface SlotAgentUpdate {
+  status: SlotStatus;
+  started_at?: string;   // ISO time HH:MM:SS
+  actual_duration?: number;
+}
+```
+
+---
+
+## 9. Implementation Files
+
+| File | Purpose |
+|------|---------|
+| `plugin/calendar/types.ts` | TypeScript interfaces for all request/response shapes |
+| `plugin/calendar/calendar-bridge.ts` | `CalendarBridgeClient` HTTP client |
+| `plugin/calendar/index.ts` | Module entry point |
+| `docs/PLG-CAL-001-calendar-heartbeat-format.md` | This specification |
--- a/docs/monitor-server-connector-plan.md
+++ b/docs/monitor-server-connector-plan.md
@@ -1,112 +1,54 @@
-# HarborForge OpenClaw Server Connector Plugin — Project Plan
+# Monitor Server Connector Plan

-## 1) Goal
-Provide a secure, lightweight plugin/agent that connects servers to HarborForge Monitor, streams telemetry in real time, and falls back to HTTP heartbeat when WebSocket is unavailable.
+## Current design

-## 2) Scope
- **Handshake + auth** using backend-issued challenge + RSA-OAEP encrypted payload.
- **WebSocket telemetry** to `/monitor/server/ws`.
- **HTTP heartbeat** to `/monitor/server/heartbeat` as fallback.
- **System metrics**: CPU/Mem/Disk/Swap/Uptime/OpenClaw version/Agents list.
- **Retry & backoff**, offline handling, and minimal local state.
+The plugin and Monitor communicate over a local bridge port (`monitor_port` / `MONITOR_PORT`).

-## 3) Non-Goals
- No UI in the plugin.
- No provider billing calls from plugin.
- No multi-tenant auth beyond challenge + server identifier.
+### Data flow

-## 4) Architecture
-```
-plugin/
-  config/          # load config & secrets
-  crypto/          # RSA-OAEP encrypt/decrypt helpers
-  collector/       # system + openclaw metrics
-  transport/       # ws + http heartbeat
-  state/           # retry/backoff, last sent, cache
-  main.ts|py        # entry
-```
+1. **Monitor → Plugin** (GET): Plugin queries `GET /telemetry` on the bridge for host hardware data.
+2. **Plugin → Monitor** (POST): Plugin pushes OpenClaw metadata via `POST /openclaw` to the bridge.
+3. **Monitor → Backend**: Monitor heartbeats to `POST /monitor/server/heartbeat-v2` with `X-API-Key`, enriched with any available OpenClaw metadata.

-### 4.1 Config
- `backend_url`
- `identifier`
- `challenge_uuid`
- `report_interval_sec` (default: 20-30s)
- `http_fallback_interval_sec` (default: 60s)
- `log_level`
+### Bridge endpoints (on Monitor, 127.0.0.1:MONITOR_PORT)

-### 4.2 Security
- Fetch public key: `GET /monitor/public/server-public-key`
- Encrypt payload with RSA-OAEP
- Include `nonce` + `ts` (UTC) to prevent replay
- **Challenge valid**: 10 minutes
- **Offline threshold**: 7 minutes
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check, returns monitor version and identifier |
+| `/telemetry` | GET | Latest hardware telemetry snapshot |
+| `/openclaw` | POST | Receive OpenClaw metadata from plugin |

-## 5) Communication Flow
-### 5.1 Handshake (WS)
-1. Plugin reads `identifier + challenge_uuid`.
-2. Fetch RSA public key.
-3. Encrypt payload: `{identifier, challenge_uuid, nonce, ts}`.
-4. Connect WS `/monitor/server/ws` and send `encrypted_payload`.
-5. On success: begin periodic telemetry push.
+### Plugin behavior

-### 5.2 Fallback (HTTP)
-If WS fails:
- POST telemetry to `/monitor/server/heartbeat` with same payload fields.
- Retry with exponential backoff (cap 5–10 min).
+- On `gateway_start`, plugin begins periodic metadata push (aligned with `reportIntervalSec`).
+- Initial push is delayed 2s to allow Monitor bridge startup.
+- If bridge is unreachable, pushes fail silently. Plugin remains fully functional.
+- On `gateway_stop`, periodic push is stopped.

-## 6) Telemetry Schema (example)
-```
+## No longer used
+
+The following design has been retired:
+
+- challenge UUID / RSA handshake / WebSocket telemetry
+- Plugin-side `server/` sidecar process
+
+## Heartbeat payload
+
+```json
 {
-  identifier: "vps.t1",
-  openclaw_version: "x.y.z",
-  cpu_pct: 12.5,
-  mem_pct: 41.2,
-  disk_pct: 62.0,
-  swap_pct: 0.0,
-  agents: [ { id: "a1", name: "agent", status: "running" } ],
-  last_seen_at: "2026-03-11T21:00:00Z"
+  "identifier": "vps.t1",
+  "openclaw_version": "OpenClaw 2026.3.13 (61d171a)",
+  "plugin_version": "0.2.0",
+  "agents": [],
+  "cpu_pct": 10.5,
+  "mem_pct": 52.1,
+  "disk_pct": 81.0,
+  "swap_pct": 0.0,
+  "load_avg": [0.12, 0.09, 0.03],
+  "uptime_seconds": 12345,
+  "nginx_installed": true,
+  "nginx_sites": ["default"]
 }
 ```

-## 7) Reliability
- Automatic reconnect on WS drop
- HTTP fallback if WS unavailable > 2 intervals
- Exponential backoff on failures
- Local cache for last successful payload
-
-## 8) Deployment Options
- **Systemd service** (preferred for VPS)
- **Docker container** (optional)
- Single-binary build if using Go/Rust
-
-## 9) Milestones
-**M1 – POC (2–3 days)**
- CLI config loader + HTTP heartbeat
- See online + metrics in Monitor
-
-**M2 – WS realtime (2–3 days)**
- Full handshake + WS streaming
- Reconnect & fallback logic
-
-**M3 – Packaging (1–2 days)**
- systemd unit + sample config
- installation script
-
-**M4 – Hardening & Docs (1–2 days)**
- logging, metrics, docs
- troubleshooting guide
-
-## 10) Deliverables
- Plugin source
- Config template + systemd unit
- Integration docs
- Test script + example payloads
-
-## 11) Open Questions
- Preferred language (Go/Python/Node/Rust)?
- How to read OpenClaw agent list (API vs local state)?
- Required log format / retention?
-
---
-
-**Next step:** confirm preferred runtime (Go/Python/Node) and I will scaffold the project structure + first heartbeat implementation.
+`openclaw_version`, `plugin_version`, and `agents` are optional enrichment from the plugin. If plugin never pushes metadata, these fields are omitted and the heartbeat contains only hardware telemetry.
--- a/package-lock.json
+++ b/package-lock.json
@@ -0,0 +1,17 @@
+{
+  "name": "harbor-forge-openclaw-plugin",
+  "version": "0.2.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "harbor-forge-openclaw-plugin",
+      "version": "0.2.0",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    }
+  }
+}
--- a/package.json
+++ b/package.json
@@ -1,14 +1,15 @@
 {
-  "name": "harborforge-openclaw-plugin",
-  "version": "0.1.0",
-  "description": "OpenClaw plugin for HarborForge Monitor - streams server telemetry",
+  "name": "harbor-forge-openclaw-plugin",
+  "version": "0.2.0",
+  "description": "OpenClaw plugin for HarborForge - project management, monitoring, and CLI integration",
  "type": "module",
  "scripts": {
    "build": "cd plugin && npm run build",
    "install": "node scripts/install.mjs",
+    "install-cli": "node scripts/install.mjs --install-cli",
    "uninstall": "node scripts/install.mjs --uninstall"
  },
-  "keywords": ["openclaw", "plugin", "monitoring", "harborforge"],
+  "keywords": ["openclaw", "plugin", "monitoring", "harborforge", "harbor-forge"],
  "license": "MIT",
  "engines": {
    "node": ">=18.0.0"
--- a/plugin/calendar/calendar-bridge.ts
+++ b/plugin/calendar/calendar-bridge.ts
@@ -0,0 +1,330 @@
+/**
+ * HarborForge Calendar Bridge Client
+ *
+ * PLG-CAL-001: Handles HTTP communication between the OpenClaw plugin
+ * and the HarborForge backend for Calendar heartbeat and slot updates.
+ *
+ * Request authentication:
+ *   • X-Agent-ID header — set to process.env.AGENT_ID
+ *   • X-Claw-Identifier header — set to the server's claw_identifier
+ *     (from plugin config or hostname fallback)
+ *
+ * Base URL:
+ *   Derived from plugin config: backendUrl + "/calendar"
+ *   Default backendUrl: "https://monitor.hangman-lab.top"
+ *
+ * Endpoints used:
+ *   POST /calendar/agent/heartbeat        — fetch pending slots
+ *   PATCH /calendar/slots/{id}/agent-update   — update real slot status
+ *   PATCH /calendar/slots/virtual/{vid}/agent-update — update virtual slot status
+ *
+ * References:
+ *   • NEXT_WAVE_DEV_DIRECTION.md §6.1 (Heartbeat flow)
+ *   • HarborForge.Backend/app/services/agent_heartbeat.py (BE-AGT-001)
+ */
+
+import {
+  CalendarHeartbeatRequest,
+  CalendarHeartbeatResponse,
+  CalendarSlotResponse,
+  SlotAgentUpdate,
+  SlotStatus,
+} from './types.js';
+
+export interface CalendarBridgeConfig {
+  /** HarborForge backend base URL (e.g. "https://monitor.hangman-lab.top") */
+  backendUrl: string;
+  /** Server/claw identifier (from plugin config or hostname fallback) */
+  clawIdentifier: string;
+  /** OpenClaw agent ID ($AGENT_ID), set at agent startup */
+  agentId: string;
+  /** HTTP request timeout in milliseconds (default: 5000) */
+  timeoutMs?: number;
+}
+
+export class CalendarBridgeClient {
+  private baseUrl: string;
+  private config: Required<CalendarBridgeConfig>;
+  private timeoutMs: number;
+
+  constructor(config: CalendarBridgeConfig) {
+    this.baseUrl = config.backendUrl.replace(/\/$/, ''); // strip trailing slash
+    this.config = {
+      timeoutMs: 5000,
+      ...config,
+    };
+    this.timeoutMs = this.config.timeoutMs;
+  }
+
+  /**
+   * Fetch today's pending calendar slots for this agent.
+   *
+   * Heartbeat flow (§6.1):
+   *  1. Plugin sends heartbeat every minute
+   *  2. Backend returns slots where status is NotStarted or Deferred
+   *     AND scheduled_at <= now
+   *  3. Plugin selects highest-priority slot (if any)
+   *  4. For remaining slots, plugin sets status = Deferred + priority += 1
+   *
+   * @returns CalendarHeartbeatResponse or null if the backend is unreachable
+   */
+  async heartbeat(): Promise<CalendarHeartbeatResponse | null> {
+    const url = `${this.baseUrl}/calendar/agent/heartbeat`;
+    const body: CalendarHeartbeatRequest = {
+      claw_identifier: this.config.clawIdentifier,
+      agent_id: this.config.agentId,
+    };
+
+    try {
+      const response = await this.fetchJson<CalendarHeartbeatResponse>(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Agent-ID': this.config.agentId,
+          'X-Claw-Identifier': this.config.clawIdentifier,
+        },
+        body: JSON.stringify(body),
+      });
+      return response;
+    } catch (err) {
+      // Non-fatal: backend unreachable — return null, plugin continues
+      return null;
+    }
+  }
+
+  /**
+   * Update a real (materialized) slot's status after agent execution.
+   *
+   * Used by the plugin to report:
+   *   - Slot attended (attended=true, started_at=now, status=Ongoing)
+   *   - Slot finished (actual_duration set, status=Finished)
+   *   - Slot deferred (status=Deferred, priority += 1)
+   *   - Slot aborted (status=Aborted)
+   *
+   * @param slotId  Real slot DB id
+   * @param update  Status update payload
+   * @returns true on success, false on failure
+   */
+  async updateSlot(slotId: number, update: SlotAgentUpdate): Promise<boolean> {
+    const url = `${this.baseUrl}/calendar/slots/${slotId}/agent-update`;
+    return this.sendBoolean('PATCH', url, update);
+  }
+
+  /**
+   * Update a virtual (plan-generated) slot's status after agent execution.
+   *
+   * When updating a virtual slot, the backend first materializes it
+   * (creates a real TimeSlot row), then applies the update.
+   * The returned slot will have a real id on subsequent calls.
+   *
+   * @param virtualId  Virtual slot id in format "plan-{plan_id}-{date}"
+   * @param update     Status update payload
+   * @returns Updated CalendarSlotResponse on success, null on failure
+   */
+  async updateVirtualSlot(
+    virtualId: string,
+    update: SlotAgentUpdate
+  ): Promise<CalendarSlotResponse | null> {
+    const url = `${this.baseUrl}/calendar/slots/virtual/${encodeURIComponent(virtualId)}/agent-update`;
+    try {
+      const response = await this.fetchJson<{ slot: CalendarSlotResponse }>(url, {
+        method: 'PATCH',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Agent-ID': this.config.agentId,
+          'X-Claw-Identifier': this.config.clawIdentifier,
+        },
+        body: JSON.stringify(update),
+      });
+      return response?.slot ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Report the agent's current runtime status to HarborForge.
+   *
+   * Used to push agent status transitions:
+   *   idle → busy / on_call  (when starting a slot)
+   *   busy / on_call → idle  (when finishing a slot)
+   *   → exhausted (on rate-limit / billing error, with recovery_at)
+   *   → offline (after 2 min with no heartbeat)
+   *
+   * @param status  New agent status
+   * @param recoveryAt  ISO timestamp for expected Exhausted recovery (optional)
+   * @param exhaustReason "rate_limit" | "billing" (required if status=exhausted)
+   */
+  async reportAgentStatus(params: {
+    status: 'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline';
+    recoveryAt?: string;
+    exhaustReason?: 'rate_limit' | 'billing';
+  }): Promise<boolean> {
+    const url = `${this.baseUrl}/calendar/agent/status`;
+    const body = {
+      agent_id: this.config.agentId,
+      claw_identifier: this.config.clawIdentifier,
+      ...params,
+    };
+    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
+  // -------------------------------------------------------------------------
+
+  private async fetchJson<T>(
+    url: string,
+    init: RequestInit
+  ): Promise<T | null> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const response = await fetch(url, {
+        ...init,
+        signal: controller.signal,
+      });
+      clearTimeout(timeout);
+
+      if (!response.ok) return null;
+      return (await response.json()) as T;
+    } catch {
+      clearTimeout(timeout);
+      return null;
+    }
+  }
+
+  private async sendBoolean(method: 'POST' | 'PATCH', url: string, body: unknown): Promise<boolean> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Agent-ID': this.config.agentId,
+          'X-Claw-Identifier': this.config.clawIdentifier,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      clearTimeout(timeout);
+      return response.ok;
+    } catch {
+      clearTimeout(timeout);
+      return false;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Utility: build CalendarBridgeConfig from plugin API context
+// ---------------------------------------------------------------------------
+
+import { hostname } from 'os';
+import { getPluginConfig } from '../core/config.js';
+
+export interface CalendarPluginConfig {
+  /** Backend URL for calendar API (overrides monitor backendUrl) */
+  calendarBackendUrl?: string;
+  /** Server identifier (overrides auto-detected hostname) */
+  identifier?: string;
+  /** Agent ID from OpenClaw ($AGENT_ID) */
+  agentId: string;
+  /** HTTP timeout for calendar API calls (default: 5000) */
+  timeoutMs?: number;
+}
+
+/**
+ * Build a CalendarBridgeClient from the OpenClaw plugin API context.
+ *
+ * @param api           OpenClaw plugin API (register() receives this)
+ * @param fallbackUrl   Fallback backend URL if not configured
+ * @param agentId       $AGENT_ID from OpenClaw environment
+ */
+export function createCalendarBridgeClient(
+  api: { config?: Record<string, unknown>; logger?: { debug?: (...args: unknown[]) => void } },
+  fallbackUrl: string,
+  agentId: string
+): CalendarBridgeClient {
+  const baseConfig = getPluginConfig(api as any);
+
+  const clawIdentifier = baseConfig.identifier || hostname();
+
+  return new CalendarBridgeClient({
+    backendUrl: baseConfig.backendUrl || fallbackUrl,
+    clawIdentifier,
+    agentId,
+    timeoutMs: 5000,
+  });
+}
--- a/plugin/calendar/index.ts
+++ b/plugin/calendar/index.ts
@@ -0,0 +1,34 @@
+/**
+ * HarborForge Calendar — Plugin Module
+ *
+ * PLG-CAL-001: Calendar heartbeat request/response format definition.
+ * PLG-CAL-002: Plugin-side slot execution scheduler and agent wakeup.
+ *
+ * Exports:
+ *   • Types for heartbeat request/response and slot update
+ *   • CalendarBridgeClient — HTTP client for backend communication
+ *   • createCalendarBridgeClient — factory from plugin API context
+ *   • CalendarScheduler — manages periodic heartbeat and slot execution
+ *   • createCalendarScheduler — factory for scheduler
+ *   • AgentWakeContext — context passed to agent when waking
+ *
+ * Usage in plugin/index.ts:
+ *   import { createCalendarBridgeClient, createCalendarScheduler } from './calendar.js';
+ *
+ *   const agentId = process.env.AGENT_ID || 'unknown';
+ *   const calendar = createCalendarBridgeClient(api, 'https://monitor.hangman-lab.top', agentId);
+ *
+ *   const scheduler = createCalendarScheduler({
+ *     bridge: calendar,
+ *     getAgentStatus: async () => { ... },
+ *     wakeAgent: async (context) => { ... },
+ *     logger: api.logger,
+ *   });
+ *
+ *   scheduler.start();
+ */
+
+export * from './types.js';
+export * from './calendar-bridge.js';
+export * from './scheduler.js';
+export * from './schedule-cache.js';
--- a/plugin/calendar/schedule-cache.ts
+++ b/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;
+  }
+}
--- a/plugin/calendar/scheduler.ts
+++ b/plugin/calendar/scheduler.ts
@@ -0,0 +1,953 @@
+/**
+ * HarborForge Calendar Scheduler
+ *
+ * PLG-CAL-002: Plugin-side handling for pending slot execution.
+ * PLG-CAL-004: ScheduledGatewayRestart event handling with state persistence.
+ *
+ * Responsibilities:
+ *   - Run calendar heartbeat every minute
+ *   - Detect when agent is Idle and slots are pending
+ *   - Wake agent with task context
+ *   - Handle slot status transitions (attended, ongoing, deferred)
+ *   - Manage agent status transitions (idle → busy/on_call)
+ *   - Persist state on ScheduledGatewayRestart and restore on startup
+ *   - Send final heartbeat before graceful shutdown
+ *
+ * Design reference: NEXT_WAVE_DEV_DIRECTION.md §6 (Agent wakeup mechanism)
+ */
+
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { CalendarBridgeClient } from './calendar-bridge.js';
+import {
+  CalendarSlotResponse,
+  SlotStatus,
+  AgentStatusValue,
+  SlotAgentUpdate,
+  CalendarEventDataJob,
+  CalendarEventDataSystemEvent,
+} from './types.js';
+
+export interface CalendarSchedulerConfig {
+  /** Calendar bridge client for backend communication */
+  bridge: CalendarBridgeClient;
+  /** Function to get current agent status from backend */
+  getAgentStatus: () => Promise<AgentStatusValue | null>;
+  /** Function to wake/spawn agent with task context */
+  wakeAgent: (context: AgentWakeContext) => Promise<boolean>;
+  /** Logger instance */
+  logger: {
+    info: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+    debug: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+  };
+  /** Heartbeat interval in milliseconds (default: 60000) */
+  heartbeatIntervalMs?: number;
+  /** Enable verbose debug logging */
+  debug?: boolean;
+  /** Directory for state persistence (default: plugin data dir) */
+  stateDir?: string;
+}
+
+/**
+ * Context passed to agent when waking for slot execution.
+ * This is the payload the agent receives to understand what to do.
+ */
+export interface AgentWakeContext {
+  /** The slot to execute */
+  slot: CalendarSlotResponse;
+  /** Human-readable task description */
+  taskDescription: string;
+  /** Prompt/instructions for the agent */
+  prompt: string;
+  /** Whether this is a virtual slot (needs materialization) */
+  isVirtual: boolean;
+}
+
+/**
+ * Persisted state structure for recovery after restart.
+ */
+interface PersistedState {
+  /** Version for migration compatibility */
+  version: number;
+  /** When the state was persisted */
+  persistedAt: string;
+  /** Reason for persistence (e.g., 'ScheduledGatewayRestart') */
+  reason: string;
+  /** The slot that was being executed when persisted */
+  currentSlot: CalendarSlotResponse | null;
+  /** Deferred slot IDs at persistence time */
+  deferredSlotIds: string[];
+  /** Whether a slot was in progress */
+  isProcessing: boolean;
+  /** Agent status at persistence time */
+  agentStatus: AgentStatusValue | null;
+}
+
+/**
+ * Current execution state tracked by the scheduler.
+ */
+interface SchedulerState {
+  /** Whether scheduler is currently running */
+  isRunning: boolean;
+  /** Currently executing slot (null if idle) */
+  currentSlot: CalendarSlotResponse | null;
+  /** Last heartbeat timestamp */
+  lastHeartbeatAt: Date | null;
+  /** Interval handle for cleanup */
+  intervalHandle: 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 */
+  isProcessing: boolean;
+  /** Whether a gateway restart is scheduled/pending */
+  isRestartPending: boolean;
+}
+
+/** State file name */
+const STATE_FILENAME = 'calendar-scheduler-state.json';
+/** State file version for migration compatibility */
+const STATE_VERSION = 1;
+
+/**
+ * CalendarScheduler manages the periodic heartbeat and slot execution lifecycle.
+ */
+export class CalendarScheduler {
+  private config: Required<CalendarSchedulerConfig>;
+  private state: SchedulerState;
+  private stateFilePath: string;
+
+  constructor(config: CalendarSchedulerConfig) {
+    this.config = {
+      heartbeatIntervalMs: 60000, // 1 minute default
+      debug: false,
+      stateDir: this.getDefaultStateDir(),
+      ...config,
+    };
+
+    this.stateFilePath = join(this.config.stateDir, STATE_FILENAME);
+
+    this.state = {
+      isRunning: false,
+      currentSlot: null,
+      lastHeartbeatAt: null,
+      intervalHandle: null,
+      deferredSlotIds: new Set(),
+      isProcessing: false,
+      isRestartPending: false,
+    };
+
+    // Attempt to restore state from previous persistence
+    this.restoreState();
+  }
+
+  /**
+   * Get default state directory (plugin data directory or temp fallback).
+   */
+  private getDefaultStateDir(): string {
+    // Try to use the plugin's directory or a standard data location
+    const candidates = [
+      process.env.OPENCLAW_PLUGIN_DATA_DIR,
+      process.env.HARBORFORGE_PLUGIN_DIR,
+      join(process.cwd(), '.harborforge'),
+      join(process.cwd(), 'data'),
+      '/tmp/harborforge',
+    ];
+
+    for (const dir of candidates) {
+      if (dir) {
+        try {
+          if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+          }
+          // Test write access
+          const testFile = join(dir, '.write-test');
+          writeFileSync(testFile, '', { flag: 'w' });
+          return dir;
+        } catch {
+          continue;
+        }
+      }
+    }
+
+    // Fallback to current working directory
+    return process.cwd();
+  }
+
+  /**
+   * Persist current state to disk for recovery after restart.
+   */
+  private persistState(reason: string): void {
+    try {
+      const persistedState: PersistedState = {
+        version: STATE_VERSION,
+        persistedAt: new Date().toISOString(),
+        reason,
+        currentSlot: this.state.currentSlot,
+        deferredSlotIds: Array.from(this.state.deferredSlotIds),
+        isProcessing: this.state.isProcessing,
+        agentStatus: null, // Will be determined at restore time
+      };
+
+      writeFileSync(this.stateFilePath, JSON.stringify(persistedState, null, 2));
+      this.config.logger.info(`[PLG-CAL-004] State persisted to ${this.stateFilePath} (reason: ${reason})`);
+    } catch (err) {
+      this.config.logger.error('[PLG-CAL-004] Failed to persist state:', err);
+    }
+  }
+
+  /**
+   * Restore state from disk if available.
+   */
+  private restoreState(): void {
+    try {
+      if (!existsSync(this.stateFilePath)) {
+        return;
+      }
+
+      const data = readFileSync(this.stateFilePath, 'utf-8');
+      const persisted: PersistedState = JSON.parse(data);
+
+      // Validate version
+      if (persisted.version !== STATE_VERSION) {
+        this.config.logger.warn(`[PLG-CAL-004] State version mismatch: ${persisted.version} vs ${STATE_VERSION}`);
+        this.clearPersistedState();
+        return;
+      }
+
+      // Restore deferred slot IDs
+      if (persisted.deferredSlotIds && persisted.deferredSlotIds.length > 0) {
+        this.state.deferredSlotIds = new Set(persisted.deferredSlotIds);
+        this.config.logger.info(`[PLG-CAL-004] Restored ${persisted.deferredSlotIds.length} deferred slot(s)`);
+      }
+
+      // If there was a slot in progress, mark it for replanning
+      if (persisted.isProcessing && persisted.currentSlot) {
+        this.config.logger.warn(
+          `[PLG-CAL-004] Previous session had in-progress slot: ${this.getSlotId(persisted.currentSlot)}`
+        );
+        // The slot will be picked up by the next heartbeat and can be resumed or deferred
+      }
+
+      this.config.logger.info(`[PLG-CAL-004] State restored from ${persisted.persistedAt} (reason: ${persisted.reason})`);
+
+      // Clear the persisted state after successful restore
+      this.clearPersistedState();
+    } catch (err) {
+      this.config.logger.error('[PLG-CAL-004] Failed to restore state:', err);
+    }
+  }
+
+  /**
+   * Clear persisted state file after successful restore.
+   */
+  private clearPersistedState(): void {
+    try {
+      if (existsSync(this.stateFilePath)) {
+        // In a real implementation, we might want to archive instead of delete
+        // For now, we'll just clear the content to mark as processed
+        writeFileSync(this.stateFilePath, JSON.stringify({ restored: true, at: new Date().toISOString() }));
+      }
+    } catch (err) {
+      this.config.logger.error('[PLG-CAL-004] Failed to clear persisted state:', err);
+    }
+  }
+
+  /**
+   * Send a final heartbeat to the backend before shutdown.
+   */
+  private async sendFinalHeartbeat(reason: string): Promise<void> {
+    try {
+      this.config.logger.info(`[PLG-CAL-004] Sending final heartbeat (reason: ${reason})`);
+
+      // Send agent status update indicating we're going offline
+      await this.config.bridge.reportAgentStatus({ status: 'offline' });
+
+      this.config.logger.info('[PLG-CAL-004] Final heartbeat sent successfully');
+    } catch (err) {
+      this.config.logger.error('[PLG-CAL-004] Failed to send final heartbeat:', err);
+    }
+  }
+
+  /**
+   * Handle ScheduledGatewayRestart event.
+   * PLG-CAL-004: Persist state, send final heartbeat, pause scheduled tasks.
+   */
+  private async handleScheduledGatewayRestart(slot: CalendarSlotResponse): Promise<void> {
+    this.config.logger.info('[PLG-CAL-004] Handling ScheduledGatewayRestart event');
+
+    // 1. Mark restart as pending to prevent new slot processing
+    this.state.isRestartPending = true;
+
+    // 2. Persist current state
+    this.persistState('ScheduledGatewayRestart');
+
+    // 3. If there's a current slot, pause it gracefully
+    if (this.state.isProcessing && this.state.currentSlot) {
+      this.config.logger.info('[PLG-CAL-004] Pausing current slot before restart');
+      await this.pauseCurrentSlot();
+    }
+
+    // 4. Send final heartbeat
+    await this.sendFinalHeartbeat('ScheduledGatewayRestart');
+
+    // 5. Stop the scheduler (pause scheduled tasks)
+    this.config.logger.info('[PLG-CAL-004] Stopping scheduler due to gateway restart');
+    this.stop();
+
+    // 6. Mark the slot as finished (since we've handled the restart)
+    const update: SlotAgentUpdate = {
+      status: SlotStatus.FINISHED,
+      actual_duration: 0, // Restart preparation doesn't take time
+    };
+
+    try {
+      if (slot.id) {
+        await this.config.bridge.updateSlot(slot.id, update);
+      } else if (slot.virtual_id) {
+        await this.config.bridge.updateVirtualSlot(slot.virtual_id, update);
+      }
+    } catch (err) {
+      this.config.logger.error('[PLG-CAL-004] Failed to mark restart slot as finished:', err);
+    }
+  }
+
+  /**
+   * Start the calendar scheduler.
+   * Begins periodic heartbeat to check for pending slots.
+   */
+  start(): void {
+    if (this.state.isRunning) {
+      this.config.logger.warn('Calendar scheduler already running');
+      return;
+    }
+
+    this.state.isRunning = true;
+    this.state.isRestartPending = false;
+    this.config.logger.info('Calendar scheduler started');
+
+    // Run initial heartbeat immediately
+    this.runHeartbeat();
+
+    // Schedule periodic heartbeats
+    this.state.intervalHandle = setInterval(
+      () => this.runHeartbeat(),
+      this.config.heartbeatIntervalMs
+    );
+  }
+
+  /**
+   * Stop the calendar scheduler.
+   * Cleans up intervals and resets state.
+   */
+  stop(): void {
+    this.state.isRunning = false;
+
+    if (this.state.intervalHandle) {
+      clearInterval(this.state.intervalHandle);
+      this.state.intervalHandle = null;
+    }
+
+    this.config.logger.info('Calendar scheduler stopped');
+  }
+
+  /**
+   * Execute a single heartbeat cycle.
+   * Fetches pending slots and handles execution logic.
+   */
+  async runHeartbeat(): Promise<void> {
+    if (!this.state.isRunning) {
+      return;
+    }
+
+    // Skip heartbeat if restart is pending
+    if (this.state.isRestartPending) {
+      this.logDebug('Heartbeat skipped: gateway restart pending');
+      return;
+    }
+
+    this.state.lastHeartbeatAt = new Date();
+
+    try {
+      // Fetch pending slots from backend
+      const response = await this.config.bridge.heartbeat();
+
+      if (!response) {
+        this.logDebug('Heartbeat: backend unreachable');
+        return;
+      }
+
+      this.logDebug(
+        `Heartbeat: ${response.slots.length} slots pending, agent_status=${response.agent_status}`
+      );
+
+      // If agent is not idle, defer all pending slots
+      if (response.agent_status !== 'idle') {
+        await this.handleNonIdleAgent(response.slots, response.agent_status);
+        return;
+      }
+
+      // Agent is idle again - previously deferred slots should become eligible
+      // for selection in the next planning pass.
+      if (this.state.deferredSlotIds.size > 0) {
+        this.logDebug(
+          `Agent returned to idle; clearing ${this.state.deferredSlotIds.size} deferred slot marker(s) for replanning`
+        );
+        this.state.deferredSlotIds.clear();
+      }
+
+      // Agent is idle - handle pending slots
+      await this.handleIdleAgent(response.slots);
+    } catch (err) {
+      this.config.logger.error('Heartbeat error:', err);
+    }
+  }
+
+  /**
+   * Handle slots when agent is not idle.
+   * Defer all pending slots with priority boost.
+   */
+  private async handleNonIdleAgent(
+    slots: CalendarSlotResponse[],
+    agentStatus: AgentStatusValue
+  ): Promise<void> {
+    if (slots.length === 0) {
+      return;
+    }
+
+    this.config.logger.info(
+      `Agent not idle (status=${agentStatus}), deferring ${slots.length} slot(s)`
+    );
+
+    for (const slot of slots) {
+      const slotId = this.getSlotId(slot);
+
+      // Skip if already deferred this session
+      if (this.state.deferredSlotIds.has(slotId)) {
+        continue;
+      }
+
+      // Mark slot as deferred with priority boost (+1)
+      await this.deferSlot(slot);
+      this.state.deferredSlotIds.add(slotId);
+    }
+  }
+
+  /**
+   * Handle slots when agent is idle.
+   * Select highest priority slot and wake agent.
+   */
+  private async handleIdleAgent(slots: CalendarSlotResponse[]): Promise<void> {
+    if (slots.length === 0) {
+      return;
+    }
+
+    // Filter out already deferred slots in this session
+    const eligibleSlots = slots.filter(
+      (s) => !this.state.deferredSlotIds.has(this.getSlotId(s))
+    );
+
+    if (eligibleSlots.length === 0) {
+      this.logDebug('All pending slots have been deferred this session');
+      return;
+    }
+
+    // Select highest priority slot (backend already sorts by priority DESC)
+    const [selectedSlot, ...remainingSlots] = eligibleSlots;
+
+    this.config.logger.info(
+      `Selected slot for execution: id=${this.getSlotId(selectedSlot)}, ` +
+        `type=${selectedSlot.slot_type}, priority=${selectedSlot.priority}`
+    );
+
+    // Mark remaining slots as deferred
+    for (const slot of remainingSlots) {
+      await this.deferSlot(slot);
+      this.state.deferredSlotIds.add(this.getSlotId(slot));
+    }
+
+    // Check if this is a ScheduledGatewayRestart event
+    if (this.isScheduledGatewayRestart(selectedSlot)) {
+      await this.handleScheduledGatewayRestart(selectedSlot);
+      return;
+    }
+
+    // Wake agent to execute selected slot
+    await this.executeSlot(selectedSlot);
+  }
+
+  /**
+   * Check if a slot is a ScheduledGatewayRestart system event.
+   */
+  private isScheduledGatewayRestart(slot: CalendarSlotResponse): boolean {
+    if (slot.event_type !== 'system_event' || !slot.event_data) {
+      return false;
+    }
+    const sysData = slot.event_data as CalendarEventDataSystemEvent;
+    return sysData.event === 'ScheduledGatewayRestart';
+  }
+
+  /**
+   * Execute a slot by waking the agent.
+   */
+  private async executeSlot(slot: CalendarSlotResponse): Promise<void> {
+    if (this.state.isProcessing) {
+      this.config.logger.warn('Already processing a slot, deferring new slot');
+      await this.deferSlot(slot);
+      return;
+    }
+
+    this.state.isProcessing = true;
+    this.state.currentSlot = slot;
+
+    try {
+      // Mark slot as attended and ongoing before waking agent
+      const update: SlotAgentUpdate = {
+        status: SlotStatus.ONGOING,
+        started_at: this.formatTime(new Date()),
+      };
+
+      let updateSuccess: boolean;
+      if (slot.id) {
+        updateSuccess = await this.config.bridge.updateSlot(slot.id, update);
+      } else if (slot.virtual_id) {
+        const updated = await this.config.bridge.updateVirtualSlot(slot.virtual_id, update);
+        updateSuccess = updated !== null;
+        // Update slot reference if materialized
+        if (updated) {
+          this.state.currentSlot = updated;
+        }
+      } else {
+        updateSuccess = false;
+      }
+
+      if (!updateSuccess) {
+        this.config.logger.error('Failed to update slot status before execution');
+        this.state.isProcessing = false;
+        this.state.currentSlot = null;
+        return;
+      }
+
+      // Report agent status change to backend
+      const newAgentStatus = slot.slot_type === 'on_call' ? 'on_call' : 'busy';
+      await this.config.bridge.reportAgentStatus({ status: newAgentStatus });
+
+      // Build wake context for agent
+      const wakeContext = this.buildWakeContext(slot);
+
+      // Wake the agent
+      const wakeSuccess = await this.config.wakeAgent(wakeContext);
+
+      if (!wakeSuccess) {
+        this.config.logger.error('Failed to wake agent for slot execution');
+        // Revert slot to not_started status
+        await this.revertSlot(slot);
+        await this.config.bridge.reportAgentStatus({ status: 'idle' });
+        this.state.isProcessing = false;
+        this.state.currentSlot = null;
+        await this.triggerReplan('wake failure');
+        return;
+      }
+
+      // Note: isProcessing remains true until agent signals completion
+      // This is handled by external completion callback
+    } catch (err) {
+      this.config.logger.error('Error executing slot:', err);
+      this.state.isProcessing = false;
+      this.state.currentSlot = null;
+    }
+  }
+
+  /**
+   * Build the wake context for an agent based on slot details.
+   */
+  private buildWakeContext(slot: CalendarSlotResponse): AgentWakeContext {
+    const isVirtual = slot.virtual_id !== null;
+    const slotId = this.getSlotId(slot);
+
+    // Build task description based on event type
+    let taskDescription: string;
+    let prompt: string;
+
+    if (slot.event_type === 'job' && slot.event_data) {
+      const jobData = slot.event_data as CalendarEventDataJob;
+      taskDescription = `${jobData.type} ${jobData.code}`;
+      prompt = this.buildJobPrompt(slot, jobData);
+    } else if (slot.event_type === 'system_event' && slot.event_data) {
+      const sysData = slot.event_data as CalendarEventDataSystemEvent;
+      taskDescription = `System Event: ${sysData.event}`;
+      prompt = this.buildSystemPrompt(slot, sysData);
+    } else if (slot.event_type === 'entertainment') {
+      taskDescription = 'Entertainment slot';
+      prompt = this.buildEntertainmentPrompt(slot);
+    } else {
+      taskDescription = `Generic ${slot.slot_type} slot`;
+      prompt = this.buildGenericPrompt(slot);
+    }
+
+    return {
+      slot,
+      taskDescription,
+      prompt,
+      isVirtual,
+    };
+  }
+
+  /**
+   * Build prompt for job-type slots.
+   */
+  private buildJobPrompt(
+    slot: CalendarSlotResponse,
+    jobData: CalendarEventDataJob
+  ): string {
+    const duration = slot.estimated_duration;
+    const type = jobData.type;
+    const code = jobData.code;
+
+    return `You have a scheduled ${type} job to work on.
+
+Task Code: ${code}
+Estimated Duration: ${duration} minutes
+Slot Type: ${slot.slot_type}
+Priority: ${slot.priority}
+
+Please focus on this task for the allocated time. When you finish or need to pause,
+report your progress back to the calendar system.
+
+Working sessions: ${jobData.working_sessions?.join(', ') || 'none recorded'}
+
+Start working on ${code} now.`;
+  }
+
+  /**
+   * Build prompt for system event slots.
+   */
+  private buildSystemPrompt(
+    slot: CalendarSlotResponse,
+    sysData: CalendarEventDataSystemEvent
+  ): string {
+    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.`;
+
+      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.`;
+
+      case 'ScheduledGatewayRestart':
+        return `System Event: Scheduled Gateway Restart
+
+The OpenClaw gateway is scheduled to restart soon.
+Please:
+1. Persist any important state
+2. Complete or gracefully pause current tasks
+3. Prepare for restart
+
+Time remaining: ${slot.estimated_duration} minutes.`;
+
+      default:
+        return `System Event: ${sysData.event}
+
+A system event has been scheduled. Please handle accordingly.
+Estimated time: ${slot.estimated_duration} minutes.`;
+    }
+  }
+
+  /**
+   * Build prompt for entertainment slots.
+   */
+  private buildEntertainmentPrompt(slot: CalendarSlotResponse): string {
+    return `Scheduled Entertainment Break
+
+Duration: ${slot.estimated_duration} minutes
+
+Take a break and enjoy some leisure time. This slot is reserved for non-work activities
+ to help maintain work-life balance.`;
+  }
+
+  /**
+   * Build generic prompt for slots without specific event data.
+   */
+  private buildGenericPrompt(slot: CalendarSlotResponse): string {
+    return `Scheduled Calendar Slot
+
+Type: ${slot.slot_type}
+Duration: ${slot.estimated_duration} minutes
+Priority: ${slot.priority}
+
+Please use this time for the scheduled activity.`;
+  }
+
+  /**
+   * Mark a slot as deferred with priority boost.
+   */
+  private async deferSlot(slot: CalendarSlotResponse): Promise<void> {
+    const update: SlotAgentUpdate = {
+      status: SlotStatus.DEFERRED,
+    };
+
+    try {
+      if (slot.id) {
+        await this.config.bridge.updateSlot(slot.id, update);
+      } else if (slot.virtual_id) {
+        await this.config.bridge.updateVirtualSlot(slot.virtual_id, update);
+      }
+      this.logDebug(`Deferred slot: ${this.getSlotId(slot)}`);
+    } catch (err) {
+      this.config.logger.error('Failed to defer slot:', err);
+    }
+  }
+
+  /**
+   * Revert a slot to not_started status after failed execution attempt.
+   */
+  private async revertSlot(slot: CalendarSlotResponse): Promise<void> {
+    const update: SlotAgentUpdate = {
+      status: SlotStatus.NOT_STARTED,
+      started_at: undefined,
+    };
+
+    try {
+      if (slot.id) {
+        await this.config.bridge.updateSlot(slot.id, update);
+      } else if (slot.virtual_id) {
+        await this.config.bridge.updateVirtualSlot(slot.virtual_id, update);
+      }
+    } catch (err) {
+      this.config.logger.error('Failed to revert slot:', err);
+    }
+  }
+
+  /**
+   * Complete the current slot execution.
+   * Call this when the agent finishes the task.
+   */
+  async completeCurrentSlot(actualDurationMinutes: number): Promise<void> {
+    if (!this.state.currentSlot) {
+      this.config.logger.warn('No current slot to complete');
+      return;
+    }
+
+    const slot = this.state.currentSlot;
+    const update: SlotAgentUpdate = {
+      status: SlotStatus.FINISHED,
+      actual_duration: actualDurationMinutes,
+    };
+
+    try {
+      if (slot.id) {
+        await this.config.bridge.updateSlot(slot.id, update);
+      } else if (slot.virtual_id) {
+        await this.config.bridge.updateVirtualSlot(slot.virtual_id, update);
+      }
+
+      // Report agent back to idle
+      await this.config.bridge.reportAgentStatus({ status: 'idle' });
+
+      this.config.logger.info(
+        `Completed slot ${this.getSlotId(slot)}, actual_duration=${actualDurationMinutes}min`
+      );
+    } catch (err) {
+      this.config.logger.error('Failed to complete slot:', err);
+    } finally {
+      this.state.isProcessing = false;
+      this.state.currentSlot = null;
+      await this.triggerReplan('slot completion');
+    }
+  }
+
+  /**
+   * Abort the current slot execution.
+   * Call this when the agent cannot complete the task.
+   */
+  async abortCurrentSlot(reason?: string): Promise<void> {
+    if (!this.state.currentSlot) {
+      this.config.logger.warn('No current slot to abort');
+      return;
+    }
+
+    const slot = this.state.currentSlot;
+    const update: SlotAgentUpdate = {
+      status: SlotStatus.ABORTED,
+    };
+
+    try {
+      if (slot.id) {
+        await this.config.bridge.updateSlot(slot.id, update);
+      } else if (slot.virtual_id) {
+        await this.config.bridge.updateVirtualSlot(slot.virtual_id, update);
+      }
+
+      // Report agent back to idle
+      await this.config.bridge.reportAgentStatus({ status: 'idle' });
+
+      this.config.logger.info(
+        `Aborted slot ${this.getSlotId(slot)}${reason ? `: ${reason}` : ''}`
+      );
+    } catch (err) {
+      this.config.logger.error('Failed to abort slot:', err);
+    } finally {
+      this.state.isProcessing = false;
+      this.state.currentSlot = null;
+      await this.triggerReplan('slot abort');
+    }
+  }
+
+  /**
+   * Pause the current slot execution.
+   * Call this when the agent needs to temporarily pause.
+   */
+  async pauseCurrentSlot(): Promise<void> {
+    if (!this.state.currentSlot) {
+      this.config.logger.warn('No current slot to pause');
+      return;
+    }
+
+    const slot = this.state.currentSlot;
+    const update: SlotAgentUpdate = {
+      status: SlotStatus.PAUSED,
+    };
+
+    try {
+      if (slot.id) {
+        await this.config.bridge.updateSlot(slot.id, update);
+      } else if (slot.virtual_id) {
+        await this.config.bridge.updateVirtualSlot(slot.virtual_id, update);
+      }
+
+      this.config.logger.info(`Paused slot ${this.getSlotId(slot)}`);
+    } catch (err) {
+      this.config.logger.error('Failed to pause slot:', err);
+    }
+  }
+
+  /**
+   * Resume a paused slot.
+   */
+  async resumeCurrentSlot(): Promise<void> {
+    if (!this.state.currentSlot) {
+      this.config.logger.warn('No current slot to resume');
+      return;
+    }
+
+    const slot = this.state.currentSlot;
+    const update: SlotAgentUpdate = {
+      status: SlotStatus.ONGOING,
+    };
+
+    try {
+      if (slot.id) {
+        await this.config.bridge.updateSlot(slot.id, update);
+      } else if (slot.virtual_id) {
+        await this.config.bridge.updateVirtualSlot(slot.virtual_id, update);
+      }
+
+      this.config.logger.info(`Resumed slot ${this.getSlotId(slot)}`);
+    } catch (err) {
+      this.config.logger.error('Failed to resume slot:', err);
+    }
+  }
+
+  /**
+   * Trigger an immediate replanning pass after the current slot lifecycle ends.
+   * This lets previously deferred/not-started slots compete again as soon as
+   * the agent becomes idle.
+   */
+  private async triggerReplan(reason: string): Promise<void> {
+    if (!this.state.isRunning) {
+      return;
+    }
+
+    this.logDebug(`Triggering immediate replanning after ${reason}`);
+
+    try {
+      await this.runHeartbeat();
+    } catch (err) {
+      this.config.logger.error(`Failed to trigger replanning after ${reason}:`, err);
+    }
+  }
+
+  /**
+   * Get a stable ID for a slot (real or virtual).
+   */
+  private getSlotId(slot: CalendarSlotResponse): string {
+    return slot.id?.toString() || slot.virtual_id || 'unknown';
+  }
+
+  /**
+   * Format a Date as ISO time string (HH:MM:SS).
+   */
+  private formatTime(date: Date): string {
+    return date.toTimeString().split(' ')[0];
+  }
+
+  /**
+   * Debug logging helper.
+   */
+  private logDebug(message: string): void {
+    if (this.config.debug) {
+      this.config.logger.debug(`[CalendarScheduler] ${message}`);
+    }
+  }
+
+  /**
+   * Get current scheduler state (for introspection).
+   */
+  getState(): Readonly<SchedulerState> {
+    return { ...this.state };
+  }
+
+  /**
+   * Check if scheduler is running.
+   */
+  isRunning(): boolean {
+    return this.state.isRunning;
+  }
+
+  /**
+   * Check if currently processing a slot.
+   */
+  isProcessing(): boolean {
+    return this.state.isProcessing;
+  }
+
+  /**
+   * Get the current slot being executed (if any).
+   */
+  getCurrentSlot(): CalendarSlotResponse | null {
+    return this.state.currentSlot;
+  }
+
+  /**
+   * Check if a gateway restart is pending.
+   */
+  isRestartPending(): boolean {
+    return this.state.isRestartPending;
+  }
+
+  /**
+   * Get the path to the state file.
+   */
+  getStateFilePath(): string {
+    return this.stateFilePath;
+  }
+}
+
+/**
+ * Factory function to create a CalendarScheduler from plugin context.
+ */
+export function createCalendarScheduler(
+  config: CalendarSchedulerConfig
+): CalendarScheduler {
+  return new CalendarScheduler(config);
+}
--- a/plugin/calendar/types.ts
+++ b/plugin/calendar/types.ts
@@ -0,0 +1,198 @@
+/**
+ * HarborForge Calendar — Plugin-side type definitions
+ *
+ * PLG-CAL-001: Define the Calendar heartbeat request/response format
+ * between the OpenClaw plugin and HarborForge backend.
+ *
+ * Request flow (plugin → backend):
+ *   POST /calendar/agent/heartbeat
+ *   Headers:
+ *     X-Agent-ID: <agent_id>          — OpenClaw $AGENT_ID of the calling agent
+ *     X-Claw-Identifier: <identifier> — HarborForge server identifier
+ *   Body (JSON):
+ *     { "claw_identifier": "...", "agent_id": "..." }
+ *
+ * Response flow (backend → plugin):
+ *   Returns list of TimeSlots pending execution for today.
+ *   The plugin uses slot.id / slot.virtual_id to update slot status
+ *   via subsequent API calls.
+ *
+ * References:
+ *   • NEXT_WAVE_DEV_DIRECTION.md §6 (Agent wakeup mechanism)
+ *   • HarborForge.Backend/app/models/calendar.py  — TimeSlot DB model
+ *   • HarborForge.Backend/app/schemas/calendar.py — TimeSlot schemas
+ *   • HarborForge.Backend/app/services/agent_heartbeat.py — BE-AGT-001
+ */
+
+// ---------------------------------------------------------------------------
+// Enums (mirror backend enums)
+// ---------------------------------------------------------------------------
+
+/** Slot type — mirrors backend SlotType enum */
+export enum SlotType {
+  WORK = 'work',
+  ON_CALL = 'on_call',
+  ENTERTAINMENT = 'entertainment',
+  SYSTEM = 'system',
+}
+
+/** Slot lifecycle status — mirrors backend SlotStatus enum */
+export enum SlotStatus {
+  NOT_STARTED = 'not_started',
+  ONGOING = 'ongoing',
+  DEFERRED = 'deferred',
+  SKIPPED = 'skipped',
+  PAUSED = 'paused',
+  FINISHED = 'finished',
+  ABORTED = 'aborted',
+}
+
+/** High-level event category — mirrors backend EventType enum */
+export enum EventType {
+  JOB = 'job',
+  ENTERTAINMENT = 'entertainment',
+  SYSTEM_EVENT = 'system_event',
+}
+
+// ---------------------------------------------------------------------------
+// Request types
+// ---------------------------------------------------------------------------
+
+/**
+ * Calendar heartbeat request body sent by the plugin to HarborForge backend.
+ *
+ * How claw_identifier is determined:
+ *   1. Read from plugin config: `config.backendUrl` is the base URL.
+ *   2. If not set, fall back to `os.hostname()` (plugin machine hostname).
+ *
+ * How agent_id is determined:
+ *   - Read from OpenClaw environment variable: `process.env.AGENT_ID`
+ *   - This is set by OpenClaw at agent startup and uniquely identifies
+ *     the running agent instance within a single OpenClaw gateway.
+ */
+export interface CalendarHeartbeatRequest {
+  /** HarborForge server/claw identifier (matches MonitoredServer.identifier) */
+  claw_identifier: string;
+  /** OpenClaw agent ID ($AGENT_ID) for this agent session */
+  agent_id: string;
+}
+
+// ---------------------------------------------------------------------------
+// Response types
+// ---------------------------------------------------------------------------
+
+/**
+ * A single calendar slot returned in the heartbeat response.
+ *
+ * For **real** (materialized) slots: `id` is set, `virtual_id` is null.
+ * For **virtual** (plan-generated) slots: `id` is null, `virtual_id`
+ * is the `plan-{plan_id}-{date}` identifier.
+ *
+ * Key fields the plugin uses:
+ *   - `id` / `virtual_id`  — to update slot status after execution
+ *   - `event_type`          — to determine what action to take
+ *   - `event_data`          — job details / system event type
+ *   - `slot_type`           — work vs on_call (affects agent status transition)
+ *   - `scheduled_at`        — planned start time (HH:MM:SS)
+ *   - `estimated_duration`  — expected minutes (for time-tracking)
+ *   - `priority`            — for multi-slot competition logic
+ *   - `status`              — current status (NotStarted / Deferred)
+ */
+export interface CalendarSlotResponse {
+  /** Real slot DB id. Null for virtual slots. */
+  id: number | null;
+  /** Virtual slot id (plan-{plan_id}-{date}). Null for real slots. */
+  virtual_id: string | null;
+  /** Owner user id */
+  user_id: number;
+  /** Calendar date */
+  date: string; // ISO date string: "YYYY-MM-DD"
+  /** Slot type */
+  slot_type: SlotType;
+  /** Estimated duration in minutes (1-50) */
+  estimated_duration: number;
+  /** Planned start time (ISO time string: "HH:MM:SS") */
+  scheduled_at: string;
+  /** Actual start time, set when slot begins (null until started) */
+  started_at: string | null;
+  /** Whether the slot has been attended */
+  attended: boolean;
+  /** Actual duration in minutes (set when slot finishes) */
+  actual_duration: number | null;
+  /** Event category */
+  event_type: EventType | null;
+  /** Event details JSON — structure depends on event_type (see below) */
+  event_data: CalendarEventData | null;
+  /** Priority 0-99, higher = more urgent */
+  priority: number;
+  /** Current lifecycle status */
+  status: SlotStatus;
+  /** Source plan id if materialized from a SchedulePlan; null otherwise */
+  plan_id: number | null;
+}
+
+/**
+ * Event data stored inside CalendarSlotResponse.event_data.
+ * The shape depends on event_type.
+ *
+ * When event_type == "job":
+ *   { "type": "Task|Support|Meeting|Essential", "code": "TASK-42", "working_sessions": ["..."] }
+ *
+ * When event_type == "system_event":
+ *   { "event": "ScheduleToday|SummaryToday|ScheduledGatewayRestart" }
+ *
+ * When event_type == "entertainment":
+ *   { /* TBD /\ }
+ */
+export interface CalendarEventDataJob {
+  type: 'Task' | 'Support' | 'Meeting' | 'Essential';
+  code: string;
+  working_sessions?: string[];
+}
+
+export interface CalendarEventDataSystemEvent {
+  event: 'ScheduleToday' | 'SummaryToday' | 'ScheduledGatewayRestart';
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type CalendarEventData = CalendarEventDataJob | CalendarEventDataSystemEvent | Record<string, any>;
+
+/**
+ * Full heartbeat response returned by GET /calendar/agent/heartbeat
+ *
+ * Fields:
+ *   slots    — list of pending TimeSlots for today (sorted by priority desc)
+ *   agent_status — current agent status from the backend's perspective
+ *                  (idle | on_call | busy | exhausted | offline)
+ */
+export interface CalendarHeartbeatResponse {
+  /** Pending slots for today — sorted by priority descending */
+  slots: CalendarSlotResponse[];
+  /** Current agent status in HarborForge */
+  agent_status: AgentStatusValue;
+  /** Human-readable message (optional) */
+  message?: string;
+}
+
+/** Agent status values — mirrors backend AgentStatus enum */
+export type AgentStatusValue = 'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline';
+
+// ---------------------------------------------------------------------------
+// Slot update types (for post-execution status updates)
+// ---------------------------------------------------------------------------
+
+/**
+ * Request body for updating a real slot's status after agent execution.
+ * Called by the plugin after attending / finishing / deferring a slot.
+ *
+ * Endpoint: PATCH /calendar/slots/{slot_id}/agent-update
+ * (Plugin-facing variant that bypasses some user-level guards)
+ */
+export interface SlotAgentUpdate {
+  /** New status to set */
+  status: SlotStatus;
+  /** Actual start time (ISO time string HH:MM:SS), required when attending */
+  started_at?: string;
+  /** Actual duration in minutes, set when finishing */
+  actual_duration?: number;
+}
--- a/plugin/core/config.ts
+++ b/plugin/core/config.ts
@@ -0,0 +1,35 @@
+import { hostname } from 'os';
+
+export interface HarborForgePluginConfig {
+  enabled?: boolean;
+  backendUrl?: string;
+  identifier?: string;
+  apiKey?: string;
+  monitor_port?: number;
+  reportIntervalSec?: number;
+  httpFallbackIntervalSec?: number;
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+  calendarEnabled?: boolean;
+  calendarHeartbeatIntervalSec?: number;
+  calendarApiKey?: string;
+  managedMonitor?: string;
+}
+
+interface PluginApiLike {
+  pluginConfig?: Record<string, unknown>;
+}
+
+export function getPluginConfig(api: PluginApiLike): HarborForgePluginConfig {
+  const cfg = (api.pluginConfig || {}) as HarborForgePluginConfig;
+  return {
+    enabled: true,
+    backendUrl: 'https://monitor.hangman-lab.top',
+    identifier: hostname(),
+    reportIntervalSec: 30,
+    httpFallbackIntervalSec: 60,
+    logLevel: 'info',
+    calendarEnabled: true,
+    calendarHeartbeatIntervalSec: 60,
+    ...cfg,
+  };
+}
--- a/plugin/core/managed-monitor.ts
+++ b/plugin/core/managed-monitor.ts
@@ -0,0 +1,59 @@
+import { spawn, type ChildProcess } from 'child_process';
+import { existsSync } from 'fs';
+
+export interface ManagedMonitorConfig {
+  managedMonitor?: string;
+  backendUrl?: string;
+  identifier?: string;
+  apiKey?: string;
+  monitor_port?: number;
+  reportIntervalSec?: number;
+  logLevel?: string;
+}
+
+let monitorProcess: ChildProcess | null = null;
+
+export function startManagedMonitor(
+  logger: { info: (...args: any[]) => void; warn: (...args: any[]) => void; error: (...args: any[]) => void },
+  config: ManagedMonitorConfig,
+): void {
+  if (!config.managedMonitor) return;
+  if (monitorProcess) {
+    logger.info('HarborForge managed monitor already running');
+    return;
+  }
+  if (!existsSync(config.managedMonitor)) {
+    logger.warn(`HarborForge managed monitor path not found: ${config.managedMonitor}`);
+    return;
+  }
+
+  const args: string[] = [];
+  if (config.backendUrl) args.push('--backend-url', String(config.backendUrl));
+  if (config.identifier) args.push('--identifier', String(config.identifier));
+  if (config.apiKey) args.push('--api-key', String(config.apiKey));
+  if (config.monitor_port) args.push('--monitor-port', String(config.monitor_port));
+  if (config.reportIntervalSec) args.push('--report-interval', String(config.reportIntervalSec));
+  if (config.logLevel) args.push('--log-level', String(config.logLevel));
+
+  monitorProcess = spawn(config.managedMonitor, args, {
+    stdio: 'inherit',
+    detached: false,
+  });
+
+  monitorProcess.on('exit', (code, signal) => {
+    logger.warn(`HarborForge managed monitor exited code=${code ?? 'null'} signal=${signal ?? 'null'}`);
+    monitorProcess = null;
+  });
+
+  logger.info(`HarborForge managed monitor started: ${config.managedMonitor}`);
+}
+
+export function stopManagedMonitor(
+  logger: { info: (...args: any[]) => void; warn: (...args: any[]) => void },
+): void {
+  if (!monitorProcess) return;
+  const pid = monitorProcess.pid;
+  monitorProcess.kill('SIGTERM');
+  monitorProcess = null;
+  logger.info(`HarborForge managed monitor stopped pid=${pid ?? 'unknown'}`);
+}
--- a/plugin/core/monitor-bridge.ts
+++ b/plugin/core/monitor-bridge.ts
@@ -0,0 +1,102 @@
+/**
+ * Monitor Bridge Client
+ *
+ * Queries the local HarborForge.Monitor bridge endpoint on MONITOR_PORT
+ * to enrich plugin telemetry with host/hardware data.
+ *
+ * If the bridge is unreachable, all methods return null gracefully —
+ * the plugin continues to function without Monitor data.
+ */
+
+export interface MonitorHealth {
+  status: string;
+  monitor_version: string;
+  identifier: string;
+}
+
+export interface MonitorTelemetryResponse {
+  status: string;
+  monitor_version: string;
+  identifier: string;
+  telemetry?: {
+    identifier: string;
+    plugin_version: string;
+    cpu_pct: number;
+    mem_pct: number;
+    disk_pct: number;
+    swap_pct: number;
+    load_avg: number[];
+    uptime_seconds: number;
+    nginx_installed: boolean;
+    nginx_sites: string[];
+  };
+  last_updated?: string;
+}
+
+export class MonitorBridgeClient {
+  private baseUrl: string;
+  private timeoutMs: number;
+
+  constructor(port: number, timeoutMs = 3000) {
+    this.baseUrl = `http://127.0.0.1:${port}`;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async health(): Promise<MonitorHealth | null> {
+    return this.fetchJson<MonitorHealth>('/health');
+  }
+
+  async telemetry(): Promise<MonitorTelemetryResponse | null> {
+    return this.fetchJson<MonitorTelemetryResponse>('/telemetry');
+  }
+
+  /**
+   * POST OpenClaw metadata to the Monitor bridge so it can enrich
+   * its heartbeat uploads with OpenClaw version, plugin version,
+   * and agent information.
+   */
+  async pushOpenClawMeta(meta: OpenClawMeta): Promise<boolean> {
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+      const response = await fetch(`${this.baseUrl}/openclaw`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(meta),
+        signal: controller.signal,
+      });
+      clearTimeout(timeout);
+
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  private async fetchJson<T>(path: string): Promise<T | null> {
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+      const response = await fetch(`${this.baseUrl}${path}`, {
+        signal: controller.signal,
+      });
+      clearTimeout(timeout);
+
+      if (!response.ok) return null;
+      return (await response.json()) as T;
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * OpenClaw metadata payload sent to the Monitor bridge.
+ */
+export interface OpenClawMeta {
+  version: string;
+  plugin_version: string;
+  agents?: any[];
+}
--- a/plugin/core/openclaw-agents.ts
+++ b/plugin/core/openclaw-agents.ts
@@ -0,0 +1,48 @@
+export interface OpenClawAgentInfo {
+  name: string;
+  isDefault?: boolean;
+  identity?: string;
+  workspace?: string;
+  agentDir?: string;
+  model?: string;
+  routingRules?: number;
+  routing?: string;
+}
+
+export async function listOpenClawAgents(_logger?: { debug?: (...args: any[]) => void; warn?: (...args: any[]) => void }): Promise<OpenClawAgentInfo[]> {
+  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; };
+  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.startsWith("- ")) {
+      push();
+      const m = line.match(/^-\s+(.+?)(?:\s+\((default)\))?$/);
+      current = { name: m?.[1] || line.slice(2).trim(), isDefault: m?.[2] === "default" };
+      continue;
+    }
+    if (!current) continue;
+    const trimmed = line.trim();
+    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": current.identity = value; break;
+      case "Workspace": current.workspace = value; break;
+      case "Agent dir": 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();
+  return out;
+}
--- a/plugin/hooks/gateway-start.ts
+++ b/plugin/hooks/gateway-start.ts
@@ -0,0 +1,37 @@
+import { hostname } from 'os';
+import { getPluginConfig } from '../core/config.js';
+import { startManagedMonitor } from '../core/managed-monitor.js';
+
+export function registerGatewayStartHook(api: any, deps: {
+  logger: any;
+  pushMetaToMonitor: () => Promise<void>;
+  startCalendarScheduler: () => void;
+  setMetaPushInterval: (handle: ReturnType<typeof setInterval>) => void;
+}) {
+  const { logger, pushMetaToMonitor, startCalendarScheduler, setMetaPushInterval } = deps;
+
+  api.on('gateway_start', () => {
+    logger.info('HarborForge plugin active');
+    const live = getPluginConfig(api);
+
+    startManagedMonitor(logger, {
+      managedMonitor: live.managedMonitor,
+      backendUrl: live.backendUrl,
+      identifier: live.identifier,
+      apiKey: live.apiKey,
+      monitor_port: live.monitor_port,
+      reportIntervalSec: live.reportIntervalSec,
+      logLevel: live.logLevel,
+    });
+
+    const intervalSec = live.reportIntervalSec || 30;
+    setTimeout(() => void pushMetaToMonitor(), 2000);
+    setMetaPushInterval(setInterval(() => void pushMetaToMonitor(), intervalSec * 1000));
+
+    if (live.enabled !== false && live.calendarEnabled !== false) {
+      setTimeout(() => startCalendarScheduler(), 5000);
+    }
+
+    logger.info(`HarborForge startup config identifier=${live.identifier || hostname()} backend=${live.backendUrl}`);
+  });
+}
--- a/plugin/hooks/gateway-stop.ts
+++ b/plugin/hooks/gateway-stop.ts
@@ -0,0 +1,23 @@
+import { stopManagedMonitor } from '../core/managed-monitor.js';
+
+export function registerGatewayStopHook(api: any, deps: {
+  logger: any;
+  getMetaPushInterval: () => ReturnType<typeof setInterval> | null;
+  clearMetaPushInterval: () => void;
+  stopCalendarScheduler: () => void;
+}) {
+  const { logger, getMetaPushInterval, clearMetaPushInterval, stopCalendarScheduler } = deps;
+
+  api.on('gateway_stop', () => {
+    logger.info('HarborForge plugin stopping');
+
+    const handle = getMetaPushInterval();
+    if (handle) {
+      clearInterval(handle);
+      clearMetaPushInterval();
+    }
+
+    stopCalendarScheduler();
+    stopManagedMonitor(logger);
+  });
+}
--- a/plugin/index.ts
+++ b/plugin/index.ts
@@ -1,25 +1,30 @@
 /**
- * HarborForge Monitor Plugin for OpenClaw
+ * HarborForge Plugin for OpenClaw
 *
- * Manages sidecar lifecycle and provides monitor-related tools.
+ * Provides monitor-related tools and exposes OpenClaw metadata
+ * for the HarborForge Monitor bridge (via monitor_port).
+ *
+ * Also integrates with HarborForge Calendar system to wake agents
+ * for scheduled tasks (PLG-CAL-002, PLG-CAL-004).
+ *
+ * Sidecar architecture has been removed. Telemetry data is now
+ * served directly by the plugin when Monitor queries via the
+ * local monitor_port communication path.
 */
-import { spawn } from 'child_process';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import { existsSync } from 'fs';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-interface PluginConfig {
-  enabled?: boolean;
-  backendUrl?: string;
-  identifier?: string;
-  challengeUuid?: string;
-  reportIntervalSec?: number;
-  httpFallbackIntervalSec?: number;
-  logLevel?: 'debug' | 'info' | 'warn' | 'error';
-}
+import { hostname, freemem, totalmem, uptime, loadavg, platform } from 'node:os';
+import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
+import { MultiAgentScheduleCache } from './calendar/schedule-cache.js';
+import { getPluginConfig } from './core/config.js';
+import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge.js';
+import type { OpenClawAgentInfo } from './core/openclaw-agents.js';
+import { registerGatewayStartHook } from './hooks/gateway-start.js';
+import { registerGatewayStopHook } from './hooks/gateway-stop.js';
+import {
+  createCalendarBridgeClient,
+  createCalendarScheduler,
+  CalendarScheduler,
+  AgentWakeContext,
+} from './calendar/index.js';

 interface PluginAPI {
  logger: {
@@ -29,150 +34,643 @@ interface PluginAPI {
    warn: (...args: any[]) => void;
  };
  version?: string;
-  isRunning?: () => boolean;
+  runtime?: {
+    version?: string;
+    config?: {
+      loadConfig?: () => any;
+    };
+  };
+  config?: Record<string, unknown>;
+  pluginConfig?: Record<string, unknown>;
  on: (event: string, handler: () => void) => void;
  registerTool: (factory: (ctx: any) => any) => void;
+  /** Spawn a sub-agent with task context (OpenClaw 2.1+) */
+  spawn?: (options: {
+    agentId?: string;
+    task: string;
+    model?: string;
+    timeoutSeconds?: number;
+  }) => Promise<{ sessionId: string; status: string }>;
+  /** Get current agent status */
+  getAgentStatus?: () => Promise<{ status: string } | null>;
 }

-export default function register(api: PluginAPI, config: PluginConfig) {
-  const logger = api.logger || { 
-    info: (...args: any[]) => console.log('[HF-Monitor]', ...args),
-    error: (...args: any[]) => console.error('[HF-Monitor]', ...args),
-    debug: (...args: any[]) => console.debug('[HF-Monitor]', ...args),
-    warn: (...args: any[]) => console.warn('[HF-Monitor]', ...args),
-  };
-
-  if (!config?.enabled) {
-    logger.info('HarborForge Monitor plugin disabled');
-    return;
-  }
-
-  if (!config.challengeUuid) {
-    logger.error('Missing required config: challengeUuid');
-    logger.error('Please register server in HarborForge Monitor first');
-    return;
-  }
-
-  const serverPath = join(__dirname, '..', 'server', 'telemetry.mjs');
-  
-  if (!existsSync(serverPath)) {
-    logger.error('Telemetry server not found:', serverPath);
-    return;
-  }
-
-  let sidecar: ReturnType<typeof spawn> | null = null;
-
-  function startSidecar() {
-    if (sidecar) {
-      logger.debug('Sidecar already running');
-      return;
-    }
-
-    logger.info('Starting HarborForge Monitor telemetry server...');
-    
-    const env = {
-      ...process.env,
-      HF_MONITOR_BACKEND_URL: config.backendUrl || 'https://monitor.hangman-lab.top',
-      HF_MONITOR_IDENTIFIER: config.identifier || '',
-      HF_MONITOR_CHALLENGE_UUID: config.challengeUuid,
-      HF_MONITOR_REPORT_INTERVAL: String(config.reportIntervalSec || 30),
-      HF_MONITOR_HTTP_FALLBACK_INTERVAL: String(config.httpFallbackIntervalSec || 60),
-      HF_MONITOR_LOG_LEVEL: config.logLevel || 'info',
-      OPENCLAW_PATH: process.env.OPENCLAW_PATH || join(process.env.HOME || '/root', '.openclaw'),
-      OPENCLAW_VERSION: api.version || 'unknown',
+function register(api: PluginAPI): void {
+    const logger = api.logger || {
+      info: (...args: any[]) => console.log('[HarborForge]', ...args),
+      error: (...args: any[]) => console.error('[HarborForge]', ...args),
+      debug: (...args: any[]) => console.debug('[HarborForge]', ...args),
+      warn: (...args: any[]) => console.warn('[HarborForge]', ...args),
    };

-    sidecar = spawn('node', [serverPath], {
-      env,
-      detached: false,
-      stdio: ['ignore', 'pipe', 'pipe']
-    });
-
-    sidecar.stdout?.on('data', (data: Buffer) => {
-      logger.info('[telemetry]', data.toString().trim());
-    });
-
-    sidecar.stderr?.on('data', (data: Buffer) => {
-      logger.error('[telemetry]', data.toString().trim());
-    });
-
-    sidecar.on('exit', (code, signal) => {
-      logger.info(`Telemetry server exited (code: ${code}, signal: ${signal})`);
-      sidecar = null;
-    });
-
-    sidecar.on('error', (err: Error) => {
-      logger.error('Failed to start telemetry server:', err.message);
-      sidecar = null;
-    });
-
-    logger.info('Telemetry server started with PID:', sidecar.pid);
-  }
-
-  function stopSidecar() {
-    if (!sidecar) {
-      logger.debug('Telemetry server not running');
-      return;
+    function resolveConfig() {
+      return getPluginConfig(api);
    }

-    logger.info('Stopping HarborForge Monitor telemetry server...');
-    sidecar.kill('SIGTERM');
+    /** 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';
+    }

-    const timeout = setTimeout(() => {
-      if (sidecar && !sidecar.killed) {
-        logger.warn('Telemetry server did not exit gracefully, forcing kill');
-        sidecar.kill('SIGKILL');
-      }
-    }, 5000);
+    /**
+     * Get the monitor bridge client if monitor_port is configured.
+     */
+    function getBridgeClient(): MonitorBridgeClient | null {
+      const live = resolveConfig();
+      const port = live.monitor_port;
+      if (!port || port <= 0) return null;
+      return new MonitorBridgeClient(port);
+    }

-    sidecar.on('exit', () => {
-      clearTimeout(timeout);
-    });
-  }
-
-  // Hook into Gateway lifecycle
-  api.on('gateway:start', () => {
-    logger.info('Gateway starting, starting telemetry server...');
-    startSidecar();
-  });
-
-  api.on('gateway:stop', () => {
-    logger.info('Gateway stopping, stopping telemetry server...');
-    stopSidecar();
-  });
-
-  // Handle process signals
-  process.on('SIGTERM', stopSidecar);
-  process.on('SIGINT', stopSidecar);
-
-  // Start immediately if Gateway is already running
-  if (api.isRunning?.()) {
-    startSidecar();
-  } else {
-    setTimeout(() => startSidecar(), 1000);
-  }
-
-  // Register status tool
-  api.registerTool(() => ({
-    name: 'harborforge_monitor_status',
-    description: 'Get HarborForge Monitor plugin status',
-    parameters: {
-      type: 'object',
-      properties: {}
-    },
-    async execute() {
+    /**
+     * Collect current system telemetry snapshot.
+     * This data is exposed to the Monitor bridge when it queries the plugin.
+     */
+    function collectTelemetry() {
+      const live = resolveConfig();
+      const load = loadavg();
      return {
-        enabled: true,
-        sidecarRunning: sidecar !== null && sidecar.exitCode === null,
-        pid: sidecar?.pid || null,
-        config: {
-          backendUrl: config.backendUrl,
-          identifier: config.identifier || 'auto-detected',
-          reportIntervalSec: config.reportIntervalSec
-        }
+        identifier: live.identifier || hostname(),
+        platform: platform(),
+        hostname: hostname(),
+        uptime: uptime(),
+        memory: {
+          total: totalmem(),
+          free: freemem(),
+          used: totalmem() - freemem(),
+          usagePercent: ((totalmem() - freemem()) / totalmem()) * 100,
+        },
+        load: {
+          avg1: load[0],
+          avg5: load[1],
+          avg15: load[2],
+        },
+        openclaw: {
+          version: api.runtime?.version || api.version || 'unknown',
+          pluginVersion: '0.3.1', // Bumped for PLG-CAL-004
+        },
+        timestamp: new Date().toISOString(),
      };
    }
-  }));

-  logger.info('HarborForge Monitor plugin registered');
+    // Periodic metadata push interval handle
+    let metaPushInterval: ReturnType<typeof setInterval> | null = null;
+
+    // Calendar scheduler instance
+    let calendarScheduler: CalendarScheduler | null = null;
+
+    /**
+     * Push OpenClaw metadata to the Monitor bridge.
+     * This enriches Monitor heartbeats with OpenClaw version/plugin/agent info.
+     * Failures are non-fatal — Monitor continues to work without this data.
+     */
+    async function pushMetaToMonitor() {
+      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.runtime?.version || api.version || 'unknown',
+        plugin_version: '0.3.1',
+        agents: agentNames.map(name => ({ name })),
+      };
+
+      const ok = await bridgeClient.pushOpenClawMeta(meta);
+      if (ok) {
+        logger.debug('pushed OpenClaw metadata to Monitor bridge');
+      } else {
+        logger.debug('Monitor bridge unreachable for metadata push (non-fatal)');
+      }
+    }
+
+    /**
+     * Get current agent status from OpenClaw.
+     * Falls back to querying backend if OpenClaw API unavailable.
+     */
+    async function getAgentStatus(): Promise<'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline' | null> {
+      // Try OpenClaw API first (if available)
+      if (api.getAgentStatus) {
+        try {
+          const status = await api.getAgentStatus();
+          if (status?.status) {
+            return status.status as 'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline';
+          }
+        } catch (err) {
+          logger.debug('Failed to get agent status from OpenClaw API:', err);
+        }
+      }
+
+      // Fallback: query backend for agent status
+      const live = resolveConfig();
+      const agentId = resolveAgentId();
+      try {
+        const response = await fetch(`${live.backendUrl}/calendar/agent/status?agent_id=${agentId}`, {
+          headers: {
+            'X-Agent-ID': agentId,
+            'X-Claw-Identifier': live.identifier || hostname(),
+          },
+        });
+        if (response.ok) {
+          const data = await response.json();
+          return data.status;
+        }
+      } catch (err) {
+        logger.debug('Failed to get agent status from backend:', err);
+      }
+
+      return null;
+    }
+
+    /**
+     * Wake agent via dispatchInboundMessage — same mechanism used by Discord plugin.
+     * Direct in-process call, no WebSocket or CLI needed.
+     */
+    async function wakeAgent(
+      agentId: string,
+      dueSlots?: Array<{
+        id?: number | null;
+        virtual_id?: string | null;
+        event_data?: any;
+        scheduled_at?: string;
+        priority?: number;
+        slot_type?: string;
+        [k: string]: unknown;
+      }>
+    ): Promise<boolean> {
+      logger.info(`Waking agent ${agentId}: has due slots`);
+
+      const sessionKey = `agent:${agentId}:hf-wakeup`;
+
+      try {
+        const sdkPath = 'openclaw/plugin-sdk/reply-runtime';
+        const { dispatchInboundMessageWithDispatcher } = await import(
+          /* webpackIgnore: true */ sdkPath
+        );
+
+        // api.config first (current public API). Fall back to deprecated
+        // runtime.config.loadConfig() for older host versions. Both should
+        // contain agents.list / channels for dispatch routing.
+        const cfg = (api as any).config ?? api.runtime?.config?.loadConfig?.();
+        if (!cfg) {
+          logger.error('Cannot load OpenClaw config for dispatch');
+          return false;
+        }
+
+        // Inline the highest-priority due slot's context so the agent does
+        // not need a second round-trip to harborforge_calendar_status. The
+        // agent can read event_data.task_code / task_title etc. directly.
+        let slotBlock = '';
+        const top = dueSlots && dueSlots.length ? dueSlots[0] : undefined;
+        if (top) {
+          slotBlock = `\n\nMatching slot:\n\`\`\`json\n${JSON.stringify(
+            {
+              slot_id: top.id ?? null,
+              virtual_id: top.virtual_id ?? null,
+              scheduled_at: top.scheduled_at ?? null,
+              priority: top.priority ?? null,
+              slot_type: top.slot_type ?? null,
+              event_data: top.event_data ?? null,
+            },
+            null,
+            2
+          )}\n\`\`\``;
+        }
+
+        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.${slotBlock}`;
+
+        const result = await dispatchInboundMessageWithDispatcher({
+          ctx: {
+            Body: wakeupMessage,
+            SessionKey: sessionKey,
+            From: 'harborforge-calendar',
+            Provider: 'harborforge',
+          },
+          cfg,
+          dispatcherOptions: {
+            deliver: async (payload: any) => {
+              const text = (payload.text || '').trim();
+              logger.info(`Agent ${agentId} wakeup reply: ${text.slice(0, 100)}`);
+            },
+          },
+        });
+
+        logger.info(`Agent ${agentId} dispatched: ${result?.status || 'ok'}`);
+        return true;
+
+      } catch (err: any) {
+        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;
+      }
+    }
+
+    /**
+     * Track session completion and update slot status accordingly.
+     */
+    function trackSessionCompletion(sessionId: string, context: AgentWakeContext): void {
+      // Poll for session completion (simplified approach)
+      // In production, this would use webhooks or event streaming
+      const pollInterval = 30000; // 30 seconds
+      const maxDuration = context.slot.estimated_duration * 60 * 1000; // Convert to ms
+      const startTime = Date.now();
+
+      const poll = async () => {
+        if (!calendarScheduler) return;
+
+        const elapsed = Date.now() - startTime;
+
+        // Check if session is complete (would use actual API in production)
+        // For now, estimate completion based on duration
+        if (elapsed >= maxDuration) {
+          // Assume completion
+          const actualMinutes = Math.round(elapsed / 60000);
+          await calendarScheduler.completeCurrentSlot(actualMinutes);
+          return;
+        }
+
+        // Continue polling
+        setTimeout(poll, pollInterval);
+      };
+
+      // Start polling
+      setTimeout(poll, pollInterval);
+    }
+
+    /**
+     * Initialize and start the calendar scheduler.
+     */
+    function startCalendarScheduler(): void {
+      const live = resolveConfig();
+
+      // Create bridge client (claw-instance level, not per-agent)
+      const calendarBridge = createCalendarBridgeClient(
+        api,
+        live.backendUrl || 'https://monitor.hangman-lab.top',
+        'unused' // agentId no longer needed at bridge level
+      );
+
+      // Multi-agent sync + check loop
+      const scheduleCache = new MultiAgentScheduleCache();
+
+      const SYNC_INTERVAL_MS = 300_000; // 5 min
+      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)}`);
+        }
+      }
+
+      // Track wakes already dispatched for a slot in the current sync
+      // window — the simplified inline scheduler does not PATCH slot
+      // status server-side, so without dedupe the check loop re-wakes
+      // the same slot every 30s. Set is cleared by runSync (fresh wake
+      // budget per sync).
+      const wakedSlotKeys = new Set<string>();
+
+      // Check: find agents with due slots and wake them
+      async function runCheck() {
+        const now = new Date();
+        const agentsWithDue = scheduleCache.getAgentsWithDueSlots(now);
+
+        for (const { agentId, slots } of agentsWithDue) {
+          // Filter out slots we've already woken this sync window
+          const fresh = slots.filter((s) => {
+            const key = `${agentId}::${s.id ?? s.virtual_id ?? s.scheduled_at}`;
+            if (wakedSlotKeys.has(key)) return false;
+            return true;
+          });
+          if (fresh.length === 0) continue;
+
+          // Check if agent is busy (best effort; backend may 405 the GET
+          // — treat unknown as not-busy so wakeup still fires)
+          let status: string | null = null;
+          try {
+            status = await calendarBridge.getAgentStatus(agentId);
+          } catch {
+            status = null;
+          }
+          if (status === 'busy' || status === 'offline' || status === 'exhausted') {
+            continue;
+          }
+
+          // Wake the agent with the slot context inlined
+          const ok = await wakeAgent(agentId, fresh);
+          if (ok) {
+            for (const s of fresh) {
+              const key = `${agentId}::${s.id ?? s.virtual_id ?? s.scheduled_at}`;
+              wakedSlotKeys.add(key);
+            }
+          }
+        }
+      }
+
+      // Initial sync (also resets the wake-dedupe window)
+      const runSyncReset = async () => {
+        wakedSlotKeys.clear();
+        await runSync();
+      };
+      runSyncReset();
+
+      // Start intervals
+      const syncHandle = setInterval(runSyncReset, 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)');
+    }
+
+    /**
+     * Stop the calendar scheduler.
+     */
+    function stopCalendarScheduler(): void {
+      if (calendarScheduler) {
+        calendarScheduler.stop();
+        calendarScheduler = null;
+        logger.info('Calendar scheduler stopped');
+      }
+    }
+
+    registerGatewayStartHook(api, {
+      logger,
+      pushMetaToMonitor,
+      startCalendarScheduler,
+      setMetaPushInterval(handle) {
+        metaPushInterval = handle;
+      },
+    });
+
+    registerGatewayStopHook(api, {
+      logger,
+      getMetaPushInterval() {
+        return metaPushInterval;
+      },
+      clearMetaPushInterval() {
+        metaPushInterval = null;
+      },
+      stopCalendarScheduler,
+    });
+
+    // Tool: plugin status
+    api.registerTool(() => ({
+      name: 'harborforge_status',
+      description: 'Get HarborForge plugin status and current telemetry snapshot',
+      parameters: {
+        type: 'object',
+        properties: {},
+      },
+      async execute() {
+        const live = resolveConfig();
+        const bridgeClient = getBridgeClient();
+        let monitorBridge = null;
+
+        if (bridgeClient) {
+          const health = await bridgeClient.health();
+          monitorBridge = health
+            ? { connected: true, ...health }
+            : { connected: false, error: 'Monitor bridge unreachable' };
+        }
+
+        // Get calendar scheduler status
+        const calendarStatus = calendarScheduler ? {
+          running: calendarScheduler.isRunning(),
+          processing: calendarScheduler.isProcessing(),
+          currentSlot: calendarScheduler.getCurrentSlot(),
+          isRestartPending: calendarScheduler.isRestartPending(),
+        } : null;
+
+        return {
+          enabled: live.enabled !== false,
+          config: {
+            backendUrl: live.backendUrl,
+            identifier: live.identifier || hostname(),
+            monitorPort: live.monitor_port ?? null,
+            reportIntervalSec: live.reportIntervalSec,
+            hasApiKey: Boolean(live.apiKey),
+          },
+          monitorBridge,
+          calendar: calendarStatus,
+          telemetry: collectTelemetry(),
+        };
+      },
+    }));
+
+    // Tool: telemetry snapshot (for Monitor bridge queries)
+    api.registerTool(() => ({
+      name: 'harborforge_telemetry',
+      description: 'Get current system telemetry data for HarborForge Monitor',
+      parameters: {
+        type: 'object',
+        properties: {},
+      },
+      async execute() {
+        return collectTelemetry();
+      },
+    }));
+
+    // Tool: query Monitor bridge for host hardware telemetry
+    api.registerTool(() => ({
+      name: 'harborforge_monitor_telemetry',
+      description: 'Query HarborForge Monitor bridge for host hardware telemetry (CPU, memory, disk, etc.)',
+      parameters: {
+        type: 'object',
+        properties: {},
+      },
+      async execute() {
+        const bridgeClient = getBridgeClient();
+        if (!bridgeClient) {
+          return {
+            error: 'Monitor bridge not configured (monitor_port not set or 0)',
+          };
+        }
+
+        const data = await bridgeClient.telemetry();
+        if (!data) {
+          return {
+            error: 'Monitor bridge unreachable',
+          };
+        }
+
+        return data;
+      },
+    }));
+
+    // Tool: calendar slot management
+    api.registerTool(() => ({
+      name: 'harborforge_calendar_status',
+      description: 'Get current calendar scheduler status and pending slots',
+      parameters: {
+        type: 'object',
+        properties: {},
+      },
+      async execute() {
+        if (!calendarScheduler) {
+          return { error: 'Calendar scheduler not running' };
+        }
+
+        return {
+          running: calendarScheduler.isRunning(),
+          processing: calendarScheduler.isProcessing(),
+          currentSlot: calendarScheduler.getCurrentSlot(),
+          state: calendarScheduler.getState(),
+          isRestartPending: calendarScheduler.isRestartPending(),
+          stateFilePath: calendarScheduler.getStateFilePath(),
+        };
+      },
+    }));
+
+    // Tool: complete current slot (for agent to report completion)
+    api.registerTool(() => ({
+      name: 'harborforge_calendar_complete',
+      description: 'Complete the current calendar slot with actual duration',
+      parameters: {
+        type: 'object',
+        properties: {
+          actualDurationMinutes: {
+            type: 'number',
+            description: 'Actual time spent on the task in minutes',
+          },
+        },
+        required: ['actualDurationMinutes'],
+      },
+      async execute(params: { actualDurationMinutes: number }) {
+        if (!calendarScheduler) {
+          return { error: 'Calendar scheduler not running' };
+        }
+
+        await calendarScheduler.completeCurrentSlot(params.actualDurationMinutes);
+        return { success: true, message: 'Slot completed' };
+      },
+    }));
+
+    // Tool: abort current slot (for agent to report failure)
+    api.registerTool(() => ({
+      name: 'harborforge_calendar_abort',
+      description: 'Abort the current calendar slot',
+      parameters: {
+        type: 'object',
+        properties: {
+          reason: {
+            type: 'string',
+            description: 'Reason for aborting',
+          },
+        },
+      },
+      async execute(params: { reason?: string }) {
+        if (!calendarScheduler) {
+          return { error: 'Calendar scheduler not running' };
+        }
+
+        await calendarScheduler.abortCurrentSlot(params.reason);
+        return { success: true, message: 'Slot aborted' };
+      },
+    }));
+
+    // Tool: pause current slot
+    api.registerTool(() => ({
+      name: 'harborforge_calendar_pause',
+      description: 'Pause the current calendar slot',
+      parameters: {
+        type: 'object',
+        properties: {},
+      },
+      async execute() {
+        if (!calendarScheduler) {
+          return { error: 'Calendar scheduler not running' };
+        }
+
+        await calendarScheduler.pauseCurrentSlot();
+        return { success: true, message: 'Slot paused' };
+      },
+    }));
+
+    // Tool: resume current slot
+    api.registerTool(() => ({
+      name: 'harborforge_calendar_resume',
+      description: 'Resume the paused calendar slot',
+      parameters: {
+        type: 'object',
+        properties: {},
+      },
+      async execute() {
+        if (!calendarScheduler) {
+          return { error: 'Calendar scheduler not running' };
+        }
+
+        await calendarScheduler.resumeCurrentSlot();
+        return { success: true, message: 'Slot resumed' };
+      },
+    }));
+
+    // Tool: check ScheduledGatewayRestart status
+    api.registerTool(() => ({
+      name: 'harborforge_restart_status',
+      description: 'Check if a gateway restart is pending (PLG-CAL-004)',
+      parameters: {
+        type: 'object',
+        properties: {},
+      },
+      async execute() {
+        if (!calendarScheduler) {
+          return { error: 'Calendar scheduler not running' };
+        }
+
+        const isPending = calendarScheduler.isRestartPending();
+        const stateFilePath = calendarScheduler.getStateFilePath();
+
+        return {
+          isRestartPending: isPending,
+          stateFilePath: stateFilePath,
+          message: isPending
+            ? 'A gateway restart has been scheduled. The scheduler has been paused.'
+            : 'No gateway restart is pending.',
+        };
+      },
+    }));
+
+    logger.info('HarborForge plugin registered (id: harbor-forge)');
 }
+
+// HarborForge's local PluginAPI is broader than the standard OpenClawPluginApi
+// (it surfaces optional `version`/`runtime`/`spawn` accessors that older
+// OpenClaw builds exposed). The cast at the definePluginEntry boundary
+// acknowledges that gap — the runtime api object is whatever the gateway
+// passes us, and each access is guarded with optional chaining / fallbacks.
+export default definePluginEntry({
+  id: 'harbor-forge',
+  name: 'HarborForge',
+  description: 'HarborForge plugin for OpenClaw - project management, monitoring, and CLI integration',
+  register: register as (api: any) => void,
+});
--- a/plugin/openclaw-sdk.d.ts
+++ b/plugin/openclaw-sdk.d.ts
@@ -0,0 +1,25 @@
+// Ambient declarations for the focused subpaths of the openclaw plugin SDK
+// that this plugin needs at compile time.
+//
+// We intentionally do NOT take a `dependencies` (or `devDependencies`) entry
+// on the openclaw npm package itself: openclaw is provided by the host
+// gateway at runtime, and listing it as a file:/.../openclaw devDep breaks
+// the installer's `npm install --omit=dev` step because npm/arborist trips
+// over openclaw's own (deeply nested) dependency graph.
+//
+// These declarations cover only what we use here. They are deliberately
+// permissive — the runtime contract is whatever the gateway hands us, and
+// we guard each api access with optional chaining or a fallback at call site.
+
+declare module 'openclaw/plugin-sdk/plugin-entry' {
+  export function definePluginEntry<T extends {
+    id: string;
+    name: string;
+    description?: string;
+    register: (api: any) => void | Promise<void>;
+  }>(opts: T): T;
+}
+
+declare module 'openclaw/plugin-sdk/core' {
+  export type OpenClawPluginApi = unknown;
+}
--- a/plugin/openclaw.plugin.json
+++ b/plugin/openclaw.plugin.json
@@ -1,9 +1,23 @@
 {
-  "id": "harborforge-monitor",
-  "name": "HarborForge Monitor",
-  "version": "0.1.0",
-  "description": "Server monitoring plugin for HarborForge - streams telemetry to Monitor",
-  "entry": "./index.js",
+  "id": "harbor-forge",
+  "name": "HarborForge",
+  "description": "HarborForge plugin for OpenClaw - project management, monitoring, and CLI integration",
+  "activation": {
+    "onStartup": true
+  },
+  "contracts": {
+    "tools": [
+      "harborforge_status",
+      "harborforge_telemetry",
+      "harborforge_monitor_telemetry",
+      "harborforge_calendar_status",
+      "harborforge_calendar_complete",
+      "harborforge_calendar_abort",
+      "harborforge_calendar_pause",
+      "harborforge_calendar_resume",
+      "harborforge_restart_status"
+    ]
+  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
@@ -11,20 +25,24 @@
      "enabled": {
        "type": "boolean",
        "default": true,
-        "description": "Enable the monitor plugin"
+        "description": "Enable the HarborForge plugin"
      },
      "backendUrl": {
        "type": "string",
        "default": "https://monitor.hangman-lab.top",
-        "description": "HarborForge Monitor backend URL"
+        "description": "HarborForge backend base URL (shared by Monitor and Calendar API)"
      },
      "identifier": {
        "type": "string",
-        "description": "Server identifier (auto-detected from hostname if not set)"
+        "description": "Server/claw identifier. Used as claw_identifier in Calendar heartbeat and as MonitoredServer.identifier. Auto-detected from hostname if not set."
      },
-      "challengeUuid": { 
+      "apiKey": {
        "type": "string",
-        "description": "Registration challenge UUID from Monitor"
+        "description": "API Key from HarborForge Monitor admin panel (optional but required for Monitor authentication)"
+      },
+      "monitor_port": {
+        "type": "number",
+        "description": "Local port for communication between HarborForge Monitor and this plugin"
      },
      "reportIntervalSec": {
        "type": "number",
@@ -41,8 +59,25 @@
        "enum": ["debug", "info", "warn", "error"],
        "default": "info",
        "description": "Logging level"
+      },
+      "calendarEnabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable Calendar heartbeat integration (PLG-CAL-001). When enabled, plugin sends periodic heartbeat to /calendar/agent/heartbeat to receive pending TimeSlots."
+      },
+      "calendarHeartbeatIntervalSec": {
+        "type": "number",
+        "default": 60,
+        "description": "How often to send Calendar heartbeat to backend (seconds). Defaults to 60s (1 minute)."
+      },
+      "calendarApiKey": {
+        "type": "string",
+        "description": "API key for Calendar API authentication. If not set, uses apiKey or plugin auto-authentication via X-Agent-ID header."
+      },
+      "managedMonitor": {
+        "type": "string",
+        "description": "Absolute path to an installed HarborForge.Monitor binary managed by this plugin installer. If set, gateway_start/gateway_stop hooks will start/stop the monitor process automatically."
      }
-    },
-    "required": ["challengeUuid"]
+    }
  }
 }
--- a/plugin/package-lock.json
+++ b/plugin/package-lock.json
@@ -0,0 +1,48 @@
+{
+  "name": "harbor-forge-plugin",
+  "version": "0.2.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "harbor-forge-plugin",
+      "version": "0.2.0",
+      "license": "MIT",
+      "devDependencies": {
+        "@types/node": "^20.19.41",
+        "typescript": "^5.0.0"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "20.19.41",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.41.tgz",
+      "integrity": "sha512-ECymXOukMnOoVkC2bb1Vc/w/836DXncOg5m8Xj1RH7xSHZJWNYY6Zh7EH477vcnD5egKNNfy2RpNOmuChhFPgQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "dev": true,
+      "license": "MIT"
+    }
+  }
+}
--- a/plugin/package.json
+++ b/plugin/package.json
@@ -1,14 +1,16 @@
 {
-  "name": "harborforge-monitor-plugin",
-  "version": "0.1.0",
-  "description": "OpenClaw plugin for HarborForge Monitor",
-  "main": "index.js",
+  "name": "harbor-forge-plugin",
+  "version": "0.2.0",
+  "description": "OpenClaw plugin for HarborForge monitor bridge and CLI integration",
+  "type": "module",
+  "main": "dist/index.js",
  "scripts": {
-    "build": "tsc",
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
    "watch": "tsc --watch"
  },
  "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^20.19.41",
    "typescript": "^5.0.0"
  },
  "license": "MIT"
--- a/plugin/tsconfig.json
+++ b/plugin/tsconfig.json
@@ -1,17 +1,16 @@
 {
  "compilerOptions": {
    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
-    "outDir": "./",
+    "outDir": "./dist",
    "rootDir": "./",
-    "declaration": true,
-    "declarationMap": true,
+    "declaration": false,
    "sourceMap": true
  },
-  "include": ["*.ts"],
-  "exclude": ["node_modules"]
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
 }
--- a/scripts/install.mjs
+++ b/scripts/install.mjs
@@ -1,7 +1,13 @@
 #!/usr/bin/env node

 /**
- * HarborForge Monitor Plugin Installer v0.1.0
+ * HarborForge Plugin Installer v0.2.0
+ *
+ * Changes from v0.1.0:
+ * - Plugin renamed from harborforge-monitor to harbor-forge
+ * - Sidecar server removed (telemetry served directly by plugin)
+ * - Added --install-cli flag for building and installing the hf CLI
+ * - skills/hf/ only installed when --install-cli is present
 */

 import { execSync } from 'child_process';
@@ -11,8 +17,7 @@ import {
  copyFileSync,
  readdirSync,
  rmSync,
-  readFileSync,
-  writeFileSync,
+  chmodSync,
 } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
@@ -21,10 +26,11 @@ import { homedir, platform } from 'os';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = resolve(dirname(__filename), '..');

-const PLUGIN_NAME = 'harborforge-monitor';
+const PLUGIN_NAME = 'harbor-forge';
+const OLD_PLUGIN_NAME = 'harborforge-monitor';
 const PLUGIN_SRC_DIR = join(__dirname, 'plugin');
-const SERVER_SRC_DIR = join(__dirname, 'server');
 const SKILLS_SRC_DIR = join(__dirname, 'skills');
+const MONITOR_REPO_URL = 'https://git.hangman-lab.top/zhi/HarborForge.Monitor.git';

 const args = process.argv.slice(2);
 const options = {
@@ -34,6 +40,9 @@ const options = {
  verbose: args.includes('--verbose') || args.includes('-v'),
  uninstall: args.includes('--uninstall'),
  installOnly: args.includes('--install'),
+  installCli: args.includes('--install-cli'),
+  installMonitor: 'no',
+  monitorBranch: 'main',
 };

 const profileIdx = args.indexOf('--openclaw-profile-path');
@@ -41,6 +50,16 @@ if (profileIdx !== -1 && args[profileIdx + 1]) {
  options.openclawProfilePath = resolve(args[profileIdx + 1]);
 }

+const installMonitorIdx = args.indexOf('--install-monitor');
+if (installMonitorIdx !== -1 && args[installMonitorIdx + 1]) {
+  options.installMonitor = String(args[installMonitorIdx + 1]).toLowerCase();
+}
+
+const monitorBranchIdx = args.indexOf('--monitor-branch');
+if (monitorBranchIdx !== -1 && args[monitorBranchIdx + 1]) {
+  options.monitorBranch = String(args[monitorBranchIdx + 1]);
+}
+
 function resolveOpenclawPath() {
  if (options.openclawProfilePath) return options.openclawProfilePath;
  if (process.env.OPENCLAW_PATH) return resolve(process.env.OPENCLAW_PATH);
@@ -79,23 +98,37 @@ function setOpenclawConfig(key, value) {
  exec(`openclaw config set ${key} '${JSON.stringify(value)}' --json`, { silent: true });
 }

+function assertConfigValue(key, predicate, description) {
+  const value = getOpenclawConfig(key, undefined);
+  if (!predicate(value)) {
+    throw new Error(`Config verification failed for ${key}: ${description}`);
+  }
+  return value;
+}
+
 function unsetOpenclawConfig(key) {
  try { exec(`openclaw config unset ${key}`, { silent: true }); } catch {}
 }

-function copyDir(src, dest) {
+function copyDir(src, dest, { exclude = [] } = {}) {
  mkdirSync(dest, { recursive: true });
  for (const entry of readdirSync(src, { withFileTypes: true })) {
    const s = join(src, entry.name);
    const d = join(dest, entry.name);
    if (entry.name === 'node_modules') continue;
-    entry.isDirectory() ? copyDir(s, d) : copyFileSync(s, d);
+    if (exclude.includes(entry.name)) continue;
+    entry.isDirectory() ? copyDir(s, d, { exclude }) : copyFileSync(s, d);
  }
 }

+function shellEscape(value) {
+  return `'${String(value).replace(/'/g, `'"'"'`)}'`;
+}
+
 function detectEnvironment() {
-  logStep(1, 5, 'Detecting environment...');
-  const env = { platform: platform(), nodeVersion: null };
+  const totalSteps = options.installCli ? 6 : 5;
+  logStep(1, totalSteps, 'Detecting environment...');
+  const env = { platform: platform(), nodeVersion: null, goVersion: null };
  
  try { 
    env.nodeVersion = exec('node --version', { silent: true }).trim(); 
@@ -110,12 +143,22 @@ function detectEnvironment() {
    logWarn('openclaw CLI not in PATH'); 
  }

+  if (options.installCli) {
+    try {
+      env.goVersion = exec('go version', { silent: true }).trim();
+      logOk(env.goVersion);
+    } catch {
+      logWarn('Go not found (needed for --install-cli)');
+    }
+  }
+  
  return env;
 }

 function checkDeps(env) {
-  if (options.skipCheck) { logStep(2, 5, 'Skipping dep checks'); return; }
-  logStep(2, 5, 'Checking dependencies...');
+  const totalSteps = options.installCli ? 6 : 5;
+  if (options.skipCheck) { logStep(2, totalSteps, 'Skipping dep checks'); return; }
+  logStep(2, totalSteps, 'Checking dependencies...');
  
  let fail = false;
  if (!env.nodeVersion || parseInt(env.nodeVersion.slice(1)) < 18) { 
@@ -123,6 +166,11 @@ function checkDeps(env) {
    fail = true; 
  }

+  if (options.installCli && !env.goVersion) {
+    logErr('Go is required for --install-cli');
+    fail = true;
+  }
+  
  if (fail) { 
    log('\nInstall missing deps and retry.', 'red'); 
    process.exit(1); 
@@ -132,7 +180,8 @@ function checkDeps(env) {
 }

 async function build() {
-  logStep(3, 5, 'Building plugin...');
+  const totalSteps = options.installCli ? 6 : 5;
+  logStep(3, totalSteps, 'Building plugin...');
  
  log(' Building TypeScript plugin...', 'blue');
  exec('npm install', { cwd: PLUGIN_SRC_DIR, silent: !options.verbose });
@@ -140,12 +189,39 @@ async function build() {
  logOk('plugin compiled');
 }

+function installManagedMonitor(openclawPath) {
+  if (options.installMonitor !== 'yes') return null;
+  const tmpDir = join('/tmp', `harborforge-monitor-${Date.now()}`);
+  const monitorDestDir = join(openclawPath, 'plugins', PLUGIN_NAME, 'bin');
+  const binaryPath = join(monitorDestDir, 'HarborForge.Monitor');
+  mkdirSync(monitorDestDir, { recursive: true });
+  try {
+    exec(`git clone --branch ${shellEscape(options.monitorBranch)} ${shellEscape(MONITOR_REPO_URL)} ${shellEscape(tmpDir)}`, { silent: !options.verbose });
+    exec(`go build -o ${shellEscape(binaryPath)} ./cmd/harborforge-monitor`, { cwd: tmpDir, silent: !options.verbose });
+    chmodSync(binaryPath, 0o755);
+    logOk(`Managed monitor installed → ${binaryPath} (branch hint: ${options.monitorBranch})`);
+    return binaryPath;
+  } catch (err) {
+    logWarn(`Managed monitor build failed: ${err.message}`);
+    return null;
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
 function clearInstallTargets(openclawPath) {
+  // Remove new plugin dir
  const destDir = join(openclawPath, 'plugins', PLUGIN_NAME);
  if (existsSync(destDir)) { 
    rmSync(destDir, { recursive: true, force: true }); 
    logOk(`Removed ${destDir}`); 
  }
+  // Remove old plugin dir if it exists
+  const oldDestDir = join(openclawPath, 'plugins', OLD_PLUGIN_NAME);
+  if (existsSync(oldDestDir)) {
+    rmSync(oldDestDir, { recursive: true, force: true });
+    logOk(`Removed old plugin dir ${oldDestDir}`);
+  }
 }

 function cleanupConfig(openclawPath) {
@@ -153,20 +229,31 @@ function cleanupConfig(openclawPath) {
  
  try {
    const allow = getOpenclawConfig('plugins.allow', []);
-    const idx = allow.indexOf(PLUGIN_NAME);
-    if (idx !== -1) {
-      allow.splice(idx, 1);
-      setOpenclawConfig('plugins.allow', allow);
-      logOk('Removed from allow list');
+    // Remove both old and new names
+    for (const name of [PLUGIN_NAME, OLD_PLUGIN_NAME]) {
+      const idx = allow.indexOf(name);
+      if (idx !== -1) {
+        allow.splice(idx, 1);
+        logOk(`Removed ${name} from allow list`);
+      }
    }
+    setOpenclawConfig('plugins.allow', allow);
    
    unsetOpenclawConfig(`plugins.entries.${PLUGIN_NAME}`);
-    logOk('Removed plugin entry');
+    unsetOpenclawConfig(`plugins.entries.${OLD_PLUGIN_NAME}`);
+    logOk('Removed plugin entries');
    
    const paths = getOpenclawConfig('plugins.load.paths', []);
-    const pidx = paths.indexOf(destDir);
-    if (pidx !== -1) {
-      paths.splice(pidx, 1);
+    const oldDestDir = join(openclawPath, 'plugins', OLD_PLUGIN_NAME);
+    let changed = false;
+    for (const p of [destDir, oldDestDir]) {
+      const pidx = paths.indexOf(p);
+      if (pidx !== -1) {
+        paths.splice(pidx, 1);
+        changed = true;
+      }
+    }
+    if (changed) {
      setOpenclawConfig('plugins.load.paths', paths);
      logOk('Removed from load paths');
    }
@@ -176,8 +263,9 @@ function cleanupConfig(openclawPath) {
 }

 async function install() {
-  if (options.buildOnly) { logStep(4, 5, 'Skipping install (--build-only)'); return null; }
-  logStep(4, 5, 'Installing...');
+  const totalSteps = options.installCli ? 6 : 5;
+  if (options.buildOnly) { logStep(4, totalSteps, 'Skipping install (--build-only)'); return null; }
+  logStep(4, totalSteps, 'Installing...');
  
  const openclawPath = resolveOpenclawPath();
  const pluginsDir = join(openclawPath, 'plugins');
@@ -186,41 +274,89 @@ async function install() {
  log(` OpenClaw path: ${openclawPath}`, 'blue');
  
  if (existsSync(destDir)) {
-    logWarn('Existing install detected, uninstalling before install...');
+    logWarn('Existing install detected, cleaning up...');
    clearInstallTargets(openclawPath);
    cleanupConfig(openclawPath);
  }
  
-  if (existsSync(destDir)) rmSync(destDir, { recursive: true, force: true });
+  // Clean up old plugin name if present
+  const oldDestDir = join(pluginsDir, OLD_PLUGIN_NAME);
+  if (existsSync(oldDestDir)) {
+    logWarn('Old plugin (harborforge-monitor) detected, removing...');
+    rmSync(oldDestDir, { recursive: true, force: true });
+    cleanupConfig(openclawPath);
+  }
  
-  // Copy compiled plugin
+  // Copy compiled plugin (no server directory — sidecar removed)
  mkdirSync(destDir, { recursive: true });
-  copyDir(PLUGIN_SRC_DIR, destDir);
+  copyDir(PLUGIN_SRC_DIR, destDir, { exclude: ['node_modules', '.git'] });
+  logOk(`Plugin files → ${destDir}`);
  
-  // Copy telemetry server
-  const serverDestDir = join(destDir, 'server');
-  mkdirSync(serverDestDir, { recursive: true });
-  copyDir(SERVER_SRC_DIR, serverDestDir);
-  logOk(`Server files → ${serverDestDir}`);
-  
-  // Copy skills
+  // Copy skills (exclude hf/ unless --install-cli)
  if (existsSync(SKILLS_SRC_DIR)) {
    const skillsDestDir = join(openclawPath, 'skills');
-    mkdirSync(skillsDestDir, { recursive: true });
-    copyDir(SKILLS_SRC_DIR, skillsDestDir);
-    logOk(`Skills → ${skillsDestDir}`);
+    const excludeSkills = options.installCli ? [] : ['hf'];
+    copyDir(SKILLS_SRC_DIR, skillsDestDir, { exclude: excludeSkills });
+    if (options.installCli) {
+      logOk(`Skills (including hf) → ${skillsDestDir}`);
+    } else {
+      logOk(`Skills (hf skipped, use --install-cli) → ${skillsDestDir}`);
+    }
  }
  
  // Install runtime deps
  exec('npm install --omit=dev', { cwd: destDir, silent: !options.verbose });
  logOk('Runtime deps installed');
  
-  return { destDir };
+  const managedMonitorPath = installManagedMonitor(openclawPath);
+  return { destDir, managedMonitorPath };
+}
+
+async function installCli() {
+  if (!options.installCli) return;
+  const totalSteps = 6;
+  logStep(5, totalSteps, 'Building and installing hf CLI...');
+  
+  const openclawPath = resolveOpenclawPath();
+  const binDir = join(openclawPath, 'bin');
+  mkdirSync(binDir, { recursive: true });
+  
+  // Find CLI source — look for HarborForge.Cli relative to project root
+  const projectRoot = resolve(__dirname, '..');
+  const cliDir = join(projectRoot, 'HarborForge.Cli');
+  
+  if (!existsSync(cliDir)) {
+    // Try parent directory (monorepo layout)
+    const monoCliDir = resolve(projectRoot, '..', 'HarborForge.Cli');
+    if (!existsSync(monoCliDir)) {
+      logErr(`Cannot find HarborForge.Cli at ${cliDir} or ${monoCliDir}`);
+      logWarn('Skipping CLI installation');
+      return;
+    }
+  }
+  
+  const effectiveCliDir = existsSync(cliDir) 
+    ? cliDir 
+    : resolve(projectRoot, '..', 'HarborForge.Cli');
+  
+  log(` Building hf from ${effectiveCliDir}...`, 'blue');
+  
+  try {
+    const hfBinary = join(binDir, 'hf');
+    exec(`go build -o ${hfBinary} ./cmd/hf`, { cwd: effectiveCliDir, silent: !options.verbose });
+    chmodSync(hfBinary, 0o755);
+    logOk(`hf binary → ${hfBinary}`);
+  } catch (err) {
+    logErr(`Failed to build hf CLI: ${err.message}`);
+    logWarn('CLI installation failed, plugin still installed');
+  }
 }

 async function configure() {
-  if (options.buildOnly) { logStep(5, 5, 'Skipping config'); return; }
-  logStep(5, 5, 'Configuring OpenClaw...');
+  const totalSteps = options.installCli ? 6 : 5;
+  const step = options.installCli ? 6 : 5;
+  if (options.buildOnly) { logStep(step, totalSteps, 'Skipping config'); return; }
+  logStep(step, totalSteps, 'Configuring OpenClaw...');
  
  const openclawPath = resolveOpenclawPath();
  const destDir = join(openclawPath, 'plugins', PLUGIN_NAME);
@@ -231,6 +367,7 @@ async function configure() {
      paths.push(destDir); 
      setOpenclawConfig('plugins.load.paths', paths); 
    }
+    assertConfigValue('plugins.load.paths', (value) => Array.isArray(value) && value.includes(destDir), `missing ${destDir}`);
    logOk(`plugins.load.paths includes ${destDir}`);
    
    const allow = getOpenclawConfig('plugins.allow', []);
@@ -238,22 +375,45 @@ async function configure() {
      allow.push(PLUGIN_NAME); 
      setOpenclawConfig('plugins.allow', allow); 
    }
+    assertConfigValue('plugins.allow', (value) => Array.isArray(value) && value.includes(PLUGIN_NAME), `missing ${PLUGIN_NAME}`);
    logOk(`plugins.allow includes ${PLUGIN_NAME}`);

-    // Note: challengeUuid must be configured manually by user
-    logOk('Plugin configured (remember to set challengeUuid in ~/.openclaw/openclaw.json)');
+    const enabledKey = `plugins.entries.${PLUGIN_NAME}.enabled`;
+    const configEnabledKey = `plugins.entries.${PLUGIN_NAME}.config.enabled`;
+    if (getOpenclawConfig(enabledKey, undefined) === undefined) {
+      setOpenclawConfig(enabledKey, true);
+    }
+    if (getOpenclawConfig(configEnabledKey, undefined) === undefined) {
+      setOpenclawConfig(configEnabledKey, true);
+    }
+    assertConfigValue(enabledKey, (value) => value === true, 'expected true');
+    assertConfigValue(configEnabledKey, (value) => value === true, 'expected true');
+
+    if (options.installMonitor === 'yes') {
+      const binaryPath = join(openclawPath, 'plugins', PLUGIN_NAME, 'bin', 'HarborForge.Monitor');
+      const managedMonitorKey = `plugins.entries.${PLUGIN_NAME}.config.managedMonitor`;
+      if (getOpenclawConfig(managedMonitorKey, undefined) === undefined) {
+        setOpenclawConfig(managedMonitorKey, binaryPath);
+      }
+      assertConfigValue(managedMonitorKey, (value) => value === binaryPath, `expected ${binaryPath}`);
+      logOk(`managedMonitor configured → ${binaryPath}`);
+    }
+    
+    logOk('Plugin configured (remember to set apiKey in plugins.entries.harbor-forge.config)');
    
  } catch (err) {
-    logWarn(`Config failed: ${err.message}`);
+    logErr(`Config failed: ${err.message}`);
+    throw err;
  }
 }

 function summary() {
-  logStep(5, 5, 'Done!');
+  const totalSteps = options.installCli ? 6 : 5;
+  logStep(totalSteps, totalSteps, 'Done!');
  console.log('');
-  log('╔══════════════════════════════════════════════╗', 'cyan');
-  log('║ HarborForge Monitor v0.1.0 Install Complete ║', 'cyan');
-  log('╚══════════════════════════════════════════════╝', 'cyan');
+  log('╔════════════════════════════════════════════╗', 'cyan');
+  log('║ HarborForge v0.2.0 Install Complete        ║', 'cyan');
+  log('╚════════════════════════════════════════════╝', 'cyan');
  
  if (options.buildOnly) {
    log('\nBuild-only — plugin not installed.', 'yellow');
@@ -262,33 +422,59 @@ function summary() {
  
  console.log('');
  log('Next steps:', 'blue');
-  log(' 1. Register server in HarborForge Monitor to get challengeUuid', 'cyan');
-  log(' 2. Edit ~/.openclaw/openclaw.json:', 'cyan');
+  log(' 1. Register server in HarborForge Monitor to get apiKey', 'cyan');
+  log(' 2. Edit ~/.openclaw/openclaw.json under plugins.entries.harbor-forge.config:', 'cyan');
+  log('    (monitor_port is required for the local monitor bridge)', 'cyan');
  log('    {', 'cyan');
  log('      "plugins": {', 'cyan');
-  log('        "harborforge-monitor": {', 'cyan');
-  log('          "enabled": true,', 'cyan');
-  log('          "challengeUuid": "your-challenge-uuid"', 'cyan');
+  log('        "entries": {', 'cyan');
+  log('          "harbor-forge": {', 'cyan');
+  log('            "enabled": true,', 'cyan');
+  log('            "config": {', 'cyan');
+  log('              "enabled": true,', 'cyan');
+  log('              "apiKey": "your-api-key"', 'cyan');
+  log('            }', 'cyan');
+  log('          }', 'cyan');
  log('        }', 'cyan');
  log('      }', 'cyan');
  log('    }', 'cyan');
  log(' 3. openclaw gateway restart', 'cyan');
+  
+  if (options.installCli) {
+    console.log('');
+    log(' hf CLI installed to ~/.openclaw/bin/hf', 'green');
+    log(' Ensure ~/.openclaw/bin is in your PATH', 'cyan');
+  }
  console.log('');
 }

 async function uninstall() {
-  log('Uninstalling HarborForge Monitor...', 'cyan');
+  log('Uninstalling HarborForge...', 'cyan');
  const openclawPath = resolveOpenclawPath();
  clearInstallTargets(openclawPath);
  cleanupConfig(openclawPath);
+  
+  // Remove CLI binary if present
+  const hfBinary = join(openclawPath, 'bin', 'hf');
+  if (existsSync(hfBinary)) {
+    rmSync(hfBinary, { force: true });
+    logOk('Removed hf CLI binary');
+  }
+
+  const managedDir = join(openclawPath, 'plugins', PLUGIN_NAME, 'bin');
+  if (existsSync(managedDir)) {
+    rmSync(managedDir, { recursive: true, force: true });
+    logOk('Removed managed HarborForge monitor');
+  }
+  
  log('\nRun: openclaw gateway restart', 'yellow');
 }

 async function main() {
  console.log('');
-  log('╔══════════════════════════════════════════════╗', 'cyan');
-  log('║ HarborForge Monitor Plugin Installer v0.1.0 ║', 'cyan');
-  log('╚══════════════════════════════════════════════╝', 'cyan');
+  log('╔════════════════════════════════════════════╗', 'cyan');
+  log('║ HarborForge Plugin Installer v0.2.0        ║', 'cyan');
+  log('╚════════════════════════════════════════════╝', 'cyan');
  console.log('');
  
  try {
@@ -304,6 +490,9 @@ async function main() {
    
    if (!options.buildOnly) {
      await install();
+      if (options.installCli) {
+        await installCli();
+      }
      await configure();
    }
    
--- a/server/telemetry.mjs
+++ b/server/telemetry.mjs
@@ -1,278 +0,0 @@
-/**
- * HarborForge Monitor Telemetry Server
- * 
- * Runs as separate process from Gateway.
- * Collects system metrics and OpenClaw status, sends to Monitor.
- */
-import { readFile, access } from 'fs/promises';
-import { constants } from 'fs';
-import { exec } from 'child_process';
-import { promisify } from 'util';
-import { platform, hostname, freemem, totalmem, uptime } from 'os';
-
-const execAsync = promisify(exec);
-
-// Config from environment (set by plugin)
-const CONFIG = {
-  backendUrl: process.env.HF_MONITOR_BACKEND_URL || 'https://monitor.hangman-lab.top',
-  identifier: process.env.HF_MONITOR_IDENTIFIER || hostname(),
-  challengeUuid: process.env.HF_MONITOR_CHALLENGE_UUID,
-  reportIntervalSec: parseInt(process.env.HF_MONITOR_REPORT_INTERVAL || '30', 10),
-  httpFallbackIntervalSec: parseInt(process.env.HF_MONITOR_HTTP_FALLBACK_INTERVAL || '60', 10),
-  logLevel: process.env.HF_MONITOR_LOG_LEVEL || 'info',
-  openclawPath: process.env.OPENCLAW_PATH || `${process.env.HOME}/.openclaw`,
-  openclawVersion: process.env.OPENCLAW_VERSION || 'unknown',
-};
-
-// Logging
-const log = {
-  debug: (...args) => CONFIG.logLevel === 'debug' && console.log('[DEBUG]', ...args),
-  info: (...args) => ['debug', 'info'].includes(CONFIG.logLevel) && console.log('[INFO]', ...args),
-  warn: (...args) => console.log('[WARN]', ...args),
-  error: (...args) => console.error('[ERROR]', ...args),
-};
-
-// State
-let wsConnection = null;
-let lastSuccessfulSend = null;
-let consecutiveFailures = 0;
-let isShuttingDown = false;
-
-/**
- * Collect system metrics
- */
-async function collectSystemMetrics() {
-  try {
-    const cpuUsage = await getCpuUsage();
-    const memTotal = totalmem();
-    const memFree = freemem();
-    const memUsed = memTotal - memFree;
-    const diskInfo = await getDiskUsage();
-    const loadAvg = platform() !== 'win32' ? require('os').loadavg() : [0, 0, 0];
-    
-    return {
-      cpu_pct: cpuUsage,
-      mem_pct: Math.round((memUsed / memTotal) * 100 * 10) / 10,
-      mem_used_mb: Math.round(memUsed / 1024 / 1024),
-      mem_total_mb: Math.round(memTotal / 1024 / 1024),
-      disk_pct: diskInfo.usedPct,
-      disk_used_gb: Math.round(diskInfo.usedGB * 10) / 10,
-      disk_total_gb: Math.round(diskInfo.totalGB * 10) / 10,
-      swap_pct: diskInfo.swapUsedPct || 0,
-      uptime_sec: Math.floor(uptime()),
-      load_avg_1m: Math.round(loadAvg[0] * 100) / 100,
-      platform: platform(),
-      hostname: hostname(),
-    };
-  } catch (err) {
-    log.error('Failed to collect system metrics:', err.message);
-    return {};
-  }
-}
-
-/**
- * Get CPU usage percentage
- */
-async function getCpuUsage() {
-  try {
-    if (platform() === 'linux') {
-      const { stdout } = await execAsync("top -bn1 | grep 'Cpu(s)' | awk '{print $2}' | cut -d'%' -f1");
-      const usage = parseFloat(stdout.trim());
-      return isNaN(usage) ? 0 : Math.round(usage * 10) / 10;
-    } else if (platform() === 'darwin') {
-      const { stdout } = await execAsync("top -l 1 | grep 'CPU usage' | awk '{print $3}' | cut -d'%' -f1");
-      const usage = parseFloat(stdout.trim());
-      return isNaN(usage) ? 0 : Math.round(usage * 10) / 10;
-    }
-  } catch {
-    try {
-      const stat = await readFile('/proc/stat', 'utf8');
-      const cpuLine = stat.split('\n')[0];
-      const parts = cpuLine.split(/\s+/).slice(1).map(Number);
-      const idle = parts[3];
-      const total = parts.reduce((a, b) => a + b, 0);
-      const usage = ((total - idle) / total) * 100;
-      return Math.round(usage * 10) / 10;
-    } catch {
-      return 0;
-    }
-  }
-  return 0;
-}
-
-/**
- * Get disk usage
- */
-async function getDiskUsage() {
-  try {
-    if (platform() === 'linux' || platform() === 'darwin') {
-      const { stdout } = await execAsync("df -h / | tail -1 | awk '{print $2,$3,$5}'");
-      const [total, used, pct] = stdout.trim().split(/\s+/);
-      return {
-        totalGB: parseSizeToGB(total),
-        usedGB: parseSizeToGB(used),
-        usedPct: parseInt(pct.replace('%', ''), 10),
-      };
-    }
-  } catch (err) {
-    log.debug('Failed to get disk usage:', err.message);
-  }
-  return { totalGB: 0, usedGB: 0, usedPct: 0 };
-}
-
-function parseSizeToGB(size) {
-  const num = parseFloat(size);
-  if (size.includes('T')) return num * 1024;
-  if (size.includes('G')) return num;
-  if (size.includes('M')) return num / 1024;
-  if (size.includes('K')) return num / 1024 / 1024;
-  return num;
-}
-
-/**
- * Collect OpenClaw status
- */
-async function collectOpenclawStatus() {
-  try {
-    const agents = await getOpenclawAgents();
-    return {
-      version: CONFIG.openclawVersion,
-      agent_count: agents.length,
-      agents: agents.map(a => ({
-        id: a.id,
-        name: a.name,
-        status: a.status,
-      })),
-    };
-  } catch (err) {
-    log.debug('Failed to collect OpenClaw status:', err.message);
-    return { version: CONFIG.openclawVersion, agent_count: 0, agents: [] };
-  }
-}
-
-/**
- * Get list of OpenClaw agents from local state
- */
-async function getOpenclawAgents() {
-  try {
-    const agentConfigPath = `${CONFIG.openclawPath}/agents.json`;
-    try {
-      await access(agentConfigPath, constants.R_OK);
-      const data = JSON.parse(await readFile(agentConfigPath, 'utf8'));
-      return data.agents || [];
-    } catch {
-      return [];
-    }
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Build telemetry payload
- */
-async function buildPayload() {
-  const system = await collectSystemMetrics();
-  const openclaw = await collectOpenclawStatus();
-  
-  return {
-    identifier: CONFIG.identifier,
-    challenge_uuid: CONFIG.challengeUuid,
-    timestamp: new Date().toISOString(),
-    ...system,
-    openclaw_version: openclaw.version,
-    openclaw_agents: openclaw.agents,
-    openclaw_agent_count: openclaw.agent_count,
-  };
-}
-
-/**
- * Send telemetry via HTTP
- */
-async function sendHttpHeartbeat() {
-  try {
-    const payload = await buildPayload();
-    log.debug('Sending HTTP heartbeat...');
-    
-    const response = await fetch(`${CONFIG.backendUrl}/monitor/server/heartbeat`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'X-Server-Identifier': CONFIG.identifier,
-        'X-Challenge-UUID': CONFIG.challengeUuid,
-      },
-      body: JSON.stringify(payload),
-    });
-    
-    if (response.ok) {
-      log.debug('HTTP heartbeat sent successfully');
-      lastSuccessfulSend = Date.now();
-      consecutiveFailures = 0;
-      return true;
-    } else {
-      throw new Error(`HTTP ${response.status}: ${await response.text()}`);
-    }
-  } catch (err) {
-    log.error('HTTP heartbeat failed:', err.message);
-    consecutiveFailures++;
-    return false;
-  }
-}
-
-/**
- * Main reporting loop
- */
-async function reportingLoop() {
-  while (!isShuttingDown) {
-    try {
-      const success = await sendHttpHeartbeat();
-      
-      let interval = CONFIG.reportIntervalSec * 1000;
-      if (!success) {
-        const backoff = Math.min(consecutiveFailures * 10000, 300000);
-        interval = Math.max(interval, backoff);
-        log.info(`Retry in ${interval}ms (backoff)`);
-      }
-      
-      await new Promise(resolve => setTimeout(resolve, interval));
-    } catch (err) {
-      log.error('Reporting loop error:', err.message);
-      await new Promise(resolve => setTimeout(resolve, 30000));
-    }
-  }
-}
-
-/**
- * Graceful shutdown
- */
-function shutdown() {
-  log.info('Shutting down telemetry server...');
-  isShuttingDown = true;
-  
-  if (wsConnection) {
-    wsConnection.close();
-  }
-  
-  sendHttpHeartbeat().finally(() => {
-    process.exit(0);
-  });
-}
-
-// Handle signals
-process.on('SIGTERM', shutdown);
-process.on('SIGINT', shutdown);
-
-// Start
-log.info('HarborForge Monitor Telemetry Server starting...');
-log.info('Config:', {
-  identifier: CONFIG.identifier,
-  backendUrl: CONFIG.backendUrl,
-  reportIntervalSec: CONFIG.reportIntervalSec,
-});
-
-if (!CONFIG.challengeUuid) {
-  log.error('Missing HF_MONITOR_CHALLENGE_UUID environment variable');
-  process.exit(1);
-}
-
-reportingLoop();
--- a/skills/hf/SKILL.md
+++ b/skills/hf/SKILL.md
@@ -0,0 +1,59 @@
+# hf - HarborForge CLI
+
+`hf` is the Go-based CLI for HarborForge. It manages users, projects, tasks, milestones, meetings, support tickets, proposals, and server monitoring.
+
+## Quick Start
+
+```bash
+# See all available commands (including those you may not have permission for)
+hf --help
+
+# See only the commands you're permitted to use
+hf --help-brief
+
+# Check API health
+hf health
+
+# Show CLI version
+hf version
+```
+
+## Configuration
+
+```bash
+# Set the HarborForge API URL
+hf config --url https://your-harborforge.example.com
+
+# View current config
+hf config
+```
+
+## Usage Tips
+
+- Use `hf --help-brief` to quickly see what you can do — it hides commands you don't have permission for.
+- Use `hf <group> --help` for the full subcommand list of any group (e.g. `hf task --help`).
+- Add `--json` to any command for machine-readable JSON output.
+- Resources use **codes** (not numeric IDs) — e.g. `hf task get TASK-42`.
+
+## Authentication
+
+If `pass_mgr` is available (padded-cell mode), authentication is automatic — no flags needed.
+
+Without `pass_mgr` (manual mode), pass `--token <token>` to authenticated commands.
+
+## Command Groups
+
+| Group       | Description                        |
+|-------------|------------------------------------|
+| `user`      | Manage user accounts               |
+| `role`      | Manage roles and permissions       |
+| `project`   | Manage projects and members        |
+| `milestone` | Manage project milestones          |
+| `task`      | Manage and track tasks             |
+| `meeting`   | Manage meetings and attendance     |
+| `support`   | Manage support tickets             |
+| `propose`   | Manage proposals                   |
+| `monitor`   | Monitor servers and API keys       |
+| `config`    | CLI configuration                  |
+| `health`    | API health check                   |
+| `version`   | Show CLI version                   |
Author	SHA1	Message	Date
hzhang	9ba591795b	fix: wake dedupe + inline slot context + complete contracts.tools Three issues making HF→agent wakeup unusable in practice, surfaced by DinD sim end-to-end test (recruiter agent + slot for 招募 manager task): 1. Plugin re-woke the same slot every 30s. The inline runCheck only destructured agentId from scheduleCache.getAgentsWithDueSlots() and dropped the slots array, then called wakeAgent without recording the wake. The simplified inline scheduler also never PATCHes slot status server-side from not_started→ongoing, so the next 30s check sees the slot still due and wakes again. After 4 wakes the agent's wakeup session was full of WAKEUP_OK noise. Fix: keep slots in runCheck, add an in-memory wakedSlotKeys set keyed by (agentId, slotId\|virtual_id\|scheduled_at). Dedupe on this set; clear it inside the sync interval (fresh wake budget per sync). Server-side slot transition still TODO (requires re-introducing the CalendarScheduler class path or PATCH /calendar/slots/.../agent-update here); the dedupe at least stops the wake spam. 2. Wakeup message had no slot context. The wakeup body just said 'follow hf-wakeup workflow' with no slot id/event_data/task_code. The agent then had to call harborforge_calendar_status to learn anything — which itself is broken in the simplified scheduler (it queries a CalendarScheduler instance that never gets created). Fix: pass dueSlots into wakeAgent and inline the highest-priority slot's {slot_id, scheduled_at, priority, slot_type, event_data} as a JSON block in the wakeup message. The agent reads event_data. task_code directly and routes via workflow_lookup without any round-trip. Per PLG-CAL-001 docs in hf-hangman-lab SKILL.md, this is the documented contract; we are bringing the message in line. 3. contracts.tools listed 5 of the 9 registered tools. Manifest had harborforge_status/telemetry/monitor_telemetry/calendar_status/ calendar_complete. Code also registers calendar_abort, calendar_pause, calendar_resume, harborforge_restart_status. With the new OpenClaw plugin host enforcement (same gotcha that bit Meridian — see zhi/Meridian#2), undeclared tools are silently dropped from the agent's tool list, so abort/pause/resume cannot be called by the agent. plugin doctor was emitting: 'plugin tool is undeclared (harbor-forge): harborforge_calendar_abort' for each missing tool. Fix: add the 4 missing tool names to contracts.tools. Also use api.config as the primary config source in wakeAgent (current public API), falling back to runtime.config.loadConfig() for older hosts — same pattern as the Meridian fix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-20 12:02:25 +01:00
hzhang	c9f61419cb	Merge docs/readme-refresh into main Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-16 17:55:57 +01:00
hzhang	cc807484fc	docs: refresh README — accuracy pass + HarborForge platform context Verified against current code; fixed stale/inaccurate sections and documented previously-undocumented features/flags/endpoints. Added a "Part of the HarborForge platform" reference and role/port. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-16 17:50:01 +01:00
operator	917cb344cf	chore: track ambient openclaw-sdk.d.ts (was caught by *.d.ts ignore) The .gitignore was set up to skip tsc's compiled .d.ts output but it also matched the hand-written ambient declarations file added in the previous commit. Add a negation rule so that one file is tracked. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-08 08:29:35 +00:00
operator	64a9c431bf	chore: convert plugin to ESM and migrate to current openclaw plugin SDK ESM conversion: - plugin/package.json: add "type": "module". - plugin/tsconfig.json: switch module/moduleResolution to "nodenext"; bump target to ES2022. - All relative imports across plugin/ now carry .js extensions as required by Node ESM (nodenext module resolution). - plugin/index.ts: replace `require('./calendar/schedule-cache')` with a proper top-level import; switch `from 'os'` to `from 'node:os'`. Plugin SDK convention update: - Wrap default export with definePluginEntry({ id, name, description, register }) per the current openclaw plugin authoring contract. - Modernize plugin/openclaw.plugin.json: drop entry/version, add activation.onStartup so gateway_start fires for this plugin at boot, declare contracts.tools listing the five harborforge_* tools. - Add a local plugin/openclaw-sdk.d.ts with ambient declarations for the focused subpaths (openclaw/plugin-sdk/plugin-entry, openclaw/plugin-sdk/core). We deliberately do NOT add openclaw as an npm devDependency: the installer's `npm install --omit=dev` step trips over openclaw's own (deeply nested) dependency graph when listed via file:.../openclaw, and the runtime contract is provided by the gateway loader anyway. - The local PluginAPI interface is preserved (broader than the standard OpenClawPluginApi — it surfaces `version`/`runtime`/`spawn`); the register function is cast at the definePluginEntry boundary. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-08 08:28:58 +00:00
h z	957bcbb4a8	Merge pull request 'feat: schedule cache, workflow-aligned prompts, dispatchInbound wakeup' (#5 ) from zhi-2026-04-18 into main Reviewed-on: #5	2026-05-01 07:23:25 +00:00
operator	9195dc6bd1	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>	2026-04-19 12:24:21 +00:00
operator	248adfaafd	fix: use runtime API for version and agent list instead of subprocess Use api.runtime.version for openclaw version and api.runtime.config.loadConfig() for agent list. Eliminates the periodic openclaw agents list subprocess that caused high CPU usage.	2026-04-16 15:53:20 +00:00
operator	e4ac7b7af3	fix: disable periodic openclaw agents list subprocess Spawning a full openclaw CLI process every 30s to list agents is too heavy — each invocation loads all plugins (~16s) and hangs until killed. Return empty array for now until a lighter mechanism is available.	2026-04-16 15:26:55 +00:00
operator	2088cd12b4	fix: use OPENCLAW_SERVICE_VERSION for real version and increase agent list timeout api.version returns plugin API version (0.2.0), not the openclaw release version. Use OPENCLAW_SERVICE_VERSION env var set by the gateway instead. Also increase listOpenClawAgents timeout from 15s to 30s since plugin loading takes ~16s on T2.	2026-04-16 15:12:35 +00:00
h z	58a800a1aa	Merge pull request 'HarborForge.OpenclawPlugin: dev-2026-03-29 -> main' (#4 ) from dev-2026-03-29 into main Reviewed-on: #4	2026-04-05 22:09:30 +00:00
orion	b81125db0d	fix: use patch for calendar slot agent updates	2026-04-04 18:29:50 +00:00
orion	7f86073fe7	fix: send calendar heartbeat as post	2026-04-04 17:58:59 +00:00
orion	f3a38d6455	fix: verify plugin config during install	2026-04-04 17:30:56 +00:00
orion	bcd47d8b39	feat: populate monitor agents from openclaw list	2026-04-04 08:55:00 +00:00
orion	9b13c6b7aa	fix: only fill missing plugin config values	2026-04-04 08:33:38 +00:00
orion	3f8859424c	refactor: remove monitor legacy compatibility	2026-04-04 08:05:50 +00:00
orion	2262f32a0b	feat: pass config overrides to managed monitor	2026-04-04 07:54:07 +00:00
orion	ff5c07a38c	fix: use explicit monitor repository url	2026-04-04 07:28:32 +00:00
orion	485f8e117b	fix: build monitor from cmd entrypoint	2026-04-04 07:00:03 +00:00
orion	e6e1c5395b	fix: install managed monitor from temp clone	2026-04-04 06:54:18 +00:00
orion	038862ef8c	refactor: manage monitor via gateway hooks	2026-04-04 00:44:33 +00:00
zhi	3b0ea0ad12	PLG-CAL-004: Implement ScheduledGatewayRestart handling in plugin - Add state persistence (persistState/restoreState) for recovery after restart - Add handleScheduledGatewayRestart method that: - Persists current scheduler state to disk - Sends final heartbeat to backend before shutdown - Stops the calendar scheduler (pauses scheduled tasks) - Add isRestartPending flag to prevent new slot processing during restart - Add isScheduledGatewayRestart helper to detect restart events - Update scheduler to detect and handle ScheduledGatewayRestart events - Add new tools: harborforge_restart_status, harborforge_calendar_pause/resume - Export isRestartPending and getStateFilePath methods - Bump plugin version to 0.3.1	2026-04-01 09:41:02 +00:00
zhi	24c4a7ad14	PLG-CAL-003 fix deferred slot replanning	2026-04-01 08:52:11 +00:00
zhi	97021f97c0	PLG-CAL-002: Implement calendar scheduler for agent slot wakeup - Add CalendarScheduler class to manage periodic heartbeat and slot execution - Implement agent wakeup logic when Idle and slots are pending - Handle slot status transitions (attended, ongoing, deferred) - Support both real and virtual slot materialization - Add task context building for different event types (job, system, entertainment) - Integrate scheduler into main plugin index.ts - Add new plugin tools: harborforge_calendar_status, complete, abort	2026-04-01 08:45:05 +00:00
zhi	55d7d11a52	feat(plugin): PLG-CAL-001 - define Calendar heartbeat request/response format - Add plugin/calendar/types.ts: TypeScript interfaces for heartbeat request/response (CalendarHeartbeatRequest/Response, CalendarSlotResponse, SlotAgentUpdate, all enums: SlotType, SlotStatus, EventType) - Add plugin/calendar/calendar-bridge.ts: CalendarBridgeClient HTTP client with heartbeat(), updateSlot(), updateVirtualSlot(), reportAgentStatus() - Add plugin/calendar/index.ts: module entry point exporting all public types - Add docs/PLG-CAL-001-calendar-heartbeat-format.md: full specification documenting claw_identifier and agent_id determination, request/response shapes, error handling, and endpoint summary - Update plugin/openclaw.plugin.json: add calendarEnabled, calendarHeartbeatIntervalSec, calendarApiKey config options; clarify identifier description as claw_identifier Refs: HarborForge.NEXT_WAVE_DEV_DIRECTION.md §6, BE-AGT-001	2026-04-01 07:51:39 +00:00
hzhang	188d0a48d7	Merge pull request 'Merge dev-2026-03-21 into main' (#3 ) from dev-2026-03-21 into main Reviewed-on: #3	2026-03-22 14:15:21 +00:00
zhi	e7ba982128	feat: push OpenClaw metadata to Monitor bridge periodically - MonitorBridgeClient gains pushOpenClawMeta() method for POST /openclaw - OpenClawMeta interface defines version/plugin_version/agents payload - Plugin pushes metadata on gateway_start (delayed 2s) and periodically - Interval aligns with reportIntervalSec (default 30s) - Pushes are non-fatal — plugin continues if Monitor is unreachable - Interval cleanup on gateway_stop - Updated monitor-server-connector-plan.md with new architecture	2026-03-22 01:37:21 +00:00
zhi	27b8b74d39	Align plugin monitor_port config	2026-03-21 19:22:57 +00:00
zhi	78a61e0fb2	Integrate plugin with local monitor bridge	2026-03-21 16:07:01 +00:00
zhi	9f649e2b39	feat: rename plugin to harbor-forge, remove sidecar, add --install-cli Major changes: - Renamed plugin id from harborforge-monitor to harbor-forge (TODO 4.1) - Removed sidecar server/ directory and spawn logic (TODO 4.2) - Added monitorPort to plugin config schema (TODO 4.3) - Added --install-cli flag to installer for building hf CLI (TODO 4.4) - skills/hf/ only deployed when --install-cli is present (TODO 4.5) - Plugin now serves telemetry data directly via tools - Installer handles migration from old plugin name - Bumped version to 0.2.0	2026-03-21 15:24:50 +00:00
zhi	94eca82fc7	feat: add skills/hf/SKILL.md for hf CLI agent integration Adds the SKILL.md that teaches agents how to use the hf CLI. Gated behind --install-cli in the installer (per plan).	2026-03-21 13:50:41 +00:00
hzhang	afdbc469ad	Merge pull request 'feat: stabilize HarborForge monitor sidecar plugin' (#2 ) from feat/telemetry-sidecar-v2 into main Reviewed-on: #2	2026-03-20 09:18:36 +00:00
zhi	14ed887ce3	refactor(telemetry): read agents via [ { "id": "main", "identityName": "霓光 (Neon)", "identityEmoji": "✨", "identitySource": "identity", "workspace": "/root/.openclaw/workspace", "agentDir": "/root/.openclaw/agents/main/agent", "model": "minimax-portal/MiniMax-M2.5", "bindings": 1, "isDefault": true, "routes": [ "default (no explicit rules)" ] }, { "id": "developer", "name": "developer", "identityName": "小智 (Zhi)", "identityEmoji": "👋", "identitySource": "identity", "workspace": "/root/.openclaw/workspace/workspace-developer", "agentDir": "/root/.openclaw/agents/developer/agent", "model": "anthropic/claude-opus-4-6", "bindings": 1, "isDefault": false }, { "id": "dispatcher", "name": "dispatcher", "workspace": "/root/.openclaw/workspace/workspace-dispatcher", "agentDir": "/root/.openclaw/agents/dispatcher/agent", "model": "minimax-portal/MiniMax-M2.5", "bindings": 0, "isDefault": false }, { "id": "operator", "name": "operator", "identityName": "晨曦 (Orion)", "identityEmoji": "✨", "identitySource": "identity", "workspace": "/root/.openclaw/workspace/workspace-operator", "agentDir": "/root/.openclaw/agents/operator/agent", "model": "openai-codex/gpt-5.2-codex", "bindings": 1, "isDefault": false }, { "id": "manager", "name": "manager", "identityName": "指南(Nav)", "identityEmoji": "🧭", "identitySource": "identity", "workspace": "/root/.openclaw/workspace/workspace-manager", "agentDir": "/root/.openclaw/agents/manager/agent", "model": "openai-codex/gpt-5.2-codex", "bindings": 1, "isDefault": false }, { "id": "mentor", "name": "mentor", "identityName": "霖 (Lyn)", "identityEmoji": "🪶", "identitySource": "identity", "workspace": "/root/.openclaw/workspace/workspace-mentor", "agentDir": "/root/.openclaw/agents/mentor/agent", "model": "minimax-portal/MiniMax-M2.1", "bindings": 1, "isDefault": false }, { "id": "recruiter", "name": "recruiter", "identityName": "沐川(Evan)", "identityEmoji": "🧩", "identitySource": "identity", "workspace": "/root/.openclaw/workspace/workspace-recruiter", "agentDir": "/root/.openclaw/agents/recruiter/agent", "model": "minimax-portal/MiniMax-M2.5", "bindings": 0, "isDefault": false }, { "id": "administrative-secretary", "name": "administrative-secretary", "identityName": "映秘(Mirror)", "identityEmoji": "🪞", "identitySource": "identity", "workspace": "/root/.openclaw/workspace/workspace-administrative-secretary", "agentDir": "/root/.openclaw/agents/administrative-secretary/agent", "model": "minimax-portal/MiniMax-M2.5", "bindings": 1, "isDefault": false }, { "id": "agent-resource-director", "name": "agent-resource-director", "identityName": "影织(Sherlock)", "identityEmoji": "🕸️", "identitySource": "identity", "workspace": "/root/.openclaw/workspace/workspace-agent-resource-director", "agentDir": "/root/.openclaw/agents/agent-resource-director/agent", "model": "kimi-coding/kimi-k2-thinking", "bindings": 1, "isDefault": false } ] [plugins] memory-lancedb-pro@1.1.0-beta.6: plugin registered (db: /root/.openclaw/memory/lancedb-pro, model: jina-embeddings-v5-text-small) [plugins] memory-lancedb-pro: diagnostic build tag loaded (memory-lancedb-pro-diag-20260308-0058) [plugins] self-improvement: integrated hooks registered (agent:bootstrap, command:new, command:reset) [plugins] session-strategy: using systemSessionMemory (plugin memory-reflection hooks disabled) [plugins] PaddedCell plugin initializing... [plugins] PaddedCell plugin initialized [plugins] dirigent: pluginDir resolved from import.meta.url: /root/.openclaw/plugins/dirigent [plugins] hook runner initialized with 3 registered hooks [plugins] hook runner initialized with 3 registered hooks [plugins] hook runner initialized with 3 registered hooks [plugins] hook runner initialized with 3 registered hooks - Prefer OpenClaw CLI as source of truth for agent list - Parse JSON prefix defensively when plugin logs trail output - Keep file/directory discovery only as fallback	2026-03-20 08:12:58 +00:00
zhi	ab42936408	fix(telemetry): discover agents from ~/.openclaw/agents and clean docs - Fallback to agent directory discovery when agents.json is absent - Count configured agent workspaces (excluding main) - Rewrite plugin docs to API key-only flow	2026-03-20 08:02:19 +00:00
zhi	040cde8cad	feat(telemetry): report openclaw and plugin versions separately - Report remote OpenClaw CLI version as openclaw_version - Report harborforge-monitor plugin version as plugin_version - Pass plugin version from plugin runtime to sidecar - Read live config via api.pluginConfig/api.config helper	2026-03-20 07:23:18 +00:00
zhi	006784db63	refactor(plugin): read config via api.pluginConfig and api.config - Mirror dirigent plugin registration pattern - Read base config from api.pluginConfig - Read live config from api.config.plugins.entries.harborforge-monitor.config - Support gateway_start/gateway_stop lifecycle only - Compile nested plugin/core files	2026-03-20 07:13:12 +00:00
zhi	de4ef87491	refactor(plugin): remove fallback sidecar autostart	2026-03-20 06:42:45 +00:00
zhi	55b17e35ea	fix(plugin): use OpenClaw gateway_start/gateway_stop hooks	2026-03-20 06:36:20 +00:00
zhi	8ebc76931f	fix(plugin): normalize OpenClaw plugin config shapes - Accept flat config, nested entry.config, or missing config - Treat plugin as enabled unless explicitly disabled - Log resolved runtime config for gateway diagnostics	2026-03-20 06:27:46 +00:00
zhi	eb43434e48	fix(plugin): correct telemetry server path for installed plugin - Resolve telemetry.mjs relative to installed plugin root - Update installer messaging from challengeUuid to apiKey - Document correct OpenClaw plugin entry config structure	2026-03-20 06:24:40 +00:00
zhi	6d6d00437d	chore: add .gitignore for build artifacts	2026-03-19 18:20:43 +00:00
zhi	0dc824549a	feat: fix API Key authentication and payload alignment - Update openclaw.plugin.json: replace challengeUuid with apiKey (optional) - Fix tsconfig: use CommonJS module to avoid import.meta.url issues - Fix plugin/index.ts: remove ESM-specific code, use __dirname - Fix telemetry.mjs: - Add loadavg to os imports, remove require() call - Replace challengeUuid with apiKey in config - Update endpoint to heartbeat-v2 - Add X-API-Key header when apiKey is configured - Fix payload field names: agents, load_avg (array), uptime_seconds - Change missing apiKey from error to warning	2026-03-19 18:20:29 +00:00