Merge pull request 'refactor(install): clone HarborForge.Cli to /tmp instead of fixed path' (#12) from refactor/install-cli-clone-from-repo into main

`installCli()` used to look for the CLI source at a fixed path relative
to the plugin checkout: either `./HarborForge.Cli` or `../HarborForge.Cli`.
That breaks any install layout where the plugin lives on its own — the
script just logs "Skipping CLI installation" and returns. Same anti-
pattern installManagedMonitor had already fixed for the monitor binary.

Mirror the monitor flow:

  1. git clone --depth 1 --branch <cliBranch> CLI_REPO_URL → /tmp/<dir>
  2. go build -ldflags Version=<date>+<branch>-<sha> -o $openclaw/bin/hf
  3. chmod 755 + delete tmp dir on success or failure

Adds `--cli-branch <name>` (default: main) for parity with --monitor-branch.

Also stamps the binary with a real version string (was 'dev' before this
patch) so `hf version` is informative for debugging.

.gitignore

@@ -4,3 +4,5 @@ plugin/**/*.js
 plugin/**/*.js.map
 plugin/**/*.d.ts
 plugin/**/*.d.ts.map
+# Hand-written ambient declarations are tracked; only compiled .d.ts above is ignored.
+!plugin/openclaw-sdk.d.ts

REFACTOR_PLAN.md

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

plugin/calendar/calendar-bridge.ts

@@ -29,7 +29,7 @@ import {
   CalendarSlotResponse,
   SlotAgentUpdate,
   SlotStatus,
-} from './types';
+} from './types.js';
 
 export interface CalendarBridgeConfig {
   /** HarborForge backend base URL (e.g. "https://monitor.hangman-lab.top") */
@@ -110,6 +110,23 @@ export class CalendarBridgeClient {
     return this.sendBoolean('PATCH', url, update);
   }
 
+  /**
+   * Same as {@link updateSlot} but overrides the `X-Agent-ID` header for a
+   * single call. Used by the multi-agent scheduler handle where the bridge
+   * client is shared across agents and the constructor agentId is `'unused'`.
+   *
+   * Backend identifies the slot purely by `slotId`; the header is informational
+   * for audit. Passing the calling agent's id keeps audit/log lines correct.
+   */
+  async updateSlotAs(
+    agentId: string,
+    slotId: number,
+    update: SlotAgentUpdate
+  ): Promise<boolean> {
+    const url = `${this.baseUrl}/calendar/slots/${slotId}/agent-update`;
+    return this.sendBooleanAs(agentId, 'PATCH', url, update);
+  }
+
   /**
    * Update a virtual (plan-generated) slot's status after agent execution.
    *
@@ -169,6 +186,74 @@ export class CalendarBridgeClient {
     return this.sendBoolean('POST', url, body);
   }
 
+  /**
+   * Fetch the full day schedule for this agent.
+   *
+   * Unlike heartbeat() which only returns pending (NOT_STARTED/DEFERRED) slots,
+   * this returns ALL slots for the given date, enabling the plugin to maintain
+   * a complete local view of today's schedule.
+   *
+   * @param date  Date string in YYYY-MM-DD format
+   * @returns Array of all slots for the day, or null if unreachable
+   */
+  async getDaySchedule(date: string): Promise<CalendarSlotResponse[] | null> {
+    const url = `${this.baseUrl}/calendar/day?date=${encodeURIComponent(date)}`;
+    try {
+      const response = await this.fetchJson<{ slots: CalendarSlotResponse[] }>(url, {
+        method: 'GET',
+        headers: {
+          'X-Agent-ID': this.config.agentId,
+          'X-Claw-Identifier': this.config.clawIdentifier,
+        },
+      });
+      return response?.slots ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Sync today's schedules for all agents on this claw instance.
+   *
+   * Returns { agentId → slots[] } for all agents with matching claw_identifier.
+   * This is the primary data source for the multi-agent schedule cache.
+   */
+  async syncSchedules(): Promise<{ schedules: Record<string, any[]>; date: string } | null> {
+    const url = `${this.baseUrl}/calendar/sync`;
+    try {
+      const response = await this.fetchJson<{ schedules: Record<string, any[]>; date: string }>(url, {
+        method: 'GET',
+        headers: {
+          'X-Claw-Identifier': this.config.clawIdentifier,
+        },
+      });
+      return response;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get a specific agent's status.
+   *
+   * @param agentId  The agent ID to query
+   */
+  async getAgentStatus(agentId: string): Promise<string | null> {
+    const url = `${this.baseUrl}/calendar/agent/status?agent_id=${encodeURIComponent(agentId)}`;
+    try {
+      const response = await this.fetchJson<{ status: string }>(url, {
+        method: 'GET',
+        headers: {
+          'X-Agent-ID': agentId,
+          'X-Claw-Identifier': this.config.clawIdentifier,
+        },
+      });
+      return response?.status ?? null;
+    } catch {
+      return null;
+    }
+  }
+
   // -------------------------------------------------------------------------
   // Internal helpers
   // -------------------------------------------------------------------------
@@ -196,6 +281,15 @@ export class CalendarBridgeClient {
   }
 
   private async sendBoolean(method: 'POST' | 'PATCH', url: string, body: unknown): Promise<boolean> {
+    return this.sendBooleanAs(this.config.agentId, method, url, body);
+  }
+
+  private async sendBooleanAs(
+    agentId: string,
+    method: 'POST' | 'PATCH',
+    url: string,
+    body: unknown
+  ): Promise<boolean> {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
 
@@ -204,7 +298,7 @@ export class CalendarBridgeClient {
         method,
         headers: {
           'Content-Type': 'application/json',
-          'X-Agent-ID': this.config.agentId,
+          'X-Agent-ID': agentId,
           'X-Claw-Identifier': this.config.clawIdentifier,
         },
         body: JSON.stringify(body),
@@ -224,7 +318,7 @@ export class CalendarBridgeClient {
 // ---------------------------------------------------------------------------
 
 import { hostname } from 'os';
-import { getPluginConfig } from '../core/config';
+import { getPluginConfig } from '../core/config.js';
 
 export interface CalendarPluginConfig {
   /** Backend URL for calendar API (overrides monitor backendUrl) */

plugin/calendar/index.ts

@@ -13,7 +13,7 @@
  *   • AgentWakeContext — context passed to agent when waking
  *
  * Usage in plugin/index.ts:
- *   import { createCalendarBridgeClient, createCalendarScheduler } from './calendar';
+ *   import { createCalendarBridgeClient, createCalendarScheduler } from './calendar.js';
  *
  *   const agentId = process.env.AGENT_ID || 'unknown';
  *   const calendar = createCalendarBridgeClient(api, 'https://monitor.hangman-lab.top', agentId);
@@ -28,6 +28,7 @@
  *   scheduler.start();
  */
 
-export * from './types';
+export * from './types.js';
-export * from './calendar-bridge';
+export * from './calendar-bridge.js';
-export * from './scheduler';
+export * from './scheduler.js';
+export * from './schedule-cache.js';

plugin/calendar/multi-agent-handle.ts

@@ -0,0 +1,240 @@
+/**
+ * MultiAgentSchedulerHandle — runtime façade that backs the public
+ * `harborforge_calendar_*` tools when the plugin runs in multi-agent sync
+ * mode.
+ *
+ * Background
+ * ----------
+ * The old single-agent path used `CalendarScheduler` which kept a "current
+ * slot" cursor and exposed `isRunning() / completeCurrentSlot() / abortCurrentSlot() / …`.
+ * In multi-agent mode the plugin doesn't own a single cursor — one plugin
+ * instance services every agent on the claw — so the previous code stubbed the
+ * `calendarScheduler` variable to `{ stop() }`. That made every tool fail
+ * with `calendarScheduler.<method> is not a function`.
+ *
+ * This handle restores the same surface area (`isRunning / getCurrentSlot /
+ * completeCurrentSlot / …`) but resolves the "current slot" per caller via
+ * the agentId/sessionKey supplied by the OpenClaw tool-factory context. The
+ * scheduler records the slot it just dispatched to each agent in
+ * {@link recordWoken}; the tool resolves the caller, looks up the last woken
+ * slot, and PATCHes the backend via the shared bridge.
+ *
+ * Tools must pass the calling agentId (from `OpenClawPluginToolContext.agentId`)
+ * into every method. The handle does not consult `process.env.AGENT_ID` — the
+ * gateway sets that to the host's primary agent which is meaningless in
+ * multi-agent mode.
+ */
+
+import type { CalendarBridgeClient } from './calendar-bridge.js';
+import type { MultiAgentScheduleCache, CachedSlot } from './schedule-cache.js';
+import { SlotStatus } from './types.js';
+
+export interface MultiAgentSchedulerHandleParams {
+  bridge: CalendarBridgeClient;
+  cache: MultiAgentScheduleCache;
+  /** setInterval handles cleared on stop() */
+  syncHandle: ReturnType<typeof setInterval>;
+  checkHandle: ReturnType<typeof setInterval>;
+  logger: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+  };
+}
+
+/** Last slot we dispatched to an agent. Used as the implicit "current slot". */
+export interface WokenSlot {
+  agentId: string;
+  slotId: number | null;
+  virtualId: string | null;
+  scheduledAt: string | null;
+  slotType: string | null;
+  estimatedDuration: number | null;
+  wokenAt: string;
+}
+
+/** Public surface — mirrors the relevant subset of the old single-agent scheduler. */
+export class MultiAgentSchedulerHandle {
+  private readonly bridge: CalendarBridgeClient;
+  private readonly cache: MultiAgentScheduleCache;
+  private readonly syncHandle: ReturnType<typeof setInterval>;
+  private readonly checkHandle: ReturnType<typeof setInterval>;
+  private readonly logger: MultiAgentSchedulerHandleParams['logger'];
+  private readonly woken: Map<string, WokenSlot> = new Map();
+  private stopped = false;
+
+  constructor(params: MultiAgentSchedulerHandleParams) {
+    this.bridge = params.bridge;
+    this.cache = params.cache;
+    this.syncHandle = params.syncHandle;
+    this.checkHandle = params.checkHandle;
+    this.logger = params.logger;
+  }
+
+  // ---------- lifecycle ----------
+
+  /** True while the sync/check intervals are still ticking. */
+  isRunning(): boolean {
+    return !this.stopped;
+  }
+
+  /** Always false in multi-agent mode — there is no per-instance work queue. */
+  isProcessing(): boolean {
+    return false;
+  }
+
+  stop(): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    clearInterval(this.syncHandle);
+    clearInterval(this.checkHandle);
+    this.logger.info('Calendar scheduler stopped (multi-agent mode)');
+  }
+
+  // ---------- wake bookkeeping ----------
+
+  /** Record that we just dispatched a slot to `agentId`. */
+  recordWoken(agentId: string, slot: CachedSlot): void {
+    this.woken.set(agentId, {
+      agentId,
+      slotId: typeof slot.id === 'number' ? slot.id : null,
+      virtualId: typeof slot.virtual_id === 'string' ? slot.virtual_id : null,
+      scheduledAt: typeof slot.scheduled_at === 'string' ? slot.scheduled_at : null,
+      slotType: typeof slot.slot_type === 'string' ? slot.slot_type : null,
+      estimatedDuration:
+        typeof slot.estimated_duration === 'number' ? slot.estimated_duration : null,
+      wokenAt: new Date().toISOString(),
+    });
+  }
+
+  // ---------- per-agent reads ----------
+
+  /**
+   * The slot most recently dispatched to `agentId`, or null if we never woke
+   * them (e.g. tool called outside a wakeup). Callers can fall back to
+   * scanning {@link cachedSlotsFor} for `not_started`/`deferred` slots if they
+   * want a heuristic "current".
+   */
+  getWokenSlot(agentId: string | null | undefined): WokenSlot | null {
+    if (!agentId) return null;
+    return this.woken.get(agentId) ?? null;
+  }
+
+  /** Today's cached slots for an agent (whatever runSync last pulled). */
+  cachedSlotsFor(agentId: string | null | undefined): CachedSlot[] {
+    if (!agentId) return [];
+    return this.cache.getAgentSlots(agentId);
+  }
+
+  /**
+   * Implicit "current" slot: the last woken slot if we know about it,
+   * otherwise the highest-priority `not_started`/`deferred`/`ongoing` cached
+   * slot for the agent (so a tool called between sync windows still finds
+   * something sensible).
+   */
+  resolveCurrentSlot(agentId: string | null | undefined): WokenSlot | null {
+    const woken = this.getWokenSlot(agentId);
+    if (woken) return woken;
+    if (!agentId) return null;
+    const slots = this.cache.getAgentSlots(agentId)
+      .filter((s) => s.status === 'not_started' || s.status === 'deferred' || s.status === 'ongoing')
+      .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    const top = slots[0];
+    if (!top) return null;
+    return {
+      agentId,
+      slotId: typeof top.id === 'number' ? top.id : null,
+      virtualId: typeof top.virtual_id === 'string' ? top.virtual_id : null,
+      scheduledAt: typeof top.scheduled_at === 'string' ? top.scheduled_at : null,
+      slotType: typeof top.slot_type === 'string' ? top.slot_type : null,
+      estimatedDuration:
+        typeof top.estimated_duration === 'number' ? top.estimated_duration : null,
+      wokenAt: 'inferred-from-cache',
+    };
+  }
+
+  // ---------- per-agent writes ----------
+
+  async completeSlot(agentId: string, actualDurationMinutes: number): Promise<SlotMutationResult> {
+    return this.transition(agentId, SlotStatus.FINISHED, { actual_duration: actualDurationMinutes });
+  }
+
+  async abortSlot(agentId: string, reason?: string): Promise<SlotMutationResult> {
+    if (reason) this.logger.info(`Aborting slot for ${agentId}: ${reason}`);
+    return this.transition(agentId, SlotStatus.ABORTED);
+  }
+
+  async pauseSlot(agentId: string): Promise<SlotMutationResult> {
+    return this.transition(agentId, SlotStatus.PAUSED);
+  }
+
+  /** Resume puts the slot back into `ongoing` so it isn't picked up as `not_started`. */
+  async resumeSlot(agentId: string): Promise<SlotMutationResult> {
+    return this.transition(agentId, SlotStatus.ONGOING);
+  }
+
+  private async transition(
+    agentId: string,
+    status: SlotStatus,
+    extra: { actual_duration?: number } = {}
+  ): Promise<SlotMutationResult> {
+    const slot = this.resolveCurrentSlot(agentId);
+    if (!slot) {
+      return { ok: false, error: `No tracked slot for agent '${agentId}'` };
+    }
+    if (slot.slotId == null && slot.virtualId == null) {
+      return { ok: false, error: 'Resolved slot has neither id nor virtual_id' };
+    }
+    const update = { status, ...extra };
+    try {
+      if (slot.slotId != null) {
+        const ok = await this.bridge.updateSlotAs(agentId, slot.slotId, update);
+        if (!ok) return { ok: false, error: `Backend rejected slot ${slot.slotId} → ${status}` };
+        // Clear the wake cursor only on terminal transitions so re-wakes don't
+        // re-trigger the same slot mutation.
+        if (status === SlotStatus.FINISHED || status === SlotStatus.ABORTED) {
+          this.woken.delete(agentId);
+        }
+        return { ok: true, slot, status };
+      }
+      // virtual slot path: bridge has updateVirtualSlot
+      const materialised = await this.bridge.updateVirtualSlot(slot.virtualId!, update);
+      if (!materialised) {
+        return { ok: false, error: `Backend rejected virtual slot ${slot.virtualId}` };
+      }
+      if (status === SlotStatus.FINISHED || status === SlotStatus.ABORTED) {
+        this.woken.delete(agentId);
+      }
+      return { ok: true, slot, status, materialised };
+    } catch (err: unknown) {
+      const msg = (err as { message?: string } | undefined)?.message ?? String(err);
+      return { ok: false, error: msg };
+    }
+  }
+
+  // ---------- gateway-restart parity (no-op in multi-agent mode) ----------
+
+  /** Multi-agent scheduler does not persist a `ScheduledGatewayRestart` flag. */
+  isRestartPending(): boolean {
+    return false;
+  }
+  getStateFilePath(): string | null {
+    return null;
+  }
+  getState(): { mode: 'multi-agent'; agents: number; lastWoken: WokenSlot[] } {
+    return {
+      mode: 'multi-agent',
+      agents: this.cache.getStatus().agentCount,
+      lastWoken: Array.from(this.woken.values()),
+    };
+  }
+}
+
+export interface SlotMutationResult {
+  ok: boolean;
+  error?: string;
+  status?: SlotStatus;
+  slot?: WokenSlot;
+  /** Present only when a virtual slot was materialised. */
+  materialised?: unknown;
+}

plugin/calendar/schedule-cache.ts

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

plugin/calendar/scheduler.ts

@@ -18,7 +18,7 @@
 
 import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
-import { CalendarBridgeClient } from './calendar-bridge';
+import { CalendarBridgeClient } from './calendar-bridge.js';
 import {
   CalendarSlotResponse,
   SlotStatus,
@@ -26,7 +26,7 @@ import {
   SlotAgentUpdate,
   CalendarEventDataJob,
   CalendarEventDataSystemEvent,
-} from './types';
+} from './types.js';
 
 export interface CalendarSchedulerConfig {
   /** Calendar bridge client for backend communication */

plugin/core/openclaw-agents.ts

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

plugin/hooks/gateway-start.ts

@@ -1,6 +1,6 @@
 import { hostname } from 'os';
-import { getPluginConfig } from '../core/config';
+import { getPluginConfig } from '../core/config.js';
-import { startManagedMonitor } from '../core/managed-monitor';
+import { startManagedMonitor } from '../core/managed-monitor.js';
 
 export function registerGatewayStartHook(api: any, deps: {
   logger: any;

plugin/hooks/gateway-stop.ts

@@ -1,4 +1,4 @@
-import { stopManagedMonitor } from '../core/managed-monitor';
+import { stopManagedMonitor } from '../core/managed-monitor.js';
 
 export function registerGatewayStopHook(api: any, deps: {
   logger: any;

plugin/index.ts

@@ -11,18 +11,38 @@
  * served directly by the plugin when Monitor queries via the
  * local monitor_port communication path.
  */
-import { hostname, freemem, totalmem, uptime, loadavg, platform } from 'os';
+import { hostname, freemem, totalmem, uptime, loadavg, platform } from 'node:os';
-import { getPluginConfig } from './core/config';
+import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
-import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge';
+import { MultiAgentScheduleCache } from './calendar/schedule-cache.js';
-import { listOpenClawAgents } from './core/openclaw-agents';
+import { MultiAgentSchedulerHandle } from './calendar/multi-agent-handle.js';
-import { registerGatewayStartHook } from './hooks/gateway-start';
+import { getPluginConfig } from './core/config.js';
-import { registerGatewayStopHook } from './hooks/gateway-stop';
+import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge.js';
+import type { OpenClawAgentInfo } from './core/openclaw-agents.js';
+import { registerGatewayStartHook } from './hooks/gateway-start.js';
+import { registerGatewayStopHook } from './hooks/gateway-stop.js';
 import {
   createCalendarBridgeClient,
-  createCalendarScheduler,
   CalendarScheduler,
-  AgentWakeContext,
+} from './calendar/index.js';
-} from './calendar';
+
+// ---------------------------------------------------------------------------
+// Module-scope calendar scheduler singleton.
+//
+// `register()` is called multiple times per gateway boot — once per agent
+// (we see 5 `HarborForge plugin registered` lines for 5 agents on dind-t2).
+// `gateway_start` only fires once, so before this lift the
+// `startCalendarScheduler()` setup ran inside ONE closure while four other
+// closures kept their own `calendarScheduler = null`. Whichever of the five
+// tool registrations the gateway picked at call time was effectively a coin
+// flip, and four times out of five `harborforge_calendar_status` returned
+// `Calendar scheduler not running` even though the scheduler was active.
+//
+// Keeping the singleton at module scope removes the per-`register()` shadow:
+// the scheduler is started once, every closure reads the same binding, and
+// `startCalendarScheduler()` is idempotent so duplicate `gateway_start`
+// firings are harmless.
+// ---------------------------------------------------------------------------
+let calendarScheduler: MultiAgentSchedulerHandle | CalendarScheduler | null = null;
 
 interface PluginAPI {
   logger: {
@@ -32,6 +52,12 @@ interface PluginAPI {
     warn: (...args: any[]) => void;
   };
   version?: string;
+  runtime?: {
+    version?: string;
+    config?: {
+      loadConfig?: () => any;
+    };
+  };
   config?: Record<string, unknown>;
   pluginConfig?: Record<string, unknown>;
   on: (event: string, handler: () => void) => void;
@@ -47,10 +73,31 @@ interface PluginAPI {
   getAgentStatus?: () => Promise<{ status: string } | null>;
 }
 
-export default {
+/**
-  id: 'harbor-forge',
+ * Coerce a tool execute() return value into the MCP `{ content: [...] }`
-  name: 'HarborForge',
+ * shape that the openclaw Codex tool dispatcher requires.
-  register(api: PluginAPI) {
+ *
+ * Background: openclaw's `convertToolContents()` does `result.content.reduce(...)`
+ * to compute total text length before flattening. Every HF tool here returned a
+ * bare object (`{ running, processing, currentSlot, ... }`) which has no
+ * `.content` field, so `undefined.reduce` threw and every call to
+ * `harborforge_*` from a Codex-harness agent surfaced as the cryptic
+ * `Cannot read properties of undefined (reading 'reduce')`. The fix is to
+ * wrap every tool's execute return; doing it at the `registerTool` boundary
+ * keeps each tool body unchanged.
+ */
+function ensureMcpContentShape(result: unknown): { content: Array<{ type: 'text'; text: string }> } {
+  if (
+    result && typeof result === 'object' &&
+    Array.isArray((result as { content?: unknown }).content)
+  ) {
+    return result as { content: Array<{ type: 'text'; text: string }> };
+  }
+  const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+  return { content: [{ type: 'text', text }] };
+}
+
+function register(api: PluginAPI): void {
     const logger = api.logger || {
       info: (...args: any[]) => console.log('[HarborForge]', ...args),
       error: (...args: any[]) => console.error('[HarborForge]', ...args),
@@ -58,10 +105,35 @@ export default {
       warn: (...args: any[]) => console.warn('[HarborForge]', ...args),
     };
 
+    // Wrap api.registerTool so every tool's execute() return is coerced into
+    // the MCP `{ content: [...] }` shape openclaw expects. See
+    // `ensureMcpContentShape` above.
+    const _origRegisterTool = api.registerTool.bind(api);
+    api.registerTool = (factory: (ctx: any) => any) => {
+      _origRegisterTool((ctx: any) => {
+        const def = factory(ctx);
+        if (!def || typeof def.execute !== 'function') return def;
+        const origExecute = def.execute;
+        return {
+          ...def,
+          execute: async (...args: any[]) => ensureMcpContentShape(await origExecute(...args)),
+        };
+      });
+    };
+
     function resolveConfig() {
       return getPluginConfig(api);
     }
 
+    /** Resolve agent ID from env, config, or fallback. */
+    function resolveAgentId(): string {
+      if (process.env.AGENT_ID) return process.env.AGENT_ID;
+      // Read from cached `api.config` first — see pushMetaToMonitor for why
+      // the deprecated `api.runtime?.config?.loadConfig?.()` path is heavy.
+      const cfg = (api as any).config ?? api.runtime?.config?.loadConfig?.();
+      return cfg?.agents?.list?.[0]?.id ?? cfg?.agents?.defaults?.id ?? 'unknown';
+    }
+
     /**
      * Get the monitor bridge client if monitor_port is configured.
      */
@@ -96,8 +168,8 @@ export default {
           avg15: load[2],
         },
         openclaw: {
-          version: api.version || 'unknown',
+          version: api.runtime?.version || api.version || 'unknown',
-          pluginVersion: '0.3.1', // Bumped for PLG-CAL-004
+          pluginVersion: '0.3.4', // Bumped for PLG-CAL-004
         },
         timestamp: new Date().toISOString(),
       };
@@ -106,22 +178,53 @@ export default {
     // Periodic metadata push interval handle
     let metaPushInterval: ReturnType<typeof setInterval> | null = null;
 
-    // Calendar scheduler instance
+    // (calendarScheduler is module-scope — see top of file for the why.
-    let calendarScheduler: CalendarScheduler | null = null;
+    //  Tools and lifecycle hooks all reference the same binding so the
+    //  multi-register/single-start mismatch can't shadow them again.)
 
     /**
      * Push OpenClaw metadata to the Monitor bridge.
      * This enriches Monitor heartbeats with OpenClaw version/plugin/agent info.
      * Failures are non-fatal — Monitor continues to work without this data.
+     *
+     * IMPORTANT — read config from the cached `api.config` surface, NOT from
+     * the deprecated `api.runtime?.config?.loadConfig?.()` path. The
+     * deprecated path triggers a full plugin-metadata-snapshot rebuild on
+     * every call: realpathSync walks every plugin's package.json + manifest
+     * + source paths (lstats up the directory tree), `hashWatchedFiles`
+     * fingerprints all watched plugin files, and `discoverInDirectory`
+     * re-scans every `dist/extensions/<plugin>` dir. On t2 with ~100 plugins
+     * each rebuild costs ~6-7s of CPU; with this push firing every 30s
+     * (default reportIntervalSec) the chronic baseline was ~22-25% gateway
+     * CPU even with zero agent activity (V8 profile 2026-05-27 08:14:00 60s:
+     * lstat 44.2%, statSync 6.9%, hashWatchedFiles via memo key 1.7%, all
+     * routed through readPersistedInstalledPluginIndexInstallRecordsSync ->
+     * discoverInDirectory). Switching to `api.config` reads from the
+     * already-loaded snapshot cache; the elsewhere-in-this-file pattern was
+     * already `api.config ?? api.runtime?.config?.loadConfig?.()`.
+     *
+     * Same fix is applied to `resolveAgentId` below — that's read once at
+     * gateway start so the impact is smaller, but it's the same anti-pattern.
      */
     async function pushMetaToMonitor() {
       const bridgeClient = getBridgeClient();
       if (!bridgeClient) return;
 
+      let agentNames: string[] = [];
+      try {
+        const cfg = (api as any).config ?? api.runtime?.config?.loadConfig?.();
+        const agentsList = cfg?.agents?.list;
+        if (Array.isArray(agentsList)) {
+          agentNames = agentsList
+            .map((a: any) => typeof a === 'string' ? a : a?.name)
+            .filter(Boolean);
+        }
+      } catch { /* non-fatal */ }
+
       const meta: OpenClawMeta = {
-        version: api.version || 'unknown',
+        version: api.runtime?.version || api.version || 'unknown',
-        plugin_version: '0.3.1',
+        plugin_version: '0.3.4',
-        agents: await listOpenClawAgents(logger),
+        agents: agentNames.map(name => ({ name })),
       };
 
       const ok = await bridgeClient.pushOpenClawMeta(meta);
@@ -151,7 +254,7 @@ export default {
 
       // Fallback: query backend for agent status
       const live = resolveConfig();
-      const agentId = process.env.AGENT_ID || 'unknown';
+      const agentId = resolveAgentId();
       try {
         const response = await fetch(`${live.backendUrl}/calendar/agent/status?agent_id=${agentId}`, {
           headers: {
@@ -171,118 +274,310 @@ export default {
     }
 
     /**
-     * Wake/spawn agent with task context for slot execution.
+     * Wake agent via dispatchInboundMessage — same mechanism used by Discord plugin.
-     * This is the callback invoked by CalendarScheduler when a slot is ready.
+     * Direct in-process call, no WebSocket or CLI needed.
      */
-    async function wakeAgent(context: AgentWakeContext): Promise<boolean> {
+    async function wakeAgent(
-      logger.info(`Waking agent for slot: ${context.taskDescription}`);
+      agentId: string,
+      dueSlots?: Array<{
+        id?: number | null;
+        virtual_id?: string | null;
+        event_data?: any;
+        scheduled_at?: string;
+        priority?: number;
+        slot_type?: string;
+        [k: string]: unknown;
+      }>
+    ): Promise<boolean> {
+      logger.info(`Waking agent ${agentId}: has due slots`);
+
+      const sessionKey = `agent:${agentId}:hf-wakeup`;
 
       try {
-        // Method 1: Use OpenClaw spawn API if available (preferred)
+        const sdkPath = 'openclaw/plugin-sdk/reply-runtime';
-        if (api.spawn) {
+        const { dispatchInboundMessageWithDispatcher } = await import(
-          const result = await api.spawn({
+          /* webpackIgnore: true */ sdkPath
-            task: context.prompt,
+        );
-            timeoutSeconds: context.slot.estimated_duration * 60, // Convert to seconds
-          });
 
-          if (result?.sessionId) {
+        // api.config first (current public API). Fall back to deprecated
-            logger.info(`Agent spawned for calendar slot: session=${result.sessionId}`);
+        // runtime.config.loadConfig() for older host versions. Both should
-
+        // contain agents.list / channels for dispatch routing.
-            // Track session completion
+        const cfg = (api as any).config ?? api.runtime?.config?.loadConfig?.();
-            trackSessionCompletion(result.sessionId, context);
+        if (!cfg) {
-            return true;
+          logger.error('Cannot load OpenClaw config for dispatch');
-          }
+          return false;
         }
 
-        // Method 2: Send notification/alert to wake agent (fallback)
+        // Inline the highest-priority due slot's context so the agent does
-        // This relies on the agent's heartbeat to check for notifications
+        // not need a second round-trip to harborforge_calendar_status. The
-        logger.warn('OpenClaw spawn API not available, using notification fallback');
+        // agent can read event_data.task_code / task_title etc. directly.
-
+        let slotBlock = '';
-        // Send calendar wakeup notification via backend
+        const top = dueSlots && dueSlots.length ? dueSlots[0] : undefined;
-        const live = resolveConfig();
+        if (top) {
-        const agentId = process.env.AGENT_ID || 'unknown';
+          slotBlock = `\n\nMatching slot:\n\`\`\`json\n${JSON.stringify(
-
+            {
-        const notifyResponse = await fetch(`${live.backendUrl}/calendar/agent/notify`, {
+              slot_id: top.id ?? null,
-          method: 'POST',
+              virtual_id: top.virtual_id ?? null,
-          headers: {
+              scheduled_at: top.scheduled_at ?? null,
-            'Content-Type': 'application/json',
+              priority: top.priority ?? null,
-            'X-Agent-ID': agentId,
+              slot_type: top.slot_type ?? null,
-            'X-Claw-Identifier': live.identifier || hostname(),
+              event_data: top.event_data ?? null,
+            },
+            null,
+            2
+          )}\n\`\`\``;
+        }
+
+        // The wakeup dispatcher's `deliver` callback below only logs the
+        // reply text — it does NOT inspect any ack token. The earlier
+        // `WAKEUP_OK` first-line-ack convention was prompt-only theatre;
+        // nothing in this plugin or in openclaw acted on it. The only
+        // thing that ends a wake cycle is the slot transitioning out of
+        // `not_started`, which happens when the agent calls
+        // `harborforge_calendar_complete` or `harborforge_calendar_abort`.
+        // Tell the agent that plainly instead of asking for a fake ack.
+        const wakeupMessage =
+          `You have due slots. Drive the \`hf-wakeup\` workflow of skill ` +
+          `\`hf-hangman-lab\` to completion in this session — read slot ` +
+          `context, call the harborforge_calendar_* tools, route to the ` +
+          `right sub-workflow, and finish with harborforge_calendar_complete ` +
+          `or harborforge_calendar_abort. The scheduler keeps re-waking you ` +
+          `every 30s until the slot transitions out of \`not_started\`, so ` +
+          `partial work or silence just produces another wake.${slotBlock}`;
+
+        const result = await dispatchInboundMessageWithDispatcher({
+          ctx: {
+            Body: wakeupMessage,
+            SessionKey: sessionKey,
+            From: 'harborforge-calendar',
+            Provider: 'harborforge',
+          },
+          cfg,
+          dispatcherOptions: {
+            deliver: async (payload: any) => {
+              const text = (payload.text || '').trim();
+              logger.info(`Agent ${agentId} wakeup reply: ${text.slice(0, 100)}`);
+            },
           },
-          body: JSON.stringify({
-            agent_id: agentId,
-            message: context.prompt,
-            slot_id: context.slot.id || context.slot.virtual_id,
-            task_description: context.taskDescription,
-          }),
         });
 
-        return notifyResponse.ok;
+        logger.info(`Agent ${agentId} dispatched: ${result?.status || 'ok'}`);
+        return true;
 
-      } catch (err) {
+      } catch (err: any) {
-        logger.error('Failed to wake agent:', err);
+        const msg = err?.message || err?.code || String(err);
+        const stack = err?.stack?.split('\n').slice(0, 3).join(' | ') || '';
+        logger.error(`Failed to dispatch agent for slot: ${msg} ${stack}`);
         return false;
       }
     }
 
-    /**
+    // (trackSessionCompletion removed — legacy single-agent poll loop that
-     * Track session completion and update slot status accordingly.
+    //  called calendarScheduler.completeCurrentSlot. The multi-agent path
-     */
+    //  closes slots via the harborforge_calendar_complete tool, driven by
-    function trackSessionCompletion(sessionId: string, context: AgentWakeContext): void {
+    //  the agent itself, not by a timer.)
-      // 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.
+     *
+     * Idempotent — `gateway_start` may fire once per `register()` invocation
+     * (the host calls `register` per agent), and we only want one set of
+     * sync/check intervals across the whole process.
      */
     function startCalendarScheduler(): void {
+      if (calendarScheduler) {
+        logger.info('Calendar scheduler already started, skipping duplicate gateway_start');
+        return;
+      }
       const live = resolveConfig();
-      const agentId = process.env.AGENT_ID || 'unknown';
 
-      // Create calendar bridge client
+      // Create bridge client (claw-instance level, not per-agent)
       const calendarBridge = createCalendarBridgeClient(
         api,
         live.backendUrl || 'https://monitor.hangman-lab.top',
-        agentId
+        'unused' // agentId no longer needed at bridge level
       );
 
-      // Create and start scheduler
+      // Multi-agent sync + check loop
-      calendarScheduler = createCalendarScheduler({
+      const scheduleCache = new MultiAgentScheduleCache();
+
+      const SYNC_INTERVAL_MS = 300_000; // 5 min
+      const CHECK_INTERVAL_MS = 30_000; // 30 sec
+
+      // Sync: pull all agent schedules from backend
+      async function runSync() {
+        try {
+          const result = await calendarBridge.syncSchedules();
+          if (result) {
+            scheduleCache.sync(result.date, result.schedules);
+            const status = scheduleCache.getStatus();
+            logger.info(`Schedule synced: ${status.agentCount} agents, ${status.totalSlots} slots`);
+          }
+        } catch (err) {
+          logger.warn(`Schedule sync failed: ${String(err)}`);
+        }
+      }
+
+      // Cross-plugin exposure: agent status lookup for other plugins
+      // (currently Fabric.OpenclawPlugin uses this to skip delivering
+      // `announce` channel messages to busy agents — see DIALECTIC-V2
+      // design doc, Phase 1). Backed by calendarBridge.getAgentStatus
+      // with a small TTL cache to avoid hammering the HF backend.
+      type HfStatus = 'idle' | 'on_call' | 'busy' | 'exhausted' | 'offline';
+      const HF_STATUS_CACHE_TTL_MS = 30_000;
+      const hfStatusCache = new Map<string, { status: HfStatus; at: number }>();
+      const _G = globalThis as Record<string, unknown>;
+      _G['__hfAgentStatus'] = {
+        async get(agentId: string): Promise<HfStatus | undefined> {
+          if (!agentId) return undefined;
+          const cached = hfStatusCache.get(agentId);
+          if (cached && Date.now() - cached.at < HF_STATUS_CACHE_TTL_MS) {
+            return cached.status;
+          }
+          try {
+            const status = await calendarBridge.getAgentStatus(agentId);
+            if (status) {
+              const typed = status as HfStatus;
+              hfStatusCache.set(agentId, { status: typed, at: Date.now() });
+              return typed;
+            }
+          } catch {
+            /* fall through to cached-or-undefined */
+          }
+          return cached?.status;
+        },
+
+        /**
+         * Approximate "does agent have an on_call slot covering [from, to]?"
+         * for cross-plugin pre-check use (currently:
+         * Dialectic.OpenclawPlugin's signup HF coverage).
+         *
+         * v1 honest scope: we only have today's slots in scheduleCache
+         * (synced from /calendar/sync which is today-only). Returns:
+         *   - true  iff window is same-day AND some cached on_call slot
+         *           starts <= from AND ends >= to
+         *   - false iff window is same-day AND no such slot
+         *   - undefined for cross-day windows OR cache empty for this
+         *     agent (caller treats undefined as "I don't know" — see
+         *     Dialectic plugin's hf-precheck.ts which degrades to
+         *     "skipped" gracefully)
+         *
+         * Phase TBD: when HF backend ships a `/calendar/slots?agent&from&to`
+         * endpoint, swap this to call it for arbitrary windows. Until then,
+         * same-day-only coverage gates ~all debates created by analyze-intel
+         * (which schedules <2h windows) without needing a backend change.
+         */
+        async hasOnCallCovering(
+          agentId: string,
+          fromIso: string,
+          toIso: string,
+        ): Promise<boolean | undefined> {
+          if (!agentId || !fromIso || !toIso) return undefined;
+          const from = new Date(fromIso);
+          const to = new Date(toIso);
+          if (isNaN(from.getTime()) || isNaN(to.getTime())) return undefined;
+          if (!(from < to)) return undefined;
+          // Cross-day → cache only has today; can't decide.
+          const fromDate = from.toISOString().slice(0, 10);
+          const toDate = to.toISOString().slice(0, 10);
+          if (fromDate !== toDate) return undefined;
+          // Cache's cachedDate must match our window's date.
+          const cacheStatus = scheduleCache.getStatus();
+          if (cacheStatus.cachedDate !== fromDate) return undefined;
+          const slots = scheduleCache.getAgentSlots(agentId);
+          if (slots.length === 0) return undefined; // cache empty for this agent — can't decide
+          for (const s of slots) {
+            if (s.slot_type !== 'on_call') continue;
+            // status: ignore aborted/cancelled, accept not_started / ongoing / finished
+            if (s.status === 'aborted' || s.status === 'cancelled') continue;
+            const startStr = s.scheduled_at;
+            if (typeof startStr !== 'string') continue;
+            // scheduled_at can be HH:MM:SS (cache-relative date) or full ISO
+            const start =
+              /^\d{2}:\d{2}(:\d{2})?$/.test(startStr)
+                ? new Date(`${fromDate}T${startStr}Z`)
+                : new Date(startStr);
+            if (isNaN(start.getTime())) continue;
+            const dur = typeof s.estimated_duration === 'number' ? s.estimated_duration : 0;
+            const end = new Date(start.getTime() + dur * 60_000);
+            if (start <= from && end >= to) return true;
+          }
+          return false;
+        },
+      };
+
+      // Track wakes already dispatched for a slot in the current sync
+      // window — the simplified inline scheduler does not PATCH slot
+      // status server-side, so without dedupe the check loop re-wakes
+      // the same slot every 30s. Set is cleared by runSync (fresh wake
+      // budget per sync).
+      const wakedSlotKeys = new Set<string>();
+
+      // Check: find agents with due slots and wake them
+      async function runCheck() {
+        const now = new Date();
+        const agentsWithDue = scheduleCache.getAgentsWithDueSlots(now);
+
+        for (const { agentId, slots } of agentsWithDue) {
+          // Filter out slots we've already woken this sync window
+          const fresh = slots.filter((s) => {
+            const key = `${agentId}::${s.id ?? s.virtual_id ?? s.scheduled_at}`;
+            if (wakedSlotKeys.has(key)) return false;
+            return true;
+          });
+          if (fresh.length === 0) continue;
+
+          // Check if agent is busy (best effort; backend may 405 the GET
+          // — treat unknown as not-busy so wakeup still fires)
+          let status: string | null = null;
+          try {
+            status = await calendarBridge.getAgentStatus(agentId);
+          } catch {
+            status = null;
+          }
+          if (status === 'busy' || status === 'offline' || status === 'exhausted') {
+            continue;
+          }
+
+          // Wake the agent with the slot context inlined
+          const ok = await wakeAgent(agentId, fresh);
+          if (ok) {
+            // Top slot is the one inlined in the wakeup message; record it as
+            // the agent's "current" so harborforge_calendar_complete/abort/…
+            // can resolve a slot without an explicit param.
+            const top = fresh[0];
+            if (top && calendarScheduler instanceof MultiAgentSchedulerHandle) {
+              calendarScheduler.recordWoken(agentId, top);
+            }
+            for (const s of fresh) {
+              const key = `${agentId}::${s.id ?? s.virtual_id ?? s.scheduled_at}`;
+              wakedSlotKeys.add(key);
+            }
+          }
+        }
+      }
+
+      // Initial sync (also resets the wake-dedupe window)
+      const runSyncReset = async () => {
+        wakedSlotKeys.clear();
+        await runSync();
+      };
+      runSyncReset();
+
+      // Start intervals
+      const syncHandle = setInterval(runSyncReset, SYNC_INTERVAL_MS);
+      const checkHandle = setInterval(runCheck, CHECK_INTERVAL_MS);
+
+      // Install the multi-agent handle so calendar tools resolve per-caller.
+      calendarScheduler = new MultiAgentSchedulerHandle({
         bridge: calendarBridge,
-        getAgentStatus,
+        cache: scheduleCache,
-        wakeAgent,
+        syncHandle,
+        checkHandle,
         logger,
-        heartbeatIntervalMs: 60000, // 1 minute
-        debug: live.logLevel === 'debug',
       });
 
-      calendarScheduler.start();
+      logger.info('Calendar scheduler started (multi-agent sync mode)');
-      logger.info('Calendar scheduler started');
     }
 
     /**
@@ -317,7 +612,7 @@ export default {
     });
 
     // Tool: plugin status
-    api.registerTool(() => ({
+    api.registerTool((ctx) => ({
       name: 'harborforge_status',
       description: 'Get HarborForge plugin status and current telemetry snapshot',
       parameters: {
@@ -336,13 +631,27 @@ export default {
             : { connected: false, error: 'Monitor bridge unreachable' };
         }
 
-        // Get calendar scheduler status
+        // Get calendar scheduler status. In multi-agent mode `currentSlot`
-        const calendarStatus = calendarScheduler ? {
+        // depends on the caller, so look it up via ctx.agentId.
+        const callerAgentId = ctx?.agentId ?? resolveAgentId();
+        const calendarStatus = calendarScheduler
+          ? calendarScheduler instanceof MultiAgentSchedulerHandle
+            ? {
                 running: calendarScheduler.isRunning(),
                 processing: calendarScheduler.isProcessing(),
+                mode: 'multi-agent',
+                callerAgentId,
+                currentSlot: calendarScheduler.resolveCurrentSlot(callerAgentId),
+                isRestartPending: calendarScheduler.isRestartPending(),
+              }
+            : {
+                running: calendarScheduler.isRunning(),
+                processing: calendarScheduler.isProcessing(),
+                mode: 'single-agent',
                 currentSlot: calendarScheduler.getCurrentSlot(),
                 isRestartPending: calendarScheduler.isRestartPending(),
-        } : null;
+              }
+          : null;
 
         return {
           enabled: live.enabled !== false,
@@ -401,7 +710,7 @@ export default {
     }));
 
     // Tool: calendar slot management
-    api.registerTool(() => ({
+    api.registerTool((ctx) => ({
       name: 'harborforge_calendar_status',
       description: 'Get current calendar scheduler status and pending slots',
       parameters: {
@@ -412,10 +721,24 @@ export default {
         if (!calendarScheduler) {
           return { error: 'Calendar scheduler not running' };
         }
-
+        const callerAgentId = ctx?.agentId ?? resolveAgentId();
+        if (calendarScheduler instanceof MultiAgentSchedulerHandle) {
           return {
             running: calendarScheduler.isRunning(),
             processing: calendarScheduler.isProcessing(),
+            mode: 'multi-agent',
+            callerAgentId,
+            currentSlot: calendarScheduler.resolveCurrentSlot(callerAgentId),
+            agentSlots: calendarScheduler.cachedSlotsFor(callerAgentId),
+            state: calendarScheduler.getState(),
+            isRestartPending: calendarScheduler.isRestartPending(),
+            stateFilePath: calendarScheduler.getStateFilePath(),
+          };
+        }
+        return {
+          running: calendarScheduler.isRunning(),
+          processing: calendarScheduler.isProcessing(),
+          mode: 'single-agent',
           currentSlot: calendarScheduler.getCurrentSlot(),
           state: calendarScheduler.getState(),
           isRestartPending: calendarScheduler.isRestartPending(),
@@ -425,7 +748,7 @@ export default {
     }));
 
     // Tool: complete current slot (for agent to report completion)
-    api.registerTool(() => ({
+    api.registerTool((ctx) => ({
       name: 'harborforge_calendar_complete',
       description: 'Complete the current calendar slot with actual duration',
       parameters: {
@@ -442,14 +765,20 @@ export default {
         if (!calendarScheduler) {
           return { error: 'Calendar scheduler not running' };
         }
-
+        if (calendarScheduler instanceof MultiAgentSchedulerHandle) {
+          const agentId = ctx?.agentId ?? resolveAgentId();
+          const res = await calendarScheduler.completeSlot(agentId, params.actualDurationMinutes);
+          return res.ok
+            ? { success: true, message: 'Slot completed', slot: res.slot }
+            : { error: res.error };
+        }
         await calendarScheduler.completeCurrentSlot(params.actualDurationMinutes);
         return { success: true, message: 'Slot completed' };
       },
     }));
 
     // Tool: abort current slot (for agent to report failure)
-    api.registerTool(() => ({
+    api.registerTool((ctx) => ({
       name: 'harborforge_calendar_abort',
       description: 'Abort the current calendar slot',
       parameters: {
@@ -465,14 +794,20 @@ export default {
         if (!calendarScheduler) {
           return { error: 'Calendar scheduler not running' };
         }
-
+        if (calendarScheduler instanceof MultiAgentSchedulerHandle) {
+          const agentId = ctx?.agentId ?? resolveAgentId();
+          const res = await calendarScheduler.abortSlot(agentId, params.reason);
+          return res.ok
+            ? { success: true, message: 'Slot aborted', slot: res.slot }
+            : { error: res.error };
+        }
         await calendarScheduler.abortCurrentSlot(params.reason);
         return { success: true, message: 'Slot aborted' };
       },
     }));
 
     // Tool: pause current slot
-    api.registerTool(() => ({
+    api.registerTool((ctx) => ({
       name: 'harborforge_calendar_pause',
       description: 'Pause the current calendar slot',
       parameters: {
@@ -483,14 +818,20 @@ export default {
         if (!calendarScheduler) {
           return { error: 'Calendar scheduler not running' };
         }
-
+        if (calendarScheduler instanceof MultiAgentSchedulerHandle) {
+          const agentId = ctx?.agentId ?? resolveAgentId();
+          const res = await calendarScheduler.pauseSlot(agentId);
+          return res.ok
+            ? { success: true, message: 'Slot paused', slot: res.slot }
+            : { error: res.error };
+        }
         await calendarScheduler.pauseCurrentSlot();
         return { success: true, message: 'Slot paused' };
       },
     }));
 
     // Tool: resume current slot
-    api.registerTool(() => ({
+    api.registerTool((ctx) => ({
       name: 'harborforge_calendar_resume',
       description: 'Resume the paused calendar slot',
       parameters: {
@@ -501,7 +842,13 @@ export default {
         if (!calendarScheduler) {
           return { error: 'Calendar scheduler not running' };
         }
-
+        if (calendarScheduler instanceof MultiAgentSchedulerHandle) {
+          const agentId = ctx?.agentId ?? resolveAgentId();
+          const res = await calendarScheduler.resumeSlot(agentId);
+          return res.ok
+            ? { success: true, message: 'Slot resumed', slot: res.slot }
+            : { error: res.error };
+        }
         await calendarScheduler.resumeCurrentSlot();
         return { success: true, message: 'Slot resumed' };
       },
@@ -534,5 +881,16 @@ export default {
     }));
 
     logger.info('HarborForge plugin registered (id: harbor-forge)');
-  },
+}
-};
+
+// HarborForge's local PluginAPI is broader than the standard OpenClawPluginApi
+// (it surfaces optional `version`/`runtime`/`spawn` accessors that older
+// OpenClaw builds exposed). The cast at the definePluginEntry boundary
+// acknowledges that gap — the runtime api object is whatever the gateway
+// passes us, and each access is guarded with optional chaining / fallbacks.
+export default definePluginEntry({
+  id: 'harbor-forge',
+  name: 'HarborForge',
+  description: 'HarborForge plugin for OpenClaw - project management, monitoring, and CLI integration',
+  register: register as (api: any) => void,
+});

plugin/openclaw-sdk.d.ts

@@ -0,0 +1,25 @@
+// Ambient declarations for the focused subpaths of the openclaw plugin SDK
+// that this plugin needs at compile time.
+//
+// We intentionally do NOT take a `dependencies` (or `devDependencies`) entry
+// on the openclaw npm package itself: openclaw is provided by the host
+// gateway at runtime, and listing it as a file:/.../openclaw devDep breaks
+// the installer's `npm install --omit=dev` step because npm/arborist trips
+// over openclaw's own (deeply nested) dependency graph.
+//
+// These declarations cover only what we use here. They are deliberately
+// permissive — the runtime contract is whatever the gateway hands us, and
+// we guard each api access with optional chaining or a fallback at call site.
+
+declare module 'openclaw/plugin-sdk/plugin-entry' {
+  export function definePluginEntry<T extends {
+    id: string;
+    name: string;
+    description?: string;
+    register: (api: any) => void | Promise<void>;
+  }>(opts: T): T;
+}
+
+declare module 'openclaw/plugin-sdk/core' {
+  export type OpenClawPluginApi = unknown;
+}

plugin/openclaw.plugin.json

@@ -1,9 +1,23 @@
 {
   "id": "harbor-forge",
   "name": "HarborForge",
-  "version": "0.2.0",
   "description": "HarborForge plugin for OpenClaw - project management, monitoring, and CLI integration",
-  "entry": "./dist/index.js",
+  "activation": {
+    "onStartup": true
+  },
+  "contracts": {
+    "tools": [
+      "harborforge_status",
+      "harborforge_telemetry",
+      "harborforge_monitor_telemetry",
+      "harborforge_calendar_status",
+      "harborforge_calendar_complete",
+      "harborforge_calendar_abort",
+      "harborforge_calendar_pause",
+      "harborforge_calendar_resume",
+      "harborforge_restart_status"
+    ]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

plugin/package-lock.json

@@ -9,14 +9,14 @@
       "version": "0.2.0",
       "license": "MIT",
       "devDependencies": {
-        "@types/node": "^20.0.0",
+        "@types/node": "^20.19.41",
         "typescript": "^5.0.0"
       }
     },
     "node_modules/@types/node": {
-      "version": "20.19.37",
+      "version": "20.19.41",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.37.tgz",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.41.tgz",
-      "integrity": "sha512-8kzdPJ3FsNsVIurqBs7oodNnCEVbni9yUEkaHbgptDACOPW04jimGagZ51E6+lXUwJjgnBw+hyko/lkFWCldqw==",
+      "integrity": "sha512-ECymXOukMnOoVkC2bb1Vc/w/836DXncOg5m8Xj1RH7xSHZJWNYY6Zh7EH477vcnD5egKNNfy2RpNOmuChhFPgQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {

plugin/package.json

@@ -1,7 +1,8 @@
 {
   "name": "harbor-forge-plugin",
-  "version": "0.2.0",
+  "version": "0.3.4",
   "description": "OpenClaw plugin for HarborForge monitor bridge and CLI integration",
+  "type": "module",
   "main": "dist/index.js",
   "scripts": {
     "clean": "rm -rf dist",
@@ -9,7 +10,7 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^20.19.41",
     "typescript": "^5.0.0"
   },
   "license": "MIT"

plugin/tsconfig.json

@@ -1,8 +1,8 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "module": "CommonJS",
+    "module": "nodenext",
-    "moduleResolution": "node",
+    "moduleResolution": "nodenext",
     "esModuleInterop": true,
     "strict": true,
     "skipLibCheck": true,

scripts/install.mjs

@@ -31,6 +31,7 @@ const OLD_PLUGIN_NAME = 'harborforge-monitor';
 const PLUGIN_SRC_DIR = join(__dirname, 'plugin');
 const SKILLS_SRC_DIR = join(__dirname, 'skills');
 const MONITOR_REPO_URL = 'https://git.hangman-lab.top/zhi/HarborForge.Monitor.git';
+const CLI_REPO_URL = 'https://git.hangman-lab.top/zhi/HarborForge.Cli.git';
 
 const args = process.argv.slice(2);
 const options = {
@@ -43,6 +44,7 @@ const options = {
   installCli: args.includes('--install-cli'),
   installMonitor: 'no',
   monitorBranch: 'main',
+  cliBranch: 'main',
 };
 
 const profileIdx = args.indexOf('--openclaw-profile-path');
@@ -60,6 +62,11 @@ if (monitorBranchIdx !== -1 && args[monitorBranchIdx + 1]) {
   options.monitorBranch = String(args[monitorBranchIdx + 1]);
 }
 
+const cliBranchIdx = args.indexOf('--cli-branch');
+if (cliBranchIdx !== -1 && args[cliBranchIdx + 1]) {
+  options.cliBranch = String(args[cliBranchIdx + 1]);
+}
+
 function resolveOpenclawPath() {
   if (options.openclawProfilePath) return options.openclawProfilePath;
   if (process.env.OPENCLAW_PATH) return resolve(process.env.OPENCLAW_PATH);
@@ -321,34 +328,35 @@ async function installCli() {
   const binDir = join(openclawPath, 'bin');
   mkdirSync(binDir, { recursive: true });
 
-  // Find CLI source — look for HarborForge.Cli relative to project root
+  // Clone CLI repo to /tmp, build there, copy artifact out. Mirrors
-  const projectRoot = resolve(__dirname, '..');
+  // installManagedMonitor so the install never depends on a checked-out
-  const cliDir = join(projectRoot, 'HarborForge.Cli');
+  // sibling repo at a fixed path.
-  
+  const tmpDir = join('/tmp', `harborforge-cli-${Date.now()}`);
-  if (!existsSync(cliDir)) {
+  const hfBinary = join(binDir, 'hf');
-    // Try parent directory (monorepo layout)
-    const monoCliDir = resolve(projectRoot, '..', 'HarborForge.Cli');
-    if (!existsSync(monoCliDir)) {
-      logErr(`Cannot find HarborForge.Cli at ${cliDir} or ${monoCliDir}`);
-      logWarn('Skipping CLI installation');
-      return;
-    }
-  }
-  
-  const effectiveCliDir = existsSync(cliDir) 
-    ? cliDir 
-    : resolve(projectRoot, '..', 'HarborForge.Cli');
-  
-  log(` Building hf from ${effectiveCliDir}...`, 'blue');
 
   try {
-    const hfBinary = join(binDir, 'hf');
+    log(` Cloning ${CLI_REPO_URL} (branch ${options.cliBranch}) → ${tmpDir}...`, 'blue');
-    exec(`go build -o ${hfBinary} ./cmd/hf`, { cwd: effectiveCliDir, silent: !options.verbose });
+    exec(`git clone --branch ${shellEscape(options.cliBranch)} --depth 1 ${shellEscape(CLI_REPO_URL)} ${shellEscape(tmpDir)}`, { silent: !options.verbose });
+
+    // Stamp the binary with the version string the prod CLI surfaces in
+    // `hf version`. Fall back to a date-only label if rev-parse fails for
+    // any reason (shallow clone shouldn't, but be defensive).
+    let versionLabel = `${new Date().toISOString().slice(0, 10)}+install`;
+    try {
+      const sha = exec(`git rev-parse --short HEAD`, { cwd: tmpDir, silent: true }).trim();
+      if (sha) versionLabel = `${new Date().toISOString().slice(0, 10)}+${options.cliBranch}-${sha}`;
+    } catch { /* keep fallback */ }
+
+    log(` Building hf (version=${versionLabel})...`, 'blue');
+    const ldflags = `-X git.hangman-lab.top/zhi/HarborForge.Cli/internal/commands.Version=${versionLabel}`;
+    exec(`go build -ldflags ${shellEscape(ldflags)} -o ${shellEscape(hfBinary)} ./cmd/hf`, { cwd: tmpDir, silent: !options.verbose });
     chmodSync(hfBinary, 0o755);
-    logOk(`hf binary → ${hfBinary}`);
+    logOk(`hf binary → ${hfBinary} (branch hint: ${options.cliBranch})`);
   } catch (err) {
     logErr(`Failed to build hf CLI: ${err.message}`);
     logWarn('CLI installation failed, plugin still installed');
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true });
   }
 }