@decentnetwork/lan 0.1.279 → 0.1.280

package/dist/cli/commands.js

@@ -2,7 +2,7 @@
  * CLI command handlers
  */
 import { resolve, dirname, join } from "path";
-import { existsSync, mkdirSync, readFileSync, copyFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, copyFileSync, writeSync } from "fs";
 import { createConnection } from "net";
 import { createRequire } from "module";
 import { fileURLToPath } from "url";
@@ -18,6 +18,7 @@ import { startMultiExitRouter } from "../proxy/multi-exit-router.js";
 import { resolveEgressBindIp } from "../proxy/egress.js";
 import { startFriendUi } from "../ui/server.js";
 import { installLogThrottle } from "../utils/log-throttle.js";
+import { installExitLogger, setExitReason } from "../utils/exit-reason.js";
 /**
  * Refuse to open a second Carrier peer with this identity if the
  * daemon is already running with the same keypair. Two peers sharing
@@ -465,14 +466,35 @@ export async function cmdUp(args) {
         configDir: dir,
         useMockTun: !args.realTun,
     });
+    // Stamp a synchronous banner on every exit (code + which path claimed it).
+    // An exit whose banner says UNKNOWN is an unclaimed exit path — the
+    // 2026-08-20 incident on gpu-59 could not be attributed for lack of this.
+    installExitLogger();
     // Graceful shutdown
-    const shutdown = async () => {
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return; // systemd can deliver SIGTERM more than once
+        shuttingDown = true;
+        setExitReason(`signal ${signal}`);
         console.log("\nShutting down...");
+        // Failsafe: if graceful stop wedges past its own internal caps, force the
+        // exit ourselves rather than idling until systemd's TimeoutStopSec
+        // SIGKILL (which used to make every `systemctl restart agentnet` take
+        // 90s). unref'd so the timer never holds an otherwise-finished process.
+        const failsafe = setTimeout(() => {
+            try {
+                writeSync(2, "[agentnet] graceful stop exceeded 20s failsafe — forcing exit\n");
+            }
+            catch { /* stderr gone */ }
+            process.exit(1);
+        }, 20_000);
+        failsafe.unref();
         await daemon.stop();
         process.exit(0);
     };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
     await daemon.start();
     const status = daemon.getStatus();
     console.log(`Daemon started. Identity: ${status.identity?.address}`);

package/dist/daemon/server.d.ts

@@ -102,6 +102,10 @@ export declare class DaemonServer {
     private isFileSenderWhitelisted;
     start(): Promise<void>;
     stop(): Promise<void>;
+    /** Overall stop() ceiling. Per-step budgets in cleanup() sum to ~17.5s;
+     *  this cap and the CLI failsafe sit just above, and all of it stays under
+     *  even an aggressive systemd TimeoutStopSec=20 (default is 90). */
+    static readonly STOP_TOTAL_BUDGET_MS = 18000;
     /**
      * Periodic one-line peer-connection summary at INFO. Between the
      * startup block and the first friend flipping online the log is
@@ -166,5 +170,9 @@ export declare class DaemonServer {
     getPacketRouter(): PacketRouter | undefined;
     getConnectProxy(): ConnectProxy | undefined;
     getDoraIntegration(): DoraIntegration | undefined;
+    /** One teardown step: bounded in time AND caught, so no component can
+     *  hang or break the rest of the teardown (INBOX 2026-08-22 #1). */
+    private stopStep;
+    private removePidFile;
     private cleanup;
 }

package/dist/daemon/server.js

@@ -23,6 +23,8 @@ import { PendingFriendsStore } from "./pending-friends.js";
 import { MessageStore } from "./message-store.js";
 import { FriendMetaStore } from "./friend-meta.js";
 import { Logger } from "../utils/logger.js";
+import { boundedStep } from "../utils/bounded-step.js";
+import { setExitReason } from "../utils/exit-reason.js";
 /**
  * Quote argv safely for `sh -c`. Wraps single-quotes by closing,
  * escaping the quote, and reopening — covers paths with spaces and
@@ -562,22 +564,20 @@ export class DaemonServer {
                         this.logger.info(`Queued file "${name}" (${data.length}B) for offline ${userid.slice(0, 8)} (delivers on reconnect)`);
                         return { queued: true, name: safe, size: data.length };
                     }
-                    // NATIVE friends (iOS/Android/C Carrier) cannot see the toxcore
-                    // file-transfer protocol at all — the only online file path they
-                    // receive is the inline FileModel-JSON-over-bulkmsg envelope the
-                    // Beagle apps themselves use. Detected via the DHT-key signature.
-                    if (this.peerManager?.isNativeFriend(userid)) {
+                    // NATIVE friends (iOS/Android/C Carrier): small files take the inline
+                    // FileModel-JSON-over-bulkmsg envelope (single blob, the Beagle apps'
+                    // own fast path); anything bigger falls through to the streaming
+                    // sendFile below, which peer >= 0.1.141 carries to natives as DNFT1
+                    // frames inside friend messages (offset acks, FEC, resume — verified
+                    // 100MB JS→iPad). This gate used to REJECT >11MB outright, which
+                    // blocked the very path built for large files.
+                    const INLINE_MAX = 11 * 1024 * 1024;
+                    if (this.peerManager?.isNativeFriend(userid) && data.length <= INLINE_MAX) {
                         // The FileModel JSON envelope is base64 (inflates ~1.34x) + a little
                         // JSON overhead, and the whole thing must fit the 16MB bulkmsg cap
                         // (CARRIER_MAX_APP_BULKMSG_LEN, raised from 5MB alongside the receive
                         // reorder buffer in peer >= 0.1.87). 11MB raw → ~14.7MB envelope,
-                        // safely under 16MB. Needs BOTH ends on the raised cap. (Very large /
-                        // streaming transfers should use toxcore file transfer, not inline.)
-                        const INLINE_MAX = 11 * 1024 * 1024;
-                        if (data.length > INLINE_MAX) {
-                            throw new Error(`This friend is a native (iOS/Android) client — files are sent inline and limited to ` +
-                                `${(INLINE_MAX / 1024 / 1024).toFixed(1)} MB (this is ${(data.length / 1024 / 1024).toFixed(1)} MB).`);
-                        }
+                        // safely under 16MB. Needs BOTH ends on the raised cap.
                         // Append the chip as "sending" FIRST, then let the SDK's delivery
                         // verdict decide what it becomes. Marking "sent" the moment
                         // sendInlineFile resolved was a lie — that only meant the bytes
@@ -885,7 +885,19 @@ export class DaemonServer {
                     const { spawn } = await import("child_process");
                     const argv = process.argv.slice();
                     const node = argv.shift();
-                    this.logger.info(`Self-restart requested via IPC — relaunching ${node} ${argv.join(" ")}`);
+                    // Under systemd the spawn-a-replacement dance is self-defeating:
+                    // `detached` does not leave the cgroup, so KillMode=control-group
+                    // takes the replacement down with us, and exit(0) does not trigger
+                    // Restart=on-failure — the service ends up permanently down
+                    // (INBOX 2026-08-22 #2). Detect systemd by the env it stamps on
+                    // every unit (sudo's env_reset strips these, so an interactive
+                    // `sudo agentnet up` still takes the spawn path).
+                    const underSystemd = process.platform === "linux" &&
+                        Boolean(process.env.INVOCATION_ID || process.env.JOURNAL_STREAM);
+                    setExitReason("selfRestart via IPC");
+                    this.logger.info(underSystemd
+                        ? "Self-restart requested via IPC — running under systemd, will exit non-zero for the supervisor to relaunch"
+                        : `Self-restart requested via IPC — relaunching ${node} ${argv.join(" ")}`);
                     // Schedule shutdown for after the IPC response goes out. The
                     // 50ms timeout lets the response leave before cleanup closes IPC.
                     setTimeout(() => {
@@ -915,7 +927,7 @@ export class DaemonServer {
                                         child.unref();
                                     }
                                 }
-                                else {
+                                else if (!underSystemd) {
                                     // sh -c so we can shell-quote argv safely and use sleep.
                                     // Node's detached flag reparents the relauncher to PID 1.
                                     // At this point stop() has released IPC, TUN and the pidfile;
@@ -932,7 +944,10 @@ export class DaemonServer {
                             catch (err) {
                                 this.logger.error(`Self-restart spawn failed: ${err instanceof Error ? err.message : err}`);
                             }
-                            setTimeout(() => process.exit(0), 200);
+                            // Non-zero under systemd so Restart=on-failure (and =always)
+                            // relaunches us; zero elsewhere — the detached child is the
+                            // replacement and a supervisor must not also start one.
+                            setTimeout(() => process.exit(underSystemd ? 70 : 0), 200);
                         })();
                     }, 50);
                     return { scheduledMs: 1500, argv: [node, ...argv] };
@@ -1498,9 +1513,19 @@ export class DaemonServer {
             return;
         this.logger.info("Stopping daemon");
         this.isRunning = false;
-        await this.cleanup();
+        // Overall teardown ceiling on top of the per-step bounds in cleanup():
+        // even if every step runs to its own limit, the process must be gone
+        // well before systemd's default TimeoutStopSec=90 SIGKILL.
+        await boundedStep(() => this.cleanup(), DaemonServer.STOP_TOTAL_BUDGET_MS, () => this.logger.error(`Shutdown exceeded ${DaemonServer.STOP_TOTAL_BUDGET_MS}ms overall cap — exiting with cleanup incomplete`));
+        // The pidfile must go even when the cap cut cleanup() short — a stale
+        // pidfile makes the next start think we are still running.
+        this.removePidFile();
         this.logger.info("Daemon stopped");
     }
+    /** Overall stop() ceiling. Per-step budgets in cleanup() sum to ~17.5s;
+     *  this cap and the CLI failsafe sit just above, and all of it stays under
+     *  even an aggressive systemd TimeoutStopSec=20 (default is 90). */
+    static STOP_TOTAL_BUDGET_MS = 18_000;
     /**
      * Periodic one-line peer-connection summary at INFO. Between the
      * startup block and the first friend flipping online the log is
@@ -1777,71 +1802,48 @@ export class DaemonServer {
     getDoraIntegration() {
         return this.doraIntegration;
     }
-    async cleanup() {
-        if (this.statusTimer) {
-            clearInterval(this.statusTimer);
-            this.statusTimer = undefined;
-        }
-        // Persist any pending chat/meta writes before we exit.
-        this.messageStore?.flush();
-        this.friendMeta?.flush();
-        try {
-            if (this.dnsServer) {
-                await this.dnsServer.stop();
-            }
-        }
-        catch (e) {
-            this.logger.warn("Error stopping DNS server:", e);
-        }
-        try {
-            if (this.ipcServer) {
-                await this.ipcServer.stop();
-            }
-        }
-        catch (e) {
-            this.logger.warn("Error stopping IPC server:", e);
-        }
-        try {
-            if (this.doraIntegration) {
-                this.doraIntegration.stop();
-            }
-        }
-        catch (e) {
-            this.logger.warn("Error stopping dora integration:", e);
-        }
-        try {
-            if (this.connectProxy) {
-                await this.connectProxy.stop();
-            }
-        }
-        catch (e) {
-            this.logger.warn("Error stopping proxy:", e);
-        }
+    /** One teardown step: bounded in time AND caught, so no component can
+     *  hang or break the rest of the teardown (INBOX 2026-08-22 #1). */
+    async stopStep(label, budgetMs, run) {
         try {
-            if (this.packetRouter) {
-                await this.packetRouter.stop();
-            }
+            await boundedStep(run, budgetMs, () => this.logger.warn(`Shutdown step '${label}' exceeded ${budgetMs}ms — continuing without it`));
         }
         catch (e) {
-            this.logger.warn("Error stopping router:", e);
+            this.logger.warn(`Error in shutdown step '${label}':`, e);
         }
+    }
+    removePidFile() {
         try {
-            if (this.peerManager) {
-                await this.peerManager.stop();
+            if (this.pidFile && existsSync(this.pidFile)) {
+                unlinkSync(this.pidFile);
             }
         }
-        catch (e) {
-            this.logger.warn("Error stopping peer:", e);
-        }
-        try {
-            if (this.tunDevice) {
-                await this.tunDevice.close();
-            }
+        catch {
+            // best-effort; a stale pidfile will be detected on next start
         }
-        catch (e) {
-            this.logger.warn("Error closing TUN:", e);
+    }
+    async cleanup() {
+        if (this.statusTimer) {
+            clearInterval(this.statusTimer);
+            this.statusTimer = undefined;
         }
-        try {
+        // Persist any pending chat/meta writes before we exit.
+        this.messageStore?.flush();
+        this.friendMeta?.flush();
+        // Per-step budgets sum to less than stop()'s overall cap so a single
+        // wedged component costs its own budget, not the whole teardown.
+        await this.stopStep("dns", 1_500, () => this.dnsServer?.stop());
+        await this.stopStep("ipc", 1_500, () => this.ipcServer?.stop());
+        await this.stopStep("dora", 1_000, () => this.doraIntegration?.stop());
+        await this.stopStep("proxy", 1_500, () => this.connectProxy?.stop());
+        await this.stopStep("router", 2_500, () => this.packetRouter?.stop());
+        // Peer.stop() notifies every established friend that this net_crypto
+        // session is going away — over dead relays that can stall indefinitely.
+        // It gets the biggest budget (skipping the notifications entirely leaves
+        // remote peers stuck on our stale session key), but never a blank check.
+        await this.stopStep("peer", 5_000, () => this.peerManager?.stop());
+        await this.stopStep("tun", 2_000, () => this.tunDevice?.close());
+        await this.stopStep("routes", 2_500, async () => {
             if (this.routeManager && !this.useMockTun) {
                 // Use the configured name on Linux (where we created the device),
                 // or the actual utun name on macOS (no-op cleanup since helper exit
@@ -1853,18 +1855,8 @@ export class DaemonServer {
                     this.config.network.ip;
                 await this.routeManager.cleanup(ifname, this.config.network.subnet, ip);
             }
-        }
-        catch (e) {
-            this.logger.warn("Error cleaning routes:", e);
-        }
-        try {
-            if (this.pidFile && existsSync(this.pidFile)) {
-                unlinkSync(this.pidFile);
-            }
-        }
-        catch {
-            // best-effort; a stale pidfile will be detected on next start
-        }
+        });
+        this.removePidFile();
     }
 }
 function isProcessAlive(pid) {

package/dist/ui/desktop/app.js

@@ -1,4 +1,4 @@
-window.__DK_UI_VERSION="0.1.279";
+window.__DK_UI_VERSION="0.1.280";
 const ICON_PATHS = {
   // ---- tab bar (the four must feel like one set) ----
   users: '<path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2"/><circle cx="9" cy="7" r="4"/><path d="M22 21v-2a4 4 0 0 0-3-3.87"/><path d="M16 3.13a4 4 0 0 1 0 7.75"/>',

package/dist/utils/bounded-step.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Run one shutdown step with an upper time bound.
+ *
+ * Teardown must never hang: a wedged component (Peer.stop() flushing KILL
+ * notifications to 21 friends over dead relays, `ip tuntap del` returning
+ * EBUSY in a retry loop) would otherwise hold the whole exit hostage until
+ * systemd's TimeoutStopSec SIGKILLs us at 90s (INBOX 2026-08-22 #1).
+ *
+ * On overrun the returned promise resolves and `onOverrun` fires; the step
+ * itself keeps running detached — we are exiting anyway, and cancelling
+ * arbitrary component stops is not safely possible. Errors from the step
+ * reject as usual (callers keep their per-step try/catch).
+ */
+export declare function boundedStep(run: () => void | Promise<void>, ms: number, onOverrun: () => void): Promise<void>;

package/dist/utils/bounded-step.js

@@ -0,0 +1,33 @@
+/**
+ * Run one shutdown step with an upper time bound.
+ *
+ * Teardown must never hang: a wedged component (Peer.stop() flushing KILL
+ * notifications to 21 friends over dead relays, `ip tuntap del` returning
+ * EBUSY in a retry loop) would otherwise hold the whole exit hostage until
+ * systemd's TimeoutStopSec SIGKILLs us at 90s (INBOX 2026-08-22 #1).
+ *
+ * On overrun the returned promise resolves and `onOverrun` fires; the step
+ * itself keeps running detached — we are exiting anyway, and cancelling
+ * arbitrary component stops is not safely possible. Errors from the step
+ * reject as usual (callers keep their per-step try/catch).
+ */
+export async function boundedStep(run, ms, onOverrun) {
+    let timer;
+    try {
+        await Promise.race([
+            Promise.resolve().then(run),
+            new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    onOverrun();
+                    resolve();
+                }, ms);
+                // Must not keep an otherwise-drained event loop alive.
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/utils/exit-reason.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Exit-path forensics for the daemon.
+ *
+ * Every legitimate shutdown path (signal handler, IPC selfRestart, failsafe)
+ * claims the exit by calling setExitReason() first. installExitLogger() then
+ * stamps a one-line banner on EVERY process exit — synchronously, via
+ * writeSync, so it cannot be lost to stream buffering the way async console
+ * writes can. An exit whose banner says "UNKNOWN" is the smoking gun for an
+ * unclaimed exit path (INBOX 2026-08-22 #3: a daemon died with no shutdown
+ * banner and we could not tell which path it took).
+ *
+ * beforeExit is also instrumented: it fires only when the event loop drains
+ * naturally — i.e. every handle (IPC socket, TUN fd, timers) has closed and
+ * Node is about to exit 0 on its own. For a daemon that should run forever,
+ * that is always a bug worth a log line.
+ */
+/** Record why the process is about to exit. First caller wins — a failsafe
+ *  firing after a signal handler must not overwrite the original cause. */
+export declare function setExitReason(r: string): void;
+export declare function getExitReason(): string | null;
+export declare function installExitLogger(): void;

package/dist/utils/exit-reason.js

@@ -0,0 +1,49 @@
+/**
+ * Exit-path forensics for the daemon.
+ *
+ * Every legitimate shutdown path (signal handler, IPC selfRestart, failsafe)
+ * claims the exit by calling setExitReason() first. installExitLogger() then
+ * stamps a one-line banner on EVERY process exit — synchronously, via
+ * writeSync, so it cannot be lost to stream buffering the way async console
+ * writes can. An exit whose banner says "UNKNOWN" is the smoking gun for an
+ * unclaimed exit path (INBOX 2026-08-22 #3: a daemon died with no shutdown
+ * banner and we could not tell which path it took).
+ *
+ * beforeExit is also instrumented: it fires only when the event loop drains
+ * naturally — i.e. every handle (IPC socket, TUN fd, timers) has closed and
+ * Node is about to exit 0 on its own. For a daemon that should run forever,
+ * that is always a bug worth a log line.
+ */
+import { writeSync } from "node:fs";
+let reason = null;
+let installed = false;
+/** Record why the process is about to exit. First caller wins — a failsafe
+ *  firing after a signal handler must not overwrite the original cause. */
+export function setExitReason(r) {
+    if (reason === null)
+        reason = r;
+}
+export function getExitReason() {
+    return reason;
+}
+export function installExitLogger() {
+    if (installed)
+        return;
+    installed = true;
+    process.on("beforeExit", (code) => {
+        try {
+            writeSync(2, `[agentnet] event loop drained (beforeExit, code=${code}) — no handle is keeping the daemon alive\n`);
+        }
+        catch {
+            /* stderr gone; nothing else to do */
+        }
+    });
+    process.on("exit", (code) => {
+        try {
+            writeSync(2, `[agentnet] process exit code=${code} reason=${reason ?? "UNKNOWN (no shutdown path claimed this exit)"}\n`);
+        }
+        catch {
+            /* stderr gone; nothing else to do */
+        }
+    });
+}

package/dist/utils/log-throttle.d.ts

@@ -24,6 +24,12 @@ export interface LogThrottleOptions {
     windowMs?: number;
     /** Distinct shapes tracked at once (guards the map itself from a leak). */
     maxShapes?: number;
+    /** Where the at-exit suppressed-count summary is written (default: a
+     *  synchronous write to stdout, so it survives process.exit). Test seam. */
+    exitFlushSink?: (line: string) => void;
+    /** How the at-exit flush is registered (default: process.on("exit")).
+     *  Test seam — lets tests trigger the hook without emitting real exit. */
+    registerExitHook?: (flush: () => void) => () => void;
 }
 /** Collapse a message to its shape: strip ids, IPs, numbers and durations so
  *  the same event about different peers shares one bucket. */

package/dist/utils/log-throttle.js

@@ -17,6 +17,7 @@
  * go quiet; when the window closes, print a single "(… ×N suppressed)" line so
  * the volume is still visible. Nothing is dropped silently.
  */
+import { writeSync } from "node:fs";
 /** Collapse a message to its shape: strip ids, IPs, numbers and durations so
  *  the same event about different peers shares one bucket. */
 export function logShape(message) {
@@ -38,6 +39,20 @@ export function installLogThrottle(opts = {}) {
     const burst = opts.burst ?? 5;
     const windowMs = opts.windowMs ?? 60_000;
     const maxShapes = opts.maxShapes ?? 500;
+    const exitFlushSink = opts.exitFlushSink ??
+        ((line) => {
+            try {
+                writeSync(1, line);
+            }
+            catch {
+                /* stdout gone; nothing else to do */
+            }
+        });
+    const registerExitHook = opts.registerExitHook ??
+        ((flush) => {
+            process.on("exit", flush);
+            return () => process.removeListener("exit", flush);
+        });
     const shapes = new Map();
     const original = {
         log: console.log.bind(console),
@@ -95,7 +110,21 @@ export function installLogThrottle(opts = {}) {
     console.warn = wrap(original.warn);
     // Errors are rare and each one matters — never suppress them.
     console.error = original.error;
+    // Suppressed counts are normally reported when the shape's window rolls
+    // over — but a shape whose window never closes again (the process exits
+    // first) would vanish silently, breaking the "nothing is dropped silently"
+    // contract exactly when the log matters most (INBOX 2026-08-22 #3).
+    const flushAtExit = () => {
+        for (const st of shapes.values()) {
+            if (st.suppressed > 0) {
+                exitFlushSink(`… ${st.suppressed} more like this suppressed (flushed at exit): ${st.sample.slice(0, 160)}\n`);
+                st.suppressed = 0;
+            }
+        }
+    };
+    const unregisterExitHook = registerExitHook(flushAtExit);
     return () => {
+        unregisterExitHook();
         console.log = original.log;
         console.debug = original.debug;
         console.info = original.info;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/lan",
-  "version": "0.1.279",
+  "version": "0.1.280",
   "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",
@@ -84,7 +84,7 @@
   },
   "dependencies": {
     "@decentnetwork/dora": "^0.1.14",
-    "@decentnetwork/peer": "^0.1.140",
+    "@decentnetwork/peer": "^0.1.141",
     "@decentnetwork/peer-webrtc": "^0.2.10",
     "ink": "^5.2.1",
     "js-yaml": "^4.1.0",