elanous 0.2.41 → 0.2.43

package/src/nexus/outbound/router.ts

@@ -61,6 +61,23 @@ export interface ChannelCapabilities {
   rateLimit: boolean;
 }
 
+const CHANNEL_CAPABILITY_KEYS = {
+  send: true,
+  receive: true,
+  thread: true,
+  topic: true,
+  persona: true,
+  channelLifecycle: true,
+  permissions: true,
+  commands: true,
+  attachments: true,
+  buttons: true,
+  choices: true,
+  deliveryConfirmation: true,
+  rateLimit: true,
+} satisfies Record<keyof ChannelCapabilities, true>;
+const CHANNEL_CAPABILITY_KEY_LIST = Object.keys(CHANNEL_CAPABILITY_KEYS) as (keyof ChannelCapabilities)[];
+
 export interface ChannelEnvelope {
   text: string;
   kind: string;
@@ -98,7 +115,34 @@ export interface ChannelAdapter {
 export function receiveChannelEvent(type: string, payload: unknown): ChannelEnvelope | null | Promise<ChannelEnvelope | null> {
   const adapter = outboundAdapters.get(type) ?? installedAdapters.get(type);
   if (!adapter?.capabilities.receive || !adapter.receive) return null;
-  return adapter.receive(payload);
+  const recordOutcome = (outcome: 'accepted' | 'rejected' | 'error'): void => {
+    try {
+      const runId = process.env.ELANOUS_RUN_ID;
+      debug.log('nexus.outbound', 'receive-conformance', {
+        ...(runId ? { runId } : {}),
+        provider: type,
+        outcome,
+      });
+    } catch { /* observation must not change channel receive behavior */ }
+  };
+  const recordResult = (envelope: ChannelEnvelope | null): ChannelEnvelope | null => {
+    recordOutcome(envelope ? 'accepted' : 'rejected');
+    return envelope;
+  };
+
+  try {
+    const result = adapter.receive(payload);
+    if (result && typeof (result as Promise<ChannelEnvelope | null>).then === 'function') {
+      return Promise.resolve(result).then(recordResult, error => {
+        recordOutcome('error');
+        throw error;
+      });
+    }
+    return recordResult(result as ChannelEnvelope | null);
+  } catch (error) {
+    recordOutcome('error');
+    throw error;
+  }
 }
 
 export interface OutboundChannelConfig {
@@ -113,21 +157,43 @@ export interface OutboundChannelConfig {
 }
 
 /** Connector providers register while the host is running; unregister on plugin
- * deactivation. Built-ins cannot be replaced by a plugin or removed. */
+ * deactivation. Invalid contracts throw so the plugin host can fail activation
+ * closed. Built-ins cannot be replaced by a plugin or removed. */
 const installedAdapters = new Map<string, ChannelAdapter>();
 export function registerOutboundAdapter(adapter: ChannelAdapter): () => void {
-  if (!/^[a-z][a-z0-9-]*$/.test(adapter.type) || outboundAdapters.has(adapter.type) || installedAdapters.has(adapter.type)
-    || !adapter.capabilities.send || typeof adapter.send !== 'function' || typeof adapter.parseConfig !== 'function'
-    || (adapter.capabilities.receive && typeof adapter.receive !== 'function')
-    || (adapter.capabilities.channelLifecycle && (typeof adapter.createChannel !== 'function' || typeof adapter.archiveChannel !== 'function'))
-    || (adapter.capabilities.permissions && typeof adapter.checkPermission !== 'function')
-    || (adapter.capabilities.commands && typeof adapter.registerCommands !== 'function')
-    || (adapter.capabilities.deliveryConfirmation && typeof adapter.confirmDelivery !== 'function')
-    || (adapter.capabilities.rateLimit && typeof adapter.retryAfterMs !== 'function')) {
-    throw new Error(`invalid or duplicate outbound connector: ${adapter.type}`);
+  let adapterType = '';
+  let validContract = false;
+  try {
+    adapterType = adapter?.type ?? '';
+    const capabilities = adapter?.capabilities;
+    let completeCapabilities = false;
+    if (capabilities && typeof capabilities === 'object') {
+      const ownKeys = Reflect.ownKeys(capabilities);
+      completeCapabilities = ownKeys.length === CHANNEL_CAPABILITY_KEY_LIST.length
+        && ownKeys.every((key) => typeof key === 'string' && CHANNEL_CAPABILITY_KEY_LIST.includes(key as keyof ChannelCapabilities))
+        && CHANNEL_CAPABILITY_KEY_LIST.every((key) => {
+          const descriptor = Object.getOwnPropertyDescriptor(capabilities, key);
+          return !!descriptor && Object.hasOwn(descriptor, 'value') && typeof descriptor.value === 'boolean';
+        });
+    }
+    validContract = /^[a-z][a-z0-9-]*$/.test(adapterType)
+      && !outboundAdapters.has(adapterType) && !installedAdapters.has(adapterType)
+      && completeCapabilities && !!capabilities?.send
+      && typeof adapter.send === 'function' && typeof adapter.parseConfig === 'function'
+      && (!capabilities.receive || typeof adapter.receive === 'function')
+      && (!capabilities.channelLifecycle || (typeof adapter.createChannel === 'function' && typeof adapter.archiveChannel === 'function'))
+      && (!capabilities.permissions || typeof adapter.checkPermission === 'function')
+      && (!capabilities.commands || typeof adapter.registerCommands === 'function')
+      && (!capabilities.deliveryConfirmation || typeof adapter.confirmDelivery === 'function')
+      && (!capabilities.rateLimit || typeof adapter.retryAfterMs === 'function');
+  } catch {
+    // Capability objects with throwing reflection traps fail closed at the plugin boundary.
   }
-  installedAdapters.set(adapter.type, adapter);
-  return () => { if (installedAdapters.get(adapter.type) === adapter) installedAdapters.delete(adapter.type); };
+  if (!validContract) {
+    throw new Error(`invalid or duplicate outbound connector: ${adapterType || '[unknown]'}`);
+  }
+  installedAdapters.set(adapterType, adapter);
+  return () => { if (installedAdapters.get(adapterType) === adapter) installedAdapters.delete(adapterType); };
 }
 
 export interface OutboundFanoutConfig {
@@ -394,6 +460,25 @@ export async function routeOutbound(cfg: UserConfig, msg: OutboundMsg, deps: Rou
     try {
       const adapter = deps.adapters?.get(ch.type) ?? outboundAdapters.get(ch.type) ?? installedAdapters.get(ch.type);
       if (!adapter?.capabilities.send) return { type: ch.type, ok: false, error: 'unsupported-channel' };
+      const requirements: Array<[keyof ChannelCapabilities, boolean]> = [
+        ['thread', outMsg.threadId !== undefined],
+        ['topic', outMsg.topicId !== undefined],
+        ['persona', outMsg.persona !== undefined],
+        ['attachments', outMsg.attachments !== undefined],
+        ['buttons', outMsg.buttons !== undefined],
+        ['choices', outMsg.choices !== undefined],
+      ];
+      if (requirements.some(([capability, requested]) => requested && !adapter.capabilities[capability]))
+        return { type: ch.type, ok: false, error: 'unsupported-capability' };
+      if (outMsg.permissionAction !== undefined) {
+        if (!adapter.capabilities.permissions || typeof adapter.checkPermission !== 'function')
+          return { type: ch.type, ok: false, error: 'unsupported-capability' };
+        if (!outMsg.permissionAction.trim()) return { type: ch.type, ok: false, error: 'invalid-permission-action' };
+        let allowed = false;
+        try { allowed = await adapter.checkPermission(outMsg.permissionAction); }
+        catch { return { type: ch.type, ok: false, error: 'permission-check-failed' }; }
+        if (!allowed) return { type: ch.type, ok: false, error: 'permission-denied' };
+      }
       const result = await adapter.send(ch, outMsg, cfg, deps);
       // A connector may not impersonate another channel or echo credentials
       // through the response. Legacy built-in result fields stay unchanged.

package/src/nexus/setup-status.ts

@@ -33,6 +33,15 @@ export interface SetupCheckResult {
 
 export type SetupBootMode = 'normal' | 'setup' | 'refuse';
 
+export function shouldCheckHeadlessSetup(opts: {
+  headless: boolean;
+  detachedForTesting: boolean;
+  skipForTesting: boolean;
+  testInstance: boolean;
+}): boolean {
+  return opts.headless && !opts.detachedForTesting && !opts.skipForTesting && !opts.testInstance;
+}
+
 export interface SetupBootDecision {
   mode: SetupBootMode;
   missing: string[];

package/src/nexus/state/state.ts

@@ -93,6 +93,9 @@ export interface NexusEvent {
     // SSE 로 **내용을 담은** 메시지레벨 갱신을 받는다(content-less `session.updated` 와 달리
     // role/text 포함). 스트리밍(ACP peer broadcast)은 C5 별도. `detail` = { sessionId, role, text }.
     | 'session.output'
+    // Hand mission addressed line. Durable rows live in agent-missions; this event
+    // is only the existing /v1/events SSE notification edge.
+    | 'mission.line'
     // Rich-dev-feedback opportunistic followup §6.2 #3 (2026-05-13) —
     // AgentStatusStore lifecycle fan-out. The bridge in
     // `agent-status-event-bridge.ts` subscribes to the store and

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

@@ -29,13 +29,14 @@ import { codexPolicyAllowsCredits, codexPolicyAllowsFallback, resolveCodexQuotaP
 import { emitDecision } from '../live/detail-switch.js';
 import { debug } from '../debug/log.js';
 import {
-  decideFallback, normalizeFallbackChain, grokQuotaFromUsageSnapshot,
+  decideFallback, fallbackChainForProvider, 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 { zaiCodingPlanAvailable } from '../llm/zai-coding-plan.js';
 import { lookupOpenRouterModelSpec } from '../model-tier/llm-tier-map.js';
 import { sendOutbound } from '../domains/outbound-alert.js';
 
@@ -55,7 +56,7 @@ export function _setCodexAccountOutboundSenderForTesting(sender: CodexAccountOut
 /** ⛔⭐ 정적 import 로 읽는다 — 종전 `require()` 는 ESM 에서 «정의되지 않을 수 있고», 그러면
  *  fail-soft 가 삼켜 ***config false 가 영영 무시된다***(리뷰 should-fix: 노브가 no-op 이 된다).
  *  ⚠️ 순환 없음을 확인했다 — user-config 는 oauth 를 안 끌어온다. */
-type RotationConfig = { llm?: { codexCreditReserve?: unknown; codexAccountRotation?: boolean; codexAccountAlerts?: boolean; codexAccountRotationThresholdPercent?: unknown; codexAccountRotationThresholdPercentByAccount?: Readonly<Record<string, unknown>>; codexCreditsAllowed?: boolean; codexResetAutoConsumePerDay?: number; codexQuotaPolicy?: unknown; fallbackChain?: unknown; openrouter?: { fallbackModel?: unknown } } };
+type RotationConfig = { llm?: { provider?: string; model?: string; codexCreditReserve?: unknown; 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();
@@ -312,7 +313,8 @@ function rotationCreditsGrant(candidates: readonly RotationCandidate[]): Rotatio
   if (codexPolicyAllowsCredits(policy)) return { allowed: true, via: 'policy' };
   if (!codexPolicyAllowsFallback(policy)) return { allowed: false, via: 'none' };
   try {
-    const { chain } = normalizeFallbackChain(configReader().llm?.fallbackChain);
+    const llm = configReader().llm;
+    const { chain } = normalizeFallbackChain(llm?.fallbackChain, llm?.provider);
     if (!chain.includes('codex-credits')) return { allowed: false, via: 'none' };
     const creditAccountCount = codexCreditAccountNames(candidates, codexCreditReserveFromConfig()).length;
     const fallbackModel = configReader().llm?.openrouter?.fallbackModel;
@@ -1121,6 +1123,8 @@ export function resolveRunFallback(
     readonly grokQuota?: 'usable' | 'exhausted' | 'unknown';
     /** OpenRouter 키 «존재» seam(테스트 격리) — 안 주면 `getOpenRouterApiKey()` 로 잰다. 키 값은 기록하지 않는다. */
     readonly openrouterAvailable?: boolean;
+    /** Z.ai 키 «존재» seam(테스트 격리) — 안 주면 키 존재만 잰다. */
+    readonly zaiAvailable?: boolean;
     /** codex 크레딧 잔액 «확인» seam — 안 주면 회전 후보의 크레딧 신호(잔액 > 0 · 보유 ≠ false)로 잰다. */
     readonly codexCreditsAvailable?: boolean;
     /** ⛔ 런 원장 «읽기» seam — 체인에 `claude-pty` 가 있을 때만 쓴다. 안 주면 실제 런 원장을 읽는다. */
@@ -1150,11 +1154,18 @@ export function resolveRunFallback(
       rotation = { reason: 'no-candidate' };
     }
 
-    const normalized = normalizeFallbackChain(configReader().llm?.fallbackChain);
+    const llm = configReader().llm;
+    const normalized = normalizeFallbackChain(llm?.fallbackChain, llm?.provider);
     const { dropped, usedDefault } = normalized;
     // 대표 정책 `within-quota` — codex 밖으로 폴백하지 않는다(회전만). 전부 차면 멈춘다.
     const quotaPolicy = codexQuotaPolicyFromConfig();
-    const chain = codexPolicyAllowsFallback(quotaPolicy)
+    // A non-Codex primary has no Codex quota to enforce. Only its implicit
+    // provider default bypasses the Codex fallback policy; an explicit chain
+    // continues to obey the existing within-quota contract.
+    const nonCodexProviderDefault = usedDefault
+      && (llm?.provider === 'glm' || llm?.provider === 'zai' || llm?.provider === 'openrouter')
+      && fallbackChainForProvider(llm?.provider) !== undefined;
+    const chain = codexPolicyAllowsFallback(quotaPolicy) || nonCodexProviderDefault
       ? normalized.chain
       : normalized.chain.filter((step) => step === 'codex-rotate');
     // ⛔ grok 가용성은 «호출자가 확정»해서 줄 수 있다(테스트 격리). 안 주면 여기서 잰다.
@@ -1164,7 +1175,8 @@ export function resolveRunFallback(
     // ⛔ 「지금 쓸 수 있나」는 «자격과 다른 축»이다. 안 주면 'unknown' — 그리고 unknown 은 «통과»다.
     //   ⇒ 「모르고 갔다」와 「알고 갔다」가 관측에서 갈린다(아래 grokQuota).
     const grokQuota = deps.grokQuota ?? readCachedGrokQuota();
-    const fallbackModel = configReader().llm?.openrouter?.fallbackModel;
+    const fallbackModel = llm?.openrouter?.fallbackModel
+      ?? (llm?.provider === 'openrouter' ? llm.model : undefined);
     // SUBSCRIPTION-EXHAUST-REROUTE — 크레딧 예비분에 닿은 «넘김»은 OpenRouter 가 먼저다(대표 OP 10-11: grok 이 아니다).
     //   운영 체인 `['codex-rotate','grok']` 에는 openrouter 칸이 없다 ⇒ 이 경로에만 codex 바로 뒤에 openrouter 를 끼운다
     //   (나머지 칸은 그 뒤 · 키가 없으면 종전 체인으로). 모델은 `llm.openrouter.fallbackModel`, 없으면 «중» 기본 glm-5.3.
@@ -1179,6 +1191,7 @@ export function resolveRunFallback(
       : reserveReroute ? CREDIT_RESERVE_OPENROUTER_MODEL : undefined;
     const openrouterAvailable = effectiveChain.includes('openrouter')
       && (deps.openrouterAvailable ?? Boolean(getOpenRouterApiKey()?.trim()));
+    const zaiAvailable = effectiveChain.includes('zai') && (deps.zaiAvailable ?? zaiCodingPlanAvailable());
     // CODEX-CREDITS-STEP — 체인에 그 칸이 있을 때만 잰다(없으면 판정이 안 읽는다). 잔액을 «모르면» 없다고 본다(돈 · fail-closed).
     //   ⛔ 사람이 계정을 «명시»했으면 그 계정의 잔액만 본다 — 다른 계정 잔액으로 칸을 열고 명시 계정으로 쏘면 fail-closed 가 깨진다.
     const explicitAccount = snapshot.reason === 'explicit';
@@ -1191,7 +1204,7 @@ export function resolveRunFallback(
     //   ⛔ 없으면 `undefined` 이고 판정은 종전 그대로다(수집 0회 · 판정식 무변경).
     const claudePtyMaturity = claudePtyMaturityForChain(effectiveChain, deps.claudePtyLedger);
     const fallbackBase = {
-      rotation, chain: effectiveChain, grokAvailable, grokQuota, openrouterFallbackModel, openrouterAvailable, codexCreditsAvailable,
+      rotation, chain: effectiveChain, grokAvailable, grokQuota, openrouterFallbackModel, openrouterAvailable, zaiAvailable, codexCreditsAvailable,
       ...(claudePtyMaturity ? { claudePtyMaturity } : {}),
     };
     const fallbackInput: FallbackInput = deps.currentCredentialRateLimited === true && deps.currentStep

package/src/oauth/codex-owner-mirror.ts

@@ -0,0 +1,44 @@
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { getUserConfig } from '../user-config.js';
+import { loadTokens, type ProviderAuthState } from './store.js';
+
+export const CODEX_OWNER_MIRROR_RELATIVE_PATH = join('remote-parent-credentials', 'cli-mirror', 'auth.json');
+export const CODEX_OWNER_MIRROR_REQUIRED = 'Codex 주인 미러가 없거나 만료됐다 — 주인 호스트에서 `eln codex mirror push <host>` 를 실행해야 한다';
+
+export function codexOwnerMirrorAuthPath(): string {
+  return join(elanousStateRoot(), CODEX_OWNER_MIRROR_RELATIVE_PATH);
+}
+
+function normalizedHost(value: string): string {
+  return value.trim().replace(/\.local$/i, '').toLowerCase();
+}
+
+/** The HQ-configured machine identity is the stable short name used by the lease. */
+export function isCodexTokenOwnerHost(config = getUserConfig(), machine = hostname()): boolean {
+  const owner = normalizedHost(config.llm.codexTokenOwnerHost || 'mbp');
+  const local = normalizedHost(config.hq?.hostName || machine);
+  return local === owner;
+}
+
+/** Read only a fresh, access-only HQ snapshot. This helper never performs OAuth refresh. */
+export function readCodexOwnerAccessMirror(
+  storeKey: string,
+  opts: { path?: string; now?: number } = {},
+): ProviderAuthState {
+  const path = opts.path ?? codexOwnerMirrorAuthPath();
+  const now = opts.now ?? Date.now();
+  let state: ProviderAuthState | null = null;
+  try { state = loadTokens(storeKey, path); } catch { /* fail closed below */ }
+  const tokenFields = state?.tokens as (ProviderAuthState['tokens'] & { refresh_token?: unknown }) | undefined;
+  const expiresAt = state?.tokens.expiresAt;
+  if (!state || state.authMode !== 'chatgpt' || !state.tokens.accessToken
+    || tokenFields?.refreshToken !== '' || tokenFields?.refresh_token !== ''
+    || typeof expiresAt !== 'number'
+    || !Number.isFinite(expiresAt) || expiresAt <= now + 120_000) {
+    throw new Error(CODEX_OWNER_MIRROR_REQUIRED);
+  }
+  return state;
+}
+

package/src/oauth/codex.ts

@@ -29,7 +29,8 @@ import { join } from 'node:path';
 import { DEFAULT_CODEX_ACCOUNT, codexStoreKey, isValidAccountName, resolveCodexAccount, effectiveCodexHome, type CodexAccountResolution } from './codex-account.js';
 import { importCodexAccountFromHome, resolveCodexAccountForRun } from './codex-account-store.js';
 import { decodeJWTPayload } from './jwt.js';
-import { authStorePath } from './store.js';
+import { authStorePath, isUnderTestRunner } from './store.js';
+import { codexOwnerMirrorAuthPath, isCodexTokenOwnerHost, readCodexOwnerAccessMirror } from './codex-owner-mirror.js';
 import { platform, release, arch } from 'node:os';
 import {
   saveTokens, loadTokens, expiresAtFromSeconds,
@@ -428,8 +429,22 @@ function remainingSeconds(state: ProviderAuthState | null): number | null {
 }
 
 export async function loadFreshCodexAuthState(
-  opts: { fetchImpl?: typeof fetch; mirrorCodex?: boolean } = {},
+  opts: { fetchImpl?: typeof fetch; mirrorCodex?: boolean; ownerMirrorPath?: string } = {},
 ): Promise<ProviderAuthState | null> {
+  let tokenOwnerHost = process.env.ELANOUS_REMOTE_CODEX_ACCESS_ONLY !== '1' && isUnderTestRunner();
+  if (!tokenOwnerHost && process.env.ELANOUS_REMOTE_CODEX_ACCESS_ONLY !== '1' && isCodexTokenOwnerHost()) {
+    const { hqFenceDecision } = await import('../hq/hq.js');
+    tokenOwnerHost = hqFenceDecision('ledger-cli').run;
+  }
+  if (!tokenOwnerHost) {
+    // A non-owner host reads only the HQ-pushed access snapshot. It never
+    // reconciles ~/.codex or reaches the refresh endpoint with local credentials.
+    const mirrorPath = opts.ownerMirrorPath ?? codexOwnerMirrorAuthPath();
+    const account = resolveCodexAccountForRun(process.env, { storePath: mirrorPath });
+    const state = readCodexOwnerAccessMirror(account.storeKey, { path: mirrorPath });
+    observeCodexAuth('fresh', { storeKey: account.storeKey, remainingSeconds: remainingSeconds(state), refreshed: false, source: 'owner-cli-mirror' });
+    return state;
+  }
   // ⭐ 어느 «계정»의 토큰인가 — 기본 계정이면 종전과 동일한 키(`openai-codex`)다.
   //   ⛔ 이름 계정이면 그 계정의 스토어 키와 «그 계정의 홈» 미러를 쓴다(A 가 B 를 덮지 않게).
   // ⭐⭐ 그리고 «리밋에 걸렸으면 다른 계정으로 넘긴다»(S4 · 대표 결정).

package/src/oauth/fallback-chain.ts

@@ -44,6 +44,22 @@ export type FallbackStep = (typeof FALLBACK_STEPS)[number];
  *  «머문다». 즉 기본에 두는 비용은 0 이고 얻는 것은 「죽지 않음」이다. */
 export const DEFAULT_FALLBACK_CHAIN: readonly FallbackStep[] = ['codex-rotate', 'grok'];
 
+/** Build a one-provider default when the user has explicitly selected a provider.
+ *
+ * Keep this mapping here so chat retry, account rotation, child defaults and launch
+ * budgeting do not each invent their own provider priority. `auto` keeps the
+ * historical default chain; explicit provider selection must never add Codex/Grok.
+ */
+export function fallbackChainForProvider(provider: unknown): readonly FallbackStep[] | undefined {
+  if (typeof provider !== 'string') return undefined;
+  switch (provider.trim().toLowerCase()) {
+    case 'glm':
+    case 'zai': return ['zai'];
+    case 'openrouter': return ['openrouter'];
+    default: return undefined;
+  }
+}
+
 export function isFallbackStep(value: unknown): value is FallbackStep {
   return typeof value === 'string' && (FALLBACK_STEPS as readonly string[]).includes(value);
 }
@@ -54,9 +70,11 @@ export function isFallbackStep(value: unknown): value is FallbackStep {
  *  ⛔ 비었거나 전부 무효면 기본 체인으로 — 「설정이 있다」와 「설정이 유효하다」는 다르다. */
 export function normalizeFallbackChain(
   value: unknown,
+  configuredProvider?: unknown,
 ): { chain: readonly FallbackStep[]; dropped: readonly string[]; usedDefault: boolean } {
+  const configuredDefault = fallbackChainForProvider(configuredProvider);
   if (!Array.isArray(value)) {
-    return { chain: DEFAULT_FALLBACK_CHAIN, dropped: [], usedDefault: true };
+    return { chain: configuredDefault ?? DEFAULT_FALLBACK_CHAIN, dropped: [], usedDefault: true };
   }
   const chain: FallbackStep[] = [];
   const dropped: string[] = [];
@@ -68,7 +86,7 @@ export function normalizeFallbackChain(
     }
   }
   if (chain.length === 0) {
-    return { chain: DEFAULT_FALLBACK_CHAIN, dropped, usedDefault: true };
+    return { chain: configuredDefault ?? DEFAULT_FALLBACK_CHAIN, dropped, usedDefault: true };
   }
   return { chain, dropped, usedDefault: false };
 }
@@ -83,7 +101,7 @@ export type FallbackDecision =
   /** codex 계정을 갈아탄다(종전 동작). */
   | { readonly action: 'codex-rotate'; readonly to: RotationCandidate }
   /** 백엔드를 통째로 바꾼다. */
-  | { readonly action: 'switch-backend'; readonly backend: 'grok' | 'claude' }
+  | { readonly action: 'switch-backend'; readonly backend: 'grok' | 'claude' | 'zai' }
   /** 명시한 유료 OpenRouter 모델로 전환한다. 호출부가 모델을 바꾸지 못하면 실행하지 않는다. */
   | { readonly action: 'switch-backend'; readonly backend: 'openrouter'; readonly model: string }
   /** codex 로 «돌아와» 선불 크레딧으로 계속한다 — 체인의 `codex-credits` 칸(마지막 수단 · 유료).
@@ -116,6 +134,7 @@ export type StayReason =
   | 'grok-exhausted'
   /** 유료 OpenRouter 모델 또는 키가 없다. */
   | 'openrouter-unavailable'
+  | 'zai-unavailable'
   /** claude PTY 의 최근 표본이 성숙 관문을 통과하지 못했거나 읽히지 않는다. */
   | 'claude-pty-immature'
   /** 체인에 `codex-credits` 가 있는데 크레딧 잔액이 «확인된» codex 계정이 없다(모름 포함 — 돈이라 fail-closed). */
@@ -137,6 +156,8 @@ export type FallbackInput = {
   readonly openrouterFallbackModel?: string;
   /** OpenRouter 키 존재 여부(키 값 자체는 판정·관측에 넣지 않는다). */
   readonly openrouterAvailable?: boolean;
+  /** Direct Z.ai coding-plan credential is available (key presence only). */
+  readonly zaiAvailable?: boolean;
   /**
    * grok 이 «지금 쓸 수 있나» — ⛔ 자격(`grokAvailable`)과 «다른 축»이다.
    *   'usable'    쓸 수 있다(잔량 있음 · 무제한 · 임계 미만)
@@ -183,13 +204,13 @@ export function decideFallback(input: FallbackInput): FallbackDecision {
   const {
     rotation, chain, currentStep, currentCredentialRateLimited = false,
     grokAvailable, grokQuota = 'unknown', claudePtyMaturity, stayOnResetCreditAvailable = false,
-    openrouterFallbackModel, openrouterAvailable = false, codexCreditsAvailable = false,
+    openrouterFallbackModel, openrouterAvailable = false, zaiAvailable = false, codexCreditsAvailable = false,
   } = input;
-  const openrouter = { model: openrouterFallbackModel, available: openrouterAvailable, codexCreditsAvailable };
+  const providerExtras = { openrouterModel: openrouterFallbackModel, openrouterAvailable, zaiAvailable, codexCreditsAvailable };
 
   if (currentCredentialRateLimited) {
     if (currentStep === undefined) return { action: 'stay', why: 'chain-exhausted' };
-    return stepAfter(chain, currentStep, grokAvailable, grokQuota, claudePtyMaturity, openrouter, 'chain-exhausted');
+    return stepAfter(chain, currentStep, grokAvailable, grokQuota, claudePtyMaturity, providerExtras, 'chain-exhausted');
   }
   if (rotation.reason === 'explicit') return { action: 'stay', why: 'explicit' };
   if (rotation.reason === 'not-reached' || (rotation.reason === 'credit-pace' && !('to' in rotation))) {
@@ -203,13 +224,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, openrouter, 'chain-exhausted');
+    return stepAfterCodex(chain, grokAvailable, grokQuota, claudePtyMaturity, providerExtras, '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, openrouter, fallbackWhy);
+  return stepAfterCodex(chain, grokAvailable, grokQuota, claudePtyMaturity, providerExtras, fallbackWhy);
 }
 
 /** codex 축이 끝났는데 체인 다음 칸도 없을 때 머무는 이유.
@@ -223,18 +244,23 @@ export function stayReasonWhenCodexAxisEnds(
   return 'chain-exhausted';
 }
 
-/** 칸 판정에 필요한 «나머지» 재료 — OpenRouter 모델·키, codex 크레딧 잔액 확인. */
-type StepExtras = { readonly model?: string; readonly available: boolean; readonly codexCreditsAvailable?: boolean };
+/** Per-provider evidence consumed by backend steps. */
+type StepExtras = {
+  readonly openrouterModel?: string;
+  readonly openrouterAvailable?: boolean;
+  readonly zaiAvailable?: boolean;
+  readonly codexCreditsAvailable?: boolean;
+};
 
 function stepAfterCodex(
   chain: readonly FallbackStep[],
   grokAvailable: boolean,
   grokQuota: 'usable' | 'exhausted' | 'unknown',
   claudePtyMaturity: ClaudePtyMaturity | undefined,
-  openrouter: StepExtras,
+  providerExtras: StepExtras,
   whyIfNone: StayReason,
 ): FallbackDecision {
-  return stepAfter(chain, 'codex-rotate', grokAvailable, grokQuota, claudePtyMaturity, openrouter, whyIfNone);
+  return stepAfter(chain, 'codex-rotate', grokAvailable, grokQuota, claudePtyMaturity, providerExtras, whyIfNone);
 }
 
 function stepAfter(
@@ -243,7 +269,7 @@ function stepAfter(
   grokAvailable: boolean,
   grokQuota: 'usable' | 'exhausted' | 'unknown',
   claudePtyMaturity: ClaudePtyMaturity | undefined,
-  openrouter: StepExtras,
+  providerExtras: StepExtras,
   whyIfNone: StayReason,
 ): FallbackDecision {
   const idx = currentStep === undefined ? -1 : chain.indexOf(currentStep);
@@ -255,12 +281,16 @@ function stepAfter(
   for (const step of rest) {
     if (step === 'codex-credits') {
       // ⛔ 크레딧은 돈이다 — 잔액이 «확인된» 계정이 없으면 건너뛴다(「모른다」는 통과가 «아니다»).
-      if (openrouter.codexCreditsAvailable !== true) { skip(step, 'codex-credits-unavailable'); continue; }
+      if (providerExtras.codexCreditsAvailable !== true) { skip(step, 'codex-credits-unavailable'); continue; }
       return { action: 'codex-credits', skipped };
     }
+    if (step === 'zai') {
+      if (!providerExtras.zaiAvailable) { skip(step, 'zai-unavailable'); continue; }
+      return { action: 'switch-backend', backend: 'zai' };
+    }
     if (step === 'openrouter') {
-      const model = openrouter.model?.trim();
-      if (!openrouter.available || !model || !/^openrouter\/[^/\s]+\/[^\s]+$/.test(model)) {
+      const model = providerExtras.openrouterModel?.trim();
+      if (!providerExtras.openrouterAvailable || !model || !/^openrouter\/[^/\s]+\/[^\s]+$/.test(model)) {
         skip(step, 'openrouter-unavailable');
         continue;
       }
@@ -290,7 +320,7 @@ export function describeFallback(decision: FallbackDecision): string {
     case 'switch-backend':
       return decision.backend === 'openrouter'
         ? `백엔드 전환 → openrouter (${decision.model} · API 과금)`
-        : `백엔드 전환 → ${decision.backend} (구독)`;
+        : decision.backend === 'zai' ? '백엔드 전환 → Z.ai GLM' : `백엔드 전환 → ${decision.backend} (구독)`;
     case 'codex-credits':
       return `codex 크레딧으로 계속 (마지막 칸 · 선불 크레딧 과금${decision.skipped.length ? ` · 건너뜀 ${decision.skipped.map((s) => `${s.step}:${s.why}`).join(', ')}` : ''})`;
     case 'stay':

package/src/onboarding/first-run-doctor.ts

@@ -7,6 +7,13 @@ const AUTOMATIC = new Set<DoctorFixItem['id']>(['private-files', 'key-cache-perm
 const DEFERRED = new Set<DoctorFixItem['id']>(['install-path', 'bun-tmpdir']);
 const LATER_LINE = '나중에: elanous doctor --fix (셸 시작 파일 수정)';
 
+export function safeDoctorReason(reason: string | undefined): string {
+  if (!reason) return '원인 불명';
+  return /(?:api[_-]?key|secret|token)\s*(?:=|:)?\s*\S+/i.test(reason)
+    ? '민감 정보가 포함된 오류'
+    : reason;
+}
+
 export interface FirstRunDoctorResult {
   fixed: string[];
   skipped: string[];
@@ -20,7 +27,7 @@ export function runFirstRunDoctor(deps: DoctorFixDeps): FirstRunDoctorResult {
   const result: FirstRunDoctorResult = { fixed: [], skipped: [], failed: [], later: [], lines: [] };
   const record = (id: string, outcome: 'fixed' | 'skipped' | 'failed', reason?: string) => {
     result[outcome].push(id);
-    if (outcome === 'failed') result.lines.push(`doctor: ${id} 수리 실패 — ${reason || '원인 불명'}`);
+    if (outcome === 'failed') result.lines.push(`doctor: ${id} 수리 실패 — ${safeDoctorReason(reason)}`);
     try { debug.log('doctor.first-run', outcome, { id }); } catch { /* 관측 실패가 첫 실행을 막지 않는다. */ }
   };