elanous 0.2.24 → 0.2.27

package/src/budget/cost-tier-advisor.ts

@@ -0,0 +1,91 @@
+// Cost-tier advisor — when forecast says warn/throttle, suggest one step down
+// (premium → balanced → economy). Tier table values are estimates until
+// MODEL-BENCH replaces them.
+
+import { debug } from '../debug/log.js';
+import type { ForecastResult } from './forecaster.js';
+
+export type CostTier = 'premium' | 'balanced' | 'economy';
+
+export const COST_TIERS: Record<CostTier, {
+  label: string;
+  stages: { authoring: string; implement: string; review: string; judge: string };
+  usdPerTaskEstimate: number;
+  qualityRisk: string;
+  source: 'estimate';
+}> = {
+  premium: {
+    label: '프리미엄',
+    stages: {
+      authoring: 'claude-opus-4-7',
+      implement: 'gpt-6-astra',
+      review: 'claude-opus-4-7',
+      judge: 'grok-4.7',
+    },
+    usdPerTaskEstimate: 1.2,
+    qualityRisk: '낮음 — 최고 품질 유지',
+    source: 'estimate',
+  },
+  balanced: {
+    label: '균형',
+    stages: {
+      authoring: 'claude-sonnet-4-6',
+      implement: 'gpt-5.6-terra',
+      review: 'claude-sonnet-4-6',
+      judge: 'grok-4.6',
+    },
+    usdPerTaskEstimate: 0.45,
+    qualityRisk: '중간 — 대부분 작업에 충분',
+    source: 'estimate',
+  },
+  economy: {
+    label: '절약',
+    stages: {
+      authoring: 'claude-haiku-4-5',
+      implement: 'gpt-6-luna',
+      review: 'gemini-2.5-flash',
+      judge: 'gemini-3.5-flash-lite',
+    },
+    usdPerTaskEstimate: 0.12,
+    qualityRisk: '높음 — 단순·반복 작업에 적합',
+    source: 'estimate',
+  },
+};
+
+const DOWN_ONE: Record<CostTier, CostTier | null> = {
+  premium: 'balanced',
+  balanced: 'economy',
+  economy: null,
+};
+
+export function adviseCostTier(input: {
+  current: CostTier;
+  forecast: Pick<ForecastResult, 'recommendation' | 'usedPercent' | 'atCurrentPaceReachesLimitAt'>;
+}): {
+  from: CostTier;
+  to: CostTier;
+  savingPercent: number;
+  qualityRisk: string;
+  reason: string;
+} | null {
+  const { current, forecast } = input;
+  if (forecast.recommendation === 'safe') return null;
+
+  const to = DOWN_ONE[current];
+  if (!to) return null;
+
+  const fromTier = COST_TIERS[current];
+  const toTier = COST_TIERS[to];
+  const savingPercent = Math.round((1 - toTier.usdPerTaskEstimate / fromTier.usdPerTaskEstimate) * 100);
+  const reason = `예산 사용 ${forecast.usedPercent}% · 예측 ${forecast.recommendation} → ${toTier.label}로 내리면 약 ${savingPercent}% 절감`;
+
+  debug.log('budget.cost-tier', 'advised', { from: current, to, savingPercent });
+
+  return {
+    from: current,
+    to,
+    savingPercent,
+    qualityRisk: toTier.qualityRisk,
+    reason,
+  };
+}

package/src/budget/llm-cost.ts

@@ -24,7 +24,11 @@ export interface LlmPricingUsd {
   longContext?: { thresholdTokens: number; inputPerM: number; outputPerM: number; cacheReadPerM?: number; cacheWritePerM?: number };
 }
 
-/** AWS Bedrock Global Standard prices, USD per million tokens (AWS pricing API, ap-northeast-2). */
+/** AWS Bedrock Global Standard prices, USD per million tokens (AWS pricing API, ap-northeast-2).
+ *  ⛔ BEDROCK-COST-LEDGER(0.2.26) — mantle-openai 비-Anthropic Bedrock id(`openai.gpt-6-sol`·`zai.glm-5` 등
+ *  `src/llm/bedrock.ts` BEDROCK_MODELS 의 `route:'mantle-openai'` 행)는 여기에 행이 «없다»: 단가 수치 근거가
+ *  하나도 확보되지 않았다. 근거 없는 id는 `isBedrockPricingModel` 게이트(`claude-` 시작)를 지나지 않아
+ *  `unknownCost()` 로 `kind:'unknown'` 에 머문다 — 0원으로 꾸미지 않는다. */
 export const BEDROCK_PRICING_USD: Readonly<Record<string, LlmPricingUsd>> = {
   'claude-haiku-5-5': { inputPerM: 0.1, outputPerM: 0.5, cacheWritePerM: 0.125, cacheReadPerM: 0.01 },
   'claude-sonnet-5-5': { inputPerM: 2, outputPerM: 10, cacheWritePerM: 2.5, cacheReadPerM: 0.1 },

package/src/budget/shadow-arms.ts

@@ -0,0 +1,77 @@
+// Shadow-arm launch plan — estimate which candidate models fit today's
+// shadow budget. Plans only: no live LLM calls.
+
+import { debug } from '../debug/log.js';
+import { estimateLlmCost } from './llm-cost.js';
+
+export type ShadowStage = 'authoring' | 'implement' | 'review' | 'judge';
+
+export type ShadowDifficulty = 'small' | 'medium' | 'umbrella' | 'rework';
+
+export interface PlanShadowArmsInput {
+  stage: ShadowStage;
+  difficulty: ShadowDifficulty;
+  inputTokens: number;
+  expectedOutputTokens: number;
+  candidates: string[];
+  spentTodayUsd: number;
+  dailyCapUsd: number;
+}
+
+export interface ShadowArmFire {
+  model: string;
+  estUsd: number;
+}
+
+export interface ShadowArmSkipped {
+  model: string;
+  reason: 'over-daily-cap' | 'unknown-price';
+}
+
+export interface ShadowArmsPlan {
+  fire: ShadowArmFire[];
+  skipped: ShadowArmSkipped[];
+  remainingUsd: number;
+}
+
+export function planShadowArms(input: PlanShadowArmsInput): ShadowArmsPlan {
+  const fire: ShadowArmFire[] = [];
+  const skipped: ShadowArmSkipped[] = [];
+  let remainingUsd = input.dailyCapUsd - input.spentTodayUsd;
+  let overDailyCap = false;
+
+  for (const model of input.candidates) {
+    // Once the cap is crossed, every later arm is over-daily-cap — even one
+    // whose price is unknown (the cap decision comes first).
+    if (overDailyCap) {
+      skipped.push({ model, reason: 'over-daily-cap' });
+      continue;
+    }
+    const estimate = estimateLlmCost({
+      model,
+      inputTokens: input.inputTokens,
+      outputTokens: input.expectedOutputTokens,
+    });
+    if (estimate.kind !== 'known') {
+      skipped.push({ model, reason: 'unknown-price' });
+      continue;
+    }
+    if (estimate.usd > remainingUsd) {
+      skipped.push({ model, reason: 'over-daily-cap' });
+      overDailyCap = true;
+      continue;
+    }
+    fire.push({ model, estUsd: estimate.usd });
+    remainingUsd -= estimate.usd;
+  }
+
+  debug.log('budget.shadow-arms', 'planned', {
+    stage: input.stage,
+    difficulty: input.difficulty,
+    fire: fire.length,
+    skipped: skipped.length,
+    remainingUsd,
+  });
+
+  return { fire, skipped, remainingUsd };
+}

package/src/budget/types.ts

@@ -158,8 +158,9 @@ export type ResetCreditExpiryAxis =
   | { readonly status: 'expired'; readonly expiresAt: string; readonly hasUnknownExpiry: boolean };
 
 export interface AccountUsageRow {
-  /** `zai` = GLM Coding Plan(ZAI-CODING-PLAN-PROVIDER) — `ZAI_API_KEY` 가 있을 때만 행이 생긴다. */
-  readonly provider: 'codex' | 'grok' | 'openrouter' | 'zai';
+  /** `zai` = GLM Coding Plan(ZAI-CODING-PLAN-PROVIDER) — `ZAI_API_KEY` 가 있을 때만 행이 생긴다.
+   *  `claude` = Claude Code 구독(CLAUDE-USAGE-WINDOW) — OAuth 토큰이 있을 때만 행이 생긴다. */
+  readonly provider: 'codex' | 'claude' | 'grok' | 'openrouter' | 'zai';
   readonly accountName: string;
   readonly accountCount: number;
   readonly soleAccount: boolean;
@@ -173,7 +174,8 @@ export interface AccountUsageRow {
 export interface UnifiedUsageReport {
   readonly rows: readonly AccountUsageRow[];
   /** `zai` 는 키가 있을 때만 실린다(없으면 종전 JSON 과 같다). */
-  readonly accountCounts: Readonly<Record<'codex' | 'grok' | 'openrouter', number>> & { readonly zai?: number };
+  /** `claude` 도 토큰이 있을 때만 실린다(없으면 종전 JSON 과 같다). */
+  readonly accountCounts: Readonly<Record<'codex' | 'grok' | 'openrouter', number>> & { readonly claude?: number; readonly zai?: number };
   /** GLM Coding Plan 상세(창 · 우리 적산 · 잔액 사용 · 마지막 한도 코드) — 키가 있을 때만. */
   readonly zaiCodingPlan?: import('../llm/zai-coding-plan.js').ZaiUsageView;
 }

package/src/budget/unified-usage.ts

@@ -3,9 +3,12 @@
 // 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,
@@ -20,6 +23,7 @@ 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,
@@ -28,6 +32,7 @@ import {
 import type {
   AccountUsageRow,
   CreditAxis,
+  RateWindow,
   ResetCreditExpiryAxis,
   SubscriptionAxis,
   UnifiedUsageReport,
@@ -59,25 +64,179 @@ export interface UnifiedUsageDeps {
   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, zai] = 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, ...(zai?.rows ?? [])],
+    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 ? { zai: 1 } : {}),
+      // 종전과 같게: 조회가 성공했으면(창이 비어도) zai 1 · 실패해 error 행만 남았어도 1(실패 행도 센다).
+      ...(zai.zai || zai.rows.length > 0 ? { zai: 1 } : {}),
     },
-    ...(zai ? { zaiCodingPlan: zai.view } : {}),
+    ...(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,
   };
 }
 
@@ -429,6 +588,11 @@ 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');

package/src/cli/control-cli.ts

@@ -31,6 +31,35 @@ function reasonFor(error: unknown, token?: string): string {
   return token ? message.replaceAll(token, '[redacted]') : message;
 }
 
+/** Doctor's read-only live source. One malformed Nexus machine row invalidates the whole
+ *  reading: doctor reports unmeasured rather than treating a partial registry as complete. */
+export async function listMachineResources(options: { primaryUrl?: string; queryToken?: string; port?: string; root?: string; fetch?: (input: URL | RequestInfo, init?: RequestInit) => Promise<Response> } = {}): Promise<ResourceView[]> {
+  const portOverride = options.port ?? (process.env.ELANOUS_CONTROL_PORT?.trim() || undefined);
+  const primary = await resolvePrimary({
+    role: 'query',
+    ...(options.root ? { root: options.root } : {}),
+    config: { url: options.primaryUrl, tokens: options.queryToken ? { query: options.queryToken } : undefined },
+    ...(portOverride !== undefined ? { port: Number(portOverride) } : {}),
+  });
+  const token = primary.token;
+  if (!token) throw new Error('control query token unavailable');
+  const url = new URL('/v1/resources', primary.url);
+  url.searchParams.set('kind', 'machine');
+  const response = await (options.fetch ?? globalThis.fetch)(url, {
+    headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(5000),
+  });
+  if (!response.ok) throw new Error(`control HTTP ${response.status}`);
+  const body: unknown = await response.json();
+  if (!body || typeof body !== 'object' || !('resources' in body) || !Array.isArray(body.resources) ||
+      body.resources.some((row: unknown) => !row || typeof row !== 'object' ||
+        (row as ResourceView).kind !== 'machine' || typeof (row as ResourceView).machine !== 'string' ||
+        typeof (row as ResourceView).name !== 'string' || typeof (row as ResourceView).expired !== 'boolean' ||
+        !((row as ResourceView).attrs && typeof (row as ResourceView).attrs === 'object'))) {
+    throw new Error('invalid machine resource response');
+  }
+  return body.resources as ResourceView[];
+}
+
 export async function runResourcesQuery(options: { where?: string; kind?: string; port?: string; primaryUrl?: string; queryToken?: string; json?: boolean }): Promise<number> {
   let base = '';
   let token: string | undefined;

package/src/cli/doctor-cli.ts

@@ -27,7 +27,7 @@ import {
   type ReadinessReport,
   type SubstrateSignals,
 } from './doctor-readiness.js';
-import { debug } from '../debug/log.js';
+import { debug, redactSecretText } from '../debug/log.js';
 import { resolveDaemonEndpoint, type ResolveDaemonEndpointOpts } from '../nexus/daemon-endpoint.js';
 import { applyDoctorFixes, applyGitInstall, applyServiceRestart, applySudoFixes, planDoctorFixes, type DoctorFixDeps, type DoctorFixItem } from './doctor-fix.js';
 import { ADVISABLE_DOCTOR_FIX_IDS, adviseDoctorFixes, type DoctorAdvice } from './doctor-llm-assist.js';
@@ -40,6 +40,10 @@ 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 HostDoctorOptions, type HostDoctorRemote } from '../fleet/host-doctor.js';
+import { listMachineResources } from './control-cli.js';
+import type { ResourceView } from '../control-plane/ledger.js';
+import { loadMachineLedger } from '../machines/machine-ledger.js';
 
 function defaultCheckPythonEnv(): { status: 'ok' | 'fixable' | 'manual'; evidence: string; remedy?: string } {
   const c = checkPythonEnv(false);
@@ -198,9 +202,18 @@ 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;
+  /** HQ membership readings; injected tests need no live Nexus. */
+  hostDoctorMembership?: () => Promise<NonNullable<HostDoctorOptions['membership']>>;
+  /** Nexus machine query seam; tests can exercise the default assembly without contacting a live service. */
+  hostDoctorMachineResources?: () => Promise<ResourceView[]>;
 }
 
 const repositoryRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const observationError = (error: unknown): string => redactSecretText(error instanceof Error ? error.message : String(error)).slice(0, 200);
 const tavilyNames = new Set(['TAVILY_API_KEY', 'TAVILY_KEY']);
 
 function defaultCodeRevision(): string | undefined {
@@ -1206,6 +1219,52 @@ function formatDoctorAdvice(advice: DoctorAdvice): string {
   ].join('\n');
 }
 
+function formatDoctorAdviceProposal(advice: DoctorAdvice, report: DoctorReport): { text: string; itemId: string; observedValue: string } | null {
+  const proposal = advice.ok ? advice.order[0] : undefined;
+  if (!proposal) return null;
+  const observation = report.readiness?.items.find((item) => item.id === proposal.readinessId);
+  if (!observation) return null;
+  const observedValue = `${observation.status}: ${observation.evidence}`;
+  return {
+    itemId: proposal.readinessId,
+    observedValue,
+    text: [
+      `LLM 제안: ${proposal.why}`,
+      `운영 팩 항목 id: ${proposal.readinessId}`,
+      `현재 관측값: ${observedValue}`,
+    ].join('\n'),
+  };
+}
+
+async function recordDoctorAdviceResponse(
+  proposal: { itemId: string; observedValue: string },
+  accepted: boolean,
+): Promise<void> {
+  debug.log('doctor.advise', accepted ? 'accepted' : 'rejected', {
+    itemId: proposal.itemId,
+    observedValue: proposal.observedValue,
+    applied: 0,
+  });
+}
+
+async function presentDoctorAdviceProposal(
+  advice: DoctorAdvice,
+  report: DoctorReport,
+  deps: DoctorCliDeps,
+  json: boolean,
+  announce: (text: string) => void,
+): Promise<{ proposal: { itemId: string; observedValue: string }; response: boolean | null; text: string } | null> {
+  const formatted = formatDoctorAdviceProposal(advice, report);
+  if (!formatted) return null;
+  const proposal = { itemId: formatted.itemId, observedValue: formatted.observedValue };
+  const interactive = deps.adviceInteractive ?? (process.stdin.isTTY === true && (json ? process.stderr.isTTY === true : process.stdout.isTTY === true));
+  if (!interactive) return { proposal, response: null, text: formatted.text };
+  announce(formatted.text);
+  const accepted = await (deps.confirmAdvice ?? ((message) => confirmDoctorAdvice(message, json)))('이 제안을 수락할까요? [y/N] ');
+  await recordDoctorAdviceResponse(proposal, accepted);
+  return { proposal, response: accepted, text: `${formatted.text}\n응답: ${accepted ? '수락' : '거절'}` };
+}
+
 async function confirmDoctorAdvice(message: string, json: boolean): Promise<boolean> {
   const prompt = createInterface({ input: process.stdin, output: json ? process.stderr : process.stdout });
   try { return /^(y|yes)$/i.test((await prompt.question(message)).trim()); }
@@ -1240,6 +1299,43 @@ 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 (read-only; membership needs a repository checkout and a named remote worker)')
+    .argument('<host>', "SSH name in fleet intent; an unknown name fails membership; 'local' checks readiness without membership")
+    .option('--role <role>', 'host role: worker or hq', 'worker')
+    .option('--json', 'structured output')
+    .action(async (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;
+      let membership: HostDoctorOptions['membership'];
+      if (opts.role === 'worker' && host !== 'local') {
+        if (deps.hostDoctorMembership) membership = await deps.hostDoctorMembership();
+        else {
+          let intent: NonNullable<HostDoctorOptions['membership']>['intent'] = null;
+          let machines: NonNullable<HostDoctorOptions['membership']>['machines'] = null;
+          let parentHosts: NonNullable<HostDoctorOptions['membership']>['parentHosts'] = null;
+          let intentError: string | undefined;
+          let machinesError: string | undefined;
+          let parentHostsError: string | undefined;
+          try { intent = loadMachineLedger(deps.repositoryRoot ?? repositoryRoot); } catch (error) { intentError = observationError(error); }
+          try { machines = await (deps.hostDoctorMachineResources ?? listMachineResources)(); } catch (error) { machinesError = observationError(error); }
+          try {
+            // UserConfig permits one parent object or an array of parent objects, never a bare host string.
+            const configured = (deps.userConfig ?? (deps.getUserConfig ?? getUserConfig)()).taskAgent?.parentHost;
+            if (configured === null) parentHostsError = 'taskAgent.parentHost is null';
+            else parentHosts = configured === undefined ? [] : Array.isArray(configured) ? configured : [configured];
+          } catch (error) { parentHostsError = observationError(error); }
+          membership = { intent, machines, parentHosts, intentError, machinesError, parentHostsError };
+        }
+      }
+      const report = runHostDoctor({ host, role: opts.role, remote: deps.hostDoctorRemote, expected: deps.hostDoctorExpected, membership });
+      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')
@@ -1383,10 +1479,17 @@ export function registerDoctorCommand(program: Command, deps: DoctorCliDeps = {}
       // Planning never writes; existing repairs require --yes, while git alone can use affirmative TTY consent.
       const plan = planDoctorFixes(fixes);
       const advice = opts.advise ? await requestDoctorAdvice(report, plan, deps) : undefined;
+      const proposal = advice && !opts.fix ? await presentDoctorAdviceProposal(advice, report, deps, opts.json === true, (text) => {
+        if (opts.json) err.error(text);
+        else out.log(text);
+      }) : null;
       if (!opts.fix) {
         out.log(opts.json
-          ? JSON.stringify({ ...report, advise: advice }, null, 2)
-          : [formatDoctorReport(report, { credentials: opts.credentials }), formatDoctorAdvice(advice!)].join('\n'));
+          ? JSON.stringify({ ...report, advise: advice, ...(proposal ? { adviceProposal: { itemId: proposal.proposal.itemId, observedValue: proposal.proposal.observedValue, response: proposal.response } } : {}) }, null, 2)
+          : [
+            formatDoctorReport(report, { credentials: opts.credentials }),
+            proposal?.response === null ? proposal.text : proposal ? `응답: ${proposal.response ? '수락' : '거절'}` : formatDoctorAdvice(advice!),
+          ].join('\n'));
         if (report.requiredMissing?.length) setExitCode(1);
         return;
       }