elanous 0.2.9 → 0.2.11

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;
@@ -1945,10 +1949,12 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
     const tab = registry.get(tabId);
     if (!tab || tab.spec.kind !== 'webterm') return;
     const cwdMeta = (tab.spec.meta as { cwd?: string } | undefined)?.cwd;
+    const projectSessionId = (tab.spec.meta as { sessionId?: string } | undefined)?.sessionId;
     const backendFactory = effectiveWebtermSpawn
       ? () => {
           const decided = resolveWebtermCwd({
             ...(cwdMeta ? { tabCwd: cwdMeta } : {}),
+            ...(projectSessionId ? { sessionId: projectSessionId } : {}),
             ...(runtimeToolCwd ? { toolCwd: runtimeToolCwd } : {}),
             instance: resolveCurrentInstance(),
             processCwd: process.cwd(),
@@ -2108,7 +2114,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 +2737,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 +3369,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 +3907,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/nexus/kinds/webterm.ts

@@ -24,6 +24,7 @@ export interface WebtermTabOpts {
   id?: string;          // default: 'webterm:1'
   label?: string;
   cwd?: string;
+  sessionId?: string;
 }
 
 export const WEBTERM_KIND: TabKind = 'webterm';
@@ -34,7 +35,7 @@ export function createWebtermTabSpec(opts: WebtermTabOpts = {}): TabSpec {
     id,
     kind: WEBTERM_KIND,
     label: opts.label ?? id,
-    ...(opts.cwd ? { meta: { cwd: opts.cwd } } : {}),
+    ...(opts.cwd || opts.sessionId ? { meta: { ...(opts.cwd ? { cwd: opts.cwd } : {}), ...(opts.sessionId ? { sessionId: opts.sessionId } : {}) } } : {}),
   };
 }
 

package/src/nexus/webterm/pty.ts

@@ -31,6 +31,7 @@ import { startPty as realStartPty, onPtyEvent as realOnPtyEvent } from '../../pt
 import type { StartOpts, PtyHandle, PtyEvent } from '../../pty-shell/registry.js';
 
 import { debug } from '../../debug/log.js';
+import { resolveSessionProjectContext } from '../../project/session-context.js';
 
 // ── PtyBackend interface ─────────────────────────────────────────────
 
@@ -229,15 +230,18 @@ export function createRegistryBackend(
 }
 
 /** 웹 터미널 셸이 열릴 작업 디렉토리를 정한다(실행 맥락 SSOT: 맥락은 «한 번» 정해지고 인자로 내려간다).
- *  순서: 탭이 명시한 cwd → 데몬이 정한 tool cwd → (격리 우주면) 우주 뿌리 → 데몬 프로세스 cwd.
+ *  순서: 탭이 명시한 cwd → 대화 프로젝트 폴더 → 데몬 tool cwd → (격리 우주면) 우주 뿌리 → 프로세스 cwd.
  *  ⛔ 격리(test) 우주에서 `process.cwd()` 로 떨어지면 셸이 «사람 작업 트리»에서 열린다(🅕 실측 2026-09-26). */
 export function resolveWebtermCwd(input: {
   tabCwd?: string;
+  sessionId?: string;
   toolCwd?: string;
   instance: { kind: 'prod' | 'test'; root: string };
   processCwd: string;
-}): { cwd: string; source: 'tab' | 'tool-cwd' | 'isolated-root' | 'process-cwd' } {
+}): { cwd: string; source: 'tab' | 'project' | 'tool-cwd' | 'isolated-root' | 'process-cwd' } {
   if (input.tabCwd) return { cwd: input.tabCwd, source: 'tab' };
+  const projectCwd = resolveSessionProjectContext(input.sessionId)?.cwd;
+  if (projectCwd) return { cwd: projectCwd, source: 'project' };
   if (input.toolCwd) return { cwd: input.toolCwd, source: 'tool-cwd' };
   if (input.instance.kind === 'test') return { cwd: input.instance.root, source: 'isolated-root' };
   return { cwd: input.processCwd, source: 'process-cwd' };

package/src/onboarding/cli-auth-status.ts

@@ -0,0 +1,80 @@
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+
+export type SkillCli = 'gh' | 'gws' | 'op' | 'himalaya';
+
+export interface CliAuthStatus {
+  cli: SkillCli;
+  found: boolean;
+  authenticated: boolean;
+  skippedReason?: string;
+}
+
+export interface CliAuthStatusDeps {
+  path?: string;
+  findExecutable?: (name: SkillCli, path: string) => string | null;
+  runStatus?: (executable: string, args: readonly string[]) => { status: number | null; stdout?: string; error?: unknown };
+}
+
+const STATUS_COMMANDS: readonly { cli: SkillCli; args: readonly string[] }[] = [
+  { cli: 'gh', args: ['auth', 'status'] },
+  { cli: 'gws', args: ['auth', 'status'] },
+  { cli: 'op', args: ['whoami'] },
+  { cli: 'himalaya', args: ['account', 'check'] },
+];
+
+function findOnPath(name: SkillCli, path: string): string | null {
+  for (const directory of path.split(delimiter).filter(Boolean)) {
+    const executable = join(directory, name);
+    try {
+      accessSync(executable, constants.X_OK);
+      if (statSync(executable).isFile()) return executable;
+    } catch { /* Try the next PATH entry. */ }
+  }
+  return null;
+}
+
+function runReadOnlyStatus(executable: string, args: readonly string[]) {
+  const result = spawnSync(executable, [...args], {
+    encoding: 'utf8', timeout: 5_000, maxBuffer: 64 * 1024,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  return { status: result.status, stdout: result.stdout, error: result.error };
+}
+
+function gwsHasSession(stdout: string | undefined): boolean {
+  try {
+    const status: unknown = JSON.parse(stdout ?? '');
+    if (!status || typeof status !== 'object' || Array.isArray(status)) return false;
+    const auth = status as Record<string, unknown>;
+    return auth.token_valid === true;
+  } catch {
+    return false;
+  }
+}
+
+/** No credential-file reads, login calls, prompts, or token-bearing output leave this probe. */
+export function detectSkillCliAuth(deps: CliAuthStatusDeps = {}): CliAuthStatus[] {
+  const path = deps.path ?? process.env.PATH ?? '';
+  const find = deps.findExecutable ?? findOnPath;
+  const run = deps.runStatus ?? runReadOnlyStatus;
+  return STATUS_COMMANDS.map(({ cli, args }) => {
+    let executable: string | null;
+    try { executable = find(cli, path); }
+    catch { executable = null; }
+    if (!executable) return { cli, found: false, authenticated: false, skippedReason: 'not on PATH' };
+    try {
+      const result = run(executable, args);
+      if (result.error || result.status === null) {
+        return { cli, found: true, authenticated: false, skippedReason: 'status check unavailable' };
+      }
+      if (result.status !== 0 || (cli === 'gws' && !gwsHasSession(result.stdout))) {
+        return { cli, found: true, authenticated: false, skippedReason: 'not authenticated' };
+      }
+      return { cli, found: true, authenticated: true };
+    } catch {
+      return { cli, found: true, authenticated: false, skippedReason: 'status check unavailable' };
+    }
+  });
+}

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

package/src/onboarding/voice-ai.ts

@@ -154,12 +154,12 @@ export async function askVoiceAI(
 
   if (mode === 'preset') {
     // Phase 2 catalog isn't shipped yet; the wizard records the intent
-    // by keeping the user on Smart defaults but tagging persona='power'
+    // by keeping the user on Smart defaults but tagging profile='power'
     // so the auto-suggest hint in PWA opens the preset card directly.
     io.print('  (Preset catalog ships in Phase 2 · for now Smart defaults stay active.)');
     io.print('  elanous has noted your preference — preset hints will appear when ready.');
     return {
-      modelTier: { persona: 'power' },
+      modelTier: { profile: 'power' },
     };
   }
 
@@ -175,7 +175,7 @@ export async function askVoiceAI(
 
   const answer: VoiceAIAnswer = {
     modelTier: {
-      persona: 'custom',
+      profile: 'custom',
       voice: { stt: tier as ModelTier },
     },
   };

package/src/onboarding/web-first.ts

@@ -1,62 +1,150 @@
 import { spawnSync } from 'node:child_process';
+import { hostname, networkInterfaces, userInfo } from 'node:os';
+import { findNexusLifecycleState } from '../nexus/supervisor/lock.js';
+import { isLanReachableBind, isPrivateIpv4, pickLanAddress } from './lan-address.js';
 import { isHeadlessEnv } from '../acp/codex-auth.js';
-import { runNexusShow, type NexusShowResult } from '../cli/nexus-show.js';
+import { runBgLaunch, type BgLaunchResult } from '../cli/bg-launch.js';
+import { joinRestHealthUrl, runNexusShow, type NexusShowResult } from '../cli/nexus-show.js';
+import { issueSetupLinkToken } from '../auth/setup-link-tokens.js';
 import { debug } from '../debug/log.js';
 import { browserUnavailableReason } from '../oauth/browser-availability.js';
 import type { UserConfig } from '../user-config.js';
 
 export interface WebFirstSetupDeps {
   config: Pick<UserConfig, 'onboarding'>;
+  /** Whether a person is at a terminal (stdin TTY). Without one the web path only uses a daemon that is already up. */
   isTty?: boolean;
   terminal?: boolean;
+  startedAt?: number;
   showNexus?: () => Promise<NexusShowResult>;
+  startDaemon?: () => Promise<BgLaunchResult>;
+  probeHealth?: (url: string, timeoutMs: number) => Promise<boolean>;
   issueSetupLinkToken?: () => Promise<string | { token: string }>;
   renderQr?: (link: string) => string | undefined;
   openBrowser?: (link: string) => boolean;
   isHeadless?: () => boolean;
   browserEnv?: NodeJS.ProcessEnv;
   browserPlatform?: NodeJS.Platform;
+  httpHost?: () => string | undefined;
+  interfaces?: typeof networkInterfaces;
+  defaultRouteInterface?: () => string | undefined;
+  hostname?: typeof hostname;
+  username?: () => string;
   print?: (line: string) => void;
 }
 
+const STARTUP_TIMEOUT_MS = 12_000;
+
+async function probeHealth(url: string, timeoutMs: number): Promise<boolean> {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
 function setupUrl(pwa: string, token: string): string {
   return `${pwa.replace(/\/app\/?$/, '').replace(/\/$/, '')}/setup#t=${encodeURIComponent(token)}`;
 }
 
 export async function runWebFirstSetup(deps: WebFirstSetupDeps): Promise<'link-shown' | 'fallback'> {
-  const observe = (event: 'link-shown' | 'fallback', reason?: string, qr = false, browserOpened = false, remote: 'loopback' | 'tailnet' = 'loopback') => {
-    try { debug.log('onboarding.web-first', event, { ...(reason ? { reason } : {}), qr, browserOpened, remote }); }
+  const startedAt = deps.startedAt ?? Date.now();
+  const print = deps.print ?? console.log;
+  const observe = (event: 'link-shown' | 'fallback', reason?: string, qr = false, browserOpened = false, remote: 'loopback' | 'tailnet' = 'loopback', ms?: number, lan?: 'shown' | 'loopback-bind' | 'no-address', ssh?: boolean) => {
+    try { debug.log('onboarding.web-first', event, { ...(reason ? { reason } : {}), qr, browserOpened, remote, ...(ms !== undefined ? { ms } : {}), ...(lan ? { lan, ssh } : {}) }); }
     catch { /* Observability must not block onboarding. */ }
   };
-  if (deps.config.onboarding.webFirst !== true) { observe('fallback', 'disabled'); return 'fallback'; }
-  if ((deps.isTty ?? (process.stdin.isTTY === true)) !== true) { observe('fallback', 'non-tty'); return 'fallback'; }
+  const fallback = (reason: string): 'fallback' => {
+    print(`웹 셋업을 사용할 수 없습니다 (${reason}). 터미널 설정으로 전환합니다.`);
+    observe('fallback', reason);
+    return 'fallback';
+  };
+  if (deps.config.onboarding.webFirst === false) { observe('fallback', 'disabled'); return 'fallback'; }
   if (deps.terminal) { observe('fallback', 'terminal'); return 'fallback'; }
 
-  let shown: NexusShowResult;
-  try {
-    shown = await (deps.showNexus ?? (() => runNexusShow({ format: 'json', out: { log: () => {}, error: () => {} } })))();
-  } catch { observe('fallback', 'daemon-unavailable'); return 'fallback'; }
-  const running = shown.status === 'unregistered' || (shown.status === 'registered' && shown.instance?.alive === true);
-  if (!running || !shown.urls?.pwa.loopback) { observe('fallback', 'daemon-unavailable'); return 'fallback'; }
+  const show = deps.showNexus ?? (() => runNexusShow({ format: 'json', out: { log: () => {}, error: () => {} } }));
+  let shown: NexusShowResult | undefined;
+  try { shown = await show(); } catch { /* A missing daemon may make inspection fail. */ }
+  const running = shown?.status === 'unregistered' || (shown?.status === 'registered' && shown.instance?.alive === true);
+  // A script, pipe or CI run never starts a daemon on its own: without a terminal the web path
+  // only uses a daemon that already answers health once. (install.sh runs first setup with
+  // stdin on /dev/tty, so the install → web path still starts one.)
+  if ((deps.isTty ?? (process.stdin.isTTY === true)) !== true) {
+    const rest = running ? shown?.urls?.rest.loopback : undefined;
+    const up = rest && shown?.urls?.pwa.loopback
+      ? await (deps.probeHealth ?? probeHealth)(joinRestHealthUrl(rest), 500) : false;
+    if (!up) { observe('fallback', 'non-tty'); return 'fallback'; }
+  }
+  const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+  if (!running || !shown?.urls?.pwa.loopback) {
+    let launch: BgLaunchResult;
+    try {
+      launch = await (deps.startDaemon ?? (() => runBgLaunch({ out: { log: () => {}, error: () => {} } })))();
+    } catch { return fallback('daemon-start-failed'); }
+    if (launch.exitCode !== 0) return fallback('daemon-start-failed');
+  }
+
+  let healthy = false;
+  while (Date.now() < deadline) {
+    try {
+      shown = await show();
+      const live = shown.status === 'unregistered' || (shown.status === 'registered' && shown.instance?.alive === true);
+      if (live && shown.urls?.pwa.loopback && shown.urls.rest.loopback) {
+        const remaining = deadline - Date.now();
+        if (remaining > 0 && await (deps.probeHealth ?? probeHealth)(joinRestHealthUrl(shown.urls.rest.loopback), Math.min(remaining, 500))) {
+          healthy = true;
+          break;
+        }
+      }
+    } catch { /* A daemon may not have published its URLs yet. */ }
+    const remaining = deadline - Date.now();
+    if (remaining > 0) await Bun.sleep(Math.min(200, remaining));
+  }
+  if (!healthy) return fallback(running ? 'daemon-health-unavailable' : 'daemon-health-timeout');
+
+  if (!shown?.urls?.pwa.loopback) return fallback('daemon-unavailable');
 
   let token: string;
   try {
-    const issue = deps.issueSetupLinkToken ?? (async () => {
-      const modulePath = '../auth/setup-link-token.js';
-      const mod = await import(modulePath) as { issueSetupLinkToken?: (options: Record<string, never>) => Promise<string | { token: string }> };
-      if (typeof mod.issueSetupLinkToken !== 'function') throw new Error('issuer-missing');
-      return mod.issueSetupLinkToken({});
-    });
-    const issued = await issue();
+    const issued = await (deps.issueSetupLinkToken ?? (() => Promise.resolve(issueSetupLinkToken({}))))();
     token = typeof issued === 'string' ? issued : issued?.token;
     if (!token) throw new Error('issuer-missing');
-  } catch { observe('fallback', 'issuer-missing'); return 'fallback'; }
+  } catch { return fallback('issuer-missing'); }
 
-  const print = deps.print ?? console.log;
   const link = setupUrl(shown.urls.pwa.loopback, token);
-  const phoneLink = shown.urls.pwa.tailnet ? setupUrl(shown.urls.pwa.tailnet, token) : undefined;
+  const localUrl = new URL(shown.urls.pwa.loopback);
+  const port = localUrl.port || (localUrl.protocol === 'https:' ? '443' : '80');
+  let httpHost: string | undefined;
+  try { httpHost = (deps.httpHost ?? (() => findNexusLifecycleState()?.runtime?.httpHost))(); }
+  catch { /* Unknown bind must not produce a LAN link. */ }
+  const confirmedBind = typeof httpHost === 'string';
+  const reachable = confirmedBind && isLanReachableBind(httpHost);
+  let lanAddress: string | null = null;
+  if (reachable && httpHost !== undefined) {
+    if (isPrivateIpv4(httpHost.trim())) {
+      lanAddress = httpHost.trim();
+    } else {
+      try {
+        lanAddress = pickLanAddress({
+          interfaces: (deps.interfaces ?? networkInterfaces)(),
+          defaultRouteInterface: deps.defaultRouteInterface,
+        });
+      } catch { /* Optional LAN discovery must not block the local setup link. */ }
+    }
+  }
+  const lan: 'shown' | 'loopback-bind' | 'no-address' = !confirmedBind ? 'no-address' : !reachable ? 'loopback-bind' : lanAddress ? 'shown' : 'no-address';
+  const lanLink = lanAddress ? setupUrl(`http://${lanAddress}:${port}/app/`, token) : undefined;
+  const phoneLink = shown.urls.pwa.tailnet ? setupUrl(shown.urls.pwa.tailnet, token) : lanLink;
   print('브라우저에서 셋업을 이어가세요');
   print(link);
+  if (lanLink) {
+    print(`같은 와이파이의 폰이면: ${lanLink}`);
+    print('이 링크는 10분 안에 한 번만 열 수 있습니다');
+  } else if (lan === 'loopback-bind') {
+    print('같은 와이파이에서 열려면 `elanous nexus run` 을 루프백 없이 다시 띄우세요');
+  }
+  const linkShownMs = Date.now() - startedAt;
   let qr = false;
   if (phoneLink) {
     try {
@@ -66,14 +154,16 @@ export async function runWebFirstSetup(deps: WebFirstSetupDeps): Promise<'link-s
       }))(phoneLink);
       if (rendered) {
         print(rendered);
-        print('같은 와이파이·tailnet 의 폰 카메라로 스캔하세요');
+        print(shown.urls.pwa.tailnet ? '같은 와이파이·tailnet 의 폰 카메라로 스캔하세요' : '같은 와이파이의 폰 카메라로 스캔하세요');
         qr = true;
       }
     } catch { /* QR is optional. */ }
   }
   print('터미널에서 하려면: `elanous setup --terminal`');
   let browserOpened = false;
-  const why = browserUnavailableReason(deps.browserEnv ?? process.env, deps.browserPlatform ?? process.platform);
+  const env = deps.browserEnv ?? process.env;
+  const ssh = !!(env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY);
+  const why = browserUnavailableReason(env, deps.browserPlatform ?? process.platform);
   if (why) {
     print(why);
     debug.log('browser.open', 'skipped', { reason: why.includes('ssh') ? 'ssh' : 'no-display' });
@@ -85,6 +175,11 @@ export async function runWebFirstSetup(deps: WebFirstSetupDeps): Promise<'link-s
       }))(link);
     } catch { /* The displayed link remains usable. */ }
   }
-  observe('link-shown', undefined, qr, browserOpened, phoneLink ? 'tailnet' : 'loopback');
+  if (ssh) {
+    try {
+      print(`ssh -L ${port}:localhost:${port} ${(deps.username ?? (() => userInfo().username))()}@${(deps.hostname ?? hostname)()}`);
+    } catch { /* Optional SSH guidance must not block the setup link. */ }
+  }
+  observe('link-shown', undefined, qr, browserOpened, shown.urls.pwa.tailnet ? 'tailnet' : 'loopback', linkShownMs, lan, ssh);
   return 'link-shown';
 }

package/src/onboarding.ts

@@ -1656,6 +1656,10 @@ export function needsOnboarding(cfg: UserConfig): boolean {
   return !cfg.onboarding.completed;
 }
 
+export function needsFirstRun(cfg: UserConfig): boolean {
+  return !cfg.onboarding.completed && cfg.onboarding.ready !== true;
+}
+
 /** γ (2026-04-28) · per-step wizard. Runs ONE of the 5 steps,
  *  preserving every other field. Used by:
  *