elanous 0.2.35 → 0.2.37

package/src/nexus/api/http-server.ts

@@ -1523,7 +1523,7 @@ export async function routeRequest(
   if (method === 'POST' && pathname === '/v1/graphs/wizard') {
     if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
     if (!checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
-    return handleGraphWizardPost(req, opts.graphWizard);
+    return handleGraphWizardPost(req, opts.graphWizard, opts.eventBus);
   }
 
   if (pathname === '/v1/fabric/decompose' || pathname.startsWith('/v1/fabric/plans/')) {

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

@@ -11,6 +11,7 @@ import { createSeatsCache, todayKst } from './ops-seats.js';
 import { liveSeatsSources } from './ops-seats-sources.js';
 import { createOverviewCache } from '../../ops/overview-cache.js';
 import { resourcesFromOverview } from '../../ops/resources.js';
+import { loopsMapFromCache } from '../../ops/loops-map.js';
 import { parseSince } from '../../ops/overview-collect.js';
 import type { MetaApiOpts } from './meta-api.js';
 
@@ -184,6 +185,14 @@ export function readReleaseRuns(version: string | null = null,
   }).sort((a, b) => b.startedAt.localeCompare(a.startedAt)).slice(0, 20);
 }
 
+/**
+ * 요청이 «자격을 하나라도 실어 왔는가» — operatorSignal 이 판정에 쓰는 축(베어러·프록시 헤더·쿠키)만 본다.
+ * 아무것도 없으면 401(인증 없음), 있는데 운영자가 아니면 403(권한 없음)으로 가른다.
+ */
+function offeredCredential(req: Request): boolean {
+  return Boolean(req.headers.get('authorization') || req.headers.get('x-elanous-operator') || req.headers.get('cookie'));
+}
+
 /** The sole data gate for every read-only /v1/ops endpoint. */
 export function handleOpsApi(req: Request, metaApi: MetaApiOpts | undefined): Response | Promise<Response> {
   const url = new URL(req.url);
@@ -195,6 +204,9 @@ export function handleOpsApi(req: Request, metaApi: MetaApiOpts | undefined): Re
     debug.log('ops.api', 'refused', { path: pathname, source: signal.operatorSource });
     // RES-FLOOR-API: no credential was offered at all — this endpoint names it 401; every other path keeps 403.
     if (pathname === '/v1/ops/resources') return jsonResponse({ error: 'unauthorized' }, 401);
+    // LOOP-MAP-API: a request that offers no credential at all is 401 in the same body shape;
+    // a credential that is not an operator stays 403, exactly like the neighbouring ops paths.
+    if (pathname === '/v1/ops/loops-map' && !offeredCredential(req)) return jsonResponse({ error: 'unauthorized' }, 401);
     return jsonResponse({ error: 'forbidden' }, 403);
   }
   const served = (response: Response): Response => {
@@ -226,12 +238,8 @@ export function handleOpsApi(req: Request, metaApi: MetaApiOpts | undefined): Re
     // (name·era·beat cell observedAt; null/unmeasured value and reason preserved);
     // no new remote fan-out of its own. Loop-edge joining is a later shard.
     overviewCache ??= createOverviewCache();
-    return overviewCache.get()
-      .then((overview) => served(jsonResponse({
-        generatedAt: overview.generatedAt,
-        cacheAgeMs: overview.cacheAgeMs,
-        loops: overview.loops.map((loop) => ({ name: loop.name, era: loop.era, beat: loop.beat })),
-      })), () => jsonResponse({ error: 'overview-unavailable' }, 500));
+    // peek, not get: a cold cache answers «아직 캐시 없음» instead of starting a collection.
+    return Promise.resolve(served(jsonResponse(loopsMapFromCache(overviewCache.peek()))));
   }
   if (pathname === '/v1/ops/seats') {
     const date = url.searchParams.get('date') ?? todayKst();

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/nexus/state/state.ts

@@ -113,7 +113,13 @@ export interface NexusEvent {
     // · tone? · glyph?). PWA's M4 `subscribeHudSegmentEvents`
     // synthesizes a FeedbackEnvelope { kind: 'hud.segment' } and routes
     // it through the M1 `applyHudSegmentEnvelope` accumulator.
-    | 'hud.segment';
+    | 'hud.segment'
+    // GRAPH-WIZARD variant 관측 (ARG-L2-DESIGNER-FU1 · 2026-10-23) — POST /v1/graphs/wizard 의
+    // variant 한 턴이 끝날 때 호출 경계(handleGraphWizardPost)가 한 건 발행한다. `detail` =
+    // { mode: 'variant', status: 'composed'|'fallback-standard', reason, goal, templateId,
+    //   growth?: { from, outcome, nodeId, returnTo? }, overlayId?, patches? }.
+    // SSE 구독자는 `?topics=graph.compose` 로 받는다.
+    | 'graph.compose';
   tabId?: string;
   detail?: Record<string, unknown>;
 }

package/src/oauth/codex-account-store.ts

@@ -32,6 +32,8 @@ import {
   decideFallback, normalizeFallbackChain, grokQuotaFromUsageSnapshot,
   type FallbackDecision, type FallbackInput, type FallbackStep, type RotationOutcome,
 } from './fallback-chain.js';
+import { collectClaudePtyMaturitySample, judgeClaudePtyMaturity, type ClaudePtyMaturity } from './claude-pty-maturity.js';
+import type { UsageOutcomesDeps } from '../budget/usage-outcomes.js';
 import { resolveGrokCredential } from '../grok/credential.js';
 import { getOpenRouterApiKey } from '../config.js';
 import { lookupOpenRouterModelSpec } from '../model-tier/llm-tier-map.js';
@@ -1087,6 +1089,29 @@ function richestCreditCandidate(candidates: readonly RotationCandidate[], reserv
   return creditCandidatesByBalance(candidates, reserve)[0];
 }
 
+/**
+ * CLAUDE-FAILOVER-FU — 체인에 `claude-pty` 칸이 «있을 때만» 런 원장의 최근 표본을 읽어 성숙도를 낸다.
+ *
+ * ⛔ 다른 체인에서는 원장을 «안 읽는다» — 비용도 0 이고, claude 를 안 쓰는 구성의 판정 입력도 안 바뀐다.
+ * ⛔ 읽기 실패·표본 결손을 «전환 가능»으로 접지 않는다 — `judgeClaudePtyMaturity(null)` 이
+ *   `sample-unreadable`(미성숙)을 내고, 판정은 `claude-pty-immature` 로 닫힌다.
+ * ⛔ 예외도 삼켜 미성숙으로 닫는다 — 원장 I/O 때문에 폴백 판정 자체가 죽으면 안 된다.
+ */
+function claudePtyMaturityForChain(
+  chain: readonly FallbackStep[],
+  ledger: UsageOutcomesDeps | undefined,
+): ClaudePtyMaturity | undefined {
+  if (!chain.includes('claude-pty')) return undefined;
+  try {
+    return judgeClaudePtyMaturity(collectClaudePtyMaturitySample(ledger ?? {}));
+  } catch (error) {
+    debug.log('oauth.claude-pty', 'maturity-read-failed', {
+      reason: error instanceof Error ? error.message.slice(0, 120) : String(error).slice(0, 120),
+    }, { level: 'warn' });
+    return judgeClaudePtyMaturity(null);
+  }
+}
+
 export function resolveRunFallback(
   env: NodeJS.ProcessEnv = process.env,
   deps: {
@@ -1098,6 +1123,8 @@ export function resolveRunFallback(
     readonly openrouterAvailable?: boolean;
     /** codex 크레딧 잔액 «확인» seam — 안 주면 회전 후보의 크레딧 신호(잔액 > 0 · 보유 ≠ false)로 잰다. */
     readonly codexCreditsAvailable?: boolean;
+    /** ⛔ 런 원장 «읽기» seam — 체인에 `claude-pty` 가 있을 때만 쓴다. 안 주면 실제 런 원장을 읽는다. */
+    readonly claudePtyLedger?: UsageOutcomesDeps;
   } & Pick<FallbackInput, 'currentStep' | 'currentCredentialRateLimited'> = {},
 ): FallbackDecision {
   try {
@@ -1160,7 +1187,13 @@ export function resolveRunFallback(
       : explicitAccount ? (explicitAccountHasCredits(snapshot, creditReserve) ? [snapshot.current.name] : [])
       : codexCreditAccountNames(snapshot.candidates, creditReserve);
     const codexCreditsAvailable = effectiveChain.includes('codex-credits') && (deps.codexCreditsAvailable ?? creditAccounts.length > 0);
-    const fallbackBase = { rotation, chain: effectiveChain, grokAvailable, grokQuota, openrouterFallbackModel, openrouterAvailable, codexCreditsAvailable };
+    // CLAUDE-FAILOVER-FU — 체인에 `claude-pty` 가 «있을 때만» 원장 성숙도를 재서 판정 입력에 싣는다.
+    //   ⛔ 없으면 `undefined` 이고 판정은 종전 그대로다(수집 0회 · 판정식 무변경).
+    const claudePtyMaturity = claudePtyMaturityForChain(effectiveChain, deps.claudePtyLedger);
+    const fallbackBase = {
+      rotation, chain: effectiveChain, grokAvailable, grokQuota, openrouterFallbackModel, openrouterAvailable, codexCreditsAvailable,
+      ...(claudePtyMaturity ? { claudePtyMaturity } : {}),
+    };
     const fallbackInput: FallbackInput = deps.currentCredentialRateLimited === true && deps.currentStep
       ? { ...fallbackBase, currentStep: deps.currentStep, currentCredentialRateLimited: true }
       : { ...fallbackBase, ...(deps.currentStep ? { currentStep: deps.currentStep } : {}) };