bereach-openclaw 1.5.5 → 1.5.7

package/README.md

@@ -21,8 +21,11 @@ openclaw plugins install bereach-openclaw
 **Before upgrading:** note your `BEREACH_API_KEY` - uninstall may remove `plugins.entries.bereach-openclaw`.
 
 ```bash
-# 1. Uninstall
+# 1. Uninstall + fully delete (rm prevents stale .old copies causing 401 loops)
 openclaw plugins uninstall bereach-openclaw
+rm -rf /data/.openclaw/extensions/bereach-openclaw*
+rm -rf /data/.openclaw/node_modules/bereach-openclaw
+rm -rf /data/.openclaw/node_modules/bereach
 
 # 2. Reinstall latest
 openclaw plugins install bereach-openclaw
@@ -108,9 +111,9 @@ OpenClaw loads plugins from **two locations**:
 
 If `extensions/bereach-openclaw/` is corrupt or incomplete, you get trim/undefined errors. Fix:
 
-**1. Backup and remove the active extension:**
+**1. Fully remove the active extension** (do NOT rename to `.bak` - OpenClaw loads `.bak`/`.old` copies as duplicate plugins):
 ```bash
-mv /data/.openclaw/extensions/bereach-openclaw /data/.openclaw/extensions/bereach-openclaw.bak.$(date +%s)
+rm -rf /data/.openclaw/extensions/bereach-openclaw*
 ```
 
 **2. Reinstall from npm (inside the container):**

package/node_modules/@bereach/tools/src/definitions.ts

@@ -1289,6 +1289,11 @@ export const definitions: ToolDefinition[] = [
         dailyActionLimit: { type: "integer", minimum: 1, description: "Max actions per day." },
         dailyTarget: { type: "integer", minimum: 1, description: "Daily target goal (e.g. 50 leads/day). Set null to remove." },
         totalTarget: { type: "integer", minimum: 1, description: "Total campaign goal (e.g. 500 leads total). Auto-completes when reached. Set null to remove." },
+        handoverMode: {
+          type: "string",
+          enum: ["on_reply", "on_goal", "manual"],
+          description: "When agent hands over conversation to human. on_reply (default): stop autonomous outreach when contact replies. on_goal: keep replying until meeting booked or converted. manual: never auto-stop.",
+        },
         taskOverrides: {
           type: "object",
           description: "Per-task-type config overrides. Keys are task types (e.g. 'lead-gen-visit', 'lead-gen-qualify'). Values are config objects with: maxRunsPerDay, minIntervalMinutes, defaultBatchSize, maxCreditsPerRun.",
@@ -1428,6 +1433,7 @@ export const definitions: ToolDefinition[] = [
         lifecycleStage: { type: "string", enum: ["contact", "lead", "qualified", "approved", "rejected"], description: "New stage (forward-only, or rejected)." },
         hotScore: { type: "integer", minimum: 0, maximum: 100 },
         qualificationNotes: { type: "string", description: "Agent reasoning for qualification/rejection." },
+        leadBrief: { type: "string", description: "2-3 sentence human-readable lead summary for sales prep. NOT ICP analysis — a cheat sheet: who this person is, what they care about, notable background, conversation hooks." },
         notes: { type: "string" },
         name: { type: "string", description: "Update contact name." },
         profileData: { type: "object", description: "Full LinkedIn profile snapshot (JSON)." },

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "bereach-openclaw",
   "name": "BeReach",
-  "version": "1.5.5",
+  "version": "1.5.7",
   "description": "LinkedIn outreach automation — 75+ tools, hook-based enforcement, dynamic context",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bereach-openclaw",
-  "version": "1.5.5",
+  "version": "1.5.7",
   "description": "BeReach LinkedIn automation plugin for OpenClaw",
   "license": "AGPL-3.0",
   "exports": {

package/src/commands/connector.ts

@@ -58,10 +58,19 @@ type TaskResult = {
   commentsPosted?: number;
   invitationsAccepted?: number;
   error?: string;
+  reason?: string;
 };
 
 const MIN_POLL_MS = 5000;
 
+/** Thrown when API returns 401/403 - credentials are invalid, retrying won't help */
+export class AuthError extends Error {
+  constructor(public readonly statusCode: number, body: string) {
+    super(`Auth failed (HTTP ${statusCode}): ${body.slice(0, 200)}`);
+    this.name = "AuthError";
+  }
+}
+
 // ---------------------------------------------------------------------------
 // TaskResult extraction from OpenClaw agent output
 // ---------------------------------------------------------------------------
@@ -166,6 +175,9 @@ async function httpPost(url: string, body: unknown, headers: Record<string, stri
   });
   if (!res.ok) {
     const text = await res.text().catch(() => "");
+    if (res.status === 401 || res.status === 403) {
+      throw new AuthError(res.status, text);
+    }
     throw new Error(`HTTP ${res.status}: ${text.slice(0, 200)}`);
   }
   return res.json();
@@ -230,13 +242,12 @@ async function isWebhookAvailable(config: ConnectorConfig): Promise<boolean> {
     if (res.status === 401 || res.status === 403) return false;
     if (res.ok || res.status === 405 || res.status === 204) return true;
 
-    // Some gateways don't support OPTIONS - fall back to GET on root
-    const rootRes = await fetch(config.gatewayUrl, {
-      method: "GET",
-      signal: AbortSignal.timeout(3000),
-    });
-    // Gateway is up - assume hooks are available if we have a token
-    return rootRes.ok || rootRes.status === 404;
+    // OPTIONS returned non-2xx/405 (e.g. 404): /hooks/agent doesn't exist.
+    // Don't assume hooks are available just because the gateway root responds.
+    // This prevents a false-positive where the connector keeps dispatching
+    // to a webhook URL that doesn't exist, failing every task with 404.
+    console.log(`[connector] Webhook probe: OPTIONS /hooks/agent returned ${res.status}, hooks not available`);
+    return false;
   } catch {
     return false;
   }
@@ -480,9 +491,18 @@ async function executeOnOpenClaw(
   config: ConnectorConfig,
   task: NonNullable<PullResponse["task"]>,
   webhookAvailable: boolean,
-): Promise<{ result: TaskResult | null; error: string | null }> {
+): Promise<{ result: TaskResult | null; error: string | null; webhookDead?: boolean }> {
   if (webhookAvailable) {
-    return executeViaWebhook(config, task);
+    const res = await executeViaWebhook(config, task);
+    // Detect webhook 404 — hooks endpoint doesn't exist (plugin version mismatch,
+    // gateway restart needed). Fall back to execFile for this task AND signal the
+    // main loop to flip webhookAvailable so subsequent tasks don't keep failing.
+    if (res.error?.startsWith("Webhook HTTP 404")) {
+      console.warn(`[connector] Webhook returned 404, falling back to execFile for task ${task.id}`);
+      const fallback = await executeViaExecFile(task);
+      return { ...fallback, webhookDead: true };
+    }
+    return res;
   }
   console.log(`[connector] Webhook unavailable, falling back to execFile`);
   return executeViaExecFile(task);
@@ -504,7 +524,7 @@ async function updateTaskStatus(
 }
 
 export type ConnectorStatus = {
-  state: "stopped" | "starting" | "running" | "stopping" | "error" | "disabled";
+  state: "stopped" | "starting" | "running" | "stopping" | "error" | "disabled" | "dormant";
   uptime: number;
   lastHeartbeat: number;
   currentTaskId: string | undefined;
@@ -515,16 +535,26 @@ export type ConnectorStatus = {
 
 export async function runConnectorLoop(
   config: ConnectorConfig,
-  options?: { signal?: AbortSignal },
+  options?: { signal?: AbortSignal; onHeartbeat?: () => void },
 ): Promise<void> {
   let pollInterval = config.pollIntervalMs;
   let currentTaskId: string | undefined;
   let consecutiveErrors = 0;
+  let consecutiveAuthErrors = 0;
   let totalTasksExecuted = 0;
   let webhookAvailable = false;
 
   const signal = options?.signal;
 
+  // Internal AbortController: links heartbeat + poll loops so either can abort both.
+  // When heartbeat detects auth failure → aborts internal → poll loop exits too.
+  // External signal (from ConnectorManager) is forwarded to internal.
+  const internalAbort = new AbortController();
+  const internalSignal = internalAbort.signal;
+  if (signal) {
+    signal.addEventListener("abort", () => internalAbort.abort(signal.reason), { once: true });
+  }
+
   console.log(`[connector] Starting connector loop`);
   console.log(`[connector] API: ${config.apiUrl}`);
   console.log(`[connector] Auth: ${config.apiKey ? "API key (Bearer)" : "connector token (legacy)"}`);
@@ -541,32 +571,47 @@ export async function runConnectorLoop(
 
   // Heartbeat runs independently - does NOT touch pollInterval or consecutiveErrors.
   // Otherwise it would neutralize exponential backoff during error recovery.
+  // Uses internalAbort so auth failures kill both heartbeat AND poll loops.
   let consecutiveHeartbeatFailures = 0;
+  let consecutiveHeartbeatAuthErrors = 0;
   const heartbeatLoop = async () => {
-    while (!signal?.aborted) {
+    let heartbeatIntervalMs = 30_000;
+    while (!internalSignal.aborted) {
       try {
         await heartbeat(config, currentTaskId);
         consecutiveHeartbeatFailures = 0;
+        consecutiveHeartbeatAuthErrors = 0;
+        heartbeatIntervalMs = 30_000;
+        options?.onHeartbeat?.();
       } catch (err) {
         consecutiveHeartbeatFailures++;
-        console.error(`[connector] Heartbeat failed (${consecutiveHeartbeatFailures}):`, err);
-        if (consecutiveHeartbeatFailures === 5) {
-          console.warn("[connector] WARNING: 5 consecutive heartbeat failures, API may be unreachable");
-        }
-        if (consecutiveHeartbeatFailures >= 10) {
-          console.error("[connector] FATAL: 10 heartbeat failures, aborting connector for restart");
-          // Throw to exit the heartbeat loop - ConnectorManager will restart us
-          throw new Error("Too many consecutive heartbeat failures");
+        if (err instanceof AuthError) {
+          consecutiveHeartbeatAuthErrors++;
+          console.error(`[connector] Heartbeat auth failed (${consecutiveHeartbeatAuthErrors}/3): ${err.message}`);
+          if (consecutiveHeartbeatAuthErrors >= 3) {
+            console.error("[connector] FATAL: 3 consecutive auth failures in heartbeat, API key is invalid");
+            internalAbort.abort(err);
+            return;
+          }
+        } else {
+          consecutiveHeartbeatAuthErrors = 0;
+          console.error(`[connector] Heartbeat failed (${consecutiveHeartbeatFailures}):`, err instanceof Error ? err.message : String(err));
+          if (consecutiveHeartbeatFailures === 5) {
+            console.warn("[connector] WARNING: 5 consecutive heartbeat failures, API may be unreachable");
+          }
+          // Exponential backoff: 30s → 60s → 120s → max 5min (never die for transient errors)
+          heartbeatIntervalMs = Math.min(heartbeatIntervalMs * 2, 5 * 60 * 1000);
         }
       }
       await new Promise((r) => {
-        const timer = setTimeout(r, 30_000);
-        signal?.addEventListener("abort", () => { clearTimeout(timer); r(undefined); }, { once: true });
+        const timer = setTimeout(r, heartbeatIntervalMs);
+        internalSignal.addEventListener("abort", () => { clearTimeout(timer); r(undefined); }, { once: true });
       });
     }
   };
   heartbeatLoop().catch((err) => {
     console.error("[connector] Heartbeat loop crashed:", err instanceof Error ? err.message : String(err));
+    if (!internalSignal.aborted) internalAbort.abort(err);
   });
 
   // Task execution lock - prevents concurrent task execution.
@@ -574,11 +619,11 @@ export async function runConnectorLoop(
   let isExecuting = false;
   let idlePollCount = 0;
 
-  while (!signal?.aborted) {
+  while (!internalSignal.aborted) {
     try {
       // Skip polling while a task is running - prevents claiming concurrent tasks
       if (isExecuting) {
-        await sleep(pollInterval, signal);
+        await sleep(pollInterval, internalSignal);
         continue;
       }
 
@@ -612,6 +657,7 @@ export async function runConnectorLoop(
         );
 
         try {
+          (task as any)._startedAt = Date.now();
           await updateTaskStatus(config, task.id, "accepted");
           await updateTaskStatus(config, task.id, "running");
 
@@ -625,9 +671,9 @@ export async function runConnectorLoop(
           }, watchdogMs);
           watchdogTimer.unref(); // Don't prevent graceful shutdown
 
-          const { result, error } = await Promise.race([
+          const execResult = await Promise.race([
             executeOnOpenClaw(config, task, webhookAvailable),
-            new Promise<{ result: null; error: string }>((resolve) => {
+            new Promise<{ result: null; error: string; webhookDead?: boolean }>((resolve) => {
               const check = setTimeout(() => {
                 if (watchdogFired) {
                   resolve({ result: null, error: `Watchdog: task execution exceeded ${Math.round(watchdogMs / 1000)}s timeout` });
@@ -636,21 +682,36 @@ export async function runConnectorLoop(
               check.unref();
             }),
           ]);
+          const { result, error } = execResult;
+          // If webhook returned 404, disable it for future tasks
+          if (execResult.webhookDead) {
+            console.warn(`[connector] Disabling webhook mode — /hooks/agent not available`);
+            webhookAvailable = false;
+          }
           clearTimeout(watchdogTimer);
 
           const taskStatus = error ? "failed" : (result?.success !== false ? "succeeded" : "failed");
+          const execDuration = Date.now() - (task as any)._startedAt;
           console.log(
-            `[connector] Task ${task.id} ${taskStatus}${error ? `: ${error.slice(0, 100)}` : ""}${task.workflowRunId ? ` workflow=${task.workflowRunId}` : ""}`,
+            `[connector] Task ${task.id} ${taskStatus} (${Math.round(execDuration / 1000)}s)${error ? `: ${error.slice(0, 100)}` : ""}${result?.reason ? ` reason=${result.reason}` : ""}${task.workflowRunId ? ` workflow=${task.workflowRunId}` : ""}`,
           );
-
-          // With webhook execution, the lifecycle hook auto-reports results.
-          // Submit from connector for execFile fallback, errors, or as safety net
-          // when lifecycle hook may not have fired (agent crash).
-          // Don't submit if result looks successful — lifecycle hook already posted.
-          if (!webhookAvailable || error) {
-            await submitResult(config, task.id, result, error);
+          // Flag suspicious fast failures with no tools for investigation
+          if (!error && result?.success === false && (result as any)?.toolCallCount === 0 && execDuration < 10_000) {
+            console.warn(`[connector] DIAGNOSTIC: Task ${task.id} failed in <10s with 0 tool calls — likely context injection failure or model error`);
           }
 
+          // Always submit from connector as safety net. In webhook mode the lifecycle
+          // hook usually reports first, but if it fails silently (network, crash) the
+          // result is lost and the task stays "running" forever. The result endpoint
+          // uses an optimistic lock so double-submissions are harmless (second is a no-op).
+          // Derive error when result indicates failure but no explicit error exists.
+          const derivedError = error ?? (
+            result?.success === false
+              ? (result.error ?? result.reason ?? "Task failed (no details from agent)")
+              : undefined
+          );
+          await submitResult(config, task.id, result, derivedError ?? null);
+
           totalTasksExecuted++;
           pollInterval = 5_000;
         } finally {
@@ -666,10 +727,22 @@ export async function runConnectorLoop(
       isExecuting = false;
       currentTaskId = undefined;
       (globalThis as any).__bereachCurrentTaskId = undefined;
-      console.error(
-        `[connector] Poll error (${consecutiveErrors}):`,
-        err,
-      );
+
+      if (err instanceof AuthError) {
+        consecutiveAuthErrors++;
+        console.error(`[connector] Poll auth failed (${consecutiveAuthErrors}/3): ${err.message}`);
+        if (consecutiveAuthErrors >= 3) {
+          console.error("[connector] FATAL: 3 consecutive auth failures in poll loop, API key is invalid");
+          internalAbort.abort(err);
+          break;
+        }
+      } else {
+        consecutiveAuthErrors = 0;
+        console.error(
+          `[connector] Poll error (${consecutiveErrors}):`,
+          err instanceof Error ? err.message : String(err),
+        );
+      }
 
       pollInterval = Math.min(
         config.pollIntervalMs * Math.pow(2, consecutiveErrors),
@@ -686,10 +759,17 @@ export async function runConnectorLoop(
       }
     }
 
-    await sleep(pollInterval, signal);
+    await sleep(pollInterval, internalSignal);
   }
 
   console.log("[connector] Loop stopped (abort signal received)");
+
+  // If internal abort fired (auth failure) but external didn't (not a graceful shutdown),
+  // throw so ConnectorManager.handleCrash() triggers with the auth error.
+  if (internalSignal.aborted && !signal?.aborted) {
+    const reason = internalSignal.reason;
+    throw reason instanceof Error ? reason : new Error("Connector loop aborted internally");
+  }
 }
 
 /** Re-probe webhook availability. Called by ConnectorManager on retry. */

package/src/connector/manager.ts

@@ -4,39 +4,75 @@
  * Auto-starts the polling loop from register() when an API key is present.
  * Handles crash recovery with exponential backoff, graceful shutdown on
  * SIGTERM/SIGINT, and prevents duplicate instances.
+ *
+ * Key resilience features:
+ * - AuthError detection: distinguishes auth failures from transient errors
+ * - Dormant mode: after persistent auth failures, enters low-power probe mode
+ *   instead of burning restarts. Probes every 15 min and auto-recovers.
+ * - Config resolver: re-resolves API key on each restart/probe
+ * - Health check: detects zombie state (running but heartbeat dead)
  */
 
-import { runConnectorLoop, isWebhookAvailable, type ConnectorConfig, type ConnectorStatus } from "../commands/connector.js";
+import { runConnectorLoop, isWebhookAvailable, AuthError, type ConnectorConfig, type ConnectorStatus } from "../commands/connector.js";
 
 const MAX_RESTARTS = 10;
 const INITIAL_RESTART_DELAY_MS = 1_000;
 const MAX_RESTART_DELAY_MS = 30_000;
+const DORMANT_PROBE_INTERVAL_MS = 15 * 60 * 1000; // 15 min
 
-export type ConnectorManagerState = "stopped" | "starting" | "running" | "stopping" | "error" | "disabled";
+export type ConnectorManagerState = "stopped" | "starting" | "running" | "stopping" | "error" | "disabled" | "dormant";
 
 class ConnectorManager {
   private state: ConnectorManagerState = "stopped";
   private abortController: AbortController | null = null;
   private config: ConnectorConfig | null = null;
+  private resolveConfig: (() => ConnectorConfig) | null = null;
   private restartCount = 0;
   private startedAt = 0;
   private lastHeartbeatAt = 0;
   private totalTasksExecuted = 0;
   private consecutiveErrors = 0;
+  private consecutiveAuthCrashes = 0;
   private executionMode: "webhook" | "execFile" = "execFile";
   private loopPromise: Promise<void> | null = null;
   private signalHandlersInstalled = false;
+  private stabilityTimer: ReturnType<typeof setTimeout> | null = null;
+  private dormantTimer: ReturnType<typeof setTimeout> | null = null;
 
   /**
-   * Start the connector. Idempotent - if already running, logs and returns.
+   * Start the connector. Accepts either a static config or a resolver function
+   * that re-resolves config (including API key) on each restart.
+   *
+   * Idempotent with smart recovery:
+   * - If dormant: wakes up and attempts restart (user may have changed key)
+   * - If running but unhealthy: forces restart
+   * - If running and healthy: skips
    */
-  async start(config: ConnectorConfig): Promise<void> {
-    if (this.state === "running" || this.state === "starting") {
-      console.log("[bereach:connector] skip duplicate start (already running)");
-      return;
+  async start(configOrResolver: ConnectorConfig | (() => ConnectorConfig)): Promise<void> {
+    // Store resolver for future re-resolution
+    if (typeof configOrResolver === "function") {
+      this.resolveConfig = configOrResolver;
+      this.config = configOrResolver();
+    } else {
+      this.resolveConfig = null;
+      this.config = configOrResolver;
+    }
+
+    if (this.state === "dormant") {
+      // User may have changed their key - wake up and try
+      console.log("[bereach:connector] waking from dormant mode (register() called)");
+      if (this.dormantTimer) { clearTimeout(this.dormantTimer); this.dormantTimer = null; }
+      this.consecutiveAuthCrashes = 0;
+      // Fall through to normal start
+    } else if (this.state === "running" || this.state === "starting") {
+      if (this.isHealthy()) {
+        console.log("[bereach:connector] skip duplicate start (already running and healthy)");
+        return;
+      }
+      console.warn("[bereach:connector] connector unhealthy, forcing restart");
+      await this.stop();
     }
 
-    this.config = config;
     this.state = "starting";
     this.restartCount = 0;
 
@@ -73,11 +109,11 @@ class ConnectorManager {
       process.on("SIGINT", () => shutdown("SIGINT"));
     }
 
-    // Probe webhook availability with retry — the gateway HTTP server may not be
+    // Probe webhook availability with retry - the gateway HTTP server may not be
     // listening yet when register() fires during plugin load.
     let webhookOk = false;
     for (let attempt = 1; attempt <= 5; attempt++) {
-      webhookOk = await isWebhookAvailable(config);
+      webhookOk = await isWebhookAvailable(this.config);
       if (webhookOk) break;
       if (attempt < 5) {
         console.log(`[bereach:connector] webhook probe attempt ${attempt}/5 failed, retrying in 3s...`);
@@ -95,6 +131,9 @@ class ConnectorManager {
   async stop(): Promise<void> {
     if (this.state === "stopped" || this.state === "disabled") return;
 
+    // Clean up dormant timer if active
+    if (this.dormantTimer) { clearTimeout(this.dormantTimer); this.dormantTimer = null; }
+
     this.state = "stopping";
     console.log("[bereach:connector] stopping...");
 
@@ -128,10 +167,43 @@ class ConnectorManager {
     };
   }
 
-  private stabilityTimer: ReturnType<typeof setTimeout> | null = null;
+  /**
+   * Check if the connector is actually healthy (not a zombie).
+   * Unhealthy = running state but no heartbeat in 5+ minutes,
+   * or running for 2+ minutes without ever getting a heartbeat.
+   */
+  private isHealthy(): boolean {
+    if (this.state !== "running") return false;
+    const now = Date.now();
+    const uptime = now - this.startedAt;
+    // Just started (< 2 min), give it time
+    if (uptime < 2 * 60 * 1000) return true;
+    // No heartbeat ever received after 2 min = zombie
+    if (!this.lastHeartbeatAt) return false;
+    // Last heartbeat > 5 min ago = zombie
+    return (now - this.lastHeartbeatAt) < 5 * 60 * 1000;
+  }
+
+  /**
+   * Re-resolve config from the resolver (picks up API key changes).
+   * Falls back to stored config if no resolver.
+   */
+  private freshConfig(): ConnectorConfig | null {
+    if (this.resolveConfig) {
+      try {
+        this.config = this.resolveConfig();
+        const masked = this.config.apiKey ? `...${this.config.apiKey.slice(-6)}` : "NOT SET";
+        console.log(`[bereach:connector] re-resolved config (API key: ${masked})`);
+      } catch (err) {
+        console.error("[bereach:connector] config resolver failed:", err instanceof Error ? err.message : String(err));
+      }
+    }
+    return this.config;
+  }
 
   private startLoop(): void {
-    if (!this.config) return;
+    const config = this.freshConfig();
+    if (!config) return;
 
     this.abortController = new AbortController();
     this.startedAt = Date.now();
@@ -151,7 +223,10 @@ class ConnectorManager {
     }, 5 * 60 * 1000);
     this.stabilityTimer.unref();
 
-    this.loopPromise = runConnectorLoop(this.config, { signal: this.abortController.signal })
+    this.loopPromise = runConnectorLoop(config, {
+      signal: this.abortController.signal,
+      onHeartbeat: () => { this.lastHeartbeatAt = Date.now(); },
+    })
       .then(() => {
         // Normal exit (abort signal)
         if (this.state !== "stopping") {
@@ -160,14 +235,29 @@ class ConnectorManager {
       })
       .catch((err) => {
         console.error(`[bereach:connector] loop crashed: ${err instanceof Error ? err.message : String(err)}`);
-        this.handleCrash();
+        this.handleCrash(err);
       });
   }
 
-  private handleCrash(): void {
+  private handleCrash(err?: unknown): void {
     this.restartCount++;
     this.consecutiveErrors++;
 
+    // Track consecutive auth-related crashes for dormant mode.
+    // 2 auth crashes = 2 full start→3-failures→crash cycles = ~6 total 401s.
+    const isAuthCrash = err instanceof AuthError ||
+      (err instanceof Error && err.message.includes("Auth failed"));
+    if (isAuthCrash) {
+      this.consecutiveAuthCrashes++;
+      console.error(`[bereach:connector] auth crash ${this.consecutiveAuthCrashes}/2`);
+      if (this.consecutiveAuthCrashes >= 2) {
+        this.enterDormant();
+        return;
+      }
+    } else {
+      this.consecutiveAuthCrashes = 0;
+    }
+
     if (this.restartCount > MAX_RESTARTS) {
       // Don't give up permanently - enter cooldown then restart.
       // The user's VPS has no supervisor to restart us, so we must self-recover.
@@ -199,6 +289,69 @@ class ConnectorManager {
       this.startLoop();
     }, delay);
   }
+
+  /**
+   * Enter dormant mode - lightweight 15-min probe instead of full restart loop.
+   * Used when API key is confirmed invalid (persistent auth failures).
+   * Auto-recovers when the key becomes valid again.
+   */
+  private enterDormant(): void {
+    this.state = "dormant";
+    this.abortController = null;
+    this.loopPromise = null;
+    console.error(
+      "[bereach:connector] API key invalid - entering dormant mode. " +
+      "Will probe every 15 min and auto-recover when key is fixed.",
+    );
+    this.scheduleDormantProbe();
+  }
+
+  private scheduleDormantProbe(): void {
+    if (this.dormantTimer) clearTimeout(this.dormantTimer);
+    this.dormantTimer = setTimeout(() => this.runDormantProbe(), DORMANT_PROBE_INTERVAL_MS);
+    this.dormantTimer.unref();
+  }
+
+  private async runDormantProbe(): Promise<void> {
+    if (this.state !== "dormant") return;
+
+    // Re-resolve config to pick up any key changes
+    const config = this.freshConfig();
+    if (!config?.apiKey) {
+      console.log("[bereach:connector] dormant probe: no API key configured, will retry in 15 min");
+      this.scheduleDormantProbe();
+      return;
+    }
+
+    // Single lightweight heartbeat probe
+    try {
+      const res = await fetch(`${config.apiUrl}/connectors/heartbeat`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${config.apiKey}`,
+        },
+        body: JSON.stringify({}),
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (res.ok) {
+        console.log("[bereach:connector] dormant probe succeeded! Restarting connector.");
+        this.consecutiveAuthCrashes = 0;
+        this.restartCount = 0;
+        this.consecutiveErrors = 0;
+        this.startLoop();
+        return;
+      }
+      if (res.status === 401 || res.status === 403) {
+        console.log("[bereach:connector] dormant probe: still 401, will retry in 15 min");
+      } else {
+        console.log(`[bereach:connector] dormant probe: HTTP ${res.status}, will retry in 15 min`);
+      }
+    } catch (err) {
+      console.log(`[bereach:connector] dormant probe failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    this.scheduleDormantProbe();
+  }
 }
 
 // Module-level singleton

package/src/hooks/lifecycle.ts

@@ -125,9 +125,25 @@ export function registerLifecycleHook(
           creditsUsed: state.creditsUsedThisSession,
           toolCallCount: state.toolCallCount,
           visitCount: state.visitCount,
-          ...(state.toolCallCount === 0 ? { reason: "no_tools_called" } : {}),
+          ...(state.toolCallCount === 0 ? { reason: "no_tools_called", error: "Task completed with no tool calls" } : {}),
         };
 
+        // Diagnostic logging for no_tools_called — capture WHY the agent did nothing.
+        // This helps diagnose context injection failures, model errors, etc.
+        if (state.toolCallCount === 0) {
+          const msgCount = allMessages.length;
+          const userMsgCount = userMsgs.length;
+          const assistantMsgCount = assistantMsgs.length;
+          const lastAssistantText = outputText?.slice(0, 300) || "(empty)";
+          const hasTaskMeta = userMsgs.some((m: any) => extractTextFromContent(m.content).includes("TASK_META"));
+          const endSuccess = (endCtx as any)?.success;
+          const endError = (endCtx as any)?.error;
+          log(`NO_TOOLS_CALLED diagnostic for ${taskMode.taskId}: ` +
+            `msgs=${msgCount} (user=${userMsgCount} assistant=${assistantMsgCount}) ` +
+            `hasTaskMeta=${hasTaskMeta} endSuccess=${endSuccess} endError=${endError ? String(endError).slice(0, 200) : "none"} ` +
+            `lastAssistant="${lastAssistantText}"`);
+        }
+
         // B17 fix: In execFile mode, the connector also submits results after
         // parsing the OpenClaw --json wrapper (extractTaskResultFromWrapper).
         // The lifecycle hook fires first (inside subprocess), so it wins the race.
@@ -148,10 +164,14 @@ export function registerLifecycleHook(
           attempts++;
           try {
             if (attempt > 0) await new Promise((r) => setTimeout(r, 2000 * attempt));
+            // Derive error from result when task failed but no explicit error exists
+            const taskError = taskResult.success === false
+              ? (taskResult.error ?? taskResult.reason ?? "Task failed (no details captured)")
+              : undefined;
             const res = await fetch(`${API_BASE}/tasks/${taskMode.taskId}/result`, {
               method: "POST",
               headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
-              body: JSON.stringify({ result: taskResult }),
+              body: JSON.stringify({ result: taskResult, ...(taskError ? { error: taskError } : {}) }),
               signal: AbortSignal.timeout(10000),
             });
             if (res.ok) {

package/src/index.ts

@@ -18,6 +18,9 @@ const log = createLogger("init");
 const registeredApis = new WeakSet<object>();
 let registeredCount = 0;
 let autoDetectDone = false;
+let lastRegisterAt = 0;
+/** After initial burst, suppress noisy re-registration logs */
+const REGISTER_LOG_THRESHOLD = 5;
 
 /**
  * Resolve the BeReach API key from all supported sources (in priority order):
@@ -120,8 +123,11 @@ export default function register(api: any) {
   }
 
   registeredCount++;
-  if (registeredCount > 1) {
+  lastRegisterAt = Date.now();
+  if (registeredCount > 1 && registeredCount <= REGISTER_LOG_THRESHOLD) {
     log(`register() called again (call #${registeredCount}) — re-registering on new api instance`);
+  } else if (registeredCount === REGISTER_LOG_THRESHOLD + 1) {
+    log(`register() call #${registeredCount} — suppressing further re-registration logs`);
   }
   if (api && typeof api === "object") {
     registeredApis.add(api);
@@ -226,14 +232,14 @@ export default function register(api: any) {
     const gatewayUrl = config.gatewayUrl || readEnv("OPENCLAW_GATEWAY_URL") || "http://localhost:18789";
     const pollMs = config.connectorPollIntervalMs ?? 15000;
 
-    connectorManager.start({
-      apiKey,
+    connectorManager.start(() => ({
+      apiKey: resolveApiKey(api),
       apiUrl: API_BASE,
       openclawUrl: readEnv("OPENCLAW_URL") || "http://localhost:3579",
       pollIntervalMs: Math.max(5000, pollMs),
       gatewayUrl,
       hooksToken,
-    }).catch((err) => {
+    })).catch((err) => {
       log(`connector auto-start failed: ${err instanceof Error ? err.message : String(err)}`);
     });
   } else if (!connectorEnabled) {