fix(hf-plugin): wrap tool returns in MCP {content:[...]} shape

OpenClaw's Codex tool dispatcher (thread-lifecycle:255) expects every
tool execute() to return { content: [...] } and calls result.content.reduce()
to compute total text length. All 9 harborforge_* tools returned bare
objects ({ running, processing, currentSlot, ... }) which has no
.content field — so .reduce of undefined threw, and the agent saw the
cryptic 'Cannot read properties of undefined (reading reduce)' on
every call. This silently blocked every calendar slot transition on
prod for hours: agents could call harborforge_calendar_complete but
it always errored, so slots never moved out of not_started.

Fix is at the registerTool boundary: api.registerTool is wrapped once
to coerce every tool's execute return through ensureMcpContentShape.
Tools that already return the correct shape are unchanged. No per-tool
edits needed.

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

plugin/calendar/calendar-bridge.ts

@@ -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.
    *
@@ -264,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);
 
@@ -272,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),

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/index.ts

@@ -14,6 +14,7 @@
 import { hostname, freemem, totalmem, uptime, loadavg, platform } from 'node:os';
 import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
 import { MultiAgentScheduleCache } from './calendar/schedule-cache.js';
+import { MultiAgentSchedulerHandle } from './calendar/multi-agent-handle.js';
 import { getPluginConfig } from './core/config.js';
 import { MonitorBridgeClient, type OpenClawMeta } from './core/monitor-bridge.js';
 import type { OpenClawAgentInfo } from './core/openclaw-agents.js';
@@ -21,11 +22,28 @@ import { registerGatewayStartHook } from './hooks/gateway-start.js';
 import { registerGatewayStopHook } from './hooks/gateway-stop.js';
 import {
   createCalendarBridgeClient,
-  createCalendarScheduler,
   CalendarScheduler,
-  AgentWakeContext,
 } from './calendar/index.js';
 
+// ---------------------------------------------------------------------------
+// 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: {
     info: (...args: any[]) => void;
@@ -55,6 +73,30 @@ interface PluginAPI {
   getAgentStatus?: () => Promise<{ status: string } | null>;
 }
 
+/**
+ * Coerce a tool execute() return value into the MCP `{ content: [...] }`
+ * shape that the openclaw Codex tool dispatcher requires.
+ *
+ * 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),
@@ -63,6 +105,22 @@ function register(api: PluginAPI): void {
       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);
     }
@@ -109,7 +167,7 @@ function register(api: PluginAPI): void {
         },
         openclaw: {
           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(),
       };
@@ -118,8 +176,9 @@ function register(api: PluginAPI): void {
     // Periodic metadata push interval handle
     let metaPushInterval: ReturnType<typeof setInterval> | null = null;
 
-    // Calendar scheduler instance
-    let calendarScheduler: CalendarScheduler | null = null;
+    // (calendarScheduler is module-scope — see top of file for the why.
+    //  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.
@@ -143,7 +202,7 @@ function register(api: PluginAPI): void {
 
       const meta: OpenClawMeta = {
         version: api.runtime?.version || api.version || 'unknown',
-        plugin_version: '0.3.1',
+        plugin_version: '0.3.4',
         agents: agentNames.map(name => ({ name })),
       };
 
@@ -197,7 +256,18 @@ function register(api: PluginAPI): void {
      * Wake agent via dispatchInboundMessage — same mechanism used by Discord plugin.
      * Direct in-process call, no WebSocket or CLI needed.
      */
-    async function wakeAgent(agentId: string): Promise<boolean> {
+    async function wakeAgent(
+      agentId: string,
+      dueSlots?: Array<{
+        id?: number | null;
+        virtual_id?: string | null;
+        event_data?: any;
+        scheduled_at?: string;
+        priority?: number;
+        slot_type?: string;
+        [k: string]: unknown;
+      }>
+    ): Promise<boolean> {
       logger.info(`Waking agent ${agentId}: has due slots`);
 
       const sessionKey = `agent:${agentId}:hf-wakeup`;
@@ -208,13 +278,50 @@ function register(api: PluginAPI): void {
           /* webpackIgnore: true */ sdkPath
         );
 
-        const cfg = api.runtime?.config?.loadConfig?.();
+        // api.config first (current public API). Fall back to deprecated
+        // runtime.config.loadConfig() for older host versions. Both should
+        // contain agents.list / channels for dispatch routing.
+        const cfg = (api as any).config ?? api.runtime?.config?.loadConfig?.();
         if (!cfg) {
           logger.error('Cannot load OpenClaw config for dispatch');
           return false;
         }
 
-        const wakeupMessage = `You have due slots. Follow the \`hf-wakeup\` workflow of skill \`hf-hangman-lab\` to proceed. Only reply \`WAKEUP_OK\` in this session.`;
+        // Inline the highest-priority due slot's context so the agent does
+        // not need a second round-trip to harborforge_calendar_status. The
+        // agent can read event_data.task_code / task_title etc. directly.
+        let slotBlock = '';
+        const top = dueSlots && dueSlots.length ? dueSlots[0] : undefined;
+        if (top) {
+          slotBlock = `\n\nMatching slot:\n\`\`\`json\n${JSON.stringify(
+            {
+              slot_id: top.id ?? null,
+              virtual_id: top.virtual_id ?? null,
+              scheduled_at: top.scheduled_at ?? null,
+              priority: top.priority ?? null,
+              slot_type: top.slot_type ?? null,
+              event_data: top.event_data ?? null,
+            },
+            null,
+            2
+          )}\n\`\`\``;
+        }
+
+        // First-line ack `WAKEUP_OK` is the plugin's ack-receipt token; the
+        // agent MUST then continue in the same session and drive the
+        // `hf-wakeup` workflow to completion (calendar_status → task fetch →
+        // sub-workflow → calendar_complete/abort). Without that continuation
+        // the scheduler keeps re-waking every 30s because the slot stays
+        // `not_started` forever.
+        const wakeupMessage =
+          `You have due slots. **First line of your reply MUST be exactly ` +
+          `\`WAKEUP_OK\`** so the plugin records the ack. Then, **in this ` +
+          `same session**, drive the \`hf-wakeup\` workflow of skill ` +
+          `\`hf-hangman-lab\` to completion — read slot context, call the ` +
+          `harborforge_calendar_* tools, route to the right sub-workflow, ` +
+          `and finish with harborforge_calendar_complete or abort. Do NOT ` +
+          `stop after the ack — the scheduler will re-wake you every 30s ` +
+          `until the slot transitions out of \`not_started\`.${slotBlock}`;
 
         const result = await dispatchInboundMessageWithDispatcher({
           ctx: {
@@ -243,42 +350,23 @@ function register(api: PluginAPI): void {
       }
     }
 
-    /**
-     * 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);
-    }
+    // (trackSessionCompletion removed — legacy single-agent poll loop that
+    //  called calendarScheduler.completeCurrentSlot. The multi-agent path
+    //  closes slots via the harborforge_calendar_complete tool, driven by
+    //  the agent itself, not by a timer.)
 
     /**
      * 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();
 
       // Create bridge client (claw-instance level, not per-agent)
@@ -308,38 +396,76 @@ function register(api: PluginAPI): void {
         }
       }
 
+      // 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 } of agentsWithDue) {
-          // Check if agent is busy
-          const status = await calendarBridge.getAgentStatus(agentId);
+        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
-          await wakeAgent(agentId);
+          // 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
-      runSync();
+      // Initial sync (also resets the wake-dedupe window)
+      const runSyncReset = async () => {
+        wakedSlotKeys.clear();
+        await runSync();
+      };
+      runSyncReset();
 
       // Start intervals
-      const syncHandle = setInterval(runSync, SYNC_INTERVAL_MS);
+      const syncHandle = setInterval(runSyncReset, SYNC_INTERVAL_MS);
       const checkHandle = setInterval(runCheck, CHECK_INTERVAL_MS);
 
-      // Store handles for cleanup (reuse calendarScheduler variable)
-      (calendarScheduler as any) = {
-        stop() {
-          clearInterval(syncHandle);
-          clearInterval(checkHandle);
-          logger.info('Calendar scheduler stopped');
-        },
-      };
+      // Install the multi-agent handle so calendar tools resolve per-caller.
+      calendarScheduler = new MultiAgentSchedulerHandle({
+        bridge: calendarBridge,
+        cache: scheduleCache,
+        syncHandle,
+        checkHandle,
+        logger,
+      });
 
       logger.info('Calendar scheduler started (multi-agent sync mode)');
     }
@@ -376,7 +502,7 @@ function register(api: PluginAPI): void {
     });
 
     // Tool: plugin status
-    api.registerTool(() => ({
+    api.registerTool((ctx) => ({
       name: 'harborforge_status',
       description: 'Get HarborForge plugin status and current telemetry snapshot',
       parameters: {
@@ -395,13 +521,27 @@ function register(api: PluginAPI): void {
             : { 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;
+        // Get calendar scheduler status. In multi-agent mode `currentSlot`
+        // 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;
 
         return {
           enabled: live.enabled !== false,
@@ -460,7 +600,7 @@ function register(api: PluginAPI): void {
     }));
 
     // Tool: calendar slot management
-    api.registerTool(() => ({
+    api.registerTool((ctx) => ({
       name: 'harborforge_calendar_status',
       description: 'Get current calendar scheduler status and pending slots',
       parameters: {
@@ -471,10 +611,24 @@ function register(api: PluginAPI): void {
         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(),
@@ -484,7 +638,7 @@ function register(api: PluginAPI): void {
     }));
 
     // 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: {
@@ -501,14 +655,20 @@ function register(api: PluginAPI): void {
         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: {
@@ -524,14 +684,20 @@ function register(api: PluginAPI): void {
         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: {
@@ -542,14 +708,20 @@ function register(api: PluginAPI): void {
         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: {
@@ -560,7 +732,13 @@ function register(api: PluginAPI): void {
         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' };
       },

plugin/openclaw.plugin.json

@@ -11,7 +11,11 @@
       "harborforge_telemetry",
       "harborforge_monitor_telemetry",
       "harborforge_calendar_status",
-      "harborforge_calendar_complete"
+      "harborforge_calendar_complete",
+      "harborforge_calendar_abort",
+      "harborforge_calendar_pause",
+      "harborforge_calendar_resume",
+      "harborforge_restart_status"
     ]
   },
   "configSchema": {

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",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.37.tgz",
-      "integrity": "sha512-8kzdPJ3FsNsVIurqBs7oodNnCEVbni9yUEkaHbgptDACOPW04jimGagZ51E6+lXUwJjgnBw+hyko/lkFWCldqw==",
+      "version": "20.19.41",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.41.tgz",
+      "integrity": "sha512-ECymXOukMnOoVkC2bb1Vc/w/836DXncOg5m8Xj1RH7xSHZJWNYY6Zh7EH477vcnD5egKNNfy2RpNOmuChhFPgQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {

plugin/package.json

@@ -1,6 +1,6 @@
 {
   "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",
@@ -10,7 +10,7 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^20.19.41",
     "typescript": "^5.0.0"
   },
   "license": "MIT"