PLG-CAL-004: Implement ScheduledGatewayRestart handling in plugin

- Add state persistence (persistState/restoreState) for recovery after restart - Add handleScheduledGatewayRestart method that: - Persists current scheduler state to disk - Sends final heartbeat to backend before shutdown - Stops the calendar scheduler (pauses scheduled tasks) - Add isRestartPending flag to prevent new slot processing during restart - Add isScheduledGatewayRestart helper to detect restart events - Update scheduler to detect and handle ScheduledGatewayRestart events - Add new tools: harborforge_restart_status, harborforge_calendar_pause/resume - Export isRestartPending and getStateFilePath methods - Bump plugin version to 0.3.1
PLG-CAL-003 fix deferred slot replanning
2026-04-01 09:41:02 +00:00 · 2026-04-01 08:52:11 +00:00 · 2026-04-01 08:45:05 +00:00 · 2026-04-01 07:51:39 +00:00
24 changed files with 3741 additions and 18 deletions
--- a/docs/PLG-CAL-001-calendar-heartbeat-format.md
+++ b/docs/PLG-CAL-001-calendar-heartbeat-format.md
@@ -0,0 +1,261 @@
+# PLG-CAL-001 — Calendar Heartbeat Format Specification
+
+> **Task:** HarborForge OpenclawPlugin / Monitor 联动  
+> **Subtask:** PLG-CAL-001 — 插件侧定义 Calendar 心跳请求格式  
+> **Status:** ✅ Implemented (types + client + spec)  
+> **Date:** 2026-04-01
+
+---
+
+## Overview
+
+This document specifies the request/response format for the Calendar heartbeat
+communication between the OpenClaw HarborForge plugin and the HarborForge backend.
+
+Heartbeat direction: **Plugin → Backend**
+
+The plugin sends a heartbeat every minute (aligned with the existing Monitor
+heartbeat interval). The backend returns today's pending TimeSlots for the agent.
+
+---
+
+## 1. How `claw_identifier` is Determined
+
+`claw_identifier` identifies the server/claw instance. It is the same value used
+in the Monitor heartbeat system (`MonitoredServer.identifier`).
+
+**Priority order:**
+
+1. **`config.identifier`** — if set in the plugin config (`harbor-forge.identifier`)
+2. **`os.hostname()`** — auto-detected from the machine hostname (fallback)
+
+```typescript
+// In plugin/calendar/calendar-bridge.ts
+const clawIdentifier = baseConfig.identifier || hostname();
+```
+
+---
+
+## 2. How `agent_id` is Determined
+
+`agent_id` is the OpenClaw agent identifier (`$AGENT_ID`).
+
+- Set by OpenClaw at agent startup as an environment variable
+- The plugin reads it via `process.env.AGENT_ID`
+- Globally unique within a single OpenClaw gateway deployment
+
+```typescript
+// In plugin/index.ts (caller)
+const agentId = process.env.AGENT_ID || 'unknown';
+```
+
+---
+
+## 3. Heartbeat Request
+
+**Endpoint:** `GET /calendar/agent/heartbeat`
+
+### Headers
+
+| Header | Value | Notes |
+|--------|-------|-------|
+| `Content-Type` | `application/json` | Always set |
+| `X-Agent-ID` | `$AGENT_ID` | OpenClaw agent identifier |
+| `X-Claw-Identifier` | `claw_identifier` | Server identifier |
+
+### Request Body (JSON)
+
+```json
+{
+  "claw_identifier": "srv1390517",
+  "agent_id": "developer"
+}
+```
+
+### Field Definitions
+
+| Field | Type | Source | Notes |
+|-------|------|--------|-------|
+| `claw_identifier` | string | Plugin config or `hostname()` | Identifies the OpenClaw server instance |
+| `agent_id` | string | `process.env.AGENT_ID` | Identifies the agent session |
+
+---
+
+## 4. Heartbeat Response
+
+### Success (HTTP 200)
+
+```json
+{
+  "slots": [
+    {
+      "id": 42,
+      "virtual_id": null,
+      "user_id": 1,
+      "date": "2026-04-01",
+      "slot_type": "work",
+      "estimated_duration": 30,
+      "scheduled_at": "09:00:00",
+      "started_at": null,
+      "attended": false,
+      "actual_duration": null,
+      "event_type": "job",
+      "event_data": {
+        "type": "Task",
+        "code": "TASK-123"
+      },
+      "priority": 50,
+      "status": "not_started",
+      "plan_id": null
+    }
+  ],
+  "agent_status": "idle",
+  "message": "2 slots pending"
+}
+```
+
+### Field Definitions
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `slots` | `CalendarSlotResponse[]` | Pending slots, sorted by `priority` DESC |
+| `agent_status` | `AgentStatusValue` | Current backend-observed agent status |
+| `message` | string (optional) | Human-readable summary |
+
+### `CalendarSlotResponse` Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `number \| null` | Real slot DB id. `null` for virtual slots. |
+| `virtual_id` | `string \| null` | `plan-{plan_id}-{date}`. `null` for real slots. |
+| `user_id` | number | Owner HarborForge user id |
+| `date` | string | ISO date `YYYY-MM-DD` |
+| `slot_type` | `SlotType` | `work \| on_call \| entertainment \| system` |
+| `estimated_duration` | number | Minutes (1-50) |
+| `scheduled_at` | string | ISO time `HH:MM:SS` |
+| `started_at` | `string \| null` | Actual start time when slot begins |
+| `attended` | boolean | `true` once agent begins the slot |
+| `actual_duration` | `number \| null` | Real minutes when slot finishes |
+| `event_type` | `EventType \| null` | `job \| entertainment \| system_event` |
+| `event_data` | object \| null | See §4a below |
+| `priority` | number | 0-99, higher = more urgent |
+| `status` | `SlotStatus` | `not_started \| deferred \| ...` |
+| `plan_id` | `number \| null` | Source plan if materialized from SchedulePlan |
+
+### §4a — `event_data` Shapes
+
+**When `event_type == "job"`:**
+```json
+{
+  "type": "Task",
+  "code": "TASK-42",
+  "working_sessions": ["session-id-1"]
+}
+```
+
+**When `event_type == "system_event"`:**
+```json
+{
+  "event": "ScheduleToday"
+}
+```
+Valid events: `ScheduleToday | SummaryToday | ScheduledGatewayRestart`
+
+---
+
+## 5. Slot Update Requests (Plugin → Backend after execution)
+
+After attending / finishing / deferring a slot, the plugin calls:
+
+**Real slot:** `PATCH /calendar/slots/{slot_id}/agent-update`
+**Virtual slot:** `PATCH /calendar/slots/virtual/{virtual_id}/agent-update`
+
+### Headers
+
+Same as heartbeat (see §3).
+
+### Request Body
+
+```json
+{
+  "status": "ongoing",
+  "started_at": "09:02:31",
+  "actual_duration": null
+}
+```
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `status` | `SlotStatus` | **Required** | New status after agent action |
+| `started_at` | string | On attending | ISO time `HH:MM:SS` |
+| `actual_duration` | number | On finishing | Real minutes |
+
+### Status Transition Values
+
+| Action | `status` value |
+|--------|---------------|
+| Agent begins slot | `ongoing` |
+| Agent finishes slot | `finished` |
+| Agent defers slot | `deferred` |
+| Agent aborts slot | `aborted` |
+| Agent pauses slot | `paused` |
+
+---
+
+## 6. Backend Endpoint Summary
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/calendar/agent/heartbeat` | X-Agent-ID + X-Claw-Identifier | Fetch pending slots for today |
+| PATCH | `/calendar/slots/{id}/agent-update` | X-Agent-ID + X-Claw-Identifier | Update real slot status |
+| PATCH | `/calendar/slots/virtual/{vid}/agent-update` | X-Agent-ID + X-Claw-Identifier | Update virtual slot status |
+| POST | `/calendar/agent/status` | X-Agent-ID + X-Claw-Identifier | Report agent status change |
+
+---
+
+## 7. Error Handling
+
+- **Backend unreachable:** Plugin logs warning, returns `null` from heartbeat.  
+  Agent continues to operate without Calendar integration.
+- **Invalid credentials (401/403):** Logged as error. No retry on same interval.
+- **Rate limiting (429):** Plugin should mark agent as `Exhausted` and not retry
+  until the `Retry-After` header indicates.
+
+---
+
+## 8. TypeScript Reference
+
+Full type definitions are in `plugin/calendar/types.ts`:
+
+```typescript
+// Request
+interface CalendarHeartbeatRequest {
+  claw_identifier: string;
+  agent_id: string;
+}
+
+// Response
+interface CalendarHeartbeatResponse {
+  slots: CalendarSlotResponse[];
+  agent_status: AgentStatusValue;
+  message?: string;
+}
+
+// Slot update
+interface SlotAgentUpdate {
+  status: SlotStatus;
+  started_at?: string;   // ISO time HH:MM:SS
+  actual_duration?: number;
+}
+```
+
+---
+
+## 9. Implementation Files
+
+| File | Purpose |
+|------|---------|
+| `plugin/calendar/types.ts` | TypeScript interfaces for all request/response shapes |
+| `plugin/calendar/calendar-bridge.ts` | `CalendarBridgeClient` HTTP client |
+| `plugin/calendar/index.ts` | Module entry point |
+| `docs/PLG-CAL-001-calendar-heartbeat-format.md` | This specification |
--- a/package-lock.json
+++ b/package-lock.json
@@ -0,0 +1,17 @@
+{
+  "name": "harbor-forge-openclaw-plugin",
+  "version": "0.2.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "harbor-forge-openclaw-plugin",
+      "version": "0.2.0",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    }
+  }
+}
--- a/plugin/calendar/calendar-bridge.d.ts
+++ b/plugin/calendar/calendar-bridge.d.ts
@@ -0,0 +1,124 @@
+/**
+ * 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:
+ *   GET  /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 { CalendarHeartbeatResponse, CalendarSlotResponse, SlotAgentUpdate } 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 declare class CalendarBridgeClient {
+    private baseUrl;
+    private config;
+    private timeoutMs;
+    constructor(config: CalendarBridgeConfig);
+    /**
+     * 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
+     */
+    heartbeat(): Promise<CalendarHeartbeatResponse | 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
+     */
+    updateSlot(slotId: number, update: SlotAgentUpdate): Promise<boolean>;
+    /**
+     * 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
+     */
+    updateVirtualSlot(virtualId: string, update: SlotAgentUpdate): Promise<CalendarSlotResponse | 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)
+     */
+    reportAgentStatus(params: {
+        status: 'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline';
+        recoveryAt?: string;
+        exhaustReason?: 'rate_limit' | 'billing';
+    }): Promise<boolean>;
+    private fetchJson;
+    private postBoolean;
+}
+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 declare function createCalendarBridgeClient(api: {
+    config?: Record<string, unknown>;
+    logger?: {
+        debug?: (...args: unknown[]) => void;
+    };
+}, fallbackUrl: string, agentId: string): CalendarBridgeClient;
+//# sourceMappingURL=calendar-bridge.d.ts.map
--- a/plugin/calendar/calendar-bridge.d.ts.map
+++ b/plugin/calendar/calendar-bridge.d.ts.map
@@ -0,0 +1 @@
+{"version":3,"file":"calendar-bridge.d.ts","sourceRoot":"","sources":["calendar-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAEL,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,EAEhB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,EAAE,oBAAoB;IASxC;;;;;;;;;;;OAWG;IACG,SAAS,IAAI,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAwB5D;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAK3E;;;;;;;;;;OAUG;IACG,iBAAiB,CACrB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAkBvC;;;;;;;;;;;;OAYG;IACG,iBAAiB,CAAC,MAAM,EAAE;QAC9B,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;QAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;KAC1C,GAAG,OAAO,CAAC,OAAO,CAAC;YAcN,SAAS;YAsBT,WAAW;CAsB1B;AASD,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAA;CAAE,EAC5F,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,oBAAoB,CActB"}
--- a/plugin/calendar/calendar-bridge.js
+++ b/plugin/calendar/calendar-bridge.js
@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * 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:
+ *   GET  /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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CalendarBridgeClient = void 0;
+exports.createCalendarBridgeClient = createCalendarBridgeClient;
+class CalendarBridgeClient {
+    baseUrl;
+    config;
+    timeoutMs;
+    constructor(config) {
+        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() {
+        const url = `${this.baseUrl}/calendar/agent/heartbeat`;
+        const body = {
+            claw_identifier: this.config.clawIdentifier,
+            agent_id: this.config.agentId,
+        };
+        try {
+            const response = await this.fetchJson(url, {
+                method: 'GET',
+                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, update) {
+        const url = `${this.baseUrl}/calendar/slots/${slotId}/agent-update`;
+        return this.postBoolean(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, update) {
+        const url = `${this.baseUrl}/calendar/slots/virtual/${encodeURIComponent(virtualId)}/agent-update`;
+        try {
+            const response = await this.fetchJson(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) {
+        const url = `${this.baseUrl}/calendar/agent/status`;
+        const body = {
+            agent_id: this.config.agentId,
+            claw_identifier: this.config.clawIdentifier,
+            ...params,
+        };
+        return this.postBoolean(url, body);
+    }
+    // -------------------------------------------------------------------------
+    // Internal helpers
+    // -------------------------------------------------------------------------
+    async fetchJson(url, init) {
+        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());
+        }
+        catch {
+            clearTimeout(timeout);
+            return null;
+        }
+    }
+    async postBoolean(url, body) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                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;
+        }
+    }
+}
+exports.CalendarBridgeClient = CalendarBridgeClient;
+// ---------------------------------------------------------------------------
+// Utility: build CalendarBridgeConfig from plugin API context
+// ---------------------------------------------------------------------------
+const os_1 = require("os");
+const live_config_1 = require("../core/live-config");
+/**
+ * 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
+ */
+function createCalendarBridgeClient(api, fallbackUrl, agentId) {
+    const baseConfig = (0, live_config_1.getLivePluginConfig)(api, {
+        backendUrl: fallbackUrl,
+        identifier: (0, os_1.hostname)(),
+    });
+    const clawIdentifier = baseConfig.identifier || (0, os_1.hostname)();
+    return new CalendarBridgeClient({
+        backendUrl: baseConfig.backendUrl || fallbackUrl,
+        clawIdentifier,
+        agentId,
+        timeoutMs: 5000,
+    });
+}
+//# sourceMappingURL=calendar-bridge.js.map
--- a/plugin/calendar/calendar-bridge.js.map
+++ b/plugin/calendar/calendar-bridge.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"calendar-bridge.js","sourceRoot":"","sources":["calendar-bridge.ts"],"names":[],"mappings":"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"}
--- a/plugin/calendar/calendar-bridge.ts
+++ b/plugin/calendar/calendar-bridge.ts
@@ -0,0 +1,265 @@
+/**
+ * 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:
+ *   GET  /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: 'GET',
+        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.postBoolean(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.postBoolean(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 postBoolean(url: string, body: unknown): Promise<boolean> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        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 { getLivePluginConfig, type HarborForgeMonitorConfig } from '../core/live-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 = getLivePluginConfig(api, {
+    backendUrl: fallbackUrl,
+    identifier: hostname(),
+  } as HarborForgeMonitorConfig) as HarborForgeMonitorConfig;
+
+  const clawIdentifier = baseConfig.identifier || hostname();
+
+  return new CalendarBridgeClient({
+    backendUrl: baseConfig.backendUrl || fallbackUrl,
+    clawIdentifier,
+    agentId,
+    timeoutMs: 5000,
+  });
+}
--- a/plugin/calendar/index.d.ts
+++ b/plugin/calendar/index.d.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';
+//# sourceMappingURL=index.d.ts.map
--- a/plugin/calendar/index.d.ts.map
+++ b/plugin/calendar/index.d.ts.map
@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC"}
--- a/plugin/calendar/index.js
+++ b/plugin/calendar/index.js
@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * 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();
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./calendar-bridge"), exports);
+__exportStar(require("./scheduler"), exports);
+//# sourceMappingURL=index.js.map
--- a/plugin/calendar/index.js.map
+++ b/plugin/calendar/index.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;;;;;;;;;;;;;;AAEH,0CAAwB;AACxB,oDAAkC;AAClC,8CAA4B"}
--- a/plugin/calendar/index.ts
+++ b/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';
--- a/plugin/calendar/scheduler.d.ts
+++ b/plugin/calendar/scheduler.d.ts
@@ -0,0 +1,235 @@
+/**
+ * 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 { CalendarBridgeClient } from './calendar-bridge';
+import { CalendarSlotResponse, AgentStatusValue } 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;
+}
+/**
+ * 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;
+}
+/**
+ * CalendarScheduler manages the periodic heartbeat and slot execution lifecycle.
+ */
+export declare class CalendarScheduler {
+    private config;
+    private state;
+    private stateFilePath;
+    constructor(config: CalendarSchedulerConfig);
+    /**
+     * Get default state directory (plugin data directory or temp fallback).
+     */
+    private getDefaultStateDir;
+    /**
+     * Persist current state to disk for recovery after restart.
+     */
+    private persistState;
+    /**
+     * Restore state from disk if available.
+     */
+    private restoreState;
+    /**
+     * Clear persisted state file after successful restore.
+     */
+    private clearPersistedState;
+    /**
+     * Send a final heartbeat to the backend before shutdown.
+     */
+    private sendFinalHeartbeat;
+    /**
+     * Handle ScheduledGatewayRestart event.
+     * PLG-CAL-004: Persist state, send final heartbeat, pause scheduled tasks.
+     */
+    private handleScheduledGatewayRestart;
+    /**
+     * Start the calendar scheduler.
+     * Begins periodic heartbeat to check for pending slots.
+     */
+    start(): void;
+    /**
+     * Stop the calendar scheduler.
+     * Cleans up intervals and resets state.
+     */
+    stop(): void;
+    /**
+     * Execute a single heartbeat cycle.
+     * Fetches pending slots and handles execution logic.
+     */
+    runHeartbeat(): Promise<void>;
+    /**
+     * Handle slots when agent is not idle.
+     * Defer all pending slots with priority boost.
+     */
+    private handleNonIdleAgent;
+    /**
+     * Handle slots when agent is idle.
+     * Select highest priority slot and wake agent.
+     */
+    private handleIdleAgent;
+    /**
+     * Check if a slot is a ScheduledGatewayRestart system event.
+     */
+    private isScheduledGatewayRestart;
+    /**
+     * Execute a slot by waking the agent.
+     */
+    private executeSlot;
+    /**
+     * Build the wake context for an agent based on slot details.
+     */
+    private buildWakeContext;
+    /**
+     * Build prompt for job-type slots.
+     */
+    private buildJobPrompt;
+    /**
+     * Build prompt for system event slots.
+     */
+    private buildSystemPrompt;
+    /**
+     * Build prompt for entertainment slots.
+     */
+    private buildEntertainmentPrompt;
+    /**
+     * Build generic prompt for slots without specific event data.
+     */
+    private buildGenericPrompt;
+    /**
+     * Mark a slot as deferred with priority boost.
+     */
+    private deferSlot;
+    /**
+     * Revert a slot to not_started status after failed execution attempt.
+     */
+    private revertSlot;
+    /**
+     * Complete the current slot execution.
+     * Call this when the agent finishes the task.
+     */
+    completeCurrentSlot(actualDurationMinutes: number): Promise<void>;
+    /**
+     * Abort the current slot execution.
+     * Call this when the agent cannot complete the task.
+     */
+    abortCurrentSlot(reason?: string): Promise<void>;
+    /**
+     * Pause the current slot execution.
+     * Call this when the agent needs to temporarily pause.
+     */
+    pauseCurrentSlot(): Promise<void>;
+    /**
+     * Resume a paused slot.
+     */
+    resumeCurrentSlot(): Promise<void>;
+    /**
+     * 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 triggerReplan;
+    /**
+     * Get a stable ID for a slot (real or virtual).
+     */
+    private getSlotId;
+    /**
+     * Format a Date as ISO time string (HH:MM:SS).
+     */
+    private formatTime;
+    /**
+     * Debug logging helper.
+     */
+    private logDebug;
+    /**
+     * Get current scheduler state (for introspection).
+     */
+    getState(): Readonly<SchedulerState>;
+    /**
+     * Check if scheduler is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Check if currently processing a slot.
+     */
+    isProcessing(): boolean;
+    /**
+     * Get the current slot being executed (if any).
+     */
+    getCurrentSlot(): CalendarSlotResponse | null;
+    /**
+     * Check if a gateway restart is pending.
+     */
+    isRestartPending(): boolean;
+    /**
+     * Get the path to the state file.
+     */
+    getStateFilePath(): string;
+}
+/**
+ * Factory function to create a CalendarScheduler from plugin context.
+ */
+export declare function createCalendarScheduler(config: CalendarSchedulerConfig): CalendarScheduler;
+export {};
+//# sourceMappingURL=scheduler.d.ts.map
--- a/plugin/calendar/scheduler.d.ts.map
+++ b/plugin/calendar/scheduler.d.ts.map
@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["scheduler.ts"],"names":[],"mappings":"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"}
--- a/plugin/calendar/scheduler.js
+++ b/plugin/calendar/scheduler.js
@@ -0,0 +1,755 @@
+"use strict";
+/**
+ * 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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CalendarScheduler = void 0;
+exports.createCalendarScheduler = createCalendarScheduler;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const types_1 = require("./types");
+/** 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.
+ */
+class CalendarScheduler {
+    config;
+    state;
+    stateFilePath;
+    constructor(config) {
+        this.config = {
+            heartbeatIntervalMs: 60000, // 1 minute default
+            debug: false,
+            stateDir: this.getDefaultStateDir(),
+            ...config,
+        };
+        this.stateFilePath = (0, path_1.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).
+     */
+    getDefaultStateDir() {
+        // 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,
+            (0, path_1.join)(process.cwd(), '.harborforge'),
+            (0, path_1.join)(process.cwd(), 'data'),
+            '/tmp/harborforge',
+        ];
+        for (const dir of candidates) {
+            if (dir) {
+                try {
+                    if (!(0, fs_1.existsSync)(dir)) {
+                        (0, fs_1.mkdirSync)(dir, { recursive: true });
+                    }
+                    // Test write access
+                    const testFile = (0, path_1.join)(dir, '.write-test');
+                    (0, fs_1.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.
+     */
+    persistState(reason) {
+        try {
+            const 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
+            };
+            (0, fs_1.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.
+     */
+    restoreState() {
+        try {
+            if (!(0, fs_1.existsSync)(this.stateFilePath)) {
+                return;
+            }
+            const data = (0, fs_1.readFileSync)(this.stateFilePath, 'utf-8');
+            const persisted = 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.
+     */
+    clearPersistedState() {
+        try {
+            if ((0, fs_1.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
+                (0, fs_1.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.
+     */
+    async sendFinalHeartbeat(reason) {
+        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.
+     */
+    async handleScheduledGatewayRestart(slot) {
+        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 = {
+            status: types_1.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() {
+        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() {
+        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() {
+        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.
+     */
+    async handleNonIdleAgent(slots, agentStatus) {
+        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.
+     */
+    async handleIdleAgent(slots) {
+        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.
+     */
+    isScheduledGatewayRestart(slot) {
+        if (slot.event_type !== 'system_event' || !slot.event_data) {
+            return false;
+        }
+        const sysData = slot.event_data;
+        return sysData.event === 'ScheduledGatewayRestart';
+    }
+    /**
+     * Execute a slot by waking the agent.
+     */
+    async executeSlot(slot) {
+        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 = {
+                status: types_1.SlotStatus.ONGOING,
+                started_at: this.formatTime(new Date()),
+            };
+            let updateSuccess;
+            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.
+     */
+    buildWakeContext(slot) {
+        const isVirtual = slot.virtual_id !== null;
+        const slotId = this.getSlotId(slot);
+        // Build task description based on event type
+        let taskDescription;
+        let prompt;
+        if (slot.event_type === 'job' && slot.event_data) {
+            const jobData = slot.event_data;
+            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;
+            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.
+     */
+    buildJobPrompt(slot, jobData) {
+        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.
+     */
+    buildSystemPrompt(slot, sysData) {
+        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.
+     */
+    buildEntertainmentPrompt(slot) {
+        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.
+     */
+    buildGenericPrompt(slot) {
+        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.
+     */
+    async deferSlot(slot) {
+        const update = {
+            status: types_1.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.
+     */
+    async revertSlot(slot) {
+        const update = {
+            status: types_1.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) {
+        if (!this.state.currentSlot) {
+            this.config.logger.warn('No current slot to complete');
+            return;
+        }
+        const slot = this.state.currentSlot;
+        const update = {
+            status: types_1.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) {
+        if (!this.state.currentSlot) {
+            this.config.logger.warn('No current slot to abort');
+            return;
+        }
+        const slot = this.state.currentSlot;
+        const update = {
+            status: types_1.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() {
+        if (!this.state.currentSlot) {
+            this.config.logger.warn('No current slot to pause');
+            return;
+        }
+        const slot = this.state.currentSlot;
+        const update = {
+            status: types_1.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() {
+        if (!this.state.currentSlot) {
+            this.config.logger.warn('No current slot to resume');
+            return;
+        }
+        const slot = this.state.currentSlot;
+        const update = {
+            status: types_1.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.
+     */
+    async triggerReplan(reason) {
+        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).
+     */
+    getSlotId(slot) {
+        return slot.id?.toString() || slot.virtual_id || 'unknown';
+    }
+    /**
+     * Format a Date as ISO time string (HH:MM:SS).
+     */
+    formatTime(date) {
+        return date.toTimeString().split(' ')[0];
+    }
+    /**
+     * Debug logging helper.
+     */
+    logDebug(message) {
+        if (this.config.debug) {
+            this.config.logger.debug(`[CalendarScheduler] ${message}`);
+        }
+    }
+    /**
+     * Get current scheduler state (for introspection).
+     */
+    getState() {
+        return { ...this.state };
+    }
+    /**
+     * Check if scheduler is running.
+     */
+    isRunning() {
+        return this.state.isRunning;
+    }
+    /**
+     * Check if currently processing a slot.
+     */
+    isProcessing() {
+        return this.state.isProcessing;
+    }
+    /**
+     * Get the current slot being executed (if any).
+     */
+    getCurrentSlot() {
+        return this.state.currentSlot;
+    }
+    /**
+     * Check if a gateway restart is pending.
+     */
+    isRestartPending() {
+        return this.state.isRestartPending;
+    }
+    /**
+     * Get the path to the state file.
+     */
+    getStateFilePath() {
+        return this.stateFilePath;
+    }
+}
+exports.CalendarScheduler = CalendarScheduler;
+/**
+ * Factory function to create a CalendarScheduler from plugin context.
+ */
+function createCalendarScheduler(config) {
+    return new CalendarScheduler(config);
+}
+//# sourceMappingURL=scheduler.js.map
--- a/plugin/calendar/scheduler.js.map
+++ b/plugin/calendar/scheduler.js.map
--- a/plugin/calendar/scheduler.ts
+++ b/plugin/calendar/scheduler.ts
@@ -0,0 +1,953 @@
+/**
+ * HarborForge Calendar Scheduler
+ *
+ * PLG-CAL-002: Plugin-side handling for pending slot execution.
+ * PLG-CAL-004: ScheduledGatewayRestart event handling with state persistence.
+ *
+ * Responsibilities:
+ *   - Run calendar heartbeat every minute
+ *   - Detect when agent is Idle and slots are pending
+ *   - Wake agent with task context
+ *   - Handle slot status transitions (attended, ongoing, deferred)
+ *   - Manage agent status transitions (idle → busy/on_call)
+ *   - Persist state on ScheduledGatewayRestart and restore on startup
+ *   - Send final heartbeat before graceful shutdown
+ *
+ * Design reference: NEXT_WAVE_DEV_DIRECTION.md §6 (Agent wakeup mechanism)
+ */
+
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { CalendarBridgeClient } from './calendar-bridge';
+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);
+}
--- a/plugin/calendar/types.d.ts
+++ b/plugin/calendar/types.d.ts
@@ -0,0 +1,171 @@
+/**
+ * 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
+ */
+/** Slot type — mirrors backend SlotType enum */
+export declare enum SlotType {
+    WORK = "work",
+    ON_CALL = "on_call",
+    ENTERTAINMENT = "entertainment",
+    SYSTEM = "system"
+}
+/** Slot lifecycle status — mirrors backend SlotStatus enum */
+export declare 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 declare enum EventType {
+    JOB = "job",
+    ENTERTAINMENT = "entertainment",
+    SYSTEM_EVENT = "system_event"
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+    /** 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';
+}
+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';
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map
--- a/plugin/calendar/types.d.ts.map
+++ b/plugin/calendar/types.d.ts.map
@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,gDAAgD;AAChD,oBAAY,QAAQ;IAClB,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,aAAa,kBAAkB;IAC/B,MAAM,WAAW;CAClB;AAED,8DAA8D;AAC9D,oBAAY,UAAU;IACpB,WAAW,gBAAgB;IAC3B,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,OAAO,YAAY;CACpB;AAED,iEAAiE;AACjE,oBAAY,SAAS;IACnB,GAAG,QAAQ;IACX,aAAa,kBAAkB;IAC/B,YAAY,iBAAiB;CAC9B;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,wBAAwB;IACvC,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,oEAAoE;IACpE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB;IAChB,SAAS,EAAE,QAAQ,CAAC;IACpB,2CAA2C;IAC3C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,qBAAqB;IACrB,UAAU,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,uEAAuE;IACvE,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACrC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,MAAM,EAAE,UAAU,CAAC;IACnB,yEAAyE;IACzE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,eAAe,GAAG,cAAc,GAAG,yBAAyB,CAAC;CACrE;AAGD,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,GAAG,4BAA4B,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE1G;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,8DAA8D;IAC9D,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,0CAA0C;IAC1C,YAAY,EAAE,gBAAgB,CAAC;IAC/B,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAMrF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B"}
--- a/plugin/calendar/types.js
+++ b/plugin/calendar/types.js
@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventType = exports.SlotStatus = exports.SlotType = void 0;
+// ---------------------------------------------------------------------------
+// Enums (mirror backend enums)
+// ---------------------------------------------------------------------------
+/** Slot type — mirrors backend SlotType enum */
+var SlotType;
+(function (SlotType) {
+    SlotType["WORK"] = "work";
+    SlotType["ON_CALL"] = "on_call";
+    SlotType["ENTERTAINMENT"] = "entertainment";
+    SlotType["SYSTEM"] = "system";
+})(SlotType || (exports.SlotType = SlotType = {}));
+/** Slot lifecycle status — mirrors backend SlotStatus enum */
+var SlotStatus;
+(function (SlotStatus) {
+    SlotStatus["NOT_STARTED"] = "not_started";
+    SlotStatus["ONGOING"] = "ongoing";
+    SlotStatus["DEFERRED"] = "deferred";
+    SlotStatus["SKIPPED"] = "skipped";
+    SlotStatus["PAUSED"] = "paused";
+    SlotStatus["FINISHED"] = "finished";
+    SlotStatus["ABORTED"] = "aborted";
+})(SlotStatus || (exports.SlotStatus = SlotStatus = {}));
+/** High-level event category — mirrors backend EventType enum */
+var EventType;
+(function (EventType) {
+    EventType["JOB"] = "job";
+    EventType["ENTERTAINMENT"] = "entertainment";
+    EventType["SYSTEM_EVENT"] = "system_event";
+})(EventType || (exports.EventType = EventType = {}));
+//# sourceMappingURL=types.js.map
--- a/plugin/calendar/types.js.map
+++ b/plugin/calendar/types.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AAEH,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E,gDAAgD;AAChD,IAAY,QAKX;AALD,WAAY,QAAQ;IAClB,yBAAa,CAAA;IACb,+BAAmB,CAAA;IACnB,2CAA+B,CAAA;IAC/B,6BAAiB,CAAA;AACnB,CAAC,EALW,QAAQ,wBAAR,QAAQ,QAKnB;AAED,8DAA8D;AAC9D,IAAY,UAQX;AARD,WAAY,UAAU;IACpB,yCAA2B,CAAA;IAC3B,iCAAmB,CAAA;IACnB,mCAAqB,CAAA;IACrB,iCAAmB,CAAA;IACnB,+BAAiB,CAAA;IACjB,mCAAqB,CAAA;IACrB,iCAAmB,CAAA;AACrB,CAAC,EARW,UAAU,0BAAV,UAAU,QAQrB;AAED,iEAAiE;AACjE,IAAY,SAIX;AAJD,WAAY,SAAS;IACnB,wBAAW,CAAA;IACX,4CAA+B,CAAA;IAC/B,0CAA6B,CAAA;AAC/B,CAAC,EAJW,SAAS,yBAAT,SAAS,QAIpB"}
--- a/plugin/calendar/types.ts
+++ b/plugin/calendar/types.ts
@@ -0,0 +1,198 @@
+/**
+ * HarborForge Calendar — Plugin-side type definitions
+ *
+ * PLG-CAL-001: Define the Calendar heartbeat request/response format
+ * between the OpenClaw plugin and HarborForge backend.
+ *
+ * Request flow (plugin → backend):
+ *   POST /calendar/agent/heartbeat
+ *   Headers:
+ *     X-Agent-ID: <agent_id>          — OpenClaw $AGENT_ID of the calling agent
+ *     X-Claw-Identifier: <identifier> — HarborForge server identifier
+ *   Body (JSON):
+ *     { "claw_identifier": "...", "agent_id": "..." }
+ *
+ * Response flow (backend → plugin):
+ *   Returns list of TimeSlots pending execution for today.
+ *   The plugin uses slot.id / slot.virtual_id to update slot status
+ *   via subsequent API calls.
+ *
+ * References:
+ *   • NEXT_WAVE_DEV_DIRECTION.md §6 (Agent wakeup mechanism)
+ *   • HarborForge.Backend/app/models/calendar.py  — TimeSlot DB model
+ *   • HarborForge.Backend/app/schemas/calendar.py — TimeSlot schemas
+ *   • HarborForge.Backend/app/services/agent_heartbeat.py — BE-AGT-001
+ */
+
+// ---------------------------------------------------------------------------
+// Enums (mirror backend enums)
+// ---------------------------------------------------------------------------
+
+/** Slot type — mirrors backend SlotType enum */
+export enum SlotType {
+  WORK = 'work',
+  ON_CALL = 'on_call',
+  ENTERTAINMENT = 'entertainment',
+  SYSTEM = 'system',
+}
+
+/** Slot lifecycle status — mirrors backend SlotStatus enum */
+export enum SlotStatus {
+  NOT_STARTED = 'not_started',
+  ONGOING = 'ongoing',
+  DEFERRED = 'deferred',
+  SKIPPED = 'skipped',
+  PAUSED = 'paused',
+  FINISHED = 'finished',
+  ABORTED = 'aborted',
+}
+
+/** High-level event category — mirrors backend EventType enum */
+export enum EventType {
+  JOB = 'job',
+  ENTERTAINMENT = 'entertainment',
+  SYSTEM_EVENT = 'system_event',
+}
+
+// ---------------------------------------------------------------------------
+// Request types
+// ---------------------------------------------------------------------------
+
+/**
+ * Calendar heartbeat request body sent by the plugin to HarborForge backend.
+ *
+ * How claw_identifier is determined:
+ *   1. Read from plugin config: `config.backendUrl` is the base URL.
+ *   2. If not set, fall back to `os.hostname()` (plugin machine hostname).
+ *
+ * How agent_id is determined:
+ *   - Read from OpenClaw environment variable: `process.env.AGENT_ID`
+ *   - This is set by OpenClaw at agent startup and uniquely identifies
+ *     the running agent instance within a single OpenClaw gateway.
+ */
+export interface CalendarHeartbeatRequest {
+  /** HarborForge server/claw identifier (matches MonitoredServer.identifier) */
+  claw_identifier: string;
+  /** OpenClaw agent ID ($AGENT_ID) for this agent session */
+  agent_id: string;
+}
+
+// ---------------------------------------------------------------------------
+// Response types
+// ---------------------------------------------------------------------------
+
+/**
+ * A single calendar slot returned in the heartbeat response.
+ *
+ * For **real** (materialized) slots: `id` is set, `virtual_id` is null.
+ * For **virtual** (plan-generated) slots: `id` is null, `virtual_id`
+ * is the `plan-{plan_id}-{date}` identifier.
+ *
+ * Key fields the plugin uses:
+ *   - `id` / `virtual_id`  — to update slot status after execution
+ *   - `event_type`          — to determine what action to take
+ *   - `event_data`          — job details / system event type
+ *   - `slot_type`           — work vs on_call (affects agent status transition)
+ *   - `scheduled_at`        — planned start time (HH:MM:SS)
+ *   - `estimated_duration`  — expected minutes (for time-tracking)
+ *   - `priority`            — for multi-slot competition logic
+ *   - `status`              — current status (NotStarted / Deferred)
+ */
+export interface CalendarSlotResponse {
+  /** Real slot DB id. Null for virtual slots. */
+  id: number | null;
+  /** Virtual slot id (plan-{plan_id}-{date}). Null for real slots. */
+  virtual_id: string | null;
+  /** Owner user id */
+  user_id: number;
+  /** Calendar date */
+  date: string; // ISO date string: "YYYY-MM-DD"
+  /** Slot type */
+  slot_type: SlotType;
+  /** Estimated duration in minutes (1-50) */
+  estimated_duration: number;
+  /** Planned start time (ISO time string: "HH:MM:SS") */
+  scheduled_at: string;
+  /** Actual start time, set when slot begins (null until started) */
+  started_at: string | null;
+  /** Whether the slot has been attended */
+  attended: boolean;
+  /** Actual duration in minutes (set when slot finishes) */
+  actual_duration: number | null;
+  /** Event category */
+  event_type: EventType | null;
+  /** Event details JSON — structure depends on event_type (see below) */
+  event_data: CalendarEventData | null;
+  /** Priority 0-99, higher = more urgent */
+  priority: number;
+  /** Current lifecycle status */
+  status: SlotStatus;
+  /** Source plan id if materialized from a SchedulePlan; null otherwise */
+  plan_id: number | null;
+}
+
+/**
+ * Event data stored inside CalendarSlotResponse.event_data.
+ * The shape depends on event_type.
+ *
+ * When event_type == "job":
+ *   { "type": "Task|Support|Meeting|Essential", "code": "TASK-42", "working_sessions": ["..."] }
+ *
+ * When event_type == "system_event":
+ *   { "event": "ScheduleToday|SummaryToday|ScheduledGatewayRestart" }
+ *
+ * When event_type == "entertainment":
+ *   { /* TBD /\ }
+ */
+export interface CalendarEventDataJob {
+  type: 'Task' | 'Support' | 'Meeting' | 'Essential';
+  code: string;
+  working_sessions?: string[];
+}
+
+export interface CalendarEventDataSystemEvent {
+  event: 'ScheduleToday' | 'SummaryToday' | 'ScheduledGatewayRestart';
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type CalendarEventData = CalendarEventDataJob | CalendarEventDataSystemEvent | Record<string, any>;
+
+/**
+ * Full heartbeat response returned by GET /calendar/agent/heartbeat
+ *
+ * Fields:
+ *   slots    — list of pending TimeSlots for today (sorted by priority desc)
+ *   agent_status — current agent status from the backend's perspective
+ *                  (idle | on_call | busy | exhausted | offline)
+ */
+export interface CalendarHeartbeatResponse {
+  /** Pending slots for today — sorted by priority descending */
+  slots: CalendarSlotResponse[];
+  /** Current agent status in HarborForge */
+  agent_status: AgentStatusValue;
+  /** Human-readable message (optional) */
+  message?: string;
+}
+
+/** Agent status values — mirrors backend AgentStatus enum */
+export type AgentStatusValue = 'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline';
+
+// ---------------------------------------------------------------------------
+// Slot update types (for post-execution status updates)
+// ---------------------------------------------------------------------------
+
+/**
+ * Request body for updating a real slot's status after agent execution.
+ * Called by the plugin after attending / finishing / deferring a slot.
+ *
+ * Endpoint: PATCH /calendar/slots/{slot_id}/agent-update
+ * (Plugin-facing variant that bypasses some user-level guards)
+ */
+export interface SlotAgentUpdate {
+  /** New status to set */
+  status: SlotStatus;
+  /** Actual start time (ISO time string HH:MM:SS), required when attending */
+  started_at?: string;
+  /** Actual duration in minutes, set when finishing */
+  actual_duration?: number;
+}
--- a/plugin/index.ts
+++ b/plugin/index.ts
@@ -4,6 +4,9 @@
 * 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.
@@ -11,6 +14,12 @@
 import { hostname, freemem, totalmem, uptime, loadavg, platform } from 'os';
 import { getLivePluginConfig, type HarborForgeMonitorConfig } from './core/live-config';
 import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge';
+import {
+  createCalendarBridgeClient,
+  createCalendarScheduler,
+  CalendarScheduler,
+  AgentWakeContext,
+} from './calendar';

 interface PluginAPI {
  logger: {
@@ -24,6 +33,15 @@ interface PluginAPI {
  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 {
@@ -87,7 +105,7 @@ export default {
        },
        openclaw: {
          version: api.version || 'unknown',
-          pluginVersion: '0.2.0',
+          pluginVersion: '0.3.1', // Bumped for PLG-CAL-004
        },
        timestamp: new Date().toISOString(),
      };
@@ -96,6 +114,9 @@ export default {
    // 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.
@@ -107,7 +128,7 @@ export default {

      const meta: OpenClawMeta = {
        version: api.version || 'unknown',
-        plugin_version: '0.2.0',
+        plugin_version: '0.3.1',
        agents: [], // TODO: populate from api agent list when available
      };

@@ -119,6 +140,170 @@ export default {
      }
    }

+    /**
+     * 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');
+      }
+    }
+
    api.on('gateway_start', () => {
      logger.info('HarborForge plugin active');

@@ -135,14 +320,22 @@ export default {
        () => pushMetaToMonitor(),
        intervalSec * 1000,
      );
+
+      // Start calendar scheduler (delayed to let everything initialize)
+      if (live.enabled !== false) {
+        setTimeout(() => startCalendarScheduler(), 5000);
+      }
    });

    api.on('gateway_stop', () => {
      logger.info('HarborForge plugin stopping');
+
      if (metaPushInterval) {
        clearInterval(metaPushInterval);
        metaPushInterval = null;
      }
+
+      stopCalendarScheduler();
    });

    // Tool: plugin status
@@ -165,6 +358,14 @@ export default {
            : { 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: {
@@ -175,6 +376,7 @@ export default {
            hasApiKey: Boolean(live.apiKey),
          },
          monitorBridge,
+          calendar: calendarStatus,
          telemetry: collectTelemetry(),
        };
      },
@@ -220,6 +422,139 @@ export default {
      },
    }));

+    // 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)');
  },
 };
--- a/plugin/openclaw.plugin.json
+++ b/plugin/openclaw.plugin.json
@@ -8,43 +8,57 @@
    "type": "object",
    "additionalProperties": false,
    "properties": {
-      "enabled": { 
-        "type": "boolean", 
+      "enabled": {
+        "type": "boolean",
        "default": true,
        "description": "Enable the HarborForge plugin"
      },
-      "backendUrl": { 
-        "type": "string", 
+      "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": { 
+      "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."
      },
-      "apiKey": { 
+      "apiKey": {
        "type": "string",
-        "description": "API Key from HarborForge Monitor admin panel (optional but required for authentication)"
+        "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", 
+      "reportIntervalSec": {
+        "type": "number",
        "default": 30,
        "description": "How often to report metrics (seconds)"
      },
-      "httpFallbackIntervalSec": { 
-        "type": "number", 
+      "httpFallbackIntervalSec": {
+        "type": "number",
        "default": 60,
        "description": "HTTP heartbeat interval when WS unavailable"
      },
-      "logLevel": { 
-        "type": "string", 
-        "enum": ["debug", "info", "warn", "error"], 
+      "logLevel": {
+        "type": "string",
+        "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."
      }
    }
  }
Author	SHA1	Message	Date
zhi	3b0ea0ad12	PLG-CAL-004: Implement ScheduledGatewayRestart handling in plugin - Add state persistence (persistState/restoreState) for recovery after restart - Add handleScheduledGatewayRestart method that: - Persists current scheduler state to disk - Sends final heartbeat to backend before shutdown - Stops the calendar scheduler (pauses scheduled tasks) - Add isRestartPending flag to prevent new slot processing during restart - Add isScheduledGatewayRestart helper to detect restart events - Update scheduler to detect and handle ScheduledGatewayRestart events - Add new tools: harborforge_restart_status, harborforge_calendar_pause/resume - Export isRestartPending and getStateFilePath methods - Bump plugin version to 0.3.1	2026-04-01 09:41:02 +00:00
zhi	24c4a7ad14	PLG-CAL-003 fix deferred slot replanning	2026-04-01 08:52:11 +00:00
zhi	97021f97c0	PLG-CAL-002: Implement calendar scheduler for agent slot wakeup - Add CalendarScheduler class to manage periodic heartbeat and slot execution - Implement agent wakeup logic when Idle and slots are pending - Handle slot status transitions (attended, ongoing, deferred) - Support both real and virtual slot materialization - Add task context building for different event types (job, system, entertainment) - Integrate scheduler into main plugin index.ts - Add new plugin tools: harborforge_calendar_status, complete, abort	2026-04-01 08:45:05 +00:00
zhi	55d7d11a52	feat(plugin): PLG-CAL-001 - define Calendar heartbeat request/response format - Add plugin/calendar/types.ts: TypeScript interfaces for heartbeat request/response (CalendarHeartbeatRequest/Response, CalendarSlotResponse, SlotAgentUpdate, all enums: SlotType, SlotStatus, EventType) - Add plugin/calendar/calendar-bridge.ts: CalendarBridgeClient HTTP client with heartbeat(), updateSlot(), updateVirtualSlot(), reportAgentStatus() - Add plugin/calendar/index.ts: module entry point exporting all public types - Add docs/PLG-CAL-001-calendar-heartbeat-format.md: full specification documenting claw_identifier and agent_id determination, request/response shapes, error handling, and endpoint summary - Update plugin/openclaw.plugin.json: add calendarEnabled, calendarHeartbeatIntervalSec, calendarApiKey config options; clarify identifier description as claw_identifier Refs: HarborForge.NEXT_WAVE_DEV_DIRECTION.md §6, BE-AGT-001	2026-04-01 07:51:39 +00:00
				`@@ -0,0 +1 @@`
				{"version":3,"file":"calendar-bridge.d.ts","sourceRoot":"","sources":["calendar-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAEL,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,EAEhB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,EAAE,oBAAoB;IASxC;;;;;;;;;;;OAWG;IACG,SAAS,IAAI,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAwB5D;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAK3E;;;;;;;;;;OAUG;IACG,iBAAiB,CACrB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAkBvC;;;;;;;;;;;;OAYG;IACG,iBAAiB,CAAC,MAAM,EAAE;QAC9B,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;QAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;KAC1C,GAAG,OAAO,CAAC,OAAO,CAAC;YAcN,SAAS;YAsBT,WAAW;CAsB1B;AASD,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAA;CAAE,EAC5F,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,oBAAoB,CActB"}
				`@@ -0,0 +1 @@`
				{"version":3,"file":"calendar-bridge.js","sourceRoot":"","sources":["calendar-bridge.ts"],"names":[],"mappings":"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"}
				`@@ -0,0 +1 @@`
				`{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC"}`
				`@@ -0,0 +1 @@`
				`{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;;;;;;;;;;;;;;AAEH,0CAAwB;AACxB,oDAAkC;AAClC,8CAA4B"}`
				`@@ -0,0 +1 @@`
				{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["scheduler.ts"],"names":[],"mappings":"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"}
				`@@ -0,0 +1 @@`
				{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,gDAAgD;AAChD,oBAAY,QAAQ;IAClB,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,aAAa,kBAAkB;IAC/B,MAAM,WAAW;CAClB;AAED,8DAA8D;AAC9D,oBAAY,UAAU;IACpB,WAAW,gBAAgB;IAC3B,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,OAAO,YAAY;CACpB;AAED,iEAAiE;AACjE,oBAAY,SAAS;IACnB,GAAG,QAAQ;IACX,aAAa,kBAAkB;IAC/B,YAAY,iBAAiB;CAC9B;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,wBAAwB;IACvC,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,oEAAoE;IACpE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB;IAChB,SAAS,EAAE,QAAQ,CAAC;IACpB,2CAA2C;IAC3C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,qBAAqB;IACrB,UAAU,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,uEAAuE;IACvE,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACrC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,MAAM,EAAE,UAAU,CAAC;IACnB,yEAAyE;IACzE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,eAAe,GAAG,cAAc,GAAG,yBAAyB,CAAC;CACrE;AAGD,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,GAAG,4BAA4B,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE1G;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,8DAA8D;IAC9D,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,0CAA0C;IAC1C,YAAY,EAAE,gBAAgB,CAAC;IAC/B,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAMrF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B"}
				`@@ -0,0 +1 @@`
				{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AAEH,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E,gDAAgD;AAChD,IAAY,QAKX;AALD,WAAY,QAAQ;IAClB,yBAAa,CAAA;IACb,+BAAmB,CAAA;IACnB,2CAA+B,CAAA;IAC/B,6BAAiB,CAAA;AACnB,CAAC,EALW,QAAQ,wBAAR,QAAQ,QAKnB;AAED,8DAA8D;AAC9D,IAAY,UAQX;AARD,WAAY,UAAU;IACpB,yCAA2B,CAAA;IAC3B,iCAAmB,CAAA;IACnB,mCAAqB,CAAA;IACrB,iCAAmB,CAAA;IACnB,+BAAiB,CAAA;IACjB,mCAAqB,CAAA;IACrB,iCAAmB,CAAA;AACrB,CAAC,EARW,UAAU,0BAAV,UAAU,QAQrB;AAED,iEAAiE;AACjE,IAAY,SAIX;AAJD,WAAY,SAAS;IACnB,wBAAW,CAAA;IACX,4CAA+B,CAAA;IAC/B,0CAA6B,CAAA;AAC/B,CAAC,EAJW,SAAS,yBAAT,SAAS,QAIpB"}