@decentnetwork/lan 0.1.17 → 0.1.21

package/dist/cli/commands.d.ts

@@ -90,7 +90,7 @@ export declare function cmdFriendRequest(args: {
  * (this takes ~45s), then wait for the request to arrive.
  */
 export declare function cmdFriendAccept(args: {
-    pubkey?: string;
+    userid?: string;
     waitForRequest?: boolean;
     waitMs?: number;
     configDir?: string;

package/dist/cli/commands.js

@@ -460,6 +460,21 @@ export async function cmdFriendRequest(args) {
 export async function cmdFriendAccept(args) {
     const dir = args.configDir || ConfigLoader.defaultConfigDir();
     const config = await ConfigLoader.load(resolve(dir, "config.yaml"));
+    // When the daemon is up, route the accept through IPC — no need
+    // to bring the daemon down. This is what 'friends accept' does
+    // and 'friend-accept' is just an alias for that path now.
+    if (daemonPid(config) !== null) {
+        if (!args.userid) {
+            throw new Error("userid is required when the daemon is up. Use 'agentnet friends pending' to see queued requests, then 'agentnet friend-accept <userid>'.");
+        }
+        await cmdFriendsAccept({ userid: args.userid, configDir: args.configDir });
+        return;
+    }
+    // Daemon-down fallback: open a standalone peer. This path stays
+    // because it's the only way to accept a request when the daemon
+    // can't run (e.g. the operator hasn't set up the helper binary
+    // yet). The --wait interactive mode is also useful for one-shot
+    // bootstrapping.
     assertDaemonNotRunning(config, "friend-accept");
     const { Peer } = await import("@decentnetwork/peer");
     const keyFile = resolve(config.carrier.dataDir, "keypair.json");
@@ -487,7 +502,10 @@ export async function cmdFriendAccept(args) {
     if (stored.length === 0) {
         console.warn(`Self-announce got 0 storage nodes — request may still arrive via express relay`);
     }
-    let pubkey = args.pubkey;
+    // The SDK uses `pubkey` as the local-var name historically; semantically
+    // this is the sender's userid (base58). Keep the variable name to
+    // minimize churn but document the mapping.
+    let pubkey = args.userid;
     const wait = args.waitForRequest;
     if (!pubkey || wait) {
         const waitMs = args.waitMs ?? 120000;
@@ -500,7 +518,7 @@ export async function cmdFriendAccept(args) {
         catch (err) {
             if (!pubkey)
                 throw err;
-            console.warn(`No incoming request — will try acceptance with provided pubkey ${pubkey}`);
+            console.warn(`No incoming request — will try acceptance with provided userid ${pubkey}`);
         }
     }
     console.log(`Accepting friend request from ${pubkey}...`);
@@ -769,7 +787,36 @@ export async function cmdProxyAllowHost(args) {
     config.proxy = { ...proxy, allowHosts: [...allowHosts] };
     await ConfigLoader.save(config, configPath);
     console.log(`Added '${args.host}' to proxy allow-hosts.`);
-    console.log(`Restart the daemon to take effect.`);
+    await applyProxyReloadIfRunning(config);
+}
+/**
+ * If the daemon is up, push the freshly-saved proxy allowlist into the
+ * running proxy over IPC — no restart, no Carrier-session churn. Prints
+ * the outcome. When the daemon is down (or the proxy isn't running yet),
+ * tells the operator a restart is needed.
+ */
+async function applyProxyReloadIfRunning(config) {
+    if (daemonPid(config) === null) {
+        console.log("Daemon is down — change takes effect on next 'agentnet up'.");
+        return;
+    }
+    try {
+        const res = await ipcCall(config, { op: "proxy-reload" });
+        if (!res.ok) {
+            console.log(`(live reload failed: ${res.error}) — restart the daemon to apply.`);
+            return;
+        }
+        const data = res.data;
+        if (data.applied) {
+            console.log(`Applied live to the running proxy — no restart needed.`);
+        }
+        else {
+            console.log(`Not applied live: ${data.reason ?? "proxy not running"}.`);
+        }
+    }
+    catch (err) {
+        console.log(`(live reload error: ${err instanceof Error ? err.message : err}) — restart to apply.`);
+    }
 }
 /**
  * Remove a host glob from the proxy allowlist.
@@ -785,6 +832,7 @@ export async function cmdProxyRevokeHost(args) {
     await ConfigLoader.save(config, configPath);
     if (filtered.length < before) {
         console.log(`Removed '${args.host}' from proxy allow-hosts.`);
+        await applyProxyReloadIfRunning(config);
     }
     else {
         console.log(`No exact match for '${args.host}' in allow-hosts.`);

package/dist/cli/index.js

@@ -112,8 +112,8 @@ async function main() {
             configDir: argv["config-dir"],
         });
     })
-        .command("friend-request", "Send a friend request (run while daemon is down)", (y) => y
-        .option("address", { type: "string", demandOption: true, describe: "Recipient Carrier address" })
+        .command("friend-request <address>", "Send a friend request (routes through the running daemon when up; opens a standalone peer when down)", (y) => y
+        .positional("address", { type: "string", demandOption: true, describe: "Recipient Carrier address" })
         .option("hello", { type: "string", describe: "Greeting message" })
         .option("wait-ms", { type: "number", default: 8000, describe: "Wait time for relay delivery" })
         .option("config-dir", { type: "string" }), async (argv) => {
@@ -124,13 +124,27 @@ async function main() {
             configDir: argv["config-dir"],
         });
     })
-        .command("friend-accept", "Accept a friend request (run while daemon is down)", (y) => y
-        .option("pubkey", { type: "string", describe: "Sender pubkey (omit with --wait to receive interactively)" })
-        .option("wait", { type: "boolean", default: false, describe: "Wait for incoming request" })
+        // `friend-accept` is the legacy daemon-down command. With autoAccept
+        // on by default (the standard config), this is rarely used — but we
+        // keep it as an alias for `friends accept` so an operator running
+        // an old recipe doesn't dead-end.
+        //
+        // Positional userid is supported. The flag is named --userid (NOT
+        // --pubkey) because Carrier's identifier model is address + userid;
+        // "pubkey" only exists as a hex-encoded internal representation
+        // operators never need to touch.
+        .command("friend-accept [userid]", "Accept a queued friend-request by userid (alias of 'friends accept')", (y) => y
+        .positional("userid", { type: "string", describe: "Sender's Carrier userid (base58)" })
+        .option("userid", { type: "string", describe: "Sender's Carrier userid (base58)" })
+        // --wait is kept for the daemon-down interactive path
+        // (rarely used now; only matters when autoAccept is off
+        // AND the operator wants to run a one-shot accept without
+        // bringing the daemon up).
+        .option("wait", { type: "boolean", default: false, describe: "Daemon-down mode: wait for an incoming request" })
         .option("wait-ms", { type: "number", default: 120000, describe: "Time to wait for request (ms)" })
         .option("config-dir", { type: "string" }), async (argv) => {
         await cmdFriendAccept({
-            pubkey: argv.pubkey,
+            userid: argv.userid,
             waitForRequest: argv.wait,
             waitMs: argv["wait-ms"],
             configDir: argv["config-dir"],
@@ -149,14 +163,24 @@ async function main() {
         .command("pending", "List queued friend-requests (over IPC; daemon must be up)", (yy) => yy.option("config-dir", { type: "string" }), async (argv) => {
         await cmdFriendsPending({ configDir: argv["config-dir"] });
     })
-        .command("accept", "Accept a queued friend-request by userid (over IPC; daemon stays up)", (yy) => yy
-        .option("userid", { type: "string", demandOption: true, describe: "Sender's Carrier userid (base58)" })
+        // Accept positional userid OR `--userid X`. Operators expect
+        // `agentnet friends accept <userid>` to just work — without
+        // a positional that fails with "Unknown argument: <userid>"
+        // because yargs treats the unflagged value as junk.
+        .command("accept [userid]", "Accept a queued friend-request by userid (over IPC; daemon stays up)", (yy) => yy
+        .positional("userid", { type: "string", describe: "Sender's Carrier userid (base58)" })
+        .option("userid", { type: "string", describe: "Same as positional; either form works" })
         .option("config-dir", { type: "string" }), async (argv) => {
+        if (!argv.userid)
+            throw new Error("userid is required (positional or --userid)");
         await cmdFriendsAccept({ userid: argv.userid, configDir: argv["config-dir"] });
     })
-        .command("reject", "Drop a queued friend-request by userid (over IPC; daemon stays up)", (yy) => yy
-        .option("userid", { type: "string", demandOption: true })
+        .command("reject [userid]", "Drop a queued friend-request by userid (over IPC; daemon stays up)", (yy) => yy
+        .positional("userid", { type: "string", describe: "Sender's Carrier userid (base58)" })
+        .option("userid", { type: "string", describe: "Same as positional; either form works" })
         .option("config-dir", { type: "string" }), async (argv) => {
+        if (!argv.userid)
+            throw new Error("userid is required (positional or --userid)");
         await cmdFriendsReject({ userid: argv.userid, configDir: argv["config-dir"] });
     })
         .demandCommand(1, "Specify a friends subcommand (run 'agentnet friends --help')"), () => {

package/dist/daemon/ipc.d.ts

@@ -39,9 +39,15 @@ export interface IpcHandlers {
     /** Reject (drop) a queued friend-request by userid. Doesn't
      *  notify the sender — they'll just see no acceptance. */
     friendsReject: (userid: string) => Promise<void>;
+    /** Re-read proxy allowlist from config and apply it to the running
+     *  proxy WITHOUT restarting the daemon. Lets `agentnet proxy
+     *  allow-host` take effect instantly instead of forcing a daemon
+     *  restart (which drops every Carrier session). Returns the applied
+     *  allowlist for the CLI to echo. */
+    proxyReload: () => Promise<Record<string, unknown>>;
 }
 export interface IpcRequest {
-    op: "friend-request" | "ping" | "diag" | "friends-pending" | "friends-accept" | "friends-reject";
+    op: "friend-request" | "ping" | "diag" | "friends-pending" | "friends-accept" | "friends-reject" | "proxy-reload";
     address?: string;
     hello?: string;
     userid?: string;

package/dist/daemon/ipc.js

@@ -144,6 +144,8 @@ export class IpcServer {
                 await this.handlers.friendsReject(req.userid);
                 return;
             }
+            case "proxy-reload":
+                return await this.handlers.proxyReload();
             default:
                 throw new Error(`unknown op: ${req.op}`);
         }

package/dist/daemon/server.d.ts

@@ -36,6 +36,7 @@ export declare class DaemonServer {
     private startedAt;
     private isRunning;
     private pidFile?;
+    private configDir;
     constructor(opts: DaemonOptions);
     start(): Promise<void>;
     stop(): Promise<void>;

package/dist/daemon/server.js

@@ -18,6 +18,7 @@ import { DnsServer } from "../dns/server.js";
 import { IpcServer, ipcSocketPath } from "./ipc.js";
 import { PendingFriendsStore } from "./pending-friends.js";
 import { Logger } from "../utils/logger.js";
+import { ConfigLoader } from "../config/loader.js";
 export class DaemonServer {
     config;
     useMockTun;
@@ -40,9 +41,13 @@ export class DaemonServer {
     startedAt = 0;
     isRunning = false;
     pidFile;
+    configDir;
     constructor(opts) {
         this.config = opts.config;
         this.useMockTun = opts.useMockTun ?? true; // Default to mock; override for production
+        // Remember where config.yaml lives so live-reload ops (e.g.
+        // proxy-reload) can re-read it without a daemon restart.
+        this.configDir = opts.configDir ?? ConfigLoader.defaultConfigDir();
         this.logger = new Logger({ prefix: "Daemon" });
     }
     async start() {
@@ -145,6 +150,31 @@ export class DaemonServer {
                         throw new Error(`No pending friend-request for userid ${userid}`);
                     // No-op at the Carrier level — sender just sees no acceptance.
                 },
+                proxyReload: async () => {
+                    // Re-read the proxy allowlist from disk and push it into the
+                    // running proxy without a daemon restart (which would drop
+                    // every Carrier session). If the proxy isn't running yet,
+                    // tell the caller so it can fall back to "restart needed".
+                    const fresh = await ConfigLoader.load(resolve(this.configDir, "config.yaml"));
+                    const allowHosts = fresh.proxy?.allowHosts ?? [];
+                    const allowConnectPorts = fresh.proxy?.allowConnectPorts;
+                    if (!this.connectProxy) {
+                        return {
+                            applied: false,
+                            reason: fresh.proxy?.enabled
+                                ? "proxy enabled in config but not running — restart the daemon once to start the listener"
+                                : "proxy is disabled — run 'agentnet proxy enable' then restart once",
+                        };
+                    }
+                    this.connectProxy.updateAllowlist(allowHosts, allowConnectPorts);
+                    // Keep the in-memory config in sync so a later diag reflects it.
+                    if (this.config.proxy) {
+                        this.config.proxy.allowHosts = allowHosts;
+                        if (allowConnectPorts)
+                            this.config.proxy.allowConnectPorts = allowConnectPorts;
+                    }
+                    return { applied: true, allowHosts };
+                },
                 diag: async () => {
                     // Snapshot of everything an operator needs to debug why
                     // packets aren't moving: forwarding counters, friend
@@ -413,26 +443,43 @@ export class DaemonServer {
             // explicitly enabled it via `agentnet proxy enable`. Binds to the
             // virtual IP so reach is gated by the existing per-peer ACL — we
             // don't add a second auth layer at the HTTP level.
+            //
+            // Bind to `tunIp` (the dora-ALLOCATED IP), NOT config.network.ip.
+            // They diverge when dora hands out an address different from the
+            // init default: the listener would try to bind config's
+            // 10.86.1.10 while the TUN is actually at 10.86.1.15, and
+            // Node throws EADDRNOTAVAIL because that address isn't local.
+            //
+            // Also: a proxy bind failure must NOT take down the whole daemon.
+            // Packet forwarding, DNS, dora, friends — all work fine without
+            // the proxy. Catch + log so an EADDRNOTAVAIL (or port-in-use)
+            // degrades gracefully to "no proxy" instead of a crash loop.
             if (this.config.proxy?.enabled) {
                 if (this.useMockTun) {
                     this.logger.warn("Proxy enabled but daemon is in mock-TUN mode; skipping proxy listener");
                 }
                 else {
-                    this.connectProxy = new ConnectProxy({
-                        bindIp: this.config.network.ip,
-                        port: this.config.proxy.port,
-                        allowHosts: this.config.proxy.allowHosts ?? [],
-                        allowConnectPorts: this.config.proxy.allowConnectPorts,
-                        resolvePeerName: (srcIp) => this.ipam.resolveIp(srcIp)?.name,
-                        onTunnelOpen: ({ src, srcName, target }) => {
-                            this.auditLog.logProxyOpen({ srcIp: src, srcName, target });
-                        },
-                        onTunnelClose: ({ src, srcName, target, bytesTransferred }) => {
-                            this.auditLog.logProxyClose({ srcIp: src, srcName, target, bytesTransferred });
-                        },
-                    });
-                    await this.connectProxy.start();
-                    this.logger.info(`Proxy listening on ${this.config.network.ip}:${this.config.proxy.port}`);
+                    try {
+                        this.connectProxy = new ConnectProxy({
+                            bindIp: tunIp,
+                            port: this.config.proxy.port,
+                            allowHosts: this.config.proxy.allowHosts ?? [],
+                            allowConnectPorts: this.config.proxy.allowConnectPorts,
+                            resolvePeerName: (srcIp) => this.ipam.resolveIp(srcIp)?.name,
+                            onTunnelOpen: ({ src, srcName, target }) => {
+                                this.auditLog.logProxyOpen({ srcIp: src, srcName, target });
+                            },
+                            onTunnelClose: ({ src, srcName, target, bytesTransferred }) => {
+                                this.auditLog.logProxyClose({ srcIp: src, srcName, target, bytesTransferred });
+                            },
+                        });
+                        await this.connectProxy.start();
+                        this.logger.info(`Proxy listening on ${tunIp}:${this.config.proxy.port}`);
+                    }
+                    catch (err) {
+                        this.connectProxy = undefined;
+                        this.logger.error(`Proxy failed to start on ${tunIp}:${this.config.proxy.port} — continuing without it: ${err instanceof Error ? err.message : err}`);
+                    }
                 }
             }
             this.isRunning = true;

package/dist/proxy/connect-proxy.d.ts

@@ -65,6 +65,17 @@ export declare class ConnectProxy {
     start(): Promise<void>;
     stop(): Promise<void>;
     getStats(): ConnectProxyStats;
+    /**
+     * Update the host allowlist (and optionally the port allowlist) of a
+     * RUNNING proxy without restarting it. handleConnect reads
+     * `this.opts.allowHosts` / `allowConnectPorts` at request time, so a
+     * plain field swap takes effect on the next CONNECT — no need to tear
+     * down the listener or, more importantly, the daemon's Carrier
+     * sessions. Lets `agentnet proxy allow-host` apply instantly instead
+     * of forcing a daemon restart that would drop every peer session and
+     * trigger a slow reconvergence storm.
+     */
+    updateAllowlist(allowHosts: string[], allowConnectPorts?: number[]): void;
     private handleConnect;
     private refuse;
 }

package/dist/proxy/connect-proxy.js

@@ -86,6 +86,23 @@ export class ConnectProxy {
     getStats() {
         return { ...this.stats };
     }
+    /**
+     * Update the host allowlist (and optionally the port allowlist) of a
+     * RUNNING proxy without restarting it. handleConnect reads
+     * `this.opts.allowHosts` / `allowConnectPorts` at request time, so a
+     * plain field swap takes effect on the next CONNECT — no need to tear
+     * down the listener or, more importantly, the daemon's Carrier
+     * sessions. Lets `agentnet proxy allow-host` apply instantly instead
+     * of forcing a daemon restart that would drop every peer session and
+     * trigger a slow reconvergence storm.
+     */
+    updateAllowlist(allowHosts, allowConnectPorts) {
+        this.opts.allowHosts = allowHosts;
+        if (allowConnectPorts)
+            this.opts.allowConnectPorts = allowConnectPorts;
+        this.logger.info(`Allowlist updated live: ${allowHosts.length} host glob(s)` +
+            (allowConnectPorts ? `, ports ${allowConnectPorts.join(",")}` : ""));
+    }
     handleConnect(req, clientSocket, head) {
         const src = clientSocket.remoteAddress ?? "?";
         const srcName = this.opts.resolvePeerName?.(src);

package/docs/INSTALL.md

@@ -102,33 +102,146 @@ ping <peer-name>.decent        # if you ran 'dns install'
 
 ## Running the daemon as a service
 
-There's no built-in init script. Pattern is the same as any
-foreground binary; rough sketches:
+The daemon is a foreground binary. Pick one of:
 
-### systemd (Linux)
+### Option A — `nohup` (fastest; no auto-restart)
 
-```ini
-# /etc/systemd/system/agentnet.service
+```bash
+# pre-create the log so the unprivileged user can tail it
+sudo touch /var/log/agentnet.log
+sudo chmod 666 /var/log/agentnet.log
+
+# IMPORTANT: wrap the whole pipeline in `sudo sh -c '...'`.
+# Otherwise `>>` is interpreted by your unprivileged shell and the
+# redirect fails with "Permission denied" before sudo elevates.
+sudo sh -c 'nohup agentnet up --real-tun --config-dir /home/YOURUSER/.agentnet >> /var/log/agentnet.log 2>&1 &'
+
+# verify
+ps -ef | grep -E 'agentnet up|tun-helper' | grep -v grep
+tail -f /var/log/agentnet.log
+
+# stop
+sudo pkill -f 'agentnet up'; sudo pkill -f tun-helper
+```
+
+Always pass `--config-dir /home/YOURUSER/.agentnet` when launching with
+`sudo` — `sudo` changes `$HOME` to `/root`, so without an explicit
+`--config-dir` the daemon (and any one-off CLI invocations) will look
+at `/root/.agentnet/` and report "Not initialized."
+
+### Option B — systemd (Linux, persistent + auto-restart)
+
+```bash
+sudo tee /etc/systemd/system/agentnet.service <<'EOF'
 [Unit]
 Description=Decent AgentNet daemon
 After=network-online.target
 Wants=network-online.target
 
 [Service]
-ExecStart=/usr/bin/agentnet up --real-tun --config-dir /home/<you>/.agentnet
+Type=simple
 User=root
+ExecStart=/usr/local/bin/agentnet up --real-tun --config-dir /home/YOURUSER/.agentnet
 Restart=on-failure
 RestartSec=5
+StandardOutput=append:/var/log/agentnet.log
+StandardError=append:/var/log/agentnet.log
 
 [Install]
 WantedBy=multi-user.target
+EOF
+
+sudo systemctl daemon-reload
+sudo systemctl enable --now agentnet
+sudo systemctl status agentnet
+journalctl -u agentnet -f      # live logs (alternative to /var/log/agentnet.log)
+```
+
+Persists across reboots. If you ever previously launched via
+`systemd-run --unit=agentnet ...` (transient unit), the unit file
+above replaces it cleanly.
+
+### Option C — launchd (macOS, persistent + auto-restart)
+
+```bash
+sudo tee /Library/LaunchDaemons/com.decentlan.agentnet.plist <<EOF
+<?xml version="1.0"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>com.decentlan.agentnet</string>
+  <key>UserName</key><string>root</string>
+  <key>ProgramArguments</key><array>
+    <string>/usr/local/bin/agentnet</string>
+    <string>up</string>
+    <string>--real-tun</string>
+    <string>--config-dir</string>
+    <string>/Users/YOURUSER/.agentnet</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>/var/log/agentnet.log</string>
+  <key>StandardErrorPath</key><string>/var/log/agentnet.log</string>
+</dict></plist>
+EOF
+sudo launchctl load /Library/LaunchDaemons/com.decentlan.agentnet.plist
+tail -f /var/log/agentnet.log
+```
+
+`sudo launchctl unload /Library/LaunchDaemons/com.decentlan.agentnet.plist`
+to stop. Drop the `.plist` file to disable persistence.
+
+## Running CLI commands once the daemon is up
+
+The CLI talks to the daemon over a Unix socket in the config-dir.
+Most commands (`diag`, `ipam list`, `friends list`, `friends pending`,
+`resolve`, `dora autofriend`) just read or write config files — they
+**don't need sudo**:
+
+```bash
+agentnet diag
+agentnet ipam list
+agentnet friends list
+agentnet dora autofriend all
+```
+
+The few that DO need sudo (writing `/etc/resolver/` on macOS, or
+`/etc/dnsmasq.d/` on Linux) require an explicit `--config-dir`
+because `sudo`'s `$HOME` is `/root`:
+
+```bash
+sudo agentnet dns install --config-dir /home/YOURUSER/.agentnet
+```
+
+## DNS on Linux when dnsPort isn't 53
+
+`agentnet init` defaults to `dnsPort: 5354` (5353 is reserved for
+mDNS / Avahi; we step around it). systemd-resolved only forwards to
+upstreams on port 53, so `agentnet dns install` on Linux will warn
+and refuse rather than write a broken config. Two workarounds:
+
+```bash
+# Workaround 1 — static /etc/hosts (simple; re-run on roster changes)
+agentnet dns hosts | sudo tee -a /etc/hosts > /dev/null
+
+# Workaround 2 — dnsmasq forward
+agentnet dns install     # prints a dnsmasq snippet; paste into
+                         # /etc/dnsmasq.d/decent.conf, restart dnsmasq
 ```
 
-### launchd (macOS)
+macOS has no port-53 restriction — `agentnet dns install` works
+out of the box there.
+
+## Troubleshooting
 
-`/Library/LaunchDaemons/com.decent.agentnet.plist` — see
-`man launchd.plist`. Important: `Sudo` env isn't a thing in
-launchd, so put the daemon under `<key>UserName</key><string>root</string>`.
+| symptom | likely cause | fix |
+|---|---|---|
+| `Not initialized. Run 'agentnet init' first.` after running with sudo | `sudo` set `$HOME=/root`; CLI is looking at `/root/.agentnet/` | add `--config-dir /home/YOURUSER/.agentnet` |
+| `/var/log/agentnet.log: Permission denied` when starting with `sudo nohup ... >> ...` | `>>` runs in your unprivileged shell before sudo elevates | wrap in `sudo sh -c '...'`, OR pre-create the log file with `chmod 666` |
+| `Unit agentnet.service not found.` after a successful `systemctl restart` | previous launch was a transient `systemd-run` unit (auto-removed on stop) | install the persistent unit file (Option B above) |
+| `dora friend is offline` for >60s right after restart | Carrier session re-handshake takes 30–90s; not a real failure | wait, or `agentnet diag` to confirm `friends[].status == "online"` |
+| `ipam list` shows only the self entry | dora roster fetch hasn't merged yet, or dora server is down | wait one refresh interval (60s default), then check the dora server; also confirm `dora.autoFriend` isn't `none` |
+| `ping <peer>.decent` resolves but times out | TUN routing OK but the remote daemon is older without the auto-learn-IPAM fix | upgrade the remote to `@decentnetwork/lan@0.1.13+` |
+| `ping <peer>.decent` fails with `Unknown host` even though `nslookup -port=5354 <peer>.decent 127.0.0.1` works | macOS hasn't reloaded `/etc/resolver/` | `sudo killall -HUP mDNSResponder` |
 
 ## Uninstall
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/lan",
-  "version": "0.1.17",
+  "version": "0.1.21",
   "description": "Private virtual LAN for self-hosted services and AI agents, built on Elastos Carrier. NAT-traversal, name service, ACL, all over a peer-to-peer mesh — no public IP required.",
   "type": "module",
   "main": "./dist/index.js",