elanous 0.2.8 → 0.2.10

package/src/nexus/api/usage-api.ts

@@ -0,0 +1,102 @@
+import { collectUnifiedUsage } from '../../budget/unified-usage.js';
+import type { UnifiedUsageReport } from '../../budget/types.js';
+import { jsonResponse } from './json-response.js';
+
+const CACHE_MS = 30_000;
+
+// TC 조건(10-03 01:21): 계정 이름·이메일·토큰은 응답에 «하나도» 싣지 않는다 — 공급자·사용률·리셋만.
+// 계정이 여럿이면 공급자 안 순번(«계정 1»)으로만 가른다(이름에서 비밀을 걸러 내는 방식은 쓰지 않는다).
+function accountLabel(index: number, count: number): string {
+  return count > 1 ? `계정 ${index + 1}` : '계정';
+}
+
+const SAFE_REASONS = new Set(['query-does-not-supply', 'not-a-subscription']);
+function safeReason(reason: unknown): string {
+  return typeof reason === 'string' && SAFE_REASONS.has(reason) ? reason : 'unknown';
+}
+
+function periodType(value: string | null): string | null {
+  return value && /^(?:session|weekly|monthly|daily|prepaid-usd|USAGE_PERIOD_TYPE_(?:SESSION|WEEKLY|MONTHLY|DAILY))$/.test(value) ? value : null;
+}
+
+function isoDate(value: string | null): string | null {
+  if (!value) return null;
+  const epoch = Date.parse(value);
+  return Number.isFinite(epoch) && epoch > 0 ? new Date(epoch).toISOString() : null;
+}
+
+function resetsInMs(resetsAt: number, nowMs: number): number | null {
+  return Number.isFinite(resetsAt) && resetsAt > 0 ? Math.max(0, resetsAt - nowMs) : null;
+}
+
+function projectUsage(report: UnifiedUsageReport, nowMs: number) {
+  return {
+    ok: true as const,
+    accountCounts: {
+      codex: report.accountCounts.codex,
+      grok: report.accountCounts.grok,
+      openrouter: report.accountCounts.openrouter,
+    },
+    rows: report.rows.map((row, _i, rows) => ({
+      provider: row.provider,
+      account: accountLabel(rows.filter((r) => r.provider === row.provider).indexOf(row), rows.filter((r) => r.provider === row.provider).length),
+      accountCount: row.accountCount,
+      soleAccount: row.soleAccount,
+      credits: row.credits.status === 'ok' ? {
+        status: 'ok' as const,
+        usedPercent: row.credits.usedPercent,
+        periodType: periodType(row.credits.periodType),
+        periodStart: isoDate(row.credits.periodStart),
+        periodEnd: isoDate(row.credits.periodEnd),
+        resetsInMs: resetsInMs(row.credits.periodEnd ? Date.parse(row.credits.periodEnd) : 0, nowMs),
+        monthlyLimit: row.credits.monthlyLimit,
+        used: row.credits.used,
+        onDemandCap: row.credits.onDemandCap,
+        onDemandUsed: row.credits.onDemandUsed,
+        prepaidBalance: row.credits.prepaidBalance,
+        balance: row.credits.balance,
+        hasCredits: row.credits.hasCredits,
+        unlimited: row.credits.unlimited,
+      } : { status: row.credits.status },
+      subscription: row.subscription.status === 'available' ? {
+        status: 'available' as const,
+        remainingPercent: row.subscription.remainingPercent,
+        resetsAt: row.subscription.resetsAt,
+        resetsInMs: resetsInMs(row.subscription.resetsAt, nowMs),
+        windowKind: row.subscription.windowKind,
+      } : { status: 'unavailable' as const, reason: safeReason(row.subscription.reason) },
+      resetCredits: row.resetCredits.status === 'available' || row.resetCredits.status === 'expiring-soon' || row.resetCredits.status === 'expired' ? {
+        status: row.resetCredits.status,
+        expiresAt: isoDate(row.resetCredits.expiresAt),
+        hasUnknownExpiry: row.resetCredits.hasUnknownExpiry,
+      } : { status: row.resetCredits.status },
+    })),
+  };
+}
+
+/** A per-daemon 30-second snapshot; concurrent requests share the same collection. */
+export function createUsageHandler(
+  collect: () => Promise<UnifiedUsageReport> = collectUnifiedUsage,
+  now: () => number = Date.now,
+): () => Promise<Response> {
+  let cached: ReturnType<typeof projectUsage> | undefined;
+  let cachedAt = 0;
+  let pending: Promise<ReturnType<typeof projectUsage>> | undefined;
+  return async () => {
+    if (cached && now() - cachedAt < CACHE_MS) return jsonResponse(cached);
+    pending ??= Promise.resolve().then(collect).then((report) => {
+      const value = projectUsage(report, now());
+      cached = value;
+      cachedAt = now();
+      return value;
+    }).finally(() => { pending = undefined; });
+    try {
+      return jsonResponse(await pending);
+    } catch {
+      // Upstream exceptions can contain credentials; never echo their messages.
+      return jsonResponse({ ok: false, reason: 'usage-collection-failed' });
+    }
+  };
+}
+
+export const handleUsageGet = createUsageHandler();

package/src/nexus/config/secrets/file-backend.ts

@@ -5,8 +5,10 @@
 // without touching caller code. The legacy module re-exports this
 // backend's accessor functions to preserve backwards compatibility.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, copyFileSync, unlinkSync, chmodSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { dirname } from 'node:path';
+import { acquireLockSync } from '../../../storage/file-lock.js';
 import { SECRETS_VERSION, type SecretsFile } from '../types.js';
 import { secretsPath } from '../paths.js';
 import type { SecretBackend, SecretBackendAvailability, SyncReadableBackend } from './types.js';
@@ -21,20 +23,47 @@ function readSecretsFile(): SecretsFile {
   try {
     const raw = readFileSync(path, 'utf-8');
     const parsed = JSON.parse(raw) as Partial<SecretsFile>;
-    if (parsed.version !== SECRETS_VERSION) return defaultSecrets();
-    return {
-      version: SECRETS_VERSION,
-      secrets: (parsed.secrets ?? {}) as Record<string, string>,
-    };
-  } catch {
-    return defaultSecrets();
+    if (parsed?.version !== SECRETS_VERSION || !parsed.secrets || typeof parsed.secrets !== 'object'
+      || Array.isArray(parsed.secrets) || Object.values(parsed.secrets).some(value => typeof value !== 'string')) {
+      throw new Error('invalid secrets file version or contents');
+    }
+    return { version: SECRETS_VERSION, secrets: parsed.secrets };
+  } catch (error) {
+    throw new Error(`cannot read secrets file at ${path}`, { cause: error });
   }
 }
 
 function writeSecretsFile(s: SecretsFile): void {
   const path = secretsPath();
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, JSON.stringify(s, null, 2), { mode: 0o600 });
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  const backupTmp = `${path}.${randomUUID()}.bak.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify(s, null, 2), { mode: 0o600, flag: 'wx' });
+    if (existsSync(path)) {
+      copyFileSync(path, backupTmp);
+      chmodSync(backupTmp, 0o600);
+      renameSync(backupTmp, `${path}.bak`);
+    }
+    renameSync(tmp, path);
+  } finally {
+    if (existsSync(tmp)) unlinkSync(tmp);
+    if (existsSync(backupTmp)) unlinkSync(backupTmp);
+  }
+}
+
+function modifySecretsFile(change: (s: SecretsFile) => boolean): boolean {
+  const path = secretsPath();
+  mkdirSync(dirname(path), { recursive: true });
+  const release = acquireLockSync(`${path}.lock`);
+  try {
+    const s = readSecretsFile();
+    if (!change(s)) return false;
+    writeSecretsFile(s);
+    return true;
+  } finally {
+    release();
+  }
 }
 
 const syncReadable: SyncReadableBackend = {
@@ -46,16 +75,14 @@ export const fileBackend: SecretBackend = {
   id: 'file',
   async get(id) { return syncReadable.getSync(id); },
   async set(id, value) {
-    const s = readSecretsFile();
-    s.secrets[id] = value;
-    writeSecretsFile(s);
+    modifySecretsFile(s => { s.secrets[id] = value; return true; });
   },
   async delete(id) {
-    const s = readSecretsFile();
-    if (!(id in s.secrets)) return false;
-    delete s.secrets[id];
-    writeSecretsFile(s);
-    return true;
+    return modifySecretsFile(s => {
+      if (!Object.hasOwn(s.secrets, id)) return false;
+      delete s.secrets[id];
+      return true;
+    });
   },
   async list() { return syncReadable.listSync(); },
   async isAvailable(): Promise<SecretBackendAvailability> {
@@ -74,5 +101,16 @@ export function readSecretsFileRaw(): SecretsFile {
 }
 
 export function writeSecretsFileRaw(s: SecretsFile): void {
-  writeSecretsFile(s);
+  if (s.version !== SECRETS_VERSION || !s.secrets || typeof s.secrets !== 'object'
+    || Array.isArray(s.secrets) || Object.values(s.secrets).some(value => typeof value !== 'string')) {
+    throw new Error('invalid secrets file version or contents');
+  }
+  const path = secretsPath();
+  mkdirSync(dirname(path), { recursive: true });
+  const release = acquireLockSync(`${path}.lock`);
+  try {
+    writeSecretsFile(s);
+  } finally {
+    release();
+  }
 }

package/src/nexus/index.ts

@@ -15,7 +15,10 @@
 // In PR α `elanous nexus` is opt-in only; `elanous` continues to launch
 // the legacy dashboard.
 
+import { getElanousConfigDir } from '../elanous-config-dir.js';
 import { hostname } from 'node:os';
+import { request as httpRequest } from 'node:http';
+import { isIP } from 'node:net';
 import { resolveToolCwd } from '../boot/tool-cwd.js';
 import { acquireNexusLock, NexusLockError, readNexusLock, findNexusLifecycleState } from './supervisor/lock.js';
 import { classifyNexusStatus, type NexusHttpHealth } from './status-line.js';
@@ -1267,6 +1270,7 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
   let coordinatorPushWatcher: { stop(): void } | undefined;
   // V2.2-3 (2026-05-12) — NEXUS-hosted Discord workflow trigger bot.
   // Wired below once the workflow daemon is constructed.
+  let webPushDecisionTimer: ReturnType<typeof setInterval> | undefined;
   let workflowDiscordBot: NexusDiscordTriggerBotHandle | undefined;
   // V2.2-4 (2026-05-12) — NEXUS-hosted Telegram workflow trigger bot.
   let workflowTelegramBot: NexusTelegramTriggerBotHandle | undefined;
@@ -2108,7 +2112,9 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
           },
         } : {}),
         voiceAdapter,
-        ...buildNexusWsBridgeAuth(bearerToken),
+        // The verifier reads the token envelope from the same config dir the boot token was written to
+        // (ensureAuthToken) — default ~/.elanous would make an isolated daemon check the production envelope.
+        ...buildNexusWsBridgeAuth(bearerToken, { configDir: getElanousConfigDir() }),
       };
 
       metaApiOpts = {
@@ -2729,6 +2735,28 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
       console.warn(`[nexus] workflow daemon boot skipped: ${msg}`);
     }
 
+    // Decision cards use the same ledger and first-start baseline as the messaging transports.
+    if ((getUserConfig().raw?.decisions as { cards?: unknown } | undefined)?.cards !== false && !isAutonomousRunContext()) {
+      try {
+        const { DecisionCardService } = await import('../decisions/decision-cards.js');
+        const { webPushDecisionTransport } = await import('../decisions/web-push-decision-cards.js');
+        const { listSubscriptions } = await import('../web-push/subscriptions.js');
+        const { DecisionLedger } = await import('../decisions/decision-ledger.js');
+        const ledger = new DecisionLedger();
+        const service = new DecisionCardService({ transport: webPushDecisionTransport(ledger), ownerIds: [], ledger });
+        await service.tick();
+        webPushDecisionTimer = setInterval(() => {
+          void service.tick().catch((error: unknown) => {
+            debug.log('decisions.webpush', 'tick-failed', { reason: error instanceof Error ? error.message.slice(0, 80) : 'unknown' }, { level: 'warn' });
+          });
+        }, 20_000);
+        webPushDecisionTimer.unref();
+        debug.log('decisions.webpush', 'attached', { subscribers: listSubscriptions().length });
+      } catch (error) {
+        debug.log('decisions.webpush', 'attach-failed', { reason: error instanceof Error ? error.message.slice(0, 80) : 'unknown' }, { level: 'warn' });
+      }
+    }
+
     // W7-후속 (2026-05-12) — Outbound substrate boot. Builds the
     // OutboundRouter + iOS push channel + token store from user-config
     // `notifications.apns.*`. The token store is passed to the http
@@ -3339,6 +3367,7 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
         console.warn(`[nexus] continuation scheduler stop failed: ${(err as Error).message}`);
       }
     }
+    if (webPushDecisionTimer) { clearInterval(webPushDecisionTimer); webPushDecisionTimer = undefined; }
     // R5 — stop the dig-goal armer poller (no-op when never armed).
     if (digArmerHandle) { clearInterval(digArmerHandle); digArmerHandle = undefined; }
     if (replayArmerHandle) { clearInterval(replayArmerHandle); replayArmerHandle = undefined; }
@@ -3876,9 +3905,21 @@ async function probeNexusStatusHealth(runtime: NexusRuntimeMeta | null): Promise
     const healthUrl = new URL('http://localhost/v1/health');
     healthUrl.hostname = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
     healthUrl.port = String(runtime.httpPort);
-    const response = await fetch(healthUrl.href, {
-      signal: AbortSignal.timeout(NEXUS_STATUS_HEALTH_TIMEOUT_MS),
-    });
+    const signal = AbortSignal.timeout(NEXUS_STATUS_HEALTH_TIMEOUT_MS);
+    if (healthUrl.hostname === 'localhost' || healthUrl.hostname === '[::1]'
+      || (isIP(healthUrl.hostname) === 4 && healthUrl.hostname.startsWith('127.'))) {
+      // Bun fetch inherits HTTP_PROXY even for loopback; node:http opens a direct socket.
+      const ok = await new Promise<boolean>((resolve, reject) => {
+        const req = httpRequest(healthUrl, { signal }, (response) => {
+          response.resume();
+          resolve(response.statusCode !== undefined && response.statusCode >= 200 && response.statusCode < 300);
+        });
+        req.on('error', reject);
+        req.end();
+      });
+      return ok ? 'responsive' : 'silent';
+    }
+    const response = await fetch(healthUrl.href, { signal });
     return response.ok ? 'responsive' : 'silent';
   } catch {
     // The request could not complete, so retain unknown rather than infer listener silence.

package/src/onboarding/first-run-doctor.ts

@@ -0,0 +1,54 @@
+import { delimiter, join, win32 } from 'node:path';
+import { applyDoctorFixes, planDoctorFixes, type DoctorFixDeps, type DoctorFixItem } from '../cli/doctor-fix.js';
+import { staticToolBinDir } from '../cli/doctor-static-tools.js';
+import { debug } from '../debug/log.js';
+
+const AUTOMATIC = new Set<DoctorFixItem['id']>(['private-files', 'key-cache-permissions', 'static-tools']);
+const DEFERRED = new Set<DoctorFixItem['id']>(['install-path', 'bun-tmpdir']);
+const LATER_LINE = '나중에: elanous doctor --fix (셸 시작 파일 수정)';
+
+export interface FirstRunDoctorResult {
+  fixed: string[];
+  skipped: string[];
+  failed: string[];
+  later: string[];
+  lines: string[];
+}
+
+/** 첫 실행에서는 동의가 필요 없는 수리만 실행하고, 셸 시작 파일은 손대지 않는다. */
+export function runFirstRunDoctor(deps: DoctorFixDeps): FirstRunDoctorResult {
+  const result: FirstRunDoctorResult = { fixed: [], skipped: [], failed: [], later: [], lines: [] };
+  const record = (id: string, outcome: 'fixed' | 'skipped' | 'failed', reason?: string) => {
+    result[outcome].push(id);
+    if (outcome === 'failed') result.lines.push(`doctor: ${id} 수리 실패 — ${reason || '원인 불명'}`);
+    try { debug.log('doctor.first-run', outcome, { id }); } catch { /* 관측 실패가 첫 실행을 막지 않는다. */ }
+  };
+
+  try {
+    const windows = deps.readiness?.platform === 'win32';
+    const prefix = deps.readiness?.installPrefix;
+    const bin = typeof prefix === 'string' && prefix.trim()
+      ? windows ? win32.join(prefix.trim(), 'bin') : join(prefix.trim(), 'bin')
+      : staticToolBinDir(deps.env ?? process.env, deps.home);
+    const separator = windows ? ';' : delimiter;
+    const entries = (process.env.PATH ?? '').split(separator);
+    if (!entries.some((entry) => windows ? entry.toLowerCase() === bin.toLowerCase() : entry === bin)) {
+      process.env.PATH = [bin, process.env.PATH].filter(Boolean).join(separator);
+    }
+
+    const plan = planDoctorFixes(deps);
+    for (const item of plan.items) {
+      if (DEFERRED.has(item.id) && item.status === 'fixable') result.later.push(item.id);
+    }
+    const applied = applyDoctorFixes(deps, true, AUTOMATIC);
+    for (const item of applied.items) {
+      if (AUTOMATIC.has(item.id) && item.result === 'failed') record(item.id, 'failed', item.reason);
+      else if (AUTOMATIC.has(item.id) && item.result === 'fixed') record(item.id, 'fixed');
+      else record(item.id, 'skipped');
+    }
+  } catch {
+    record('doctor', 'failed', '계획 또는 적용 중 예외');
+  }
+  if (result.later.length) result.lines.push(LATER_LINE);
+  return result;
+}

package/src/onboarding/first-run.ts

@@ -0,0 +1,89 @@
+import * as readline from 'node:readline/promises';
+import { detectProviders, type DetectedProvider } from '../llm/provider-detect.js';
+import { debug } from '../debug/log.js';
+import { resolveProviderCredential } from '../llm/provider-credentials.js';
+import {
+  getUserConfig, saveUserConfig, userConfigPath,
+  type LLMProviderName, type UserConfig,
+} from '../user-config.js';
+
+export interface FirstRunDeps {
+  config?: UserConfig;
+  path?: string;
+  detectProviders?: () => Promise<DetectedProvider[]>;
+  isTTY?: boolean;
+  chooseProvider?: () => Promise<LLMProviderName | null>;
+  print?: (message: string) => void;
+  saveConfig?: (config: UserConfig, path: string) => void;
+}
+
+async function chooseProvider(): Promise<LLMProviderName | null> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question('Choose LLM (1 Codex, 2 Grok, 3 Claude; Enter to cancel): ')).trim();
+    return ({ '1': 'openai-codex', '2': 'grok', '3': 'anthropic' } as Record<string, LLMProviderName>)[answer] ?? null;
+  } finally {
+    rl.close();
+  }
+}
+
+export async function runFirstRun(deps: FirstRunDeps = {}): Promise<{
+  outcome: 'ready' | 'needs-llm' | 'cancelled'; provider?: string; inputs: number;
+}> {
+  const path = deps.path ?? userConfigPath();
+  const cfg = deps.config ?? getUserConfig(path);
+  const print = deps.print ?? console.log;
+  let detected: DetectedProvider[] = [];
+  try { detected = await (deps.detectProviders ?? detectProviders)(); }
+  catch { /* Detection is advisory; a TTY can still choose. */ }
+  const subscriptions = detected.filter((d) => d.available && (d.auth === 'oauth' || d.auth === 'agent-cli'));
+  const providers = subscriptions.map((d) => d.provider);
+  const observe = (event: 'detected' | 'chosen' | 'ready' | 'needs-llm', inputs: number) =>
+    debug.log('onboarding.first-run', event, { providers, inputs });
+  observe('detected', 0);
+  // An incomplete onboarding marker does not mean the user's LLM is unconfigured.
+  // Keep an already usable provider, key and model rather than replacing them with a detected subscription.
+  const existing = cfg.llm.provider !== 'auto'
+    ? resolveProviderCredential({ provider: cfg.llm.provider, rotation: cfg.llm.rotation,
+        baseProvider: cfg.llm.provider, baseApiKey: cfg.llm.apiKey })
+    : undefined;
+  const configured = existing && existing.source !== 'none'
+    ? cfg.llm.provider : undefined;
+  const picked = (['openai-codex', 'grok', 'claude-code', 'anthropic', 'gemini', 'openai', 'openrouter'] as const)
+    .find((name) => providers.includes(name));
+  let provider: LLMProviderName | null | undefined = configured ??
+    (picked === 'claude-code' ? 'anthropic' : picked as LLMProviderName | undefined);
+  let inputs = 0;
+  if (!provider) {
+    if ((deps.isTTY ?? process.stdin.isTTY) !== true) {
+      print('eln setup llm 으로 고르세요');
+      observe('needs-llm', 0);
+      return { outcome: 'needs-llm', inputs: 0 };
+    }
+    inputs = 1;
+    provider = await (deps.chooseProvider ?? chooseProvider)();
+    if (!provider) return { outcome: 'cancelled', inputs };
+    observe('chosen', inputs);
+  }
+  const credential = inputs === 1 || provider !== cfg.llm.provider
+    ? resolveProviderCredential({
+        provider, rotation: cfg.llm.rotation,
+        baseProvider: cfg.llm.provider, baseApiKey: cfg.llm.apiKey,
+      })
+    : undefined;
+  if (inputs === 1 && credential?.source === 'none') {
+    print('eln setup llm 으로 고르세요');
+    observe('needs-llm', inputs);
+    return { outcome: 'needs-llm', inputs };
+  }
+  (deps.saveConfig ?? saveUserConfig)({
+    ...cfg,
+    llm: { ...cfg.llm, provider,
+      ...(provider !== cfg.llm.provider ? { apiKey: credential?.apiKey, baseUrl: credential?.baseUrl, model: undefined } : {}),
+      ...(credential?.apiKey ? { apiKey: credential.apiKey } : {}),
+      ...(credential?.baseUrl ? { baseUrl: credential.baseUrl } : {}) },
+    onboarding: { ...cfg.onboarding, ready: true },
+  }, path);
+  observe('ready', inputs);
+  return { outcome: 'ready', provider, inputs };
+}

package/src/onboarding/lan-address.ts

@@ -0,0 +1,45 @@
+import { execFileSync } from 'node:child_process';
+import { networkInterfaces } from 'node:os';
+
+export function isPrivateIpv4(addr: string): boolean {
+  const parts = addr.split('.');
+  if (parts.length !== 4 || parts.some(part => !/^(0|[1-9]\d{0,2})$/.test(part) || Number(part) > 255)) return false;
+  const [a, b] = parts.map(Number);
+  return a === 10 || (a === 172 && b! >= 16 && b! <= 31) || (a === 192 && b === 168);
+}
+
+export function defaultRouteInterface(platform: NodeJS.Platform = process.platform): string | undefined {
+  try {
+    if (platform === 'darwin') {
+      return /^\s*interface:\s*(\S+)/m.exec(execFileSync('route', ['-n', 'get', 'default'], { encoding: 'utf8', timeout: 1000, stdio: ['ignore', 'pipe', 'ignore'] }))?.[1];
+    }
+    if (platform === 'linux') {
+      return /^default\s+.*?\bdev\s+(\S+)/m.exec(execFileSync('ip', ['route', 'show', 'default'], { encoding: 'utf8', timeout: 1000, stdio: ['ignore', 'pipe', 'ignore'] }))?.[1];
+    }
+  } catch { /* Route lookup is optional. */ }
+  return undefined;
+}
+
+export function pickLanAddress({ interfaces, defaultRouteInterface: route }: {
+  interfaces: ReturnType<typeof networkInterfaces>;
+  defaultRouteInterface?: string | (() => string | undefined);
+}): string | null {
+  const candidates: { name: string; address: string }[] = [];
+  for (const [name, addresses] of Object.entries(interfaces)) {
+    for (const info of addresses ?? []) {
+      if (info.family === 'IPv4' && !info.internal && isPrivateIpv4(info.address)) {
+        candidates.push({ name, address: info.address });
+      }
+    }
+  }
+  if (candidates.length === 0) return null;
+  let preferred: string | undefined;
+  try { preferred = typeof route === 'function' ? route() : route ?? defaultRouteInterface(); } catch { /* Use sorted candidates. */ }
+  candidates.sort((a, b) => a.name.localeCompare(b.name) || a.address.localeCompare(b.address));
+  return (candidates.find(candidate => candidate.name === preferred) ?? candidates[0])?.address ?? null;
+}
+
+export function isLanReachableBind(httpHost: string | undefined): boolean {
+  const host = httpHost?.trim() ?? '';
+  return host === '' || host === '0.0.0.0' || host === '::' || host === '[::]' || isPrivateIpv4(host);
+}