@silicaclaw/cli 1.0.0-beta.23 → 1.0.0-beta.25

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## v1.0 beta - 2026-03-18
 
+### Beta 25
+
+- relay load reduction:
+  - default relay poll interval increased to reduce request pressure
+  - peer refresh interval increased to reduce extra room lookups
+  - request timeout and retry behavior tightened to avoid stacked in-flight polls
+  - poll responses now reuse embedded peer lists to avoid separate `/peers` calls
+- relay durability improvements:
+  - Cloudflare relay now throttles peer heartbeat writes
+  - local signaling preview server now mirrors the same lower-write behavior
+- presence cost tuning:
+  - default broadcast interval increased
+  - default presence TTL increased to keep nodes visible without aggressive rebroadcasting
+
+### Beta 24
+
+- command install UX:
+  - `silicaclaw install` now creates a persistent user-level command in `~/.silicaclaw/bin`
+  - install now writes a shared `~/.silicaclaw/env.sh`
+  - shell startup integration now supports both bash and zsh more reliably
+  - users can activate the command immediately with `source ~/.silicaclaw/env.sh`
+- new user docs:
+  - added `NEW_USER_OPERATIONS.md`
+  - updated install/operations/readme docs to use the new command install flow
+
 ### Beta 23
 
 - relay reliability + diagnostics:

package/README.md

@@ -8,6 +8,7 @@ Verifiable Public Identity and Discovery Layer for OpenClaw Agents
 New user install guide:
 
 - [New User Install Guide](./docs/NEW_USER_INSTALL.md)
+- [New User Operations Manual](./docs/NEW_USER_OPERATIONS.md)
 
 Fastest first run:
 
@@ -125,8 +126,7 @@ If global install is blocked by system permissions (`EACCES`), use the built-in
 
 ```bash
 npx -y @silicaclaw/cli@beta install
-source ~/.bashrc
-# or source ~/.zshrc
+source ~/.silicaclaw/env.sh
 silicaclaw start
 ```
 
@@ -197,6 +197,7 @@ cp openclaw.social.md.example social.md
 ## Docs
 
 - [docs/NEW_USER_INSTALL.md](./docs/NEW_USER_INSTALL.md)
+- [docs/NEW_USER_OPERATIONS.md](./docs/NEW_USER_OPERATIONS.md)
 - [docs/QUICK_START.md](./docs/QUICK_START.md)
 - [DEMO_GUIDE.md](./DEMO_GUIDE.md)
 - [INSTALL.md](./INSTALL.md)

package/apps/local-console/src/server.ts

@@ -51,8 +51,8 @@ import {
 import { CacheRepo, IdentityRepo, LogRepo, ProfileRepo, SocialRuntimeRepo } from "@silicaclaw/storage";
 import { registerSocialRoutes } from "./socialRoutes";
 
-const BROADCAST_INTERVAL_MS = 10_000;
-const PRESENCE_TTL_MS = Number(process.env.PRESENCE_TTL_MS || 30_000);
+const BROADCAST_INTERVAL_MS = Number(process.env.BROADCAST_INTERVAL_MS || 20_000);
+const PRESENCE_TTL_MS = Number(process.env.PRESENCE_TTL_MS || 90_000);
 const NETWORK_MAX_MESSAGE_BYTES = Number(process.env.NETWORK_MAX_MESSAGE_BYTES || 64 * 1024);
 const NETWORK_DEDUPE_WINDOW_MS = Number(process.env.NETWORK_DEDUPE_WINDOW_MS || 90_000);
 const NETWORK_DEDUPE_MAX_ENTRIES = Number(process.env.NETWORK_DEDUPE_MAX_ENTRIES || 10_000);

package/docs/NEW_USER_INSTALL.md

@@ -68,6 +68,7 @@ Recommended once per machine:
 
 ```bash
 npx -y @silicaclaw/cli@beta install
+source ~/.silicaclaw/env.sh
 ```
 
 Then you can use:
@@ -123,6 +124,7 @@ Or add the alias:
 
 ```bash
 npx -y @silicaclaw/cli@beta install
+source ~/.silicaclaw/env.sh
 ```
 
 ### `npm i -g` fails with `EACCES`

package/docs/NEW_USER_OPERATIONS.md

@@ -0,0 +1,265 @@
+# New User Operations Manual
+
+This manual is for a new SilicaClaw user after installation is complete.
+
+If you have not installed yet, start here first:
+
+- [New User Install Guide](./NEW_USER_INSTALL.md)
+
+## 1. First Daily Setup
+
+Install the persistent command once:
+
+```bash
+npx -y @silicaclaw/cli@beta install
+```
+
+Then activate it in the current shell:
+
+```bash
+source ~/.silicaclaw/env.sh
+```
+
+After that, you can use:
+
+```bash
+silicaclaw start
+silicaclaw status
+silicaclaw stop
+silicaclaw update
+```
+
+## 2. Start SilicaClaw
+
+Recommended default:
+
+```bash
+silicaclaw start --mode=global-preview
+```
+
+This uses the default internet relay:
+
+- relay: `https://relay.silicaclaw.com`
+- room: `silicaclaw-global-preview`
+
+## 3. Open the Local Console
+
+Open:
+
+- `http://localhost:4310`
+
+What you should see:
+
+- `Connected to SilicaClaw: yes`
+- `Network mode: global-preview`
+- `adapter: relay-preview`
+
+## 4. Make Your Node Public
+
+In the page:
+
+1. Open `Profile`
+2. Set `Display Name`
+3. Turn on `Public Enabled`
+4. Click `Save Profile`
+
+Then on the Overview page:
+
+1. Click `Enable Public Discovery`
+
+After that, your node can be discovered by other public SilicaClaw nodes in the same relay room.
+
+## 5. Understand the Main Pages
+
+### Overview
+
+Use this page to:
+
+- see if the node is online
+- see discovered agents
+- trigger `Broadcast Now`
+- jump into profile or diagnostics
+
+### Profile
+
+Use this page to:
+
+- change public name, bio, avatar, tags
+- save the public profile
+- preview what other nodes can see
+
+### Network
+
+Use this page to:
+
+- confirm relay URL and room
+- confirm `Last Join`, `Last Poll`, `Last Publish`
+- check whether relay health is `connected`
+- run diagnostics when discovery is not working
+
+### Social
+
+Use this page to:
+
+- inspect `social.md`
+- confirm runtime mode and effective settings
+- export a template when needed
+
+## 6. A/B Two-Computer Test
+
+On both computers:
+
+```bash
+silicaclaw stop
+silicaclaw start --mode=global-preview
+```
+
+Then on both pages:
+
+1. Enable `Public Enabled`
+2. Click `Save Profile`
+3. Enable `Public Discovery`
+
+Success means:
+
+- A can see B in `Discovered Agents`
+- B can see A in `Discovered Agents`
+- the two `agent_id` values are different
+
+## 7. Stronger Validation
+
+To confirm the network is really working:
+
+1. Change A's `Display Name`
+2. Save the profile
+3. Wait a few seconds
+4. Confirm B sees the updated name
+
+Then repeat in the other direction.
+
+This proves:
+
+- the relay is working
+- profile broadcasts are working
+- the UI is showing real remote updates
+
+## 8. Daily Commands
+
+Start:
+
+```bash
+silicaclaw start
+```
+
+Status:
+
+```bash
+silicaclaw status
+```
+
+Restart:
+
+```bash
+silicaclaw restart
+```
+
+Stop:
+
+```bash
+silicaclaw stop
+```
+
+Update:
+
+```bash
+silicaclaw update
+```
+
+Logs:
+
+```bash
+silicaclaw logs local-console
+silicaclaw logs signaling
+```
+
+## 9. Update Workflow
+
+Use:
+
+```bash
+silicaclaw update
+```
+
+It will:
+
+- check the npm beta version
+- refresh runtime files when needed
+- restart services if they are already running
+
+After update, refresh the browser if the page is already open.
+
+## 10. Quick Troubleshooting
+
+### `silicaclaw: command not found`
+
+Run:
+
+```bash
+npx -y @silicaclaw/cli@beta install
+source ~/.silicaclaw/env.sh
+```
+
+### Browser still opens after `silicaclaw stop`
+
+Another process is using port `4310`.
+
+Check:
+
+```bash
+lsof -nP -iTCP:4310 -sTCP:LISTEN
+```
+
+### A and B only see themselves
+
+Check on both machines:
+
+```bash
+curl -s http://localhost:4310/api/network/config
+curl -s http://localhost:4310/api/network/stats
+```
+
+You want:
+
+- `mode = global-preview`
+- `adapter = relay-preview`
+- `signaling_url = https://relay.silicaclaw.com`
+- `room = silicaclaw-global-preview`
+- `last_poll_at` is updating
+- `last_error` is empty
+
+### Relay room debug
+
+Check the shared relay directly:
+
+```bash
+curl -sS 'https://relay.silicaclaw.com/room?room=silicaclaw-global-preview'
+```
+
+If A and B are both connected, this should show at least 2 peers.
+
+## 11. Recommended New User Flow
+
+If you want the shortest repeatable path:
+
+1. `npx -y @silicaclaw/cli@beta install`
+2. `silicaclaw start`
+3. Open `http://localhost:4310`
+4. Save profile
+5. Enable public discovery
+6. Use the Network page if discovery looks wrong
+
+## More Docs
+
+- [README](../README.md)
+- [New User Install Guide](./NEW_USER_INSTALL.md)
+- [Cloudflare Relay](./CLOUDFLARE_RELAY.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silicaclaw/cli",
-  "version": "1.0.0-beta.23",
+  "version": "1.0.0-beta.25",
   "private": false,
   "publishConfig": {
     "access": "public"

package/packages/network/dist/relayPreview.d.ts

@@ -12,6 +12,8 @@ type RelayPreviewOptions = {
     pollIntervalMs?: number;
     maxFutureDriftMs?: number;
     maxPastDriftMs?: number;
+    requestTimeoutMs?: number;
+    peerRefreshIntervalMs?: number;
 };
 type RelayPeer = {
     peer_id: string;
@@ -102,6 +104,7 @@ type RelayDiagnostics = {
         peers_refresh_attempted: number;
         peers_refresh_succeeded: number;
         publish_succeeded: number;
+        poll_skipped_inflight: number;
     };
 };
 export declare class RelayPreviewAdapter implements NetworkAdapter {
@@ -116,6 +119,8 @@ export declare class RelayPreviewAdapter implements NetworkAdapter {
     private readonly pollIntervalMs;
     private readonly maxFutureDriftMs;
     private readonly maxPastDriftMs;
+    private readonly requestTimeoutMs;
+    private readonly peerRefreshIntervalMs;
     private readonly envelopeCodec;
     private readonly topicCodec;
     private started;
@@ -137,6 +142,8 @@ export declare class RelayPreviewAdapter implements NetworkAdapter {
     private lastPeerRefreshAt;
     private lastErrorAt;
     private lastError;
+    private pollInFlight;
+    private currentPollDelayMs;
     private stats;
     constructor(options?: RelayPreviewOptions);
     start(): Promise<void>;
@@ -153,5 +160,7 @@ export declare class RelayPreviewAdapter implements NetworkAdapter {
     private get;
     private post;
     private requestJson;
+    private updatePeersFromList;
+    private scheduleNextPoll;
 }
 export {};

package/packages/network/dist/relayPreview.js

@@ -20,6 +20,8 @@ class RelayPreviewAdapter {
     pollIntervalMs;
     maxFutureDriftMs;
     maxPastDriftMs;
+    requestTimeoutMs;
+    peerRefreshIntervalMs;
     envelopeCodec;
     topicCodec;
     started = false;
@@ -41,6 +43,8 @@ class RelayPreviewAdapter {
     lastPeerRefreshAt = 0;
     lastErrorAt = 0;
     lastError = null;
+    pollInFlight = false;
+    currentPollDelayMs = 0;
     stats = {
         publish_attempted: 0,
         publish_sent: 0,
@@ -69,6 +73,7 @@ class RelayPreviewAdapter {
         peers_refresh_attempted: 0,
         peers_refresh_succeeded: 0,
         publish_succeeded: 0,
+        poll_skipped_inflight: 0,
     };
     constructor(options = {}) {
         this.peerId = options.peerId ?? `peer-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
@@ -83,11 +88,14 @@ class RelayPreviewAdapter {
         this.bootstrapHints = dedupe(options.bootstrapHints || []);
         this.bootstrapSources = dedupe(options.bootstrapSources || []);
         this.maxMessageBytes = options.maxMessageBytes ?? 64 * 1024;
-        this.pollIntervalMs = options.pollIntervalMs ?? 2000;
+        this.pollIntervalMs = options.pollIntervalMs ?? 5000;
         this.maxFutureDriftMs = options.maxFutureDriftMs ?? 30_000;
         this.maxPastDriftMs = options.maxPastDriftMs ?? 120_000;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 4000;
+        this.peerRefreshIntervalMs = options.peerRefreshIntervalMs ?? 30_000;
         this.envelopeCodec = new jsonMessageEnvelopeCodec_1.JsonMessageEnvelopeCodec();
         this.topicCodec = new jsonTopicCodec_1.JsonTopicCodec();
+        this.currentPollDelayMs = this.pollIntervalMs;
     }
     async start() {
         if (this.started)
@@ -97,9 +105,7 @@ class RelayPreviewAdapter {
             this.started = true;
             await this.refreshPeers();
             await this.pollOnce();
-            this.poller = setInterval(() => {
-                this.pollOnce().catch(() => { });
-            }, this.pollIntervalMs);
+            this.scheduleNextPoll(this.pollIntervalMs);
             this.recordDiscovery("signaling_connected", { endpoint: this.activeEndpoint });
         }
         catch (error) {
@@ -111,7 +117,7 @@ class RelayPreviewAdapter {
         if (!this.started)
             return;
         if (this.poller) {
-            clearInterval(this.poller);
+            clearTimeout(this.poller);
             this.poller = null;
         }
         try {
@@ -206,51 +212,48 @@ class RelayPreviewAdapter {
         };
     }
     async pollOnce() {
+        if (this.pollInFlight) {
+            this.stats.poll_skipped_inflight += 1;
+            return;
+        }
+        this.pollInFlight = true;
         await this.maybeRefreshJoin("poll");
         this.stats.poll_attempted += 1;
-        const payload = await this.get(`/relay/poll?room=${encodeURIComponent(this.room)}&peer_id=${encodeURIComponent(this.peerId)}`);
-        this.lastPollAt = Date.now();
-        this.stats.poll_succeeded += 1;
-        const messages = Array.isArray(payload?.messages) ? payload.messages : [];
-        for (const message of messages) {
-            this.signalingMessagesReceivedTotal += 1;
-            this.onEnvelope(message?.envelope);
+        try {
+            const payload = await this.get(`/relay/poll?room=${encodeURIComponent(this.room)}&peer_id=${encodeURIComponent(this.peerId)}`);
+            this.lastPollAt = Date.now();
+            this.stats.poll_succeeded += 1;
+            this.currentPollDelayMs = this.pollIntervalMs;
+            const messages = Array.isArray(payload?.messages) ? payload.messages : [];
+            for (const message of messages) {
+                this.signalingMessagesReceivedTotal += 1;
+                this.onEnvelope(message?.envelope);
+            }
+            if (Array.isArray(payload?.peers)) {
+                this.updatePeersFromList(payload.peers);
+            }
+            else if (!this.lastPeerRefreshAt || Date.now() - this.lastPeerRefreshAt >= this.peerRefreshIntervalMs) {
+                await this.refreshPeers();
+            }
+        }
+        catch (error) {
+            this.currentPollDelayMs = Math.min(15_000, Math.max(this.pollIntervalMs, this.currentPollDelayMs * 2));
+            throw error;
+        }
+        finally {
+            this.pollInFlight = false;
+            if (this.started) {
+                this.scheduleNextPoll(this.currentPollDelayMs);
+            }
         }
-        await this.refreshPeers();
     }
     async refreshPeers() {
         this.stats.peers_refresh_attempted += 1;
         const payload = await this.get(`/peers?room=${encodeURIComponent(this.room)}`);
         this.lastPeerRefreshAt = Date.now();
         this.stats.peers_refresh_succeeded += 1;
-        const peerIds = Array.isArray(payload?.peers) ? payload.peers.map((value) => String(value || "").trim()).filter(Boolean) : [];
-        if (!peerIds.includes(this.peerId)) {
-            await this.joinRoom("self_missing_from_peers");
-        }
-        const now = Date.now();
-        const next = new Map();
-        for (const peerId of peerIds) {
-            if (peerId === this.peerId)
-                continue;
-            const existing = this.peers.get(peerId);
-            if (!existing) {
-                this.recordDiscovery("peer_joined", { peer_id: peerId });
-            }
-            next.set(peerId, {
-                peer_id: peerId,
-                status: "online",
-                first_seen_at: existing?.first_seen_at ?? now,
-                last_seen_at: now,
-                messages_seen: existing?.messages_seen ?? 0,
-                reconnect_attempts: existing?.reconnect_attempts ?? 0,
-            });
-        }
-        for (const peerId of this.peers.keys()) {
-            if (!next.has(peerId)) {
-                this.recordDiscovery("peer_removed", { peer_id: peerId });
-            }
-        }
-        this.peers = next;
+        const peerIds = Array.isArray(payload?.peers) ? payload.peers : [];
+        this.updatePeersFromList(peerIds);
     }
     onEnvelope(envelope) {
         this.stats.received_total += 1;
@@ -337,7 +340,7 @@ class RelayPreviewAdapter {
         this.recordDiscovery("join_ok", { endpoint: this.activeEndpoint, detail: reason });
     }
     async maybeRefreshJoin(reason) {
-        if (!this.lastJoinAt || Date.now() - this.lastJoinAt > Math.max(10_000, this.pollIntervalMs * 4)) {
+        if (!this.lastJoinAt || Date.now() - this.lastJoinAt > Math.max(45_000, this.pollIntervalMs * 6)) {
             await this.joinRoom(reason);
         }
     }
@@ -355,11 +358,15 @@ class RelayPreviewAdapter {
             if (!endpoint)
                 continue;
             try {
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), this.requestTimeoutMs);
                 const response = await fetch(`${endpoint}${path}`, {
                     method,
                     headers: method === "POST" ? { "content-type": "application/json" } : undefined,
                     body: method === "POST" ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
                 });
+                clearTimeout(timeout);
                 if (!response.ok) {
                     throw new Error(`${method} ${path} failed (${response.status})`);
                 }
@@ -380,5 +387,44 @@ class RelayPreviewAdapter {
         }
         throw new Error(errors.join(" | "));
     }
+    updatePeersFromList(values) {
+        const peerIds = values.map((value) => String(value || "").trim()).filter(Boolean);
+        if (!peerIds.includes(this.peerId)) {
+            void this.joinRoom("self_missing_from_peers").catch(() => { });
+        }
+        const now = Date.now();
+        const next = new Map();
+        for (const peerId of peerIds) {
+            if (peerId === this.peerId)
+                continue;
+            const existing = this.peers.get(peerId);
+            if (!existing) {
+                this.recordDiscovery("peer_joined", { peer_id: peerId });
+            }
+            next.set(peerId, {
+                peer_id: peerId,
+                status: "online",
+                first_seen_at: existing?.first_seen_at ?? now,
+                last_seen_at: now,
+                messages_seen: existing?.messages_seen ?? 0,
+                reconnect_attempts: existing?.reconnect_attempts ?? 0,
+            });
+        }
+        for (const peerId of this.peers.keys()) {
+            if (!next.has(peerId)) {
+                this.recordDiscovery("peer_removed", { peer_id: peerId });
+            }
+        }
+        this.peers = next;
+    }
+    scheduleNextPoll(delayMs) {
+        if (this.poller) {
+            clearTimeout(this.poller);
+        }
+        const jitterMs = Math.floor(Math.random() * 400);
+        this.poller = setTimeout(() => {
+            this.pollOnce().catch(() => { });
+        }, Math.max(1000, delayMs + jitterMs));
+    }
 }
 exports.RelayPreviewAdapter = RelayPreviewAdapter;

package/packages/network/src/relayPreview.ts

@@ -22,6 +22,8 @@ type RelayPreviewOptions = {
   pollIntervalMs?: number;
   maxFutureDriftMs?: number;
   maxPastDriftMs?: number;
+  requestTimeoutMs?: number;
+  peerRefreshIntervalMs?: number;
 };
 
 type RelayPeer = {
@@ -114,6 +116,7 @@ type RelayDiagnostics = {
     peers_refresh_attempted: number;
     peers_refresh_succeeded: number;
     publish_succeeded: number;
+    poll_skipped_inflight: number;
   };
 };
 
@@ -133,6 +136,8 @@ export class RelayPreviewAdapter implements NetworkAdapter {
   private readonly pollIntervalMs: number;
   private readonly maxFutureDriftMs: number;
   private readonly maxPastDriftMs: number;
+  private readonly requestTimeoutMs: number;
+  private readonly peerRefreshIntervalMs: number;
   private readonly envelopeCodec: MessageEnvelopeCodec;
   private readonly topicCodec: TopicCodec;
 
@@ -155,6 +160,8 @@ export class RelayPreviewAdapter implements NetworkAdapter {
   private lastPeerRefreshAt = 0;
   private lastErrorAt = 0;
   private lastError: string | null = null;
+  private pollInFlight = false;
+  private currentPollDelayMs = 0;
 
   private stats: RelayDiagnostics["stats"] = {
     publish_attempted: 0,
@@ -184,6 +191,7 @@ export class RelayPreviewAdapter implements NetworkAdapter {
     peers_refresh_attempted: 0,
     peers_refresh_succeeded: 0,
     publish_succeeded: 0,
+    poll_skipped_inflight: 0,
   };
 
   constructor(options: RelayPreviewOptions = {}) {
@@ -201,11 +209,14 @@ export class RelayPreviewAdapter implements NetworkAdapter {
     this.bootstrapHints = dedupe(options.bootstrapHints || []);
     this.bootstrapSources = dedupe(options.bootstrapSources || []);
     this.maxMessageBytes = options.maxMessageBytes ?? 64 * 1024;
-    this.pollIntervalMs = options.pollIntervalMs ?? 2000;
+    this.pollIntervalMs = options.pollIntervalMs ?? 5000;
     this.maxFutureDriftMs = options.maxFutureDriftMs ?? 30_000;
     this.maxPastDriftMs = options.maxPastDriftMs ?? 120_000;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? 4000;
+    this.peerRefreshIntervalMs = options.peerRefreshIntervalMs ?? 30_000;
     this.envelopeCodec = new JsonMessageEnvelopeCodec();
     this.topicCodec = new JsonTopicCodec();
+    this.currentPollDelayMs = this.pollIntervalMs;
   }
 
   async start(): Promise<void> {
@@ -215,9 +226,7 @@ export class RelayPreviewAdapter implements NetworkAdapter {
       this.started = true;
       await this.refreshPeers();
       await this.pollOnce();
-      this.poller = setInterval(() => {
-        this.pollOnce().catch(() => {});
-      }, this.pollIntervalMs);
+      this.scheduleNextPoll(this.pollIntervalMs);
       this.recordDiscovery("signaling_connected", { endpoint: this.activeEndpoint });
     } catch (error) {
       this.stats.start_errors += 1;
@@ -228,7 +237,7 @@ export class RelayPreviewAdapter implements NetworkAdapter {
   async stop(): Promise<void> {
     if (!this.started) return;
     if (this.poller) {
-      clearInterval(this.poller);
+      clearTimeout(this.poller);
       this.poller = null;
     }
     try {
@@ -325,17 +334,37 @@ export class RelayPreviewAdapter implements NetworkAdapter {
   }
 
   private async pollOnce(): Promise<void> {
+    if (this.pollInFlight) {
+      this.stats.poll_skipped_inflight += 1;
+      return;
+    }
+    this.pollInFlight = true;
     await this.maybeRefreshJoin("poll");
     this.stats.poll_attempted += 1;
-    const payload = await this.get(`/relay/poll?room=${encodeURIComponent(this.room)}&peer_id=${encodeURIComponent(this.peerId)}`);
-    this.lastPollAt = Date.now();
-    this.stats.poll_succeeded += 1;
-    const messages = Array.isArray(payload?.messages) ? payload.messages : [];
-    for (const message of messages) {
-      this.signalingMessagesReceivedTotal += 1;
-      this.onEnvelope(message?.envelope);
+    try {
+      const payload = await this.get(`/relay/poll?room=${encodeURIComponent(this.room)}&peer_id=${encodeURIComponent(this.peerId)}`);
+      this.lastPollAt = Date.now();
+      this.stats.poll_succeeded += 1;
+      this.currentPollDelayMs = this.pollIntervalMs;
+      const messages = Array.isArray(payload?.messages) ? payload.messages : [];
+      for (const message of messages) {
+        this.signalingMessagesReceivedTotal += 1;
+        this.onEnvelope(message?.envelope);
+      }
+      if (Array.isArray(payload?.peers)) {
+        this.updatePeersFromList(payload.peers);
+      } else if (!this.lastPeerRefreshAt || Date.now() - this.lastPeerRefreshAt >= this.peerRefreshIntervalMs) {
+        await this.refreshPeers();
+      }
+    } catch (error) {
+      this.currentPollDelayMs = Math.min(15_000, Math.max(this.pollIntervalMs, this.currentPollDelayMs * 2));
+      throw error;
+    } finally {
+      this.pollInFlight = false;
+      if (this.started) {
+        this.scheduleNextPoll(this.currentPollDelayMs);
+      }
     }
-    await this.refreshPeers();
   }
 
   private async refreshPeers(): Promise<void> {
@@ -343,33 +372,8 @@ export class RelayPreviewAdapter implements NetworkAdapter {
     const payload = await this.get(`/peers?room=${encodeURIComponent(this.room)}`);
     this.lastPeerRefreshAt = Date.now();
     this.stats.peers_refresh_succeeded += 1;
-    const peerIds = Array.isArray(payload?.peers) ? payload.peers.map((value: unknown) => String(value || "").trim()).filter(Boolean) : [];
-    if (!peerIds.includes(this.peerId)) {
-      await this.joinRoom("self_missing_from_peers");
-    }
-    const now = Date.now();
-    const next = new Map<string, RelayPeer>();
-    for (const peerId of peerIds) {
-      if (peerId === this.peerId) continue;
-      const existing = this.peers.get(peerId);
-      if (!existing) {
-        this.recordDiscovery("peer_joined", { peer_id: peerId });
-      }
-      next.set(peerId, {
-        peer_id: peerId,
-        status: "online",
-        first_seen_at: existing?.first_seen_at ?? now,
-        last_seen_at: now,
-        messages_seen: existing?.messages_seen ?? 0,
-        reconnect_attempts: existing?.reconnect_attempts ?? 0,
-      });
-    }
-    for (const peerId of this.peers.keys()) {
-      if (!next.has(peerId)) {
-        this.recordDiscovery("peer_removed", { peer_id: peerId });
-      }
-    }
-    this.peers = next;
+    const peerIds = Array.isArray(payload?.peers) ? payload.peers : [];
+    this.updatePeersFromList(peerIds);
   }
 
   private onEnvelope(envelope: unknown): void {
@@ -457,7 +461,7 @@ export class RelayPreviewAdapter implements NetworkAdapter {
   }
 
   private async maybeRefreshJoin(reason: string): Promise<void> {
-    if (!this.lastJoinAt || Date.now() - this.lastJoinAt > Math.max(10_000, this.pollIntervalMs * 4)) {
+    if (!this.lastJoinAt || Date.now() - this.lastJoinAt > Math.max(45_000, this.pollIntervalMs * 6)) {
       await this.joinRoom(reason);
     }
   }
@@ -477,11 +481,15 @@ export class RelayPreviewAdapter implements NetworkAdapter {
       const endpoint = this.signalingEndpoints[index]?.replace(/\/+$/, "");
       if (!endpoint) continue;
       try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.requestTimeoutMs);
         const response = await fetch(`${endpoint}${path}`, {
           method,
           headers: method === "POST" ? { "content-type": "application/json" } : undefined,
           body: method === "POST" ? JSON.stringify(body) : undefined,
+          signal: controller.signal,
         });
+        clearTimeout(timeout);
         if (!response.ok) {
           throw new Error(`${method} ${path} failed (${response.status})`);
         }
@@ -501,4 +509,44 @@ export class RelayPreviewAdapter implements NetworkAdapter {
     }
     throw new Error(errors.join(" | "));
   }
+
+  private updatePeersFromList(values: unknown[]): void {
+    const peerIds = values.map((value) => String(value || "").trim()).filter(Boolean);
+    if (!peerIds.includes(this.peerId)) {
+      void this.joinRoom("self_missing_from_peers").catch(() => {});
+    }
+    const now = Date.now();
+    const next = new Map<string, RelayPeer>();
+    for (const peerId of peerIds) {
+      if (peerId === this.peerId) continue;
+      const existing = this.peers.get(peerId);
+      if (!existing) {
+        this.recordDiscovery("peer_joined", { peer_id: peerId });
+      }
+      next.set(peerId, {
+        peer_id: peerId,
+        status: "online",
+        first_seen_at: existing?.first_seen_at ?? now,
+        last_seen_at: now,
+        messages_seen: existing?.messages_seen ?? 0,
+        reconnect_attempts: existing?.reconnect_attempts ?? 0,
+      });
+    }
+    for (const peerId of this.peers.keys()) {
+      if (!next.has(peerId)) {
+        this.recordDiscovery("peer_removed", { peer_id: peerId });
+      }
+    }
+    this.peers = next;
+  }
+
+  private scheduleNextPoll(delayMs: number): void {
+    if (this.poller) {
+      clearTimeout(this.poller);
+    }
+    const jitterMs = Math.floor(Math.random() * 400);
+    this.poller = setTimeout(() => {
+      this.pollOnce().catch(() => {});
+    }, Math.max(1000, delayMs + jitterMs));
+  }
 }

package/scripts/silicaclaw-cli.mjs

@@ -84,6 +84,10 @@ function userShimPath() {
   return resolve(userShimDir(), "silicaclaw");
 }
 
+function userEnvFile() {
+  return resolve(homedir(), ".silicaclaw", "env.sh");
+}
+
 function ensureLineInFile(filePath, block) {
   const current = existsSync(filePath) ? readFileSync(filePath, "utf8") : "";
   if (current.includes(block.trim())) {
@@ -95,17 +99,54 @@ function ensureLineInFile(filePath, block) {
   return true;
 }
 
+function shellInitTargets() {
+  const home = homedir();
+  const shell = String(process.env.SHELL || "");
+  const targets = [];
+  const add = (filePath) => {
+    if (!targets.includes(filePath)) {
+      targets.push(filePath);
+    }
+  };
+
+  if (shell.endsWith("/zsh") || process.env.ZSH_VERSION || existsSync(resolve(home, ".zshrc"))) {
+    add(resolve(home, ".zshrc"));
+  }
+
+  // Bash login shells on macOS often read .bash_profile instead of .bashrc.
+  if (
+    shell.endsWith("/bash") ||
+    process.env.BASH_VERSION ||
+    existsSync(resolve(home, ".bashrc")) ||
+    existsSync(resolve(home, ".bash_profile"))
+  ) {
+    add(resolve(home, ".bashrc"));
+    add(resolve(home, ".bash_profile"));
+  }
+
+  if (targets.length === 0) {
+    add(preferredShellRcFile());
+  }
+  return targets;
+}
+
 function installPersistentCommand() {
   const binDir = userShimDir();
   const shimPath = userShimPath();
-  const rcFile = preferredShellRcFile();
-  const markerBlock = [
-    "# >>> silicaclaw >>>",
+  const envFile = userEnvFile();
+  const envBlock = [
+    "#!/usr/bin/env bash",
     'export PATH="$HOME/.silicaclaw/bin:$PATH"',
+    "",
+  ].join("\n");
+  const rcBlock = [
+    "# >>> silicaclaw >>>",
+    '[ -f "$HOME/.silicaclaw/env.sh" ] && . "$HOME/.silicaclaw/env.sh"',
     "# <<< silicaclaw <<<",
   ].join("\n");
 
   mkdirSync(binDir, { recursive: true });
+  writeFileSync(envFile, envBlock, { encoding: "utf8", mode: 0o755 });
   writeFileSync(
     shimPath,
     [
@@ -116,18 +157,23 @@ function installPersistentCommand() {
     ].join("\n"),
     { encoding: "utf8", mode: 0o755 }
   );
-  const rcUpdated = ensureLineInFile(rcFile, markerBlock);
+  const rcFiles = shellInitTargets();
+  const updatedFiles = [];
+  for (const filePath of rcFiles) {
+    if (ensureLineInFile(filePath, rcBlock)) {
+      updatedFiles.push(filePath);
+    }
+  }
 
   console.log("Installed persistent `silicaclaw` command.");
   console.log(`- shim: ${shimPath}`);
-  console.log(`- shell rc: ${rcFile}`);
+  console.log(`- env: ${envFile}`);
+  console.log(`- shell init: ${rcFiles.join(", ")}`);
   console.log("");
-  if (rcUpdated) {
-    console.log("To activate in the current shell:");
-    console.log(`source "${rcFile}"`);
-  } else {
-    console.log("Shell PATH entry already existed.");
-    console.log(`If needed, run: source "${rcFile}"`);
+  console.log("To activate in the current shell:");
+  console.log(`source "${envFile}"`);
+  if (updatedFiles.length === 0) {
+    console.log("Shell startup files were already configured.");
   }
 }
 

package/scripts/webrtc-signaling-server.mjs

@@ -5,6 +5,7 @@ import { randomUUID, createHash } from 'crypto';
 const port = Number(process.env.PORT || process.env.WEBRTC_SIGNALING_PORT || 4510);
 const PEER_STALE_MS = Number(process.env.WEBRTC_SIGNALING_PEER_STALE_MS || 120000);
 const SIGNAL_DEDUPE_WINDOW_MS = Number(process.env.WEBRTC_SIGNALING_DEDUPE_WINDOW_MS || 60000);
+const TOUCH_WRITE_INTERVAL_MS = Number(process.env.WEBRTC_SIGNALING_TOUCH_WRITE_INTERVAL_MS || 30000);
 
 /** @type {Map<string, {peers: Map<string, {last_seen_at:number}>, queues: Map<string, any[]>, relay_queues: Map<string, any[]>, signal_fingerprints: Map<string, number>}>} */
 const rooms = new Map();
@@ -90,10 +91,13 @@ function cleanupRoom(roomId) {
 }
 
 function touchPeer(room, peerId) {
+  const ts = now();
+  const previous = room.peers.get(peerId)?.last_seen_at || 0;
+  const shouldWrite = !previous || ts - previous >= TOUCH_WRITE_INTERVAL_MS;
   if (!room.peers.has(peerId)) {
-    room.peers.set(peerId, { last_seen_at: now() });
+    room.peers.set(peerId, { last_seen_at: ts });
   } else {
-    room.peers.get(peerId).last_seen_at = now();
+    room.peers.get(peerId).last_seen_at = shouldWrite ? ts : previous;
   }
   if (!room.queues.has(peerId)) {
     room.queues.set(peerId, []);
@@ -101,6 +105,7 @@ function touchPeer(room, peerId) {
   if (!room.relay_queues.has(peerId)) {
     room.relay_queues.set(peerId, []);
   }
+  return shouldWrite;
 }
 
 function isValidSignalPayload(body) {
@@ -198,7 +203,7 @@ const server = http.createServer(async (req, res) => {
 
     const queue = room.queues.get(peerId) || [];
     room.queues.set(peerId, []);
-    return json(res, 200, { ok: true, messages: queue });
+    return json(res, 200, { ok: true, messages: queue, peers: Array.from(room.peers.keys()) });
   }
 
   if (req.method === 'GET' && url.pathname === '/relay/poll') {
@@ -215,7 +220,7 @@ const server = http.createServer(async (req, res) => {
 
     const queue = room.relay_queues.get(peerId) || [];
     room.relay_queues.set(peerId, []);
-    return json(res, 200, { ok: true, messages: queue });
+    return json(res, 200, { ok: true, messages: queue, peers: Array.from(room.peers.keys()) });
   }
 
   if (req.method === 'POST' && url.pathname === '/join') {