iOS/Gateway: harden pairing resolution and settings-driven capability refresh (#22120)

Merged via /review-pr -> /prepare-pr -> /merge-pr.

Prepared head SHA: 55b8a93a999b7458c98f9d3b31abbd3665929b31
Co-authored-by: mbelinky <132747814+mbelinky@users.noreply.github.com>
Co-authored-by: mbelinky <132747814+mbelinky@users.noreply.github.com>
Reviewed-by: @mbelinky

src/shared/node-match.ts

@@ -2,6 +2,7 @@ export type NodeMatchCandidate = {
   nodeId: string;
   displayName?: string;
   remoteIp?: string;
+  connected?: boolean;
 };
 
 export function normalizeNodeKey(value: string) {
@@ -53,14 +54,23 @@ export function resolveNodeIdFromCandidates(nodes: NodeMatchCandidate[], query:
     throw new Error("node required");
   }
 
-  const matches = resolveNodeMatches(nodes, q);
-  if (matches.length === 1) {
-    return matches[0]?.nodeId ?? "";
+  const rawMatches = resolveNodeMatches(nodes, q);
+  if (rawMatches.length === 1) {
+    return rawMatches[0]?.nodeId ?? "";
   }
-  if (matches.length === 0) {
+  if (rawMatches.length === 0) {
     const known = listKnownNodes(nodes);
     throw new Error(`unknown node: ${q}${known ? ` (known: ${known})` : ""}`);
   }
+
+  // Re-pair/reinstall flows can leave multiple nodes with the same display name.
+  // Prefer a unique connected match when available.
+  const connectedMatches = rawMatches.filter((match) => match.connected === true);
+  const matches = connectedMatches.length > 0 ? connectedMatches : rawMatches;
+  if (matches.length === 1) {
+    return matches[0]?.nodeId ?? "";
+  }
+
   throw new Error(
     `ambiguous node: ${q} (matches: ${matches
       .map((n) => n.displayName || n.remoteIp || n.nodeId)

src/shared/shared-misc.test.ts

@@ -124,4 +124,28 @@ describe("resolveNodeIdFromCandidates", () => {
       resolveNodeIdFromCandidates([{ nodeId: "mac-abcdef" }, { nodeId: "mac-abc999" }], "mac-abc"),
     ).toThrow(/ambiguous node: mac-abc.*matches:/);
   });
+
+  it("prefers a unique connected node when names are duplicated", () => {
+    expect(
+      resolveNodeIdFromCandidates(
+        [
+          { nodeId: "ios-old", displayName: "iPhone", connected: false },
+          { nodeId: "ios-live", displayName: "iPhone", connected: true },
+        ],
+        "iphone",
+      ),
+    ).toBe("ios-live");
+  });
+
+  it("stays ambiguous when multiple connected nodes match", () => {
+    expect(() =>
+      resolveNodeIdFromCandidates(
+        [
+          { nodeId: "ios-a", displayName: "iPhone", connected: true },
+          { nodeId: "ios-b", displayName: "iPhone", connected: true },
+        ],
+        "iphone",
+      ),
+    ).toThrow(/ambiguous node: iphone.*matches:/);
+  });
 });