fix: filter ghost workers from health output

Co-authored-by: Codex <noreply@openai.com>

Author: ericjuta

README.md

@@ -959,12 +959,22 @@ This restarts both the engine and worker, clearing stale channels. Data is prese
 # Restart without rebuilding (clears stale engine state)
 docker compose restart
 
+# Rebuild the worker image explicitly
+docker compose build agentmemory-worker
+
 # Rebuild after code changes
 docker compose up -d --build
 
 # Rebuild only the worker (faster, keeps engine running)
 docker compose up -d --build agentmemory-worker
 
+# Force-recreate the worker from the current local image
+docker compose up -d --force-recreate agentmemory-worker
+
+# Common live-fix sequence after worker code changes
+docker compose build agentmemory-worker
+docker compose up -d --force-recreate agentmemory-worker
+
 # View worker logs
 docker compose logs -f agentmemory-worker
 

src/health/monitor.ts

@@ -2,6 +2,7 @@
 import type { ISdk } from "iii-sdk";
 import { getHeapStatistics } from "node:v8";
 import type { HealthSnapshot } from "../types.js";
+import type { HealthWorker } from "../types.js";
 import type { StateKV } from "../state/kv.js";
 import { KV } from "../state/schema.js";
 import { evaluateHealth } from "./thresholds.js";
@@ -12,12 +13,51 @@ let latestHealthSnapshot: HealthSnapshot | null = null;
 const BASE_INTERVAL_MS = 30_000;
 const MAX_INTERVAL_MS = 300_000; // 5 min cap when backing off
 
+const GHOST_WORKER_CONNECTED_DELTA_MS = 5_000;
+
 export interface PipelineMetrics {
   compressActive: number;
   compressPending: number;
   totalInflight: number;
 }
 
+function isGhostWorkerCandidate(worker: HealthWorker): boolean {
+  return (
+    worker.status === "connected" &&
+    (worker.function_count ?? 0) === 0 &&
+    !worker.name &&
+    !worker.runtime &&
+    !worker.version
+  );
+}
+
+function sharesWorkerOrigin(a: HealthWorker, b: HealthWorker): boolean {
+  if (a.ip_address && b.ip_address && a.ip_address === b.ip_address) {
+    return true;
+  }
+  if (
+    typeof a.connected_at_ms === "number" &&
+    typeof b.connected_at_ms === "number" &&
+    Math.abs(a.connected_at_ms - b.connected_at_ms) <= GHOST_WORKER_CONNECTED_DELTA_MS
+  ) {
+    return true;
+  }
+  return false;
+}
+
+export function filterGhostWorkers(workers: HealthWorker[]): HealthWorker[] {
+  return workers.filter((worker) => {
+    if (!isGhostWorkerCandidate(worker)) return true;
+    return !workers.some((other) => {
+      if (other.id === worker.id) return false;
+      if (other.status !== "connected") return false;
+      if ((other.function_count ?? 0) <= 0) return false;
+      if (!other.name) return false;
+      return sharesWorkerOrigin(worker, other);
+    });
+  });
+}
+
 export function registerHealthMonitor(
   sdk: ISdk,
   kv: StateKV,
@@ -75,7 +115,7 @@ export function registerHealthMonitor(
         unknown,
         { workers?: HealthSnapshot["workers"] }
       >({ function_id: "engine::workers::list", payload: {} });
-      if (result?.workers) workers = result.workers;
+      if (result?.workers) workers = filterGhostWorkers(result.workers);
     } catch {}
 
     // Skip KV probe when persist circuit is open — engine is already struggling

src/types.ts

@@ -348,9 +348,21 @@ export interface FunctionMetrics {
   avgQualityScore: number;
 }
 
+export interface HealthWorker {
+  id: string;
+  name: string | null;
+  status: string;
+  connected_at_ms?: number;
+  function_count?: number;
+  ip_address?: string | null;
+  runtime?: string | null;
+  version?: string | null;
+  [key: string]: unknown;
+}
+
 export interface HealthSnapshot {
   connectionState: string;
-  workers: Array<{ id: string; name: string; status: string }>;
+  workers: HealthWorker[];
   memory: {
     heapUsed: number;
     heapTotal: number;

test/health-monitor.test.ts

@@ -1,6 +1,10 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { registerHealthMonitor, getLatestHealth } from "../src/health/monitor.js";
+import {
+  filterGhostWorkers,
+  registerHealthMonitor,
+  getLatestHealth,
+} from "../src/health/monitor.js";
 import { KV } from "../src/state/schema.js";
 
 describe("registerHealthMonitor", () => {
@@ -46,4 +50,32 @@ describe("registerHealthMonitor", () => {
 
     monitor.stop();
   });
+
+  it("filters the duplicate anonymous zero-function ghost worker", () => {
+    const workers = filterGhostWorkers([
+      {
+        id: "real",
+        name: "agentmemory",
+        status: "connected",
+        function_count: 289,
+        connected_at_ms: 1001,
+        ip_address: "172.18.0.3",
+        runtime: "node",
+        version: "0.11.0",
+      },
+      {
+        id: "ghost",
+        name: null,
+        status: "connected",
+        function_count: 0,
+        connected_at_ms: 1000,
+        ip_address: "172.18.0.3",
+        runtime: null,
+        version: null,
+      },
+    ]);
+
+    expect(workers).toHaveLength(1);
+    expect(workers[0]?.id).toBe("real");
+  });
 });