@ceralive/modem-control 1.2.1 → 1.3.0

package/dist/backend/mm-mutations.js

@@ -1,259 +1,52 @@
-// The ModemManager mutations — the disruptive-and-SIM half of `ModemManagerPort`.
-//
-// Every disruptive op runs through the shared per-modem `ModemActor` (serialized on
-// the STABLE key, so two ops on one modem never interleave and a replug keeps the
-// same queue). Mode and slot changes additionally run QUIESCED (NM briefly stands
-// down first, via the actor's quiesce hook). PIN / PUK / scan serialize too but do
-// NOT quiesce — they don't touch the bearer. NONE of these methods can reach a bearer
-// or connect verb: the port has none, and the fake's tripwire proves it at test time.
-import { decodeBandList, encodeBandList, isResetSelection } from '../band/index.js';
-import { epochMillis } from '../domain/index.js';
-import { receipt } from '../ports/index.js';
-import { MM_BUS_NAME, MM_MANAGER_IFACE, MM_ROOT_PATH, MODEM_IFACE, MODEM3GPP_IFACE, } from './constants.js';
-import { fetchManagedObjects, findInterface, numberProp, propValue, stringProp, } from './managed-objects.js';
-import { sendSimPin, sendSimPuk } from './sim-unlock.js';
-/** MMModemMode bit per RAT family (2G/3G/4G/5G). */
-const MODE_BIT = { gsm: 2, umts: 4, lte: 8, '5gnr': 16 };
-/** MMModem3gppNetworkAvailability → the port's availability. */
-const AVAILABILITY = {
-    0: 'unknown',
-    1: 'available',
-    2: 'current',
-    3: 'forbidden',
-};
-/** A network scan can take a long time — MM's own default is not enough. */
+import { MM_BUS_NAME } from './constants.js';
+import { readBands, setCurrentBands } from './mm-mutations/bands.js';
+import { inhibitDevice, uninhibitDevice } from './mm-mutations/inhibit.js';
+import { setModeCombination, setRadioModes } from './mm-mutations/modes.js';
+import { scanNetworks } from './mm-mutations/scan.js';
+import { setPrimarySimSlot, unlockWithPin, unlockWithPuk } from './mm-mutations/sim.js';
 const DEFAULT_SCAN_TIMEOUT_MS = 300_000;
-/** The disruptive + SIM mutations of `ModemManagerPort`, serialized per modem. */
 export class MmMutations {
-    #transport;
-    #actor;
-    #destination;
-    #resolveStableKey;
+    #context;
     #scanTimeoutMs;
     #now;
     constructor(deps) {
-        this.#transport = deps.transport;
-        this.#actor = deps.actor;
-        this.#destination = deps.destination ?? MM_BUS_NAME;
-        this.#resolveStableKey = deps.resolveStableKey;
+        this.#context = {
+            transport: deps.transport,
+            actor: deps.actor,
+            destination: deps.destination ?? MM_BUS_NAME,
+            resolveStableKey: deps.resolveStableKey,
+        };
         this.#scanTimeoutMs = deps.scanTimeoutMs ?? DEFAULT_SCAN_TIMEOUT_MS;
         this.#now = deps.now ?? Date.now;
     }
     setRadioModes(modem, preference) {
-        const allowed = maskOf(preference.allowedSet ?? new Set(preference.preferenceOrdered));
-        const preferred = preference.preferenceOrdered[0];
-        const preferredMask = preferred !== undefined ? MODE_BIT[preferred] : 0;
-        if (allowed === 0) {
-            return Promise.resolve(receipt('radio', 'failed', 'no radio modes were requested'));
-        }
-        return this.#actor.runQuiesced({ stableKey: this.#resolveStableKey(modem) }, async () => {
-            try {
-                await this.#transport.callMethod({
-                    destination: this.#destination,
-                    path: modem,
-                    interface: MODEM_IFACE,
-                    member: 'SetCurrentModes',
-                    signature: '(uu)',
-                    args: [[allowed, preferredMask]],
-                });
-                return receipt('radio', 'applied', 'radio mode preference applied');
-            }
-            catch (error) {
-                return receipt('radio', 'failed', `SetCurrentModes failed: ${describe(error)}`);
-            }
-        });
+        return setRadioModes(this.#context, modem, preference);
     }
-    /**
-     * `SetCurrentModes` over the RAW `(uu)` masks the modem itself advertised.
-     *
-     * `setRadioModes` above speaks the reconciler's vocabulary — an ordered RAT
-     * preference — and structurally cannot express `MM_MODEM_MODE_NONE`: its preferred
-     * mask is derived from `preferenceOrdered[0]`, so "allow this set and prefer
-     * nothing within it" has no spelling. That is the combination the bench FM350-GL
-     * actually advertises, so a caller selecting an advertised combination verbatim
-     * needs this entry point. It quiesces for the same reason `setRadioModes` does: a
-     * mode change re-registers the radio and drops the bearer underneath NM.
-     *
-     * An `allowed` mask of 0 is refused — that is not a selection, it is a radio with
-     * nothing switched on — while a `preferred` mask of 0 is passed through untouched.
-     */
     setModeCombination(modem, allowed, preferred) {
-        if (allowed === 0) {
-            return Promise.resolve(receipt('radio', 'failed', 'no radio modes were requested'));
-        }
-        return this.#actor.runQuiesced({ stableKey: this.#resolveStableKey(modem) }, async () => {
-            try {
-                await this.#transport.callMethod({
-                    destination: this.#destination,
-                    path: modem,
-                    interface: MODEM_IFACE,
-                    member: 'SetCurrentModes',
-                    signature: '(uu)',
-                    args: [[allowed, preferred]],
-                });
-                return receipt('radio', 'applied', 'radio mode combination applied');
-            }
-            catch (error) {
-                return receipt('radio', 'failed', `SetCurrentModes failed: ${describe(error)}`);
-            }
-        });
+        return setModeCombination(this.#context, modem, allowed, preferred);
     }
-    async readBands(modem) {
-        try {
-            const tree = await fetchManagedObjects(this.#transport, this.#destination);
-            const props = findInterface(tree, modem, MODEM_IFACE);
-            if (props === undefined) {
-                return { ok: false, reason: 'the modem exports no Modem interface' };
-            }
-            return {
-                ok: true,
-                bands: {
-                    supported: decodeBandList(propValue(props, 'SupportedBands')),
-                    current: decodeBandList(propValue(props, 'CurrentBands')),
-                },
-            };
-        }
-        catch (error) {
-            return { ok: false, reason: `reading bands failed: ${describe(error)}` };
-        }
+    readBands(modem) {
+        return readBands(this.#context, modem);
     }
-    // Quiesced like `setRadioModes`, and for the same reason: a band change
-    // re-registers the radio, so NM must stand down before the bearer drops
-    // underneath it rather than after.
     setCurrentBands(modem, bands) {
-        if (bands.length === 0) {
-            return Promise.resolve(receipt('band', 'failed', 'no bands were requested'));
-        }
-        const encoded = encodeBandList(bands);
-        if (!encoded.ok) {
-            return Promise.resolve(receipt('band', 'unsupported', `this build does not know the band "${encoded.unknown}"`));
-        }
-        const values = encoded.values;
-        return this.#actor.runQuiesced({ stableKey: this.#resolveStableKey(modem) }, async () => {
-            try {
-                await this.#transport.callMethod({
-                    destination: this.#destination,
-                    path: modem,
-                    interface: MODEM_IFACE,
-                    member: 'SetCurrentBands',
-                    signature: 'au',
-                    args: [values],
-                });
-                return receipt('band', 'applied', isResetSelection(bands) ? 'band lock released' : `bands set to ${bands.join(', ')}`);
-            }
-            catch (error) {
-                return receipt('band', 'failed', `SetCurrentBands failed: ${describe(error)}`);
-            }
-        });
+        return setCurrentBands(this.#context, modem, bands);
     }
-    async setPrimarySimSlot(modem, slotIndex) {
-        const slots = await this.#readSlotCount(modem);
-        if (slots === undefined) {
-            return receipt('simSlot', 'failed', 'could not read the modem SIM-slot list');
-        }
-        if (slots <= 1) {
-            return receipt('simSlot', 'unsupported', 'single-slot modem has no primary slot to select');
-        }
-        if (slotIndex < 1 || slotIndex > slots) {
-            return receipt('simSlot', 'failed', `slot ${slotIndex} is out of range (1..${slots})`);
-        }
-        return this.#actor.runQuiesced({ stableKey: this.#resolveStableKey(modem) }, async () => {
-            try {
-                await this.#transport.callMethod({
-                    destination: this.#destination,
-                    path: modem,
-                    interface: MODEM_IFACE,
-                    member: 'SetPrimarySimSlot',
-                    signature: 'u',
-                    args: [slotIndex],
-                });
-                return receipt('simSlot', 'applied', `primary SIM slot set to ${slotIndex}`);
-            }
-            catch (error) {
-                return receipt('simSlot', 'failed', `SetPrimarySimSlot failed: ${describe(error)}`);
-            }
-        });
+    setPrimarySimSlot(modem, slotIndex) {
+        return setPrimarySimSlot(this.#context, modem, slotIndex);
     }
     sendPin(modem, pin) {
-        return this.#actor.run(this.#resolveStableKey(modem), () => sendSimPin(this.#transport, this.#destination, modem, pin));
+        return unlockWithPin(this.#context, modem, pin);
     }
     sendPuk(modem, puk, newPin) {
-        return this.#actor.run(this.#resolveStableKey(modem), () => sendSimPuk(this.#transport, this.#destination, modem, puk, newPin));
+        return unlockWithPuk(this.#context, modem, puk, newPin);
     }
     scanNetworks(modem) {
-        return this.#actor.run(this.#resolveStableKey(modem), async () => {
-            try {
-                const reply = await this.#transport.callMethod({
-                    destination: this.#destination,
-                    path: modem,
-                    interface: MODEM3GPP_IFACE,
-                    member: 'Scan',
-                    timeoutMs: this.#scanTimeoutMs,
-                });
-                return { ok: true, networks: parseScan(reply.body[0]) };
-            }
-            catch (error) {
-                return { ok: false, reason: `network scan failed: ${describe(error)}` };
-            }
-        });
+        return scanNetworks(this.#context, modem, this.#scanTimeoutMs);
     }
-    async inhibit(uid) {
-        await this.#inhibitDevice(uid, true);
-        return { uid, acquiredAt: epochMillis(this.#now()) };
+    inhibit(uid) {
+        return inhibitDevice(this.#context, uid, this.#now);
     }
-    async uninhibit(lease) {
-        await this.#inhibitDevice(lease.uid, false);
+    uninhibit(lease) {
+        return uninhibitDevice(this.#context, lease);
     }
-    #inhibitDevice(uid, inhibit) {
-        return this.#transport.callMethod({
-            destination: this.#destination,
-            path: MM_ROOT_PATH,
-            interface: MM_MANAGER_IFACE,
-            member: 'InhibitDevice',
-            signature: 'sb',
-            args: [uid, inhibit],
-        });
-    }
-    async #readSlotCount(modem) {
-        try {
-            const tree = await fetchManagedObjects(this.#transport, this.#destination);
-            const slots = propValue(findInterface(tree, modem, MODEM_IFACE), 'SimSlots');
-            return Array.isArray(slots) ? slots.length : undefined;
-        }
-        catch {
-            return undefined;
-        }
-    }
-}
-/** OR of the MMModemMode bits for a set of RATs. */
-function maskOf(rats) {
-    let mask = 0;
-    for (const rat of rats) {
-        mask |= MODE_BIT[rat];
-    }
-    return mask;
-}
-/** Parse a `Modem3gpp.Scan` reply (`aa{sv}` → dicts) into scanned networks. */
-function parseScan(value) {
-    if (!Array.isArray(value)) {
-        return [];
-    }
-    const networks = [];
-    for (const entry of value) {
-        const operatorCode = stringProp(entry, 'operator-code');
-        if (operatorCode === undefined) {
-            continue;
-        }
-        const name = stringProp(entry, 'operator-long') ?? stringProp(entry, 'operator-short');
-        const availability = AVAILABILITY[numberProp(entry, 'status') ?? 0] ?? 'unknown';
-        networks.push({
-            operatorCode,
-            ...(name !== undefined ? { operatorName: name } : {}),
-            availability,
-        });
-    }
-    return networks;
-}
-function describe(error) {
-    return error instanceof Error ? error.message : String(error);
 }

package/dist/backend/observer/bus-lifecycle.d.ts

@@ -0,0 +1,7 @@
+import type { DbusTransport, SignalEvent, Subscription } from '../../transport/index.js';
+export interface ObserverSignalHandlers {
+    readonly onObjectSignal: (event: SignalEvent) => void;
+    readonly onNameOwnerChanged: (event: SignalEvent) => void;
+}
+export declare function subscribeObserverSignals(transport: DbusTransport, handlers: ObserverSignalHandlers): Promise<readonly Subscription[]>;
+export declare function unsubscribeObserverSignals(subscriptions: readonly Subscription[]): Promise<void>;

package/dist/backend/observer/bus-lifecycle.js

@@ -0,0 +1,12 @@
+import { DBUS_IFACE, MM_ROOT_PATH, OBJECT_MANAGER_IFACE, PROPERTIES_IFACE } from '../constants.js';
+export async function subscribeObserverSignals(transport, handlers) {
+    const objectManager = { interface: OBJECT_MANAGER_IFACE, path: MM_ROOT_PATH };
+    const interfacesAdded = await transport.subscribeSignal({ ...objectManager, member: 'InterfacesAdded' }, handlers.onObjectSignal);
+    const interfacesRemoved = await transport.subscribeSignal({ ...objectManager, member: 'InterfacesRemoved' }, handlers.onObjectSignal);
+    const propertiesChanged = await transport.subscribeSignal({ interface: PROPERTIES_IFACE, member: 'PropertiesChanged' }, handlers.onObjectSignal);
+    const nameOwnerChanged = await transport.subscribeSignal({ interface: DBUS_IFACE, member: 'NameOwnerChanged' }, handlers.onNameOwnerChanged);
+    return [interfacesAdded, interfacesRemoved, propertiesChanged, nameOwnerChanged];
+}
+export async function unsubscribeObserverSignals(subscriptions) {
+    await Promise.all(subscriptions.map((subscription) => subscription.unsubscribe().catch(() => undefined)));
+}

package/dist/backend/observer/epoch-reconcile.d.ts

@@ -0,0 +1,4 @@
+import type { DbusTransport } from '../../transport/index.js';
+import { type DecodedManagedObjects } from '../managed-objects.js';
+export declare function queryModemManagerOwner(transport: DbusTransport): Promise<string | undefined>;
+export declare function readAuthoritativeTree(transport: DbusTransport, destination: string): Promise<DecodedManagedObjects>;

package/dist/backend/observer/epoch-reconcile.js

@@ -0,0 +1,28 @@
+import { DBUS_DESTINATION, DBUS_IFACE, DBUS_PATH, MM_BUS_NAME, MM_ROOT_PATH, OBJECT_MANAGER_IFACE, } from '../constants.js';
+import { asManagedObjects } from '../managed-objects.js';
+export async function queryModemManagerOwner(transport) {
+    try {
+        const reply = await transport.callMethod({
+            destination: DBUS_DESTINATION,
+            path: DBUS_PATH,
+            interface: DBUS_IFACE,
+            member: 'GetNameOwner',
+            signature: 's',
+            args: [MM_BUS_NAME],
+        });
+        const owner = reply.body[0];
+        return typeof owner === 'string' && owner.length > 0 ? owner : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function readAuthoritativeTree(transport, destination) {
+    const reply = await transport.callMethod({
+        destination,
+        path: MM_ROOT_PATH,
+        interface: OBJECT_MANAGER_IFACE,
+        member: 'GetManagedObjects',
+    });
+    return asManagedObjects(reply.body[0]);
+}

package/dist/backend/observer/signal-routing.d.ts

@@ -0,0 +1,11 @@
+import type { SignalEvent } from '../../transport/index.js';
+export type OwnerSignal = {
+    readonly kind: 'unrelated';
+} | {
+    readonly kind: 'lost';
+} | {
+    readonly kind: 'owned';
+    readonly owner: string;
+};
+export declare function routeOwnerSignal(event: SignalEvent): OwnerSignal;
+export declare function isCurrentOwnerSignal(event: SignalEvent, currentOwner: string | undefined): boolean;

package/dist/backend/observer/signal-routing.js

@@ -0,0 +1,11 @@
+import { MM_BUS_NAME } from '../constants.js';
+export function routeOwnerSignal(event) {
+    if (event.body[0] !== MM_BUS_NAME) {
+        return { kind: 'unrelated' };
+    }
+    const newOwner = typeof event.body[2] === 'string' ? event.body[2] : '';
+    return newOwner.length === 0 ? { kind: 'lost' } : { kind: 'owned', owner: newOwner };
+}
+export function isCurrentOwnerSignal(event, currentOwner) {
+    return currentOwner !== undefined && event.sender === currentOwner;
+}

package/dist/backend/observer.d.ts

@@ -1,6 +1,6 @@
 import type { ModemObservationPort, ObservationList, ObservationListener, Unsubscribe } from '../ports/index.js';
 import type { DbusTransport } from '../transport/index.js';
-import { type DecodedManagedObjects } from './managed-objects.js';
+import type { DecodedManagedObjects } from './managed-objects.js';
 /**
  * A current-epoch authoritative snapshot, delivered to `onEpochRefresh` AFTER the
  * epoch guard passes. `epoch` is the owning MM unique bus name; `tree` is the decoded

package/dist/backend/observer.js

@@ -13,8 +13,10 @@
 // `sourceUnavailable`. The false-removal class is dead by construction: even the
 // `ObservationList` failure arm retains its rows. Row bookkeeping lives in
 // `ObservationRowStore`; this file owns epoch tracking, subscriptions, and refresh.
-import { DBUS_DESTINATION, DBUS_IFACE, DBUS_PATH, MM_BUS_NAME, MM_ROOT_PATH, OBJECT_MANAGER_IFACE, PROPERTIES_IFACE, } from './constants.js';
-import { asManagedObjects } from './managed-objects.js';
+import { MM_BUS_NAME } from './constants.js';
+import { subscribeObserverSignals, unsubscribeObserverSignals } from './observer/bus-lifecycle.js';
+import { queryModemManagerOwner, readAuthoritativeTree } from './observer/epoch-reconcile.js';
+import { isCurrentOwnerSignal, routeOwnerSignal } from './observer/signal-routing.js';
 import { ObservationRowStore } from './row-store.js';
 export class MmDbusObserver {
     #transport;
@@ -70,14 +72,16 @@ export class MmDbusObserver {
         this.#stopped = true;
         this.#transport.off('disconnected', this.#onDisconnected);
         this.#transport.off('reconnected', this.#onReconnected);
-        const subs = this.#subscriptions.splice(0);
-        await Promise.all(subs.map((sub) => sub.unsubscribe().catch(() => undefined)));
+        const subscriptions = this.#subscriptions.splice(0);
+        await unsubscribeObserverSignals(subscriptions);
         this.#listeners.clear();
     }
     // ── signal subscription ────────────────────────────────────────────────────────
     async #subscribeAll() {
-        const om = { interface: OBJECT_MANAGER_IFACE, path: MM_ROOT_PATH };
-        this.#subscriptions.push(await this.#transport.subscribeSignal({ ...om, member: 'InterfacesAdded' }, (event) => this.#onObjectSignal(event)), await this.#transport.subscribeSignal({ ...om, member: 'InterfacesRemoved' }, (event) => this.#onObjectSignal(event)), await this.#transport.subscribeSignal({ interface: PROPERTIES_IFACE, member: 'PropertiesChanged' }, (event) => this.#onObjectSignal(event)), await this.#transport.subscribeSignal({ interface: DBUS_IFACE, member: 'NameOwnerChanged' }, (event) => this.#onNameOwnerChanged(event)));
+        this.#subscriptions.push(...(await subscribeObserverSignals(this.#transport, {
+            onObjectSignal: (event) => this.#onObjectSignal(event),
+            onNameOwnerChanged: (event) => this.#onNameOwnerChanged(event),
+        })));
     }
     // ── epoch tracking ───────────────────────────────────────────────────────────
     async #adoptCurrentOwner() {
@@ -90,47 +94,32 @@ export class MmDbusObserver {
         await this.#runRefresh(owner);
     }
     async #queryOwner() {
-        try {
-            const reply = await this.#transport.callMethod({
-                destination: DBUS_DESTINATION,
-                path: DBUS_PATH,
-                interface: DBUS_IFACE,
-                member: 'GetNameOwner',
-                signature: 's',
-                args: [MM_BUS_NAME],
-            });
-            const owner = reply.body[0];
-            return typeof owner === 'string' && owner.length > 0 ? owner : undefined;
-        }
-        catch {
-            // NameHasNoOwner (or a transient failure) → no current epoch yet.
-            return undefined;
-        }
+        return queryModemManagerOwner(this.#transport);
     }
     #onNameOwnerChanged(event) {
-        if (event.body[0] !== MM_BUS_NAME) {
+        const routed = routeOwnerSignal(event);
+        if (routed.kind === 'unrelated') {
             return;
         }
-        const newOwner = typeof event.body[2] === 'string' ? event.body[2] : '';
-        if (newOwner.length === 0) {
+        if (routed.kind === 'lost') {
             // Owner lost — stale, never a removal.
             this.#handleSourceGone('source-unavailable');
             return;
         }
-        if (newOwner === this.#currentOwner) {
+        if (routed.owner === this.#currentOwner) {
             return;
         }
         // New epoch: everything goes stale until the fresh snapshot restores it.
         if (this.#store.markUnavailable('source-unavailable')) {
             this.#emit();
         }
-        this.#currentOwner = newOwner;
+        this.#currentOwner = routed.owner;
         this.#scheduleRefresh();
     }
     #onObjectSignal(event) {
         // Epoch guard: a signal from anyone but the current owner is an OLD-epoch
         // straggler and must never drive a removal (draft §Oracle round-3 #5).
-        if (this.#currentOwner === undefined || event.sender !== this.#currentOwner) {
+        if (!isCurrentOwnerSignal(event, this.#currentOwner)) {
             return;
         }
         if (this.#priming) {
@@ -154,17 +143,11 @@ export class MmDbusObserver {
     async #runRefresh(epochOwner) {
         this.#refreshing = true;
         try {
-            const reply = await this.#transport.callMethod({
-                destination: this.#destination,
-                path: MM_ROOT_PATH,
-                interface: OBJECT_MANAGER_IFACE,
-                member: 'GetManagedObjects',
-            });
+            const tree = await readAuthoritativeTree(this.#transport, this.#destination);
             // Late reply from a superseded epoch — discard (draft §Oracle round-3 #5).
             if (this.#currentOwner !== epochOwner || this.#stopped) {
                 return;
             }
-            const tree = asManagedObjects(reply.body[0]);
             const rowsChanged = this.#store.reconcile(tree);
             const healthChanged = this.#store.markHealthy();
             this.#notifyEpochRefresh(epochOwner, tree);

package/dist/backend/router-ethernet.d.ts

@@ -9,7 +9,14 @@ export interface RouterEthernetProbeDeps {
     readonly resolveGateway?: (ifname: DeviceIfname) => Promise<string | undefined>;
     /** Whether `host` is reachable via `ifname` (ICMP). */
     readonly ping?: (host: string, ifname: DeviceIfname) => Promise<boolean>;
+    /** Override the public DNS target used by the egress probe. */
+    readonly probeHost?: string;
+    /** Bound applied to every default subprocess, including `ip`. */
+    readonly subprocessTimeoutMs?: number;
 }
+export declare const ROUTER_PROBE_FAILURES: readonly ['command-missing', 'timeout', 'nonzero-exit', 'unreachable'];
+export type RouterProbeFailureKind = (typeof ROUTER_PROBE_FAILURES)[number];
+export declare function classifyRouterProbeFailure(error: unknown): RouterProbeFailureKind;
 /**
  * Create a router-ethernet probe implementing the advisory `RouterPort`. Presence is
  * link-up; health additionally reports DHCP-gateway reachability and a basic egress

package/dist/backend/router-ethernet.js

@@ -8,38 +8,70 @@
 // observed. Each probe is an injectable seam (default `Bun.spawn` of `ip` / `ping`)
 // so tests run with no real network.
 import { epochMillis } from '../domain/index.js';
+export const ROUTER_PROBE_FAILURES = [
+    'command-missing',
+    'timeout',
+    'nonzero-exit',
+    'unreachable',
+];
+export function classifyRouterProbeFailure(error) {
+    if (error instanceof Error && error.name === 'TimeoutError')
+        return 'timeout';
+    if (error instanceof Error && error.name === 'UnreachableError')
+        return 'unreachable';
+    if (error instanceof Error &&
+        'code' in error &&
+        typeof error.code === 'string' &&
+        error.code === 'ENOENT') {
+        return 'command-missing';
+    }
+    return 'nonzero-exit';
+}
 /** The host used for the basic egress-health probe (public DNS anycast). */
 const EGRESS_PROBE_HOST = '1.1.1.1';
-async function spawnSucceeds(command) {
+const DEFAULT_SUBPROCESS_TIMEOUT_MS = 5_000;
+function bounded(operation, timeoutMs) {
+    return Promise.race([
+        operation,
+        new Promise((_, reject) => setTimeout(() => reject(Object.assign(new Error('probe timed out'), { name: 'TimeoutError' })), timeoutMs)),
+    ]);
+}
+async function spawnSucceeds(command, timeoutMs) {
     try {
         const proc = Bun.spawn([...command], { stdout: 'pipe', stderr: 'pipe' });
-        return (await proc.exited) === 0;
+        return ((await Promise.race([
+            proc.exited,
+            new Promise((resolve) => setTimeout(() => resolve(124), timeoutMs)),
+        ])) === 0);
     }
     catch {
         return false;
     }
 }
-async function spawnOutput(command) {
+async function spawnOutput(command, timeoutMs) {
     try {
         const proc = Bun.spawn([...command], { stdout: 'pipe', stderr: 'pipe' });
-        const [out, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+        const [out, code] = await Promise.race([
+            Promise.all([new Response(proc.stdout).text(), proc.exited]),
+            new Promise((resolve) => setTimeout(() => resolve(['', 124]), timeoutMs)),
+        ]);
         return code === 0 ? out : '';
     }
     catch {
         return '';
     }
 }
-function defaultCheckLinkUp(ifname) {
-    return spawnSucceeds(['ip', 'link', 'show', 'up', 'dev', String(ifname)]);
+function defaultCheckLinkUp(ifname, timeoutMs) {
+    return spawnSucceeds(['ip', 'link', 'show', 'up', 'dev', String(ifname)], timeoutMs);
 }
-async function defaultResolveGateway(ifname) {
+async function defaultResolveGateway(ifname, timeoutMs) {
     // `ip -o route show default dev <ifname>` → "default via 192.168.8.1 dev <ifname> …".
-    const out = await spawnOutput(['ip', '-o', 'route', 'show', 'default', 'dev', String(ifname)]);
+    const out = await spawnOutput(['ip', '-o', 'route', 'show', 'default', 'dev', String(ifname)], timeoutMs);
     const match = out.match(/default via (\S+)/);
     return match?.[1];
 }
-function defaultPing(host, ifname) {
-    return spawnSucceeds(['ping', '-c', '1', '-W', '2', '-I', String(ifname), host]);
+function defaultPing(host, ifname, timeoutMs) {
+    return spawnSucceeds(['ping', '-c', '1', '-W', '2', '-I', String(ifname), host], timeoutMs);
 }
 /**
  * Create a router-ethernet probe implementing the advisory `RouterPort`. Presence is
@@ -49,18 +81,38 @@ function defaultPing(host, ifname) {
  */
 export function createRouterEthernetProbe(deps = {}) {
     const now = deps.now ?? (() => epochMillis(Date.now()));
-    const checkLinkUp = deps.checkLinkUp ?? defaultCheckLinkUp;
-    const resolveGateway = deps.resolveGateway ?? defaultResolveGateway;
-    const ping = deps.ping ?? defaultPing;
+    const timeoutMs = deps.subprocessTimeoutMs ?? DEFAULT_SUBPROCESS_TIMEOUT_MS;
+    const checkLinkUp = deps.checkLinkUp ?? ((ifname) => defaultCheckLinkUp(ifname, timeoutMs));
+    const resolveGateway = deps.resolveGateway ?? ((ifname) => defaultResolveGateway(ifname, timeoutMs));
+    const ping = deps.ping ?? ((host, ifname) => defaultPing(host, ifname, timeoutMs));
+    const probeHost = deps.probeHost ?? EGRESS_PROBE_HOST;
     async function probePresence(ifname) {
-        return (await checkLinkUp(ifname).catch(() => false)) ? 'present' : 'absent';
+        return (await bounded(checkLinkUp(ifname), timeoutMs).catch(() => false))
+            ? 'present'
+            : 'absent';
     }
     async function checkHealth(ifname) {
         const presence = await probePresence(ifname);
-        const gateway = presence === 'present' ? await resolveGateway(ifname).catch(() => undefined) : undefined;
-        const gatewayReachable = gateway !== undefined && (await ping(gateway, ifname).catch(() => false));
-        const egressHealthy = gatewayReachable && (await ping(EGRESS_PROBE_HOST, ifname).catch(() => false));
-        return { presence, gatewayReachable, egressHealthy, observedAt: now() };
+        const failureKinds = [];
+        const gateway = presence === 'present'
+            ? await bounded(resolveGateway(ifname), timeoutMs).catch((error) => {
+                failureKinds.push(classifyRouterProbeFailure(error));
+                return undefined;
+            })
+            : undefined;
+        const gatewayReachable = gateway !== undefined &&
+            (await bounded(ping(gateway, ifname), timeoutMs).catch((error) => {
+                failureKinds.push(classifyRouterProbeFailure(error));
+                return false;
+            }));
+        const egressHealthy = gatewayReachable &&
+            (await bounded(ping(probeHost, ifname), timeoutMs).catch((error) => {
+                failureKinds.push(classifyRouterProbeFailure(error));
+                return false;
+            }));
+        const health = { presence, gatewayReachable, egressHealthy, observedAt: now() };
+        Object.defineProperty(health, 'failureKinds', { value: failureKinds, enumerable: true });
+        return health;
     }
     return { probePresence, checkHealth };
 }