elanous 0.2.23 → 0.2.25

package/src/budget/unified-usage.ts

@@ -3,12 +3,16 @@
 // Codex: enumerate known account names, fetch each via the existing
 // ProviderFetcher with CODEX_HOME on the child env only.
 // Grok: this wiring has no multi-account list — 0 or 1 current-credential row.
-// Claude / Gemini are intentionally out of this landing.
+// Claude Code (2026-10-11 CLAUDE-USAGE-WINDOW): subscription row — 5-hour window
+// (credits axis) + 7-day window (subscription axis), from the OAuth usage endpoint.
+// Gemini is intentionally out of this landing.
 
 import { createCodexFetcher, type CodexFetcherOpts } from './fetchers/codex.js';
+import { createClaudeFetcher, resolveClaudeAccessToken } from './fetchers/claude.js';
 import {
   fetchGrokUsage,
   GROK_SUBSCRIPTION_AXIS,
+  grokUsageToSubscriptionAxis,
   grokUsageToCreditAxis,
   type GrokUsageResult,
 } from '../grok/usage.js';
@@ -19,10 +23,16 @@ import { loadTokens } from '../oauth/store.js';
 import { envLiteral } from '../platform/env-literal.js';
 import { describeResetCreditExpiry } from './codex-reset-credit-state.js';
 import { visibleWidth } from '../tui.js';
+import { debug } from '../debug/log.js';
 import { listCodexResetCredits, type CodexResetCreditsResult } from './codex-reset-credits.js';
+import {
+  buildZaiUsageView, fetchZaiQuota, getZaiApiKey, readZaiLedger,
+  type ZaiLedgerRecord, type ZaiQuotaResult, type ZaiUsageView,
+} from '../llm/zai-coding-plan.js';
 import type {
   AccountUsageRow,
   CreditAxis,
+  RateWindow,
   ResetCreditExpiryAxis,
   SubscriptionAxis,
   UnifiedUsageReport,
@@ -50,24 +60,247 @@ export interface UnifiedUsageDeps {
   /** 결정 2026-09-23 — OpenRouter 선불 크레딧 조회 seam. 없으면 실키로 `/api/v1/credits`. */
   readonly openRouterKey?: () => string | undefined;
   readonly fetchOpenRouterImpl?: typeof fetch;
+  /** ZAI-CODING-PLAN-PROVIDER seam — 키 «있음» 판정(값은 안 쓴다) · 공식 조회 · 원장. */
+  readonly zaiKey?: () => string | undefined;
+  readonly fetchZaiQuota?: () => Promise<ZaiQuotaResult>;
+  readonly readZaiLedger?: () => ZaiLedgerRecord[];
+  /** Claude Code OAuth 토큰 해석 심 — 없으면 조회를 안 탄다(토큰 없음 = 행 없음). */
+  readonly resolveClaudeToken?: () => string | null;
+  /** Claude 사용량 조회 심 — `createClaudeFetcher().fetch()` 모양. */
+  readonly fetchClaude?: () => Promise<UsageSnapshot>;
+  /** 캐시 «아래»의 원 조회 심 — 주면 15분/5분 캐시를 거친다(`fetchClaude` 는 캐시를 우회한다). */
+  readonly fetchClaudeUncached?: () => Promise<UsageSnapshot>;
+}
+
+/** 공급자별 실패 격리(2026-10-11) — collector 가 «try 밖에서» 던지면 그 공급자만 한 error 행으로 바꾼다.
+ *  ⛔ 종전 `Promise.all` 은 한 공급자의 예외(예: 키 조회 seam throw)가 usage «전체» 를 죽였다.
+ *    `allSettled` 로 바꾸고 rejected 는 여기서 한 행으로 접는다 — 다른 공급자 행은 그대로 산다. */
+type ZaiOutcome = { rows: AccountUsageRow[]; view: ZaiUsageView };
+
+function isolateProviderRows(
+  provider: AccountUsageRow['provider'],
+  settled: PromiseSettledResult<AccountUsageRow[] | ZaiOutcome | null>,
+): { rows: AccountUsageRow[]; zai: ZaiOutcome | null } {
+  if (settled.status === 'fulfilled') {
+    const value = settled.value;
+    if (value === null) return { rows: [], zai: null };
+    if (Array.isArray(value)) return { rows: value, zai: null };
+    return { rows: value.rows, zai: value };
+  }
+  const detail = settled.reason instanceof Error ? settled.reason.message : String(settled.reason);
+  debug.log('usage', 'provider-failed', { provider, detail });
+  return {
+    rows: [{
+      provider,
+      accountName: 'default',
+      accountCount: 1,
+      soleAccount: true,
+      credits: { status: 'error', detail },
+      subscription: { status: 'unavailable', reason: 'query-does-not-supply' },
+      resetCredits: { status: 'unavailable', detail },
+    }],
+    zai: null,
+  };
 }
 
 export async function collectUnifiedUsage(deps: UnifiedUsageDeps = {}): Promise<UnifiedUsageReport> {
-  const [codexRows, grokRows, openRouterRows] = await Promise.all([
+  const [codexSettled, claudeSettled, grokSettled, openRouterSettled, zaiSettled] = await Promise.allSettled([
     collectCodexRows(deps),
+    collectClaudeRows(deps),
     collectGrokRows(deps),
     collectOpenRouterRows(deps),
+    collectZaiRows(deps),
   ]);
+  const codex = isolateProviderRows('codex', codexSettled);
+  const claude = isolateProviderRows('claude', claudeSettled);
+  const grok = isolateProviderRows('grok', grokSettled);
+  const openRouter = isolateProviderRows('openrouter', openRouterSettled);
+  const zai = isolateProviderRows('zai', zaiSettled);
+  const zaiRows = zai.zai?.rows ?? zai.rows;
   return {
-    rows: [...codexRows, ...grokRows, ...openRouterRows],
+    rows: [...codex.rows, ...claude.rows, ...grok.rows, ...openRouter.rows, ...zaiRows],
     accountCounts: {
-      codex: codexRows.length,
-      grok: grokRows.length,
-      openrouter: openRouterRows.length,
+      codex: codex.rows.length,
+      grok: grok.rows.length,
+      openrouter: openRouter.rows.length,
+      // ⛔ claude 도 토큰이 없으면(행 0) 칸을 안 싣는다 — 종전 JSON·문면과 바이트 동일(0행 ≠ 0% 사용).
+      ...(claude.rows.length > 0 ? { claude: claude.rows.length } : {}),
+      // ⛔ 키가 없으면 칸 자체를 안 싣는다 — 종전 JSON·문면과 바이트 동일.
+      // 종전과 같게: 조회가 성공했으면(창이 비어도) zai 1 · 실패해 error 행만 남았어도 1(실패 행도 센다).
+      ...(zai.zai || zai.rows.length > 0 ? { zai: 1 } : {}),
     },
+    ...(zai.zai ? { zaiCodingPlan: zai.zai.view } : {}),
+  };
+}
+
+/** 실 OAuth usage 엔드포인트는 5~10분 간격에도 429 를 낸다(fetchers/claude.ts 머리말 · 기본 주기 15분).
+ *  nexus `/api/usage` 는 30초 캐시로 이 조립을 부르므로, 기본 조회 경로(심 없음)는 성공 스냅숏을 15분 재사용한다. */
+const CLAUDE_USAGE_CACHE_MS = 15 * 60_000;
+/** 실패(429 등)도 5분 재사용한다 — 429 가 이어지는 동안 30초마다 다시 치지 않게. */
+const CLAUDE_USAGE_FAILURE_CACHE_MS = 5 * 60_000;
+type ClaudeUsageCacheEntry = { readonly at: number; readonly token: string } & (
+  | { readonly ok: true; readonly snap: UsageSnapshot }
+  | { readonly ok: false; readonly error: unknown });
+let claudeUsageCache: ClaudeUsageCacheEntry | null = null;
+
+/** 시험 전용 — 모듈 캐시를 비운다. */
+export function resetClaudeUsageCacheForTest(): void {
+  claudeUsageCache = null;
+}
+
+async function fetchClaudeCached(token: string, nowMs: number, fetchRaw: () => Promise<UsageSnapshot>): Promise<UsageSnapshot> {
+  const c = claudeUsageCache;
+  // 캐시 키 = 토큰 — 토큰이 바뀌면(재로그인·계정 교체) 옛 계정 값을 새 행으로 보이지 않는다.
+  if (c && c.token === token && nowMs - c.at < (c.ok ? CLAUDE_USAGE_CACHE_MS : CLAUDE_USAGE_FAILURE_CACHE_MS)) {
+    if (c.ok) return c.snap;
+    throw c.error;
+  }
+  try {
+    const snap = await fetchRaw();
+    claudeUsageCache = { at: nowMs, token, ok: true, snap };
+    return snap;
+  } catch (error) {
+    claudeUsageCache = { at: nowMs, token, ok: false, error };
+    throw error;
+  }
+}
+
+/** Claude Code 구독 행 — 5시간 창(credits 축) ⊕ 7일 창(subscription 축).
+ *  ⛔ 토큰이 없으면 행을 «안» 만든다(0행 ≠ 0% 사용) — openrouter·zai 키와 같은 접기. */
+async function collectClaudeRows(deps: UnifiedUsageDeps): Promise<AccountUsageRow[]> {
+  // ⛔ 시험 런타임은 심이 없으면 «토큰 없음»으로 본다 — 실제 자격 파일을 읽으면
+  //   심을 모르는 옛 시험이 실제 네트워크를 치게 된다(openrouter·zai 키와 같은 이유).
+  const resolveToken = deps.resolveClaudeToken
+    ?? (process.env.NODE_ENV === 'test' ? () => null : resolveClaudeAccessToken);
+  let token: string | null;
+  try {
+    token = resolveToken();
+  } catch (err) {
+    // 자격 파일이 깨진 경우를 «토큰 없음»과 가를 수 있게 관측만 남긴다(행은 안 만든다).
+    debug.log('usage', 'claude-token-resolve-failed', { detail: err instanceof Error ? err.message : String(err) });
+    token = null;
+  }
+  if (!token) return [];
+  const base = {
+    provider: 'claude' as const,
+    accountName: 'default',
+    accountCount: 1,
+    soleAccount: true,
+    resetCredits: { status: 'not-applicable' } as const,
+  };
+  const tokenKey = token;
+  const fetchClaude = deps.fetchClaude ?? (() => fetchClaudeCached(
+    tokenKey, (deps.now ?? Date.now)(), deps.fetchClaudeUncached ?? (() => createClaudeFetcher().fetch())));
+  try {
+    const snap = await fetchClaude();
+    const fiveHour = snap.windows.find((w) => w.model === undefined && w.kind === 'session');
+    const weekly = snap.windows.find((w) => w.model === undefined && w.kind === 'weekly');
+    return [{ ...base, credits: claudeCreditsFromWindow(fiveHour), subscription: claudeSubscriptionFromWindow(weekly) }];
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    debug.log('usage', 'claude-fetch-failed', { detail });
+    return [{
+      ...base,
+      credits: { status: 'error', detail },
+      subscription: { status: 'unavailable', reason: 'query-does-not-supply' },
+    }];
+  }
+}
+
+function claudeCreditsFromWindow(window: RateWindow | undefined): CreditAxis {
+  const periodEnd = window && isValidEpochMs(window.resetsAt) ? new Date(window.resetsAt) : null;
+  const periodStartEpoch = periodEnd !== null && window !== undefined && isPositiveFinite(window.windowMinutes)
+    ? periodEnd.getTime() - window.windowMinutes * 60_000
+    : null;
+  const periodStart = periodStartEpoch !== null && isValidDateMs(periodStartEpoch) ? new Date(periodStartEpoch) : null;
+  return {
+    status: 'ok',
+    usedPercent: window ? window.used : null,
+    periodType: window?.kind ?? null,
+    periodStart: periodStart?.toISOString() ?? null,
+    periodEnd: periodEnd?.toISOString() ?? null,
+    monthlyLimit: null,
+    used: window ? window.used : null,
+    onDemandCap: null,
+    onDemandUsed: null,
+    prepaidBalance: null,
+    balance: null,
+    hasCredits: null,
+    unlimited: null,
+  };
+}
+
+function claudeSubscriptionFromWindow(window: RateWindow | undefined): SubscriptionAxis {
+  if (!window) return { status: 'unavailable', reason: 'query-does-not-supply' };
+  return {
+    status: 'available',
+    remainingPercent: window.remainingPercent,
+    resetsAt: window.resetsAt,
+    windowKind: window.kind,
   };
 }
 
+/** ZAI-CODING-PLAN-PROVIDER — GLM Coding Plan 의 5h·주 창 ⊕ 잔액(extra usage) 사용.
+ *  ⓒ 공식 조회(`/api/monitor/usage/quota/limit`)가 되면 그 값 · 안 되면 ⓐ 우리 적산 ⊕ ⓑ 429 리셋 시각으로 «추정».
+ *  ⛔ 키가 없으면 행을 «안» 만든다. ⛔ 시험 런타임은 seam 이 없으면 «키 없음»(키 캐시는 파일이라 스크럽을 통과한다). */
+async function collectZaiRows(deps: UnifiedUsageDeps): Promise<{ rows: AccountUsageRow[]; view: ZaiUsageView } | null> {
+  // ⛔ 시험 런타임(NODE_ENV=test)은 seam 이 없으면 «env 의 ZAI_API_KEY 만» 본다 — 키 캐시 «파일»은 env 스크럽을 통과해
+  //   seam 을 모르는 옛 usage 시험이 실제 Z.ai 를 치게 되기 때문이다. env 로 키를 주면 test 에서도 행이 선다.
+  const key = (deps.zaiKey ?? (process.env.NODE_ENV === 'test' ? () => process.env.ZAI_API_KEY?.trim() || undefined : () => getZaiApiKey()))();
+  if (!key) return null;
+  const nowMs = (deps.now ?? Date.now)();
+  // ⛔ 조회가 «던져도» usage 전체를 죽이지 않는다 — 실패는 결과값으로 바꿔 추정 표로 간다.
+  const quota: ZaiQuotaResult = await (deps.fetchZaiQuota ?? (() => fetchZaiQuota()))()
+    .catch((error: unknown) => ({ status: 'error' as const, detail: error instanceof Error ? error.message : String(error) }));
+  const view = buildZaiUsageView(quota, (deps.readZaiLedger ?? (() => readZaiLedger()))(), nowMs);
+  const base = { provider: 'zai' as const, accountCount: 1, soleAccount: true, resetCredits: { status: 'not-applicable' } as const };
+  const sourceLabel = { official: '공식', next_flush_time: 'next_flush_time', estimated: '추정' } as const;
+  const rows: AccountUsageRow[] = view.windows.map((w) => {
+    const windowMs = w.window === '5h' ? 5 * 3_600_000 : 7 * 86_400_000;
+    const usedPercent = w.limit > 0 ? Math.round((w.used / w.limit) * 1000) / 10 : null;
+    const end = w.resetAt !== null && isValidEpochMs(w.resetAt) ? new Date(w.resetAt) : null;
+    const kind: WindowKind = w.window === '5h' ? 'session' : 'weekly';
+    return {
+      ...base,
+      accountName: w.window === '5h' ? 'plan-5h' : 'plan-week',
+      credits: {
+        status: 'ok',
+        usedPercent,
+        periodType: kind,
+        periodStart: end ? new Date(end.getTime() - windowMs).toISOString() : null,
+        periodEnd: end?.toISOString() ?? null,
+        monthlyLimit: null,
+        used: w.used,
+        onDemandCap: null,
+        onDemandUsed: null,
+        prepaidBalance: null,
+        balance: null,
+        hasCredits: null,
+        unlimited: false,
+      },
+      // 리셋 시각을 모르면 «available» 로 NaN 을 흘리지 않는다.
+      subscription: usedPercent === null || !end
+        ? { status: 'unavailable', reason: 'query-does-not-supply' }
+        : { status: 'available', remainingPercent: Math.round((100 - usedPercent) * 10) / 10, resetsAt: end.getTime(), windowKind: kind },
+      // ⓐ 우리 적산을 공식 값 옆에 같이 둔다 — 공식은 정수 크레딧으로 내려 작은 호출이 0 으로 보인다(10-11 실측).
+      note: `${w.used}/${w.limit} 크레딧 · 출처=${sourceLabel[w.source]}${w.resetAt === null ? ' · 리셋 시각 모름' : ''}`
+        + (w.source === 'official' ? ` · elanous 적산 ${w.window === '5h' ? view.local.fiveHour.used : view.local.weekly.used}` : ''),
+    };
+  });
+  rows.push({
+    ...base,
+    accountName: 'extra-usage',
+    credits: {
+      status: 'ok', usedPercent: null, periodType: 'extra-usage', periodStart: null, periodEnd: null,
+      monthlyLimit: null, used: view.balanceCredits, onDemandCap: null, onDemandUsed: null,
+      prepaidBalance: null, balance: null, hasCredits: null, unlimited: false,
+    },
+    subscription: { status: 'unavailable', reason: 'not-a-subscription' },
+    note: `잔액 사용 ${view.balanceCredits} 크레딧(추정 · 최근 7일)${view.lastLimit ? ` · 마지막 한도 코드 ${view.lastLimit.code}` : ''}`,
+  });
+  return { rows, view };
+}
+
 async function collectCodexRows(deps: UnifiedUsageDeps): Promise<AccountUsageRow[]> {
   const listed = (deps.listCodexAccounts ?? listCodexAccountsInStore)();
   const accounts = listed;
@@ -138,7 +371,11 @@ async function collectGrokRows(deps: UnifiedUsageDeps): Promise<AccountUsageRow[
     resetCredits: { status: 'not-applicable' } as const,
   };
   if (result.status === 'ok') {
-    return [{ ...base, credits: grokUsageToCreditAxis(result.usage) }];
+    return [{
+      ...base,
+      subscription: grokUsageToSubscriptionAxis(result.usage),
+      credits: grokUsageToCreditAxis(result.usage),
+    }];
   }
   if (result.status === 'no-subscription') {
     return [{ ...base, credits: { status: 'no-subscription' } }];
@@ -284,7 +521,7 @@ export function formatUsageCompact(report: UnifiedUsageReport, options: { width:
     const reset = subscription.status === 'available' ? subscription.resetsAt
       : credits.status === 'ok' && credits.periodEnd ? Date.parse(credits.periodEnd) : Number.NaN;
     const periodLabel = period ? `${formatCompactPeriod(period)} ` : '';
-    const when = period === 'prepaid-usd' ? '' : !isValidEpochMs(reset)
+    const when = period === 'prepaid-usd' || period === 'extra-usage' ? '' : !isValidEpochMs(reset)
       ? ` · ${periodLabel}시각 모름`
       : reset <= options.nowMs
         ? ` · ${periodLabel}재조회 필요`
@@ -351,6 +588,13 @@ export function formatUnifiedUsage(report: UnifiedUsageReport): string {
     const count = report.accountCounts[provider];
     lines.push(`  ${provider}  accounts=${count}${count === 1 ? '  (하나뿐)' : count === 0 ? '  (없음)' : ''}`);
   }
+  // ⛔ claude 토큰이 없으면 줄을 안 낸다 — 종전 문면과 바이트 동일.
+  if (report.accountCounts.claude !== undefined) {
+    const count = report.accountCounts.claude;
+    lines.push(`  claude  accounts=${count}${count === 1 ? '  (하나뿐)' : ''}  (Claude Code 구독 · 5시간 창 ⊕ 7일 창)`);
+  }
+  // ⛔ 키가 없으면 줄을 안 낸다 — 종전 문면과 바이트 동일.
+  if (report.accountCounts.zai !== undefined) lines.push(`  zai  accounts=${report.accountCounts.zai}  (GLM Coding Plan)`);
   lines.push('  provider    account     accounts  credits.usedPercent  credits.window              window-resets-in       reset-credit-expiry                  subscription');
   for (const row of report.rows) {
     lines.push(formatRow(row));
@@ -364,7 +608,7 @@ function formatRow(row: AccountUsageRow): string {
   const resetsIn = formatWindowResetsIn(row.credits);
   const resetCredits = formatResetCreditExpiryCell(row.resetCredits);
   const subscription = formatSubscriptionCell(row.subscription);
-  return `  ${row.provider.padEnd(10)} ${row.accountName.padEnd(11)} ${String(row.accountCount).padEnd(8)} ${credits.padEnd(20)} ${window.padEnd(26)} ${resetsIn.padEnd(22)} ${resetCredits.padEnd(36)} ${subscription}`;
+  return `  ${row.provider.padEnd(10)} ${row.accountName.padEnd(11)} ${String(row.accountCount).padEnd(8)} ${credits.padEnd(20)} ${window.padEnd(26)} ${resetsIn.padEnd(22)} ${resetCredits.padEnd(36)} ${subscription}${row.note ? `  — ${row.note}` : ''}`;
 }
 
 function formatResetCreditExpiryCell(expiry: ResetCreditExpiryAxis): string {
@@ -381,6 +625,7 @@ function formatResetCreditExpiryCell(expiry: ResetCreditExpiryAxis): string {
 
 function formatCreditsCell(credits: CreditAxis): string {
   if (credits.status !== 'ok') return credits.status;
+  if (credits.periodType === 'extra-usage') return `${credits.used ?? 0} cr`;
   if (credits.usedPercent === null) return 'unknown';
   // 선불 달러 — 퍼센트만으로는 «얼마 남았나»를 못 읽는다.
   if (credits.periodType === 'prepaid-usd' && credits.balance !== null) return `${credits.usedPercent}% ($${credits.balance} left)`;
@@ -390,6 +635,7 @@ function formatCreditsCell(credits: CreditAxis): string {
 function formatCreditsWindow(credits: CreditAxis): string {
   if (credits.status !== 'ok') return '—';
   if (credits.periodType === 'prepaid-usd') return 'prepaid (창 없음)';
+  if (credits.periodType === 'extra-usage') return 'extra-usage (잔액)';
   const type = credits.periodType ?? '—';
   if (credits.periodStart && credits.periodEnd) {
     return `${type} ${credits.periodStart.slice(0, 10)}~${credits.periodEnd.slice(0, 10)}`;
@@ -407,7 +653,7 @@ function formatCreditsWindow(credits: CreditAxis): string {
  */
 export function formatWindowResetsIn(credits: CreditAxis, nowMs: number = Date.now()): string {
   if (credits.status !== 'ok') return '—';
-  if (credits.periodType === 'prepaid-usd') return 'n/a (리셋 없음)';
+  if (credits.periodType === 'prepaid-usd' || credits.periodType === 'extra-usage') return 'n/a (리셋 없음)';
   const end = credits.periodEnd ? Date.parse(credits.periodEnd) : Number.NaN;
   if (!Number.isFinite(end)) return 'unknown';
   const remainMs = end - nowMs;

package/src/cli/bench-cli.ts

@@ -0,0 +1,34 @@
+/** BENCH-ISOLATED-ARMS ④ — `elanous bench ls <id>`: 벤치 원장(`<config dir>/bench/<id>.jsonl`)을 읽는 한 자리. */
+import type { Command } from 'commander';
+import { benchLedgerPath, parseBenchSpec, readBenchLedger, renderBenchLs } from '../bench/bench.js';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+
+export interface BenchCliDeps {
+  readonly configDir?: () => string;
+  readonly write?: (line: string) => void;
+}
+
+export function registerBenchCommands(program: Command, deps: BenchCliDeps = {}): Command {
+  const bench = program.command('bench').description('벤치 팔(같은 골 · 모델만 다른 발사) 원장 — harness ask/say --bench 가 쓴다');
+  bench.command('ls <id>')
+    .description('벤치 원장 줄(bench id · base sha · 이미지 pin · 자식 모델 · 라운드)을 읽는다')
+    .option('--json', 'JSON 배열로')
+    .action((id: string, opts: { json?: boolean }) => {
+      const write = deps.write ?? ((line: string) => console.log(line));
+      let benchId: string;
+      try { benchId = parseBenchSpec(id).id; }
+      catch (error) {
+        console.error(`❌ ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 2;
+        return;
+      }
+      const configDir = (deps.configDir ?? getElanousConfigDir)();
+      const rows = readBenchLedger(benchId, configDir);
+      if (opts.json) write(JSON.stringify(rows));
+      else {
+        write(renderBenchLs(benchId, rows));
+        if (rows.length === 0) write(`원장 경로: ${benchLedgerPath(benchId, configDir)}`);
+      }
+    });
+  return bench;
+}

package/src/cli/doctor-cli.ts

@@ -40,6 +40,7 @@ import type { LlmInventory } from '../llm/local-manager/types.js';
 import { buildDoctorBundle } from './doctor-bundle.js';
 import { uploadDoctorBundle } from './doctor-bundle-upload.js';
 import { checkNodeModules, formatNodeModulesCheck, nodeModulesTrees } from './doctor-node-modules.js';
+import { formatHostDoctorLines, runHostDoctor, type HostDoctorExpected, type HostDoctorRemote } from '../fleet/host-doctor.js';
 
 function defaultCheckPythonEnv(): { status: 'ok' | 'fixable' | 'manual'; evidence: string; remedy?: string } {
   const c = checkPythonEnv(false);
@@ -198,6 +199,10 @@ export interface DoctorCliDeps extends DoctorOptions, Pick<DoctorFixDeps, 'home'
   /** Inject the upload transport and consent for isolated CLI tests. */
   uploadFetch?: typeof globalThis.fetch;
   confirmBundleUpload?: (message: string) => Promise<boolean>;
+  /** `doctor host` 원격 실행(시험 seam) — 기본 = ssh BatchMode · `local` 이면 이 기계. */
+  hostDoctorRemote?: HostDoctorRemote;
+  /** `doctor host` 가 대조할 HQ 실측값(설치 판 · 이미지 핀) — 없으면 해당 점검은 unmeasured. */
+  hostDoctorExpected?: HostDoctorExpected;
 }
 
 const repositoryRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
@@ -1240,6 +1245,22 @@ export function registerDoctorCommand(program: Command, deps: DoctorCliDeps = {}
       out.log(json ? JSON.stringify(opts.all ? checks : checks[0], null, 2) : checks.map(formatNodeModulesCheck).join('\n'));
       if (checks.some((check) => check.status !== 'ok')) setExitCode(1);
     });
+  doctor.command('host')
+    .description('Check whether a fleet host stands ready for its role (read-only · setup-status shape)')
+    .argument('<host>', "ssh name, or 'local' for this machine")
+    .option('--role <role>', 'host role: worker or hq', 'worker')
+    .option('--json', 'structured output')
+    .action((host: string, opts: { role: string; json?: boolean }, command: Command) => {
+      if (opts.role !== 'worker' && opts.role !== 'hq') {
+        err.error('--role must be worker or hq');
+        setExitCode(1);
+        return;
+      }
+      const json = opts.json === true || command.parent?.opts().json === true;
+      const report = runHostDoctor({ host, role: opts.role, remote: deps.hostDoctorRemote, expected: deps.hostDoctorExpected });
+      out.log(json ? JSON.stringify(report, null, 2) : formatHostDoctorLines(report).join('\n'));
+      if (!report.ok) setExitCode(1);
+    });
   doctor
     .option('--credentials', 'show per-credential details in human-readable output')
     .option('--bundle', 'write a redacted diagnostics archive for support')

package/src/cli/friendly-errors.ts

@@ -0,0 +1,113 @@
+import { detectLocale, type Locale } from '../expression/locale.js';
+import { classifyError } from '../session-runtime/retry-policy.js';
+
+export type FriendlyErrorCode =
+  | 'credential-missing'
+  | 'provider-unknown'
+  | 'model-unavailable'
+  | 'network'
+  | 'quota'
+  | 'context-too-long'
+  | 'config-broken'
+  | 'daemon-down'
+  | 'permission'
+  | 'unknown-command';
+
+export interface FriendlyMessage {
+  what: string;
+  why: string;
+  next: string;
+}
+
+export type FriendlyLanguage = 'ko' | 'en';
+
+export const FRIENDLY_ERRORS: Readonly<Record<FriendlyErrorCode, Readonly<Record<FriendlyLanguage, FriendlyMessage>>>> = {
+  'credential-missing': {
+    ko: { what: '모델에 접속할 자격이 없습니다', why: '이 provider 에 로그인하지 않았거나 키가 없습니다', next: 'elanous login' },
+    en: { what: 'No credentials for this model provider', why: 'You have not signed in or set a key', next: 'elanous login' },
+  },
+  'provider-unknown': {
+    ko: { what: '설정된 provider 를 모릅니다', why: 'llm.provider 값이 지원 목록에 없습니다', next: 'elanous config get llm.provider' },
+    en: { what: 'Unknown model provider', why: 'llm.provider is not a supported name', next: 'elanous config get llm.provider' },
+  },
+  'model-unavailable': {
+    ko: { what: '이 모델을 쓸 수 없습니다', why: 'provider 와 모델이 맞지 않거나 모델이 없습니다', next: 'elanous config get llm.model' },
+    en: { what: 'This model is not available', why: 'The provider and model do not match, or the model does not exist', next: 'elanous config get llm.model' },
+  },
+  network: {
+    ko: { what: '서버에 연결하지 못했습니다', why: '네트워크가 끊겼거나 서버가 응답하지 않습니다', next: 'elanous doctor' },
+    en: { what: 'Could not reach the server', why: 'The network is down or the server did not answer', next: 'elanous doctor' },
+  },
+  quota: {
+    ko: { what: '사용 한도에 걸렸습니다', why: '이 계정의 할당량을 다 썼거나 요청이 너무 잦습니다', next: 'elanous usage' },
+    en: { what: 'Usage limit reached', why: 'The account quota is used up or requests are too frequent', next: 'elanous usage' },
+  },
+  'context-too-long': {
+    ko: { what: '입력이 너무 깁니다', why: '모델이 한 번에 읽는 양을 넘었습니다', next: 'elanous ask "<더 짧은 질문>"' },
+    en: { what: 'The input is too long', why: 'It exceeds what the model reads at once', next: 'elanous ask "<shorter question>"' },
+  },
+  'config-broken': {
+    ko: { what: '설정 파일을 읽지 못했습니다', why: 'config 파일의 JSON 이 깨졌습니다', next: 'elanous doctor --fix' },
+    en: { what: 'Could not read the config file', why: 'The config JSON is malformed', next: 'elanous doctor --fix' },
+  },
+  'daemon-down': {
+    ko: { what: '엘라누스 데몬이 떠 있지 않습니다', why: '백그라운드 서비스가 꺼져 있습니다', next: 'elanous nexus' },
+    en: { what: 'The elanous daemon is not running', why: 'The background service is stopped', next: 'elanous nexus' },
+  },
+  permission: {
+    ko: { what: '파일에 접근할 권한이 없습니다', why: '이 사용자로 그 경로를 읽거나 쓸 수 없습니다', next: 'elanous doctor' },
+    en: { what: 'Permission denied', why: 'This user cannot read or write that path', next: 'elanous doctor' },
+  },
+  'unknown-command': {
+    ko: { what: '모르는 명령입니다', why: '명령 이름이 틀렸거나 이 판에 없습니다', next: 'elanous --help' },
+    en: { what: 'Unknown command', why: 'The name is misspelled or not in this version', next: 'elanous --help' },
+  },
+};
+
+function messageOf(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return typeof err === 'string' ? err : '';
+}
+
+function errnoOf(err: unknown): string {
+  if (err && typeof err === 'object') {
+    const code = (err as { code?: unknown }).code;
+    if (typeof code === 'string') return code;
+  }
+  return '';
+}
+
+/** Maps a thrown value to a friendly-error code by its wording and by the
+ *  retry-policy category. Returns null when nothing matches. */
+export function classifyFriendlyError(err: unknown): FriendlyErrorCode | null {
+  const msg = messageOf(err);
+  const errno = errnoOf(err);
+
+  if (/provider-model compatibility/i.test(msg)) return 'model-unavailable';
+  if (/\bunknown provider:/i.test(msg)) return 'provider-unknown';
+  if (/\bunavailable:\s+(set|run|configure)\b/i.test(msg)) return 'credential-missing';
+  if (/the elanous daemon is not running/i.test(msg)) return 'daemon-down';
+  if (/unknown command '/i.test(msg)) return 'unknown-command';
+  if (/input exceeds the \d+-token context budget/i.test(msg)) return 'context-too-long';
+  if (
+    /Unexpected token .*JSON|JSON Parse error|is not valid JSON|JSON at position/i.test(msg) ||
+    (err instanceof Error && err.name === 'SyntaxError' && /json/i.test(msg))
+  ) return 'config-broken';
+  if (errno === 'EACCES' || errno === 'EPERM' || /\b(EACCES|EPERM)\b/.test(msg)) return 'permission';
+
+  switch (classifyError(err)) {
+    case 'network-transient': return 'network';
+    case 'quota-exceeded':
+    case 'rate-limit': return 'quota';
+    case 'context-window-exceeded': return 'context-too-long';
+    case 'provider-unavailable': return 'credential-missing';
+    default: return null;
+  }
+}
+
+/** Renders one language only (ko, otherwise en). The last line is the one command to run. */
+export function formatFriendlyError(code: FriendlyErrorCode, locale: Locale = detectLocale()): string {
+  const language: FriendlyLanguage = locale === 'ko' ? 'ko' : 'en';
+  const { what, why, next } = FRIENDLY_ERRORS[code][language];
+  return `❌ ${what}\n  ↳ ${why}\n  ${next}`;
+}

package/src/cli/guardian-cli.ts

@@ -27,7 +27,32 @@ export function registerGuardianCommands(program: Command): void {
         const cfg = getUserConfig();
         // Live activation (and crontab retirement) is a separate operational change.
         if (cfg.guardian?.mode === 'live') throw new Error('guardian live activation is outside GUARD-ONE-a');
-        const result = await guardianTick(new Date(), plan, { config: cfg });
+        // The shadow observation is for the tick's entry time, however long the GC's evidence collection takes.
+        const tickAt = new Date();
+        // Local orphan GC is separate from the guardian's shadow-only schedule execution.
+        const orphanGc = cfg.guardian?.orphanGc ?? 'shadow';
+        try {
+          // off never loads the collector, so no ps snapshot is taken.
+          if (orphanGc !== 'off') {
+            // Loading the collector is inside the guard too: a GC that cannot even load only observes.
+            const { runMachineHeartbeat } = await import('../ops/machine-heartbeat.js');
+            await runMachineHeartbeat(plan.jobs.filter((job): job is typeof job & { command: string; cron: string } =>
+              job.source === 'crontab' && job.run_via === 'crontab' && !!job.enabled
+              && typeof job.command === 'string' && typeof job.cron === 'string')
+              .map(job => ({ command: job.command, cron: job.cron })), { timeZone: plan.timeZone, mode: orphanGc });
+          } else {
+            // Still one decision line per tick, so «switched off» is distinguishable from «tick never ran».
+            const { debug } = await import('../debug/log.js');
+            debug.log('ops.orphan-cli', 'decision', { mode: 'off', candidates: 0, collected: 0, alreadyEvidenced: 0, killed: 0 });
+          }
+        } catch (error) {
+          // The logger import is inside the guard as well: if it is the failing module, the shadow tick still runs.
+          try {
+            const { debug } = await import('../debug/log.js');
+            debug.log('ops.orphan-cli', 'observation-failed', { error: String(error) });
+          } catch { /* guardian shadow still runs */ }
+        }
+        const result = await guardianTick(tickAt, plan, { config: cfg });
         await writeStdoutJson(JSON.stringify(result, null, 2) + '\n');
       } finally { db.close(); }
     });