elanous 0.2.23 → 0.2.25

package/scripts/tsc-baseline-cache.ts

@@ -0,0 +1,172 @@
+/**
+ * 승격 착지의 base 쪽 tsc 진단을 «main 커밋별로 한 번만» 재고 재사용하는 캐시.
+ * 키 = base sha ⊕ tsc 명령 ⊕ 설정 파일(base 커밋에서 git show 로 읽은 내용) 해시 ⊕ 작업 트리 설치 키(bun.lock 실물) ⊕ tsc 판.
+ * 값 = rebase 전 정규화 진단(워크트리 절대 경로는 «<ROOT>» 자리표로 저장).
+ * ⛔ 캐시 실패는 호출자에게 던지지 않는다 — 읽기·쓰기 모두 miss 로 떨어진다.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { elanousStateRoot } from '../src/autopilot/state-paths.js';
+import type { TypecheckError } from '../src/typecheck-ratchet.js';
+
+export const ROOT_PLACEHOLDER = '<ROOT>';
+export const BASELINE_CACHE_MAX_ENTRIES = 50;
+const CACHE_FORMAT = 2;
+
+/** 키에 들어가는 «기준 커밋의 설정 파일» — 이 중 하나라도 달라지면 같은 sha 라도 다른 진단이다. */
+export const BASELINE_CACHE_CONFIG_FILES = ['tsconfig.gate.json', 'apps/pwa/tsconfig.json', 'tsconfig.pwa-env.json', 'tsconfig.json', 'bun.lock'] as const;
+
+export interface BaselineCacheOptions {
+  /** 캐시 디렉터리. 생략하면 `<상태 디렉터리>/cache/tsc-baseline`. */
+  dir?: string;
+  env?: NodeJS.ProcessEnv;
+  /** git 실행 심 — 출력 바이트를 돌려주고 실패하면 던진다. */
+  git?: (args: string[], cwd: string) => Buffer;
+  /** 작업 트리 설치 파일 읽기 심 — 파일 바이트를 돌려주고 읽을 수 없으면 던진다. */
+  readInstallFile?: (path: string) => Buffer;
+  /** tsc 판 조회 심. */
+  tscVersion?: (cwd: string) => string;
+  maxEntries?: number;
+}
+
+export type BaselineCacheLookup =
+  | { result: 'hit'; diagnostics: TypecheckError[] }
+  | { result: 'miss' }
+  | { result: 'corrupt' };
+
+export function baselineCacheEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.TSC_BASELINE_CACHE?.trim() !== '0';
+}
+
+export function defaultBaselineCacheDir(): string {
+  return join(elanousStateRoot(), 'cache', 'tsc-baseline');
+}
+
+function defaultGit(args: string[], cwd: string): Buffer {
+  const env = { ...process.env };
+  delete env.GIT_DIR;
+  delete env.GIT_WORK_TREE;
+  delete env.GIT_COMMON_DIR;
+  return execFileSync('git', args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 });
+}
+
+function defaultTscVersion(cwd: string): string {
+  try {
+    const parsed = JSON.parse(readFileSync(join(cwd, 'node_modules', 'typescript', 'package.json'), 'utf8')) as { version?: unknown };
+    return typeof parsed.version === 'string' ? parsed.version : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/** 키에 들어가는 «작업 트리에 실제로 깔린 판» — base 쪽 bun.lock 이 같아도 설치가 다르면 진단이 다르다. */
+const BASELINE_CACHE_INSTALL_FILES = ['bun.lock', 'apps/pwa/bun.lock'] as const;
+
+/**
+ * 지금 트리에 실제로 깔린 판의 키 — 작업 트리 루트 `bun.lock`(⊕ 있으면 `apps/pwa/bun.lock`) 파일 해시.
+ * 루트 `bun.lock` 을 못 읽으면 undefined(호출자는 캐시 없이 잰다 — base 키 규율과 같다) · `apps/pwa/bun.lock` 은 못 읽으면 absent.
+ */
+export function workingTreeInstallKey(cwd: string, options: Pick<BaselineCacheOptions, 'readInstallFile'> = {}): string | undefined {
+  const read = options.readInstallFile ?? ((path: string) => readFileSync(path));
+  const files: Record<string, string> = {};
+  for (const file of BASELINE_CACHE_INSTALL_FILES) {
+    try {
+      files[file] = createHash('sha256').update(read(join(cwd, file))).digest('hex');
+    } catch {
+      if (file === 'bun.lock') return undefined;
+      files[file] = 'absent';
+    }
+  }
+  return createHash('sha256').update(JSON.stringify(files)).digest('hex');
+}
+
+/** 키를 못 만들면(base 를 sha 로 풀 수 없음 등) undefined — 호출자는 캐시 없이 잰다. */
+export function computeBaselineCacheKey(base: string, command: string, cwd: string, options: BaselineCacheOptions = {}): string | undefined {
+  try {
+    const git = options.git ?? defaultGit;
+    const sha = git(['rev-parse', '--verify', `${base}^{commit}`], cwd).toString('utf8').trim();
+    if (!/^[0-9a-f]{40,64}$/.test(sha)) return undefined;
+    const files: Record<string, string> = {};
+    for (const file of BASELINE_CACHE_CONFIG_FILES) {
+      try {
+        files[file] = createHash('sha256').update(git(['show', `${sha}:${file}`], cwd)).digest('hex');
+      } catch {
+        files[file] = 'absent';
+      }
+    }
+    const install = workingTreeInstallKey(cwd, options);
+    if (install === undefined) return undefined;
+    const tsc = (options.tscVersion ?? defaultTscVersion)(cwd);
+    return createHash('sha256').update(JSON.stringify({ format: CACHE_FORMAT, sha, command, files, install, tsc })).digest('hex');
+  } catch {
+    return undefined;
+  }
+}
+
+function worktreeRoots(worktree: string): string[] {
+  const real = (() => { try { return realpathSync(worktree); } catch { return worktree; } })();
+  return [...new Set([worktree, real])].sort((left, right) => right.length - left.length);
+}
+
+/** rebase 전 진단의 워크트리 절대 경로를 «<ROOT>» 로 바꾼다(긴 경로 먼저). */
+export function toPlaceholderPaths(diagnostics: readonly TypecheckError[], worktree: string): TypecheckError[] {
+  const roots = worktreeRoots(worktree);
+  const swap = (text: string): string => roots.reduce((acc, root) => acc.split(root).join(ROOT_PLACEHOLDER), text);
+  return diagnostics.map((diagnostic) => ({ ...diagnostic, line: swap(diagnostic.line), file: swap(diagnostic.file) }));
+}
+
+function entryFile(dir: string, key: string): string {
+  return join(dir, `${key}.json`);
+}
+
+function isStoredDiagnostic(value: unknown): value is TypecheckError {
+  if (!value || typeof value !== 'object') return false;
+  const entry = value as Record<string, unknown>;
+  return typeof entry.file === 'string' && typeof entry.line === 'string' && (entry.code === undefined || typeof entry.code === 'string');
+}
+
+export function lookupBaselineCache(key: string, options: BaselineCacheOptions = {}): BaselineCacheLookup {
+  try {
+    const file = entryFile(options.dir ?? defaultBaselineCacheDir(), key);
+    if (!existsSync(file)) return { result: 'miss' };
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as { format?: unknown; key?: unknown; diagnostics?: unknown };
+    if (parsed.format !== CACHE_FORMAT || parsed.key !== key || !Array.isArray(parsed.diagnostics) || !parsed.diagnostics.every(isStoredDiagnostic)) {
+      return { result: 'corrupt' };
+    }
+    try { const now = new Date(); utimesSync(file, now, now); } catch { /* 보존 순서 갱신 실패는 무해하다 */ }
+    return { result: 'hit', diagnostics: parsed.diagnostics };
+  } catch {
+    return { result: 'corrupt' };
+  }
+}
+
+function pruneBaselineCache(dir: string, keep: number): void {
+  const entries = readdirSync(dir)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => ({ name, mtimeMs: statSync(join(dir, name)).mtimeMs }))
+    .sort((left, right) => right.mtimeMs - left.mtimeMs || left.name.localeCompare(right.name));
+  for (const stale of entries.slice(keep)) rmSync(join(dir, stale.name), { force: true });
+}
+
+/** `<ROOT>` 자리표가 든 진단을 원자 쓰기(임시→rename)로 저장한다. 성공 여부만 돌려주고 던지지 않는다. */
+export function storeBaselineCache(key: string, command: string, diagnostics: readonly TypecheckError[], options: BaselineCacheOptions = {}): boolean {
+  try {
+    const dir = options.dir ?? defaultBaselineCacheDir();
+    mkdirSync(dir, { recursive: true });
+    const file = entryFile(dir, key);
+    const temporary = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    try {
+      writeFileSync(temporary, JSON.stringify({ format: CACHE_FORMAT, key, command, storedAt: new Date().toISOString(), diagnostics }));
+      renameSync(temporary, file);
+    } catch (error) {
+      rmSync(temporary, { force: true });
+      throw error;
+    }
+    try { pruneBaselineCache(dir, options.maxEntries ?? BASELINE_CACHE_MAX_ENTRIES); } catch { /* 정리 실패는 저장 성공을 뒤집지 않는다 */ }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/scripts/usage-rollup.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 // 실행 칸(Pod 등)이 사라지기 «전»에 자기 llm.usage 를 한 줄로 요약해 stdout 에 — 슈퍼바이저가 호스트로 가져간다.
 // RFC-fleet-supervisor-substrates-benchmark-and-token-accounting §A2·F2 · 2026-09-25.
-//   bun scripts/usage-rollup.ts [--since 6h]
+//   bun scripts/usage-rollup.ts [--since 6h] [--partial [--seq N]]
 //   출력: ELANOUS_USAGE_ROLLUP {"substrate","runId","armId","truncated","rows":[{site,provider,model,calls,inputTokens,outputTokens,cacheReadInputTokens,cacheCreationInputTokens,usdKnown,unknownCostCalls}],"total":{…}}
 // ⛔ 의존성 없음(설치본 `elanous` 만 부른다) — clone 에 node_modules 가 없어도 돈다.
 // ⛔ 비용을 모르는 호출(cost.kind≠known)은 0 으로 합치지 않고 따로 센다.
@@ -9,18 +9,64 @@
 //    호스트(맥)에서 돌리면 테스트 우주·워크트리·다른 트랙의 런까지 섞인다(📏 09-25: 운영만 16회 vs 전체 124회). 호스트 집계용이 아니다.
 import { spawnSync } from 'node:child_process';
 
-export interface UsageRow { site: string; provider: string; model: string; calls: number; inputTokens: number; outputTokens: number; cacheReadInputTokens: number; cacheCreationInputTokens: number; cacheCreationUnmeasuredCalls: number; usdKnown: number; unknownCostCalls: number; includedCalls: number; apiEquivalentUsd: number }
+export interface UsageRow { site: string; provider: string; model: string; calls: number; inputTokens: number; outputTokens: number; cacheReadInputTokens: number; cacheCreationInputTokens: number; cacheCreationUnmeasuredCalls: number; usdKnown: number; unknownCostCalls: number; includedCalls: number; apiEquivalentUsd: number;
+  /** OR-BYOK-COST — BYOK 호출 수 ⊕ 그중 상류 청구액 합(알려진 것만) ⊕ 상류를 모르는 호출 수. BYOK 를 본 행에만 있다(종전 행 바이트 불변). */
+  byokCalls?: number; byokUpstreamUsd?: number; byokUpstreamUnknownCalls?: number }
+
+type UsageData = { site?: string; provider?: string; billingProvider?: string; model?: string; inputTokens?: number; outputTokens?: number; cacheReadInputTokens?: number; cacheCreationInputTokens?: number; cost?: { kind?: string; usd?: number }; podRollupKey?: string; partial?: boolean; partialSeq?: number; partialAt?: string };
+
+/** 재방출 행 dedup 에 필요한 칸만 — 호스트 소비처(bench-report · `elanous usage`)도 같은 규칙을 쓴다. */
+export type PodRollupKeyed = { podRollupKey?: unknown; partial?: unknown; partialSeq?: unknown; partialAt?: unknown };
+
+/** 같은 podRollupKey 두 행 중 어느 쪽이 더 완전한가 — 최종 > 부분 · 부분끼리는 seq 큰 쪽 · 같으면 at 늦은 쪽. 완전히 같으면 앞 행을 둔다. */
+function rollupRowBeats(next: PodRollupKeyed, kept: PodRollupKeyed): boolean {
+  const nextFinal = next.partial !== true;
+  const keptFinal = kept.partial !== true;
+  if (nextFinal !== keptFinal) return nextFinal;
+  if (nextFinal) return false;
+  const nextSeq = Number(next.partialSeq ?? 0);
+  const keptSeq = Number(kept.partialSeq ?? 0);
+  if (nextSeq !== keptSeq) return nextSeq > keptSeq;
+  return String(next.partialAt ?? '') > String(kept.partialAt ?? '');
+}
+
+/** ⭐ METER-POD-ROLLUP-GAP-2 — 같은 Pod 사용량의 재방출(부분 ⊕ 최종 · abort ⊕ resume)을 podRollupKey 로 한 번만 남긴다.
+ *  들어온 순서가 아니라 «더 완전한 행»을 남기고(rollupRowBeats), 키 없는 행은 그대로 다 둔다(순서 보존). */
+export function dedupePodRollupRows<T>(rows: readonly T[], dataOf: (row: T) => PodRollupKeyed = (row) => row as PodRollupKeyed): T[] {
+  const kept: T[] = [];
+  const keptIndexByKey = new Map<string, number>();
+  for (const row of rows) {
+    const d = dataOf(row);
+    if (typeof d.podRollupKey === 'string') {
+      const at = keptIndexByKey.get(d.podRollupKey);
+      if (at !== undefined) {
+        if (rollupRowBeats(d, dataOf(kept[at]!))) kept[at] = row;
+        continue;
+      }
+      keptIndexByKey.set(d.podRollupKey, kept.length);
+    }
+    kept.push(row);
+  }
+  return kept;
+}
 
 export function rollup(lines: readonly string[]): { rows: UsageRow[]; truncated: boolean } {
   const by = new Map<string, UsageRow>();
+  // ⭐ MF-3c0d253e — 같은 Pod 사용량의 재방출(부분 ⊕ 최종 · abort ⊕ resume)은 podRollupKey 로 한 번만 센다(이중계상 방지).
+  //   들어온 순서가 아니라 «더 완전한 행»을 남긴다(최종 > 부분 · seq · at — rollupRowBeats).
+  //   키가 없는 행(기존 경로 전부)은 종전과 동작·바이트 그대로다.
   let truncated = false;
+  const parsed: UsageData[] = [];
   for (const line of lines) {
     if (/limitReached=true|truncated/.test(line) && !line.startsWith('{')) truncated = true;
     if (!line.startsWith('{')) continue;
     let r: { event?: string; data?: Record<string, unknown> };
     try { r = JSON.parse(line); } catch { continue; }
     if (r.event !== 'llm-usage' || !r.data) continue;
-    const d = r.data as { site?: string; provider?: string; billingProvider?: string; model?: string; inputTokens?: number; outputTokens?: number; cacheReadInputTokens?: number; cacheCreationInputTokens?: number; cost?: { kind?: string; usd?: number } };
+    parsed.push(r.data as UsageData);
+  }
+  const entries = dedupePodRollupRows(parsed);
+  for (const d of entries) {
     const provider = d.billingProvider ?? d.provider ?? '?';   // ⭐ 과금 주체 우선(B10)
     const key = `${d.site ?? '?'}|${provider}|${d.model ?? '?'}`;
     const row = by.get(key) ?? { site: d.site ?? '?', provider, model: d.model ?? '?', calls: 0, inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0, cacheCreationInputTokens: 0, cacheCreationUnmeasuredCalls: 0, usdKnown: 0, unknownCostCalls: 0, includedCalls: 0, apiEquivalentUsd: 0 };
@@ -38,14 +84,34 @@ export function rollup(lines: readonly string[]): { rows: UsageRow[]; truncated:
     // ⭐ `actual`(provider 보고 청구액 · C7)은 알려진 비용이다.
     else if ((d.cost?.kind === 'known' || d.cost?.kind === 'actual') && typeof d.cost.usd === 'number') row.usdKnown += d.cost.usd;
     else { row.unknownCostCalls++; if (d.cost?.kind === 'partial' && typeof d.cost.usd === 'number') row.usdKnown += d.cost.usd; }
+    // OR-BYOK-COST — BYOK 비용은 위에서 이미 usdKnown(actual)·unknownCostCalls(partial)로 갈렸다. 여기선 출처만 따로 나른다.
+    const c = d.cost as { byok?: unknown; upstreamUsd?: unknown } | undefined;
+    if (c?.byok === true) {
+      row.byokCalls = (row.byokCalls ?? 0) + 1;
+      if (typeof c.upstreamUsd === 'number' && Number.isFinite(c.upstreamUsd)) row.byokUpstreamUsd = (row.byokUpstreamUsd ?? 0) + c.upstreamUsd;
+      else row.byokUpstreamUnknownCalls = (row.byokUpstreamUnknownCalls ?? 0) + 1;
+    }
     by.set(key, row);
   }
   return { rows: [...by.values()], truncated };
 }
 
+/** METER-POD-ROLLUP-GAP — 인자 해석: `--partial`(⊕ `--seq N`)면 부분 롤업 한 줄로 바꾼다. 전체판(기본)은 불변. */
+export function parseRollupArgs(argv: readonly string[]): { since: string; partial: boolean; seq: number } {
+  const sinceAt = argv.indexOf('--since');
+  const seqAt = argv.indexOf('--seq');
+  const seqRaw = seqAt >= 0 ? Number(argv[seqAt + 1] ?? 1) : 1;
+  return { since: sinceAt >= 0 ? argv[sinceAt + 1] ?? '6h' : '6h', partial: argv.includes('--partial'), seq: Number.isInteger(seqRaw) && seqRaw > 0 ? seqRaw : 1 };
+}
+
+/** 한 줄 표현 — 전체판 줄은 기존 바이트와 동일, 부분판은 partial:true ⊕ seq ⊕ at 만 얹는다. */
+export function renderRollupLine(payload: Record<string, unknown>, opts: { partial: boolean; seq: number }): string {
+  if (opts.partial) return `ELANOUS_USAGE_ROLLUP_PARTIAL ${JSON.stringify({ ...payload, partial: true, seq: opts.seq, at: new Date().toISOString() })}`;
+  return `ELANOUS_USAGE_ROLLUP ${JSON.stringify(payload)}`;
+}
+
 if (import.meta.main) {
-  const i = process.argv.indexOf('--since');
-  const since = i > 0 ? process.argv[i + 1] ?? '6h' : '6h';
+  const { since, partial, seq } = parseRollupArgs(process.argv);
   const r = spawnSync('elanous', ['logs', '--all', '--include-test', '--event', 'llm-usage', '--since', since, '--limit', '50000', '--json', '--json-data'], { encoding: 'utf8', timeout: 120_000, maxBuffer: 256 * 1024 * 1024 });
   const { rows, truncated } = rollup(`${r.stdout ?? ''}\n${r.stderr ?? ''}`.split('\n'));
   const total = rows.reduce((t, x) => ({ calls: t.calls + x.calls, inputTokens: t.inputTokens + x.inputTokens, outputTokens: t.outputTokens + x.outputTokens, usdKnown: t.usdKnown + x.usdKnown, unknownCostCalls: t.unknownCostCalls + x.unknownCostCalls }), { calls: 0, inputTokens: 0, outputTokens: 0, usdKnown: 0, unknownCostCalls: 0 });
@@ -54,5 +120,5 @@ if (import.meta.main) {
   const elanousVersion = v.status === 0 ? (v.stdout ?? '').trim().split('\n').pop() ?? null : null;
   // ⭐ 런 출처 칸(🅣 RFC run-origin 이름 그대로) — 호스트 재방출이 그대로 받는다.
   const origin = { podName: process.env.ELANOUS_POD_NAME ?? null, nodeName: process.env.ELANOUS_NODE_NAME ?? null, hostId: process.env.ELANOUS_HOST_ID ?? null, imageCommit: process.env.ELANOUS_IMAGE_COMMIT ?? null };
-  console.log(`ELANOUS_USAGE_ROLLUP ${JSON.stringify({ substrate: process.env.ELANOUS_SUBSTRATE ?? null, elanousVersion, ...origin, runId: process.env.ELANOUS_RUN_ID ?? null, armId: process.env.ELANOUS_ARM_ID ?? null, measured: r.status === 0, truncated, rows, total })}`);
+  console.log(renderRollupLine({ substrate: process.env.ELANOUS_SUBSTRATE ?? null, elanousVersion, ...origin, runId: process.env.ELANOUS_RUN_ID ?? null, armId: process.env.ELANOUS_ARM_ID ?? null, measured: r.status === 0, truncated, rows, total }, { partial, seq }));
 }

package/scripts/ux-sim.ts

@@ -13,6 +13,9 @@
 //   bun scripts/ux-sim.ts --computer-use normal --from-run <runId> --save-trajectory <name> # 이름으로 저장
 //   bun scripts/ux-sim.ts --computer-use normal --trajectory <name> # 저장한 궤적을 재생
 //   bun scripts/ux-sim.ts --list-trajectories # 저장한 궤적과 출처 목록
+//   bun scripts/ux-sim.ts --fault cred-expiry # 결함 주입: grok 구독 만료 임박 × 갱신 결과 → 디스패처·발사 판정
+//   bun scripts/ux-sim.ts --fault pod-death   # 결함 주입: PARTIAL 줄을 남긴 Pod 가 SIGTERM 으로 지워짐 → 호스트 재방출 판정
+//   bun scripts/ux-sim.ts --fault pool-cap    # 결함 주입: --pod-pool 에 :N 이 빠진 풀 → 승인 판정(limitedBy)
 //
 // ⛔ 이 CLI 는 «실제 위젯 render()» 를 부른다 — 흉내 렌더러가 아니다.
 import { simRenderLogFrame } from '../src/ux-sim/render-frame.js';
@@ -33,7 +36,7 @@ const argv = process.argv.slice(2);
 //  ⛔ 그래서 「알려진 플래그」를 «한 곳»에 두고, 그 밖의 `--` 인자는 거부한다.
 const KNOWN_FLAGS = new Set([
   '--list', '--list-trajectories', '--computer-use', '--trajectory', '--from-run',
-  '--save-trajectory', '--esc', '--queue', '--width', '--height', '--draft',
+  '--save-trajectory', '--esc', '--queue', '--width', '--height', '--draft', '--fault',
 ]);
 {
   const unknown = argv.filter((a) => a.startsWith('--') && !KNOWN_FLAGS.has(a.split('=')[0]));
@@ -46,6 +49,32 @@ const KNOWN_FLAGS = new Set([
 }
 if (argv.includes('--list')) { console.log([...PHASES, 'computer-use: normal | capture-stalls | capture-fails | target-missing'].join('\n')); process.exit(0); }
 
+{
+  // `--fault=<이름>` 꼴도 받는다 — KNOWN_FLAGS 는 등호 꼴을 통과시키므로 여기서 놓치면 조용히 기본 국면으로 빠진다.
+  const eq = argv.find((a) => a.startsWith('--fault='));
+  if (eq) argv.splice(argv.indexOf(eq), 1, '--fault', eq.slice('--fault='.length));
+}
+if (argv.includes('--fault')) {
+  const fault = argv[argv.indexOf('--fault') + 1];
+  if (fault === 'cred-expiry') {
+    const { credExpirySweep, renderCredExpiry } = await import('../src/ux-sim/fault-cred-expiry.js');
+    console.log(renderCredExpiry(credExpirySweep()).join('\n'));
+    process.exit(0);
+  }
+  if (fault === 'pod-death') {
+    const { simPodDeath, renderPodDeath } = await import('../src/ux-sim/fault-pod-death.js');
+    console.log(renderPodDeath(simPodDeath()).join('\n'));
+    process.exit(0);
+  }
+  if (fault === 'pool-cap') {
+    const { poolCapSweep, renderPoolCap } = await import('../src/ux-sim/fault-pool-cap.js');
+    console.log(renderPoolCap(poolCapSweep()).join('\n'));
+    process.exit(0);
+  }
+  console.error(`⛔ 모르는 결함이다: ${fault ?? '(없음)'} — 아는 것: cred-expiry · pod-death · pool-cap`);
+  process.exit(2);
+}
+
 if (argv.includes('--list-trajectories')) {
   const { listSavedBrowserActionTrajectories } = await import('../src/harness/browser-trajectory.js');
   const saved = listSavedBrowserActionTrajectories();

package/skills/youtube-master/scripts/main.ts

@@ -10,7 +10,7 @@ import { fetchSupadataTranscript, judgeTranscriptSufficiency } from '../src/tran
 import { downloadAudio, splitAudio } from '../src/audio.js';
 import { transcribeChunks } from '../src/stt.js';
 import { summarize, parseMetaFromSummary } from '../src/summarize.js';
-import { getSaveDir, saveMarkdown, prepareRunDir, persistArtifacts } from '../src/obsidian.js';
+import { getSaveDir, saveMarkdown, prepareRunDir, persistArtifacts, saveSkipNotice } from '../src/obsidian.js';
 import { classifyDomain, stagingEnabled, stagingSubdir } from '../src/domain-staging.js';
 import { buildStudyNote } from '../src/study-note.js';
 import { decideRoute } from '../src/router.js';
@@ -203,6 +203,7 @@ async function main() {
     });
     console.log(`  저장 완료: ${savedPath}`);
   }
+  const skipNotice = savedPath === null ? saveSkipNotice(route.target, saveDir) : null;
 
   if (flags.print) {
     console.log('\n---BEGIN_YOUTUBE_MASTER_MARKDOWN---\n');
@@ -211,6 +212,8 @@ async function main() {
   }
 
   outputSignals(route);
+
+  if (skipNotice) console.log(skipNotice);
 }
 
 // ── Transcript acquisition (auto-fallback) ──

package/skills/youtube-master/src/obsidian.ts

@@ -21,6 +21,15 @@ export function getStudyNoteSaveDir(): string | null {
   return join(vaultRoot, ...sub.split('/'));
 }
 
+const SAVE_SKIP_NOTICE =
+  '저장 안 됨 · OBSIDIAN_VAULT_ROOT 가 없다 · 고칠 한 줄: export OBSIDIAN_VAULT_ROOT=<vault 경로>';
+
+/** target 이 obsidian 인데 saveDir 이 없으면 세 칸 안내, 아니면 null. */
+export function saveSkipNotice(target: string, saveDir: string | null): string | null {
+  if (target === 'obsidian' && saveDir == null) return SAVE_SKIP_NOTICE;
+  return null;
+}
+
 /* ── Artifact persistence (Cloud STT path) ── */
 
 export async function prepareRunDir(saveDir: string, meta: VideoMeta, videoId: string): Promise<string> {

package/src/agent/run-context.ts

@@ -85,6 +85,14 @@ function childBedrockEnv(provider: string): Record<string, string> {
   return provider === 'bedrock' ? bedrockChildRelayEnv() : {};
 }
 
+/** ZAI-POD-CHILD — glm(Z.ai GLM Coding Plan) 자격은 «env»(`ZAI_API_KEY` · Pod 에선 secretKeyRef)에 산다 — 키 캐시 파일이 없는 Pod 에선
+ *  replace env 라 릴레이가 없으면 자식이 직결을 못 탄다. 카탈로그 envKey(`ZHIPU_API_KEY`)와 다른 이름이라 따로 넘긴다(값은 싣기만 · 어디에도 안 찍는다). */
+function childZaiEnv(provider: string): Record<string, string> {
+  if (provider !== 'glm') return {};
+  const key = process.env.ZAI_API_KEY?.trim();
+  return key ? { ZAI_API_KEY: key } : {};
+}
+
 /** The family classifier is model-id based, so preserve local-provider identity
  * across the replace-env child boundary without changing non-local model IDs. */
 function childRelayModel(provider: string, model: string): string {
@@ -110,6 +118,7 @@ export function childLlmSelectionEnv(selection?: ChildLlmSelection): Record<stri
       ...childProviderKeyEnv(provider),
       ...childLocalEndpointEnv(provider),
       ...childBedrockEnv(provider),
+      ...childZaiEnv(provider),
     };
   }
   // ⛔⭐ 상속 갈래도 local 이면 «주소»를 같이 넘긴다(BACKLOG B12 · 2026-09-25).
@@ -122,5 +131,6 @@ export function childLlmSelectionEnv(selection?: ChildLlmSelection): Record<stri
     ...(inheritedProvider ? childLocalEndpointEnv(inheritedProvider) : {}),
     // 상속 갈래도 bedrock 이면 AWS_* 를 같이 넘긴다(명시 갈래와 같은 규칙 — replace env 라 자동 상속이 없다).
     ...(inheritedProvider ? childBedrockEnv(inheritedProvider) : {}),
+    ...(inheritedProvider ? childZaiEnv(inheritedProvider) : {}),
   };
 }

package/src/agent-mission/driver.ts

@@ -174,6 +174,8 @@ export interface AgentBackend {
   args: string[];
   /** 구독 모드 위해 스크럽할 env 키(API 과금 회피). */
   scrubEnv?: string[];
+  /** 이 실행에만 덧씌울 env(스크럽 뒤 · 바깥 값을 «덮는다»). CODEX-CREDITS-STEP 재시도가 크레딧 계정의 `CODEX_HOME` 을 싣는다. */
+  env?: Readonly<Record<string, string>>;
   /** 초기 신뢰/권한 프롬프트 처리 — 스크린 보고 필요 시 키 입력. 처리했으면 true. */
   handleTrust?(screen: string, write: (s: string) => void): boolean;
 }
@@ -341,6 +343,7 @@ export function resolveBackendSpawn(
       forcedEnv.push(key);
     }
   }
+  for (const [key, value] of Object.entries(backend.env ?? {})) env[key] = value;
   let nestedEnvRemovedCount = 0;
   for (const key of NESTED_AGENT_ENV_BLOCKLIST) {
     if (key in env) {
@@ -464,6 +467,10 @@ export function resolveDefaultBackend(
       debug.log('agent-mission.backend', 'fallback-switch', { from: 'codex', to: decision.backend, reason: 'codex-exhausted' });
       return decision.backend === 'claude' ? claudeBackend : grokBackend;
     }
+    if (decision.action === 'codex-credits') {
+      // CODEX-CREDITS-STEP — 체인 마지막 칸: codex 로 «돌아와» 선불 크레딧으로 계속(판정 쪽이 이미 관측을 남겼다).
+      debug.log('agent-mission.backend', 'fallback-codex-credits', { from: 'codex', to: 'codex', reason: 'chain-last-step' });
+    }
   } catch (err) {
     debug.log('agent-mission.backend', 'fallback-failed', { message: (err as Error)?.message }, { level: 'warn' });
   }
@@ -522,10 +529,17 @@ export function decideRuntimeFallback(
   failure: unknown,
   currentStep: FallbackStep,
   state: RuntimeFallbackState,
-  decide: (input: { currentStep: FallbackStep; currentCredentialRateLimited: true }) => { action: string; backend?: string },
+  decide: (input: { currentStep: FallbackStep; currentCredentialRateLimited: true }) => { action: string; backend?: string; to?: { readonly name: string; readonly home: string } },
 ): AgentBackend | null {
   if (classifyAuthError(failure).errorKind !== 'rate-limited' || state.descents >= state.maxDescents) return null;
   const decision = decide({ currentStep, currentCredentialRateLimited: true });
+  // CODEX-CREDITS-STEP — grok 등이 한도로 죽고 체인의 다음 칸이 `codex-credits` 면 codex 로 돌아온다(크레딧 · 한 번만).
+  if (decision.action === 'codex-credits') {
+    if (state.attemptedSteps.has('codex-credits')) return null;
+    // 판정이 고른 크레딧 계정(잔액 많은 순)의 홈으로 자식 codex 를 띄운다 — 없으면 호스트 CODEX_HOME 그대로.
+    const home = decision.to?.home?.trim();
+    return home ? { ...codexBackend, env: { CODEX_HOME: home } } : codexBackend;
+  }
   if (decision.action !== 'switch-backend') return null;
   const nextStep = decision.backend === 'grok' ? 'grok' : decision.backend === 'claude' ? 'claude-pty' : null;
   if (!nextStep || state.attemptedSteps.has(nextStep)) return null;
@@ -642,7 +656,7 @@ export interface AgentMissionDeps {
   /** Inject controller responses while keeping the production control loop. */
   controlStream?: StreamLLMFn;
   resolvePtyWebAddress?: typeof resolvePtyWebAddress;
-  resolveRunFallback?: (input: { currentStep: FallbackStep; currentCredentialRateLimited: true }) => { action: string; backend?: string };
+  resolveRunFallback?: (input: { currentStep: FallbackStep; currentCredentialRateLimited: true }) => { action: string; backend?: string; to?: { readonly name: string; readonly home: string } };
   /** 재귀 재시도 사이에만 전달되는 런 로컬 폴백 진행 상태. */
   runtimeFallback?: RuntimeFallbackContext;
   reemitPtyUsage?: typeof reemitPtyUsage;
@@ -2310,7 +2324,8 @@ async function runAgentMissionBody(spec: AgentMissionSpec, deps: AgentMissionDep
     });
     if (nextBackend && !deps.isMissionAborted?.()) {
       decisionEvent({ step: 'recover', text: `Switching ${backend.name} to ${nextBackend.name}`, detail: { blocked: control.termination.message, action: `Retry with ${nextBackend.name}` } });
-      const nextStep: FallbackStep = nextBackend.name === 'grok' ? 'grok' : nextBackend.name === 'claude' ? 'claude-pty' : 'codex-rotate';
+      // runtime 이 codex 로 «돌아오는» 길은 `codex-credits` 칸뿐이다(decideRuntimeFallback) — 그 칸을 시도한 것으로 적는다.
+      const nextStep: FallbackStep = nextBackend.name === 'grok' ? 'grok' : nextBackend.name === 'claude' ? 'claude-pty' : 'codex-credits';
       stopLive();
       if (h.pid) await (deps.terminateProcessTree ?? terminateMissionProcessTree)(h.pid);
       try { h.kill(); } catch { /* noop */ }

package/src/agent-mission/resource-ladder.ts

@@ -2,7 +2,8 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { elanousStateRoot } from '../autopilot/state-paths.js';
 import { debug } from '../debug/log.js';
-import { streamLLM } from '../llm.js';
+import * as llm from '../llm.js';
+import { resolveRoleLlm } from '../user-config.js';
 import { emitDecision, type DecisionEvent } from '../live/detail-switch.js';
 import { OFFICIAL_INDEX_KEYS } from '../market/official-keys.js';
 import { verifyIndex, type MarketplaceIndex } from '../market/signed-index.js';
@@ -80,10 +81,14 @@ function parseNeeds(raw: string, vocabulary: readonly string[]): string[] {
 }
 
 async function inferNeeds(mission: string, vocabulary: readonly string[]): Promise<string> {
-  return streamLLM([
+  const resolved = resolveRoleLlm('classify');
+  const provider = llm.PROVIDERS[resolved.provider];
+  if (!provider) throw new Error(`Unknown classify provider: ${resolved.provider}`);
+  debug.log('llm.role-pin', 'resolved', { site: 'resource-ladder', role: 'classify', model: resolved.model, provider: resolved.provider, source: resolved.source });
+  return llm.streamLLM([
     { role: 'system', content: `Identify at most five concrete tool/service/skill capabilities required for this mission. Reply ONLY with JSON {"needs":["capability"]}. No credentials, tokens, URLs, or mission text in the output. If a relevant label appears in this verified official marketplace vocabulary, use that exact label; otherwise use a concrete capability. If uncertain, return an empty list.\nVerified labels: ${JSON.stringify(vocabulary)}` },
     { role: 'user', content: mission },
-  ], () => {}, { maxTokens: 200, temperature: 0 });
+  ], () => {}, { model: resolved.model, provider, usageRole: 'classify', maxTokens: 200, temperature: 0 });
 }
 
 async function readOfficialIndex(): Promise<{ marketplaceBytes: Uint8Array; signatureText: string }> {

package/src/agent-mission/review-loop.ts

@@ -11,6 +11,7 @@ import { runGitCommand } from '../git-fs/runner.js';
 import * as llm from '../llm.js';
 import type { LLMMessage } from '../llm.js';
 import { debug } from '../debug/log.js';
+import { resolveRoleLlm } from '../user-config.js';
 import { releasePathHold, releasePathHoldShouldPost, releasePathHoldComment, releasePathHoldCommentsArgs, releasePrFilePaths, RELEASE_PATH_LABEL } from '../self-dev/release-path-guard.js';
 import { runAgentMission, resolveBackend, type AgentMissionResult, type EvidenceMode } from './driver.js';
 import { judgeWithAcp, prepareJudgeDiff } from './acp-judge.js';
@@ -439,8 +440,13 @@ asks: reinforce 일 때 codex 가 반영할 **구체 지적 목록**(각 한 줄
 JSON 만: {"verdict":"...","asks":["..."],"reason":"..."}`;
   const messages: LLMMessage[] = [{ role: 'system', content: sys }, { role: 'user', content: body.slice(0, 6000) }];
   let raw = '';
-  try { raw = await llm.streamLLM(messages, () => {}, { maxTokens: 700, temperature: 0.1 }); }
-  catch (e) { return { verdict: 'ambiguous', asks: [], reason: `분류 오류: ${describeThrownValue(e)}`, classificationSource: 'llm-call-failure' }; }
+  try {
+    const resolved = resolveRoleLlm('classify');
+    const provider = llm.PROVIDERS[resolved.provider];
+    if (!provider) throw new Error(`Unknown classify provider: ${resolved.provider}`);
+    debug.log('llm.role-pin', 'resolved', { site: 'classify-review', role: 'classify', model: resolved.model, provider: resolved.provider, source: resolved.source });
+    raw = await llm.streamLLM(messages, () => {}, { model: resolved.model, provider, usageRole: 'classify', maxTokens: 700, temperature: 0.1 });
+  } catch (e) { return { verdict: 'ambiguous', asks: [], reason: `분류 오류: ${describeThrownValue(e)}`, classificationSource: 'llm-call-failure' }; }
   const jm = raw.match(/\{[\s\S]*\}/);
   if (!jm) return { verdict: 'ambiguous', asks: [], reason: 'JSON 파싱 실패', classificationSource: 'llm' };
   try {