Merge pull request 'fix: wake dedupe + inline slot context + complete contracts.tools' (#6 ) from fix/wake-dedupe-and-contracts into main

fix: wake dedupe + inline slot context + complete contracts.tools
Three issues making HF→agent wakeup unusable in practice, surfaced by DinD sim end-to-end test (recruiter agent + slot for 招募 manager task): 1. **Plugin re-woke the same slot every 30s.** The inline runCheck only destructured agentId from scheduleCache.getAgentsWithDueSlots() and dropped the slots array, then called wakeAgent without recording the wake. The simplified inline scheduler also never PATCHes slot status server-side from not_started→ongoing, so the next 30s check sees the slot still due and wakes again. After 4 wakes the agent's wakeup session was full of WAKEUP_OK noise. Fix: keep slots in runCheck, add an in-memory wakedSlotKeys set keyed by (agentId, slotId|virtual_id|scheduled_at). Dedupe on this set; clear it inside the sync interval (fresh wake budget per sync). Server-side slot transition still TODO (requires re-introducing the CalendarScheduler class path or PATCH /calendar/slots/.../agent-update here); the dedupe at least stops the wake spam. 2. **Wakeup message had no slot context.** The wakeup body just said 'follow hf-wakeup workflow' with no slot id/event_data/task_code. The agent then had to call harborforge_calendar_status to learn anything — which itself is broken in the simplified scheduler (it queries a CalendarScheduler instance that never gets created). Fix: pass dueSlots into wakeAgent and inline the highest-priority slot's {slot_id, scheduled_at, priority, slot_type, event_data} as a JSON block in the wakeup message. The agent reads event_data. task_code directly and routes via workflow_lookup without any round-trip. Per PLG-CAL-001 docs in hf-hangman-lab SKILL.md, this is the documented contract; we are bringing the message in line. 3. **contracts.tools listed 5 of the 9 registered tools.** Manifest had harborforge_status/telemetry/monitor_telemetry/calendar_status/ calendar_complete. Code also registers calendar_abort, calendar_pause, calendar_resume, harborforge_restart_status. With the new OpenClaw plugin host enforcement (same gotcha that bit Meridian — see zhi/Meridian#2), undeclared tools are silently dropped from the agent's tool list, so abort/pause/resume cannot be called by the agent. plugin doctor was emitting: 'plugin tool is undeclared (harbor-forge): harborforge_calendar_abort' for each missing tool. Fix: add the 4 missing tool names to contracts.tools. Also use api.config as the primary config source in wakeAgent (current public API), falling back to runtime.config.loadConfig() for older hosts — same pattern as the Meridian fix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-20 14:48:06 +00:00 · 2026-05-20 12:02:25 +01:00
9 changed files with 96 additions and 1319 deletions
--- a/plugin/calendar/calendar-bridge.ts
+++ b/plugin/calendar/calendar-bridge.ts
@@ -110,23 +110,6 @@ 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.
   *
@@ -281,15 +264,6 @@ 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);
@@ -298,7 +272,7 @@ export class CalendarBridgeClient {
        method,
        headers: {
          'Content-Type': 'application/json',
-          'X-Agent-ID': agentId,
+          'X-Agent-ID': this.config.agentId,
          'X-Claw-Identifier': this.config.clawIdentifier,
        },
        body: JSON.stringify(body),
--- a/plugin/calendar/multi-agent-handle.ts
+++ b/plugin/calendar/multi-agent-handle.ts
@@ -1,240 +0,0 @@
 /**
 * 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;
 }
--- a/plugin/index.ts
+++ b/plugin/index.ts
@@ -14,46 +14,18 @@
 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';
 import { registerGatewayStartHook } from './hooks/gateway-start.js';
 import { registerGatewayStopHook } from './hooks/gateway-stop.js';
 import { Block as KBBlock } from './tools/kbblock.js';
 import { KBClient } from './tools/kbclient.js';
 import {
  type KBDeps,
  createListKBsTool,
  createListTopicsTool,
  createListFactsTool,
  createCacheTool,
  createEvictTool,
 } from './tools/dynamic-kb.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;
@@ -83,57 +55,6 @@ 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.
 */
 /**
 * Install a fail-open globalThis.__padded stub if PaddedCell hasn't loaded
 * yet (load order isn't guaranteed). PaddedCell's installGlobalApi drains
 * `_pendingCatalog` and replaces `allowTool` with the real check when it
 * starts. This means HF tools registered before PaddedCell are visible
 * to the agent until PaddedCell takes over, after which they fall under
 * the per-session cache gate (decision #37, openclaw side).
 */
 function ensurePaddedStub(): void {
  const g = globalThis as unknown as {
    __padded?: {
      _pendingCatalog?: Array<{ name: string; description: string }>;
      registerCatalogEntry?: (n: string, d: string) => void;
      allowTool?: (n: string, c: unknown) => boolean;
    };
  };
  if (g.__padded) return;
  const buf: Array<{ name: string; description: string }> = [];
  g.__padded = {
    _pendingCatalog: buf,
    registerCatalogEntry(name: string, description: string): void {
      buf.push({ name, description });
    },
    allowTool: () => true,
  };
 }
 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),
@@ -142,43 +63,6 @@ function register(api: PluginAPI): void {
      warn: (...args: any[]) => console.warn('[HarborForge]', ...args),
    };
    // PaddedCell tools-cache integration (decision #37, openclaw side).
    // Stub the global API early so the gate is consistent regardless of
    // plugin load order; PaddedCell will replace stub with the real impl
    // when it loads. fail-open until then.
    ensurePaddedStub();
    const seenForCatalog = new Set<string>();
    // Wrap api.registerTool so every tool:
    //   (a) registers its name+description into PaddedCell's catalog so
    //       dynamic-list-tools / dynamic-search-tools surface it (#37)
    //   (b) returns null when the per-session cache doesn't include the
    //       name → the tool is hidden from the model that turn
    //   (c) has its execute() return coerced into the MCP `{ content: [...] }`
    //       shape openclaw expects (preserved from earlier).
    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 padded = (globalThis as any).__padded as
          | { allowTool?: (n: string, c: any) => boolean; registerCatalogEntry?: (n: string, d: string) => void }
          | undefined;
        if (def.name && padded?.registerCatalogEntry && !seenForCatalog.has(def.name)) {
          padded.registerCatalogEntry(def.name, def.description ?? '');
          seenForCatalog.add(def.name);
        }
        if (def.name && padded?.allowTool && !padded.allowTool(def.name, ctx)) {
          return null;
        }
        const origExecute = def.execute;
        return {
          ...def,
          execute: async (...args: any[]) => ensureMcpContentShape(await origExecute(...args)),
        };
      });
    };
    function resolveConfig() {
      return getPluginConfig(api);
    }
@@ -186,9 +70,7 @@ function register(api: PluginAPI): void {
    /** 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
+      const cfg = api.runtime?.config?.loadConfig?.();
      // 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';
    }
@@ -227,7 +109,7 @@ function register(api: PluginAPI): void {
        },
        openclaw: {
          version: api.runtime?.version || api.version || 'unknown',
-          pluginVersion: '0.3.4', // Bumped for PLG-CAL-004
+          pluginVersion: '0.3.1', // Bumped for PLG-CAL-004
        },
        timestamp: new Date().toISOString(),
      };
@@ -236,33 +118,13 @@ function register(api: PluginAPI): void {
    // Periodic metadata push interval handle
    let metaPushInterval: ReturnType<typeof setInterval> | null = null;
-    // (calendarScheduler is module-scope — see top of file for the why.
+    // Calendar scheduler instance
-    //  Tools and lifecycle hooks all reference the same binding so the
+    let calendarScheduler: CalendarScheduler | null = null;
    //  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();
@@ -270,7 +132,7 @@ function register(api: PluginAPI): void {
      let agentNames: string[] = [];
      try {
-        const cfg = (api as any).config ?? api.runtime?.config?.loadConfig?.();
+        const cfg = api.runtime?.config?.loadConfig?.();
        const agentsList = cfg?.agents?.list;
        if (Array.isArray(agentsList)) {
          agentNames = agentsList
@@ -281,7 +143,7 @@ function register(api: PluginAPI): void {
      const meta: OpenClawMeta = {
        version: api.runtime?.version || api.version || 'unknown',
-        plugin_version: '0.3.4',
+        plugin_version: '0.3.1',
        agents: agentNames.map(name => ({ name })),
      };
@@ -386,22 +248,10 @@ function register(api: PluginAPI): void {
          )}\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 ` +
+          `You have due slots. Follow the \`hf-wakeup\` workflow of skill ` +
-          `\`hf-hangman-lab\` to completion in this session — read slot ` +
+          `\`hf-hangman-lab\` to proceed. Only reply \`WAKEUP_OK\` in this ` +
-          `context, call the harborforge_calendar_* tools, route to the ` +
+          `session.${slotBlock}`;
          `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: {
@@ -430,23 +280,42 @@ function register(api: PluginAPI): void {
      }
    }
-    // (trackSessionCompletion removed — legacy single-agent poll loop that
+    /**
-    //  called calendarScheduler.completeCurrentSlot. The multi-agent path
+     * Track session completion and update slot status accordingly.
-    //  closes slots via the harborforge_calendar_complete tool, driven by
+     */
-    //  the agent itself, not by a timer.)
+    function trackSessionCompletion(sessionId: string, context: AgentWakeContext): void {
      // Poll for session completion (simplified approach)
      // In production, this would use webhooks or event streaming
      const pollInterval = 30000; // 30 seconds
      const maxDuration = context.slot.estimated_duration * 60 * 1000; // Convert to ms
      const startTime = Date.now();
      const poll = async () => {
        if (!calendarScheduler) return;
        const elapsed = Date.now() - startTime;
        // Check if session is complete (would use actual API in production)
        // For now, estimate completion based on duration
        if (elapsed >= maxDuration) {
          // Assume completion
          const actualMinutes = Math.round(elapsed / 60000);
          await calendarScheduler.completeCurrentSlot(actualMinutes);
          return;
        }
        // Continue polling
        setTimeout(poll, pollInterval);
      };
      // Start polling
      setTimeout(poll, pollInterval);
    }
    /**
     * Initialize and start the calendar scheduler.
     *
     * 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)
@@ -476,94 +345,6 @@ function register(api: PluginAPI): void {
        }
      }
      // 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
@@ -600,13 +381,6 @@ function register(api: PluginAPI): void {
          // 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);
@@ -626,14 +400,14 @@ function register(api: PluginAPI): void {
      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.
+      // Store handles for cleanup (reuse calendarScheduler variable)
-      calendarScheduler = new MultiAgentSchedulerHandle({
+      (calendarScheduler as any) = {
-        bridge: calendarBridge,
+        stop() {
-        cache: scheduleCache,
+          clearInterval(syncHandle);
-        syncHandle,
+          clearInterval(checkHandle);
-        checkHandle,
+          logger.info('Calendar scheduler stopped');
-        logger,
+        },
-      });
+      };
      logger.info('Calendar scheduler started (multi-agent sync mode)');
    }
@@ -670,7 +444,7 @@ function register(api: PluginAPI): void {
    });
    // Tool: plugin status
-    api.registerTool((ctx) => ({
+    api.registerTool(() => ({
      name: 'harborforge_status',
      description: 'Get HarborForge plugin status and current telemetry snapshot',
      parameters: {
@@ -689,27 +463,13 @@ function register(api: PluginAPI): void {
            : { connected: false, error: 'Monitor bridge unreachable' };
        }
-        // Get calendar scheduler status. In multi-agent mode `currentSlot`
+        // Get calendar scheduler status
-        // depends on the caller, so look it up via ctx.agentId.
+        const calendarStatus = calendarScheduler ? {
        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,
@@ -768,7 +528,7 @@ function register(api: PluginAPI): void {
    }));
    // Tool: calendar slot management
-    api.registerTool((ctx) => ({
+    api.registerTool(() => ({
      name: 'harborforge_calendar_status',
      description: 'Get current calendar scheduler status and pending slots',
      parameters: {
@@ -779,24 +539,10 @@ 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(),
@@ -806,7 +552,7 @@ function register(api: PluginAPI): void {
    }));
    // Tool: complete current slot (for agent to report completion)
-    api.registerTool((ctx) => ({
+    api.registerTool(() => ({
      name: 'harborforge_calendar_complete',
      description: 'Complete the current calendar slot with actual duration',
      parameters: {
@@ -823,20 +569,14 @@ 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((ctx) => ({
+    api.registerTool(() => ({
      name: 'harborforge_calendar_abort',
      description: 'Abort the current calendar slot',
      parameters: {
@@ -852,20 +592,14 @@ 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((ctx) => ({
+    api.registerTool(() => ({
      name: 'harborforge_calendar_pause',
      description: 'Pause the current calendar slot',
      parameters: {
@@ -876,20 +610,14 @@ 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((ctx) => ({
+    api.registerTool(() => ({
      name: 'harborforge_calendar_resume',
      description: 'Resume the paused calendar slot',
      parameters: {
@@ -900,13 +628,7 @@ 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' };
      },
@@ -938,73 +660,6 @@ function register(api: PluginAPI): void {
      },
    }));
    // ---- dynamic-kb-* family (DESIGN-DYNAMIC-BLOCK.md §3.3 / §4.4)
    // Cross-runtime mirror of HarborForge.PlexumPlugin/internal/tools/kb.go +
    // /internal/kbblock + /internal/kbclient. v1 auth = plugin-level apiKey
    // via Bearer (per-agent hf-token resolution is a TODO matching the
    // Plexum side).
    const kbCfg = resolveConfig();
    const kbBackendUrl =
      typeof kbCfg?.backendUrl === 'string' && kbCfg.backendUrl
        ? (kbCfg.backendUrl as string)
        : 'https://monitor.hangman-lab.top';
    const kbApiKey = typeof kbCfg?.apiKey === 'string' ? (kbCfg.apiKey as string) : '';
    const kbDeps: KBDeps = {
      client: kbApiKey ? new KBClient(kbBackendUrl, kbApiKey) : null,
      tokenFor: null,
      makeClient: null,
      turnFor: () => 0,
    };
    // Wrap each KB tool factory: pass ctx into execute so cache/evict can
    // resolve the per-session kb-block.json path.
    const kbFactories = [
      createListKBsTool,
      createListTopicsTool,
      createListFactsTool,
      createCacheTool,
      createEvictTool,
    ];
    for (const make of kbFactories) {
      api.registerTool((ctx: any) => {
        const tool = make(kbDeps);
        const inner = tool.execute;
        tool.execute = async (callId: string, params: any) =>
          inner(callId, params, { agentId: ctx?.agentId, sessionId: ctx?.sessionId });
        return tool;
      });
    }
    // <kb-block> subblock injection via before_prompt_build hook
    // (DESIGN-DYNAMIC-BLOCK.md §2 + §7: openclaw side uses
    // appendSystemContext since the hook can't replace baked-in
    // <available_skills> precisely). Empty block → no append.
    const apiOn = (api as any).on;
    if (typeof apiOn === 'function') {
      apiOn.call(
        api,
        'before_prompt_build',
        async (_event: any, ctx: any) => {
          const agentId = ctx?.agentId;
          const sessionId = ctx?.sessionId;
          if (!agentId || !sessionId) return undefined;
          let body = '';
          try {
            const block = KBBlock.open(agentId, sessionId);
            body = block.render();
          } catch (err) {
            logger.warn(`kb-block render failed: ${err}`);
            return undefined;
          }
          if (!body) return undefined;
          return {
            appendSystemContext: `<dynamic-block>\n<kb-block>\n${body}</kb-block>\n</dynamic-block>\n`,
          };
        },
      );
      logger.info('HarborForge kb-block subblock hook registered');
    }
    logger.info('HarborForge plugin registered (id: harbor-forge)');
 }
--- a/plugin/openclaw.plugin.json
+++ b/plugin/openclaw.plugin.json
@@ -15,12 +15,7 @@
      "harborforge_calendar_abort",
      "harborforge_calendar_pause",
      "harborforge_calendar_resume",
-      "harborforge_restart_status",
+      "harborforge_restart_status"
      "dynamic-kb-list-kbs",
      "dynamic-kb-list-topics",
      "dynamic-kb-list-facts",
      "dynamic-kb-cache",
      "dynamic-kb-evict"
    ]
  },
  "configSchema": {
--- a/plugin/package.json
+++ b/plugin/package.json
@@ -1,6 +1,6 @@
 {
  "name": "harbor-forge-plugin",
-  "version": "0.3.4",
+  "version": "0.2.0",
  "description": "OpenClaw plugin for HarborForge monitor bridge and CLI integration",
  "type": "module",
  "main": "dist/index.js",
--- a/plugin/tools/dynamic-kb.ts
+++ b/plugin/tools/dynamic-kb.ts
@@ -1,278 +0,0 @@
 // dynamic-kb.ts — 5 host tools (dynamic-kb-list-kbs / list-topics /
 // list-facts / cache / evict) implementing the agent-side knowledge-
 // base browse + cache flow per DESIGN-DYNAMIC-BLOCK.md §4.4.
 //
 // Cross-runtime aligned with Plexum's dynmem/kb_tools.go — same tool
 // names, same input shapes, same return shapes (so ClawSkills
 // workflow text reads identically on either runtime).
 //
 // Returns ToolResult.content[].text for both ok and error cases. The
 // `isError: true` flag surfaces errors to the model rather than RPC-
 // failing the tool call.
 import { Block as KBBlock } from './kbblock.js';
 import { KBClient } from './kbclient.js';
 interface ToolCtx {
  agentId?: string;
  sessionId?: string;
 }
 interface ToolResult {
  content: Array<{ type: 'text'; text: string }>;
  isError?: boolean;
 }
 function ok(text: string): ToolResult {
  return { content: [{ type: 'text', text }] };
 }
 function err(text: string): ToolResult {
  return { isError: true, content: [{ type: 'text', text }] };
 }
 /** Dependencies the 5 KB tools share. Built once in index.ts. */
 export interface KBDeps {
  /** HF backend KB HTTP client. */
  client: KBClient | null;
  /** Resolve hf-token for the agent at call time (via secret-mgr). null → no auth */
  tokenFor: ((agentId: string) => Promise<string | null>) | null;
  /** Build new client given a token (so each call gets fresh per-agent client). */
  makeClient: ((token: string) => KBClient) | null;
  /** Best-effort current turn number; 0 is acceptable. */
  turnFor: (agentId: string) => number;
 }
 /**
 * Resolve a per-agent KBClient. Returns null with reason if no client
 * (no agent context / no token / no backend URL).
 */
 async function clientFor(deps: KBDeps, ctx: ToolCtx): Promise<{ c: KBClient | null; reason: string }> {
  if (!ctx.agentId) return { c: null, reason: 'no agent context' };
  if (deps.makeClient && deps.tokenFor) {
    const tok = await deps.tokenFor(ctx.agentId);
    if (!tok) return { c: null, reason: 'agent has no hf-token in secret-mgr' };
    return { c: deps.makeClient(tok), reason: '' };
  }
  if (deps.client) return { c: deps.client, reason: '' };
  return { c: null, reason: 'HF KB backend unavailable' };
 }
 // ----- 5 tool factories -----
 export function createListKBsTool(deps: KBDeps) {
  return {
    name: 'dynamic-kb-list-kbs',
    description: 'List HarborForge Knowledge Bases the agent can access. Optional project-code filter.',
    parameters: {
      type: 'object',
      properties: { 'project-code': { type: 'string' } },
    },
    async execute(_id: string, params: any, ctxArg?: ToolCtx): Promise<ToolResult> {
      const ctx = ctxArg ?? {};
      const r = await clientFor(deps, ctx);
      if (!r.c) return err('dynamic-kb-list-kbs: ' + r.reason);
      const proj = params?.['project-code'];
      try {
        const kbs = await r.c.listKBs(typeof proj === 'string' ? proj : undefined);
        const lines: string[] = [];
        if (proj) lines.push(`project: ${proj}`);
        lines.push(`kbs: ${kbs.length}`, '');
        for (const k of kbs) {
          lines.push(`[${k.knowledge_base_code}] ${k.title}`);
          lines.push(`  ${k.description || ''}`, '');
        }
        lines.push(`Call dynamic-kb-list-topics({kb-code: "<code>"}) to drill into a KB.`);
        return ok(lines.join('\n'));
      } catch (e: any) {
        return err('dynamic-kb-list-kbs: ' + (e?.message || String(e)));
      }
    },
  };
 }
 export function createListTopicsTool(deps: KBDeps) {
  return {
    name: 'dynamic-kb-list-topics',
    description: 'List topics in one HF KB by code.',
    parameters: {
      type: 'object',
      properties: { 'kb-code': { type: 'string' } },
      required: ['kb-code'],
    },
    async execute(_id: string, params: any, ctxArg?: ToolCtx): Promise<ToolResult> {
      const ctx = ctxArg ?? {};
      const r = await clientFor(deps, ctx);
      if (!r.c) return err('dynamic-kb-list-topics: ' + r.reason);
      const kbCode = String(params?.['kb-code'] ?? '');
      if (!kbCode) return err('dynamic-kb-list-topics: kb-code required');
      try {
        const ts = await r.c.listTopics(kbCode);
        const lines = [
          `kb: ${kbCode}`,
          `topics: ${ts.length}`,
          '',
          ...ts.flatMap((t) => [`[${t.id}] ${t.topic}`, `  ${t.description || ''}`, '']),
          `Call dynamic-kb-list-facts({kb-code: "${kbCode}", topic-ids: [<id>, ...]}) to drill into facts.`,
        ];
        return ok(lines.join('\n'));
      } catch (e: any) {
        return err('dynamic-kb-list-topics: ' + (e?.message || String(e)));
      }
    },
  };
 }
 export function createListFactsTool(deps: KBDeps) {
  return {
    name: 'dynamic-kb-list-facts',
    description: 'List fact previews (id/topic/title/snippet) in given topics. Feed into dynamic-kb-cache.',
    parameters: {
      type: 'object',
      properties: {
        'kb-code': { type: 'string' },
        'topic-ids': { type: 'array', items: { type: 'integer' } },
      },
      required: ['kb-code', 'topic-ids'],
    },
    async execute(_id: string, params: any, ctxArg?: ToolCtx): Promise<ToolResult> {
      const ctx = ctxArg ?? {};
      const r = await clientFor(deps, ctx);
      if (!r.c) return err('dynamic-kb-list-facts: ' + r.reason);
      const kbCode = String(params?.['kb-code'] ?? '');
      const topicIds = Array.isArray(params?.['topic-ids']) ? params['topic-ids'].map((x: any) => Number(x)) : [];
      if (!kbCode || topicIds.length === 0) {
        return err('dynamic-kb-list-facts: kb-code + topic-ids required');
      }
      try {
        const facts = await r.c.listFacts(kbCode, topicIds);
        const lines = [
          `kb: ${kbCode}`,
          `topics: [${topicIds.join(', ')}]`,
          `facts: ${facts.length}`,
          '',
          ...facts.flatMap((f) => [
            `[${f.id}] (topic ${f.topic_id}/${f.topic_slug}) ${f.title}`,
            `  ${f.snippet}`,
            '',
          ]),
          `Call dynamic-kb-cache({kb-code: "${kbCode}", fact-ids: [<id>, ...]}) to commit selected facts to your kb-block.`,
        ];
        return ok(lines.join('\n'));
      } catch (e: any) {
        return err('dynamic-kb-list-facts: ' + (e?.message || String(e)));
      }
    },
  };
 }
 export function createCacheTool(deps: KBDeps) {
  return {
    name: 'dynamic-kb-cache',
    description: 'Cache KB facts into your per-session kb-block (visible next turn).',
    parameters: {
      type: 'object',
      properties: {
        'kb-code': { type: 'string' },
        'fact-ids': { type: 'array', items: { type: 'integer' } },
        'previous-dynamic-id': { type: 'string' },
      },
      required: ['kb-code', 'fact-ids'],
    },
    async execute(_id: string, params: any, ctxArg?: ToolCtx): Promise<ToolResult> {
      const ctx = ctxArg ?? {};
      if (!ctx.agentId || !ctx.sessionId) {
        return err('dynamic-kb-cache: no per-session context');
      }
      const r = await clientFor(deps, ctx);
      if (!r.c) return err('dynamic-kb-cache: ' + r.reason);
      const kbCode = String(params?.['kb-code'] ?? '');
      const factIds = Array.isArray(params?.['fact-ids']) ? params['fact-ids'].map((x: any) => Number(x)) : [];
      if (!kbCode || factIds.length === 0) {
        return err('dynamic-kb-cache: kb-code + fact-ids required');
      }
      let block: KBBlock;
      try {
        block = KBBlock.open(ctx.agentId, ctx.sessionId);
      } catch (e: any) {
        return err('dynamic-kb-cache: open block: ' + (e?.message || String(e)));
      }
      const toFetch: number[] = [];
      const alreadyCached: number[] = [];
      for (const id of factIds) {
        if (block.has(id)) alreadyCached.push(id);
        else toFetch.push(id);
      }
      let fetched: Array<{ id: number; kb_code: string; topic_slug: string; content: string }> = [];
      if (toFetch.length > 0) {
        try {
          fetched = await r.c.getFacts(kbCode, toFetch);
        } catch (e: any) {
          return err('dynamic-kb-cache: ' + (e?.message || String(e)));
        }
      }
      const turn = deps.turnFor(ctx.agentId);
      const fetchedByID = new Map(fetched.map((f) => [f.id, f]));
      const added: number[] = [];
      for (const id of toFetch) {
        const f = fetchedByID.get(id);
        if (!f) continue;
        if (block.add(f.id, kbCode, f.topic_slug, f.content, turn)) added.push(f.id);
      }
      try {
        block.save();
      } catch (e: any) {
        return err('dynamic-kb-cache: save: ' + (e?.message || String(e)));
      }
      const missing = toFetch.filter((id) => !added.includes(id));
      return ok(
        JSON.stringify({
          added: added.sort((a, b) => a - b),
          already_cached: alreadyCached.sort((a, b) => a - b),
          missing: missing.length ? missing.sort((a, b) => a - b) : undefined,
          note: 'Newly cached facts are available starting your next turn.',
        }),
      );
    },
  };
 }
 export function createEvictTool(_deps: KBDeps) {
  return {
    name: 'dynamic-kb-evict',
    description: "Remove cached facts from your kb-block. Takes effect next turn.",
    parameters: {
      type: 'object',
      properties: { 'fact-ids': { type: 'array', items: { type: 'integer' } } },
      required: ['fact-ids'],
    },
    async execute(_id: string, params: any, ctxArg?: ToolCtx): Promise<ToolResult> {
      const ctx = ctxArg ?? {};
      if (!ctx.agentId || !ctx.sessionId) {
        return err('dynamic-kb-evict: no per-session context');
      }
      const factIds = Array.isArray(params?.['fact-ids']) ? params['fact-ids'].map((x: any) => Number(x)) : [];
      if (factIds.length === 0) return err('dynamic-kb-evict: fact-ids required');
      let block: KBBlock;
      try {
        block = KBBlock.open(ctx.agentId, ctx.sessionId);
      } catch (e: any) {
        return err('dynamic-kb-evict: open block: ' + (e?.message || String(e)));
      }
      const evicted = block.remove(factIds);
      try {
        block.save();
      } catch (e: any) {
        return err('dynamic-kb-evict: save: ' + (e?.message || String(e)));
      }
      const notCached = factIds.filter((id: number) => !evicted.includes(id));
      return ok(
        JSON.stringify({
          evicted: evicted.sort((a, b) => a - b),
          not_cached: notCached.length ? notCached.sort((a: number, b: number) => a - b) : undefined,
          note: 'Evictions take effect starting your next turn.',
        }),
      );
    },
  };
 }
--- a/plugin/tools/kbblock.ts
+++ b/plugin/tools/kbblock.ts
@@ -1,155 +0,0 @@
 // kbblock.ts — TypeScript mirror of HarborForge.PlexumPlugin's
 // internal/kbblock package. Per-session storage of HarborForge KB
 // facts the agent has cached, rendered as <kb-fact id=N kb=<code>
 // source=topic:<slug>>content</kb-fact> per DESIGN-DYNAMIC-BLOCK.md
 // §3.3 / §4.4.
 //
 // Storage location:
 //
 //   <OPENCLAW_PATH>/agents/<agentId>/sessions/<sessionId>/plugins/
 //   harbor-forge/kb-block.json
 //
 // Fade NOT applied in v1 (§9 #3 placeholder; defer until prod data).
 // Cross-runtime aligned with Plexum kbblock.
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 export interface Entry {
  id: number;          // HF backend DB primary key
  kb_code: string;     // e.g. "KB-PAYROT"
  source_topic: string; // human slug from HF, e.g. "debugging"
  content: string;
  insert_seq: number;
  added_at_turn: number;
  last_refresh_at_turn: number;
 }
 interface BlockShape {
  version: number;
  next_seq: number;
  entries: Entry[];
 }
 const FILE_NAME = 'kb-block.json';
 const VERSION = 1;
 function openclawRoot(): string {
  const env = process.env.OPENCLAW_PATH;
  if (env) return env;
  const home = process.env.HOME || os.homedir();
  return path.join(home, '.openclaw');
 }
 /** sessions/<sid>/plugins/harbor-forge path under openclaw profile. */
 export function sessionDir(agentId: string, sessionId: string): string {
  return path.join(openclawRoot(), 'agents', agentId, 'sessions', sessionId, 'plugins', 'harbor-forge');
 }
 export function blockPath(agentId: string, sessionId: string): string {
  return path.join(sessionDir(agentId, sessionId), FILE_NAME);
 }
 /** Block is the in-memory representation. Cheap to Open + Save per call. */
 export class Block {
  private readonly path: string;
  next_seq: number = 1;
  entries: Entry[] = [];
  private constructor(blockPath: string) { this.path = blockPath; }
  /** Open from disk (missing file → empty block). Throws on parse error. */
  static open(agentId: string, sessionId: string): Block {
    if (!agentId || !sessionId) {
      throw new Error('kbblock.open: agentId + sessionId required');
    }
    const b = new Block(blockPath(agentId, sessionId));
    try {
      const raw = fs.readFileSync(b.path, 'utf8');
      if (raw.trim().length === 0) return b;
      const data = JSON.parse(raw) as Partial<BlockShape>;
      if (data.next_seq && data.next_seq > 0) b.next_seq = data.next_seq;
      if (Array.isArray(data.entries)) b.entries = data.entries;
    } catch (err: any) {
      if (err?.code === 'ENOENT') return b;
      throw err;
    }
    return b;
  }
  len(): number { return this.entries.length; }
  has(id: number): boolean {
    return this.entries.some((e) => e.id === id);
  }
  /** Add new entry. Returns it; null on duplicate (silent no-op per §9 #4). */
  add(id: number, kb_code: string, source_topic: string, content: string, at_turn: number): Entry | null {
    if (this.has(id)) return null;
    const e: Entry = {
      id, kb_code, source_topic, content,
      insert_seq: this.next_seq,
      added_at_turn: at_turn,
      last_refresh_at_turn: at_turn,
    };
    this.next_seq += 1;
    this.entries.push(e);
    return e;
  }
  /** Remove given IDs. Returns IDs actually removed. */
  remove(ids: number[]): number[] {
    const want = new Set(ids);
    const removed: number[] = [];
    this.entries = this.entries.filter((e) => {
      if (want.has(e.id)) {
        removed.push(e.id);
        return false;
      }
      return true;
    });
    return removed;
  }
  lookup(id: number): Entry | undefined {
    return this.entries.find((e) => e.id === id);
  }
  /** Atomic save (tmp+rename, 0600). Empty block with no prior file = no-op. */
  save(): void {
    if (this.entries.length === 0) {
      if (!fs.existsSync(this.path)) return;
    }
    fs.mkdirSync(path.dirname(this.path), { recursive: true });
    const payload: BlockShape = {
      version: VERSION,
      next_seq: this.next_seq,
      entries: this.entries,
    };
    const tmp = this.path + '.tmp';
    fs.writeFileSync(tmp, JSON.stringify(payload, null, 2), { mode: 0o600 });
    fs.renameSync(tmp, this.path);
  }
  /**
   * Render the <kb-block> inner body — flat sequence of
   * <kb-fact id=N kb=<code> source=topic:<slug>>content</kb-fact>
   * ordered by insert_seq (§9 #4). Empty block → "".
   */
  render(): string {
    if (this.entries.length === 0) return '';
    const ordered = [...this.entries].sort((a, b) => a.insert_seq - b.insert_seq);
    const lines: string[] = [];
    ordered.forEach((e, i) => {
      if (i > 0) lines.push('');
      let head = `<kb-fact id=${e.id} kb=${e.kb_code}`;
      if (e.source_topic) head += ` source=topic:${e.source_topic}`;
      head += '>';
      lines.push(head);
      lines.push(e.content);
      lines.push('</kb-fact>');
    });
    return lines.join('\n') + '\n';
  }
 }
--- a/plugin/tools/kbclient.ts
+++ b/plugin/tools/kbclient.ts
@@ -1,166 +0,0 @@
 // kbclient.ts — TypeScript HTTP client for HarborForge.Backend KB
 // REST routes. Mirrors HarborForge.PlexumPlugin/internal/kbclient.
 // Routes verified against app/api/routers/knowledge.py:
 //
 //   GET /knowledge-bases[?project=<code>]    list KBs
 //   GET /knowledge-bases/{id|code}/topics    list topics in a KB
 //   GET /knowledge-bases/{id|code}/tree      full hierarchy
 //   GET /knowledge-facts/{id}                single fact
 //
 // Auth: per-agent HF token (looked up via secret-mgr by caller; this
 // client takes a pre-resolved token string). Cross-runtime parity
 // note: Plexum client uses plugin-level APIKey from config because
 // the Plexum SDK can't reach secret-mgr; openclaw side has agent
 // context so we go per-agent here.
 export interface KBSummary {
  id: number;
  knowledge_base_code: string;
  title: string;
  description: string;
 }
 export interface TopicSummary {
  id: number;
  topic: string;
  description: string;
 }
 export interface FactSummary {
  id: number;
  topic_id: number;
  topic_slug: string;
  title: string;
  snippet: string;
 }
 export interface Fact {
  id: number;
  kb_code: string;
  topic_slug: string;
  content: string;
 }
 interface TreeNode {
  id: number;
  topic?: string;
  category?: string;
  title?: string;
  content?: string;
  categories?: TreeNode[];
  facts?: TreeNode[];
 }
 interface KBTree {
  knowledge_base_code: string;
  topics: TreeNode[];
 }
 export class KBClient {
  private readonly baseUrl: string;
  private readonly token: string;
  constructor(baseUrl: string, token: string) {
    this.baseUrl = baseUrl.replace(/\/$/, '');
    this.token = token;
  }
  async listKBs(projectCode?: string): Promise<KBSummary[]> {
    let path = '/knowledge-bases';
    if (projectCode) path += '?project=' + encodeURIComponent(projectCode);
    return this.get<KBSummary[]>(path);
  }
  async listTopics(kbCode: string): Promise<TopicSummary[]> {
    if (!kbCode) throw new Error('kbclient: kb-code required');
    return this.get<TopicSummary[]>('/knowledge-bases/' + encodeURIComponent(kbCode) + '/topics');
  }
  /** ListFacts pulls the tree once + flattens facts under topic-ids client-side. */
  async listFacts(kbCode: string, topicIds: number[]): Promise<FactSummary[]> {
    if (!kbCode) throw new Error('kbclient: kb-code required');
    if (!topicIds || topicIds.length === 0) throw new Error('kbclient: topic-ids required');
    const tree = await this.get<KBTree>('/knowledge-bases/' + encodeURIComponent(kbCode) + '/tree');
    const wantTopic = new Set(topicIds);
    const out: FactSummary[] = [];
    for (const topic of tree.topics || []) {
      if (!wantTopic.has(topic.id)) continue;
      this.walkFactsInto(out, topic.id, topic.topic || '', topic.categories || [], topic.facts || []);
    }
    return out;
  }
  private walkFactsInto(
    out: FactSummary[],
    topicId: number,
    topicSlug: string,
    cats: TreeNode[],
    facts: TreeNode[],
  ): void {
    for (const f of facts) {
      out.push({
        id: f.id,
        topic_id: topicId,
        topic_slug: topicSlug,
        title: f.title || '',
        snippet: snippet(f.content || '', 120),
      });
    }
    for (const c of cats) {
      this.walkFactsInto(out, topicId, topicSlug, c.categories || [], c.facts || []);
    }
  }
  /** GetFacts pulls each fact's full body. Backend has no batch route. */
  async getFacts(kbCode: string, factIds: number[]): Promise<Fact[]> {
    if (!kbCode) throw new Error('kbclient: kb-code required');
    const out: Fact[] = [];
    for (const id of factIds) {
      try {
        const node = await this.get<{ id: number; title: string; content: string; topic: string }>(
          '/knowledge-facts/' + id,
        );
        out.push({
          id: node.id,
          kb_code: kbCode,
          topic_slug: node.topic || '',
          content: node.content || '',
        });
      } catch (err: any) {
        if (err?.code === 404) continue; // skip missing
        throw err;
      }
    }
    return out;
  }
  private async get<T>(p: string): Promise<T> {
    const res = await fetch(this.baseUrl + p, {
      method: 'GET',
      headers: {
        Accept: 'application/json',
        ...(this.token ? { Authorization: 'Bearer ' + this.token } : {}),
      },
    });
    if (res.status === 404) {
      const e: any = new Error(`GET ${p}: 404 not found`);
      e.code = 404;
      throw e;
    }
    if (!res.ok) {
      const body = await res.text().catch(() => '');
      throw new Error(`GET ${p}: HTTP ${res.status}: ${truncate(body, 200)}`);
    }
    if (res.status === 204) return undefined as T;
    return (await res.json()) as T;
  }
 }
 function snippet(s: string, n: number): string {
  s = s.trim();
  return s.length <= n ? s : s.slice(0, n) + '...';
 }
 function truncate(s: string, n: number): string {
  return s.length > n ? s.slice(0, n) + '...' : s;
 }
--- a/scripts/install.mjs
+++ b/scripts/install.mjs
@@ -31,7 +31,6 @@ 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 = {
@@ -44,7 +43,6 @@ const options = {
  installCli: args.includes('--install-cli'),
  installMonitor: 'no',
  monitorBranch: 'main',
  cliBranch: 'main',
 };
 const profileIdx = args.indexOf('--openclaw-profile-path');
@@ -62,11 +60,6 @@ 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);
@@ -328,35 +321,34 @@ async function installCli() {
  const binDir = join(openclawPath, 'bin');
  mkdirSync(binDir, { recursive: true });
-  // Clone CLI repo to /tmp, build there, copy artifact out. Mirrors
+  // Find CLI source — look for HarborForge.Cli relative to project root
-  // installManagedMonitor so the install never depends on a checked-out
+  const projectRoot = resolve(__dirname, '..');
-  // sibling repo at a fixed path.
+  const cliDir = join(projectRoot, 'HarborForge.Cli');
-  const tmpDir = join('/tmp', `harborforge-cli-${Date.now()}`);
+  
  if (!existsSync(cliDir)) {
    // Try parent directory (monorepo layout)
    const monoCliDir = resolve(projectRoot, '..', 'HarborForge.Cli');
    if (!existsSync(monoCliDir)) {
      logErr(`Cannot find HarborForge.Cli at ${cliDir} or ${monoCliDir}`);
      logWarn('Skipping CLI installation');
      return;
    }
  }
  const effectiveCliDir = existsSync(cliDir) 
    ? cliDir 
    : resolve(projectRoot, '..', 'HarborForge.Cli');
  log(` Building hf from ${effectiveCliDir}...`, 'blue');
  try {
    const hfBinary = join(binDir, 'hf');
-
+    exec(`go build -o ${hfBinary} ./cmd/hf`, { cwd: effectiveCliDir, silent: !options.verbose });
  try {
    log(` Cloning ${CLI_REPO_URL} (branch ${options.cliBranch}) → ${tmpDir}...`, 'blue');
    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} (branch hint: ${options.cliBranch})`);
+    logOk(`hf binary → ${hfBinary}`);
  } catch (err) {
    logErr(`Failed to build hf CLI: ${err.message}`);
    logWarn('CLI installation failed, plugin still installed');
  } finally {
    rmSync(tmpDir, { recursive: true, force: true });
  }
 }