elanous 0.2.9 → 0.2.10

package/src/nexus/api/sessions-store.ts

@@ -18,6 +18,11 @@ import {
   isHarnessSessionOrigin,
   type SessionMeta,
 } from '../../session/index.js';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmdirSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { getProject } from '../../project/project-store.js';
+import { sessionRoot } from '../../session/index.js';
 import { checkAuth, type MetaApiOpts } from './meta-api.js';
 import { jsonResponse } from './http-server.js';
 
@@ -32,6 +37,7 @@ export interface SessionStoreCard {
    *  `harness` = 하니스 자식이 만든 세션. 기본 목록에서 숨기고 includeHarness=1 로 포함. */
   origin?: string;
   sourceKind?: string;
+  projectId?: string;
   createdAt: string;
   updatedAt: string;
   messageCount: number;
@@ -50,6 +56,7 @@ function toCard(m: SessionMeta, preview: string, nowMs: number): SessionStoreCar
     source: m.source,
     ...(m.origin ? { origin: m.origin } : {}),
     ...(m.sourceKind ? { sourceKind: m.sourceKind } : {}),
+    ...(m.projectId !== undefined ? { projectId: m.projectId } : {}),
     createdAt: m.createdAt,
     updatedAt: m.updatedAt,
     messageCount: m.messageCount,
@@ -82,11 +89,13 @@ export function handleSessionsStoreList(req: Request, opts: MetaApiOpts): Respon
   // 하니스 자식 세션(origin:'harness')은 기본 숨김 — includeHarness=1 로 포함.
   // 신분이 없는 옛 세션은 사람 대화로 본다(숨기지 않음). 제목 문면으로 판정하지 않는다.
   const includeHarness = url.searchParams.get('includeHarness') === '1';
+  const projectId = url.searchParams.get('projectId');
   const limit = Math.min(Math.max(Number(url.searchParams.get('limit')) || 100, 1), 300);
   const nowMs = Date.now();
 
   let metas = listSessions({
     limit: 600,
+    ...(projectId !== null ? { projectId } : {}),
     ...(includeOperational ? {} : { excludeSourceKinds: ['scheduled'] }),
     ...(includeHarness ? {} : { excludeOrigins: [HARNESS_SESSION_ORIGIN] }),
   }); // 이미 updatedAt DESC
@@ -157,6 +166,60 @@ export async function handleSessionsStoreFork(
   );
 }
 
+/** PATCH /v1/sessions/store/:id — only project membership; leave transcript and other meta untouched. */
+export async function handleSessionsStorePatch(req: Request, id: string, opts: MetaApiOpts): Promise<Response> {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (!id || id.includes('/') || id.includes('\\') || id.includes('..')) {
+    return jsonResponse({ ok: false, error: 'invalid_session_id' }, 400);
+  }
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return jsonResponse({ ok: false, error: 'invalid_json' }, 400); }
+  if (!body || typeof body !== 'object' || Array.isArray(body)
+    || !Object.hasOwn(body, 'projectId')
+    || Object.keys(body).some((key) => key !== 'projectId')) {
+    return jsonResponse({ ok: false, error: 'invalid_project_id' }, 400);
+  }
+  const projectId = (body as { projectId: unknown }).projectId;
+  if (projectId !== null && (typeof projectId !== 'string' || !getProject(projectId))) {
+    return jsonResponse({ ok: false, error: 'invalid_project_id' }, 400);
+  }
+
+  const root = sessionRoot();
+  const lock = join(root, '.index.lock');
+  const deadline = Date.now() + 10_000;
+  for (;;) {
+    try { mkdirSync(lock); break; }
+    catch {
+      if (!existsSync(lock)) continue;
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > 30_000) { rmdirSync(lock); continue; }
+      } catch { continue; }
+      if (Date.now() >= deadline) throw new Error(`timed out acquiring lock ${lock}`);
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
+  try {
+    const path = join(root, 'index.json');
+    const entries = JSON.parse(readFileSync(path, 'utf8')) as SessionMeta[];
+    const pos = entries.findIndex((meta) => meta.id === id);
+    if (pos < 0) return jsonResponse({ ok: false, error: 'not_found' }, 404);
+    const meta = { ...entries[pos] };
+    if (projectId === null) delete meta.projectId;
+    else meta.projectId = projectId;
+    entries[pos] = meta;
+    const temp = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+    writeFileSync(temp, JSON.stringify(entries, null, 2) + '\n', 'utf8');
+    renameSync(temp, path);
+    return jsonResponse({ ok: true, meta }, 200);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return jsonResponse({ ok: false, error: 'not_found' }, 404);
+    throw error;
+  } finally {
+    rmdirSync(lock);
+  }
+}
+
 /** DELETE /v1/sessions/store/:id — on-disk 세션 삭제(index.json + <id>.jsonl 제거).
  *  파괴적·복구불가. in-flight turn abort + in-memory history forget 도 fail-soft 로 동반. */
 export function handleSessionsStoreDelete(req: Request, id: string, opts: MetaApiOpts): Response {

package/src/nexus/api/setup-codex-login.ts

@@ -0,0 +1,160 @@
+import { debug } from '../../debug/log.js';
+import { loginWithCodexBrowser } from '../../oauth/codex-browser-login.js';
+import {
+  CODEX_DEVICE_LOGIN_URL,
+  exchangeDeviceAuthCode,
+  pollDeviceCode,
+  requestDeviceCode,
+} from '../../oauth/codex.js';
+import { expiresAtFromSeconds, saveTokens } from '../../oauth/store.js';
+import { getUserConfig, reloadUserConfig, saveUserConfig } from '../../user-config.js';
+
+type Mode = 'browser' | 'device';
+type CodexLoginStatus =
+  | { state: 'idle' }
+  | { state: 'pending'; mode: Mode; authorizeUrl?: string; userCode?: string; verificationUrl?: string }
+  | { state: 'ok'; mode: Mode }
+  | { state: 'error'; mode: Mode; error: string };
+
+const TIMEOUT_MS = 5 * 60_000;
+const SAFE_ERRORS = [
+  'timeout', 'authorization-denied', 'browser-unavailable', 'port-unavailable',
+  'token-exchange', 'device-code-failed', 'device-poll-failed', 'config-save-failed',
+] as const;
+
+type Failure = typeof SAFE_ERRORS[number];
+function reason(error: unknown, mode: Mode): Failure {
+  const message = error instanceof Error ? error.message : '';
+  for (const value of SAFE_ERRORS) if (message === value || message === `codex browser login failed: ${value}`) return value;
+  return mode === 'browser' ? 'browser-unavailable' : 'device-poll-failed';
+}
+
+interface LoginDeps {
+  browser: (openBrowser: (url: string) => boolean) => Promise<unknown>;
+  device: (ready: (userCode: string, verificationUrl: string) => void) => Promise<unknown>;
+  saveProvider: () => void;
+  observe: (event: 'started' | 'ok' | 'error', mode: Mode) => void;
+}
+
+async function deviceLogin(ready: (userCode: string, verificationUrl: string) => void): Promise<void> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  const fetchImpl = ((input, init) => fetch(input, { ...init, signal: controller.signal })) as typeof fetch;
+  try {
+    let code: Awaited<ReturnType<typeof requestDeviceCode>>;
+    try { code = await requestDeviceCode({ fetchImpl }); }
+    catch { throw new Error('device-code-failed'); }
+    if (controller.signal.aborted) throw new Error('timeout');
+    ready(code.user_code, code.verification_uri || CODEX_DEVICE_LOGIN_URL);
+    const interval = Math.max(3000, (code.interval ?? 0) * 1000);
+    const deadline = Date.now() + TIMEOUT_MS;
+    while (!controller.signal.aborted && Date.now() < deadline) {
+      await new Promise<void>((resolve) => setTimeout(resolve, Math.min(interval, Math.max(0, deadline - Date.now()))));
+      if (controller.signal.aborted || Date.now() >= deadline) break;
+      let result: Awaited<ReturnType<typeof pollDeviceCode>>;
+      try { result = await pollDeviceCode(code.device_auth_id, code.user_code, { fetchImpl }); }
+      catch { throw new Error('device-poll-failed'); }
+      if (!result) continue;
+      let token: Awaited<ReturnType<typeof exchangeDeviceAuthCode>>;
+      try { token = await exchangeDeviceAuthCode(result.authorization_code, result.code_verifier, { fetchImpl }); }
+      catch { throw new Error('token-exchange'); }
+      if (controller.signal.aborted) break;
+      saveTokens('openai-codex', {
+        accessToken: token.access_token,
+        refreshToken: token.refresh_token,
+        ...(token.id_token ? { idToken: token.id_token } : {}),
+        expiresAt: expiresAtFromSeconds(token.expires_in),
+        scope: token.scope,
+        tokenType: token.token_type ?? 'Bearer',
+      }, { authMode: 'chatgpt' });
+      return;
+    }
+    throw new Error('timeout');
+  } catch (error) {
+    if (controller.signal.aborted) throw new Error('timeout');
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function saveCodexProvider(): void {
+  const cur = getUserConfig();
+  saveUserConfig({ ...cur, llm: { ...cur.llm, provider: 'openai-codex', apiKey: undefined, baseUrl: undefined, model: undefined } });
+  reloadUserConfig();
+}
+
+const defaultDeps: LoginDeps = {
+  browser: (openBrowser) => loginWithCodexBrowser({ openBrowser, timeoutMs: TIMEOUT_MS }),
+  device: deviceLogin,
+  saveProvider: saveCodexProvider,
+  observe: (event, mode) => { debug.log('setup.codex-login', event, { mode }); },
+};
+
+function json(body: CodexLoginStatus | { error: string }, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status, headers: { 'content-type': 'application/json; charset=utf-8', 'access-control-allow-origin': '*' },
+  });
+}
+
+/** One in-process login survives leaving or reloading the setup page. */
+export function createCodexLoginHandlers(deps: LoginDeps = defaultDeps) {
+  let status: CodexLoginStatus = { state: 'idle' };
+  let preparing: Promise<void> | undefined;
+  let generation = 0;
+
+  const get = (): Response => json(status);
+
+  const post = async (req: Request): Promise<Response> => {
+    let body: unknown;
+    try { body = await req.json(); } catch { return json({ error: 'invalid-json' }, 400); }
+    const mode = body && typeof body === 'object' && 'mode' in body ? body.mode : undefined;
+    if (mode !== 'browser' && mode !== 'device') return json({ error: 'invalid-mode' }, 400);
+    // Same method again → the login already in flight. A different method → start over; the older
+    // attempt's result is ignored (generation). Browser → device is the recovery path when a popup
+    // was blocked; device needs no local port, so it never collides with the browser's callback server.
+    if (status.state === 'pending' && status.mode === mode) {
+      if (preparing) await preparing;
+      return json(status);
+    }
+
+    status = { state: 'pending', mode };
+    const attempt = ++generation;
+    deps.observe('started', mode);
+    let resolveReady!: () => void;
+    preparing = new Promise<void>((resolve) => { resolveReady = resolve; });
+    const ready = (fields: Pick<Extract<CodexLoginStatus, { state: 'pending' }>, 'authorizeUrl' | 'userCode' | 'verificationUrl'>) => {
+      if (generation === attempt && status.state === 'pending' && status.mode === mode) {
+        status = { ...status, ...fields };
+        resolveReady();
+      }
+    };
+    void (async () => {
+      try {
+        if (mode === 'browser') {
+          await deps.browser((url) => { ready({ authorizeUrl: url }); return true; });
+        } else {
+          await deps.device((userCode, verificationUrl) => ready({ userCode, verificationUrl }));
+        }
+        if (generation !== attempt) return;
+        try { deps.saveProvider(); } catch { throw new Error('config-save-failed'); }
+        status = { state: 'ok', mode };
+        deps.observe('ok', mode);
+      } catch (error) {
+        if (generation !== attempt) return;
+        status = { state: 'error', mode, error: reason(error, mode) };
+        deps.observe('error', mode);
+      } finally {
+        resolveReady();
+        if (generation === attempt) preparing = undefined;
+      }
+    })();
+    await preparing;
+    return json(status);
+  };
+  return { get, post };
+}
+
+const login = createCodexLoginHandlers();
+export const handleSetupCodexLoginGet = login.get;
+export const handleSetupCodexLoginPost = login.post;

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/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.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);
+}