dsh-mizar 0.8.5 → 0.8.7

package/README.md

@@ -121,6 +121,28 @@ DSH 自己的 Web 接口暴露出去（那是 DSH 的安全边界，插件不碰
 通信**：手机即使和电脑在同一个 Wi-Fi 也走中继，局域网解锁（附件、全量细节）不生效，其余
 功能不变。
 
+### 中继隧道自愈：断线会自己重连
+
+中继方向有两个只有长期运行才会暴露的故障，0.8.6 起都做了兜底：
+
+- **半开隧道。** 电脑换网络（Wi-Fi 切换、VPN 断掉、休眠唤醒）时，本地 socket 可能既收不到
+  中继的 close、也不再有任何流量，而系统仍报 `ESTABLISHED`。中继那边过了 90 秒没收到
+  pong 就把房间摘掉；插件这边却一直显示「已连接」，于是再也不重拨 —— 手机无论直连还是中继
+  都连不上，只能重启 DSH。现在插件自己有**静默看门狗**：超过 `relay.watchdogMs`（默认
+  120 秒，即中继 30 秒一次 ping 的四个周期）没收到中继任何一帧，就强制丢弃这条 socket 并
+  重拨。可用 `relay.watchdogMs: 0` 关掉。
+- **端口漂移。** DSH 可能重复挂载/重载插件；以前每次挂载都绑一个新监听，端口从 19390 一路
+  漂到 19391、19392，手机配对里保存的直连地址就永远失效了。现在一个进程只保留**一个**挂载：
+  新挂载要等旧挂载完全释放监听之后才绑端口；网络变化导致监听地址改变时，隧道也会立刻用新
+  地址重拨，并把监听端口的变化同步给隧道（否则隧道健康、手机请求却全部 502）。
+- **0.8.7 修了 0.8.6 单实例的漏洞。** 0.8.6 的注册表是模块级的，而 DSH 会在同一进程里多次
+  加载插件模块，每份副本各有一张空注册表——实测一个进程因此挂了 8 个监听（19390–19397）。
+  0.8.7 把注册表放到 `globalThis`（`Symbol.for('dsh-mizar.mount-registry')`），所有模块副本
+  共用同一个槽位，一个进程只剩一个监听。
+
+日志里对应 `relay: the tunnel has been silent for …s — redialling it`、
+`relay: the network changed — redialling the tunnel` 和 `relay: the listener moved to port …`。
+
 ### 对话只传总结
 
 一页历史里只保留这些：你的提问、每一轮的 `turn/start` 和 `turn/end`、每个 `step/start`

package/lib/config.d.ts

@@ -97,6 +97,8 @@ export interface Config {
         preferLoopback: boolean;
         reconnectBaseMs: number;
         reconnectMaxMs: number;
+        /** How long the relay may stay silent before the tunnel is redialled. */
+        watchdogMs: number;
     };
     pairing: {
         codeTtlSeconds: number;

package/lib/config.js

@@ -38,6 +38,15 @@ export const Config = z.object({
         preferLoopback: z.boolean().default(false),
         reconnectBaseMs: z.natural().default(1_000),
         reconnectMaxMs: z.natural().default(60_000),
+        /**
+         * How long the relay may stay silent before the tunnel is redialled, in ms.
+         *
+         * The relay pings every tunnel every `tunnelIdleMs / 3` (30 s with the
+         * relay's default 90 s idle window). Four missed pings is longer than any
+         * healthy relay's silence and short enough that a blackholed network cannot
+         * leave a dead room behind for hours. `0` disables the watchdog.
+         */
+        watchdogMs: z.natural().default(120_000),
     }),
     pairing: z.object({
         codeTtlSeconds: z.natural().default(300),

package/lib/index.js

@@ -27,6 +27,7 @@ import { awaitRequestedPlan, bindKey, isRequested, needsRebind } from './net/wat
 import { PROTOCOL_VERSION } from './protocol/frames.js';
 import { MizarListener } from './server/listener.js';
 import { RelayClient, phoneBaseURL } from './relay/client.js';
+import { sharedMountRegistry } from './mount.js';
 import { loadOrCreateTunnelSecret } from './relay/identity.js';
 import { runSpike } from './spike.js';
 /** Cordis plugin name. */
@@ -54,7 +55,7 @@ const systemLocale = (() => {
  * code in place and every symptom unchanged. One line at boot turns that from a
  * guess into a fact.
  */
-const MIZAR_VERSION = '0.8.5';
+const MIZAR_VERSION = '0.8.7';
 /**
  * Services this plugin must observe before it activates.
  *
@@ -78,7 +79,7 @@ export const inject = ['typert', 'typertGateway', 'sessionProjections', 'session
  * @param initial - the plan the listener is bound to now.
  * @param signal - aborted when the plugin unloads.
  */
-function startBindWatcher(config, readPlan, holder, initial, signal) {
+function startBindWatcher(config, readPlan, holder, initial, signal, onRebound) {
     let current = bindKey(initial);
     const timer = setInterval(() => {
         void (async () => {
@@ -92,6 +93,11 @@ function startBindWatcher(config, readPlan, holder, initial, signal) {
             try {
                 await listener.rebind(next);
                 current = bindKey(next);
+                // A rebind that lands on a different port has just moved the tunnel's
+                // replay target, and a network change is exactly when the outbound
+                // tunnel should be redialled from the new address rather than left on a
+                // path the operating system no longer has.
+                onRebound?.(listener);
             }
             catch (error) {
                 report(`rebind failed, staying on [${current}] — ${describe(error)}`);
@@ -112,7 +118,7 @@ function describe(error) {
     return String(error);
 }
 /**
- * Start the listener for one plugin mount and return its disposer.
+ * Start the listener for one plugin mount and return it with its disposer.
  *
  * @param ctx - the plugin context, used for the lifecycle effect.
  * @param config - validated plugin configuration.
@@ -298,6 +304,7 @@ async function startListener(ctx, config, signal) {
             log: report,
             reconnectBaseMs: config.relay.reconnectBaseMs,
             reconnectMaxMs: config.relay.reconnectMaxMs,
+            watchdogMs: config.relay.watchdogMs,
             onState: (state) => {
                 const wasConnected = relayState.connected;
                 relayState = state;
@@ -435,28 +442,56 @@ async function startListener(ctx, config, signal) {
         // entirely.
         notifier.noteActivity(session.id, event.type);
     });
-    startBindWatcher(config, readPlan, holder, plan, signal);
+    startBindWatcher(config, readPlan, holder, plan, signal, (rebound) => {
+        relay?.setLocalPort(rebound.port);
+        relay?.reconnectNow('the network changed');
+    });
+    // One shutdown path, idempotent and awaitable. The tunnel goes first: it
+    // exists to carry traffic to the listener, so leaving it up while the listener
+    // closes would produce 502s instead of clean disconnects for whatever is
+    // still connected.
+    let shutdown = null;
+    const dispose = () => {
+        shutdown ??= (async () => {
+            relay?.stop();
+            // A pending notification is about a session that has stopped; on unload
+            // there is nothing left to announce it with.
+            notifier.dispose();
+            // Release anything still waiting before the transport disappears, so no
+            // agent is left holding a turn open for a question nobody can answer.
+            broker.dispose();
+            try {
+                await listener.stop();
+            }
+            catch (error) {
+                report(`listener shutdown failed — ${describe(error)}`);
+            }
+        })();
+        return shutdown;
+    };
+    // An unload must not wait for the mount registry's queue to notice: DSH
+    // expects an effect's cleanup to stop the work it started.
     signal.addEventListener('abort', () => {
-        // The tunnel goes first: it exists to carry traffic to the listener, so
-        // leaving it up while the listener closes would produce 502s instead of
-        // clean disconnects for whatever is still connected.
-        relay?.stop();
-        // A pending notification is about a session that has stopped; on unload
-        // there is nothing left to announce it with.
-        notifier.dispose();
-        // Release anything still waiting before the transport disappears, so no
-        // agent is left holding a turn open for a question nobody can answer.
-        broker.dispose();
-        void listener.stop().catch((error) => {
-            report(`listener shutdown failed — ${describe(error)}`);
-        });
+        void dispose();
     });
     if (config.pairing.issueOnStart) {
         const issued = await listener.issuePairingCode();
         report(`pairing code: ${issued.display} (valid for ${config.pairing.codeTtlSeconds}s)`);
     }
-    return listener;
+    return { listener, dispose };
 }
+/**
+ * The one mount this process runs at a time.
+ *
+ * DSH may compose or re-apply a bundle more than once, and each apply used to
+ * bind its own listener: three mounts in one process left three ports listening
+ * (19390/19391/19392) and the port in a phone's pairing was from the wrong
+ * generation of them. The plugin cannot order DSH's lifecycle, so it keeps the
+ * invariant it owns: a new mount starts only after the previous one has
+ * finished shutting down, so the port is free and the address a phone saved is
+ * still the address the computer listens on.
+ */
+const mounts = sharedMountRegistry();
 /**
  * Mount the Mizar host half.
  * @param ctx - the plugin context.
@@ -481,20 +516,35 @@ export function apply(ctx, config) {
     }
     ctx.effect(() => {
         const controller = new AbortController();
-        void (async () => {
+        let mounted = null;
+        void mounts.start(async () => {
+            if (controller.signal.aborted)
+                return null;
+            let next;
             try {
-                const listener = await startListener(ctx, config, controller.signal);
-                if (controller.signal.aborted) {
-                    await listener.stop();
-                    return;
-                }
-                report(`ready — pair with the code shown in the DSH Web panel, or reach ${listener.authorities.join(' / ')}`);
+                next = await startListener(ctx, config, controller.signal);
             }
             catch (error) {
                 report(`listener failed to start — ${describe(error)}`);
+                return null;
             }
-        })();
-        return () => controller.abort();
+            if (controller.signal.aborted) {
+                // Stopped while starting: do not leave a listener behind for the next
+                // mount to find, and do not publish it as the active one.
+                await next.dispose();
+                return null;
+            }
+            mounted = next;
+            report(`ready — pair with the code shown in the DSH Web panel, or reach ${next.listener.authorities.join(' / ')}`);
+            return next;
+        });
+        return () => {
+            // Abort for a fast stop, then queue the awaited disposal: the mount that
+            // replaces this one must bind only after the port is really free.
+            controller.abort();
+            void mounts.stop(mounted);
+            mounted = null;
+        };
     }, 'mizar:listener');
     if (!config.spike)
         return;

package/lib/mount.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The one registry every copy of this plugin in a process shares.
+ *
+ * Module-level state is not enough: the plugin can be loaded more than once in
+ * one process, and each load gets its own copy of this module -- which is how a
+ * single DSH process ended up with eight Mizar listeners (19390 through 19397)
+ * after 0.8.6 shipped a module-level registry. Each copy saw an empty slot and
+ * bound its own port, so the port a phone had saved was always one generation
+ * behind.
+ *
+ * `globalThis` is shared by every copy in the process, and `Symbol.for` gives
+ * the key a stable identity across them. The registry therefore outlives a
+ * module copy exactly as long as the process does, which is the lifetime that
+ * matters for a listening port.
+ *
+ * @returns the process-wide registry.
+ */
+export declare function sharedMountRegistry(): MountRegistry;
+/** Something that can be shut down once, asynchronously. */
+export interface Mounted {
+    /** Release the listener, the tunnel and anything else this mount owns. */
+    dispose(): Promise<void>;
+}
+/**
+ * The serialized, single-instance mount slot.
+ *
+ * `start` disposes the running mount before creating the next; `stop` disposes
+ * one mount without disturbing a newer one. Both run on one chain, so the order
+ * calls were made in is the order they act in -- which is what keeps a
+ * replacement from binding while the old listener still owns the port.
+ */
+export declare class MountRegistry {
+    #private;
+    /**
+     * Start a mount after stopping the one already running.
+     *
+     * A creation that fails (or that decides it is unwanted and returns `null`)
+     * leaves the slot empty rather than with a half-mounted object.
+     *
+     * @param create - makes the mount; may return `null` to mount nothing.
+     * @returns the created mount, or `null`.
+     */
+    start<T extends Mounted>(create: () => Promise<T | null>): Promise<T | null>;
+    /**
+     * Stop the running mount.
+     *
+     * `null` is a no-op, and so is a mount a newer `start` has already replaced:
+     * that replacement disposed it before creating its own, and disposing it a
+     * second time would only run a shutdown that is already complete.
+     *
+     * @param mounted - the mount to dispose, when it is the one still running.
+     */
+    stop(mounted: Mounted | null): Promise<void>;
+    /** The mount this process is running, when it has one. */
+    get active(): Mounted | null;
+}

package/lib/mount.js

@@ -0,0 +1,110 @@
+//
+//  mount.ts
+//  MizarKit
+//
+//  One set of Mizar resources per process, mounted in order.
+//
+//  The reported failure: a phone could not reach its computer at all, and the
+//  machine had three live Mizar listeners in one DSH process — ports 19390,
+//  19391 and 19392, each belonging to a different plugin mount. The first one
+//  held the pairing's address, the current one held the relay replay target, and
+//  the port a phone had saved in its pairing was from neither of the two that
+//  still answered. A port that moves is a pairing that rots.
+//
+//  DSH may compose, reload or re-apply a bundle more than once, and each mount
+//  used to bind its own listener without the previous one necessarily being
+//  released first. The plugin cannot order DSH's lifecycle, so it enforces the
+//  invariant it owns instead: **at most one mount runs at a time, and a new one
+//  starts only after the previous one has finished shutting down.** Every start
+//  and stop goes through one promise chain, so concurrent applies queue rather
+//  than race.
+//
+//  Pure, so the ordering is tested without a plugin host or an open port.
+//
+/**
+ * The one registry every copy of this plugin in a process shares.
+ *
+ * Module-level state is not enough: the plugin can be loaded more than once in
+ * one process, and each load gets its own copy of this module -- which is how a
+ * single DSH process ended up with eight Mizar listeners (19390 through 19397)
+ * after 0.8.6 shipped a module-level registry. Each copy saw an empty slot and
+ * bound its own port, so the port a phone had saved was always one generation
+ * behind.
+ *
+ * `globalThis` is shared by every copy in the process, and `Symbol.for` gives
+ * the key a stable identity across them. The registry therefore outlives a
+ * module copy exactly as long as the process does, which is the lifetime that
+ * matters for a listening port.
+ *
+ * @returns the process-wide registry.
+ */
+export function sharedMountRegistry() {
+    const key = Symbol.for('dsh-mizar.mount-registry');
+    const bag = globalThis;
+    let registry = bag[key];
+    if (registry === undefined) {
+        registry = new MountRegistry();
+        bag[key] = registry;
+    }
+    return registry;
+}
+/**
+ * The serialized, single-instance mount slot.
+ *
+ * `start` disposes the running mount before creating the next; `stop` disposes
+ * one mount without disturbing a newer one. Both run on one chain, so the order
+ * calls were made in is the order they act in -- which is what keeps a
+ * replacement from binding while the old listener still owns the port.
+ */
+export class MountRegistry {
+    /** Serializes every start and stop. Never rejects; failures are per task. */
+    #tail = Promise.resolve();
+    #active = null;
+    /** Run one task after everything queued before it. */
+    #enqueue(task) {
+        const run = this.#tail.then(task, task);
+        this.#tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /**
+     * Start a mount after stopping the one already running.
+     *
+     * A creation that fails (or that decides it is unwanted and returns `null`)
+     * leaves the slot empty rather than with a half-mounted object.
+     *
+     * @param create - makes the mount; may return `null` to mount nothing.
+     * @returns the created mount, or `null`.
+     */
+    start(create) {
+        return this.#enqueue(async () => {
+            const previous = this.#active;
+            this.#active = null;
+            if (previous !== null)
+                await previous.dispose();
+            const created = await create();
+            this.#active = created;
+            return created;
+        });
+    }
+    /**
+     * Stop the running mount.
+     *
+     * `null` is a no-op, and so is a mount a newer `start` has already replaced:
+     * that replacement disposed it before creating its own, and disposing it a
+     * second time would only run a shutdown that is already complete.
+     *
+     * @param mounted - the mount to dispose, when it is the one still running.
+     */
+    stop(mounted) {
+        return this.#enqueue(async () => {
+            if (mounted === null || this.#active !== mounted)
+                return;
+            this.#active = null;
+            await mounted.dispose();
+        });
+    }
+    /** The mount this process is running, when it has one. */
+    get active() {
+        return this.#active;
+    }
+}

package/lib/relay/client.d.ts

@@ -24,6 +24,19 @@ export interface RelayClientOptions {
     readonly reconnectBaseMs?: number;
     /** Longest reconnect delay, in ms. */
     readonly reconnectMaxMs?: number;
+    /**
+     * How long the relay may stay silent before the tunnel is redialled, in ms.
+     *
+     * The relay pings every tunnel (`tunnelIdleMs / 3` in its own config, 30 s by
+     * default) precisely so that a half-open tunnel becomes a `close` it can act
+     * on. The computer has the mirror problem: a network change can blackhole the
+     * socket without the operating system ever reporting a close, and then the
+     * tunnel is gone at the relay while this side still says "connected" -- which
+     * is what left a phone's relay room unreachable for hours. Silence for longer
+     * than this window is treated as a dead tunnel and redialled. `0` disables the
+     * watchdog.
+     */
+    readonly watchdogMs?: number;
 }
 /** What the outside world can see about the tunnel. */
 export interface RelayClientState {
@@ -45,6 +58,12 @@ export interface RelayClientState {
 export interface RelaySocket {
     send(text: string): void;
     close(code?: number, reason?: string): void;
+    /**
+     * Drop the socket without a closing handshake, when the implementation has
+     * one. A half-open socket cannot complete a close handshake, so the watchdog
+     * needs this; a test stand-in may omit it and be closed with `close`.
+     */
+    terminate?(): void;
     on(event: 'message', listener: (data: Buffer, isBinary: boolean) => void): unknown;
     on(event: 'close', listener: (code: number, reason: Buffer) => void): unknown;
     on(event: 'error', listener: (error: Error) => void): unknown;
@@ -121,4 +140,26 @@ export declare class RelayClient {
     start(): void;
     /** Stop reconnecting and close the tunnel. */
     stop(): void;
+    /**
+     * Redial the tunnel now, keeping the reconnect loop.
+     *
+     * Used when the reason to redial is known here rather than discovered by the
+     * transport: the host's network changed, or the listener moved to a different
+     * port. The attempt counter is reset so the next socket is tried at the base
+     * delay rather than after a backoff earned by an unrelated failure.
+     *
+     * @param reason - why, for the operator's log.
+     */
+    reconnectNow(reason: string): void;
+    /**
+     * Point the replay target at a listener bound to a different port.
+     *
+     * Rebinding can land on a different port when the configured one was taken
+     * while the listener was moving. The tunnel was constructed with the port the
+     * listener had at startup; replaying to the old one would answer every phone
+     * request with a connection error over a tunnel that is otherwise healthy.
+     *
+     * @param port - the listener's current port.
+     */
+    setLocalPort(port: number): void;
 }

package/lib/relay/client.js

@@ -168,11 +168,18 @@ function forwardable(headers) {
 /** The tunnel client. */
 export class RelayClient {
     #options;
+    #localHost;
+    #localPort;
     #localOrigin;
     #socket = null;
     #stopped = false;
     #attempt = 0;
     #timer;
+    /** How long silence from the relay is tolerated before a redial. */
+    #watchdogMs;
+    #watchdog;
+    /** When the last frame from the relay arrived, on any clock change. */
+    #lastFrameAt = 0;
     /** Phone WebSockets currently bridged through this tunnel, by tunnel id. */
     #streams = new Map();
     #state = { connected: false, room: null, lastError: null };
@@ -181,8 +188,10 @@ export class RelayClient {
      */
     constructor(options) {
         this.#options = options;
-        const host = options.localHost ?? '127.0.0.1';
-        this.#localOrigin = `http://${host}:${options.localPort}`;
+        this.#localHost = options.localHost ?? '127.0.0.1';
+        this.#localPort = options.localPort;
+        this.#localOrigin = `http://${this.#localHost}:${this.#localPort}`;
+        this.#watchdogMs = options.watchdogMs ?? 120_000;
     }
     /** The relay connection's current state. */
     get state() {
@@ -195,6 +204,8 @@ export class RelayClient {
     /** Connect, and keep reconnecting until {@link stop}. */
     start() {
         this.#stopped = false;
+        this.#lastFrameAt = Date.now();
+        this.#armWatchdog();
         this.#connect();
     }
     /** Stop reconnecting and close the tunnel. */
@@ -203,11 +214,54 @@ export class RelayClient {
         if (this.#timer !== undefined)
             clearTimeout(this.#timer);
         this.#timer = undefined;
+        if (this.#watchdog !== undefined)
+            clearInterval(this.#watchdog);
+        this.#watchdog = undefined;
         this.#closeStreams('the tunnel is shutting down');
         this.#socket?.close(1000, 'shutting down');
         this.#socket = null;
         this.#setState({ connected: false });
     }
+    /**
+     * Redial the tunnel now, keeping the reconnect loop.
+     *
+     * Used when the reason to redial is known here rather than discovered by the
+     * transport: the host's network changed, or the listener moved to a different
+     * port. The attempt counter is reset so the next socket is tried at the base
+     * delay rather than after a backoff earned by an unrelated failure.
+     *
+     * @param reason - why, for the operator's log.
+     */
+    reconnectNow(reason) {
+        if (this.#stopped)
+            return;
+        this.#attempt = 0;
+        if (this.#socket === null) {
+            this.#options.log(`relay: ${reason} — redialling the tunnel`);
+            this.#scheduleReconnect(0);
+            return;
+        }
+        this.#options.log(`relay: ${reason} — redialling the tunnel`);
+        this.#drop(reason);
+    }
+    /**
+     * Point the replay target at a listener bound to a different port.
+     *
+     * Rebinding can land on a different port when the configured one was taken
+     * while the listener was moving. The tunnel was constructed with the port the
+     * listener had at startup; replaying to the old one would answer every phone
+     * request with a connection error over a tunnel that is otherwise healthy.
+     *
+     * @param port - the listener's current port.
+     */
+    setLocalPort(port) {
+        if (!Number.isFinite(port) || port <= 0 || port === this.#localPort)
+            return;
+        this.#localPort = port;
+        this.#localOrigin = `http://${this.#localHost}:${port}`;
+        this.#options.log(`relay: the listener moved to port ${port}`);
+        this.reconnectNow('the listener moved to a different port');
+    }
     /** Open a connection attempt. */
     #connect() {
         if (this.#stopped)
@@ -222,14 +276,24 @@ export class RelayClient {
                 headers: { authorization: `Bearer ${this.#options.token}` },
             });
         this.#socket = socket;
+        this.#lastFrameAt = Date.now();
         socket.on('open', () => {
+            this.#lastFrameAt = Date.now();
             this.#options.log(`relay: connected to ${url}`);
         });
-        socket.on('message', (data) => this.#receive(data.toString('utf8')));
+        socket.on('message', (data) => {
+            this.#lastFrameAt = Date.now();
+            this.#receive(data.toString('utf8'));
+        });
         socket.on('error', (error) => {
             this.#options.log(`relay: ${error.message}`);
         });
         socket.on('close', () => {
+            // A socket this client has already replaced is not news: the watchdog and
+            // `reconnectNow` both drop the old socket before scheduling the next, and
+            // acting on its late close would reset the backoff they just earned.
+            if (this.#socket !== socket)
+                return;
             this.#socket = null;
             this.#closeStreams('the tunnel closed');
             if (this.#stopped)
@@ -237,10 +301,75 @@ export class RelayClient {
             const delay = this.#backoff();
             this.#setState({ connected: false, lastError: 'the relay connection closed' });
             this.#options.log(`relay: reconnecting in ${Math.round(delay / 1000)}s`);
-            this.#timer = setTimeout(() => this.#connect(), delay);
-            this.#timer.unref?.();
+            this.#scheduleReconnect(delay);
         });
     }
+    /** Time one connection attempt, clearing any already pending. */
+    #scheduleReconnect(delay) {
+        if (this.#timer !== undefined)
+            clearTimeout(this.#timer);
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            this.#connect();
+        }, delay);
+        this.#timer.unref?.();
+    }
+    /**
+     * Start the silence watchdog.
+     *
+     * The relay pings every tunnel so a computer that vanished is dropped; this is
+     * the same question asked from the other side. Without it a half-open socket
+     * -- a laptop that walked to another network -- stays "connected" here while
+     * the relay has already forgotten the room, and nothing ever redials.
+     */
+    #armWatchdog() {
+        if (this.#watchdog !== undefined || this.#watchdogMs <= 0)
+            return;
+        const every = Math.max(20, Math.floor(this.#watchdogMs / 4));
+        this.#watchdog = setInterval(() => this.#checkWatchdog(), every);
+        this.#watchdog.unref?.();
+    }
+    /** Redial a tunnel the relay has stopped talking to. */
+    #checkWatchdog() {
+        if (this.#stopped || this.#socket === null)
+            return;
+        const silent = Date.now() - this.#lastFrameAt;
+        if (silent <= this.#watchdogMs)
+            return;
+        this.#options.log(`relay: the tunnel has been silent for ${Math.round(silent / 1000)}s — redialling it`);
+        this.#drop('no traffic from the relay inside the watchdog window');
+    }
+    /**
+     * Forget the current socket and start over.
+     *
+     * `terminate` rather than `close` where the transport has it: a half-open
+     * socket cannot complete a closing handshake, and waiting for one is how the
+     * "connected" state outlives the connection. A test socket without `terminate`
+     * gets the ordinary close.
+     */
+    #drop(reason) {
+        const socket = this.#socket;
+        this.#socket = null;
+        this.#closeStreams(reason);
+        if (socket !== null) {
+            try {
+                if (typeof socket.terminate === 'function')
+                    socket.terminate();
+                else
+                    socket.close(4001, reason);
+            }
+            catch {
+                // The close/reconnect below is the recovery path; a throwing transport is
+                // already gone.
+            }
+        }
+        if (this.#stopped)
+            return;
+        const delay = this.#backoff();
+        this.#setState({ connected: false, lastError: reason });
+        this.#options.log(`relay: ${reason}; reconnecting in ${Math.round(delay / 1000)}s`);
+        this.#scheduleReconnect(delay);
+    }
     /** Exponential backoff with jitter, so many computers do not return in lockstep. */
     #backoff() {
         const base = this.#options.reconnectBaseMs ?? 1_000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mizar",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Remote monitoring and guidance for DSH agents — host plugin backing the DSH-Mizar iOS app.",
   "license": "GPL-3.0-only",
   "type": "module",