@feynmanzhang/open-party 0.1.3 → 0.1.5

package/dist/cli/index.js

@@ -138,11 +138,11 @@ function execWithSudoFallback(cmd, timeout = 15e3) {
 function joinTailnet(authKey, timeout = 3e4) {
   const binary = getTailscaleBinary();
   try {
-    const output = execWithSudoFallback(
+    const output2 = execWithSudoFallback(
       [binary, "up", "--authkey", authKey],
       timeout
     );
-    return { success: true, output: output.trim() };
+    return { success: true, output: output2.trim() };
   } catch (e) {
     const err = e;
     return { success: false, output: (err.stderr ?? err.message ?? "").trim() };
@@ -168,11 +168,12 @@ function getTailscaleInstallationStatus() {
       };
     }
     return { state: "not_connected", binary };
-  } catch (e) {
+  } catch (error) {
+    console.error("[Tailscale] Failed to get installation status:", error);
     return {
       state: "not_connected",
       binary,
-      error: e.message
+      error: error instanceof Error ? error.message : String(error)
     };
   }
 }
@@ -182,9 +183,9 @@ function resetTailscaleBinaryCache() {
 function logoutTailscale(timeout = 15e3) {
   const binary = getTailscaleBinary();
   try {
-    const output = runExec([binary, "logout"], timeout);
+    const output2 = runExec([binary, "logout"], timeout);
     resetTailscaleBinaryCache();
-    return { success: true, output: output.trim() };
+    return { success: true, output: output2.trim() };
   } catch (e) {
     const err = e;
     return { success: false, output: (err.stderr ?? err.message ?? "").trim() };
@@ -3342,14 +3343,348 @@ var init_config = __esm({
   "src/server/config.ts"() {
     "use strict";
     PARTY_PORT = parseInt(process.env.PARTY_PORT || "8000", 10);
-    HEARTBEAT_TIMEOUT = parseFloat(process.env.HEARTBEAT_TIMEOUT || "30");
-    CLEANUP_INTERVAL = parseFloat(process.env.CLEANUP_INTERVAL || "10");
+    HEARTBEAT_TIMEOUT = parseFloat(process.env.HEARTBEAT_TIMEOUT || "60");
+    CLEANUP_INTERVAL = parseFloat(process.env.CLEANUP_INTERVAL || "60");
     DISCOVERY_INTERVAL = parseFloat(process.env.DISCOVERY_INTERVAL || "20");
     REMOTE_STALE_FACTOR = parseInt(process.env.REMOTE_STALE_FACTOR || "3", 10);
     PROBE_TIMEOUT = parseFloat(process.env.PROBE_TIMEOUT || "5");
   }
 });
 
+// src/server/logger.ts
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, appendFileSync, readdirSync as readdirSync2, unlinkSync as unlinkSync2, statSync } from "fs";
+import { join as join5 } from "path";
+import { homedir as homedir4 } from "os";
+function getEffectiveLevel() {
+  const env = (process.env.LOG_LEVEL || "info").toLowerCase().trim();
+  if (env in LEVEL_ORDER) return env;
+  return "info";
+}
+function initLogFile() {
+  if (!existsSync5(LOG_DIR)) {
+    mkdirSync3(LOG_DIR, { recursive: true });
+    return;
+  }
+  try {
+    const now = Date.now();
+    const cutoff = now - LOG_RETENTION_DAYS * 24 * 60 * 60 * 1e3;
+    const files = readdirSync2(LOG_DIR);
+    for (const f of files) {
+      if (!f.endsWith("-open-party.log")) continue;
+      try {
+        const stat = statSync(join5(LOG_DIR, f));
+        if (stat.mtimeMs < cutoff) {
+          unlinkSync2(join5(LOG_DIR, f));
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+}
+function getLogFilePath() {
+  const d = /* @__PURE__ */ new Date();
+  const yy = String(d.getFullYear()).slice(2);
+  const mm = String(d.getMonth() + 1).padStart(2, "0");
+  const dd = String(d.getDate()).padStart(2, "0");
+  return join5(LOG_DIR, `${yy}-${mm}-${dd}-open-party.log`);
+}
+function shouldLog(level) {
+  return LEVEL_ORDER[level] >= LEVEL_ORDER[effectiveLevel];
+}
+function extractError(err) {
+  if (err instanceof Error) {
+    const stack = err.stack ? `
+${err.stack}` : "";
+    return `${err.message}${stack}`;
+  }
+  return String(err);
+}
+function format(level, tag, message) {
+  const now = /* @__PURE__ */ new Date();
+  const levelStr = level.toUpperCase().padEnd(5);
+  const yy = String(now.getFullYear()).slice(2);
+  const mm = String(now.getMonth() + 1).padStart(2, "0");
+  const dd = String(now.getDate()).padStart(2, "0");
+  const hh = String(now.getHours()).padStart(2, "0");
+  const min = String(now.getMinutes()).padStart(2, "0");
+  const ss = String(now.getSeconds()).padStart(2, "0");
+  const ts = `${yy}-${mm}-${dd} ${hh}:${min}:${ss}`;
+  return `${ts} [${levelStr}] [${tag}] ${message}`;
+}
+function output(consoleFn, level, tag, message) {
+  if (!shouldLog(level)) return;
+  const line = format(level, tag, message);
+  consoleFn(line);
+  try {
+    appendFileSync(getLogFilePath(), line + "\n", "utf-8");
+  } catch {
+  }
+}
+var LEVEL_ORDER, effectiveLevel, LOG_DIR, LOG_RETENTION_DAYS, logger;
+var init_logger = __esm({
+  "src/server/logger.ts"() {
+    "use strict";
+    LEVEL_ORDER = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3
+    };
+    effectiveLevel = getEffectiveLevel();
+    LOG_DIR = join5(homedir4(), ".open-party", "logs");
+    LOG_RETENTION_DAYS = 7;
+    initLogFile();
+    logger = {
+      info(tag, message, data) {
+        output(console.log, "info", tag, data ? `${message} ${JSON.stringify(data)}` : message);
+      },
+      warn(tag, message, data) {
+        output(console.warn, "warn", tag, data ? `${message} ${JSON.stringify(data)}` : message);
+      },
+      error(tag, message, err) {
+        const detail = err ? `: ${extractError(err)}` : "";
+        output(console.error, "error", tag, message + detail);
+      },
+      debug(tag, message, data) {
+        output(console.debug, "debug", tag, data ? `${message} ${JSON.stringify(data)}` : message);
+      }
+    };
+  }
+});
+
+// src/server/persistence.ts
+import { existsSync as existsSync6, readFileSync as readFileSync3, writeFileSync as writeFileSync3, unlinkSync as unlinkSync3, renameSync, mkdirSync as mkdirSync4 } from "fs";
+import { join as join6 } from "path";
+import { homedir as homedir5 } from "os";
+function dataDirPath() {
+  const pluginData = process.env.CLAUDE_PLUGIN_DATA || "";
+  if (pluginData) return join6(pluginData, "data");
+  return join6(homedir5(), ".open-party", "data");
+}
+function runMigrations(raw2) {
+  const data = raw2;
+  if (!data || typeof data !== "object") {
+    throw new Error("Snapshot is not a valid object");
+  }
+  const version = typeof data.version === "number" ? data.version : 0;
+  let snapshot = {
+    version,
+    saved_at: typeof data.saved_at === "number" ? data.saved_at : 0,
+    agents: Array.isArray(data.agents) ? data.agents : [],
+    history: typeof data.history === "object" && data.history !== null && !Array.isArray(data.history) ? data.history : {}
+  };
+  for (const m of MIGRATORS) {
+    if (m.version > snapshot.version) {
+      snapshot = m.migrate(snapshot);
+      snapshot.version = m.version;
+    }
+  }
+  return snapshot;
+}
+function abortableSleep(ms, signal) {
+  return new Promise((resolve4, reject) => {
+    const timer = setTimeout(resolve4, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(new DOMException("Aborted", "AbortError"));
+      },
+      { once: true }
+    );
+  });
+}
+var CURRENT_SCHEMA_VERSION, SNAPSHOT_FILE, SHUTDOWN_MARKER_FILE, DEFAULT_SNAPSHOT_INTERVAL_MS, DEBOUNCE_MS, MIGRATORS, SnapshotManager;
+var init_persistence = __esm({
+  "src/server/persistence.ts"() {
+    "use strict";
+    init_logger();
+    CURRENT_SCHEMA_VERSION = 1;
+    SNAPSHOT_FILE = "snapshot.json";
+    SHUTDOWN_MARKER_FILE = "shutdown-marker.json";
+    DEFAULT_SNAPSHOT_INTERVAL_MS = 6e4;
+    DEBOUNCE_MS = 5e3;
+    MIGRATORS = [
+      // Future: { version: 2, migrate(snapshot) { ... } },
+    ];
+    SnapshotManager = class {
+      _dir;
+      _snapshotPath;
+      _markerPath;
+      _debounceTimer = null;
+      constructor(dataDir) {
+        this._dir = dataDir ?? dataDirPath();
+        this._snapshotPath = join6(this._dir, SNAPSHOT_FILE);
+        this._markerPath = join6(this._dir, SHUTDOWN_MARKER_FILE);
+        mkdirSync4(this._dir, { recursive: true });
+        const tmpPath = this._snapshotPath + ".tmp";
+        try {
+          if (existsSync6(tmpPath)) {
+            unlinkSync3(tmpPath);
+          }
+        } catch (error) {
+          logger.warn("Persistence", "Failed to clean up stale tmp file", error);
+        }
+      }
+      // ------------------------------------------------------------------
+      // Write / Load
+      // ------------------------------------------------------------------
+      /** Atomically write a snapshot of registry agents and message queue history. */
+      writeSnapshot(agents, history) {
+        const snapshot = {
+          version: CURRENT_SCHEMA_VERSION,
+          saved_at: Date.now(),
+          agents,
+          history
+        };
+        const serialized = JSON.stringify(snapshot, null, 2);
+        const tmpPath = this._snapshotPath + ".tmp";
+        try {
+          writeFileSync3(tmpPath, serialized, "utf-8");
+          renameSync(tmpPath, this._snapshotPath);
+        } catch (error) {
+          logger.error("Persistence", "Failed to write snapshot", error);
+          try {
+            unlinkSync3(tmpPath);
+          } catch {
+          }
+          throw error;
+        }
+      }
+      /** Load and validate snapshot. Returns null if file missing or corrupt. */
+      loadSnapshot() {
+        if (!existsSync6(this._snapshotPath)) {
+          return null;
+        }
+        try {
+          const raw2 = JSON.parse(readFileSync3(this._snapshotPath, "utf-8"));
+          return runMigrations(raw2);
+        } catch (error) {
+          logger.warn("Persistence", "Failed to load snapshot (starting fresh)", error);
+          return null;
+        }
+      }
+      // ------------------------------------------------------------------
+      // Hydration (restore in-memory state from snapshot)
+      // ------------------------------------------------------------------
+      /** Restore agents into registry. Overwrites host_ip with current selfIp. */
+      hydrateAgents(registry2, selfIp) {
+        const snapshot = this.loadSnapshot();
+        if (!snapshot || snapshot.agents.length === 0) return 0;
+        const now = Date.now() / 1e3;
+        let count = 0;
+        for (const agent of snapshot.agents) {
+          agent.last_heartbeat = now;
+          const info = registry2.register({
+            agent_id: agent.agent_id,
+            display_name: agent.display_name,
+            metadata: agent.metadata ?? {}
+          });
+          info.host_ip = selfIp;
+          count++;
+        }
+        return count;
+      }
+      /** Restore message history into queue. */
+      hydrateHistory(queue) {
+        const snapshot = this.loadSnapshot();
+        if (!snapshot || Object.keys(snapshot.history).length === 0) return 0;
+        let totalEntries = 0;
+        for (const [agentId, entries] of Object.entries(snapshot.history)) {
+          for (const entry of entries) {
+            queue.logToHistory(agentId, entry.direction, {
+              sender_id: entry.sender_id,
+              recipient_id: entry.recipient_id,
+              summary: entry.summary,
+              content: entry.content,
+              timestamp: entry.timestamp
+            });
+            totalEntries++;
+          }
+        }
+        return totalEntries;
+      }
+      // ------------------------------------------------------------------
+      // Shutdown marker
+      // ------------------------------------------------------------------
+      /** Write shutdown marker to detect interrupted shutdown on next start. */
+      writeShutdownMarker() {
+        try {
+          writeFileSync3(
+            this._markerPath,
+            JSON.stringify({ started_at: Date.now() }),
+            "utf-8"
+          );
+        } catch (error) {
+          logger.warn("Persistence", "Failed to write shutdown marker", error);
+        }
+      }
+      /** Remove shutdown marker — called after successful shutdown. */
+      removeShutdownMarker() {
+        try {
+          if (existsSync6(this._markerPath)) {
+            unlinkSync3(this._markerPath);
+          }
+        } catch (error) {
+          logger.warn("Persistence", "Failed to remove shutdown marker", error);
+        }
+      }
+      /** Check if a shutdown marker exists (indicates previous shutdown was interrupted). */
+      hasShutdownMarker() {
+        return existsSync6(this._markerPath);
+      }
+      // ------------------------------------------------------------------
+      // Snapshot loop & debounce
+      // ------------------------------------------------------------------
+      /**
+       * Start periodic snapshot background loop.
+       * Writes snapshot every `intervalMs` milliseconds until signal is aborted.
+       */
+      async startSnapshotLoop(signal, getAgents, getHistory, intervalMs = DEFAULT_SNAPSHOT_INTERVAL_MS) {
+        while (!signal.aborted) {
+          try {
+            await abortableSleep(intervalMs, signal);
+          } catch (e) {
+            if (signal.aborted) break;
+            throw e;
+          }
+          if (signal.aborted) break;
+          try {
+            this.writeSnapshot(getAgents(), getHistory());
+          } catch (error) {
+            logger.warn("Persistence", "Periodic snapshot failed", error);
+          }
+        }
+      }
+      /**
+       * Schedule a debounced snapshot write.
+       * Multiple calls within DEBOUNCE_MS window are coalesced into one write.
+       */
+      scheduleSnapshot(getAgents, getHistory) {
+        if (this._debounceTimer !== null) {
+          clearTimeout(this._debounceTimer);
+        }
+        this._debounceTimer = setTimeout(() => {
+          this._debounceTimer = null;
+          try {
+            this.writeSnapshot(getAgents(), getHistory());
+          } catch (error) {
+            logger.warn("Persistence", "Debounced snapshot failed", error);
+          }
+        }, DEBOUNCE_MS);
+      }
+      /** Cancel pending debounced snapshot (called during shutdown). */
+      cancelDebounce() {
+        if (this._debounceTimer !== null) {
+          clearTimeout(this._debounceTimer);
+          this._debounceTimer = null;
+        }
+      }
+    };
+  }
+});
+
 // src/server/message-queue.ts
 var HISTORY_CAP, MessageQueue;
 var init_message_queue = __esm({
@@ -3412,6 +3747,14 @@ var init_message_queue = __esm({
       removeAgentHistory(agentId) {
         this._history.delete(agentId);
       }
+      /** Return a shallow copy of the full history map (for persistence snapshots). */
+      getHistorySnapshot() {
+        const copy = {};
+        for (const [agentId, entries] of this._history) {
+          copy[agentId] = [...entries];
+        }
+        return copy;
+      }
     };
   }
 });
@@ -3426,15 +3769,14 @@ function classifyFetchError(error) {
   if (error instanceof DOMException && error.name === "AbortError") return null;
   return null;
 }
-function sleep2(ms) {
-  return new Promise((resolve4) => setTimeout(resolve4, ms));
-}
 var UNKNOWN, PARTY_SERVER, DEGRADED, SUSPECT, DOWN, NOT_SERVER, MAYBE, MAYBE_MAX_RETRIES, BACKOFF_BASE, BACKOFF_CAP, FAILURE_SUSPECT, FAILURE_DOWN, PeerDiscovery;
 var init_peer_discovery = __esm({
   "src/server/peer-discovery.ts"() {
     "use strict";
     init_config();
     init_tailscale();
+    init_persistence();
+    init_logger();
     UNKNOWN = "UNKNOWN";
     PARTY_SERVER = "PARTY_SERVER";
     DEGRADED = "DEGRADED";
@@ -3496,14 +3838,14 @@ var init_peer_discovery = __esm({
       // ------------------------------------------------------------------
       // Main discovery loop
       // ------------------------------------------------------------------
-      async runLoop() {
-        while (true) {
+      async runLoop(signal) {
+        while (!signal?.aborted) {
           try {
             await this.discoveryCycle();
           } catch (e) {
-            console.error("[Discovery] Cycle failed:", e);
+            logger.error("Discovery", "Cycle failed", e);
           }
-          await sleep2(DISCOVERY_INTERVAL * 1e3);
+          await abortableSleep(DISCOVERY_INTERVAL * 1e3, signal);
         }
       }
       async discoveryCycle() {
@@ -3536,8 +3878,8 @@ var init_peer_discovery = __esm({
         let status;
         try {
           status = readTailscaleStatus();
-        } catch {
-          console.warn("[Discovery] Failed to read Tailscale status");
+        } catch (error) {
+          logger.warn("Discovery", "Failed to read Tailscale status", error);
           return [];
         }
         const peersRaw = status.Peer;
@@ -3562,7 +3904,7 @@ var init_peer_discovery = __esm({
       // Peer probing
       // ------------------------------------------------------------------
       async probePeer(ps) {
-        ps.lastProbeAt = performance.now() / 1e3;
+        ps.lastProbeAt = Date.now() / 1e3;
         const healthy = await this.checkHealth(ps.ip);
         if (healthy === null) {
           this.handleProbeFailure(ps, true);
@@ -3631,7 +3973,7 @@ var init_peer_discovery = __esm({
         const old = ps.status;
         ps.status = newStatus;
         if (old !== newStatus) {
-          console.log(`[Discovery] Peer ${ps.ip}: ${old} -> ${newStatus}`);
+          logger.info("Discovery", `Peer ${ps.ip}: ${old} -> ${newStatus}`);
         }
         if (newStatus === NOT_SERVER) {
           const retries = ps.maybeRetries > 0 ? ps.maybeRetries : 1;
@@ -3674,8 +4016,8 @@ var init_peer_discovery = __esm({
               this._remoteAgents.delete(aid);
             }
           }
-        } catch {
-          console.warn(`[Discovery] Failed to sync agents from ${peerIp}`);
+        } catch (error) {
+          logger.warn("Discovery", `Failed to sync agents from ${peerIp}`, error);
         }
       }
       // ------------------------------------------------------------------
@@ -3731,7 +4073,8 @@ var init_registry = __esm({
         return info;
       }
       remove(agentId) {
-        return this._agents.delete(agentId);
+        const existed = this._agents.delete(agentId);
+        return existed;
       }
       heartbeat(agentId) {
         const info = this._agents.get(agentId);
@@ -3769,9 +4112,14 @@ __export(state_exports, {
   STARTED_AT: () => STARTED_AT,
   discovery: () => discovery,
   getSelfIp: () => getSelfIp,
+  getSnapshotManager: () => getSnapshotManager,
+  initSnapshotManager: () => initSnapshotManager,
+  lifecycleController: () => lifecycleController,
   messageQueue: () => messageQueue,
   refreshSelfIp: () => refreshSelfIp,
-  registry: () => registry
+  registry: () => registry,
+  scheduleSnapshot: () => scheduleSnapshot,
+  snapshotManager: () => snapshotManager
 });
 function resolveSelfIp() {
   try {
@@ -3791,7 +4139,19 @@ function refreshSelfIp() {
   _selfIp = resolveSelfIp();
   return _selfIp;
 }
-var _selfIp, STARTED_AT, registry, messageQueue, discovery;
+function scheduleSnapshot() {
+  snapshotManager?.scheduleSnapshot(
+    () => registry.listAll(),
+    () => messageQueue.getHistorySnapshot()
+  );
+}
+function initSnapshotManager(mgr) {
+  snapshotManager = mgr;
+}
+function getSnapshotManager() {
+  return snapshotManager;
+}
+var _selfIp, STARTED_AT, registry, messageQueue, discovery, snapshotManager, lifecycleController;
 var init_state = __esm({
   "src/server/state.ts"() {
     "use strict";
@@ -3804,6 +4164,8 @@ var init_state = __esm({
     registry = new AgentRegistry(getSelfIp());
     messageQueue = new MessageQueue();
     discovery = new PeerDiscovery(getSelfIp());
+    snapshotManager = null;
+    lifecycleController = new AbortController();
   }
 });
 
@@ -3845,23 +4207,29 @@ var init_agent = __esm({
     init_dist();
     init_models();
     init_config();
+    init_logger();
     agentRoutes = new Hono2();
     agentRoutes.post("/register", async (c) => {
-      const { registry: registry2 } = await Promise.resolve().then(() => (init_state(), state_exports));
+      const { registry: registry2, scheduleSnapshot: scheduleSnapshot3 } = await Promise.resolve().then(() => (init_state(), state_exports));
       const req = await c.req.json();
       const info = registry2.register(req);
+      scheduleSnapshot3();
+      logger.info("Agent", `Registered: ${info.agent_id} (display: "${info.display_name ?? "N/A"}")`);
       return c.json(sanitizeAgentInfo(info));
     });
     agentRoutes.post("/remove", async (c) => {
-      const { registry: registry2 } = await Promise.resolve().then(() => (init_state(), state_exports));
+      const { registry: registry2, scheduleSnapshot: scheduleSnapshot3 } = await Promise.resolve().then(() => (init_state(), state_exports));
       const req = await c.req.json();
       const removed = registry2.remove(req.agent_id);
+      if (removed) scheduleSnapshot3();
+      logger.info("Agent", removed ? `Removed: ${req.agent_id}` : `Remove failed: ${req.agent_id} (not found)`);
       return c.json({ status: removed ? "removed" : "not_found" });
     });
     agentRoutes.post("/heartbeat", async (c) => {
       const { registry: registry2 } = await Promise.resolve().then(() => (init_state(), state_exports));
       const req = await c.req.json();
       const info = registry2.heartbeat(req.agent_id);
+      logger.info("Agent", `Heartbeat from ${req.agent_id}`);
       return c.json({ status: "ok", last_heartbeat: info.last_heartbeat });
     });
     agentRoutes.get("/list", async (c) => {
@@ -3872,7 +4240,7 @@ var init_agent = __esm({
       return c.json({ agents: sanitizeAgentList(allAgents), count: allAgents.length });
     });
     agentRoutes.post("/send", async (c) => {
-      const { registry: registry2, messageQueue: messageQueue2, discovery: discovery2 } = await Promise.resolve().then(() => (init_state(), state_exports));
+      const { registry: registry2, messageQueue: messageQueue2, discovery: discovery2, scheduleSnapshot: scheduleSnapshot3 } = await Promise.resolve().then(() => (init_state(), state_exports));
       const envelope = await c.req.json();
       const recipient = envelope.recipient_id;
       if (!recipient) {
@@ -3883,6 +4251,8 @@ var init_agent = __esm({
         const count = messageQueue2.enqueue(recipient, stamped);
         messageQueue2.logToHistory(envelope.sender_id, "sent", stamped);
         messageQueue2.logToHistory(recipient, "received", stamped);
+        scheduleSnapshot3();
+        logger.info("Agent", `Send ${envelope.sender_id} -> ${recipient}: delivered_locally`);
         return c.json({ status: "delivered_locally", target: recipient });
       }
       const peerIp = discovery2.getPeerForAgent(recipient);
@@ -3891,12 +4261,16 @@ var init_agent = __esm({
           const result = await forwardToPeer(peerIp, envelope);
           if (result.status === "forwarded") {
             messageQueue2.logToHistory(envelope.sender_id, "sent", { ...envelope, timestamp: envelope.timestamp ?? Date.now() / 1e3 });
+            scheduleSnapshot3();
+            logger.info("Agent", `Send ${envelope.sender_id} -> ${recipient}: forwarded (peer ${peerIp})`);
           }
           return c.json(result);
         } else {
+          logger.info("Agent", `Send ${envelope.sender_id} -> ${recipient}: peer_unreachable (peer ${peerIp})`);
           return c.json({ status: "peer_unreachable", target: peerIp });
         }
       }
+      logger.info("Agent", `Send ${envelope.sender_id} -> ${recipient}: agent_not_found`);
       return c.json({ status: "agent_not_found", target: recipient });
     });
     agentRoutes.get("/messages/:agent_id", async (c) => {
@@ -3925,6 +4299,7 @@ var init_proxy = __esm({
     init_config();
     init_tailscale();
     init_state();
+    init_logger();
     proxyRoutes = new Hono2();
     proxyRoutes.get("/health", async (c) => {
       let hostname = "127.0.0.1";
@@ -3949,13 +4324,13 @@ var init_proxy = __esm({
       if (envelope.recipient_id) {
         messageQueue.enqueue(envelope.recipient_id, stamped);
         messageQueue.logToHistory(envelope.recipient_id, "received", stamped);
-        console.log(`[\u6536\u5230\u6D88\u606F] ${envelope.sender_id} -> ${envelope.recipient_id}: ${envelope.content}`);
+        logger.info("Proxy", `Received msg ${envelope.sender_id} -> ${envelope.recipient_id}`);
       } else {
         for (const agent of registry.listAll()) {
           messageQueue.enqueue(agent.agent_id, stamped);
           messageQueue.logToHistory(agent.agent_id, "received", stamped);
         }
-        console.log(`[\u5E7F\u64AD\u6D88\u606F] ${envelope.sender_id} -> all: ${envelope.content}`);
+        logger.info("Proxy", `Broadcast from ${envelope.sender_id} to all agents`);
       }
       return c.json({ status: "received" });
     });
@@ -3973,10 +4348,10 @@ var init_proxy = __esm({
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify(payload)
         });
-        console.log(`[\u53D1\u9001\u6210\u529F] \u76EE\u6807 ${targetIp}`);
+        logger.info("Proxy", `Forwarded to ${targetIp}`);
         return c.json({ status: "forwarded", target: targetIp });
       } catch (e) {
-        console.log(`[\u53D1\u9001\u5931\u8D25] \u76EE\u6807 ${targetIp}, \u9519\u8BEF: ${e.message}`);
+        logger.warn("Proxy", `Forward to ${targetIp} failed: ${e.message}`);
         return c.json({ status: "error", target: targetIp, error: e.message });
       }
     });
@@ -4636,6 +5011,16 @@ body::after{
     }).join('');
   }
 
+  // Build agent_id \u2192 display_name lookup from local + remote agents
+  function buildNameMap(data) {
+    const map = {};
+    const all = [...(data.agents.local_agents || []), ...(data.agents.remote_agents || [])];
+    for (const a of all) { map[a.agent_id] = a.display_name || a.agent_id; }
+    return map;
+  }
+
+  function resolveName(map, id) { return map[id] || id; }
+
   function renderMessages(data) {
     const container = $('#msgFeed');
     const msgs = data.messages.recent || [];
@@ -4645,12 +5030,14 @@ body::after{
       return;
     }
 
+    const names = buildNameMap(data);
+
     container.innerHTML = msgs.map(function(m) {
       const dir = m.direction === 'received' ? 'received' : '';
       const arrow = m.direction === 'received' ? '&#8592;' : '&#8594;';
       const flow = m.direction === 'received'
-        ? m.sender_id + ' <span class="arrow">' + arrow + '</span> ' + (m.agent_id || '?')
-        : (m.agent_id || '?') + ' <span class="arrow">' + arrow + '</span> ' + (m.recipient_id || 'broadcast');
+        ? resolveName(names, m.sender_id) + ' <span class="arrow">' + arrow + '</span> ' + resolveName(names, m.agent_id)
+        : resolveName(names, m.agent_id) + ' <span class="arrow">' + arrow + '</span> ' + resolveName(names, m.recipient_id) || 'broadcast';
       return '<div class="msg-item ' + dir + '">'
         + '<div class="msg-top">'
         + '<div class="msg-flow">' + flow + '</div>'
@@ -5064,6 +5451,7 @@ var init_dashboard = __esm({
     init_dashboard_html();
     init_tailscale();
     init_state();
+    init_logger();
     dashboardRoutes = new Hono2();
     dashboardRoutes.get("/", (c) => {
       return c.html(DASHBOARD_HTML);
@@ -5089,10 +5477,14 @@ var init_dashboard = __esm({
       const localAgents = sanitizeAgentList(registry.listAll());
       const remoteEntries = discovery.getRemoteAgentEntries();
       const peerStates = discovery.getPeerStates();
+      const seen = /* @__PURE__ */ new Set();
       const recentMessages = [];
       for (const agent of localAgents) {
         const history = messageQueue.getHistory(agent.agent_id, 5);
         for (const entry of history) {
+          const key = `${entry.sender_id}:${entry.recipient_id ?? ""}:${Math.floor(entry.timestamp)}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
           recentMessages.push({ agent_id: agent.agent_id, ...entry });
         }
       }
@@ -5156,6 +5548,7 @@ var init_dashboard = __esm({
           return c.json({ success: false, output: "auth_key is required" }, 400);
         }
         const result = joinTailnet(authKey);
+        logger.info("Dashboard", `Join network: ${result.success ? "success" : "failed"}`);
         return c.json(result, result.success ? 200 : 500);
       } catch (e) {
         return c.json({ success: false, output: e.message }, 500);
@@ -5164,6 +5557,7 @@ var init_dashboard = __esm({
     activeLogin = null;
     dashboardRoutes.post("/api/logout", async (c) => {
       const result = logoutTailscale();
+      logger.info("Dashboard", `Logout: ${result.success ? "success" : "failed"}`);
       if (result.success) {
         resetTailscaleBinaryCache();
         refreshSelfIp();
@@ -5176,6 +5570,7 @@ var init_dashboard = __esm({
       }
       const { promise, process: process2 } = startInteractiveLogin();
       activeLogin = { process: process2 };
+      logger.info("Dashboard", "Tailscale login initiated");
       const result = await promise;
       if (result.success && result.url) {
         activeLogin.url = result.url;
@@ -5187,6 +5582,7 @@ var init_dashboard = __esm({
     dashboardRoutes.post("/api/install-tailscale", async (c) => {
       const { installTailscale: installTailscale2 } = await Promise.resolve().then(() => (init_tailscale_installer(), tailscale_installer_exports));
       const result = await installTailscale2(process.platform);
+      logger.info("Dashboard", `Install Tailscale: ${result.success ? "success" : "failed"}`);
       if (result.success) {
         resetTailscaleBinaryCache();
       }
@@ -5197,40 +5593,107 @@ var init_dashboard = __esm({
 
 // src/server/index.ts
 var server_exports = {};
-import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync3, unlinkSync as unlinkSync2 } from "fs";
-import { join as join5, dirname as dirname3 } from "path";
-import { homedir as homedir4 } from "os";
+import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync4, unlinkSync as unlinkSync4 } from "fs";
+import { join as join7, dirname as dirname4 } from "path";
+import { homedir as homedir6 } from "os";
 async function periodicCleanup() {
+  while (!lifecycleController.signal.aborted) {
+    try {
+      const removed = registry.cleanupStale(HEARTBEAT_TIMEOUT);
+      if (removed.length > 0) {
+        logger.info("Cleanup", `Removed ${removed.length} stale agent(s): ${removed.join(", ")}`);
+      }
+    } catch (e) {
+      logger.error("Cleanup", "Error during cleanup", e);
+    }
+    await abortableSleep(CLEANUP_INTERVAL * 1e3, lifecycleController.signal);
+  }
 }
 function pidFilePath2() {
   const pluginData = process.env.CLAUDE_PLUGIN_DATA || "";
-  if (pluginData) return join5(pluginData, "server.pid");
-  return join5(homedir4(), ".open-party", "server.pid");
+  if (pluginData) return join7(pluginData, "server.pid");
+  return join7(homedir6(), ".open-party", "server.pid");
+}
+async function performShutdown(server, pidPath) {
+  if (shutdownInitiated) return;
+  shutdownInitiated = true;
+  logger.info("Shutdown", "Shutting down Party Server...");
+  try {
+    lifecycleController.abort();
+    getSnapshotManager()?.cancelDebounce();
+    try {
+      getSnapshotManager()?.writeSnapshot(registry.listAll(), messageQueue.getHistorySnapshot());
+      logger.info("Shutdown", "Final snapshot written.");
+    } catch (error) {
+      logger.error("Shutdown", "Failed to write final snapshot", error);
+    }
+    if (server.closeAllConnections) {
+      server.closeAllConnections();
+    }
+    if (process.platform === "win32") {
+      await new Promise((r) => setTimeout(r, 500));
+    }
+    await new Promise((resolve4, reject) => {
+      server.close((err) => err ? reject(err) : resolve4());
+    });
+    if (process.platform === "win32") {
+      await new Promise((r) => setTimeout(r, 500));
+    }
+    getSnapshotManager()?.removeShutdownMarker();
+    try {
+      unlinkSync4(pidPath);
+    } catch {
+    }
+    logger.info("Shutdown", "Party Server shut down cleanly.");
+  } catch (error) {
+    logger.error("Shutdown", "Error during shutdown sequence", error);
+  } finally {
+    process.exit(0);
+  }
 }
 async function main() {
   const pidPath = pidFilePath2();
-  mkdirSync3(dirname3(pidPath), { recursive: true });
-  writeFileSync3(pidPath, String(process.pid));
-  console.log(`Starting Party Server on port ${PARTY_PORT} (Tailscale IP: ${getSelfIp()})`);
+  mkdirSync5(dirname4(pidPath), { recursive: true });
+  writeFileSync4(pidPath, String(process.pid));
+  initSnapshotManager(new SnapshotManager());
+  const sm = getSnapshotManager();
+  let recoveredAgents = 0;
+  let recoveredHistoryEntries = 0;
+  if (sm.hasShutdownMarker()) {
+    logger.info("Recovery", "Previous shutdown was interrupted (shutdown marker found).");
+  }
+  const savedSnapshot = sm.loadSnapshot();
+  if (savedSnapshot) {
+    recoveredAgents = sm.hydrateAgents(registry, getSelfIp());
+    recoveredHistoryEntries = sm.hydrateHistory(messageQueue);
+    if (recoveredAgents > 0 || recoveredHistoryEntries > 0) {
+      logger.info(
+        "Recovery",
+        `Recovered ${recoveredAgents} agent(s), ${recoveredHistoryEntries} history entry/entries.`
+      );
+    }
+  }
+  logger.info("Server", `Starting Party Server on port ${PARTY_PORT} (Tailscale IP: ${getSelfIp()})`);
   process.on("SIGHUP", () => {
   });
   const server = serve({ fetch: app.fetch, port: PARTY_PORT });
-  const discoveryPromise = discovery.runLoop();
+  const discoveryPromise = discovery.runLoop(lifecycleController.signal);
   const cleanupPromise = periodicCleanup();
-  const shutdown = () => {
-    console.log("\nShutting down Party Server...");
-    try {
-      unlinkSync2(pidPath);
-    } catch {
-    }
-    server.close();
-    process.exit(0);
-  };
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
-  await Promise.race([discoveryPromise, cleanupPromise]);
+  const snapshotLoopPromise = sm.startSnapshotLoop(
+    lifecycleController.signal,
+    () => registry.listAll(),
+    () => messageQueue.getHistorySnapshot()
+  );
+  const shutdownHandler = () => void performShutdown(server, pidPath);
+  process.on("SIGINT", shutdownHandler);
+  process.on("SIGTERM", shutdownHandler);
+  app.post("/api/shutdown", (c) => {
+    void performShutdown(server, pidPath);
+    return c.json({ status: "shutting_down" });
+  });
+  await Promise.race([discoveryPromise, cleanupPromise, snapshotLoopPromise]);
 }
-var app;
+var app, shutdownInitiated;
 var init_server = __esm({
   "src/server/index.ts"() {
     "use strict";
@@ -5238,24 +5701,46 @@ var init_server = __esm({
     init_cors();
     init_dist2();
     init_config();
+    init_persistence();
+    init_logger();
     init_state();
     init_agent();
     init_proxy();
     init_dashboard();
     app = new Hono2();
     app.use("*", cors());
+    app.use("*", async (c, next) => {
+      const start = Date.now();
+      await next();
+      const ms = Date.now() - start;
+      const ip = c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ?? c.info?.remote?.address ?? "unknown";
+      const path = c.req.path;
+      if (path === "/proxy/health") {
+        logger.debug("HTTP", `${c.req.method} ${path} ${c.res.status} ${ms}ms ${ip}`);
+      } else {
+        logger.info("HTTP", `${c.req.method} ${path} ${c.res.status} ${ms}ms ${ip}`);
+      }
+    });
+    app.onError((err, c) => {
+      logger.error("HTTP", `${c.req.method} ${c.req.path} failed (${err.status ?? 500}): ${err.message}`, err);
+      return c.json({
+        status: "error",
+        error: (err.status ?? 500) >= 500 ? "Internal server error" : err.message
+      }, err.status ?? 500);
+    });
     app.route("/agent", agentRoutes);
     app.route("/proxy", proxyRoutes);
     app.route("/dashboard", dashboardRoutes);
+    shutdownInitiated = false;
     main().catch((e) => {
-      console.error("Fatal error:", e);
+      logger.error("Server", "Fatal error", e);
       process.exit(1);
     });
     process.on("uncaughtException", (e) => {
-      console.error("Uncaught exception:", e);
+      logger.error("Server", "Uncaught exception", e);
     });
     process.on("unhandledRejection", (e) => {
-      console.error("Unhandled rejection:", e);
+      logger.error("Server", "Unhandled rejection", e);
     });
   }
 });
@@ -5288,26 +5773,24 @@ function detectClaudeCode() {
     configPath: settingsPath
   };
 }
-function detectCursor() {
-  const configPath = process.platform === "win32" ? join2(homedir(), "AppData", "Roaming", "Cursor", "User", "globalStorage", "settings.json") : join2(homedir(), ".cursor", "mcp.json");
-  const mcpPath = join2(homedir(), ".cursor", "mcp.json");
-  return {
-    type: "cursor",
-    name: "Cursor",
-    detected: existsSync2(mcpPath) || isExecutableInPath("cursor"),
-    configPath: mcpPath
-  };
-}
-function detectGeminiCli() {
-  return {
-    type: "gemini-cli",
-    name: "Gemini CLI",
-    detected: isExecutableInPath("gemini"),
-    configPath: join2(homedir(), ".gemini", "settings.json")
-  };
+function detectOpenClaw() {
+  const configPath = join2(homedir(), ".openclaw", "openclaw.json");
+  if (isExecutableInPath("openclaw") || isExecutableInPath("openclaw.mjs")) {
+    return { type: "openclaw", name: "OpenClaw", detected: true, configPath };
+  }
+  const candidatePaths = [
+    join2(homedir(), ".openclaw", "openclaw.mjs"),
+    join2(homedir(), ".openclaw", "openclaw")
+  ];
+  for (const p of candidatePaths) {
+    if (existsSync2(p)) {
+      return { type: "openclaw", name: "OpenClaw", detected: true, configPath };
+    }
+  }
+  return { type: "openclaw", name: "OpenClaw", detected: false, configPath };
 }
 function detectAgents() {
-  return [detectClaudeCode(), detectCursor(), detectGeminiCli()];
+  return [detectClaudeCode(), detectOpenClaw()];
 }
 
 // src/cli/agent-installer.ts
@@ -5343,7 +5826,8 @@ function findPluginDistDir() {
     if (existsSync3(join3(pluginDir, ".claude-plugin", "plugin.json"))) {
       return pluginDir;
     }
-  } catch {
+  } catch (error) {
+    console.error("[Agent Installer] Failed to list plugin dist directory:", error instanceof Error ? error.message : String(error));
   }
   return null;
 }
@@ -5362,25 +5846,26 @@ function findDistJsDir() {
 function getPluginVersion() {
   const pluginDir = findPluginDistDir();
   if (pluginDir) {
-    const manifest2 = readJsonFile(
+    const manifest = readJsonFile(
       join3(pluginDir, ".claude-plugin", "plugin.json"),
       {}
     );
-    if (manifest2.version) return manifest2.version;
-  }
-  const sourceManifest = resolve(
-    import.meta.dirname ?? ".",
-    "..",
-    "..",
-    "src",
-    "client",
-    "claude-code",
-    ".claude-plugin",
-    "plugin.json"
-  );
-  const manifest = readJsonFile(sourceManifest, {});
-  if (manifest.version) return manifest.version;
-  return "0.1.0";
+    if (manifest.version) return manifest.version;
+  }
+  const distJsDir = findDistJsDir();
+  if (distJsDir) {
+    const buildInfo = readJsonFile(
+      join3(distJsDir, "..", "BUILD_INFO.json"),
+      {}
+    );
+    if (buildInfo.version) return buildInfo.version;
+  }
+  try {
+    const pkg = JSON.parse(readFileSync(join3(import.meta.dirname ?? ".", "..", "..", "package.json"), "utf-8"));
+    if (pkg.version) return pkg.version;
+  } catch {
+  }
+  return "0.0.0";
 }
 function getMarketplaceDir() {
   return join3(homedir2(), ".claude", "plugins", "marketplaces", "open-party");
@@ -5506,42 +5991,56 @@ function installClaudeCode() {
     configPath: settingsPath
   };
 }
-function installCursor() {
-  const configPath = join3(homedir2(), ".cursor", "mcp.json");
-  const { command: command2, args: args2 } = getPluginCommand();
-  const config = readJsonFile(configPath, {});
-  if (!config.mcpServers) config.mcpServers = {};
-  config.mcpServers["open-party"] = { type: "stdio", command: command2, args: args2 };
-  writeJsonFile(configPath, config);
-  return { success: true, configPath };
+function findOpenclawDistDir() {
+  const distDir = resolve(import.meta.dirname ?? ".", "..", "openclaw");
+  if (!existsSync3(distDir)) return null;
+  try {
+    const entries = readdirSync(distDir);
+    const dirs = entries.filter((e) => e.startsWith("open-party-"));
+    if (dirs.length === 0) return null;
+    return join3(distDir, dirs[dirs.length - 1]);
+  } catch (error) {
+    console.error("[Agent Installer] Failed to list openclaw dist directory:", error instanceof Error ? error.message : String(error));
+  }
+  return null;
 }
-function installGeminiCli() {
-  const configPath = join3(homedir2(), ".gemini", "settings.json");
-  const { command: command2, args: args2 } = getPluginCommand();
+function installOpenClaw() {
+  const pluginDir = findOpenclawDistDir();
+  if (!pluginDir) {
+    return {
+      success: false,
+      error: 'OpenClaw plugin package not found. Run "npm run build:openclaw" first.'
+    };
+  }
+  const configPath = join3(homedir2(), ".openclaw", "openclaw.json");
+  const extensionDir = join3(homedir2(), ".openclaw", "extensions", "open-party");
+  if (existsSync3(extensionDir)) {
+    rmSync(extensionDir, { recursive: true });
+  }
+  mkdirSync(extensionDir, { recursive: true });
+  cpSync(pluginDir, extensionDir, { recursive: true });
   const config = readJsonFile(configPath, {});
-  if (!config.mcpServers) config.mcpServers = {};
-  config.mcpServers["open-party"] = { type: "stdio", command: command2, args: args2 };
+  if (!config.plugins) config.plugins = {};
+  if (!config.plugins.entries) {
+    config.plugins.entries = {};
+  }
+  const entries = config.plugins.entries;
+  entries["open-party"] = {
+    enabled: true,
+    config: {
+      partyServerUrl: "http://127.0.0.1:8000",
+      heartbeatInterval: 3e4
+    }
+  };
   writeJsonFile(configPath, config);
   return { success: true, configPath };
 }
-function getPluginCommand() {
-  const distDir = findDistJsDir();
-  if (distDir) {
-    const serverPath = join3(distDir, "mcp-server.js");
-    if (existsSync3(serverPath)) {
-      return { command: "node", args: [serverPath] };
-    }
-  }
-  return { command: "npx", args: ["@feynmanzhang/open-party", "mcp"] };
-}
 async function installPluginToAgent(agentType) {
   switch (agentType) {
     case "claude-code":
       return installClaudeCode();
-    case "cursor":
-      return installCursor();
-    case "gemini-cli":
-      return installGeminiCli();
+    case "openclaw":
+      return installOpenClaw();
     default:
       return { success: false, error: `Unknown agent type: ${agentType}` };
   }
@@ -5884,7 +6383,7 @@ ${bold(cyan("\u{1F50D} Step 2: Detecting AI agents in your environment..."))}
   const detected = agents.filter((a) => a.detected);
   if (detected.length === 0) {
     console.log(yellow("No supported AI agents detected in this environment."));
-    console.log("  Supported agents: Claude Code, Cursor, Gemini CLI");
+    console.log("  Supported agents: Claude Code, OpenClaw");
     console.log("");
     console.log("  Install one and re-run: open-party setup");
     return;
@@ -5914,6 +6413,9 @@ Installing Open Party plugin for ${agent.name}...`);
       if (agent.type === "claude-code") {
         console.log(`  ${bold("Please restart Claude Code")} for changes to take effect.`);
       }
+      if (agent.type === "openclaw") {
+        console.log(`  ${bold("Please restart OpenClaw gateway")} for changes to take effect.`);
+      }
     } else {
       console.log(`${red("\u274C")} Failed to install for ${agent.name}: ${result.error}`);
     }
@@ -5927,9 +6429,9 @@ async function setupCommand() {
   console.log(`
 ${bold(cyan("\u{1F680} Starting Party Server..."))}`);
   const { spawn: spawn4 } = await import("child_process");
-  const { resolve: resolve4, dirname: dirname5 } = await import("path");
+  const { resolve: resolve4, dirname: dirname6 } = await import("path");
   const { fileURLToPath: fileURLToPath3 } = await import("url");
-  const __dirname2 = dirname5(fileURLToPath3(import.meta.url));
+  const __dirname2 = dirname6(fileURLToPath3(import.meta.url));
   const serverScript = resolve4(__dirname2, "..", "party-server.js");
   const serverProc = spawn4(process.execPath, [serverScript], {
     detached: true,
@@ -6048,12 +6550,12 @@ function removePidFile() {
 function isProcessRunning(pid) {
   if (process.platform === "win32") {
     try {
-      const output = execSync3(`tasklist /FI "PID eq ${pid}" /NH`, {
+      const output2 = execSync3(`tasklist /FI "PID eq ${pid}" /NH`, {
         encoding: "utf-8",
         windowsHide: true,
         stdio: ["pipe", "pipe", "pipe"]
       });
-      return output.includes(String(pid));
+      return output2.includes(String(pid));
     } catch {
       return false;
     }
@@ -6136,7 +6638,28 @@ function killServer(pid) {
     } else {
       process.kill(pid, "SIGTERM");
     }
+  } catch (error) {
+    void error;
+  }
+}
+function findPidByPort(port) {
+  try {
+    if (process.platform === "win32") {
+      const output3 = execSync3(
+        `netstat -ano -p tcp | findstr "LISTENING" | findstr ":${port} "`,
+        { encoding: "utf-8", windowsHide: true, stdio: ["pipe", "pipe", "pipe"] }
+      );
+      const match2 = output3.trim().match(/\s(\d+)\s*$/);
+      return match2 ? parseInt(match2[1], 10) : null;
+    }
+    const output2 = execSync3(`lsof -t -i :${port} -sTCP:LISTEN`, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const pid = parseInt(output2.trim().split("\n")[0], 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
   } catch {
+    return null;
   }
 }
 function parseStartArgs(args2) {
@@ -6204,14 +6727,48 @@ async function startDaemon(port) {
 }
 
 // src/cli/stop-server.ts
+async function stopServerGracefully(pid, port) {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 8e3);
+    const resp = await fetch(`http://127.0.0.1:${port}/api/shutdown`, {
+      method: "POST",
+      signal: controller.signal
+    });
+    clearTimeout(timer);
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+async function waitForProcessExit(pid, timeoutMs = 1e4) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isProcessRunning(pid)) return true;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  return false;
+}
 async function stopServer() {
   const pid = readPid();
+  const port = resolvePort();
   if (pid === null) {
-    const port2 = resolvePort();
-    const healthy = await isServerHealthy(port2);
+    const healthy = await isServerHealthy(port);
     if (healthy) {
-      console.log(`No PID file found, but a server is responding on port ${port2}.`);
-      console.log("It may have been started manually. Kill it by port or process name.");
+      const foundPid = findPidByPort(port);
+      if (foundPid !== null && isProcessRunning(foundPid)) {
+        console.log(`No PID file found, but a server is responding on port ${port} (PID ${foundPid}).`);
+        console.log(`Stopping by port lookup...`);
+        killServer(foundPid);
+        const stillUp2 = await isServerHealthy(port);
+        if (!stillUp2) {
+          console.log("Party Server stopped.");
+          return;
+        }
+        console.warn(`Process ${foundPid} was killed, but port ${port} is still responding.`);
+      } else {
+        console.log(`No PID file found, and no process found on port ${port}.`);
+      }
     } else {
       console.log("Party Server is not running (no PID file found).");
     }
@@ -6223,9 +6780,18 @@ async function stopServer() {
     return;
   }
   console.log(`Stopping Party Server (PID ${pid})...`);
+  const gracefulOk = await stopServerGracefully(pid, port);
+  if (gracefulOk) {
+    const exited = await waitForProcessExit(pid);
+    if (exited) {
+      removePidFile();
+      console.log("Party Server stopped gracefully.");
+      return;
+    }
+    console.warn("Graceful shutdown timed out, falling back to force kill...");
+  }
   killServer(pid);
   removePidFile();
-  const port = resolvePort();
   const stillUp = await isServerHealthy(port);
   if (stillUp) {
     console.warn(`Process ${pid} was killed, but port ${port} is still responding.`);
@@ -6284,12 +6850,12 @@ async function statusCommand() {
 }
 
 // src/cli/version.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { resolve as resolve3, dirname as dirname4 } from "path";
+import { readFileSync as readFileSync4 } from "fs";
+import { resolve as resolve3, dirname as dirname5 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function showVersion() {
-  const pkgPath = resolve3(dirname4(fileURLToPath2(import.meta.url)), "..", "..", "package.json");
-  const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+  const pkgPath = resolve3(dirname5(fileURLToPath2(import.meta.url)), "..", "..", "package.json");
+  const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
   console.log(`open-party v${pkg.version}`);
 }