elanous 0.2.22 → 0.2.24

package/src/oauth/fallback-chain.ts

@@ -21,8 +21,14 @@
 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;
+/** 체인에 놓을 수 있는 칸. ⛔ 모르는 이름은 «조용히 건너뛰지 않고» 거부한다(오타 방어).
+ *
+ *  ⭐ `codex-credits`(CODEX-CREDITS-STEP · 2026-10-10) — «마지막 수단»으로 codex 를 «선불 크레딧»으로 쓴다.
+ *    한도 정책이 `fallback`(크레딧 ✗)이면 회전은 찬 계정에 «머물지» 않고(`no-candidate`) 체인의 다음 칸(grok)으로 간다.
+ *    그 grok 마저 못 쓰면 갈 곳이 없었다 — 이 칸을 grok «뒤»에 두면 그때만 크레딧으로 돌아온다.
+ *    ⛔ 첫 칸의 크레딧 금지(`codexQuotaPolicy`)는 그대로다 — 이 칸은 «체인이 여기까지 왔을 때»만 돈을 쓴다.
+ *    ⛔ 기본 체인에는 «없다» — 돈이라 사람이 config 에 «명시»할 때만 켜진다. */
+export const FALLBACK_STEPS = ['codex-rotate', 'grok', 'claude-pty', 'openrouter', 'codex-credits'] as const;
 export type FallbackStep = (typeof FALLBACK_STEPS)[number];
 
 /** 기본 체인 — ⛔⭐ **2026-08-20 에 `grok` 이 «기본»으로 들어왔다**(대표 지시).
@@ -78,6 +84,16 @@ 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 }
+  /** codex 로 «돌아와» 선불 크레딧으로 계속한다 — 체인의 `codex-credits` 칸(마지막 수단 · 유료).
+   *  `skipped` 는 «왜 앞 칸들을 못 썼나»(관측용 · 비밀 없음). */
+  | {
+    readonly action: 'codex-credits';
+    readonly skipped: readonly { readonly step: FallbackStep; readonly why: StayReason }[];
+    /** 크레딧으로 쓸 계정(잔액 많은 순 첫 계정) — 순수 판정은 비우고, 수집기(`resolveRunFallback`)가 채운다. */
+    readonly to?: RotationCandidate;
+  }
   /** 아무것도 안 한다 — 이유를 «값으로» 남긴다. */
   | { readonly action: 'stay'; readonly why: StayReason };
 
@@ -98,8 +114,12 @@ export type StayReason =
   | 'grok-unavailable'
   /** grok 자격은 있는데 «잔량이 소진»됐다 — 자격 부재와 «다른 값»이다. */
   | 'grok-exhausted'
+  /** 유료 OpenRouter 모델 또는 키가 없다. */
+  | 'openrouter-unavailable'
   /** claude PTY 의 최근 표본이 성숙 관문을 통과하지 못했거나 읽히지 않는다. */
-  | 'claude-pty-immature';
+  | 'claude-pty-immature'
+  /** 체인에 `codex-credits` 가 있는데 크레딧 잔액이 «확인된» codex 계정이 없다(모름 포함 — 돈이라 fail-closed). */
+  | 'codex-credits-unavailable';
 
 type FallbackRunPosition =
   | { readonly currentCredentialRateLimited?: false; readonly currentStep?: FallbackStep }
@@ -113,6 +133,10 @@ export type FallbackInput = {
   /** grok 자격이 «있나». ⛔ 「모른다」를 boolean 에 접지 마라 — 호출자가
    *  `resolveGrokCredential() !== null` 로 확정해서 준다. */
   readonly grokAvailable: boolean;
+  /** `llm.openrouter.fallbackModel` — 기본 모델로의 유료 폴백은 허용하지 않는다. */
+  readonly openrouterFallbackModel?: string;
+  /** OpenRouter 키 존재 여부(키 값 자체는 판정·관측에 넣지 않는다). */
+  readonly openrouterAvailable?: boolean;
   /**
    * grok 이 «지금 쓸 수 있나» — ⛔ 자격(`grokAvailable`)과 «다른 축»이다.
    *   'usable'    쓸 수 있다(잔량 있음 · 무제한 · 임계 미만)
@@ -132,6 +156,11 @@ export type FallbackInput = {
    * ⛔ 이 함수는 config 를 읽지 않는다 — 호출자가 이 칸을 준다.
    */
   readonly stayOnResetCreditAvailable?: boolean;
+  /**
+   * 크레딧 잔액이 «확인된»(잔액 > 0 · 보유 ≠ false) codex 계정이 하나라도 있나 — `codex-credits` 칸만 읽는다.
+   * ⛔ 생략·false 는 그 칸을 «건너뛴다»(돈이라 「모른다」를 통과로 접지 않는다 — grok 의 unknown 통과와 «반대»).
+   */
+  readonly codexCreditsAvailable?: boolean;
 } & FallbackRunPosition;
 
 /**
@@ -154,11 +183,13 @@ export function decideFallback(input: FallbackInput): FallbackDecision {
   const {
     rotation, chain, currentStep, currentCredentialRateLimited = false,
     grokAvailable, grokQuota = 'unknown', claudePtyMaturity, stayOnResetCreditAvailable = false,
+    openrouterFallbackModel, openrouterAvailable = false, codexCreditsAvailable = false,
   } = input;
+  const openrouter = { model: openrouterFallbackModel, available: openrouterAvailable, codexCreditsAvailable };
 
   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 +203,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 축이 끝났는데 체인 다음 칸도 없을 때 머무는 이유.
@@ -192,14 +223,18 @@ export function stayReasonWhenCodexAxisEnds(
   return 'chain-exhausted';
 }
 
+/** 칸 판정에 필요한 «나머지» 재료 — OpenRouter 모델·키, codex 크레딧 잔액 확인. */
+type StepExtras = { readonly model?: string; readonly available: boolean; readonly codexCreditsAvailable?: boolean };
+
 function stepAfterCodex(
   chain: readonly FallbackStep[],
   grokAvailable: boolean,
   grokQuota: 'usable' | 'exhausted' | 'unknown',
   claudePtyMaturity: ClaudePtyMaturity | undefined,
+  openrouter: StepExtras,
   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,22 +243,39 @@ function stepAfter(
   grokAvailable: boolean,
   grokQuota: 'usable' | 'exhausted' | 'unknown',
   claudePtyMaturity: ClaudePtyMaturity | undefined,
+  openrouter: StepExtras,
   whyIfNone: StayReason,
 ): FallbackDecision {
   const idx = currentStep === undefined ? -1 : chain.indexOf(currentStep);
   const rest = idx === -1 ? chain : chain.slice(idx + 1);
   let unavailableWhy: StayReason | undefined;
+  // `codex-credits` 칸이 «왜 앞 칸을 못 썼나»를 값으로 남긴다(관측 — 비밀 없음).
+  const skipped: { step: FallbackStep; why: StayReason }[] = [];
+  const skip = (step: FallbackStep, why: StayReason): void => { unavailableWhy = why; skipped.push({ step, why }); };
   for (const step of rest) {
+    if (step === 'codex-credits') {
+      // ⛔ 크레딧은 돈이다 — 잔액이 «확인된» 계정이 없으면 건너뛴다(「모른다」는 통과가 «아니다»).
+      if (openrouter.codexCreditsAvailable !== true) { skip(step, 'codex-credits-unavailable'); continue; }
+      return { action: 'codex-credits', skipped };
+    }
+    if (step === 'openrouter') {
+      const model = openrouter.model?.trim();
+      if (!openrouter.available || !model || !/^openrouter\/[^/\s]+\/[^\s]+$/.test(model)) {
+        skip(step, 'openrouter-unavailable');
+        continue;
+      }
+      return { action: 'switch-backend', backend: 'openrouter', model };
+    }
     if (step === 'grok') {
       // 자격 부재와 소진은 다른 값이다. 다음 칸이 있으면 그 칸을 살핀다.
-      if (!grokAvailable) { unavailableWhy = 'grok-unavailable'; continue; }
+      if (!grokAvailable) { skip(step, 'grok-unavailable'); continue; }
       // 「모른다」는 통과시킨다 — 못 읽었다고 갈 곳을 없애지 않는다.
-      if (grokQuota === 'exhausted') { unavailableWhy = 'grok-exhausted'; continue; }
+      if (grokQuota === 'exhausted') { skip(step, 'grok-exhausted'); continue; }
       return { action: 'switch-backend', backend: 'grok' };
     }
     if (step === 'claude-pty') {
       // 미성숙·못 읽음은 «건너뛴다» — 뒤에 다른 칸이 있으면 그 칸을 본다(없으면 이 사유로 머문다).
-      if (claudePtyMaturity?.mature !== true) { unavailableWhy = 'claude-pty-immature'; continue; }
+      if (claudePtyMaturity?.mature !== true) { skip(step, 'claude-pty-immature'); continue; }
       return { action: 'switch-backend', backend: 'claude' };
     }
   }
@@ -236,7 +288,11 @@ 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 'codex-credits':
+      return `codex 크레딧으로 계속 (마지막 칸 · 선불 크레딧 과금${decision.skipped.length ? ` · 건너뜀 ${decision.skipped.map((s) => `${s.step}:${s.why}`).join(', ')}` : ''})`;
     case 'stay':
       return `전환 없음 (${decision.why})`;
   }
@@ -273,24 +329,28 @@ export function grokQuotaFromCreditAxis(axis: {
 /**
  * budget 스냅샷 → 폴백 판정이 쓰는 세 값.
  *
- * ⭐ 공급자가 「리밋이 찼다」고 «말한» 것을 우리 산술보다 «먼저» 본다
+ * ⭐ 공급자가 「리밋이 찼다」고 «말한» 것을 weekly window 산술보다 «먼저» 본다
  *   (`UsageSnapshot.rateLimitReached` 주석의 그 권위를 그대로 따른다).
  * ⛔ 스냅샷이 없거나 판단할 재료가 없으면 `'unknown'` 이다 — 「소진」으로 접지 «않는다».
  * ⛔ 이 함수는 «네트워크를 안 친다» — 이미 채워진 캐시를 받는다.
  */
 export function grokQuotaFromUsageSnapshot(snapshot: {
   readonly rateLimitReached?: string;
+  readonly windows?: readonly { readonly kind: string; readonly remainingPercent: number }[];
   readonly credits?: { readonly hasCredits?: boolean; readonly unlimited?: boolean };
 } | null | undefined): 'usable' | 'exhausted' | 'unknown' {
   if (!snapshot) return 'unknown';
-  // ⛔ 공급자 판정이 이긴다 — 우리가 used >= limit 로 추론하지 않는다.
+  // ⛔ 공급자 판정이 이긴다 — 주간 창 판정보다 앞선다.
   if (typeof snapshot.rateLimitReached === 'string' && snapshot.rateLimitReached.length > 0) return 'exhausted';
+  const weekly = snapshot.windows?.find((window) => window.kind === 'weekly');
+  if (weekly && Number.isFinite(weekly.remainingPercent) && weekly.remainingPercent >= 0 && weekly.remainingPercent <= 100) {
+    return weekly.remainingPercent === 0 ? 'exhausted' : 'usable';
+  }
   const credits = snapshot.credits;
   if (!credits) return 'unknown';
   if (credits.unlimited === true) return 'usable';
   // ⛔⭐ `hasCredits` 는 브랜드마다 «다른 것»을 뜻할 수 있다 — grok 은 「선불 잔액이 있나」다.
-  //   ⇒ 사용률 창(rateLimitReached)이 이미 위에서 판정을 냈고, 여기 오면 그 신호가 «없다».
-  //   그러면 hasCredits=false 하나로 「소진」을 단정하지 «않는다» — 「모른다」가 정직하다.
+  //   ⇒ 주간 quota 창이 없으면 hasCredits=false 하나로 「소진」을 단정하지 «않는다» — 「모른다」가 정직하다.
   if (credits.hasCredits === true) return 'usable';
   return 'unknown';
 }

package/src/onboarding/first-run.ts

@@ -13,21 +13,34 @@ export interface FirstRunDeps {
   path?: string;
   detectProviders?: () => Promise<DetectedProvider[]>;
   isTTY?: boolean;
-  chooseProvider?: () => Promise<LLMProviderName | null>;
+  chooseProvider?: (detected: readonly LLMProviderName[]) => Promise<LLMProviderName | null>;
   print?: (message: string) => void;
   saveConfig?: (config: UserConfig, path: string) => void;
 }
 
-async function chooseProvider(): Promise<LLMProviderName | null> {
+const CHOICE_BASE: readonly LLMProviderName[] = ['openai-codex', 'grok', 'anthropic'];
+const CHOICE_LABEL: Partial<Record<LLMProviderName, string>> = { 'openai-codex': 'Codex', grok: 'Grok', anthropic: 'Claude' };
+const SUBSCRIPTION_PRIORITY = ['openai-codex', 'grok', 'anthropic', 'gemini', 'openai', 'openrouter'] as const;
+
+/** Menu order: detected subscriptions first (in priority order), then the remaining base choices. */
+export function orderProviderChoices(detected: readonly LLMProviderName[] = []): LLMProviderName[] {
+  return [...detected, ...CHOICE_BASE.filter((name) => !detected.includes(name))];
+}
+
+async function chooseProvider(detected: readonly LLMProviderName[] = []): Promise<LLMProviderName | null> {
+  const choices = orderProviderChoices(detected);
+  const menu = choices.map((name, i) => `${i + 1} ${CHOICE_LABEL[name] ?? name}`).join(', ');
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   try {
-    const answer = (await rl.question('Choose LLM (1 Codex, 2 Grok, 3 Claude; Enter to cancel): ')).trim();
-    return ({ '1': 'openai-codex', '2': 'grok', '3': 'anthropic' } as Record<string, LLMProviderName>)[answer] ?? null;
+    const answer = (await rl.question(`Choose LLM (${menu}; Enter to cancel): `)).trim();
+    return choices[Number(answer) - 1] ?? null;
   } finally {
     rl.close();
   }
 }
 
+const detectionLabel = (provider: string) => `${provider === 'openai-codex' ? 'codex' : provider} 구독`;
+
 export async function runFirstRun(deps: FirstRunDeps = {}): Promise<{
   outcome: 'ready' | 'needs-llm' | 'cancelled'; provider?: string; inputs: number;
 }> {
@@ -50,21 +63,31 @@ export async function runFirstRun(deps: FirstRunDeps = {}): Promise<{
     : undefined;
   const configured = existing && existing.source !== 'none'
     ? cfg.llm.provider : undefined;
-  const picked = (['openai-codex', 'grok', 'claude-code', 'anthropic', 'gemini', 'openai', 'openrouter'] as const)
-    .find((name) => providers.includes(name));
-  let provider: LLMProviderName | null | undefined = configured ??
-    (picked === 'claude-code' ? 'anthropic' : picked as LLMProviderName | undefined);
+  // claude-code is detected but has no subscription path in elanous: mapping it to the 'anthropic'
+  // API-key provider would save a provider whose first call fails for a subscription-only user.
+  const usable = SUBSCRIPTION_PRIORITY.filter((name) => providers.includes(name));
+  const detectionLine = (outcome: string) => `감지: ${providers.map(detectionLabel).join(' · ')} → ${outcome}`;
+  const needsLlm = (inputs: number, extra: string[] = []) => {
+    print('eln setup llm 으로 고르세요');
+    for (const line of extra) print(line);
+    observe('needs-llm', inputs);
+    return { outcome: 'needs-llm' as const, inputs };
+  };
+  let provider: LLMProviderName | null | undefined = configured ?? (usable.length === 1 ? usable[0] : undefined);
+  if (!configured && provider) print(detectionLine(provider));
   let inputs = 0;
   if (!provider) {
+    if (providers.length > 0) {
+      print(detectionLine(usable.length === 0
+        ? 'claude-code 구독은 구독으로 쓸 수 있는 경로가 없어 자동 선택하지 않음'
+        : '둘 이상 감지되어 고르세요'));
+    }
     if ((deps.isTTY ?? process.stdin.isTTY) !== true) {
-      print('eln setup llm 으로 고르세요');
       // FIRST-CHAT-NONTTY — bare `elanous` with no TTY gets the same one-line next step as the other entrances.
-      print(unattendedNextStepLine());
-      observe('needs-llm', 0);
-      return { outcome: 'needs-llm', inputs: 0 };
+      return needsLlm(0, [unattendedNextStepLine()]);
     }
     inputs = 1;
-    provider = await (deps.chooseProvider ?? chooseProvider)();
+    provider = await (deps.chooseProvider ?? chooseProvider)(usable);
     if (!provider) return { outcome: 'cancelled', inputs };
     observe('chosen', inputs);
   }
@@ -74,11 +97,7 @@ export async function runFirstRun(deps: FirstRunDeps = {}): Promise<{
         baseProvider: cfg.llm.provider, baseApiKey: cfg.llm.apiKey,
       })
     : undefined;
-  if (inputs === 1 && credential?.source === 'none') {
-    print('eln setup llm 으로 고르세요');
-    observe('needs-llm', inputs);
-    return { outcome: 'needs-llm', inputs };
-  }
+  if (inputs === 1 && credential?.source === 'none') return needsLlm(inputs);
   (deps.saveConfig ?? saveUserConfig)({
     ...cfg,
     llm: { ...cfg.llm, provider,

package/src/onboarding/web-first.ts

@@ -15,6 +15,8 @@ export interface WebFirstSetupDeps {
   /** Whether a person is at a terminal (stdin TTY). Without one the web path only uses a daemon that is already up. */
   isTty?: boolean;
   terminal?: boolean;
+  /** Bare first run never starts or waits for a missing daemon; explicit setup retains web launch. */
+  startIfMissing?: boolean;
   startedAt?: number;
   showNexus?: () => Promise<NexusShowResult>;
   startDaemon?: () => Promise<BgLaunchResult>;
@@ -67,9 +69,13 @@ export async function runWebFirstSetup(deps: WebFirstSetupDeps): Promise<'link-s
   let shown: NexusShowResult | undefined;
   try { shown = await show(); } catch { /* A missing daemon may make inspection fail. */ }
   const running = shown?.status === 'unregistered' || (shown?.status === 'registered' && shown.instance?.alive === true);
+  if (deps.startIfMissing === false && !running) {
+    print('오프라인 모드');
+    observe('fallback', 'offline');
+    return 'fallback';
+  }
   // A script, pipe or CI run never starts a daemon on its own: without a terminal the web path
-  // only uses a daemon that already answers health once. (install.sh runs first setup with
-  // stdin on /dev/tty, so the install → web path still starts one.)
+  // only uses a daemon that already answers health once.
   if ((deps.isTty ?? (process.stdin.isTTY === true)) !== true) {
     const rest = running ? shown?.urls?.rest.loopback : undefined;
     const up = rest && shown?.urls?.pwa.loopback
@@ -78,6 +84,12 @@ export async function runWebFirstSetup(deps: WebFirstSetupDeps): Promise<'link-s
   }
   const deadline = Date.now() + STARTUP_TIMEOUT_MS;
   if (!running || !shown?.urls?.pwa.loopback) {
+    if (deps.startIfMissing === false) {
+      print('오프라인 모드');
+      observe('fallback', 'offline');
+      return 'fallback';
+    }
+    print('웹 셋업을 위해 데몬을 시작합니다.');
     let launch: BgLaunchResult;
     try {
       launch = await (deps.startDaemon ?? (() => runBgLaunch({ out: { log: () => {}, error: () => {} } })))();
@@ -98,9 +110,15 @@ export async function runWebFirstSetup(deps: WebFirstSetupDeps): Promise<'link-s
         }
       }
     } catch { /* A daemon may not have published its URLs yet. */ }
+    if (deps.startIfMissing === false) break;
     const remaining = deadline - Date.now();
     if (remaining > 0) await Bun.sleep(Math.min(200, remaining));
   }
+  if (!healthy && deps.startIfMissing === false) {
+    print('오프라인 모드');
+    observe('fallback', 'offline');
+    return 'fallback';
+  }
   if (!healthy) return fallback(running ? 'daemon-health-unavailable' : 'daemon-health-timeout');
 
   if (!shown?.urls?.pwa.loopback) return fallback('daemon-unavailable');

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/ops/machine-heartbeat.ts

@@ -0,0 +1,185 @@
+import { writeFileSync, mkdirSync, existsSync, readFileSync, renameSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { CardStore } from '../task-cards/card-store.js';
+import { debug, redactSecretText } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { recordRunExit, readRunExits } from '../harness/harness-incidents.js';
+import { notifyOwners } from '../loops/checker.js';
+import { bunVersion, cliFingerprint, gcTools, orphanCandidates, type FenceGcDeps } from '../hq/fence.js';
+
+export interface MachineHeartbeatDeps extends FenceGcDeps {
+  root?: string;
+  now?: Date;
+  record?: typeof recordRunExit;
+  log?: typeof debug.log;
+  publish?: typeof notifyOwners;
+  card?: (command: string, day: string, evidencePaths: string[], root: string) => void;
+  version?: (pid: number, run: (binary: string, args: string[]) => string) => string;
+  /** How long the same tree must stay at the same CPU across guardian ticks before it is called stalled. */
+  stallMs?: number;
+  /** off = collect nothing · shadow (default) = candidates, evidence file and observation only · on = evidence, then SIGTERM. */
+  mode?: OrphanGcMode;
+}
+
+export type OrphanGcMode = 'off' | 'shadow' | 'on';
+
+/** A tree is «stalled» only when an earlier tick saw the very same tree at the very same CPU this long ago.
+ *  One in-tick second is not enough: Linux `ps time` has whole-second resolution and I/O waits burn no CPU. */
+export const ORPHAN_STALL_MS = 10 * 60_000;
+/** `shadowEvidenced`: shadow already wrote this tree's evidence once — later shadow ticks skip it (no lsof/sample, no new file). */
+type StallWatch = Record<string, { since: string; cpu: number; tree: string; shadowEvidenced?: true }>;
+
+function readStallWatch(path: string): StallWatch {
+  if (!existsSync(path)) return {};
+  const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as StallWatch : {};
+}
+
+/** One cause card per command/day, with incident files as attachments in the incidents section. */
+export function publishOrphanCauseCard(command: string, day: string, paths: string[], root: string): void {
+  const store = new CardStore(root);
+  try {
+    const hash = createHash('sha256').update(command).digest('hex').slice(0, 24);
+    const card = store.createCard({ goalId: `orphan-cli-${day}-${hash}`, title: `TC 원인 조사: ${redactSecretText(command)}` });
+    for (const path of paths) store.appendSection(card.id, { key: `incidents:${basename(path).replaceAll('.', '-')}`, owner: 'TC',
+      content: `증거: incidents/${basename(path)}\n가설(미확정): bun fs.watch 등 상주 핸들이 CLI 종료를 막음` });
+  } finally { store.close(); }
+}
+
+/** Run on the local guardian tick; an observation failure never authorizes termination. */
+export async function runMachineHeartbeat(schedules: readonly { command: string; cron: string }[], deps: MachineHeartbeatDeps = {}): Promise<{ collected: number; terminated: number; cards: number }> {
+  const mode = deps.mode ?? 'shadow';
+  if (mode === 'off') return { collected: 0, terminated: 0, cards: 0 };
+  const tools = gcTools(deps);
+  const now = deps.now ?? new Date();
+  const root = deps.root ?? effectiveInstanceRoot();
+  const timeZone = deps.timeZone;
+  const stallMs = deps.stallMs ?? ORPHAN_STALL_MS;
+  const watchPath = join(root, 'ops', 'orphan-cli-watch.json');
+  // An unreadable watch never authorizes termination: start over and only observe this tick.
+  let watch: StallWatch;
+  try { watch = readStallWatch(watchPath); } catch { watch = {}; }
+  const nextWatch: StallWatch = {};
+  const stalled: ReturnType<typeof orphanCandidates> = [];
+  const first = tools.snapshot();
+  await tools.sleep(1_000);
+  const second = tools.snapshot();
+  let collected = 0;
+  let terminated = 0;
+  let cards = 0;
+  let alreadyEvidenced = 0;
+  const logDecision = (): void => {
+    try { (deps.log ?? debug.log.bind(debug))('ops.orphan-cli', 'decision', { mode, candidates: stalled.length, collected, alreadyEvidenced, killed: terminated }); } catch { /* observe only */ }
+  };
+  for (const candidate of orphanCandidates(first, second, schedules, now, timeZone)) {
+    const key = `${candidate.process.pid}:${candidate.process.ppid}:${candidate.process.command}`;
+    const cpu = Math.round(candidate.tree.reduce((total, row) => total + row.cpuSeconds, 0) * 100) / 100;
+    const tree = candidate.tree.map(row => `${row.pid}:${row.cpuSeconds}`).join(',');
+    const seen = watch[key];
+    const elapsed = seen ? now.getTime() - Date.parse(seen.since) : NaN;
+    // Same tree, same CPU, and the process is at least as old as the watch (not a reused PID).
+    if (!seen || seen.cpu !== cpu || seen.tree !== tree || !(elapsed >= 0) || candidate.process.ageSeconds * 1000 + 2_000 < elapsed) {
+      nextWatch[key] = { since: now.toISOString(), cpu, tree };
+      continue;
+    }
+    nextWatch[key] = seen;
+    if (elapsed < stallMs) continue;
+    // Shadow never ends the tree, so the same hang stays stalled: evidence it once, not on every tick.
+    if (mode !== 'on' && seen.shadowEvidenced) { alreadyEvidenced++; continue; }
+    stalled.push(candidate);
+  }
+  try {
+    mkdirSync(join(root, 'ops'), { recursive: true });
+    const tmp = `${watchPath}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(nextWatch), { mode: 0o600 });
+    renameSync(tmp, watchPath);
+  } catch (error) {
+    // Without a durable watch the next tick cannot prove a stall either — observe only.
+    try { (deps.log ?? debug.log.bind(debug))('ops.orphan-cli', 'observation-failed', { stage: 'stall-watch', error: redactSecretText(String(error)) }); } catch { /* observe only */ }
+    logDecision();
+    return { collected, terminated, cards };
+  }
+  const writeWatch = (): void => {
+    mkdirSync(join(root, 'ops'), { recursive: true });
+    const tmp = `${watchPath}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(nextWatch), { mode: 0o600 });
+    renameSync(tmp, watchPath);
+  };
+  let shadowMarked = false;
+  for (const candidate of stalled) {
+    // Recheck the whole tree after slow diagnostics. A new child or CPU progress invalidates the decision.
+    let evidence: { command: string; ageSeconds: number; periodMinutes: number; pid: number; tree: number[]; lsof: string; sample: string; bunVersion: string; at: string };
+    try {
+      evidence = {
+        command: candidate.process.command, ageSeconds: candidate.process.ageSeconds, periodMinutes: candidate.periodMinutes, pid: candidate.process.pid,
+        tree: candidate.tree.map(row => row.pid),
+        lsof: tools.run('lsof', ['-p', candidate.tree.map(row => row.pid).join(',')]),
+        sample: tools.run('sample', [String(candidate.process.pid), '1']),
+        bunVersion: (deps.version ?? bunVersion)(candidate.process.pid, tools.run), at: now.toISOString(),
+      };
+      const latest = tools.snapshot();
+      const found = orphanCandidates(second, latest, schedules, now, timeZone).find(row => row.process.pid === candidate.process.pid);
+      if (!found || found.tree.length !== candidate.tree.length || found.tree.some(row => !candidate.tree.some(old => old.pid === row.pid))) continue;
+      // File + existing incident ledger + logs are committed before any signal is delivered.
+      const path = join(root, 'incidents', `orphan-cli-${now.getTime()}-${candidate.process.pid}-${randomUUID().slice(0, 8)}.json`);
+      mkdirSync(join(root, 'incidents'), { recursive: true });
+      const safe = JSON.stringify(evidence, (_key, value) => typeof value === 'string' ? redactSecretText(value) : value);
+      writeFileSync(path, safe, { flag: 'wx', mode: 0o600 });
+      const fingerprint = redactSecretText(cliFingerprint(candidate.process.command));
+      (deps.log ?? debug.log.bind(debug))('ops.orphan-cli', mode === 'on' ? 'evidence-before-termination' : 'shadow-evidence', {
+        path, command: redactSecretText(evidence.command), ageSeconds: evidence.ageSeconds, periodMinutes: evidence.periodMinutes, pid: evidence.pid,
+        tree: evidence.tree, lsof: redactSecretText(evidence.lsof), sample: redactSecretText(evidence.sample), bunVersion: evidence.bunVersion,
+      });
+      collected++;
+      if (mode !== 'on') {
+        const key = `${candidate.process.pid}:${candidate.process.ppid}:${candidate.process.command}`;
+        if (nextWatch[key]) { nextWatch[key] = { ...nextWatch[key]!, shadowEvidenced: true }; shadowMarked = true; }
+        continue;
+      }
+      // Children first: do not leave the stuck parent holding resources while descendants outlive it.
+      const signalFailures: Array<{ pid: number; error: string }> = [];
+      for (const row of [...found.tree].reverse()) {
+        try { tools.kill(row.pid); } catch (error) { signalFailures.push({ pid: row.pid, error: redactSecretText(String(error)) }); }
+      }
+      // The run-exit row records what the signals actually did, written after they were sent: SIGTERM only when every
+      // signal landed, otherwise no signal and the failures beside the evidence path. The evidence file and log above
+      // were committed before any signal. Either way the hang counts toward the cause card below.
+      (deps.record ?? recordRunExit)({ runId: `orphan-cli-${candidate.process.pid}-${randomUUID()}`, reason: `orphan-cli:${fingerprint}`, status: null,
+        signal: signalFailures.length === 0 ? 'SIGTERM' : null, at: now.toISOString(), pid: candidate.process.pid, entrance: 'guardian-tick',
+        lastLines: [path, ...signalFailures.map((failure) => `termination-failed pid=${failure.pid}: ${failure.error}`)] }, root);
+      if (signalFailures.length > 0) {
+        (deps.log ?? debug.log.bind(debug))('ops.orphan-cli', 'termination-failed', { path, pid: candidate.process.pid, failures: signalFailures });
+      } else terminated++;
+      const day = new Date(now.getTime() + 9 * 3_600_000).toISOString().slice(0, 10);
+      // One hang is one process: the same PID recorded on several ticks (its SIGTERM did not take) counts once.
+      const byPid = new Map<number, ReturnType<typeof readRunExits>[number]>();
+      for (const row of readRunExits(root)) {
+        if (row.reason !== `orphan-cli:${fingerprint}` || typeof row.pid !== 'number') continue;
+        if (new Date(Date.parse(row.at) + 9 * 3_600_000).toISOString().slice(0, 10) !== day) continue;
+        if (!byPid.has(row.pid)) byPid.set(row.pid, row);
+      }
+      const same = [...byPid.values()];
+      if (same.length >= 3) {
+        const paths = same.flatMap(row => row.lastLines ?? []).filter(file => existsSync(file));
+        if (paths.length < 3) {
+          (deps.log ?? debug.log.bind(debug))('ops.orphan-cli', 'cause-card-evidence-missing', { command: redactSecretText(candidate.process.command), count: same.length, evidence: paths.length });
+          continue;
+        }
+        const reason = `원인 카드: ${fingerprint} · 하루 ${same.length}회 매달림 · 증거 ${paths.join(' , ')} · 가설(미확정): bun fs.watch 등 상주 핸들이 CLI 종료를 막음`;
+        (deps.card ?? publishOrphanCauseCard)(fingerprint, day, paths, root);
+        cards += (deps.publish ?? notifyOwners)([{ id: `orphan-cli:${fingerprint}`, owner: 'TC', enabled: true, registered: true, state: 'failing', reason }], { root, now });
+      }
+    } catch (error) {
+      try { (deps.log ?? debug.log.bind(debug))('ops.orphan-cli', 'observation-failed', { pid: candidate.process.pid, error: redactSecretText(String(error)) }); } catch { /* log failure must not kill a process */ }
+    }
+  }
+  if (shadowMarked) {
+    // A lost mark only means one more evidence file next tick — never a signal.
+    try { writeWatch(); } catch (error) {
+      try { (deps.log ?? debug.log.bind(debug))('ops.orphan-cli', 'observation-failed', { stage: 'shadow-mark', error: redactSecretText(String(error)) }); } catch { /* observe only */ }
+    }
+  }
+  logDecision();
+  return { collected, terminated, cards };
+}