elanous 0.2.22 → 0.2.23

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

@@ -6,12 +6,15 @@
 // ⛔ 토큰 «값»은 어디에도 출력하지 않는다 — accountId 앞 8자만(R-LLM2).
 
 import { readFile } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { mkdirSync, openSync, closeSync, unlinkSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { consumeCodexResetCredits, listCodexResetCredits } from '../budget/codex-reset-credits.js';
+import { codexCredentialRoot, readAvailabilityState, writeAvailabilityState } from '../budget/codex-reset-credit-state.js';
 import {
   DEFAULT_CODEX_ACCOUNT, codexStoreKey, accountNameFromStoreKey, isValidAccountName, isCodexStoreKey,
   resolveCodexAccount, effectiveCodexHome, type CodexHomeSource, type CodexAccountResolution,
 } from './codex-account.js';
-import { authStorePath, defaultCodexHome, listProviders, loadTokens, saveTokens } from './store.js';
+import { authStorePath, defaultCodexHome, isUnderTestRunner, listProviders, loadTokens, saveTokens } from './store.js';
 import { readFreshAvailabilityState, quotaSignalDir, readQuotaSignal, readQuotaSignalCredits, readQuotaSignalUsedPercent, readQuotaSignalObservedAt, readQuotaSignalObservedAtRaw } from '../budget/codex-reset-credit-state.js';
 import { creditPaceStatus } from '../budget/codex-credit-pace.js';
 import { loadLlmPolicy } from '../policy/llm-policy.js';
@@ -29,6 +32,8 @@ import {
   type FallbackDecision, type FallbackInput, type RotationOutcome,
 } from './fallback-chain.js';
 import { resolveGrokCredential } from '../grok/credential.js';
+import { getOpenRouterApiKey } from '../config.js';
+import { lookupOpenRouterModelSpec } from '../model-tier/llm-tier-map.js';
 import { sendOutbound } from '../domains/outbound-alert.js';
 
 type CodexAccountOutboundSender = (text: string, kind?: string) => boolean;
@@ -47,7 +52,7 @@ export function _setCodexAccountOutboundSenderForTesting(sender: CodexAccountOut
 /** ⛔⭐ 정적 import 로 읽는다 — 종전 `require()` 는 ESM 에서 «정의되지 않을 수 있고», 그러면
  *  fail-soft 가 삼켜 ***config false 가 영영 무시된다***(리뷰 should-fix: 노브가 no-op 이 된다).
  *  ⚠️ 순환 없음을 확인했다 — user-config 는 oauth 를 안 끌어온다. */
-type RotationConfig = { llm?: { codexAccountRotation?: boolean; codexAccountAlerts?: boolean; codexAccountRotationThresholdPercent?: unknown; codexAccountRotationThresholdPercentByAccount?: Readonly<Record<string, unknown>>; codexCreditsAllowed?: boolean; codexQuotaPolicy?: unknown; fallbackChain?: unknown } };
+type RotationConfig = { llm?: { codexAccountRotation?: boolean; codexAccountAlerts?: boolean; codexAccountRotationThresholdPercent?: unknown; codexAccountRotationThresholdPercentByAccount?: Readonly<Record<string, unknown>>; codexCreditsAllowed?: boolean; codexResetAutoConsumePerDay?: number; codexQuotaPolicy?: unknown; fallbackChain?: unknown; openrouter?: { fallbackModel?: unknown } } };
 
 function readUserConfig(): RotationConfig {
   return getUserConfig();
@@ -636,6 +641,9 @@ export function resolveCodexAccountForRun(
     to: decision.reason === 'credit-pace' ? decision.to?.name ?? current.name : decision.to?.name,
   });
   observeRotation(decision, current.name);
+  // 순서 ② — 구독 남은 계정이 없고 리셋권이 있으면 «스스로 1개» 쓴다(일일 상한 · 비동기 · 이번 호출은 종전대로 머문다).
+  //   ⛔ 판정이 `reset-credit-available` 일 때만 닿는다 — 구독 남은 계정이 있으면(rotated) 여기 안 온다.
+  if (decision.reason === 'reset-credit-available') void autoConsumeCodexResetCredit({ storePath: path });
   const resolved = applyRotation(current, decision);
   if (resolved.source === 'rotated') {
     notifyCodexAccountEventWithUsage('rotation', path, now,
@@ -658,6 +666,111 @@ export function resolveCodexAccountForRun(
   return resolved;
 }
 
+/** 리셋권 자동 소비 결과 — 소비했거나, 왜 안 했는지(관측 `reset-consume-skipped` 와 같은 이유). */
+export type CodexResetAutoConsumeOutcome =
+  | { readonly consumed: true; readonly account: string; readonly expiresAt: string | null; readonly todayCount: number; readonly redecision?: string }
+  | { readonly consumed: false; readonly reason: 'disabled' | 'daily-cap-reached' | 'test-runtime-guard' | 'in-flight' | 'lock-held' | 'no-available-credit' | 'consume-failed' | 'error'; readonly detail?: string };
+
+export interface CodexResetAutoConsumeDeps {
+  readonly storePath?: string;
+  readonly now?: number;
+  /** ⛔ 테스트는 «반드시» 가짜를 준다 — 안 주면 실물이고, 테스트 러너 안에서는 실물을 «부르지 않는다». */
+  readonly consume?: typeof consumeCodexResetCredits;
+  readonly list?: typeof listCodexResetCredits;
+  /** 일일 카운터 파일(테스트 격리). 기본 = 자격 뿌리 `budget/codex-reset-auto-consume.json`. */
+  readonly counterPath?: string;
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+/** `llm.codexResetAutoConsumePerDay` — 기본 1 · 0 이면 끔 · 못 읽으면 기본. */
+function resetAutoConsumePerDayFromConfig(): number {
+  try {
+    const v = (configReader().llm as { codexResetAutoConsumePerDay?: unknown } | undefined)?.codexResetAutoConsumePerDay;
+    return typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 ? v : 1;
+  } catch { return 1; }
+}
+
+function readAutoConsumeCount(path: string, day: string): number {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as { day?: unknown; count?: unknown };
+    return parsed.day === day && typeof parsed.count === 'number' && Number.isFinite(parsed.count) ? parsed.count : 0;
+  } catch { return 0; }
+}
+
+let autoConsumeInFlight = false;
+
+/**
+ * 순서 ② «리셋권» — 만료가 가장 이른 계정의 리셋권을 «하나» 쓴다. ⛔ 되돌릴 수 없다.
+ * ⛔ 소비는 기존 `consumeCodexResetCredits` 한 연산뿐이다(새 API 경로 없음).
+ * ⛔ 하루 상한(UTC 일) — 소비 «전»에 칸을 잡는다(실패해도 그날 칸은 쓴 것으로 센다: 되돌릴 수 없는 일은 덜 하는 쪽).
+ * 성공 → `codex.rotation reset-consumed` ⊕ 소비 알림 ⊕ 판정을 한 번 다시 돈다(조회 전용).
+ * 실패·상한 → `codex.rotation reset-consume-skipped { reason }` — 호출부는 종전대로 크레딧 단계로 간다.
+ */
+export async function autoConsumeCodexResetCredit(deps: CodexResetAutoConsumeDeps = {}): Promise<CodexResetAutoConsumeOutcome> {
+  const skip = (reason: Extract<CodexResetAutoConsumeOutcome, { consumed: false }>['reason'], extra: Record<string, unknown> = {}): CodexResetAutoConsumeOutcome => {
+    debug.log('codex.rotation', 'reset-consume-skipped', { reason, ...extra });
+    return { consumed: false, reason, ...(typeof extra.detail === 'string' ? { detail: extra.detail } : {}) };
+  };
+  const cap = resetAutoConsumePerDayFromConfig();
+  if (cap <= 0) return skip('disabled', { cap });
+  const now = deps.now ?? Date.now();
+  const day = new Date(now).toISOString().slice(0, 10);
+  const counterPath = deps.counterPath ?? join(codexCredentialRoot(), 'budget', 'codex-reset-auto-consume.json');
+  const before = readAutoConsumeCount(counterPath, day);
+  if (before >= cap) return skip('daily-cap-reached', { cap, todayCount: before });
+  // ⛔⭐ 되돌릴 수 없는 실물 소비를 테스트가 «절대» 못 부르게 — 가짜를 안 줬고 테스트 러너면 멈춘다.
+  if ((!deps.consume || !deps.list) && isUnderTestRunner(deps.env ?? process.env)) return skip('test-runtime-guard');
+  const consume = deps.consume ?? consumeCodexResetCredits;
+  const list = deps.list ?? listCodexResetCredits;
+  if (autoConsumeInFlight) return skip('in-flight');
+  const lockPath = `${counterPath}.lock`;
+  let lockFd: number | undefined;
+  autoConsumeInFlight = true;
+  try {
+    mkdirSync(dirname(counterPath), { recursive: true });
+    try { lockFd = openSync(lockPath, 'wx'); } catch {
+      // 죽은 프로세스가 남긴 잠금(10분 넘음)은 걷고 한 번만 다시 잡는다 — 안 그러면 자동 소비가 영영 꺼진다.
+      try { if (now - statSync(lockPath).mtimeMs > 10 * 60_000) { unlinkSync(lockPath); lockFd = openSync(lockPath, 'wx'); } } catch { /* */ }
+      if (lockFd === undefined) return skip('lock-held');
+    }
+    // 다른 프로세스가 방금 썼을 수 있다 — 잠근 «뒤»에 다시 센다.
+    const locked = readAutoConsumeCount(counterPath, day);
+    if (locked >= cap) return skip('daily-cap-reached', { cap, todayCount: locked });
+    const path = deps.storePath ?? authStorePath();
+    let earliest: { name: string; home: string; expiresAt: string | null; expiresMs: number } | undefined;
+    for (const candidate of buildRotationCandidates(path, now, deps.env ?? process.env)) {
+      if (!candidate.home) continue;
+      const listed = await list({ authFilePath: join(candidate.home, 'auth.json'), env: { CODEX_HOME: candidate.home } as unknown as NodeJS.ProcessEnv });
+      if (!listed.ok) continue;
+      for (const credit of listed.value.credits) {
+        if (credit.status !== 'available' || credit.redeemed_at) continue;
+        const ms = credit.expires_at ? Date.parse(credit.expires_at) : Number.POSITIVE_INFINITY;
+        const expiresMs = Number.isFinite(ms) || ms === Number.POSITIVE_INFINITY ? ms : Number.POSITIVE_INFINITY;
+        if (!earliest || expiresMs < earliest.expiresMs) earliest = { name: candidate.name, home: candidate.home, expiresAt: credit.expires_at, expiresMs };
+      }
+    }
+    if (!earliest) return skip('no-available-credit');
+    const todayCount = locked + 1;
+    writeFileSync(counterPath, `${JSON.stringify({ day, count: todayCount, lastAccount: earliest.name, at: new Date(now).toISOString() })}\n`, 'utf8');
+    const result = await consume({ authFilePath: join(earliest.home, 'auth.json'), env: { CODEX_HOME: earliest.home } as unknown as NodeJS.ProcessEnv });
+    if (!result.ok) return skip('consume-failed', { account: earliest.name, kind: result.kind, detail: result.message.slice(0, 200), todayCount });
+    const previous = readAvailabilityState(earliest.home);
+    const remaining = typeof previous === 'number' ? Math.max(0, previous - 1) : undefined;
+    if (remaining !== undefined) { try { writeAvailabilityState(remaining, earliest.home); } catch { /* 관측 갱신 실패는 소비를 되돌리지 않는다 */ } }
+    debug.log('codex.rotation', 'reset-consumed', { account: earliest.name, expiresAt: earliest.expiresAt, todayCount });
+    notifyCodexResetCreditConsumed({ name: earliest.name }, remaining, { storePath: path, now });
+    // 판정을 한 번 다시 돈다 — 조회 전용(관측·고정 없음). 다음 런 판정이 그 계정을 구독으로 고른다.
+    let redecision: string | undefined;
+    try { redecision = inspectCodexRotation(deps.env ?? process.env, { storePath: path }).reason; } catch { /* 재판정 실패는 소비 결과를 바꾸지 않는다 */ }
+    return { consumed: true, account: earliest.name, expiresAt: earliest.expiresAt, todayCount, ...(redecision ? { redecision } : {}) };
+  } catch (error) {
+    return skip('error', { detail: error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200) });
+  } finally {
+    if (lockFd !== undefined) { try { closeSync(lockFd); } catch { /* */ } try { unlinkSync(lockPath); } catch { /* */ } }
+    autoConsumeInFlight = false;
+  }
+}
+
 /**
  * ⛔⭐⭐⭐⭐⭐ **회전한 계정을 «자식 env»로만 내려보낸다** (2026-08-07 · 크레딧 유출 차단).
  *
@@ -738,6 +851,8 @@ export function resolveRunFallback(
     readonly grokAvailable?: boolean;
     /** ⛔ grok «잔량» seam — 안 주면 재지 «않고» 'unknown' 이다(이 판정은 네트워크를 안 친다). */
     readonly grokQuota?: 'usable' | 'exhausted' | 'unknown';
+    /** OpenRouter 키 «존재» seam(테스트 격리) — 안 주면 `getOpenRouterApiKey()` 로 잰다. 키 값은 기록하지 않는다. */
+    readonly openrouterAvailable?: boolean;
   } & Pick<FallbackInput, 'currentStep' | 'currentCredentialRateLimited'> = {},
 ): FallbackDecision {
   try {
@@ -777,11 +892,18 @@ export function resolveRunFallback(
     // ⛔ 「지금 쓸 수 있나」는 «자격과 다른 축»이다. 안 주면 'unknown' — 그리고 unknown 은 «통과»다.
     //   ⇒ 「모르고 갔다」와 「알고 갔다」가 관측에서 갈린다(아래 grokQuota).
     const grokQuota = deps.grokQuota ?? readCachedGrokQuota();
-    const fallbackBase = { rotation, chain, grokAvailable, grokQuota };
+    const fallbackModel = configReader().llm?.openrouter?.fallbackModel;
+    const openrouterFallbackModel = typeof fallbackModel === 'string' ? fallbackModel : undefined;
+    const openrouterAvailable = chain.includes('openrouter')
+      && (deps.openrouterAvailable ?? Boolean(getOpenRouterApiKey()?.trim()));
+    const fallbackBase = { rotation, chain, grokAvailable, grokQuota, openrouterFallbackModel, openrouterAvailable };
     const fallbackInput: FallbackInput = deps.currentCredentialRateLimited === true && deps.currentStep
       ? { ...fallbackBase, currentStep: deps.currentStep, currentCredentialRateLimited: true }
       : { ...fallbackBase, ...(deps.currentStep ? { currentStep: deps.currentStep } : {}) };
     const decision = decideFallback(fallbackInput);
+    // tier-map 칸(가격·창 근거) — 유료 전환은 «무슨 값으로 가는지»를 관측에 남긴다. 미등록이면 'unregistered'.
+    const openrouterSpec = decision.action === 'switch-backend' && decision.backend === 'openrouter'
+      ? lookupOpenRouterModelSpec(decision.model) : undefined;
 
     debug.log('oauth.fallback-chain', 'decide', {
       rotationReason: rotation.reason,
@@ -797,16 +919,23 @@ export function resolveRunFallback(
       ...(dropped.length > 0 ? { droppedSteps: dropped } : {}),
       grokAvailable,
       grokQuota,
+      ...(chain.includes('openrouter') ? { openrouterAvailable, openrouterModelConfigured: Boolean(openrouterFallbackModel?.trim()) } : {}),
       action: decision.action,
       ...(decision.action === 'switch-backend' ? { backend: decision.backend } : {}),
+      ...(decision.action === 'switch-backend' && decision.backend === 'openrouter'
+        ? { model: decision.model, modelSpec: openrouterSpec ? `${openrouterSpec.label} · ${openrouterSpec.rationale}` : 'unregistered' }
+        : {}),
       ...(decision.action === 'stay' ? { why: decision.why } : {}),
       ...(decision.action === 'codex-rotate' ? { to: decision.to.name } : {}),
     });
     if (decision.action === 'switch-backend') {
+      const openrouterNote = decision.backend === 'openrouter'
+        ? ` · API 과금 ${decision.model} (${openrouterSpec ? `${openrouterSpec.label} · ${openrouterSpec.rationale}` : 'tier-map 미등록'})`
+        : '';
       emitDecision({
         kind: 'ROUTE',
         what: `공급자 전환 codex → ${decision.backend}`,
-        reason: `회전 ${rotation.reason} · 정책 ${quotaPolicy}${fallbackInput.currentCredentialRateLimited ? ' · 한도 오류' : ''}`,
+        reason: `회전 ${rotation.reason} · 정책 ${quotaPolicy}${openrouterNote}${fallbackInput.currentCredentialRateLimited ? ' · 한도 오류' : ''}`,
         purpose: '작업을 멈추지 않고 이어 간다',
         target: decision.backend,
         paths: chain.length,

package/src/oauth/fallback-chain.ts

@@ -22,7 +22,7 @@ import type { RotationCandidate } from './codex-account-rotation.js';
 import type { ClaudePtyMaturity } from './claude-pty-maturity.js';
 
 /** 체인에 놓을 수 있는 칸. ⛔ 모르는 이름은 «조용히 건너뛰지 않고» 거부한다(오타 방어). */
-export const FALLBACK_STEPS = ['codex-rotate', 'grok', 'claude-pty'] as const;
+export const FALLBACK_STEPS = ['codex-rotate', 'grok', 'claude-pty', 'openrouter'] as const;
 export type FallbackStep = (typeof FALLBACK_STEPS)[number];
 
 /** 기본 체인 — ⛔⭐ **2026-08-20 에 `grok` 이 «기본»으로 들어왔다**(대표 지시).
@@ -78,6 +78,8 @@ export type FallbackDecision =
   | { readonly action: 'codex-rotate'; readonly to: RotationCandidate }
   /** 백엔드를 통째로 바꾼다. */
   | { readonly action: 'switch-backend'; readonly backend: 'grok' | 'claude' }
+  /** 명시한 유료 OpenRouter 모델로 전환한다. 호출부가 모델을 바꾸지 못하면 실행하지 않는다. */
+  | { readonly action: 'switch-backend'; readonly backend: 'openrouter'; readonly model: string }
   /** 아무것도 안 한다 — 이유를 «값으로» 남긴다. */
   | { readonly action: 'stay'; readonly why: StayReason };
 
@@ -98,6 +100,8 @@ export type StayReason =
   | 'grok-unavailable'
   /** grok 자격은 있는데 «잔량이 소진»됐다 — 자격 부재와 «다른 값»이다. */
   | 'grok-exhausted'
+  /** 유료 OpenRouter 모델 또는 키가 없다. */
+  | 'openrouter-unavailable'
   /** claude PTY 의 최근 표본이 성숙 관문을 통과하지 못했거나 읽히지 않는다. */
   | 'claude-pty-immature';
 
@@ -113,6 +117,10 @@ export type FallbackInput = {
   /** grok 자격이 «있나». ⛔ 「모른다」를 boolean 에 접지 마라 — 호출자가
    *  `resolveGrokCredential() !== null` 로 확정해서 준다. */
   readonly grokAvailable: boolean;
+  /** `llm.openrouter.fallbackModel` — 기본 모델로의 유료 폴백은 허용하지 않는다. */
+  readonly openrouterFallbackModel?: string;
+  /** OpenRouter 키 존재 여부(키 값 자체는 판정·관측에 넣지 않는다). */
+  readonly openrouterAvailable?: boolean;
   /**
    * grok 이 «지금 쓸 수 있나» — ⛔ 자격(`grokAvailable`)과 «다른 축»이다.
    *   'usable'    쓸 수 있다(잔량 있음 · 무제한 · 임계 미만)
@@ -154,11 +162,13 @@ export function decideFallback(input: FallbackInput): FallbackDecision {
   const {
     rotation, chain, currentStep, currentCredentialRateLimited = false,
     grokAvailable, grokQuota = 'unknown', claudePtyMaturity, stayOnResetCreditAvailable = false,
+    openrouterFallbackModel, openrouterAvailable = false,
   } = input;
+  const openrouter = { model: openrouterFallbackModel, available: openrouterAvailable };
 
   if (currentCredentialRateLimited) {
     if (currentStep === undefined) return { action: 'stay', why: 'chain-exhausted' };
-    return stepAfter(chain, currentStep, grokAvailable, grokQuota, claudePtyMaturity, 'chain-exhausted');
+    return stepAfter(chain, currentStep, grokAvailable, grokQuota, claudePtyMaturity, openrouter, 'chain-exhausted');
   }
   if (rotation.reason === 'explicit') return { action: 'stay', why: 'explicit' };
   if (rotation.reason === 'not-reached' || (rotation.reason === 'credit-pace' && !('to' in rotation))) {
@@ -172,13 +182,13 @@ export function decideFallback(input: FallbackInput): FallbackDecision {
     // 회전이 답을 냈는데 체인이 codex-rotate 를 «빼» 놨다면 그 뜻을 존중하고
     // 다음 칸으로 간다(회전을 원치 않는 구성).
     if (chain.includes('codex-rotate')) return { action: 'codex-rotate', to: rotation.to };
-    return stepAfterCodex(chain, grokAvailable, grokQuota, claudePtyMaturity, 'chain-exhausted');
+    return stepAfterCodex(chain, grokAvailable, grokQuota, claudePtyMaturity, openrouter, 'chain-exhausted');
   }
 
   // no-candidate | disabled | reset-credit-available(기본) — codex 축이 끝났다. 다음 칸을 본다.
   // ⛔ 다음 칸이 «없을 때»의 이름만 고른다. 진행(stepAfterCodex)은 그대로다.
   const fallbackWhy = stayReasonWhenCodexAxisEnds(rotation.reason === 'credit-pace' ? 'no-candidate' : rotation.reason);
-  return stepAfterCodex(chain, grokAvailable, grokQuota, claudePtyMaturity, fallbackWhy);
+  return stepAfterCodex(chain, grokAvailable, grokQuota, claudePtyMaturity, openrouter, fallbackWhy);
 }
 
 /** codex 축이 끝났는데 체인 다음 칸도 없을 때 머무는 이유.
@@ -197,9 +207,10 @@ function stepAfterCodex(
   grokAvailable: boolean,
   grokQuota: 'usable' | 'exhausted' | 'unknown',
   claudePtyMaturity: ClaudePtyMaturity | undefined,
+  openrouter: { readonly model?: string; readonly available: boolean },
   whyIfNone: StayReason,
 ): FallbackDecision {
-  return stepAfter(chain, 'codex-rotate', grokAvailable, grokQuota, claudePtyMaturity, whyIfNone);
+  return stepAfter(chain, 'codex-rotate', grokAvailable, grokQuota, claudePtyMaturity, openrouter, whyIfNone);
 }
 
 function stepAfter(
@@ -208,12 +219,21 @@ function stepAfter(
   grokAvailable: boolean,
   grokQuota: 'usable' | 'exhausted' | 'unknown',
   claudePtyMaturity: ClaudePtyMaturity | undefined,
+  openrouter: { readonly model?: string; readonly available: boolean },
   whyIfNone: StayReason,
 ): FallbackDecision {
   const idx = currentStep === undefined ? -1 : chain.indexOf(currentStep);
   const rest = idx === -1 ? chain : chain.slice(idx + 1);
   let unavailableWhy: StayReason | undefined;
   for (const step of rest) {
+    if (step === 'openrouter') {
+      const model = openrouter.model?.trim();
+      if (!openrouter.available || !model || !/^openrouter\/[^/\s]+\/[^\s]+$/.test(model)) {
+        unavailableWhy = 'openrouter-unavailable';
+        continue;
+      }
+      return { action: 'switch-backend', backend: 'openrouter', model };
+    }
     if (step === 'grok') {
       // 자격 부재와 소진은 다른 값이다. 다음 칸이 있으면 그 칸을 살핀다.
       if (!grokAvailable) { unavailableWhy = 'grok-unavailable'; continue; }
@@ -236,7 +256,9 @@ export function describeFallback(decision: FallbackDecision): string {
     case 'codex-rotate':
       return `codex 계정 전환 → ${decision.to.name}`;
     case 'switch-backend':
-      return `백엔드 전환 → ${decision.backend} (구독)`;
+      return decision.backend === 'openrouter'
+        ? `백엔드 전환 → openrouter (${decision.model} · API 과금)`
+        : `백엔드 전환 → ${decision.backend} (구독)`;
     case 'stay':
       return `전환 없음 (${decision.why})`;
   }

package/src/onboarding.ts

@@ -51,6 +51,7 @@ import { DiscordBot } from './discord.js';
 import { pickCodexAuthMode, pickCodexModel } from './codex/setup.js';
 import { getInventory, resolveBaseUrl } from './llm/local-manager/manager.js';
 import { getMessages, format as i18nFormat } from './expression/i18n/index.js';
+import { messagesEn } from './expression/i18n/messages.en.js';
 import type {
   ChoiceOption,
   ChooseOpts,
@@ -1562,7 +1563,7 @@ export async function runOnboarding(opts: RunWizardOpts = {}): Promise<UserConfi
     io.print('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
     io.print(`  ${m.setupComplete}`);
     // ER1 — first-run consent notice (default on · 대표 10-01): what is sent and how to turn it off.
-    io.print('  오류가 나면 운영팀에 자동으로 알립니다(오류 내용·버전·무작위 설치 ID — 이름·메일 없이). 끄기: elanous config set errorReports.enabled false');
+    io.print(`  ${m.setupErrorReportNotice ?? messagesEn.setupErrorReportNotice}`);
     io.print(`  Provider : ${marked.llm.provider}${marked.llm.model ? ` (${marked.llm.model})` : ''}`);
     // EN5 — show what the loader will actually read (resolveSkillSources), not the raw preset fields.
     const skillSources = resolveSkillSources(marked).filter((source) => source.enabled);

package/src/plugins/adapters/claude-package.ts

@@ -72,25 +72,17 @@ export function readClaudePackageLedger(
     return { status: 'installed-plugins-unreadable', packages: [] };
   }
 
-  const marketplacesRaw = readJsonFile(marketplacesPath);
-  if (marketplacesRaw === undefined) {
-    return { status: 'known-marketplaces-unreadable', packages: [] };
-  }
-
   const plugins = asPluginMap(installedRaw);
   if (plugins === undefined) {
     return { status: 'installed-plugins-unreadable', packages: [] };
   }
 
-  const marketplaces = asMarketplaceMap(marketplacesRaw);
-  if (marketplaces === undefined) {
-    return { status: 'known-marketplaces-unreadable', packages: [] };
-  }
-
+  const marketplaces = asMarketplaceMap(readJsonFile(marketplacesPath));
+  const status: ClaudePackageLedgerStatus = marketplaces === undefined ? 'known-marketplaces-unreadable' : 'ok';
   const packages: ClaudeInstalledPackage[] = [];
   for (const [key, records] of Object.entries(plugins)) {
     const { plugin, marketplace } = splitClaudePluginKey(key);
-    const source = formatMarketplaceSource(marketplaces[marketplace]);
+    const source = formatMarketplaceSource(marketplaces?.[marketplace]);
     for (const record of records) {
       packages.push({
         name: key,
@@ -104,7 +96,7 @@ export function readClaudePackageLedger(
     }
   }
 
-  return { status: 'ok', packages };
+  return { status, packages };
 }
 
 function readJsonFile(path: string): unknown {

package/src/plugins/core/capability-policy.ts

@@ -1,3 +1,6 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
 import type { ExecutionSurfaceSpec } from '../../display/index.js';
 import type { PluginCapability, PluginSource } from './manifest.js';
 
@@ -83,6 +86,144 @@ export class PluginCapabilityPolicy {
   }
 }
 
+export type PluginScanLevel = 'safe' | 'caution' | 'dangerous';
+export interface PluginSecurityFinding { level: Exclude<PluginScanLevel, 'safe'>; code: string }
+export interface PluginSecurityDecision {
+  scan: PluginScanLevel;
+  findings: PluginSecurityFinding[];
+  integrity: string;
+  license: 'redistributable' | 'restricted' | 'unknown';
+}
+
+/** Scan bytes before consent or installation. Only non-identifying codes leave this boundary. */
+export function inspectPluginSecurity(dir: string): PluginSecurityDecision {
+  const findings: PluginSecurityFinding[] = [];
+  const hash = createHash('sha256');
+  let license: PluginSecurityDecision['license'] = 'unknown';
+  // Code files are collected first; import/exec checks run after we know which files are reachable at runtime.
+  const code = new Map<string, { text: string; test: boolean }>();
+  const entrypoints: string[] = [];
+  const visit = (folder: string): void => {
+    for (const entry of readdirSync(folder, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+      const file = join(folder, entry.name);
+      const rel = relative(dir, file).replaceAll('\\', '/');
+      if (entry.isSymbolicLink() || (!entry.isDirectory() && !entry.isFile())) {
+        findings.push({ level: 'dangerous', code: 'unsafe-entry' });
+        hash.update(rel).update('!\0');
+        continue;
+      }
+      if (entry.isDirectory()) { hash.update(rel).update('/\0'); visit(file); continue; }
+      hash.update(rel).update('\0');
+      // Size is checked before reading so an oversized import cannot exhaust memory in the scanner.
+      const size = statSync(file).size;
+      if (size > 2_000_000) {
+        hash.update(String(size)).update('\0').update('oversize');
+        findings.push({ level: 'dangerous', code: 'unscannable-file' });
+        continue;
+      }
+      const bytes = readFileSync(file);
+      hash.update(String(bytes.length)).update('\0').update(bytes);
+      if (/(?:^|\/)(?:\.env(?:\.|$)|id_rsa$|credentials?\.json$)/i.test(rel)) {
+        findings.push({ level: 'dangerous', code: 'credential-file' });
+      }
+      if (/(?:api[_-]?key|secret|token)\s*[:=]\s*[A-Za-z0-9_-]{16,}/i.test(rel)) {
+        findings.push({ level: 'dangerous', code: 'credential-filename' });
+      }
+      if (/^(?:LICENSE|LICENCE)(?:\.[^/]*)?$/i.test(rel)) {
+        if (/\b(?:MIT License|Apache License, Version 2\.0|BSD [23]-Clause|ISC License)\b/i.test(bytes.toString('utf8'))) license = 'redistributable';
+        else if (license !== 'redistributable') license = 'restricted';
+      }
+      if (bytes.includes(0)) {
+        findings.push({ level: 'dangerous', code: 'unscannable-file' });
+        continue;
+      }
+      const text = bytes.toString('utf8');
+      if (/^plugin\.json$/.test(rel)) {
+        try {
+          const manifest: unknown = JSON.parse(text);
+          if (manifest && typeof manifest === 'object' && !Array.isArray(manifest)) {
+            const raw = manifest as Record<string, unknown>;
+            const ext = raw.extensions && typeof raw.extensions === 'object' ? (raw.extensions as Record<string, unknown>)['ai.elanous'] : undefined;
+            for (const main of [raw.main, ext && typeof ext === 'object' ? (ext as Record<string, unknown>).main : undefined]) {
+              if (typeof main === 'string' && main.trim()) entrypoints.push(resolve(dir, main));
+            }
+            if (typeof raw.license === 'string' && raw.license.trim()) {
+              license = /^(?:MIT|Apache-2\.0|BSD-2-Clause|BSD-3-Clause|ISC|0BSD|CC0-1\.0)$/.test(raw.license.trim())
+                ? 'redistributable' : 'restricted';
+            }
+            const contributes = raw.contributes ?? (ext && typeof ext === 'object' ? (ext as Record<string, unknown>).contributes : undefined);
+            if (contributes && typeof contributes === 'object' && Array.isArray((contributes as Record<string, unknown>).hooks)
+              && ((contributes as Record<string, unknown>).hooks as unknown[]).length) {
+              findings.push({ level: 'caution', code: 'hooks-disabled' });
+            }
+          }
+        } catch { findings.push({ level: 'dangerous', code: 'invalid-manifest' }); }
+      }
+      // Quotes may be JSON-escaped (a value nested inside a JSON string field), so allow a backslash before them.
+      const sensitive = /(?:-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|(?:\\?["'])?(?:api[_-]?key|secret|token)(?:\\?["'])?\s*[:=]\s*(\\?["'])?([A-Za-z0-9_\-]{16,})(\(?))/gi;
+      // Two narrow non-secrets: a documented placeholder (`tvly-YOUR_API_KEY`, `xxxxxxxx…`, `REPLACE_ME`) and an
+      // unquoted call result (`apiKey = getUpstageApiKey()`). Anything else that matches — quoted or not — still counts.
+      // Both exemptions look at the WHOLE value: a placeholder shape (optional vendor prefix), or a digit-free
+      // camelCase function name immediately called. A key with `xxxxxxxx` or `YOUR_` inside it still counts.
+      const placeholder = /^(?:[A-Za-z0-9]+[_-])*(?:YOUR[_-][A-Za-z_-]+|PLACEHOLDER[A-Za-z_-]*|REPLACE[_-]?ME[A-Za-z_-]*|x{8,})$/i;
+      const callee = /^[a-z_$][A-Za-z_$]*[a-z][A-Z][A-Za-z_$]*$/;
+      const hasSecret = [...text.matchAll(sensitive)].some(([, quote, value, call]) => value === undefined
+        || !(placeholder.test(value) || (!quote && call === '(' && callee.test(value))));
+      if (/(?:^|\/)(?:knowledge|knowledge-packs?)(?:\/|$)/i.test(rel) && hasSecret) {
+        findings.push({ level: 'dangerous', code: 'knowledge-dlp' });
+      } else if (hasSecret && !/\.lock$/.test(rel)) {
+        findings.push({ level: 'dangerous', code: 'embedded-secret' });
+      }
+      if (/\.[cm]?[jt]sx?$/.test(rel)) code.set(resolve(file), { text, test: /(?:^|\/)[^/]+\.(?:test|spec)\.[cm]?[jt]sx?$/.test(rel) });
+      if (/(?:curl|wget)\b[^\n|]*\|\s*(?:sh|bash)\b|\b(?:rm\s+-rf|sudo)\b/i.test(text)) {
+        findings.push({ level: 'dangerous', code: 'unsafe-command' });
+      }
+    }
+  };
+  visit(dir);
+  if (!entrypoints.length) entrypoints.push(resolve(dir, 'plugin.ts'));
+  // Shipped test fixtures are skipped only while nothing executable reaches them: the manifest `main`
+  // and every non-test code file are roots, and any test file they import (transitively) is scanned too.
+  const importsOf = (text: string): string[] =>
+    [...text.matchAll(/\b(?:import|export)\s*(?:[\s\S]*?\s+from\s*)?["']([^"']+)["']|\b(?:import|require)\s*\(\s*["']([^"']+)["']/g)]
+      .map(match => match[1] ?? match[2] ?? '').filter(Boolean);
+  const resolveLocal = (from: string, target: string): string | undefined => {
+    if (!target.startsWith('.')) return undefined;
+    const base = resolve(from, '..', target);
+    const swapped = base.replace(/\.([cm]?)js(x?)$/, '.$1ts$2');
+    return [base, swapped, `${base}.ts`, `${base}.tsx`, `${base}.js`, `${base}.mjs`, join(base, 'index.ts'), join(base, 'index.js')]
+      .find(candidate => code.has(candidate));
+  };
+  const reachable = new Set<string>();
+  const queue = [...entrypoints.filter(path => code.has(path)), ...[...code].filter(([, info]) => !info.test).map(([path]) => path)];
+  while (queue.length) {
+    const file = queue.pop()!;
+    if (reachable.has(file)) continue;
+    reachable.add(file);
+    for (const target of importsOf(code.get(file)!.text)) {
+      const next = resolveLocal(file, target);
+      if (next && !reachable.has(next)) queue.push(next);
+    }
+  }
+  for (const file of reachable) {
+    const text = code.get(file)!.text;
+    if (/\b(?:eval\s*\(|new\s+Function\s*\(|child_process\b|Bun\.spawn\s*\()/i.test(text)) {
+      findings.push({ level: 'caution', code: 'executable-code' });
+    }
+    for (const target of importsOf(text)) {
+      // A relative or absolute import must stay inside the package; the package's own `./src/…` is fine,
+      // while `../…/src/`, `/abs/…/src/` or a `file:` URL that can leave the package root is unsafe.
+      if (/^file:/i.test(target)
+        || ((target.startsWith('.') || target.startsWith('/')) && !resolve(file, '..', target).startsWith(`${resolve(dir)}${sep}`))) {
+        findings.push({ level: 'dangerous', code: 'unsafe-import' });
+      }
+    }
+  }
+  if ((license as PluginSecurityDecision['license']) !== 'redistributable') findings.push({ level: 'caution', code: 'private-only-license' });
+  return { scan: findings.some(f => f.level === 'dangerous') ? 'dangerous' : findings.length ? 'caution' : 'safe',
+    findings, integrity: hash.digest('hex'), license };
+}
+
 export function assertCapability(decision: CapabilityDecision): void {
   if (!decision.ok) throw new Error(decision.reason);
 }

package/src/plugins/core/host.ts

@@ -38,7 +38,7 @@ import { debug } from '../../debug/log.js';
 import { getSessionCwd } from '../../session/working-dir.js';
 import { CommandRegistry, type CommandDisposable, type RegisteredCommand } from '../../command-registry.js';
 import { PluginCapabilityPolicy, assertCapability } from './capability-policy.js';
-import { PluginTrustStore } from './trust-store.js';
+import { PluginTrustStore, enabledPluginHooks } from './trust-store.js';
 import { PluginTaskService } from './task-service.js';
 import { readClipboardText, writeClipboard } from '../../clipboard/index.js';
 import {
@@ -54,6 +54,7 @@ import { getGlobalElementRegistry, publishElementEvent } from '../../element-reg
 import { mintPluginUri } from '../../mss/uri/builder.js';
 import type { PluginUri } from '../../mss/uri/brand.js';
 import { loadPluginNodes } from '../../graph-kinds/plugin-nodes.js';
+import { registerOutboundAdapter } from '../../nexus/outbound/router.js';
 import { getNodeKindRegistration, listNodeKinds, unregisterPluginNodeKind, type NodeKindEntry } from '../../graph-kinds/registry.js';
 
 /** Clamp a tool handler's return value to something short enough for
@@ -113,8 +114,10 @@ export interface ActivePlugin {
   ownedCommandDisposables: CommandDisposable[];
   /** Task registrations for this activation. */
   ownedTaskDisposables: Array<{ dispose(): void }>;
-  /** PX-3: hook registrations (from manifest.contributes.hooks[] +
-   *  ctx.hooks.register calls). Disposed on deactivate. */
+  /** Connector registrations are owner-scoped and removed on deactivate. */
+  ownedChannelDisposers: Array<() => void>;
+  /** Hook registrations from manifest.contributes.hooks[]; disposed on deactivate.
+   *  PluginContext does not expose a programmatic hooks registration API. */
   ownedHookDisposers: Array<() => void>;
   /** PX-4: mission registrations (one per contributes.missions[] entry).
    *  Disposers tear down globalMissionRegistry entries on deactivate. */
@@ -369,13 +372,12 @@ export class PluginHost {
     }
   }
 
-  /** PX-3 P4: register all manifest-declared shell hooks for the
-   *  plugin we're activating. Disposers are tracked on the active
-   *  entry so deactivate() unregisters them. In-process hooks go
-   *  through ctx.hooks.register inside onActivate (see buildContext). */
+  /** Register manifest-declared shell hooks for the plugin being activated.
+   *  Installed plugins' hooks stay off (no approval path); disposers unregister them on deactivate. */
   private registerManifestHooks(entry: PluginEntry): void {
     if (!this.activeEntry) return;
-    const specs = entry.manifest.contributes.hooks ?? [];
+    const declared = entry.manifest.contributes.hooks ?? [];
+    const specs = enabledPluginHooks(declared, entry.source);
     if (specs.length === 0) return;
     // Lazy imports so headless tests that don't exercise hooks never
     // pull in the dispatcher stack.
@@ -770,6 +772,7 @@ export class PluginHost {
       ownedDisplayDisposables: [],
       ownedCommandDisposables: [],
       ownedTaskDisposables: [],
+      ownedChannelDisposers: [],
       ownedHookDisposers: [],
       ownedMissionDisposers: [],
       ownedRouteDisposers: [],
@@ -822,6 +825,13 @@ export class PluginHost {
     const ctx = this.buildContext();
     try {
       await plugin.onActivate?.(ctx);
+      for (const adapter of plugin.channelAdapters ?? []) {
+        if (!entry.manifest.contributes.connectors?.some(connector => connector.id === adapter.type)) {
+          throw new Error(`channel connector ${adapter.type} must be declared in contributes.connectors`);
+        }
+        // The manifest declaration alone is not an active channel.
+        this.activeEntry.ownedChannelDisposers.push(registerOutboundAdapter(adapter));
+      }
       // Resolve layout after onActivate so the plugin can initialize
       // state first (e.g. fetch remote rows). buildLayout can spawn
       // widgets via the tracked helper — we record ids for dispose.
@@ -848,6 +858,7 @@ export class PluginHost {
         for (const d of this.activeEntry.ownedDisplayDisposables) d.dispose();
         for (const d of this.activeEntry.ownedCommandDisposables) d.dispose();
         for (const d of this.activeEntry.ownedTaskDisposables) d.dispose();
+        for (const d of this.activeEntry.ownedChannelDisposers) d();
         for (const d of this.activeEntry.ownedHookDisposers) d();
         for (const d of this.activeEntry.ownedMissionDisposers) d();
         for (const d of this.activeEntry.ownedRouteDisposers) d();
@@ -880,6 +891,7 @@ export class PluginHost {
     for (const d of this.activeEntry.ownedDisplayDisposables) d.dispose();
     for (const d of this.activeEntry.ownedCommandDisposables) d.dispose();
     for (const d of this.activeEntry.ownedTaskDisposables) d.dispose();
+    for (const d of this.activeEntry.ownedChannelDisposers) d();
     const promptStore = getPromptBankStore();
     for (const id of this.activeEntry.promptFragmentIds) promptStore.delete(id);
     // PX-3: dispose hook registrations for this plugin.
@@ -1746,6 +1758,7 @@ function normalizePluginExport(plugin: Partial<ElanousPlugin>, manifest: PluginM
     ...(plugin.slashCommands ? { slashCommands: plugin.slashCommands } : {}),
     ...(plugin.keybindings ? { keybindings: plugin.keybindings } : {}),
     ...(plugin.llmTools ? { llmTools: plugin.llmTools } : {}),
+    ...(plugin.channelAdapters ? { channelAdapters: plugin.channelAdapters } : {}),
     ...(plugin.onActivate ? { onActivate: plugin.onActivate } : {}),
     ...(plugin.onDeactivate ? { onDeactivate: plugin.onDeactivate } : {}),
     ...(plugin.isBusy ? { isBusy: plugin.isBusy } : {}),