@matter/nodejs-shell 0.17.9 → 0.18.0-alpha.0-20260812-4d7f2790e

package/src/shell/cmd_commission.ts

@@ -4,15 +4,23 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Diagnostic, Logger, MatterError } from "@matter/general";
+import { Diagnostic, ImplementationError, Logger, Seconds } from "@matter/general";
+import { ClientNode, CommissioningClient } from "@matter/node";
+import { BasicInformationClient } from "@matter/node/behaviors/basic-information";
+import { DescriptorClient } from "@matter/node/behaviors/descriptor";
 import { DiscoveryCapabilitiesSchema, ManualPairingCodeCodec, NodeId, QrCode, QrPairingCodeCodec } from "@matter/types";
-import { BasicInformation, Descriptor, GeneralCommissioning } from "@matter/types/clusters";
-import { NodeCommissioningOptions } from "@project-chip/matter.js";
+import { GeneralCommissioning } from "@matter/types/clusters";
 import type { Argv } from "yargs";
-import { createDiagnosticCallbacks, MatterNode } from "../MatterNode.js";
+import { MatterNode } from "../MatterNode.js";
+import { awaitSeeded } from "../util/awaitSeeded.js";
 
 const logger = Logger.get("Commission");
 
+/** Look up a commissioned peer by node id across the controller's default admin fabric. */
+function findCommissionedNode(theNode: MatterNode, nodeId: NodeId): ClientNode | undefined {
+    return theNode.node.peers.commissioned.find(peer => peer.peerAddress?.nodeId === nodeId);
+}
+
 export default function commands(theNode: MatterNode) {
     return {
         command: "commission",
@@ -23,9 +31,53 @@ export default function commands(theNode: MatterNode) {
                 .command("pair", "Pair with a matter device", yargs => {
                     return (
                         yargs
+                            // Options are registered before the command below so their types flow into its handler's argv.
+                            .options({
+                                pairingCode: {
+                                    describe: "pairing code",
+                                    default: undefined,
+                                    type: "string",
+                                },
+                                qrCode: {
+                                    describe: "QR code string (MT:...)",
+                                    default: undefined,
+                                    type: "string",
+                                },
+                                qrCodeIndex: {
+                                    describe: "Index of QR code entry if multiple (1..n)",
+                                    default: 1,
+                                    type: "number",
+                                },
+                                setupPinCode: {
+                                    describe: "setup pin code",
+                                    default: 20202021,
+                                    type: "number",
+                                },
+                                instanceId: {
+                                    alias: "i",
+                                    describe: "instance id",
+                                    type: "string",
+                                },
+                                discriminator: {
+                                    alias: "d",
+                                    description: "Long discriminator",
+                                    type: "number",
+                                },
+                                shortDiscriminator: {
+                                    alias: "s",
+                                    description: "Short discriminator",
+                                    type: "number",
+                                },
+                                ble: {
+                                    alias: "b",
+                                    description: "Also discover over BLE",
+                                    type: "boolean",
+                                    default: false,
+                                },
+                            })
                             // Pair
                             .command(
-                                "* [node-id] [ip:[port]]",
+                                "* [node-id] [ip] [port]",
                                 "Commission a matter device",
                                 yargs => {
                                     return yargs
@@ -46,17 +98,16 @@ export default function commands(theNode: MatterNode) {
                                         });
                                 },
                                 async argv => {
-                                    const {
-                                        pairingCode,
-                                        qrCode,
-                                        nodeId: nodeIdStr,
-                                        ipPort,
-                                        ip,
-                                        ble = false,
-                                        instanceId,
-                                    } = argv;
+                                    const { pairingCode, qrCode, nodeId: nodeIdStr, port, ip, ble, instanceId } = argv;
                                     let { setupPinCode, discriminator, shortDiscriminator, qrCodeIndex } = argv;
 
+                                    if ((ip === undefined) !== (port === undefined)) {
+                                        console.log(
+                                            "Known-address commissioning requires both <ip> and <port>; provide both or neither (to use discovery).",
+                                        );
+                                        return;
+                                    }
+
                                     if (typeof pairingCode === "string" && pairingCode.length > 0) {
                                         const { shortDiscriminator: pairingCodeShortDiscriminator, passcode } =
                                             ManualPairingCodeCodec.decode(pairingCode);
@@ -104,32 +155,6 @@ export default function commands(theNode: MatterNode) {
 
                                     const nodeId = nodeIdStr !== undefined ? NodeId(BigInt(nodeIdStr)) : undefined;
                                     await theNode.start();
-                                    if (theNode.commissioningController === undefined) {
-                                        throw new Error("CommissioningController not initialized");
-                                    }
-
-                                    const options = {
-                                        discovery: {
-                                            knownAddress:
-                                                ip !== undefined && ipPort !== undefined
-                                                    ? { ip, port: ipPort, type: "udp" }
-                                                    : undefined,
-                                            identifierData:
-                                                instanceId !== undefined
-                                                    ? { instanceId }
-                                                    : discriminator !== undefined
-                                                      ? { longDiscriminator: discriminator }
-                                                      : shortDiscriminator !== undefined
-                                                        ? { shortDiscriminator }
-                                                        : {},
-                                            discoveryCapabilities: {
-                                                ble,
-                                                onIpNetwork: true,
-                                            },
-                                        },
-                                        passcode: setupPinCode,
-                                        ...createDiagnosticCallbacks(),
-                                    } as NodeCommissioningOptions;
 
                                     // Attestation policy: strict rejects errors but allows warnings/info
                                     const strictAttestation = await theNode.Store.get<boolean>(
@@ -137,8 +162,12 @@ export default function commands(theNode: MatterNode) {
                                         false,
                                     );
 
-                                    options.commissioning = {
-                                        nodeId: nodeId !== undefined ? NodeId(nodeId) : undefined,
+                                    const commissioningOptions: CommissioningClient.CommissioningOptions = {
+                                        passcode: setupPinCode,
+                                        discriminator,
+                                        nodeId,
+                                        // The shell subscribes on demand via the `subscribe` command, not at commission.
+                                        autoSubscribe: false,
                                         regulatoryLocation: GeneralCommissioning.RegulatoryLocationType.Outdoor, // Set to the most restrictive if relevant
                                         regulatoryCountryCode: "XX",
                                         onAttestationFailure: findings => {
@@ -156,103 +185,82 @@ export default function commands(theNode: MatterNode) {
                                         },
                                     };
 
-                                    console.log(Diagnostic.json(options));
+                                    // Keep secrets out of the debug dump (CodeQL: clear-text logging of sensitive
+                                    // info). Omit the passcode entirely — spreading then overriding still flows it
+                                    // into the logged object — and mask network credentials.
+                                    const { passcode: _passcode, wifiNetwork, ...loggable } = commissioningOptions;
+                                    console.log(
+                                        Diagnostic.json({
+                                            ...loggable,
+                                            ...(wifiNetwork && {
+                                                wifiNetwork: { ...wifiNetwork, wifiCredentials: "<redacted>" },
+                                            }),
+                                        }),
+                                    );
 
                                     await theNode.certificateService();
 
                                     const wifiSsid = await theNode.Store.get<string>("WiFiSsid", "");
                                     const wifiCredentials = await theNode.Store.get<string>("WiFiPassword", "");
                                     if (wifiSsid.length > 0 && wifiCredentials.length > 0) {
-                                        options.commissioning.wifiNetwork = { wifiSsid, wifiCredentials };
+                                        commissioningOptions.wifiNetwork = { wifiSsid, wifiCredentials };
                                     }
                                     const threadOperationalDataset = await theNode.Store.get<string>(
                                         "ThreadOperationalDataset",
                                         "",
                                     );
                                     if (threadOperationalDataset.length > 0) {
-                                        options.commissioning.threadNetwork = {
+                                        commissioningOptions.threadNetwork = {
                                             networkName: await theNode.Store.get<string>("ThreadName", ""),
                                             operationalDataset: threadOperationalDataset,
                                         };
                                     }
 
-                                    const commissionedNodeId =
-                                        await theNode.commissioningController.commissionNode(options);
+                                    let node: ClientNode;
+                                    if (ip !== undefined && port !== undefined) {
+                                        // Known address: locate/create the peer node directly instead of running mDNS
+                                        // discovery. Mirrors MatterController's own known-address commissioning path.
+                                        node = await theNode.node.peers.forDescriptor({
+                                            addresses: [{ ip, port, type: "udp" }],
+                                        });
+                                        await node.commission(commissioningOptions);
+                                    } else {
+                                        const identifierData =
+                                            instanceId !== undefined
+                                                ? { instanceId }
+                                                : shortDiscriminator !== undefined
+                                                  ? { shortDiscriminator }
+                                                  : {};
+                                        node = await theNode.node.peers.commission({
+                                            ...identifierData,
+                                            ...commissioningOptions,
+                                            discoveryCapabilities: { ble, onIpNetwork: true },
+                                        });
+                                    }
 
-                                    console.log("Commissioned Node:", commissionedNodeId);
+                                    console.log("Commissioned Node:", node.peerAddress?.nodeId.toString());
 
-                                    const node = theNode.commissioningController.getPairedNode(commissionedNodeId);
-                                    if (node === undefined) {
-                                        // Should not happen
-                                        throw new MatterError("Node not found after commissioning.");
+                                    if (!(await awaitSeeded(node))) {
+                                        return;
                                     }
 
-                                    // Important: This is a temporary API to proof the methods working and this will change soon and is NOT stable!
-                                    // It is provided to proof the concept
-
-                                    // Example to initialize a ClusterClient and access concrete fields as API methods
-                                    const descriptor = node.getRootClusterClient(Descriptor);
+                                    // Example to read cluster state directly instead of via a ClusterClient
+                                    const descriptor = node.maybeStateOf(DescriptorClient);
                                     if (descriptor !== undefined) {
-                                        console.log(await descriptor.attributes.deviceTypeList.get()); // you can call that way
-                                        console.log(await descriptor.getServerListAttribute()); // or more convenient that way
+                                        console.log(descriptor.deviceTypeList);
+                                        console.log(descriptor.serverList);
                                     } else {
                                         console.log("No Descriptor Cluster found. This should never happen!");
                                     }
 
-                                    // Example to subscribe to a field and get the value
-                                    const info = node.getRootClusterClient(BasicInformation);
+                                    const info = node.maybeStateOf(BasicInformationClient);
                                     if (info !== undefined) {
-                                        console.log(await info.getProductNameAttribute()); // This call is executed remotely
-                                        //console.log(await info.subscribeProductNameAttribute(value => console.log("productName", value), 5, 30));
-                                        //console.log(await info.getProductNameAttribute()); // This call is resolved locally because we have subscribed to the value!
+                                        console.log(info.productName);
                                     } else {
                                         console.log("No BasicInformation Cluster found. This should never happen!");
                                     }
                                 },
                             )
-                            .options({
-                                pairingCode: {
-                                    describe: "pairing code",
-                                    default: undefined,
-                                    type: "string",
-                                },
-                                qrCode: {
-                                    describe: "QR code string (MT:...)",
-                                    default: undefined,
-                                    type: "string",
-                                },
-                                qrCodeIndex: {
-                                    describe: "Index of QR code entry if multiple (1..n)",
-                                    default: 1,
-                                    type: "number",
-                                },
-                                setupPinCode: {
-                                    describe: "setup pin code",
-                                    default: 20202021,
-                                    type: "number",
-                                },
-                                instanceId: {
-                                    alias: "i",
-                                    describe: "instance id",
-                                    type: "string",
-                                },
-                                discriminator: {
-                                    alias: "d",
-                                    description: "Long discriminator",
-                                    type: "number",
-                                },
-                                shortDiscriminator: {
-                                    alias: "s",
-                                    description: "Short discriminator",
-                                    type: "number",
-                                },
-                                ble: {
-                                    alias: "b",
-                                    description: "Also discover over BLE",
-                                    type: "boolean",
-                                    default: false,
-                                },
-                            })
                     );
                 })
                 .command(
@@ -275,8 +283,11 @@ export default function commands(theNode: MatterNode) {
                         const { nodeId, timeout } = argv;
                         await theNode.start();
                         const node = (await theNode.connectAndGetNodes(nodeId, { autoSubscribe: false }))[0];
+                        if (!(await awaitSeeded(node))) {
+                            return;
+                        }
 
-                        await node.openBasicCommissioningWindow(timeout);
+                        await node.openBasicCommissioningWindow(Seconds(timeout));
 
                         console.log(`Basic Commissioning Window for node ${nodeId} opened`);
                     },
@@ -301,10 +312,14 @@ export default function commands(theNode: MatterNode) {
                         await theNode.start();
                         const { nodeId, timeout } = argv;
                         const node = (await theNode.connectAndGetNodes(nodeId, { autoSubscribe: false }))[0];
-                        const data = await node.openEnhancedCommissioningWindow(timeout);
+                        if (!(await awaitSeeded(node))) {
+                            return;
+                        }
+                        const { qrPairingCode, manualPairingCode } = await node.openEnhancedCommissioningWindow(
+                            Seconds(timeout),
+                        );
 
                         console.log(`Enhanced Commissioning Window for node ${nodeId} opened`);
-                        const { qrPairingCode, manualPairingCode } = data;
 
                         console.log(QrCode.get(qrPairingCode));
                         console.log(
@@ -333,11 +348,19 @@ export default function commands(theNode: MatterNode) {
                     },
                     async argv => {
                         await theNode.start();
-                        const { nodeId, force } = argv;
+                        const { nodeId: nodeIdStr, force } = argv;
                         if (force) {
-                            await theNode.controller.removeNode(NodeId(BigInt(nodeId)), !force);
+                            // Force: skip the on-device decommission attempt and just drop the peer locally.
+                            const node = findCommissionedNode(theNode, NodeId(BigInt(nodeIdStr)));
+                            if (node === undefined) {
+                                throw new ImplementationError(`Node ${nodeIdStr} not commissioned`);
+                            }
+                            await node.delete();
                         } else {
-                            const node = (await theNode.connectAndGetNodes(nodeId, { autoSubscribe: false }))[0];
+                            const node = (await theNode.connectAndGetNodes(nodeIdStr, { autoSubscribe: false }))[0];
+                            if (!(await awaitSeeded(node))) {
+                                return;
+                            }
                             await node.decommission();
                         }
                     },

package/src/shell/cmd_discover.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Diagnostic, Seconds } from "@matter/general";
+import { ChannelType, Diagnostic, Seconds } from "@matter/general";
 import { CommissionableDeviceIdentifiers } from "@matter/protocol";
 import { ManualPairingCodeCodec, VendorId } from "@matter/types";
 import type { Argv } from "yargs";
@@ -88,9 +88,6 @@ export default function commands(theNode: MatterNode) {
                         }
 
                         await theNode.start();
-                        if (theNode.commissioningController === undefined) {
-                            throw new Error("CommissioningController not initialized");
-                        }
 
                         const identifierData: CommissionableDeviceIdentifiers =
                             discriminator !== undefined
@@ -111,25 +108,42 @@ export default function commands(theNode: MatterNode) {
                             )} for ${once ? "first match or " : ""}${timeoutSeconds} seconds.`,
                         );
 
-                        const results = await theNode.commissioningController.discoverCommissionableDevices(
-                            identifierData,
-                            {
-                                ble,
-                                onIpNetwork: true,
-                            },
-                            device => {
-                                console.log(`Discovered device ${Diagnostic.json(device)}`);
-                                if (once) {
-                                    theNode.commissioningController?.cancelCommissionableDeviceDiscovery(
-                                        identifierData,
-                                        { ble, onIpNetwork: true },
-                                    );
-                                }
-                            },
-                            Seconds(timeoutSeconds),
-                        );
+                        // scannerFilter mirrors the discoveryCapabilities->filter mapping in CommissioningDiscovery.
+                        const discovery = theNode.node.peers.discover({
+                            ...identifierData,
+                            timeout: Seconds(timeoutSeconds),
+                            scannerFilter: scanner =>
+                                scanner.type === ChannelType.UDP || (ble && scanner.type === ChannelType.BLE),
+                        });
+                        // A re-advertising device fires `discovered` again for the same node; dedupe by its
+                        // canonical identity so the log doesn't spam duplicate lines.
+                        const seen = new Set<string>();
+                        discovery.discovered.on(node => {
+                            const { deviceIdentifier, addresses } = node.state.commissioning;
+                            // Prefer the stable device identifier; the address fallback is sorted so re-advertisement
+                            // in a different order does not read as a new device (ServerAddress carries no volatile fields).
+                            const id =
+                                deviceIdentifier ||
+                                (addresses ?? [])
+                                    .map(a => JSON.stringify(a))
+                                    .sort()
+                                    .join("|");
+                            if (seen.has(id)) {
+                                return;
+                            }
+                            seen.add(id);
+                            console.log(`Discovered device ${Diagnostic.json(node.state.commissioning)}`);
+                            if (once) {
+                                discovery.stop();
+                            }
+                        });
+
+                        const results = await discovery;
 
-                        console.log(`Discovered ${results.length} devices`, results);
+                        console.log(
+                            `Discovered ${results.length} devices`,
+                            results.map(node => node.state.commissioning),
+                        );
                     },
                 ),
         handler: async (argv: any) => {

package/src/shell/cmd_icd.ts

@@ -4,22 +4,26 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Duration, Millis, ObserverGroup } from "@matter/general";
-import { IcdClient, IcdMultiAdminError } from "@matter/node";
+import { Duration, ImplementationError, Millis, ObserverGroup } from "@matter/general";
+import { ClientNode, IcdClient, IcdMultiAdminError, NodeConnectionState } from "@matter/node";
 import { IcdManagementClient } from "@matter/node/behaviors/icd-management";
 import { NodeId, SubjectId, VendorId } from "@matter/types";
 import { IcdManagement } from "@matter/types/clusters/icd-management";
-import { NodeStates, PairedNode } from "@project-chip/matter.js/device";
 import type { Argv } from "yargs";
 import { MatterNode } from "../MatterNode.js";
+import { awaitSeeded } from "../util/awaitSeeded.js";
 
 const watchers = new Map<string, ObserverGroup>();
 
-async function printStatus(paired: PairedNode) {
-    const clientNode = paired.node;
+/** Look up a commissioned peer by node id without connecting or awaiting remote initialization. */
+function findCommissionedNode(theNode: MatterNode, nodeId: NodeId): ClientNode | undefined {
+    return theNode.node.peers.commissioned.find(peer => peer.peerAddress?.nodeId === nodeId);
+}
+
+async function printStatus(nodeId: NodeId, clientNode: ClientNode) {
     if (!clientNode.behaviors.has(IcdClient)) {
-        if (!paired.initialized) {
-            console.log(`node ${paired.nodeId}: uninitialized (no cached data yet)`);
+        if (!clientNode.lifecycle.isSeeded) {
+            console.log(`node ${nodeId}: uninitialized (no cached data yet)`);
         }
         return;
     }
@@ -31,10 +35,10 @@ async function printStatus(paired: PairedNode) {
         mgmt === undefined
             ? "n/a"
             : (IcdManagement.OperatingMode[mgmt.operatingMode ?? -1] ?? mgmt.operatingMode ?? "unknown");
-    const marker = paired.initialized ? "" : " [uninitialized]";
+    const marker = clientNode.lifecycle.isSeeded ? "" : " [uninitialized]";
     console.log(
         [
-            `node ${paired.nodeId}:${marker}`,
+            `node ${nodeId}:${marker}`,
             `  registered=${icd.registered}`,
             `  available=${icd.available}`,
             `  awake=${awake}`,
@@ -58,7 +62,12 @@ function selectsAll(nodeIdStr: string) {
 /** Resolve a node-id argument to concrete ids: `all` expands to every commissioned node, otherwise a single id. */
 async function targetNodeIds(theNode: MatterNode, nodeIdStr: string): Promise<NodeId[]> {
     await theNode.start();
-    return selectsAll(nodeIdStr) ? theNode.controller.getCommissionedNodes() : [NodeId(BigInt(nodeIdStr))];
+    if (!selectsAll(nodeIdStr)) {
+        return [NodeId(BigInt(nodeIdStr))];
+    }
+    return theNode.node.peers.commissioned
+        .map(peer => peer.peerAddress?.nodeId)
+        .filter((nodeId): nodeId is NodeId => nodeId !== undefined);
 }
 
 /**
@@ -84,19 +93,20 @@ async function eachNode(theNode: MatterNode, nodeIdStr: string, action: (nodeId:
     }
 }
 
-async function pairedNodeFor(theNode: MatterNode, nodeId: NodeId) {
-    const paired = (await theNode.connectAndGetNodes(String(nodeId)))[0];
-    if (paired === undefined) {
-        throw new Error(`Node ${nodeId} not found / not connected`);
+/** Connect to `nodeId` and verify it exposes IcdManagement, throwing an {@link ImplementationError} otherwise. */
+async function connectedIcdNode(theNode: MatterNode, nodeId: NodeId): Promise<ClientNode> {
+    const clientNode = (await theNode.connectAndGetNodes(String(nodeId)))[0];
+    if (clientNode === undefined) {
+        throw new ImplementationError(`Node ${nodeId} not found / not connected`);
     }
-    if (!paired.node.behaviors.has(IcdClient)) {
-        throw new Error(`Node ${nodeId} is not an ICD device (no IcdManagement cluster)`);
+    // Behaviors populate as part of seeding; await it so a not-yet-seeded peer isn't misread as non-ICD.
+    if (!(await awaitSeeded(clientNode, { quiet: true }))) {
+        throw new ImplementationError(`Node ${nodeId} did not become ready (offline?)`);
     }
-    return paired;
-}
-
-async function clientNodeFor(theNode: MatterNode, nodeId: NodeId) {
-    return (await pairedNodeFor(theNode, nodeId)).node;
+    if (!clientNode.behaviors.has(IcdClient)) {
+        throw new ImplementationError(`Node ${nodeId} is not an ICD device (no IcdManagement cluster)`);
+    }
+    return clientNode;
 }
 
 function stopWatch(nodeIdStr: string) {
@@ -120,8 +130,7 @@ async function startWatch(theNode: MatterNode, nodeId: NodeId) {
     watchers.get(key)?.close();
     watchers.delete(key);
 
-    const paired = await pairedNodeFor(theNode, nodeId);
-    const clientNode = paired.node;
+    const clientNode = await connectedIcdNode(theNode, nodeId);
     const observers = new ObserverGroup();
     const stamp = (msg: string) => console.log(`[icd ${nodeId}] ${msg}`);
     // Event emitters discard emit()'s promise, so a rejection from this async read must not escape.
@@ -145,10 +154,12 @@ async function startWatch(theNode: MatterNode, nodeId: NodeId) {
     observers.on(events.checkInMissed, async () => stamp(`check-in MISSED ${await wakefulnessSuffix()}`));
     observers.on(events.keyRefreshed, () => stamp("key refreshed"));
     observers.on(events.available$Changed, (value: boolean) => stamp(`available=${value}`));
-    observers.on(paired.events.stateChanged, state => stamp(`connection=${NodeStates[state] ?? state}`));
+    observers.on(clientNode.lifecycle.connectionStateChanged, state =>
+        stamp(`connection=${NodeConnectionState[state] ?? state}`),
+    );
     watchers.set(key, observers);
     // Drop the watcher when the node goes away so it doesn't leak in the map.
-    clientNode.lifecycle.destroyed.once(() => {
+    observers.on(clientNode.lifecycle.destroyed, () => {
         watchers.get(key)?.close();
         watchers.delete(key);
     });
@@ -198,7 +209,7 @@ export default function commands(theNode: MatterNode) {
                             ignoredVendors: argv.ignoreVendor?.map((v: string | number) => VendorId(Number(v))),
                         };
                         await eachNode(theNode, argv.nodeId, async nodeId => {
-                            const clientNode = await clientNodeFor(theNode, nodeId);
+                            const clientNode = await connectedIcdNode(theNode, nodeId);
                             try {
                                 await clientNode.act(agent => agent.get(IcdClient).register(options));
                                 console.log(`Registered as Check-In client on node ${nodeId}`);
@@ -235,9 +246,14 @@ export default function commands(theNode: MatterNode) {
                             if (argv.force) {
                                 // A registered-but-unreachable LIT peer parks every connecting/peer-I/O path on its
                                 // never-coming Check-In; reach it via the non-connecting accessor and forget() locally.
-                                const clientNode = (await theNode.controller.getNode(nodeId)).node;
+                                const clientNode = findCommissionedNode(theNode, nodeId);
+                                if (clientNode === undefined) {
+                                    throw new ImplementationError(`Node ${nodeId} is not commissioned`);
+                                }
                                 if (!clientNode.behaviors.has(IcdClient)) {
-                                    throw new Error(`Node ${nodeId} is not an ICD device (no IcdManagement cluster)`);
+                                    throw new ImplementationError(
+                                        `Node ${nodeId} is not an ICD device (no IcdManagement cluster)`,
+                                    );
                                 }
                                 await clientNode.act(agent => agent.get(IcdClient).forget());
                                 console.log(
@@ -245,7 +261,7 @@ export default function commands(theNode: MatterNode) {
                                 );
                                 return;
                             }
-                            const clientNode = await clientNodeFor(theNode, nodeId);
+                            const clientNode = await connectedIcdNode(theNode, nodeId);
                             await clientNode.act(agent => agent.get(IcdClient).unregister());
                             console.log(`Unregistered Check-In client on node ${nodeId}`);
                         });
@@ -269,7 +285,7 @@ export default function commands(theNode: MatterNode) {
                             }),
                     handler: async (argv: any) => {
                         await eachNode(theNode, argv.nodeId, async nodeId => {
-                            const clientNode = await clientNodeFor(theNode, nodeId);
+                            const clientNode = await connectedIcdNode(theNode, nodeId);
                             const promised = await clientNode.act(agent =>
                                 agent.get(IcdClient).stayActive(Millis(argv.durationMs)),
                             );
@@ -283,7 +299,7 @@ export default function commands(theNode: MatterNode) {
                     builder: (y: Argv) =>
                         y.positional("node-id", { describe: "node id, or 'all'", type: "string", demandOption: true }),
                     handler: async (argv: any) => {
-                        // getNode() never awaits remote init, unlike connectAndGetNodes(), so a peer stuck mid-read can't hang this command.
+                        // findCommissionedNode never connects/awaits remote init, so a peer stuck mid-read can't hang this command.
                         const nodeIds = await targetNodeIds(theNode, argv.nodeId);
                         if (nodeIds.length === 0) {
                             console.log("No commissioned nodes.");
@@ -292,7 +308,11 @@ export default function commands(theNode: MatterNode) {
                         // Diagnostic command: report an unreachable node inline rather than aborting, even for a single id.
                         for (const nodeId of nodeIds) {
                             try {
-                                await printStatus(await theNode.controller.getNode(nodeId));
+                                const clientNode = findCommissionedNode(theNode, nodeId);
+                                if (clientNode === undefined) {
+                                    throw new ImplementationError(`Node ${nodeId} is not commissioned`);
+                                }
+                                await printStatus(nodeId, clientNode);
                             } catch (e) {
                                 console.log(
                                     `node ${nodeId}: unavailable (${e instanceof Error ? e.message : String(e)})`,