elanous 0.2.34 → 0.2.36

package/src/nexus/boot/register-mcp-clients.ts

@@ -28,7 +28,7 @@
 //     daemon exit.
 
 import type { McpServerSpec } from '../../user-config.js';
-import { McpClient, McpConnectionError, type McpToolCallResult } from '../../mcp/client.js';
+import { McpClient, McpConnectionError, type McpTool, type McpToolCallResult } from '../../mcp/client.js';
 import {
   createMcpProxyRuntime,
   createMcpToolAuthorizer,
@@ -36,13 +36,13 @@ import {
 import { registerToolRuntime, unregisterToolRuntime } from '../../tool-runtime/registry.js';
 import { debug, redactSecretText } from '../../debug/log.js';
 import { elanousStateRoot } from '../../autopilot/state-paths.js';
-import { spawn as nodeSpawn } from 'node:child_process';
+import { spawn as nodeSpawn, type ChildProcess } from 'node:child_process';
 import { listNodeKinds } from '../../graph-kinds/registry.js';
 import { syncInstalledPluginNodes } from '../../graph-kinds/installed-plugin-nodes.js';
 import { listInstalledPlugins } from '../../plugins/install/plugin-install.js';
 import { pluginEnv, credentialStatus } from '../../plugins/install/plugin-credentials.js';
-import { existsSync, realpathSync } from 'node:fs';
-import { resolve, sep } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
 
 export interface McpClientsHandle {
   /** Live clients (one per successfully started server). */
@@ -56,6 +56,9 @@ export interface McpClientsHandle {
   //    ⇒ 노출하지 않는다. 허가 상태는 「등록된 런타임이 거부하나」로 «행동»으로 관측한다.
   /** Stop all clients gracefully and revoke this handle's grants. Safe to call multiple times. */
   shutdown(): Promise<void>;
+  /** 동기 마지막 수단 — 프로세스 exit 훅은 `await` 할 수 없다. 살아 있는 자식에
+   *  SIGTERM 만 «즉시» 쏘고 신호를 보낸 수를 돌려준다(유예·SIGKILL 은 `shutdown` 몫). */
+  terminateChildrenSync?(): number;
 }
 
 export interface McpServerBootResult {
@@ -65,6 +68,10 @@ export interface McpServerBootResult {
   status: 'ready' | 'disabled' | 'failed';
   /** Number of tools registered from this server. 0 unless status=='ready'. */
   toolCount: number;
+  /** When status=='ready' under `lazy`: the tools above were announced from the
+   *  cached tool index and the child has NOT been spawned yet — the first
+   *  `callTool` on one of them spawns it (once). Absent = spawned eagerly. */
+  deferred?: boolean;
   /** When status=='failed', the error message captured (string only —
    *  callers should not depend on Error identity). */
   reason?: string;
@@ -126,8 +133,33 @@ export interface RegisterMcpClientsOpts {
   setTimeoutFn?: (cb: () => void, ms: number) => { unref?(): void };
   /** Test seam — replaces `clearTimeout`. */
   clearTimeoutFn?: (handle: { unref?(): void }) => void;
+  /** CLASSIC-IDLE-MCP-LAZY (0.2.35) — classic TUI 백그라운드 경량화.
+   *  true 면 자식은 «기동 때»가 아니라 «첫 도구 호출» 때 한 번 뜬다.
+   *  그 전까지 알리는 툴 «목록»은 지난 부팅이 적어 둔 인덱스
+   *  (`MCP_TOOL_INDEX_FILENAME`) 그대로다 — 목록·권한은 무변경.
+   *  인덱스가 없는 서버(콜드 스타트)는 종전대로 즉시 기동하고 인덱스를 적는다. */
+  lazy?: boolean;
+  /** `lazy` 가 읽고 쓰는 툴 인덱스. 기본은 상태 루트의 `mcp-tool-index.json`. */
+  toolIndexStore?: McpToolIndexStore;
+  /** `lazy` 자식의 SIGTERM→SIGKILL 유예(ms). 기본 2500 — 종료 3초 계약 안쪽. */
+  lazyShutdownGraceMs?: number;
 }
 
+/** 한 서버가 지난 부팅에서 알린 툴 목록. `mcp-tool-index.json` 의 값. */
+export type McpToolIndex = Record<string, McpTool[]>;
+
+/** 툴 목록 캐시의 읽기/쓰기 자리 — 테스트가 임시 저장소로 갈아 끼운다. */
+export interface McpToolIndexStore {
+  read(): McpToolIndex;
+  write(index: McpToolIndex): void;
+}
+
+export const MCP_TOOL_INDEX_FILENAME = 'mcp-tool-index.json';
+
+/** 지연 기동 자식의 정리 유예. `McpClient` 기본 5000ms 는 「SIGTERM 3초 안에
+ *  안 끝남」이던 classic 종료 계약을 넘긴다 — 2500ms 면 SIGKILL 까지 3초 안쪽. */
+const DEFAULT_LAZY_SHUTDOWN_GRACE_MS = 2500;
+
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 8000;
 
 /** Race `op` against a timeout. Resolves to `op` on success; rejects
@@ -151,6 +183,60 @@ function withTimeout<T>(
   });
 }
 
+type DeferredInner = Pick<McpClient, 'start' | 'listTools' | 'callTool' | 'dispose'>;
+
+/** 첫 도구 호출까지 자식을 띄우지 않는 MCP 클라이언트 프록시.
+ *  - `callTool` 이 «한 번» 기동하고 동시 호출은 같은 기동을 기다린다.
+ *  - 기동 실패는 캐시하지 않는다 — 자식이 늦게 뜨면 다음 호출이 다시 시도한다.
+ *  - `dispose()` 는 진행 중 기동을 먼저 기다린다 — 자식이 새지 않는다. */
+class DeferredMcpClient implements DeferredInner {
+  private pending: Promise<void> | null = null;
+  private started = false;
+  private disposed = false;
+
+  constructor(
+    private readonly inner: DeferredInner,
+    private readonly boot: () => Promise<void>,
+    private readonly serverId: string,
+  ) {}
+
+  get spawned(): boolean { return this.started; }
+
+  async start(): Promise<void> { await this.ensureStarted(); }
+
+  async listTools(): Promise<McpTool[]> {
+    await this.ensureStarted();
+    return this.inner.listTools();
+  }
+
+  async callTool(name: string, args: Record<string, unknown>): Promise<McpToolCallResult> {
+    await this.ensureStarted();
+    // ⚠️ 기동 «뒤»의 inner.callTool 을 부른다 — 자격증명 마스킹 래퍼가
+    //    createClient 직후 client.callTool 에 씌워지므로 그 래퍼를 탄다.
+    return this.inner.callTool(name, args);
+  }
+
+  async dispose(): Promise<void> {
+    this.disposed = true;
+    if (this.pending) {
+      try { await this.pending; } catch { /* 기동 실패는 정리를 막지 않는다 */ }
+    }
+    try { await this.inner.dispose(); } catch { /* dispose() is best-effort */ }
+  }
+
+  private async ensureStarted(): Promise<void> {
+    if (this.disposed) {
+      throw new Error(`mcp.${this.serverId}: lazy client was disposed before its first tool call`);
+    }
+    if (this.started) return;
+    if (!this.pending) {
+      this.pending = this.boot().then(() => { this.started = true; });
+      this.pending.catch(() => { this.pending = null; });
+    }
+    await this.pending;
+  }
+}
+
 export interface McpBootLogger {
   info(line: string): void;
   warn(line: string): void;
@@ -196,6 +282,9 @@ export async function registerMcpClients(
       debug.log('mcp.client.boot', event, { id, ...safe });
     } catch { /* logger must never throw the boot */ }
   };
+  // 이 부팅이 띄운 자식들. 지연 기동이면 «첫 도구 호출» 뒤에야 채워지고,
+  // 프로세스가 그냥 죽는 경로(exit 훅)에서는 여기 남은 자식에 SIGTERM 을 쏜다.
+  const spawnedChildren = new Set<ChildProcess>();
   const createClient =
     opts.createClient ??
     ((spec: McpServerSpec) => {
@@ -221,6 +310,8 @@ export async function registerMcpClients(
       const selected = commandOwners.length === 1 && owners.length === 1 && owners[0] === commandOwners[0]
         ? commandOwners[0] : undefined;
       return new McpClient({ id: spec.id, command: spec.command, logger: bootLogger(spec.id),
+        // 지연 기동이면 정리 유예를 좁힌다 — classic 종료는 3초 안에 끝나야 한다.
+        ...(opts.lazy === true ? { shutdownGraceMs: opts.lazyShutdownGraceMs ?? DEFAULT_LAZY_SHUTDOWN_GRACE_MS } : {}),
         spawn: (cmd, args) => {
           const declaredEnv = [...new Set(listInstalledPlugins(root).map(item => item.name))]
             .flatMap(name => credentialStatus(name, root).fields.map(field => field.env));
@@ -234,7 +325,10 @@ export async function registerMcpClients(
             Object.assign(childEnv, env);
             injectedValuesByServer.set(spec.id, Object.values(env));
           }
-          return nodeSpawn(cmd, args, { stdio: ['pipe', 'pipe', 'pipe'], env: childEnv });
+          const child = nodeSpawn(cmd, args, { stdio: ['pipe', 'pipe', 'pipe'], env: childEnv });
+          spawnedChildren.add(child);
+          child.once('exit', () => { spawnedChildren.delete(child); });
+          return child;
         },
       });
     });
@@ -252,6 +346,66 @@ export async function registerMcpClients(
   const perServer: Record<string, McpServerBootResult> = {};
   let registered = 0;
 
+  // ── CLASSIC-IDLE-MCP-LAZY ────────────────────────────────────────────────
+  // classic TUI 는 MCP 서버 둘(xcodebuildmcp · aside mcp)을 «기동 때» 띄워
+  // 상주시켰다 — TUI 하나당 node⊕aside 자손 RSS 약 267MB, SIGTERM 3초 안에
+  // 안 끝남(0.2.35 OP 실측). ⇒ `lazy` 면 자식은 «첫 도구 호출» 때 한 번 뜨고,
+  // 그 전에 알리는 툴 «목록»은 지난 부팅이 적어 둔 인덱스 그대로다.
+  const lazy = opts.lazy === true;
+  const toolIndexStore = lazy ? (opts.toolIndexStore ?? defaultMcpToolIndexStore()) : undefined;
+  const toolIndex: McpToolIndex = toolIndexStore ? readToolIndex(toolIndexStore) : {};
+  const deferredClients: DeferredMcpClient[] = [];
+  const lazyToolsFor = (serverId: string): McpTool[] | undefined => {
+    if (!lazy) return undefined;
+    const cached = toolIndex[serverId];
+    return cached && cached.length > 0 ? cached : undefined;
+  };
+  const recordToolIndex = (serverId: string, tools: readonly McpTool[]): void => {
+    if (!toolIndexStore) return;
+    toolIndex[serverId] = [...tools];
+    toolIndexStore.write(toolIndex);
+  };
+  const logLazyBoot = (
+    serverId: string,
+    reason: 'deferred' | 'first-call' | 'no-index',
+    toolCount?: number,
+  ): void => {
+    try {
+      debug.log('mcp.client', 'lazy-boot', {
+        server: serverId,
+        reason,
+        ...(toolCount === undefined ? {} : { toolCount }),
+      });
+    } catch { /* logger must never throw the boot */ }
+  };
+  /** 허가 관문 보고 — 지연·즉시 두 경로가 «같은 문면»을 낸다. */
+  const reportAuthorization = (serverId: string, tools: readonly { name: string }[]): void => {
+    const grantedCount = tools.filter((t) => authorizer.isGranted(serverId, t.name)).length;
+    if (tools.length > 0 && grantedCount === 0) {
+      logger.warn(
+        // ⛔ 접두 «라벨»도 같은 문자열이다 — 본문만 이스케이프하면 개행이 여기로 샌다.
+        `[nexus] mcp-client ${JSON.stringify(serverId)}: ${tools.length} tool(s) registered but NONE authorized — every call will be denied. ` +
+        // ⛔ 「복사해 붙일 수 있게」라고 말하려면 «붙일 수 있는 것»을 줘야 한다.
+        //    ⇒ 서버 항목 «전체»를 흉내 내지 말고 ***더할 필드 한 줄***만 준다.
+        `Add this field to the ${JSON.stringify(serverId)} entry of mcp.servers in your elanous config: ` +
+        `"authorizedTools": [${tools.slice(0, 3).map((t) => JSON.stringify(t.name)).join(', ')}]`,
+      );
+    } else if (grantedCount < tools.length) {
+      logger.warn(
+        `[nexus] mcp-client ${JSON.stringify(serverId)}: ${tools.length} tool(s) registered but only ${grantedCount} authorized — unlisted tool calls will be denied.`,
+      );
+    }
+    debug.log('mcp.authorization', 'boot-summary', {
+      serverId,
+      toolCount: tools.length,
+      grantedCount,
+    });
+    logger.info(
+      `[nexus] mcp-client connected: ${serverId} (${tools.length} tool${tools.length === 1 ? '' : 's'}` +
+      `${grantedCount === tools.length ? '' : ` · ${grantedCount} authorized`})`,
+    );
+  };
+
   if (opts.servers.some(spec => spec.transport === 'stdio') && !opts.createClient) {
     try { syncInstalledPluginNodes(elanousStateRoot()); }
     catch (error) { debug.log('graph.kinds', 'installed-sync-failed', { reason: String(error) }); }
@@ -280,6 +434,45 @@ export async function registerMcpClients(
           }
         };
       }
+      const announced = lazyToolsFor(spec.id);
+      if (lazy && !announced) logLazyBoot(spec.id, 'no-index');
+      if (announced) {
+        // ⭐ 지연 기동 — 여기서 자식은 «하나도» 안 뜬다. 허가는 즉시 경로와
+        //    같은 관문에 미리 넣고, 등록하는 툴은 지난 부팅이 알린 목록 그대로다.
+        for (const toolName of spec.authorizedTools ?? []) {
+          authorizer.grant({ serverId: spec.id, toolName });
+        }
+        const deferred = new DeferredMcpClient(client, async () => {
+          await withTimeout(`mcp.${spec.id}.start`, () => client!.start(), serverHandshakeTimeoutMs, setTimeoutFn, clearTimeoutFn);
+          const live = await withTimeout(
+            `mcp.${spec.id}.listTools`,
+            () => client!.listTools(),
+            serverHandshakeTimeoutMs,
+            setTimeoutFn,
+            clearTimeoutFn,
+          );
+          // 이제 자식이 있다 — 리소스 경로·종료 스냅샷이 보는 clients 에 넣는다.
+          clients.push(client!);
+          recordToolIndex(spec.id, live);
+          logLazyBoot(spec.id, 'first-call', live.length);
+        }, spec.id);
+        deferredClients.push(deferred);
+        for (const t of announced) {
+          const runtime = createMcpProxyRuntime({
+            serverId: spec.id,
+            mcpTool: t,
+            client: deferred,
+            authorizer,
+          });
+          register(runtime);
+          registeredIds.push(runtime.id);
+          registered += 1;
+        }
+        perServer[spec.id] = { status: 'ready', toolCount: announced.length, deferred: true };
+        reportAuthorization(spec.id, announced);
+        logLazyBoot(spec.id, 'deferred', announced.length);
+        continue;
+      }
       await withTimeout(`mcp.${spec.id}.start`, () => client!.start(), serverHandshakeTimeoutMs, setTimeoutFn, clearTimeoutFn);
       const tools = await withTimeout(
         `mcp.${spec.id}.listTools`,
@@ -304,37 +497,14 @@ export async function registerMcpClients(
       }
       clients.push(client);
       perServer[spec.id] = { status: 'ready', toolCount: tools.length };
+      // 콜드 스타트(인덱스 없음) 1회 뒤에는 다음 부팅이 지연 기동할 수 있게 적어 둔다.
+      if (lazy) recordToolIndex(spec.id, tools);
       // ⛔⭐ **금지에는 «길»을 붙인다.** 허가 관문은 fail-closed 라 `authorizedTools` 를
       //    안 적은 서버의 툴은 «전부» 거부된다 — 그것이 의도지만, 조용하면 사용자는
       //    ***「어제 되던 툴이 오늘 안 된다」***만 겪고 이유도 고치는 법도 모른다.
       //    ⇒ 붙었는데 허가가 «하나도 없는» 서버는 이름을 대고 «무엇을 적어야 하는지»까지 말한다.
       //    ⚠️ 부팅을 막지는 않는다 — 이 배선의 계약은 「한 서버가 실패해도 계속」이다.
-      const grantedCount = tools.filter((t) => authorizer.isGranted(spec.id, t.name)).length;
-      if (tools.length > 0 && grantedCount === 0) {
-        logger.warn(
-          // ⛔ 접두 «라벨»도 같은 문자열이다 — 본문만 이스케이프하면 개행이 여기로 샌다.
-          `[nexus] mcp-client ${JSON.stringify(spec.id)}: ${tools.length} tool(s) registered but NONE authorized — every call will be denied. ` +
-          // ⛔ 「복사해 붙일 수 있게」라고 말하려면 «붙일 수 있는 것»을 줘야 한다.
-          //    초판은 `{"id":…, ..., "authorizedTools":[…]}` 를 줬는데 그 `...` 때문에
-          //    «유효한 JSON 이 아니었다» — 말과 산출이 어긋났다(리뷰가 잡음).
-          //    ⇒ 서버 항목 «전체»를 흉내 내지 말고 ***더할 필드 한 줄***만 준다.
-          `Add this field to the ${JSON.stringify(spec.id)} entry of mcp.servers in your elanous config: ` +
-          `"authorizedTools": [${tools.slice(0, 3).map((t) => JSON.stringify(t.name)).join(', ')}]`,
-        );
-      } else if (grantedCount < tools.length) {
-        logger.warn(
-          `[nexus] mcp-client ${JSON.stringify(spec.id)}: ${tools.length} tool(s) registered but only ${grantedCount} authorized — unlisted tool calls will be denied.`,
-        );
-      }
-      debug.log('mcp.authorization', 'boot-summary', {
-        serverId: spec.id,
-        toolCount: tools.length,
-        grantedCount,
-      });
-      logger.info(
-        `[nexus] mcp-client connected: ${spec.id} (${tools.length} tool${tools.length === 1 ? '' : 's'}` +
-        `${grantedCount === tools.length ? '' : ` · ${grantedCount} authorized`})`,
-      );
+      reportAuthorization(spec.id, tools);
     } catch (err) {
       // ⛔⭐ **이 줄은 「방어적 no-op」이 아니다.** try 블록이 등록 «루프»까지 감싸므로,
       //    툴 3개 중 2개까지 `register()` 가 성공한 뒤 3번째가 던지면 ***이미 등록된 두 개가
@@ -381,6 +551,19 @@ export async function registerMcpClients(
     async shutdown() {
       // Snapshot + clear so a re-entrant call (e.g. SIGTERM races) is a no-op.
       const snapshot = clients.splice(0);
+      // 아직 «안 뜬» 지연 클라이언트도 여기서 내린다 — 기동 중이면 그 기동을
+      // 기다렸다가 내리므로 자식이 새지 않는다. 이미 뜬 것은 snapshot 이 맡는다.
+      const pendingDeferred = deferredClients.splice(0).filter((d) => !d.spawned);
+      // ⭐ 자식에게 SIGTERM 을 «먼저» 보낸다 — 유예(지연 기동 기본 2500ms)가 지나면
+      //    SIGKILL 이라 종료 전체가 3초 안에 끝난다. 등록·허가 걷기는 그 뒤.
+      const teardown = [
+        ...snapshot.map((c) =>
+          c.dispose().catch(() => {
+            /* dispose() is best-effort; swallow */
+          }),
+        ),
+        ...pendingDeferred.map((d) => d.dispose().catch(() => { /* 아직 안 뜬 클라이언트 */ })),
+      ];
       for (const spec of opts.servers) authorizer.revokeServer(spec.id);
       // ⭐ 등록도 «되돌린다». 데몬 종료 때는 어차피 프로세스가 죽으니 무해하고,
       //    재장전 때는 ***이 줄이 없으면 다음 등록이 전부 id 충돌로 죽는다***.
@@ -389,18 +572,60 @@ export async function registerMcpClients(
       for (const id of ids) {
         try { unregister(id); } catch { /* best-effort */ }
       }
-      await Promise.all(
-        snapshot.map((c) =>
-          c.dispose().catch(() => {
-            /* dispose() is best-effort; swallow */
-          }),
-        ),
-      );
+      await Promise.all(teardown);
       injectedValuesByServer.clear();
     },
+    terminateChildrenSync(): number {
+      let signalled = 0;
+      for (const child of [...spawnedChildren]) {
+        spawnedChildren.delete(child);
+        try {
+          if (child.exitCode === null && child.signalCode === null && child.kill('SIGTERM')) signalled += 1;
+        } catch {
+          /* 이미 죽은 자식 — 쏠 대상이 없다 */
+        }
+      }
+      return signalled;
+    },
+  };
+}
+
+/** 기본 툴 인덱스 저장소 — `<state>/mcp-tool-index.json`.
+ *  ⚠️ 읽기·쓰기 모두 «부팅을 막지 않는다»: 깨진 JSON 은 빈 인덱스(콜드 스타트)로
+ *  떨어지고, 쓰기 실패는 debug 한 줄만 남긴다. */
+export function defaultMcpToolIndexStore(root: string = elanousStateRoot()): McpToolIndexStore {
+  const file = join(root, MCP_TOOL_INDEX_FILENAME);
+  return {
+    read(): McpToolIndex {
+      try {
+        const parsed: unknown = JSON.parse(readFileSync(file, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+        const index: McpToolIndex = {};
+        for (const [serverId, tools] of Object.entries(parsed as Record<string, unknown>)) {
+          if (!Array.isArray(tools)) continue;
+          const kept = tools.filter((tool): tool is McpTool =>
+            !!tool && typeof tool === 'object' && typeof (tool as { name?: unknown }).name === 'string');
+          if (kept.length > 0) index[serverId] = kept;
+        }
+        return index;
+      } catch { return {}; }
+    },
+    write(index: McpToolIndex): void {
+      try {
+        mkdirSync(root, { recursive: true });
+        writeFileSync(file, `${JSON.stringify(index, null, 2)}\n`, 'utf8');
+      } catch (error) {
+        try { debug.log('mcp.client', 'tool-index-write-failed', { reason: String(error) }); }
+        catch { /* logger must never throw the boot */ }
+      }
+    },
   };
 }
 
+function readToolIndex(store: McpToolIndexStore): McpToolIndex {
+  try { return store.read(); } catch { return {}; }
+}
+
 function defaultLogger(): McpBootLogger {
   return {
     info: (line) => console.info(line),

package/src/nexus/onboarding/first-boot-wizard.ts

@@ -1,7 +1,7 @@
 import type { WizardIO } from '../../onboarding.js';
 import type { SetupCheckResult } from '../setup-status.js';
 import type { TailscaleProbe } from './tailscale-probe.js';
-import { createManagementStarterContract } from '../../persona/presets.js';
+import { clonePreset, createManagementStarterContract, type PersonaPreset, type PersonaWriteOptions, type PersonaWriteResult } from '../../persona/presets.js';
 
 export interface FirstBootWizardDeps {
   io: WizardIO;
@@ -39,9 +39,12 @@ export type FirstBootResult =
 
 /** 직업 질문 답의 정규화 — «1»·«경영»·«management» 는 경영,
  *  나머지(빈 답 포함)는 일반(현재 첫 실행 동작 유지). */
-export function normalizeOccupationChoice(input: string): 'management' | 'general' {
+export type OccupationChoice = 'management' | 'marketing' | 'general';
+
+export function normalizeOccupationChoice(input: string): OccupationChoice {
   const v = input.trim().toLowerCase();
   if (v === '1' || v === '경영' || v === 'management') return 'management';
+  if (v === '3' || v === '마케팅' || v === 'marketing') return 'marketing';
   return 'general';
 }
 
@@ -108,6 +111,45 @@ function printPwaSetupBanner(deps: FirstBootWizardDeps): void {
   deps.io.print('');
 }
 
+/** 0.2.35 PERSONA-STARTER-FU — 첫 실행 «마케팅» 스타터 계약 원본. 경계 계약상
+ *  완료 경계 코드(first-boot-wizard.ts) 안에서 기존 clonePreset 파이프라인으로
+ *  persona store 에 정확히 한 장 쓴다. */
+const MARKETING_STARTER_PRESET: PersonaPreset = {
+  personaId: 'starter-marketing',
+  displayName: '마케팅 스타터',
+  names: ['마케팅 스타터', '마케팅', 'starter-marketing'],
+  role: '마케팅 파트너',
+  title: '첫 실행 스타터',
+  oneLine: '고객·메시지·채널을 같이 세우는 짝.',
+  voice: {
+    rule: '짧고 단정하게 — 고객 말로 먼저, 근거 한 줄.',
+    examples: [
+      '이번 주 메시지는 하나로 좁힙니다 — 첫 화면에서 5초 안에 남는 문장.',
+      '그 채널은 도달 근거가 부족합니다 — 가장 싼 실험부터 하시죠.',
+    ],
+  },
+  tasks: [
+    { when: '아침 루프', what: '채널 반응·미결 발행물을 한 화면에 모아 첫 판단을 준다' },
+    { when: '메시지가 갈릴 때', what: '후보 문장을 셋으로 좁혀 고객·채널·되돌림 수단을 나란히 놓는다' },
+    { when: '주간 정산', what: '지난 발행과 실제 반응을 대조해 다음 메시지 기준을 고친다' },
+  ],
+  tools: [],
+  firstQuestions: [
+    '지금 가장 급한 고객 메시지는 무엇인가요?',
+    '이번 주에 꼭 내보낼 채널이 있나요?',
+  ],
+  doesNot: [
+    '고객 개인정보를 외부에 전송하지 않는다',
+    '합의되지 않은 광고·발행을 대신 실행하지 않는다',
+  ],
+  forWhom: '처음 elanous 를 여는 마케터 — 고객·메시지·채널을 함께 시작하려는 사람.',
+};
+
+/** 첫 실행 «마케팅» 선택이 부르는 유일한 제작 입구 — 스타터 계약 한 장을 persona store 에 쓴다. */
+export function createMarketingStarterContract(opts: PersonaWriteOptions = {}): PersonaWriteResult {
+  return clonePreset(MARKETING_STARTER_PRESET, MARKETING_STARTER_PRESET.displayName, opts);
+}
+
 /** 0.2.29 PERSONA-STARTER — 직업 질문. «경영»이면 경영 스타터 계약 한 장을
  *  만들고, 일반이면 계약 없이 현재 흐름 그대로. 계약 생성이 실패해도
  *  wizard 결과는 completed 로 유지한다(fail-soft). */
@@ -120,20 +162,26 @@ async function askOccupationAndCreateStarter(
   io.print('');
   io.print('  어떤 일을 하세요? 고르면 스타터 계약 한 장을 만듭니다.');
   io.print('    1) 경영 — 방향·판단·운영을 함께 세우는 경영 스타터');
+  io.print('    3) 마케팅 — 고객·메시지·채널을 함께 세우는 마케팅 스타터');
   io.print('    2) 일반 — 지금처럼 계속 (스타터 계약 없이)');
   let answer: string;
   try {
-    answer = await io.ask('  선택 (1/2 · Enter=일반): ');
+    answer = await io.ask('  선택 (1/2/3 · Enter=일반): ');
   } catch (err) {
     out.error(`first-boot wizard: occupation question failed: ${(err as Error).message}`);
     return undefined;
   }
-  if (normalizeOccupationChoice(answer) !== 'management') return undefined;
+  const choice = normalizeOccupationChoice(answer);
+  if (choice === 'general') return undefined;
   try {
-    const written = createManagementStarterContract(
-      deps.starterContractDir ? { dir: deps.starterContractDir } : {},
-    );
-    io.print(`  ✓ 경영 스타터 계약이 만들어졌습니다: ${written.path}`);
+    const written = choice === 'management'
+      ? createManagementStarterContract(
+          deps.starterContractDir ? { dir: deps.starterContractDir } : {},
+        )
+      : createMarketingStarterContract(
+          deps.starterContractDir ? { dir: deps.starterContractDir } : {},
+        );
+    io.print(`  ✓ ${choice === 'management' ? '경영' : '마케팅'} 스타터 계약이 만들어졌습니다: ${written.path}`);
     return { personaId: written.personaId, displayName: written.displayName, path: written.path };
   } catch (err) {
     out.error(`first-boot wizard: starter contract failed: ${(err as Error).message}`);

package/src/oauth/codex.ts

@@ -458,6 +458,10 @@ export async function loadFreshCodexAuthState(
     });
     return state;
   }
+  if (process.env.ELANOUS_REMOTE_CODEX_ACCESS_ONLY === '1') {
+    observeCodexAuth('no-credential', { storeKey: account.storeKey, mirrorPath: mirrorPath ?? null, reason: 'access-only-expiring' });
+    return null;
+  }
   observeCodexAuth('refresh-start', {
     storeKey: account.storeKey, remainingSeconds: remainingSeconds(state),
     mirrorPath: mirrorPath ?? null, bufferMs: CODEX_REFRESH_BUFFER_MS,
@@ -602,6 +606,9 @@ export async function refreshCodexAccountHome(
     now?: () => number;
   } = {},
 ): Promise<CodexAccountRefreshResult> {
+  if (process.env.ELANOUS_REMOTE_CODEX_ACCESS_ONLY === '1') {
+    return { ok: false, kind: 'no-tokens', message: '원격 access 미러는 refresh 권한이 없다' };
+  }
   // ⛔ The CEO's default account (~/.codex) is shared with the official CLI — refreshing it here
   //   rotates the refresh token out from under that CLI. Named accounts only.
   if (name === DEFAULT_CODEX_ACCOUNT) {

package/src/onboarding/first-run.ts

@@ -1,6 +1,7 @@
 import * as readline from 'node:readline/promises';
 import { detectProviders, type DetectedProvider } from '../llm/provider-detect.js';
 import { debug } from '../debug/log.js';
+import { detectLocale, type Locale } from '../expression/locale.js';
 import { unattendedNextStepLine } from './entry-hints.js';
 import { resolveProviderCredential } from '../llm/provider-credentials.js';
 import {
@@ -13,6 +14,8 @@ export interface FirstRunDeps {
   path?: string;
   detectProviders?: () => Promise<DetectedProvider[]>;
   isTTY?: boolean;
+  /** Locale for user-facing wording; defaults to the shared ambient decision (detectLocale). */
+  locale?: Locale;
   chooseProvider?: (detected: readonly LLMProviderName[]) => Promise<LLMProviderName | null>;
   print?: (message: string) => void;
   saveConfig?: (config: UserConfig, path: string) => void;
@@ -44,12 +47,21 @@ export function parseMenuAnswer(answer: string, choices: readonly LLMProviderNam
   return provider !== undefined ? { kind: 'chosen', provider } : { kind: 'miss' };
 }
 
+/**
+ * The fixed choice line of the first-run menu (`1 Codex, 2 Grok, 3 Claude`).
+ * Single source of the wording: the prompt below renders it, and the ux-sim
+ * first-run device asserts against it, so a wording change cannot drift apart.
+ */
+export function formatProviderMenu(choices: readonly LLMProviderName[]): string {
+  return choices.map((name, i) => `${i + 1} ${CHOICE_LABEL[name] ?? name}`).join(', ');
+}
+
 export async function promptProviderMenu(
   ask: (prompt: string) => Promise<string>,
   detected: readonly LLMProviderName[] = [],
 ): Promise<LLMProviderName | null> {
   const choices = orderProviderChoices(detected);
-  const menu = choices.map((name, i) => `${i + 1} ${CHOICE_LABEL[name] ?? name}`).join(', ');
+  const menu = formatProviderMenu(choices);
   for (;;) {
     const parsed = parseMenuAnswer(await ask(`Choose LLM (${menu}; Enter to cancel): `), choices);
     if (parsed.kind === 'chosen') return parsed.provider;
@@ -66,7 +78,23 @@ async function chooseProvider(detected: readonly LLMProviderName[] = []): Promis
   }
 }
 
-const detectionLabel = (provider: string) => `${provider === 'openai-codex' ? 'codex' : provider} 구독`;
+/** User-facing first-run fallback wording, routed by the shared locale decision (detectLocale). */
+const FIRST_RUN_TEXT = {
+  ko: {
+    detectedPrefix: '감지: ',
+    subscription: ' 구독',
+    needsLlm: 'eln setup llm 으로 고르세요',
+    claudeNoPath: 'claude-code 구독은 구독으로 쓸 수 있는 경로가 없어 자동 선택하지 않음',
+    multipleDetected: '둘 이상 감지되어 고르세요',
+  },
+  en: {
+    detectedPrefix: 'detected: ',
+    subscription: ' subscription',
+    needsLlm: 'pick a provider via eln setup llm',
+    claudeNoPath: 'claude-code subscription has no usable path in elanous; not auto-selecting',
+    multipleDetected: 'more than one detected; pick one',
+  },
+} as const;
 
 export async function runFirstRun(deps: FirstRunDeps = {}): Promise<{
   outcome: 'ready' | 'needs-llm' | 'cancelled'; provider?: string; inputs: number;
@@ -74,6 +102,9 @@ export async function runFirstRun(deps: FirstRunDeps = {}): Promise<{
   const path = deps.path ?? userConfigPath();
   const cfg = deps.config ?? getUserConfig(path);
   const print = deps.print ?? console.log;
+  const text = FIRST_RUN_TEXT[(deps.locale ?? detectLocale()) === 'en' ? 'en' : 'ko'];
+  const detectionLabel = (provider: string) =>
+    `${provider === 'openai-codex' ? 'codex' : provider}${text.subscription}`;
   let detected: DetectedProvider[] = [];
   try { detected = await (deps.detectProviders ?? detectProviders)(); }
   catch { /* Detection is advisory; a TTY can still choose. */ }
@@ -93,9 +124,9 @@ export async function runFirstRun(deps: FirstRunDeps = {}): Promise<{
   // claude-code is detected but has no subscription path in elanous: mapping it to the 'anthropic'
   // API-key provider would save a provider whose first call fails for a subscription-only user.
   const usable = SUBSCRIPTION_PRIORITY.filter((name) => providers.includes(name));
-  const detectionLine = (outcome: string) => `감지: ${providers.map(detectionLabel).join(' · ')} → ${outcome}`;
+  const detectionLine = (outcome: string) => `${text.detectedPrefix}${providers.map(detectionLabel).join(' · ')} → ${outcome}`;
   const needsLlm = (inputs: number, extra: string[] = []) => {
-    print('eln setup llm 으로 고르세요');
+    print(text.needsLlm);
     for (const line of extra) print(line);
     observe('needs-llm', inputs);
     return { outcome: 'needs-llm' as const, inputs };
@@ -106,8 +137,8 @@ export async function runFirstRun(deps: FirstRunDeps = {}): Promise<{
   if (!provider) {
     if (providers.length > 0) {
       print(detectionLine(usable.length === 0
-        ? 'claude-code 구독은 구독으로 쓸 수 있는 경로가 없어 자동 선택하지 않음'
-        : '둘 이상 감지되어 고르세요'));
+        ? text.claudeNoPath
+        : text.multipleDetected));
     }
     if ((deps.isTTY ?? process.stdin.isTTY) !== true) {
       // FIRST-CHAT-NONTTY — bare `elanous` with no TTY gets the same one-line next step as the other entrances.