kiku-agent 1.3.2 → 1.3.3

package/server/agent/lanDiscovery.js

@@ -1,8 +1,17 @@
 import net from 'node:net';
 import os from 'node:os';
+import path from 'node:path';
+import { promises as fsp } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
 import { isPrivateIPv4 } from './sanitizer.js';
+import { KIKU_DATA_DIR } from './appPaths.js';
 
 export const DEFAULT_LLM_PORTS = Object.freeze([1234, 8000, 11434, 8080]);
+export const LAN_INTERFACE_EXEC_TIMEOUT_MS = 4000;
+export const EXPAND_CIDR_MAX_HOSTS = 65536;
+
+const execFileAsync = promisify(execFile);
 
 const CACHE_TTL_MS = 60_000;
 
@@ -27,6 +36,57 @@ function parseIpv4(host) {
   return octets;
 }
 
+export function netmaskToPrefix(netmask) {
+  const octets = parseIpv4(netmask);
+  if (!octets) return null;
+  let bits = 0;
+  let seenZero = false;
+  for (const octet of octets) {
+    for (let bit = 7; bit >= 0; bit--) {
+      const on = (octet >> bit) & 1;
+      if (on) {
+        if (seenZero) return null;
+        bits++;
+      } else {
+        seenZero = true;
+      }
+    }
+  }
+  return bits;
+}
+
+export function netmaskFromPrefix(prefix) {
+  const n = Number(prefix);
+  if (!Number.isInteger(n) || n < 0 || n > 32) return null;
+  const mask = n === 0 ? 0 : (0xffffffff << (32 - n)) >>> 0;
+  return uint32ToIp(mask);
+}
+
+export function usableHostCount(prefix) {
+  const n = Number(prefix);
+  if (!Number.isInteger(n) || n < 0 || n > 32) return 0;
+  const size = 2 ** (32 - n);
+  return n <= 30 ? Math.max(0, size - 2) : size;
+}
+
+export function networkCidr(address, prefix) {
+  const octets = parseIpv4(address);
+  const n = Number(prefix);
+  if (!octets || !Number.isInteger(n) || n < 0 || n > 32) return null;
+  const mask = n === 0 ? 0 : (0xffffffff << (32 - n)) >>> 0;
+  const network = (ipv4ToUint32(octets) & mask) >>> 0;
+  return `${uint32ToIp(network)}/${n}`;
+}
+
+export function prefixFromEntry(entry = {}) {
+  const cidrText = String(entry.cidr || '');
+  const cidrPrefix = cidrText.includes('/') ? Number(cidrText.split('/')[1]) : NaN;
+  if (Number.isInteger(cidrPrefix) && cidrPrefix >= 0 && cidrPrefix <= 32) return cidrPrefix;
+  const fromMask = netmaskToPrefix(entry.netmask);
+  if (fromMask !== null) return fromMask;
+  return 24;
+}
+
 export function getLanCandidateSubnets(interfaces = os.networkInterfaces()) {
   const seen = new Set();
   const subnets = [];
@@ -37,23 +97,40 @@ export function getLanCandidateSubnets(interfaces = os.networkInterfaces()) {
       if (!octets || octets[0] === 127) continue;
       if (octets[0] === 169 && octets[1] === 254) continue;
       if (!isPrivateIPv4(entry.address)) continue;
-      const cidr = `${octets[0]}.${octets[1]}.${octets[2]}.0/24`;
+      const prefix = prefixFromEntry(entry);
+      const cidr = networkCidr(entry.address, prefix);
       if (seen.has(cidr)) continue;
       seen.add(cidr);
-      subnets.push({ cidr, interfaceName: name, address: entry.address });
+      subnets.push({
+        cidr,
+        interfaceName: name,
+        address: entry.address,
+        netmask: netmaskFromPrefix(prefix),
+        prefix,
+        hostCount: usableHostCount(prefix),
+      });
     }
   }
   return subnets;
 }
 
-export function expandCidrToHosts(cidr) {
-  const base = String(cidr || '').split('/')[0];
+export function expandCidrToHosts(cidr, { maxHosts = EXPAND_CIDR_MAX_HOSTS } = {}) {
+  const [base, prefixStr] = String(cidr || '').split('/');
   const octets = parseIpv4(base);
-  if (!octets) throw new Error(`Invalid CIDR "${cidr}"`);
-  const hosts = [];
-  for (let last = 1; last <= 254; last++) {
-    hosts.push(`${octets[0]}.${octets[1]}.${octets[2]}.${last}`);
+  const prefix = prefixStr === undefined || prefixStr === '' ? 24 : Number(prefixStr);
+  if (!octets || !Number.isInteger(prefix) || prefix < 8 || prefix > 32) {
+    throw new Error(`Invalid CIDR "${cidr}"`);
+  }
+  const network = (ipv4ToUint32(octets) & (0xffffffff << (32 - prefix))) >>> 0;
+  const size = 2 ** (32 - prefix);
+  const usable = prefix <= 30 ? size - 2 : size;
+  if (usable > maxHosts) {
+    throw new Error(`CIDR "${cidr}" expands to ${usable.toLocaleString()} hosts (cap ${maxHosts.toLocaleString()}). Scan a smaller prefix instead.`);
   }
+  const first = prefix <= 30 ? network + 1 : network;
+  const last = prefix <= 30 ? network + size - 2 : network + size - 1;
+  const hosts = [];
+  for (let ip = first; ip <= last; ip++) hosts.push(uint32ToIp(ip >>> 0));
   return hosts;
 }
 
@@ -71,7 +148,6 @@ export function expandTargets(specs, { maxHosts = DEFAULT_MAX_SCAN_HOSTS } = {})
   const list = Array.isArray(specs) ? specs : String(specs || '').split(',');
   const out = [];
   const seen = new Set();
-  let planned = 0;
 
   const pushIp = value => {
     const ip = uint32ToIp(value);
@@ -94,14 +170,14 @@ export function expandTargets(specs, { maxHosts = DEFAULT_MAX_SCAN_HOSTS } = {})
       }
       const network = prefix === 0 ? 0 : (ipv4ToUint32(octets) & (0xffffffff << (32 - prefix))) >>> 0;
       const size = 2 ** (32 - prefix);
-      const usable = prefix <= 30 ? size - 2 : size;
-      planned += usable;
-      if (planned > maxHosts) {
-        throw new Error(`Scan target limit exceeded (>${maxHosts} hosts). Narrow the range or raise KIKU_LAN_SCAN_MAX_HOSTS.`);
-      }
       const first = prefix <= 30 ? network + 1 : network;
       const last = prefix <= 30 ? network + size - 2 : network + size - 1;
-      for (let ip = first; ip <= last; ip++) pushIp(ip >>> 0);
+      for (let ip = first; ip <= last; ip++) {
+        pushIp(ip >>> 0);
+        if (out.length > maxHosts) {
+          throw new Error(`Scan target limit exceeded (>${maxHosts} hosts). Narrow the range or raise KIKU_LAN_SCAN_MAX_HOSTS.`);
+        }
+      }
     } else if (spec.includes('-')) {
       const [startStr, endStr] = spec.split('-');
       const startOctets = parseIpv4(startStr);
@@ -112,23 +188,615 @@ export function expandTargets(specs, { maxHosts = DEFAULT_MAX_SCAN_HOSTS } = {})
       const start = ipv4ToUint32(startOctets);
       const end = ipv4ToUint32(endOctets);
       if (end < start) throw new Error(`Invalid IP range "${spec}" (start is after end)`);
-      const count = end - start + 1;
-      planned += count;
-      if (planned > maxHosts) {
-        throw new Error(`Scan target limit exceeded (>${maxHosts} hosts). Narrow the range or raise KIKU_LAN_SCAN_MAX_HOSTS.`);
+      for (let ip = start; ip <= end; ip++) {
+        pushIp(ip >>> 0);
+        if (out.length > maxHosts) {
+          throw new Error(`Scan target limit exceeded (>${maxHosts} hosts). Narrow the range or raise KIKU_LAN_SCAN_MAX_HOSTS.`);
+        }
       }
-      for (let ip = start; ip <= end; ip++) pushIp(ip >>> 0);
     } else {
       const octets = parseIpv4(spec);
       if (!octets) throw new Error(`Invalid IP address "${spec}"`);
-      planned += 1;
       pushIp(ipv4ToUint32(octets));
+      if (out.length > maxHosts) {
+        throw new Error(`Scan target limit exceeded (>${maxHosts} hosts). Narrow the range or raise KIKU_LAN_SCAN_MAX_HOSTS.`);
+      }
     }
   }
 
   return out;
 }
 
+const VIRTUAL_IFACE_RE = /(docker|veth\d*|br-[0-9a-f]|bridge|vmnet|vbox|virtualbox|tailscale|twingate|wg\d*|wireguard|utun\d*|ppp\d*|hamachi|zerotier|zt\d*|lxc|vethernet|hyper-v|\bvpn\b|\btap\b|\btun\d*)/i;
+const WIFI_IFACE_RE = /(wi-?fi|wlan\d*|ath\d*|wlp\d+s\d+)/i;
+const ETHERNET_IFACE_RE = /^(eth\d+|ethernet(\s*\d*)?|eno\d+|ens\d+|em\d+|enp\d+s\d+|lan\d*)$/i;
+
+export function inferInterfaceType(name = '', detail = '') {
+  const text = `${name} ${detail}`.trim();
+  if (!text) return 'unknown';
+  if (/^(lo(\d+)?|loopback)(?![a-z])/i.test(text)) return 'loopback';
+  if (VIRTUAL_IFACE_RE.test(text)) return 'virtual';
+  if (/local area connection/i.test(text)) return 'virtual';
+  if (WIFI_IFACE_RE.test(text)) return 'wifi';
+  if (ETHERNET_IFACE_RE.test(text)) return 'ethernet';
+  return 'unknown';
+}
+
+function normalizeIfaceStatus(value) {
+  const text = String(value || '').trim().toLowerCase();
+  if (!text) return 'unknown';
+  if (['up', 'active', 'associated', 'connected', 'enabled', 'ok', '2'].includes(text)) return 'up';
+  if (['down', 'inactive', 'disconnected', 'disabled', 'dormant', '1', 'testing', 'notpresent', 'lowerlayerdown'].includes(text)) return 'down';
+  return 'unknown';
+}
+
+function buildInterfaceBaseline(interfaces = {}) {
+  const list = [];
+  let index = 0;
+  for (const [name, entries] of Object.entries(interfaces || {})) {
+    const all = Array.isArray(entries) ? entries : [];
+    const v4 = all.filter(e => e && e.family === 'IPv4' && e.address);
+    const internal = all.length > 0 && all.every(e => e && e.internal);
+    list.push({
+      index: index++,
+      name,
+      displayName: name,
+      detail: '',
+      internal,
+      mac: (all.find(e => e && e.mac && !/^0{2}(:0{2}){5}$/i.test(e.mac)) || {}).mac || null,
+      type: inferInterfaceType(name, ''),
+      status: internal ? 'up' : 'unknown',
+      speed: null,
+      gateway: null,
+      isDefaultRoute: false,
+      addresses: v4.map(e => {
+        const prefix = prefixFromEntry(e);
+        return {
+          address: e.address,
+          netmask: e.netmask || netmaskFromPrefix(prefix),
+          prefix,
+          cidr: networkCidr(e.address, prefix),
+        };
+      }),
+    });
+  }
+  return list;
+}
+
+function matchBaseline(baseline, predicate) {
+  return baseline.find(predicate) || null;
+}
+
+function matchByName(baseline, name) {
+  const target = String(name || '').trim().toLowerCase();
+  if (!target) return null;
+  return matchBaseline(baseline, i => i.name.toLowerCase() === target)
+    || matchBaseline(baseline, i => (i.displayName || '').toLowerCase() === target);
+}
+
+function safeJsonParse(text) {
+  try {
+    const parsed = JSON.parse(String(text || ''));
+    return parsed === undefined ? null : parsed;
+  } catch {
+    return null;
+  }
+}
+
+function asArray(value) {
+  if (Array.isArray(value)) return value;
+  if (value && typeof value === 'object') return [value];
+  return [];
+}
+
+export function parseWindowsAdapters(jsonText) {
+  const rows = asArray(safeJsonParse(jsonText));
+  return rows.map(row => ({
+    name: String(row?.Name || row?.name || '').trim(),
+    description: String(row?.InterfaceDescription || row?.description || '').trim(),
+    status: normalizeIfaceStatus(row?.Status ?? row?.status),
+    speed: row?.LinkSpeed ?? row?.speed ?? null,
+    mediaType: String(row?.MediaType || row?.mediaType || ''),
+    interfaceIndex: Number(row?.InterfaceIndex ?? row?.ifIndex ?? NaN),
+  })).filter(a => a.name);
+}
+
+export function parseWindowsDefaultRoutes(jsonText) {
+  const rows = asArray(safeJsonParse(jsonText));
+  return rows
+    .map(row => ({
+      interfaceIndex: Number(row?.InterfaceIndex ?? row?.ifIndex ?? NaN),
+      gateway: String(row?.NextHop || row?.gateway || '').trim(),
+      metric: Number(row?.RouteMetric ?? row?.metric ?? 0),
+    }))
+    .filter(r => Number.isInteger(r.interfaceIndex) && parseIpv4(r.gateway));
+}
+
+export async function enrichWindowsInterfaces(baseline, run) {
+  const snapshot = safeJsonParse(await run('powershell.exe', [
+    '-NoProfile', '-NonInteractive', '-Command',
+    "@{ adapters = @(Get-NetAdapter -IncludeHidden | Select-Object Name,InterfaceDescription,Status,LinkSpeed,MediaType,InterfaceIndex); routes = @(Get-NetRoute -DestinationPrefix '0.0.0.0/0' -ErrorAction SilentlyContinue | Select-Object InterfaceIndex,NextHop,RouteMetric) } | ConvertTo-Json -Compress -Depth 3",
+  ]).catch(() => ''));
+  const adapters = parseWindowsAdapters(JSON.stringify(snapshot?.adapters ?? []));
+  const routes = parseWindowsDefaultRoutes(JSON.stringify(snapshot?.routes ?? []));
+  const byName = new Map(adapters.map(a => [a.name.toLowerCase(), a]));
+  const byIndex = new Map();
+  for (const adapter of adapters) {
+    if (Number.isInteger(adapter.interfaceIndex)) byIndex.set(adapter.interfaceIndex, adapter);
+  }
+  let defaultRoute = null;
+  for (const route of routes) {
+    if (!defaultRoute || route.metric < defaultRoute.metric) defaultRoute = route;
+  }
+  const gatewayByAdapter = new Map();
+  for (const route of routes) {
+    const adapter = byIndex.get(route.interfaceIndex);
+    if (!adapter) continue;
+    const key = adapter.name.toLowerCase();
+    const prev = gatewayByAdapter.get(key);
+    if (!prev || route.metric < prev.metric) gatewayByAdapter.set(key, route);
+  }
+  const enriched = baseline.map(iface => {
+    const adapter = byName.get(iface.name.toLowerCase());
+    if (!adapter) return iface;
+    const next = { ...iface };
+    if (adapter.description) {
+      next.displayName = iface.name;
+      next.detail = adapter.description;
+    }
+    if (adapter.status !== 'unknown') next.status = adapter.status;
+    if (adapter.speed !== null && adapter.speed !== undefined) next.speed = String(adapter.speed);
+    const nameType = inferInterfaceType(iface.name, adapter.description);
+    if (nameType === 'virtual') {
+      next.type = 'virtual';
+    } else {
+      const mediaLower = adapter.mediaType.toLowerCase();
+      if (mediaLower.includes('802.11')) next.type = 'wifi';
+      else if (mediaLower.includes('802.3')) next.type = 'ethernet';
+      else if (next.type === 'unknown' && nameType !== 'unknown') next.type = nameType;
+    }
+    const gw = gatewayByAdapter.get(iface.name.toLowerCase());
+    if (gw) {
+      next.gateway = gw.gateway;
+      if (defaultRoute && gw.gateway === defaultRoute.gateway && gw.interfaceIndex === defaultRoute.interfaceIndex) {
+        next.isDefaultRoute = true;
+      }
+    }
+    return next;
+  });
+  let nextIndex = enriched.reduce((top, i) => Math.max(top, Number(i.index) || 0), -1) + 1;
+  for (const adapter of adapters) {
+    if (enriched.some(i => i.name.toLowerCase() === adapter.name.toLowerCase())) continue;
+    const nameType = inferInterfaceType(adapter.name, adapter.description);
+    let type = 'unknown';
+    if (nameType === 'virtual') type = 'virtual';
+    else {
+      const mediaLower = adapter.mediaType.toLowerCase();
+      if (mediaLower.includes('802.11')) type = 'wifi';
+      else if (mediaLower.includes('802.3')) type = 'ethernet';
+      else if (nameType !== 'unknown') type = nameType;
+    }
+    const gw = gatewayByAdapter.get(adapter.name.toLowerCase());
+    enriched.push({
+      index: nextIndex++,
+      name: adapter.name,
+      displayName: adapter.name,
+      detail: adapter.description || '',
+      internal: false,
+      mac: null,
+      type,
+      status: adapter.status !== 'unknown' ? adapter.status : 'down',
+      speed: adapter.speed !== null && adapter.speed !== undefined ? String(adapter.speed) : null,
+      gateway: gw ? gw.gateway : null,
+      isDefaultRoute: Boolean(gw && defaultRoute && gw.gateway === defaultRoute.gateway && gw.interfaceIndex === defaultRoute.interfaceIndex),
+      addresses: [],
+    });
+  }
+  return enriched;
+}
+
+function flagsCarryUp(flags) {
+  const list = Array.isArray(flags) ? flags : String(flags || '').split(/[\s,<>|]+/);
+  return list.some(f => String(f || '').trim().toUpperCase() === 'UP');
+}
+
+function statusWithFlagFallback(rawStatus, flags) {
+  const status = normalizeIfaceStatus(rawStatus);
+  if (status === 'unknown' && flagsCarryUp(flags)) return 'up';
+  return status;
+}
+
+export function parseLinuxIpAddr(jsonText) {
+  const rows = asArray(safeJsonParse(jsonText));
+  return rows.map(row => ({
+    name: String(row?.ifname || row?.ifname === 0 ? row.ifname : (row?.ifname || '')).trim(),
+    status: statusWithFlagFallback(row?.operstate, row?.flags),
+    mac: String(row?.address || '').trim() || null,
+    mtu: Number(row?.mtu) || null,
+  })).filter(a => a.name);
+}
+
+export function parseLinuxIpAddrText(text) {
+  const links = [];
+  const blocks = String(text || '').split(/^(?=\d+:\s+\S+:)/m);
+  for (const block of blocks) {
+    const header = /^(\d+):\s+([^:]+):\s*<([^>]*)>.*state\s+(\S+)/im.exec(block);
+    if (!header) continue;
+    const name = header[2].trim().split('@')[0];
+    if (!name) continue;
+    links.push({
+      name,
+      status: statusWithFlagFallback(header[4], header[3]),
+      mac: /link\/ether\s+([0-9a-f:]{17})/i.exec(block)?.[1]?.toLowerCase() || null,
+      mtu: Number(/mtu\s+(\d+)/i.exec(block)?.[1]) || null,
+    });
+  }
+  return links;
+}
+
+export function parseLinuxDefaultRoutes(jsonText) {
+  const rows = asArray(safeJsonParse(jsonText));
+  return rows
+    .map(row => ({
+      device: String(row?.dev || row?.device || '').trim(),
+      gateway: String(row?.gateway || '').trim(),
+      metric: Number(row?.metric ?? 0),
+    }))
+    .filter(r => r.device && parseIpv4(r.gateway));
+}
+
+export async function enrichLinuxInterfaces(baseline, run) {
+  let links = [];
+  try {
+    links = parseLinuxIpAddr(await run('ip', ['-j', 'addr']));
+  } catch {
+    links = [];
+  }
+  if (links.length === 0) {
+    try {
+      links = parseLinuxIpAddrText(await run('ip', ['addr']));
+    } catch {
+      links = [];
+    }
+  }
+  const byName = new Map(links.map(l => [l.name, l]));
+  const routes = parseLinuxDefaultRoutes(await run('ip', ['-j', 'route', 'show', 'default']).catch(() => ''));
+  let defaultRoute = null;
+  for (const route of routes) {
+    if (!defaultRoute || route.metric < defaultRoute.metric) defaultRoute = route;
+  }
+  return baseline.map(iface => {
+    const next = { ...iface };
+    const link = byName.get(iface.name);
+    if (link) {
+      if (link.status !== 'unknown') next.status = link.status;
+      if (!next.mac && link.mac) next.mac = link.mac;
+      if (next.type === 'unknown') next.type = inferInterfaceType(iface.name, '');
+    }
+    const route = routes.find(r => r.device === iface.name);
+    if (route) {
+      next.gateway = route.gateway;
+      if (defaultRoute && defaultRoute.device === iface.name) next.isDefaultRoute = true;
+    }
+    return next;
+  });
+}
+
+export function parseMacHardwarePorts(text) {
+  const ports = [];
+  const blocks = String(text || '').split(/\n\s*\n/);
+  for (const block of blocks) {
+    const port = /Hardware Port:\s*(.+)/i.exec(block)?.[1]?.trim();
+    const device = /Device:\s*(\S+)/i.exec(block)?.[1]?.trim();
+    if (port && device) ports.push({ port, device });
+  }
+  return ports;
+}
+
+export function parseMacDefaultRoute(text) {
+  const gateway = /gateway:\s*([0-9.]+)/i.exec(String(text || ''))?.[1] || null;
+  const device = /interface:\s*(\S+)/i.exec(String(text || ''))?.[1] || null;
+  return {
+    gateway: gateway && parseIpv4(gateway) ? gateway : null,
+    device,
+  };
+}
+
+export function parseMacIfconfig(text) {
+  const result = new Map();
+  const blocks = String(text || '').split(/^(?=\S+:)/m);
+  for (const block of blocks) {
+    const name = /^([A-Za-z0-9_.]+):/.exec(block)?.[1];
+    if (!name) continue;
+    const statusText = /status:\s*(\S+)/i.exec(block)?.[1] || '';
+    const media = /media:\s*([^\n<]+)/i.exec(block)?.[1]?.trim() || '';
+    const flags = /^.+flags=\d+<([^>]+)>/m.exec(block)?.[1] || '';
+    let status = normalizeIfaceStatus(statusText);
+    if (status === 'unknown') {
+      status = /,UP,/i.test(`,${flags},`) ? 'up' : status;
+    }
+    result.set(name, { status, media });
+  }
+  return result;
+}
+
+export async function enrichMacInterfaces(baseline, run) {
+  const [ifconfigText, routeText, portsText] = await Promise.all([
+    run('ifconfig', []).catch(() => ''),
+    run('route', ['-n', 'get', 'default']).catch(() => ''),
+    run('networksetup', ['-listallhardwareports']).catch(() => ''),
+  ]);
+  const states = parseMacIfconfig(ifconfigText);
+  const defRoute = parseMacDefaultRoute(routeText);
+  const ports = parseMacHardwarePorts(portsText);
+  const portByDevice = new Map(ports.map(p => [p.device, p.port]));
+  return baseline.map(iface => {
+    const next = { ...iface };
+    const state = states.get(iface.name);
+    if (state) {
+      if (state.status !== 'unknown') next.status = state.status;
+      if (next.type === 'unknown') {
+        const mediaLower = state.media.toLowerCase();
+        if (/wi-?fi|wlan|802\.11/.test(mediaLower)) next.type = 'wifi';
+        else if (/ethernet|thunderbolt|1000base|100base|10gbase/.test(mediaLower)) next.type = 'ethernet';
+        else next.type = inferInterfaceType(iface.name, state.media);
+      }
+    }
+    const port = portByDevice.get(iface.name);
+    if (port) {
+      next.displayName = `${port} (${iface.name})`;
+      if (next.type === 'unknown') next.type = inferInterfaceType(port, '');
+    }
+    if (defRoute.device === iface.name) {
+      next.gateway = defRoute.gateway;
+      next.isDefaultRoute = true;
+    }
+    return next;
+  });
+}
+
+function defaultExecFn(cmd, args, { timeoutMs = LAN_INTERFACE_EXEC_TIMEOUT_MS } = {}) {
+  return execFileAsync(cmd, args, { timeout: timeoutMs, windowsHide: true, maxBuffer: 4 * 1024 * 1024 })
+    .then(result => String(result?.stdout ?? ''));
+}
+
+export async function listLanInterfaces({
+  interfaces = os.networkInterfaces(),
+  platform = process.platform,
+  execFn = null,
+  timeoutMs = LAN_INTERFACE_EXEC_TIMEOUT_MS,
+} = {}) {
+  const baseline = buildInterfaceBaseline(interfaces);
+  const enricher = platform === 'win32'
+    ? enrichWindowsInterfaces
+    : platform === 'linux'
+      ? enrichLinuxInterfaces
+      : platform === 'darwin'
+        ? enrichMacInterfaces
+        : null;
+  if (!enricher) return baseline;
+  const run = execFn || ((cmd, args) => defaultExecFn(cmd, args, { timeoutMs }));
+  try {
+    return await enricher(baseline, run);
+  } catch {
+    return baseline;
+  }
+}
+
+function ifacePrivateCidrs(iface) {
+  const cidrs = [];
+  for (const addr of iface?.addresses || []) {
+    if (!addr?.address || !isPrivateIPv4(addr.address)) continue;
+    if (addr.address.startsWith('127.') || addr.address.startsWith('169.254.')) continue;
+    if (addr.cidr) cidrs.push(addr.cidr);
+  }
+  return [...new Set(cidrs)];
+}
+
+export function classifyScanToken(token = '') {
+  const spec = String(token || '').trim();
+  if (!spec) return 'empty';
+  if (spec.includes('/')) return 'subnet';
+  if (/^\d+\.\d+\.\d+\.\d+\s*-\s*\d+\.\d+\.\d+\.\d+$/.test(spec)) return 'subnet';
+  if (parseIpv4(spec)) return 'subnet';
+  if (/^\d+\.\d+\.\d+\.\d+/.test(spec)) return 'subnet';
+  return 'name';
+}
+
+export async function resolveScanSubnets({
+  iface = null,
+  subnets = null,
+  interfaces = null,
+  platform = process.platform,
+  execFn = null,
+  maxHosts = DEFAULT_MAX_SCAN_HOSTS,
+} = {}) {
+  if (Array.isArray(subnets) && subnets.length > 0) return [...subnets];
+  if (iface === null || iface === undefined || String(iface).trim() === '' || String(iface).trim().toLowerCase() === 'auto') {
+    return null;
+  }
+  const spec = String(iface).trim();
+  if (classifyScanToken(spec) === 'subnet' && !/^\d+$/.test(spec)) {
+    return [spec];
+  }
+  const list = await listLanInterfaces({ ...(interfaces ? { interfaces } : {}), platform, execFn });
+  let matched = null;
+  if (/^\d+$/.test(spec)) {
+    matched = list[Number(spec)] || null;
+  } else {
+    matched = matchByName(list, spec);
+    if (!matched) {
+      const lower = spec.toLowerCase();
+      const partials = list.filter(i =>
+        i.name.toLowerCase().includes(lower) || (i.displayName || '').toLowerCase().includes(lower));
+      if (partials.length === 1) {
+        matched = partials[0];
+      } else if (partials.length > 1) {
+        throw new Error(`Ambiguous interface "${spec}" — matches: ${partials.map(i => `${i.index}:${i.name}`).join(', ')}. Use the index from /lan ifs.`);
+      }
+    }
+  }
+  if (!matched) {
+    const available = list.map(i => `${i.index}:${i.name}`).join(', ') || 'none';
+    throw new Error(`Unknown LAN interface "${spec}". Available: ${available}`);
+  }
+  if (matched.internal || matched.type === 'loopback') {
+    throw new Error(`Interface "${matched.name}" is internal/loopback and has no LAN subnet to scan`);
+  }
+  const cidrs = ifacePrivateCidrs(matched);
+  if (cidrs.length === 0) {
+    throw new Error(`Interface "${matched.name}" has no private IPv4 subnet to scan`);
+  }
+  const cap = Number(maxHosts) > 0 ? Math.floor(Number(maxHosts)) : DEFAULT_MAX_SCAN_HOSTS;
+  let total = 0;
+  for (const cidr of cidrs) {
+    const prefix = Number(String(cidr).split('/')[1]);
+    total += Number.isInteger(prefix) ? usableHostCount(prefix) : 0;
+  }
+  if (total > cap) {
+    const first = String(cidrs[0]).split('/')[0].split('.').slice(0, 3).join('.');
+    throw new Error(
+      `Interface "${matched.name}" covers ${cidrs.join(', ')} (${total.toLocaleString()} hosts) — over the ${cap.toLocaleString()}-host cap. ` +
+      `Scan a slice instead, e.g. /lan scan ${first}.0/24, or raise KIKU_LAN_SCAN_MAX_HOSTS.`
+    );
+  }
+  return cidrs;
+}
+
+export function parseLanScanArgs(restTokens = []) {
+  const tokens = [...(restTokens || []).map(t => String(t ?? '').trim()).filter(Boolean)];
+  let ports = null;
+  let iface = null;
+  let force = false;
+  let error = null;
+
+  const takeOption = (names) => {
+    for (let i = 0; i < tokens.length; i++) {
+      const token = tokens[i];
+      for (const name of names) {
+        if (token === name) {
+          const value = tokens[i + 1] ?? null;
+          tokens.splice(i, 2);
+          return value;
+        }
+        if (token.startsWith(`${name}=`)) {
+          tokens.splice(i, 1);
+          return token.slice(name.length + 1);
+        }
+      }
+    }
+    return undefined;
+  };
+
+  const forceIdx = tokens.findIndex(t => t === '--force' || t === '-f');
+  if (forceIdx >= 0) {
+    force = true;
+    tokens.splice(forceIdx, 1);
+  }
+
+  const portsRaw = takeOption(['--ports']);
+  if (portsRaw !== undefined) {
+    const parsed = String(portsRaw || '').split(',').map(Number)
+      .filter(p => Number.isInteger(p) && p >= 1 && p <= 65535);
+    if (!portsRaw || parsed.length === 0) {
+      error = 'ports';
+    } else {
+      ports = [...new Set(parsed)];
+    }
+  }
+
+  const ifaceRaw = takeOption(['--iface', '--interface']);
+  if (ifaceRaw !== undefined) {
+    if (!ifaceRaw || !String(ifaceRaw).trim()) {
+      error = error || 'iface';
+    } else {
+      iface = String(ifaceRaw).trim();
+    }
+  }
+
+  const subnets = tokens.join(',').split(',').map(s => s.trim()).filter(Boolean);
+  return {
+    subnets: subnets.length > 0 ? subnets : null,
+    iface,
+    ports,
+    force,
+    error,
+  };
+}
+
+export function describeLanInterface(iface = {}) {
+  const cidrs = (iface.addresses || []).map(a => a?.cidr).filter(Boolean).join(', ') || 'no IPv4';
+  const parts = [
+    `[${iface.index ?? '?'}] ${iface.displayName || iface.name || 'unknown'}`,
+    `type=${iface.type || 'unknown'}`,
+    `status=${iface.status || 'unknown'}`,
+    `subnet=${cidrs}`,
+  ];
+  if (iface.gateway) parts.push(`gw=${iface.gateway}`);
+  if (iface.isDefaultRoute) parts.push('default');
+  if (iface.internal) parts.push('loopback');
+  return parts.join('  •  ');
+}
+
+export const LAN_STATE_FILENAME = 'lan-state.json';
+
+export function lanStateFile(dataDir = KIKU_DATA_DIR) {
+  return path.join(String(dataDir || KIKU_DATA_DIR), LAN_STATE_FILENAME);
+}
+
+export async function loadLanState({ dataDir = KIKU_DATA_DIR } = {}) {
+  try {
+    const raw = await fsp.readFile(lanStateFile(dataDir), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return { lastIface: null, lastScan: null };
+    return {
+      lastIface: typeof parsed.lastIface === 'string' ? parsed.lastIface : null,
+      lastScan: parsed.lastScan && typeof parsed.lastScan === 'object' ? parsed.lastScan : null,
+    };
+  } catch {
+    return { lastIface: null, lastScan: null };
+  }
+}
+
+export async function saveLanState(patch = {}, { dataDir = KIKU_DATA_DIR } = {}) {
+  const current = await loadLanState({ dataDir });
+  const next = {
+    lastIface: patch.lastIface !== undefined ? patch.lastIface : current.lastIface,
+    lastScan: patch.lastScan !== undefined ? patch.lastScan : current.lastScan,
+  };
+  await fsp.mkdir(String(dataDir || KIKU_DATA_DIR), { recursive: true });
+  await fsp.writeFile(lanStateFile(dataDir), JSON.stringify(next, null, 2), 'utf8');
+  return next;
+}
+
+export function describeLanScanAge(savedAt, now = Date.now()) {
+  const then = Number(new Date(savedAt || 0).getTime());
+  if (!Number.isFinite(then) || then <= 0) return 'unknown age';
+  const minutes = Math.max(0, Math.floor((now - then) / 60000));
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+export function pickLanEndpointModel(endpoint = {}, wanted = null) {
+  const models = Array.isArray(endpoint.models) ? endpoint.models.filter(Boolean) : [];
+  if (models.length === 0) return { model: null, matched: false };
+  const query = String(wanted || '').trim();
+  if (!query) return { model: models[0], matched: true, via: 'first' };
+  if (/^\d+$/.test(query)) {
+    const pick = models[Number(query) - 1];
+    return pick ? { model: pick, matched: true, via: 'index' } : { model: null, matched: false };
+  }
+  const lower = query.toLowerCase();
+  const exact = models.find(m => String(m).toLowerCase() === lower);
+  if (exact) return { model: exact, matched: true, via: 'exact' };
+  const partials = models.filter(m => String(m).toLowerCase().includes(lower));
+  if (partials.length === 1) return { model: partials[0], matched: true, via: 'substring' };
+  return { model: null, matched: false, ambiguous: partials };
+}
+
 function assertAllPrivate(hosts) {
   const offenders = hosts.filter(h => {
     const octets = parseIpv4(h);
@@ -300,6 +968,10 @@ export async function scanLan({
   probeTimeoutMs = 2500,
   concurrency = 128,
   subnets = null,
+  iface = null,
+  interfaces = null,
+  platform = process.platform,
+  execFn = null,
   extraHosts = [],
   maxHosts = Number(process.env.KIKU_LAN_SCAN_MAX_HOSTS) || DEFAULT_MAX_SCAN_HOSTS,
   connector = defaultTcpProbe,
@@ -314,12 +986,37 @@ export async function scanLan({
   );
   if (portList.length === 0) throw new Error('At least one valid port is required');
 
-  const subnetList = subnets && subnets.length > 0 ? subnets : getLanCandidateSubnets().map(s => s.cidr);
+  const explicitSubnets = Array.isArray(subnets) && subnets.length > 0 ? [...subnets] : null;
+  const ifaceSubnets = explicitSubnets
+    ? null
+    : await resolveScanSubnets({ iface, interfaces, platform, execFn, maxHosts });
+  let subnetList = explicitSubnets || ifaceSubnets;
+  let skippedSubnets = [];
+  if (!subnetList) {
+    const ordered = getLanCandidateSubnets(interfaces ?? os.networkInterfaces())
+      .sort((a, b) => a.hostCount - b.hostCount);
+    const picked = [];
+    let used = 0;
+    for (const candidate of ordered) {
+      if (used + candidate.hostCount <= maxHosts) {
+        picked.push(candidate);
+        used += candidate.hostCount;
+      } else {
+        skippedSubnets.push({
+          cidr: candidate.cidr,
+          interfaceName: candidate.interfaceName,
+          hostCount: candidate.hostCount,
+          reason: 'over-budget',
+        });
+      }
+    }
+    subnetList = picked.map(c => c.cidr);
+  }
   const detectedHosts = expandTargets(subnetList, { maxHosts });
   const hostList = [...new Set(['127.0.0.1', ...detectedHosts, ...extraHosts.map(String)])];
   assertAllPrivate(hostList);
 
-  const cacheKey = JSON.stringify({ ports: portList, hosts: hostList });
+  const cacheKey = JSON.stringify({ ports: portList, hosts: hostList, iface: iface ?? null });
   if (!force && scanCache && scanCache.key === cacheKey && now() - scanCache.at < CACHE_TTL_MS) {
     return { ...scanCache.result, cached: true };
   }
@@ -356,6 +1053,7 @@ export async function scanLan({
   const result = {
     scannedAt: new Date(started).toISOString(),
     subnets: subnetList,
+    skippedSubnets,
     hostsScanned: hostList.length,
     ports: portList,
     targetsScanned: targets.length,