kiku-agent 1.3.2 → 1.3.4

package/server/agent/tests/lanInterfaces.test.js

@@ -0,0 +1,510 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  clearLanScanCache,
+  classifyScanToken,
+  describeLanInterface,
+  describeLanScanAge,
+  enrichLinuxInterfaces,
+  enrichMacInterfaces,
+  enrichWindowsInterfaces,
+  expandCidrToHosts,
+  getLanCandidateSubnets,
+  inferInterfaceType,
+  listLanInterfaces,
+  loadLanState,
+  netmaskFromPrefix,
+  netmaskToPrefix,
+  networkCidr,
+  parseLanScanArgs,
+  parseLinuxDefaultRoutes,
+  parseLinuxIpAddr,
+  parseLinuxIpAddrText,
+  parseMacDefaultRoute,
+  parseMacHardwarePorts,
+  parseMacIfconfig,
+  parseWindowsAdapters,
+  parseWindowsDefaultRoutes,
+  pickLanEndpointModel,
+  prefixFromEntry,
+  resolveScanSubnets,
+  saveLanState,
+  scanLan,
+  usableHostCount,
+} from '../lanDiscovery.js';
+import { getSettingsHtml } from '../../web-chat/ui/settingsBuilder.js';
+import { COMMAND_NAMES } from '../commandRegistry.js';
+
+test('netmask helpers convert between masks, prefixes, and network CIDRs', () => {
+  assert.equal(netmaskToPrefix('255.255.255.0'), 24);
+  assert.equal(netmaskToPrefix('255.255.240.0'), 20);
+  assert.equal(netmaskToPrefix('255.0.0.0'), 8);
+  assert.equal(netmaskToPrefix('255.0.255.0'), null);
+  assert.equal(netmaskToPrefix('bogus'), null);
+  assert.equal(netmaskFromPrefix(24), '255.255.255.0');
+  assert.equal(netmaskFromPrefix(20), '255.255.240.0');
+  assert.equal(networkCidr('192.168.5.77', 20), '192.168.0.0/20');
+  assert.equal(networkCidr('10.1.2.3', 8), '10.0.0.0/8');
+  assert.equal(usableHostCount(24), 254);
+  assert.equal(usableHostCount(31), 2);
+  assert.equal(usableHostCount(32), 1);
+  assert.equal(prefixFromEntry({ netmask: '255.255.255.0' }), 24);
+  assert.equal(prefixFromEntry({ cidr: '10.0.0.5/16' }), 16);
+  assert.equal(prefixFromEntry({}), 24);
+});
+
+test('getLanCandidateSubnets honors real netmasks instead of forcing /24', () => {
+  const subnets = getLanCandidateSubnets({
+    eth0: [{ address: '10.20.30.40', netmask: '255.255.0.0', family: 'IPv4', internal: false }],
+    wlan0: [{ address: '192.168.7.9', netmask: '255.255.254.0', family: 'IPv4', internal: false }],
+    legacy: [{ address: '192.168.9.9', family: 'IPv4', internal: false }],
+    lo: [{ address: '127.0.0.1', family: 'IPv4', internal: true }],
+  });
+  const byCidr = new Map(subnets.map(s => [s.cidr, s]));
+  assert.equal(byCidr.get('10.20.0.0/16')?.prefix, 16);
+  assert.equal(byCidr.get('10.20.0.0/16')?.hostCount, 65534);
+  assert.equal(byCidr.get('192.168.6.0/23')?.prefix, 23);
+  assert.equal(byCidr.get('192.168.9.0/24')?.prefix, 24);
+  assert.equal(subnets.length, 3);
+});
+
+test('expandCidrToHosts honors the prefix and refuses absurd ranges', () => {
+  assert.deepEqual(expandCidrToHosts('10.0.0.0/30'), ['10.0.0.1', '10.0.0.2']);
+  assert.deepEqual(expandCidrToHosts('10.0.0.4/31'), ['10.0.0.4', '10.0.0.5']);
+  assert.equal(expandCidrToHosts('192.168.5.0/23').length, 510);
+  assert.throws(() => expandCidrToHosts('10.0.0.0/8'), /cap 65,536/);
+  assert.throws(() => expandCidrToHosts('not-a-cidr'), /Invalid CIDR/);
+});
+
+test('inferInterfaceType classifies common adapter names', () => {
+  assert.equal(inferInterfaceType('Wi-Fi', ''), 'wifi');
+  assert.equal(inferInterfaceType('wlp2s0', ''), 'wifi');
+  assert.equal(inferInterfaceType('Ethernet', ''), 'ethernet');
+  assert.equal(inferInterfaceType('eno1', ''), 'ethernet');
+  assert.equal(inferInterfaceType('docker0', ''), 'virtual');
+  assert.equal(inferInterfaceType('ZeroTier One [abc]', ''), 'virtual');
+  assert.equal(inferInterfaceType('vEthernet (Default Switch)', ''), 'virtual');
+  assert.equal(inferInterfaceType('utun3', ''), 'virtual');
+  assert.equal(inferInterfaceType('lo', ''), 'loopback');
+  assert.equal(inferInterfaceType('lo', ''), 'loopback');
+  assert.equal(inferInterfaceType('lo0', ''), 'loopback');
+  assert.equal(inferInterfaceType('en0', ''), 'unknown');
+  assert.equal(inferInterfaceType('Local Area Connection* 9', ''), 'virtual');
+  assert.equal(inferInterfaceType('local area network', ''), 'unknown');
+});
+
+test('Windows adapter and route parsers handle PowerShell JSON shapes', () => {
+  const adapters = parseWindowsAdapters(JSON.stringify([
+    { Name: 'Wi-Fi', InterfaceDescription: 'Intel Wi-Fi 6', Status: 'Up', LinkSpeed: '866.7 Mbps', MediaType: '802.11', InterfaceIndex: 7 },
+    { Name: 'Ethernet', Status: 'Disconnected', MediaType: '802.3', InterfaceIndex: 3 },
+  ]));
+  assert.equal(adapters.length, 2);
+  assert.equal(adapters[0].status, 'up');
+  assert.equal(adapters[1].status, 'down');
+
+  const single = parseWindowsAdapters(JSON.stringify({ Name: 'Wi-Fi', Status: 'Up', InterfaceIndex: 7 }));
+  assert.equal(single.length, 1);
+
+  const routes = parseWindowsDefaultRoutes(JSON.stringify([
+    { InterfaceIndex: 7, NextHop: '192.168.1.1', RouteMetric: 25 },
+    { InterfaceIndex: 3, NextHop: '10.0.0.1', RouteMetric: 5 },
+  ]));
+  assert.equal(routes.length, 2);
+  assert.equal(parseWindowsAdapters('not json').length, 0);
+});
+
+test('Linux ip parsers extract operstate and default gateways', () => {
+  const links = parseLinuxIpAddr(JSON.stringify([
+    { ifname: 'wlp2s0', operstate: 'UP', address: 'aa:bb:cc:dd:ee:ff', mtu: 1500 },
+    { ifname: 'eth0', operstate: 'DOWN' },
+  ]));
+  assert.equal(links[0].status, 'up');
+  assert.equal(links[1].status, 'down');
+
+  const routes = parseLinuxDefaultRoutes(JSON.stringify([
+    { gateway: '192.168.1.1', dev: 'wlp2s0', metric: 600 },
+    { gateway: '10.0.0.1', dev: 'eth0', metric: 100 },
+  ]));
+  assert.equal(routes[0].device, 'wlp2s0');
+});
+
+test('macOS parsers read hardware ports, default route, and ifconfig state', () => {
+  const ports = parseMacHardwarePorts('Hardware Port: Wi-Fi\nDevice: en0\nEthernet Address: aa:bb\n\nHardware Port: Thunderbolt Ethernet\nDevice: en5\n');
+  assert.deepEqual(ports.map(p => p.device), ['en0', 'en5']);
+
+  const route = parseMacDefaultRoute('route to: default\ngateway: 192.168.1.1\ninterface: en0\n');
+  assert.equal(route.gateway, '192.168.1.1');
+  assert.equal(route.device, 'en0');
+
+  const states = parseMacIfconfig('en0: flags=8863<UP,BROADCAST,SMART,RUNNING,SIMPLEX,MULTICAST> mtu 1500\n\tstatus: active\n\tmedia: autoselect\nlo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384\n');
+  assert.equal(states.get('en0').status, 'up');
+  assert.ok(!states.has('lo0') || states.get('lo0').status === 'up');
+});
+
+const fixtureInterfaces = {
+  eth0: [{ address: '192.168.10.5', netmask: '255.255.255.0', family: 'IPv4', internal: false, mac: 'aa:bb:cc:dd:ee:01' }],
+  wlp2s0: [{ address: '192.168.1.20', netmask: '255.255.255.0', family: 'IPv4', internal: false, mac: 'aa:bb:cc:dd:ee:02' }],
+  lo: [{ address: '127.0.0.1', netmask: '255.0.0.0', family: 'IPv4', internal: true, mac: '00:00:00:00:00:00' }],
+  'Wi-Fi': [{ address: '192.168.1.50', netmask: '255.255.255.0', family: 'IPv4', internal: false, mac: 'aa:bb:cc:dd:ee:03' }],
+  'vEthernet (WSL)': [{ address: '172.30.0.1', netmask: '255.255.240.0', family: 'IPv4', internal: false, mac: 'aa:bb:cc:dd:ee:04' }],
+};
+
+test('listLanInterfaces builds a selectable baseline without OS commands', async () => {
+  const list = await listLanInterfaces({ interfaces: fixtureInterfaces, platform: 'none' });
+  assert.equal(list.length, 5);
+  assert.deepEqual(list.map(i => i.index), [0, 1, 2, 3, 4]);
+  assert.equal(list[0].name, 'eth0');
+  assert.equal(list[0].type, 'ethernet');
+  assert.equal(list[0].addresses[0].cidr, '192.168.10.0/24');
+  assert.equal(list[2].internal, true);
+});
+
+test('Windows enrichment resolves wifi type, status, and the default gateway', async () => {
+  const baseline = await listLanInterfaces({ interfaces: fixtureInterfaces, platform: 'none' });
+  const execFn = async (cmd, args) => {
+    assert.equal(cmd, 'powershell.exe');
+    return JSON.stringify({
+      adapters: [
+        { Name: 'eth0', Status: 'Up', MediaType: '802.3', InterfaceIndex: 11 },
+        { Name: 'wlp2s0', Status: 'Up', MediaType: '802.11', InterfaceIndex: 22 },
+      ],
+      routes: [{ InterfaceIndex: 22, NextHop: '192.168.1.1', RouteMetric: 25 }],
+    });
+  };
+  const enriched = await enrichWindowsInterfaces(baseline, execFn);
+  const wifi = enriched.find(i => i.name === 'wlp2s0');
+  assert.equal(wifi.type, 'wifi');
+  assert.equal(wifi.status, 'up');
+  assert.equal(wifi.gateway, '192.168.1.1');
+  assert.equal(wifi.isDefaultRoute, true);
+  assert.equal(enriched.find(i => i.name === 'eth0').isDefaultRoute, false);
+});
+
+test('Linux enrichment marks operstate and default route device', async () => {
+  const baseline = await listLanInterfaces({ interfaces: fixtureInterfaces, platform: 'none' });
+  const execFn = async (cmd, args) => {
+    if (cmd === 'ip' && args[1] === 'addr') {
+      return JSON.stringify([
+        { ifname: 'wlp2s0', operstate: 'UP' },
+        { ifname: 'eth0', operstate: 'DOWN' },
+      ]);
+    }
+    return JSON.stringify([{ gateway: '192.168.1.1', dev: 'wlp2s0', metric: 600 }]);
+  };
+  const enriched = await enrichLinuxInterfaces(baseline, execFn);
+  assert.equal(enriched.find(i => i.name === 'wlp2s0').status, 'up');
+  assert.equal(enriched.find(i => i.name === 'eth0').status, 'down');
+  assert.equal(enriched.find(i => i.name === 'wlp2s0').isDefaultRoute, true);
+});
+
+test('macOS enrichment maps friendly port names and active state', async () => {
+  const macFixture = {
+    en0: [{ address: '192.168.1.30', netmask: '255.255.255.0', family: 'IPv4', internal: false, mac: 'aa:bb:cc:dd:ee:ff' }],
+  };
+  const baseline = await listLanInterfaces({ interfaces: macFixture, platform: 'none' });
+  const execFn = async (cmd) => {
+    if (cmd === 'ifconfig') return 'en0: flags=8863<UP,BROADCAST,SMART,RUNNING> mtu 1500\n\tstatus: active\n\tmedia: autoselect (1000baseT <full-duplex>)\n';
+    if (cmd === 'route') return 'route to: default\ngateway: 192.168.1.1\ninterface: en0\n';
+    return 'Hardware Port: Wi-Fi\nDevice: en0\nEthernet Address: aa:bb\n';
+  };
+  const enriched = await enrichMacInterfaces(baseline, execFn);
+  assert.equal(enriched[0].displayName, 'Wi-Fi (en0)');
+  assert.equal(enriched[0].gateway, '192.168.1.1');
+  assert.equal(enriched[0].isDefaultRoute, true);
+});
+
+test('resolveScanSubnets selects subnets by index, name, or direct CIDR', async () => {
+  const opts = { interfaces: fixtureInterfaces, platform: 'none' };
+  assert.deepEqual(await resolveScanSubnets({ ...opts, iface: '1' }), ['192.168.1.0/24']);
+  assert.deepEqual(await resolveScanSubnets({ ...opts, iface: 'eth0' }), ['192.168.10.0/24']);
+  assert.deepEqual(await resolveScanSubnets({ ...opts, iface: 'ETH0' }), ['192.168.10.0/24']);
+  assert.deepEqual(await resolveScanSubnets({ ...opts, iface: '10.9.0.0/16' }), ['10.9.0.0/16']);
+  assert.equal(await resolveScanSubnets({ ...opts, iface: null }), null);
+  assert.equal(await resolveScanSubnets({ ...opts, iface: 'auto' }), null);
+  assert.deepEqual(await resolveScanSubnets({ ...opts, iface: 'eth0', subnets: ['10.1.0.0/24'] }), ['10.1.0.0/24']);
+  await assert.rejects(() => resolveScanSubnets({ ...opts, iface: 'nope' }), /Unknown LAN interface/);
+  await assert.rejects(() => resolveScanSubnets({ ...opts, iface: 'lo' }), /internal\/loopback/);
+});
+
+const WSL_IP_ADDR = `1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
+    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+    inet 127.0.0.1/8 scope host lo
+       valid_lft forever preferred_lft forever
+    inet 10.255.255.254/32 brd 10.255.255.254 scope global lo
+       valid_lft forever preferred_lft forever
+    inet6 ::1/128 scope host proto kernel_lo
+       valid_lft forever preferred_lft forever
+2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
+    link/ether 00:15:5d:14:58:0a brd ff:ff:ff:ff:ff:ff
+    inet 172.30.12.205/20 brd 172.30.15.255 scope global eth0
+       valid_lft forever preferred_lft forever
+    inet6 fe80::215:5dff:fe14:580a/64 scope link proto kernel_ll
+       valid_lft forever preferred_lft forever
+`;
+
+test('Linux plain-text ip addr fallback parses real WSL output', () => {
+  const links = parseLinuxIpAddrText(WSL_IP_ADDR);
+  assert.equal(links.length, 2);
+  assert.equal(links[0].name, 'lo');
+  assert.equal(links[0].status, 'up');
+  assert.equal(links[1].name, 'eth0');
+  assert.equal(links[1].status, 'up');
+  assert.equal(links[1].mac, '00:15:5d:14:58:0a');
+  assert.equal(links[1].mtu, 1500);
+  assert.deepEqual(parseLinuxIpAddrText(''), []);
+});
+
+test('Linux UNKNOWN operstate with UP flags still counts as up', () => {
+  const fromJson = parseLinuxIpAddr(JSON.stringify([
+    { ifname: 'lo', operstate: 'UNKNOWN', flags: ['LOOPBACK', 'UP', 'LOWER_UP'] },
+    { ifname: 'eth0', operstate: 'UNKNOWN', flags: ['BROADCAST', 'MULTICAST'] },
+  ]));
+  assert.equal(fromJson[0].status, 'up');
+  assert.equal(fromJson[1].status, 'unknown');
+
+  const fromText = parseLinuxIpAddrText('3: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 state DOWN\n    inet 172.17.0.1/16 scope global docker0\n');
+  assert.equal(fromText[0].status, 'down');
+});
+
+test('Linux enrichment falls back to plain ip addr when -j is unavailable', async () => {
+  const baseline = await listLanInterfaces({
+    interfaces: {
+      eth0: [{ address: '172.30.12.205', netmask: '255.255.240.0', family: 'IPv4', internal: false }],
+    },
+    platform: 'none',
+  });
+  const execFn = async (cmd, args) => {
+    if (args[0] === '-j') throw new Error('ip: Option "-j" is unknown');
+    if (args[0] === 'addr') return WSL_IP_ADDR;
+    return '[]';
+  };
+  const enriched = await enrichLinuxInterfaces(baseline, execFn);
+  assert.equal(enriched[0].status, 'up');
+  assert.equal(enriched[0].mac, '00:15:5d:14:58:0a');
+});
+
+test('Windows enrichment lists disconnected adapters missing from Node', async () => {
+  const baseline = await listLanInterfaces({
+    interfaces: {
+      'Wi-Fi': [{ address: '192.168.1.114', netmask: '255.255.255.0', family: 'IPv4', internal: false }],
+    },
+    platform: 'none',
+  });
+  const execFn = async () => JSON.stringify({
+    adapters: [
+      { Name: 'Wi-Fi', InterfaceDescription: 'Intel Wi-Fi', Status: 'Up', LinkSpeed: '866 Mbps', MediaType: '802.11', InterfaceIndex: 7 },
+      { Name: 'Local Area Connection* 9', InterfaceDescription: 'Microsoft Wi-Fi Direct', Status: 'Disconnected', MediaType: '802.11', InterfaceIndex: 9 },
+      { Name: 'Bluetooth Network Connection', InterfaceDescription: 'Bluetooth', Status: 'Disconnected', MediaType: '802.3', InterfaceIndex: 12 },
+    ],
+    routes: [{ InterfaceIndex: 7, NextHop: '192.168.1.1', RouteMetric: 25 }],
+  });
+  const enriched = await enrichWindowsInterfaces(baseline, execFn);
+  assert.equal(enriched.length, 3);
+  const missing = enriched.find(i => i.name === 'Local Area Connection* 9');
+  assert.ok(missing);
+  assert.equal(missing.status, 'down');
+  assert.deepEqual(missing.addresses, []);
+  assert.equal(missing.type, 'virtual');
+  const bt = enriched.find(i => i.name === 'Bluetooth Network Connection');
+  assert.equal(bt.status, 'down');
+  assert.equal(enriched.find(i => i.name === 'Wi-Fi').isDefaultRoute, true);
+});
+
+test('macOS associated Wi-Fi status counts as up', () => {
+  const states = parseMacIfconfig('en0: flags=8863<UP,BROADCAST,SMART,RUNNING> mtu 1500\n\tstatus: associated\n\tmedia: autoselect\n');
+  assert.equal(states.get('en0').status, 'up');
+});
+
+test('classifyScanToken separates network shapes from adapter names', () => {
+  assert.equal(classifyScanToken('192.168.1.0/24'), 'subnet');
+  assert.equal(classifyScanToken('10.0.0.1-10.0.0.30'), 'subnet');
+  assert.equal(classifyScanToken('192.168.1.50'), 'subnet');
+  assert.equal(classifyScanToken('999.1.1.1'), 'subnet');
+  assert.equal(classifyScanToken('Wi-Fi'), 'name');
+  assert.equal(classifyScanToken('eth0'), 'name');
+  assert.equal(classifyScanToken('vEthernet (WSL)'), 'name');
+  assert.equal(classifyScanToken(''), 'empty');
+});
+
+test('hyphenated adapter names resolve as interfaces, not IP ranges', async () => {
+  const opts = { interfaces: fixtureInterfaces, platform: 'none' };
+  assert.deepEqual(await resolveScanSubnets({ ...opts, iface: 'Wi-Fi' }), ['192.168.1.0/24']);
+  assert.deepEqual(await resolveScanSubnets({ ...opts, iface: 'wi-fi' }), ['192.168.1.0/24']);
+});
+
+test('resolveScanSubnets supports unique substrings and rejects ambiguity', async () => {
+  const opts = { interfaces: fixtureInterfaces, platform: 'none' };
+  assert.deepEqual(await resolveScanSubnets({ ...opts, iface: 'vEth' }), ['172.30.0.0/20']);
+  await assert.rejects(() => resolveScanSubnets({ ...opts, iface: 'e' }), /Ambiguous interface/);
+});
+
+test('resolveScanSubnets refuses an interface whose subnet exceeds the cap', async () => {
+  const opts = { interfaces: fixtureInterfaces, platform: 'none', maxHosts: 100 };
+  await assert.rejects(
+    () => resolveScanSubnets({ ...opts, iface: 'vEthernet (WSL)' }),
+    /over the 100-host cap.*slice instead/s
+  );
+});
+
+test('scanLan auto sweep packs small LANs first and reports skipped giants', async () => {
+  clearLanScanCache();
+  const bigFixtures = {
+    office: [{ address: '192.168.10.5', netmask: '255.255.255.0', family: 'IPv4', internal: false }],
+    lab: [{ address: '192.168.20.5', netmask: '255.255.254.0', family: 'IPv4', internal: false }],
+    hyperv: [{ address: '172.30.0.1', netmask: '255.255.0.0', family: 'IPv4', internal: false }],
+  };
+  const seen = new Set();
+  const result = await scanLan({
+    interfaces: bigFixtures,
+    platform: 'none',
+    ports: [1234],
+    maxHosts: 800,
+    force: true,
+    connector: async (host) => { seen.add(host.split('.')[2]); return false; },
+    prober: async () => ({ reachable: false }),
+  });
+  assert.deepEqual(result.subnets, ['192.168.10.0/24', '192.168.20.0/23']);
+  assert.equal(result.skippedSubnets.length, 1);
+  assert.equal(result.skippedSubnets[0].cidr, '172.30.0.0/16');
+  assert.equal(result.skippedSubnets[0].reason, 'over-budget');
+  assert.ok(!seen.has('30'));
+  clearLanScanCache();
+});
+
+test('scanLan honors iface selection end to end', async () => {
+  clearLanScanCache();
+  const seen = [];
+  const result = await scanLan({
+    iface: 'wlp2s0',
+    interfaces: fixtureInterfaces,
+    platform: 'none',
+    ports: [1234],
+    force: true,
+    connector: async (host, port) => {
+      seen.push(`${host}:${port}`);
+      return host === '192.168.1.50' && port === 1234;
+    },
+    prober: async ({ host, port }) => ({
+      host, port, url: `http://${host}:${port}/v1`, reachable: true,
+      serverType: 'lmstudio', serverName: 'LM Studio', models: ['m'], modelCount: 1,
+      authRequired: false, latencyMs: 5,
+    }),
+  });
+  assert.deepEqual(result.subnets, ['192.168.1.0/24']);
+  assert.ok(seen.length > 200 && seen.length < 300);
+  assert.ok(seen.every(s => s === '127.0.0.1:1234' || s.startsWith('192.168.1.')));
+  assert.equal(result.endpoints.length, 1);
+  clearLanScanCache();
+});
+
+test('settings UI offers an interface picker for the LAN scan', () => {
+  const html = getSettingsHtml();
+  assert.match(html, /id="lan-scan-iface"/);
+  assert.match(html, /function loadLanInterfaces\(/);
+  assert.match(html, /lblLanIface/);
+  assert.match(html, /iface=' \+ encodeURIComponent\(iface\)/);
+  assert.match(html, /kiku_lan_iface/);
+  assert.match(html, /lanScannedScope/);
+  assert.match(html, /lanSkippedScope/);
+});
+
+test('parseLanScanArgs splits targets, flags, and interface selection', () => {
+  assert.deepEqual(parseLanScanArgs([]), { subnets: null, iface: null, ports: null, force: false, error: null });
+  assert.deepEqual(parseLanScanArgs(['192.168.1.0/24']).subnets, ['192.168.1.0/24']);
+  assert.deepEqual(
+    parseLanScanArgs(['10.0.0.1-10.0.0.30', '--ports', '1234,8000']).ports,
+    [1234, 8000]
+  );
+  assert.deepEqual(parseLanScanArgs(['--ports=11434', '10.0.0.5']).subnets, ['10.0.0.5']);
+  assert.equal(parseLanScanArgs(['scan', '--iface', 'Wi-Fi']).iface, 'Wi-Fi');
+  assert.equal(parseLanScanArgs(['--iface=2']).iface, '2');
+  assert.equal(parseLanScanArgs(['--interface', 'eth0']).iface, 'eth0');
+  assert.equal(parseLanScanArgs(['--force', '192.168.1.0/24']).force, true);
+  assert.equal(parseLanScanArgs(['-f']).force, true);
+  assert.equal(parseLanScanArgs(['--ports']).error, 'ports');
+  assert.equal(parseLanScanArgs(['--ports', 'abc']).error, 'ports');
+  assert.equal(parseLanScanArgs(['--iface']).error, 'iface');
+  const mixed = parseLanScanArgs(['--iface', '1', '--ports', '1234', '192.168.2.0/24']);
+  assert.equal(mixed.iface, '1');
+  assert.deepEqual(mixed.ports, [1234]);
+  assert.deepEqual(mixed.subnets, ['192.168.2.0/24']);
+});
+
+test('describeLanInterface renders a one-line selectable summary', () => {
+  const line = describeLanInterface({
+    index: 3, name: 'Wi-Fi', displayName: 'Wi-Fi', type: 'wifi', status: 'up',
+    gateway: '192.168.1.1', isDefaultRoute: true, internal: false,
+    addresses: [{ address: '192.168.1.20', cidr: '192.168.1.0/24' }],
+  });
+  assert.match(line, /\[3\] Wi-Fi/);
+  assert.match(line, /192\.168\.1\.0\/24/);
+  assert.match(line, /gw=192\.168\.1\.1/);
+  assert.match(line, /default/);
+});
+
+test('the /lan command is registered with interface selection usage', async () => {
+  assert.ok(COMMAND_NAMES.includes('/lan'));
+  const { getCommandDetails } = await import('../commandRegistry.js');
+  const details = getCommandDetails('/lan');
+  assert.match(details?.usage || '', /--iface/);
+  assert.match(details?.usage || '', /ifs/);
+});
+
+test('lan state persists the last scan and sticky interface across restarts', async () => {
+  const { mkdtemp, rm } = await import('node:fs/promises');
+  const { tmpdir } = await import('node:os');
+  const { join } = await import('node:path');
+  const dir = await mkdtemp(join(tmpdir(), 'kiku-lan-'));
+  try {
+    const empty = await loadLanState({ dataDir: dir });
+    assert.deepEqual(empty, { lastIface: null, lastScan: null });
+
+    const saved = await saveLanState({
+      lastIface: 'Wi-Fi',
+      lastScan: { savedAt: '2026-09-15T00:00:00.000Z', subnets: ['192.168.1.0/24'], endpoints: [{ host: '192.168.1.50', port: 1234 }] },
+    }, { dataDir: dir });
+    assert.equal(saved.lastIface, 'Wi-Fi');
+
+    const reloaded = await loadLanState({ dataDir: dir });
+    assert.equal(reloaded.lastIface, 'Wi-Fi');
+    assert.equal(reloaded.lastScan.endpoints.length, 1);
+
+    const merged = await saveLanState({ lastIface: 'eth0' }, { dataDir: dir });
+    assert.equal(merged.lastIface, 'eth0');
+    assert.equal(merged.lastScan.endpoints.length, 1);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('describeLanScanAge buckets scan freshness for humans', () => {
+  const now = new Date('2026-09-15T12:00:00.000Z').getTime();
+  assert.equal(describeLanScanAge(new Date(now - 30 * 1000).toISOString(), now), 'just now');
+  assert.equal(describeLanScanAge(new Date(now - 5 * 60000).toISOString(), now), '5m ago');
+  assert.equal(describeLanScanAge(new Date(now - 3 * 3600000).toISOString(), now), '3h ago');
+  assert.equal(describeLanScanAge(new Date(now - 2 * 86400000).toISOString(), now), '2d ago');
+  assert.equal(describeLanScanAge(null, now), 'unknown age');
+});
+
+test('pickLanEndpointModel selects by index, name, or falls back to first', () => {
+  const endpoint = { host: 'h', port: 1, models: ['google/gemma-4-e4b', 'Qwen/Qwen2.5-7B', 'llama3'] };
+  assert.deepEqual(pickLanEndpointModel(endpoint, null), { model: 'google/gemma-4-e4b', matched: true, via: 'first' });
+  assert.equal(pickLanEndpointModel(endpoint, '2').model, 'Qwen/Qwen2.5-7B');
+  assert.equal(pickLanEndpointModel(endpoint, 'llama3').via, 'exact');
+  assert.equal(pickLanEndpointModel(endpoint, 'qwen').via, 'substring');
+  assert.equal(pickLanEndpointModel({ models: [] }, null).matched, false);
+  const miss = pickLanEndpointModel(endpoint, 'nope');
+  assert.equal(miss.matched, false);
+  const ambiguous = pickLanEndpointModel({ models: ['a-1', 'a-2'] }, 'a-');
+  assert.equal(ambiguous.matched, false);
+  assert.equal(ambiguous.ambiguous.length, 2);
+});
+
+test('scan panel exposes ports input with persisted value', () => {
+  const html = getSettingsHtml();
+  assert.match(html, /id="lan-scan-ports"/);
+  assert.match(html, /kiku_lan_ports/);
+  assert.match(html, /lblLanPorts/);
+  assert.match(html, /lanSkippedScope/);
+});