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.

.gitignore

@@ -0,0 +1,6 @@
+plugin/node_modules/
+plugin/dist/
+plugin/**/*.js
+plugin/**/*.js.map
+plugin/**/*.d.ts
+plugin/**/*.d.ts.map

README.md

@@ -1,167 +1,167 @@
 # HarborForge OpenClaw Plugin
 
-OpenClaw 插件，将服务器遥测数据流式传输到 HarborForge Monitor。
+OpenClaw 插件：向 HarborForge Monitor 暴露 OpenClaw 侧元数据，并提供可选的本地桥接能力；安装时也可顺带安装 `hf` CLI。
+
+## 当前状态
+
+- 插件注册名：`harbor-forge`
+- 旧 sidecar `server/` 架构已移除
+- 监控桥接走本地 `monitor_port`
+- 安装脚本支持 `--install-cli`
+- `skills/hf/` 仅在 `--install-cli` 时一并安装
 
 ## 项目结构
 
-```
+```text
 HarborForge.OpenclawPlugin/
-├── package.json                 # 根 package.json
+├── package.json
-├── README.md                    # 本文档
+├── README.md
-├── plugin/                      # OpenClaw 插件代码
+├── plugin/
-│   ├── openclaw.plugin.json     # 插件定义
+│   ├── openclaw.plugin.json
-│   ├── index.ts                 # 插件入口
+│   ├── index.ts
-│   ├── package.json             # 插件依赖
+│   ├── core/
-│   └── tsconfig.json            # TypeScript 配置
+│   │   ├── config.ts
-├── server/                      # Sidecar 服务器
+│   │   ├── managed-monitor.ts
-│   └── telemetry.mjs            # 遥测数据收集和发送
+│   │   └── monitor-bridge.ts
-├── skills/                      # OpenClaw 技能
+│   ├── hooks/
-│   └── (技能文件)
+│   │   ├── gateway-start.ts
+│   │   └── gateway-stop.ts
+│   └── package.json
+├── skills/
+│   └── hf/
+│       └── SKILL.md
 └── scripts/
-    └── install.mjs              # 安装脚本
+    └── install.mjs
-```
-
-## 架构
-
-```
-┌─────────────────────────────────────────────────┐
-│  OpenClaw Gateway                               │
-│  ┌───────────────────────────────────────────┐  │
-│  │  HarborForge.OpenclawPlugin/plugin/       │  │
-│  │  - 生命周期管理 (启动/停止)                 │  │
-│  │  - 配置管理                                │  │
-│  └───────────────────────────────────────────┘  │
-│              │                                   │
-│              ▼ 启动 telemetry server             │
-│  ┌───────────────────────────────────────────┐  │
-│  │  HarborForge.OpenclawPlugin/server/       │  │
-│  │  - 独立 Node 进程                          │  │
-│  │  - 收集系统指标                            │  │
-│  │  - 收集 OpenClaw 状态                      │  │
-│  │  - 发送到 HarborForge Monitor              │  │
-│  └───────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────┘
-                        │
-                        ▼ HTTP/WebSocket
-              ┌─────────────────────┐
-              │ HarborForge Monitor │
-              └─────────────────────┘
 ```
 
 ## 安装
 
-### 快速安装
+### 普通安装
 
 ```bash
-# 克隆仓库
-git clone https://git.hangman-lab.top/zhi/HarborForge.OpenclawPlugin.git
-cd HarborForge.OpenclawPlugin
-
-# 运行安装脚本
 node scripts/install.mjs
 ```
 
-### 开发安装
+这会：
+- 构建并安装 OpenClaw 插件
+- 复制常规 skills
+- **不会**安装 `hf` 二进制
+- **不会**复制 `skills/hf/`
+
+### 安装插件 + `hf` CLI
 
 ```bash
-# 仅构建不安装
+node scripts/install.mjs --install-cli
+```
+
+这会额外：
+- 构建 `HarborForge.Cli`
+- 安装 `hf` 到 `~/.openclaw/bin/hf`
+- `chmod +x ~/.openclaw/bin/hf`
+- 复制 `skills/hf/` 到 OpenClaw profile skills 目录
+
+### 常用选项
+
+```bash
+# 仅构建
 node scripts/install.mjs --build-only
 
-# 指定 OpenClaw 路径
+# 指定 OpenClaw profile
 node scripts/install.mjs --openclaw-profile-path /custom/path/.openclaw
 
-# 详细输出
+# 详细日志
 node scripts/install.mjs --verbose
+
+# 卸载
+node scripts/install.mjs --uninstall
 ```
 
 ## 配置
 
-1. 在 HarborForge Monitor 中注册服务器，获取 `challengeUuid`
+编辑 `~/.openclaw/openclaw.json`：
-
-2. 编辑 `~/.openclaw/openclaw.json`:
 
 ```json
 {
   "plugins": {
-    "harborforge-monitor": {
+    "entries": {
-      "enabled": true,
+      "harbor-forge": {
-      "backendUrl": "https://monitor.hangman-lab.top",
+        "enabled": true,
-      "identifier": "my-server-01",
+        "config": {
-      "challengeUuid": "your-challenge-uuid-here",
+          "enabled": true,
-      "reportIntervalSec": 30,
+          "backendUrl": "https://monitor.hangman-lab.top",
-      "httpFallbackIntervalSec": 60,
+          "identifier": "my-server-01",
-      "logLevel": "info"
+          "apiKey": "your-api-key-here",
+          "monitor_port": 9100,
+          "reportIntervalSec": 30,
+          "httpFallbackIntervalSec": 60,
+          "logLevel": "info"
+        }
+      }
     }
   }
 }
 ```
 
-3. 重启 OpenClaw Gateway:
+然后重启：
 
 ```bash
 openclaw gateway restart
 ```
 
-## 配置选项
+## 配置项
 
 | 选项 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `enabled` | boolean | `true` | 是否启用插件 |
-| `backendUrl` | string | `https://monitor.hangman-lab.top` | Monitor 后端地址 |
+| `backendUrl` | string | `https://monitor.hangman-lab.top` | HarborForge Monitor 后端地址 |
-| `identifier` | string | 自动检测 hostname | 服务器标识符 |
+| `identifier` | string | 主机名 | 服务器标识符 |
-| `challengeUuid` | string | 必填 | 注册挑战 UUID |
+| `apiKey` | string | 无 | HarborForge Monitor 生成的服务器 API Key |
+| `monitor_port` | number | 无 | 本地桥接端口；插件通过 `127.0.0.1:<monitor_port>` 与 HarborForge.Monitor 通信 |
 | `reportIntervalSec` | number | `30` | 报告间隔（秒） |
 | `httpFallbackIntervalSec` | number | `60` | HTTP 回退间隔（秒） |
-| `logLevel` | string | `"info"` | 日志级别: debug/info/warn/error |
+| `logLevel` | string | `info` | 日志级别：`debug` / `info` / `warn` / `error` |
 
-## 收集的指标
+## 本地桥接说明
 
-### 系统指标
+当插件配置了 `monitor_port`，并且 HarborForge.Monitor 也使用相同的 `MONITOR_PORT` 时：
-- CPU 使用率 (%)
-- 内存使用率 (%)、已用/总量 (MB)
-- 磁盘使用率 (%)、已用/总量 (GB)
-- 交换分区使用率 (%)
-- 系统运行时间 (秒)
-- 1分钟平均负载
-- 平台 (linux/darwin/win32)
-- 主机名
 
-### OpenClaw 指标
+- Monitor 在 `127.0.0.1:<MONITOR_PORT>` 提供本地桥接服务
-- OpenClaw 版本
+- 插件可探测 `GET /health`
-- Agent 数量
+- 插件工具 `harborforge_monitor_telemetry` 可读取 `GET /telemetry`
-- Agent 列表 (id, name, status)
+- 如果桥接端口未配置或不可达，插件仍可正常运行
 
-## 卸载
+也就是说，这条链路是**可选增强**，不是插件启动或 Monitor 心跳的前置条件。
 
-```bash
+## 插件提供的信息
-node scripts/install.mjs --uninstall
+
-```
+### OpenClaw 元数据
+- OpenClaw version
+- plugin version
+- 标识符 / 主机名
+- 时间戳
+
+### 系统快照
+- uptime
+- memory total/free/used/usagePercent
+- load avg1/avg5/avg15
+- platform
 
 ## 开发
 
-### 构建插件
-
 ```bash
 cd plugin
 npm install
 npm run build
 ```
 
-### 本地测试 telemetry server
-
-```bash
-cd server
-HF_MONITOR_CHALLENGE_UUID=test-uuid \
-HF_MONITOR_BACKEND_URL=http://localhost:8000 \
-HF_MONITOR_LOG_LEVEL=debug \
-node telemetry.mjs
-```
-
 ## 依赖
 
 - Node.js 18+
 - OpenClaw Gateway
+- Go 1.20+（仅 `--install-cli` 需要）
 
-## 文档
+## 相关提示
 
-- [监控连接器规划](./docs/monitor-server-connector-plan.md) - 原始设计文档
+- 安装 `hf` 后，建议把 `~/.openclaw/bin` 加到 `PATH`
+- Agent 使用 `hf` 时，优先试 `hf --help-brief`
+- 完整命令树看 `hf --help`

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 |

docs/monitor-server-connector-plan.md

@@ -1,112 +1,54 @@
-# HarborForge OpenClaw Server Connector Plugin — Project Plan
+# Monitor Server Connector Plan
 
-## 1) Goal
+## Current design
-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.
 
-## 2) Scope
+The plugin and Monitor communicate over a local bridge port (`monitor_port` / `MONITOR_PORT`).
-- **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.
 
-## 3) Non-Goals
+### Data flow
-- No UI in the plugin.
-- No provider billing calls from plugin.
-- No multi-tenant auth beyond challenge + server identifier.
 
-## 4) Architecture
+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.
-plugin/
+3. **Monitor → Backend**: Monitor heartbeats to `POST /monitor/server/heartbeat-v2` with `X-API-Key`, enriched with any available OpenClaw metadata.
-  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
-```
 
-### 4.1 Config
+### Bridge endpoints (on Monitor, 127.0.0.1:MONITOR_PORT)
-- `backend_url`
-- `identifier`
-- `challenge_uuid`
-- `report_interval_sec` (default: 20-30s)
-- `http_fallback_interval_sec` (default: 60s)
-- `log_level`
 
-### 4.2 Security
+| Endpoint | Method | Description |
-- Fetch public key: `GET /monitor/public/server-public-key`
+|----------|--------|-------------|
-- Encrypt payload with RSA-OAEP
+| `/health` | GET | Health check, returns monitor version and identifier |
-- Include `nonce` + `ts` (UTC) to prevent replay
+| `/telemetry` | GET | Latest hardware telemetry snapshot |
-- **Challenge valid**: 10 minutes
+| `/openclaw` | POST | Receive OpenClaw metadata from plugin |
-- **Offline threshold**: 7 minutes
 
-## 5) Communication Flow
+### Plugin behavior
-### 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.
 
-### 5.2 Fallback (HTTP)
+- On `gateway_start`, plugin begins periodic metadata push (aligned with `reportIntervalSec`).
-If WS fails:
+- Initial push is delayed 2s to allow Monitor bridge startup.
-- POST telemetry to `/monitor/server/heartbeat` with same payload fields.
+- If bridge is unreachable, pushes fail silently. Plugin remains fully functional.
-- Retry with exponential backoff (cap 5–10 min).
+- 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",
+  "identifier": "vps.t1",
-  openclaw_version: "x.y.z",
+  "openclaw_version": "OpenClaw 2026.3.13 (61d171a)",
-  cpu_pct: 12.5,
+  "plugin_version": "0.2.0",
-  mem_pct: 41.2,
+  "agents": [],
-  disk_pct: 62.0,
+  "cpu_pct": 10.5,
-  swap_pct: 0.0,
+  "mem_pct": 52.1,
-  agents: [ { id: "a1", name: "agent", status: "running" } ],
+  "disk_pct": 81.0,
-  last_seen_at: "2026-03-11T21:00:00Z"
+  "swap_pct": 0.0,
+  "load_avg": [0.12, 0.09, 0.03],
+  "uptime_seconds": 12345,
+  "nginx_installed": true,
+  "nginx_sites": ["default"]
 }
 ```
 
-## 7) Reliability
+`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.
-- 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.

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"
+      }
+    }
+  }
+}

package.json

@@ -1,14 +1,15 @@
 {
-  "name": "harborforge-openclaw-plugin",
+  "name": "harbor-forge-openclaw-plugin",
-  "version": "0.1.0",
+  "version": "0.2.0",
-  "description": "OpenClaw plugin for HarborForge Monitor - streams server telemetry",
+  "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"

plugin/calendar/calendar-bridge.ts

@@ -0,0 +1,262 @@
+/**
+ * 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';
+
+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);
+  }
+
+  // -------------------------------------------------------------------------
+  // 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';
+
+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,
+  });
+}

plugin/calendar/index.ts

@@ -0,0 +1,33 @@
+/**
+ * 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';
+ *
+ *   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';
+export * from './calendar-bridge';
+export * from './scheduler';

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';
+import {
+  CalendarSlotResponse,
+  SlotStatus,
+  AgentStatusValue,
+  SlotAgentUpdate,
+  CalendarEventDataJob,
+  CalendarEventDataSystemEvent,
+} from './types';
+
+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);
+}

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;
+}

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,
+  };
+}

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'}`);
+}

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[];
+}

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;
+}

plugin/hooks/gateway-start.ts

@@ -0,0 +1,37 @@
+import { hostname } from 'os';
+import { getPluginConfig } from '../core/config';
+import { startManagedMonitor } from '../core/managed-monitor';
+
+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}`);
+  });
+}

plugin/hooks/gateway-stop.ts

@@ -0,0 +1,23 @@
+import { stopManagedMonitor } from '../core/managed-monitor';
+
+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);
+  });
+}

plugin/index.ts

@@ -1,25 +1,28 @@
 /**
- * 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 { hostname, freemem, totalmem, uptime, loadavg, platform } from 'os';
-import { fileURLToPath } from 'url';
+import { getPluginConfig } from './core/config';
-import { dirname, join } from 'path';
+import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge';
-import { existsSync } from 'fs';
+import type { OpenClawAgentInfo } from './core/openclaw-agents';
-
+import { registerGatewayStartHook } from './hooks/gateway-start';
-const __filename = fileURLToPath(import.meta.url);
+import { registerGatewayStopHook } from './hooks/gateway-stop';
-const __dirname = dirname(__filename);
+import {
-
+  createCalendarBridgeClient,
-interface PluginConfig {
+  createCalendarScheduler,
-  enabled?: boolean;
+  CalendarScheduler,
-  backendUrl?: string;
+  AgentWakeContext,
-  identifier?: string;
+} from './calendar';
-  challengeUuid?: string;
-  reportIntervalSec?: number;
-  httpFallbackIntervalSec?: number;
-  logLevel?: 'debug' | 'info' | 'warn' | 'error';
-}
 
 interface PluginAPI {
   logger: {
@@ -29,150 +32,524 @@ 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) {
+export default {
-  const logger = api.logger || { 
+  id: 'harbor-forge',
-    info: (...args: any[]) => console.log('[HF-Monitor]', ...args),
+  name: 'HarborForge',
-    error: (...args: any[]) => console.error('[HF-Monitor]', ...args),
+  register(api: PluginAPI) {
-    debug: (...args: any[]) => console.debug('[HF-Monitor]', ...args),
+    const logger = api.logger || {
-    warn: (...args: any[]) => console.warn('[HF-Monitor]', ...args),
+      info: (...args: any[]) => console.log('[HarborForge]', ...args),
-  };
+      error: (...args: any[]) => console.error('[HarborForge]', ...args),
-
+      debug: (...args: any[]) => console.debug('[HarborForge]', ...args),
-  if (!config?.enabled) {
+      warn: (...args: any[]) => console.warn('[HarborForge]', ...args),
-    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',
     };
 
-    sidecar = spawn('node', [serverPath], {
+    function resolveConfig() {
-      env,
+      return getPluginConfig(api);
-      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;
     }
 
-    logger.info('Stopping HarborForge Monitor telemetry server...');
+    /**
-    sidecar.kill('SIGTERM');
+     * 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);
+    }
 
-    const timeout = setTimeout(() => {
+    /**
-      if (sidecar && !sidecar.killed) {
+     * Collect current system telemetry snapshot.
-        logger.warn('Telemetry server did not exit gracefully, forcing kill');
+     * This data is exposed to the Monitor bridge when it queries the plugin.
-        sidecar.kill('SIGKILL');
+     */
-      }
+    function collectTelemetry() {
-    }, 5000);
+      const live = resolveConfig();
-
+      const load = loadavg();
-    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() {
       return {
-        enabled: true,
+        identifier: live.identifier || hostname(),
-        sidecarRunning: sidecar !== null && sidecar.exitCode === null,
+        platform: platform(),
-        pid: sidecar?.pid || null,
+        hostname: hostname(),
-        config: {
+        uptime: uptime(),
-          backendUrl: config.backendUrl,
+        memory: {
-          identifier: config.identifier || 'auto-detected',
+          total: totalmem(),
-          reportIntervalSec: config.reportIntervalSec
+          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 = process.env.AGENT_ID || 'unknown';
+      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/spawn agent with task context for slot execution.
+     * This is the callback invoked by CalendarScheduler when a slot is ready.
+     */
+    async function wakeAgent(context: AgentWakeContext): Promise<boolean> {
+      logger.info(`Waking agent for slot: ${context.taskDescription}`);
+
+      try {
+        // Method 1: Use OpenClaw spawn API if available (preferred)
+        if (api.spawn) {
+          const result = await api.spawn({
+            task: context.prompt,
+            timeoutSeconds: context.slot.estimated_duration * 60, // Convert to seconds
+          });
+
+          if (result?.sessionId) {
+            logger.info(`Agent spawned for calendar slot: session=${result.sessionId}`);
+
+            // Track session completion
+            trackSessionCompletion(result.sessionId, context);
+            return true;
+          }
+        }
+
+        // Method 2: Send notification/alert to wake agent (fallback)
+        // This relies on the agent's heartbeat to check for notifications
+        logger.warn('OpenClaw spawn API not available, using notification fallback');
+
+        // Send calendar wakeup notification via backend
+        const live = resolveConfig();
+        const agentId = process.env.AGENT_ID || 'unknown';
+
+        const notifyResponse = await fetch(`${live.backendUrl}/calendar/agent/notify`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'X-Agent-ID': agentId,
+            'X-Claw-Identifier': live.identifier || hostname(),
+          },
+          body: JSON.stringify({
+            agent_id: agentId,
+            message: context.prompt,
+            slot_id: context.slot.id || context.slot.virtual_id,
+            task_description: context.taskDescription,
+          }),
+        });
+
+        return notifyResponse.ok;
+
+      } catch (err) {
+        logger.error('Failed to wake agent:', err);
+        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();
+      const agentId = process.env.AGENT_ID || 'unknown';
+
+      // Create calendar bridge client
+      const calendarBridge = createCalendarBridgeClient(
+        api,
+        live.backendUrl || 'https://monitor.hangman-lab.top',
+        agentId
+      );
+
+      // Create and start scheduler
+      calendarScheduler = createCalendarScheduler({
+        bridge: calendarBridge,
+        getAgentStatus,
+        wakeAgent,
+        logger,
+        heartbeatIntervalMs: 60000, // 1 minute
+        debug: live.logLevel === 'debug',
+      });
+
+      calendarScheduler.start();
+      logger.info('Calendar scheduler started');
+    }
+
+    /**
+     * 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)');
+  },
+};

plugin/openclaw.plugin.json

@@ -1,9 +1,9 @@
 {
-  "id": "harborforge-monitor",
+  "id": "harbor-forge",
-  "name": "HarborForge Monitor",
+  "name": "HarborForge",
-  "version": "0.1.0",
+  "version": "0.2.0",
-  "description": "Server monitoring plugin for HarborForge - streams telemetry to Monitor",
+  "description": "HarborForge plugin for OpenClaw - project management, monitoring, and CLI integration",
-  "entry": "./index.js",
+  "entry": "./dist/index.js",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -11,20 +11,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 +45,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"]
   }
 }

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.0.0",
+        "typescript": "^5.0.0"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "20.19.37",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.37.tgz",
+      "integrity": "sha512-8kzdPJ3FsNsVIurqBs7oodNnCEVbni9yUEkaHbgptDACOPW04jimGagZ51E6+lXUwJjgnBw+hyko/lkFWCldqw==",
+      "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"
+    }
+  }
+}

plugin/package.json

@@ -1,10 +1,11 @@
 {
-  "name": "harborforge-monitor-plugin",
+  "name": "harbor-forge-plugin",
-  "version": "0.1.0",
+  "version": "0.2.0",
-  "description": "OpenClaw plugin for HarborForge Monitor",
+  "description": "OpenClaw plugin for HarborForge monitor bridge and CLI integration",
-  "main": "index.js",
+  "main": "dist/index.js",
   "scripts": {
-    "build": "tsc",
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
     "watch": "tsc --watch"
   },
   "devDependencies": {

plugin/tsconfig.json

@@ -1,17 +1,16 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "module": "NodeNext",
+    "module": "CommonJS",
-    "moduleResolution": "NodeNext",
+    "moduleResolution": "node",
     "esModuleInterop": true,
     "strict": true,
     "skipLibCheck": true,
-    "outDir": "./",
+    "outDir": "./dist",
     "rootDir": "./",
-    "declaration": true,
+    "declaration": false,
-    "declarationMap": true,
     "sourceMap": true
   },
-  "include": ["*.ts"],
+  "include": ["**/*.ts"],
-  "exclude": ["node_modules"]
+  "exclude": ["node_modules", "dist"]
 }

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,
+  chmodSync,
-  writeFileSync,
 } 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 totalSteps = options.installCli ? 6 : 5;
-  const env = { platform: platform(), nodeVersion: null };
+  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; }
+  const totalSteps = options.installCli ? 6 : 5;
-  logStep(2, 5, 'Checking dependencies...');
+  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);
+    // Remove both old and new names
-    if (idx !== -1) {
+    for (const name of [PLUGIN_NAME, OLD_PLUGIN_NAME]) {
-      allow.splice(idx, 1);
+      const idx = allow.indexOf(name);
-      setOpenclawConfig('plugins.allow', allow);
+      if (idx !== -1) {
-      logOk('Removed from allow list');
+        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);
+    const oldDestDir = join(openclawPath, 'plugins', OLD_PLUGIN_NAME);
-    if (pidx !== -1) {
+    let changed = false;
-      paths.splice(pidx, 1);
+    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; }
+  const totalSteps = options.installCli ? 6 : 5;
-  logStep(4, 5, 'Installing...');
+  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
+  // Copy skills (exclude hf/ unless --install-cli)
-  const serverDestDir = join(destDir, 'server');
-  mkdirSync(serverDestDir, { recursive: true });
-  copyDir(SERVER_SRC_DIR, serverDestDir);
-  logOk(`Server files → ${serverDestDir}`);
-  
-  // Copy skills
   if (existsSync(SKILLS_SRC_DIR)) {
     const skillsDestDir = join(openclawPath, 'skills');
-    mkdirSync(skillsDestDir, { recursive: true });
+    const excludeSkills = options.installCli ? [] : ['hf'];
-    copyDir(SKILLS_SRC_DIR, skillsDestDir);
+    copyDir(SKILLS_SRC_DIR, skillsDestDir, { exclude: excludeSkills });
-    logOk(`Skills → ${skillsDestDir}`);
+    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; }
+  const totalSteps = options.installCli ? 6 : 5;
-  logStep(5, 5, 'Configuring OpenClaw...');
+  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
+    const enabledKey = `plugins.entries.${PLUGIN_NAME}.enabled`;
-    logOk('Plugin configured (remember to set challengeUuid in ~/.openclaw/openclaw.json)');
+    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('╔════════════════════════════════════════════╗', 'cyan');
-  log('║ HarborForge Monitor v0.1.0 Install Complete ║', 'cyan');
+  log('║ HarborForge v0.2.0 Install Complete        ║', 'cyan');
-  log('╚══════════════════════════════════════════════╝', '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(' 1. Register server in HarborForge Monitor to get apiKey', 'cyan');
-  log(' 2. Edit ~/.openclaw/openclaw.json:', '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('        "entries": {', 'cyan');
-  log('          "enabled": true,', 'cyan');
+  log('          "harbor-forge": {', 'cyan');
-  log('          "challengeUuid": "your-challenge-uuid"', '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('╔════════════════════════════════════════════╗', 'cyan');
-  log('║ HarborForge Monitor Plugin Installer v0.1.0 ║', 'cyan');
+  log('║ HarborForge Plugin Installer v0.2.0        ║', 'cyan');
-  log('╚══════════════════════════════════════════════╝', '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();
     }
     

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();

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                   |