elanous 0.2.23 → 0.2.24

package/scripts/release-loop/unattended-release.ts

@@ -12,6 +12,7 @@ import { runGraph, type GraphRunState } from '../../src/graph-runner/runner.js';
 import { releaseRunUniverse } from './release-universe.js';
 import { baseVersion, isStableVersion, nextPrereleaseVersion, type PrereleaseKind } from './release-version.js';
 import { publishAtError } from './publish-at.js';
+import { checkGateExecutorChoice, type GateExecutor } from './gate-executor.js';
 
 const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
 const GRAPH = join(import.meta.dir, '../../graphs/release/release-loop.yaml');
@@ -39,7 +40,10 @@ export interface ReleaseRunInput extends ReleaseLoopConfig {
   version: string;
   previousVersion: string;
   cutCommit?: string;
-  gatePodPool: string;
+  /** Required for the pod executor (the default); a host-executor run may have none. */
+  gatePodPool?: string;
+  /** GATE-HOST-EXECUTOR — absent = pod (today's input, byte-identical); `host` sweeps on `gateRemote`. */
+  gateExecutor?: GateExecutor;
   forceFreeze?: boolean;
   publishAt?: string;
   /** RELEASE-BRANCH: version-release cuts release/<v> from main HEAD and bumps only the branch. */
@@ -104,22 +108,32 @@ export function releaseLoopConfig(configPath = getElanousConfigDirOverride() ? j
   return raw.release?.loop ?? {};
 }
 
-export function buildReleaseRunInput(version: string, deps: UnattendedReleaseDeps = {}, cutCommit?: string): ReleaseRunInput {
+/** GATE-HOST-EXECUTOR — the operator's explicit executor choice (`--gate-executor` / `--gate-host`); absent = pod. */
+export interface GateExecutorRequest { executor?: string; host?: string }
+
+export function buildReleaseRunInput(version: string, deps: UnattendedReleaseDeps = {}, cutCommit?: string, gate: GateExecutorRequest = {}): ReleaseRunInput {
   const config = deps.config ?? releaseLoopConfig(deps.configPath);
+  if (gate.executor === undefined && gate.host !== undefined) throw new Error('--gate-host requires --gate-executor host');
+  const choice = gate.executor === undefined ? undefined
+    : checkGateExecutorChoice(gate.executor, gate.executor === 'host' ? gate.host ?? config.gateRemote : gate.host);
   const pool = config.gatePodPool;
-  if (typeof pool !== 'string' || !pool.trim()) throw new Error('release.loop.gatePodPool is required before graph execution');
+  const hasPool = typeof pool === 'string' && !!pool.trim();
+  // The pod executor (the default) stays fail-closed on a missing pool; an explicit host executor does not need one.
+  if (choice?.executor !== 'host' && !hasPool) throw new Error('release.loop.gatePodPool is required before graph execution');
   const previousVersion = latestPublishedPreviousVersion(baseVersion(version), deps.ledgerRoot);
   return {
     ...config,
     version, previousVersion,
     ...(cutCommit !== undefined ? { cutCommit } : {}),
-    gatePodPool: pool.trim(),
+    ...(hasPool ? { gatePodPool: pool.trim() } : {}),
+    ...(choice ? { gateExecutor: choice.executor } : {}),
+    ...(choice?.host ? { gateRemote: choice.host } : {}),
   };
 }
 
 /** Fail closed at the entry boundary, before any graph node can change a release. */
 export async function runUnattendedRelease(
-  opts: { version: string; dryRun?: boolean; cutCommit?: string; forceFreeze?: boolean; mainCut?: boolean; prerelease?: PrereleaseKind; publishAt?: string },
+  opts: { version: string; dryRun?: boolean; cutCommit?: string; forceFreeze?: boolean; mainCut?: boolean; prerelease?: PrereleaseKind; publishAt?: string; gateExecutor?: string; gateHost?: string },
   deps: UnattendedReleaseDeps = {},
 ): Promise<{ input: ReleaseRunInput; dryRun: boolean; state?: GraphRunState }> {
   // RELEASE-BRANCH (10-06): the default cut is a release branch, so main keeps landing and the run no longer needs a
@@ -135,7 +149,7 @@ export async function runUnattendedRelease(
     }
   }
   const version = resolveRunVersion(opts.version, opts.prerelease, deps);
-  const input = buildReleaseRunInput(version, deps, opts.cutCommit);
+  const input = buildReleaseRunInput(version, deps, opts.cutCommit, { executor: opts.gateExecutor, host: opts.gateHost });
   if (opts.publishAt !== undefined) {
     const invalid = publishAtError(opts.publishAt);
     if (invalid) throw new Error(invalid);
@@ -143,7 +157,8 @@ export async function runUnattendedRelease(
   }
   if (opts.forceFreeze) input.forceFreeze = true;
   if (branchCut) input.branchCut = true;
-  debug.log('release.run', 'input', { version, requested: opts.version, branchCut, prerelease: opts.prerelease ?? null, dryRun: opts.dryRun === true });
+  debug.log('release.run', 'input', { version, requested: opts.version, branchCut, prerelease: opts.prerelease ?? null, dryRun: opts.dryRun === true,
+    ...(input.gateExecutor ? { gateExecutor: input.gateExecutor, gateHost: input.gateExecutor === 'host' ? input.gateRemote ?? null : null } : {}) });
   if (opts.dryRun) return { input, dryRun: true };
   if (opts.prerelease) {
     // A rehearsal neither judges nor carries the stable version's checklist cells.

package/scripts/tsc-baseline-cache.ts

@@ -0,0 +1,147 @@
+/**
+ * 승격 착지의 base 쪽 tsc 진단을 «main 커밋별로 한 번만» 재고 재사용하는 캐시.
+ * 키 = base sha ⊕ tsc 명령 ⊕ 설정 파일(base 커밋에서 git show 로 읽은 내용) 해시 ⊕ 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 = 1;
+
+/** 키에 들어가는 «기준 커밋의 설정 파일» — 이 중 하나라도 달라지면 같은 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;
+  /** 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 를 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 tsc = (options.tscVersion ?? defaultTscVersion)(cwd);
+    return createHash('sha256').update(JSON.stringify({ format: CACHE_FORMAT, sha, command, files, 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,50 @@
 //    호스트(맥)에서 돌리면 테스트 우주·워크트리·다른 트랙의 런까지 섞인다(📏 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 };
+
+/** 같은 podRollupKey 두 행 중 어느 쪽이 더 완전한가 — 최종 > 부분 · 부분끼리는 seq 큰 쪽 · 같으면 at 늦은 쪽. 완전히 같으면 앞 행을 둔다. */
+function rollupRowBeats(next: UsageData, kept: UsageData): 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 ?? '');
+}
 
 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 entries: UsageData[] = [];
+  const keptIndexByPodRollupKey = new Map<string, number>();
   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 } };
+    const d = r.data as UsageData;
+    if (typeof d.podRollupKey === 'string') {
+      const keptIndex = keptIndexByPodRollupKey.get(d.podRollupKey);
+      if (keptIndex !== undefined) {
+        if (rollupRowBeats(d, entries[keptIndex]!)) entries[keptIndex] = d;
+        continue;
+      }
+      keptIndexByPodRollupKey.set(d.podRollupKey, entries.length);
+    }
+    entries.push(d);
+  }
+  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 +70,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 +106,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/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 {

package/src/agent-substrate/acp-implementer.ts

@@ -0,0 +1,139 @@
+// ── ACP Claude Code 를 «구현» 실행기로 (CLAUDE-IMPL-LANE · `--child-llm-provider claude-acp`) ──
+//
+// acp-reviewer.ts 의 짝이다. 리뷰어는 read-only 라 읽기 툴만 허가하지만, 구현 실행기는 런 워크트리 안에서
+// 쓰기·실행을 허가해야 한다. 그래서 approver 가 «워크트리 밖 경로 쓰기»를 구조적으로 거부한다.
+// 자식은 claude 구독 ACP 어댑터(`claude-agent-acp`)이며 env 는 subscriptionReviewerSpawn 의 과금 스크럽
+// (ANTHROPIC_API_KEY 등 제거)을 그대로 쓴다 — 지우지 않으면 구독이 아니라 API 로 과금된다.
+import { isAbsolute, relative, resolve } from 'node:path';
+import { AcpAgent, type AcpAgentOpts } from '../acp/client.js';
+import { debug } from '../debug/log.js';
+import { subscriptionReviewerSpawn } from '../self-dev/review-provider-fallback.js';
+import type { SubscriptionReviewerSpec } from '../user-config.js';
+import { isReadOnlyReviewTool } from './acp-reviewer.js';
+
+const WRITE_TOOL_KINDS = new Set(['edit', 'delete', 'move']);
+const PATH_INPUT_KEYS = ['file_path', 'filePath', 'path', 'notebook_path', 'destination', 'source'] as const;
+
+export interface ImplementerPermissionRequest {
+  title: string;
+  kind?: string;
+  rawInput?: unknown;
+}
+
+export interface ImplementerPermissionDecision {
+  tool: string;
+  path: string | null;
+  decision: 'allow' | 'deny';
+}
+
+function requestedPaths(rawInput: unknown): string[] {
+  if (!rawInput || typeof rawInput !== 'object') return [];
+  const input = rawInput as Record<string, unknown>;
+  return PATH_INPUT_KEYS.flatMap((key) => (typeof input[key] === 'string' && input[key] ? [input[key] as string] : []));
+}
+
+function insideWorktree(worktree: string, target: string): boolean {
+  const rel = relative(resolve(worktree), resolve(worktree, target));
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+/** 허가 판정(순수 함수). 쓰기 계열(edit·delete·move)은 모든 경로가 워크트리 안일 때만 허가하고,
+ *  실행(execute)은 cwd 가 워크트리라 허가한다. 읽기 계열은 허가, 그 외는 경로가 있고 전부 안쪽일 때만 허가(보수적). */
+export function decideImplementerPermission(req: ImplementerPermissionRequest, worktree: string): ImplementerPermissionDecision {
+  const paths = requestedPaths(req.rawInput);
+  const outside = paths.find((p) => !insideWorktree(worktree, p));
+  const tool = req.title.slice(0, 80);
+  const shown = outside ?? paths[0] ?? null;
+  const verdict = (allow: boolean): ImplementerPermissionDecision => ({ tool, path: shown, decision: allow ? 'allow' : 'deny' });
+  if (req.kind && WRITE_TOOL_KINDS.has(req.kind)) return verdict(paths.length > 0 && outside === undefined);
+  if (req.kind === 'execute') return verdict(true);
+  if (isReadOnlyReviewTool(req.kind, req.title)) return verdict(true);
+  return verdict(paths.length > 0 && outside === undefined);
+}
+
+export interface AcpImplementerOpts {
+  /** 런 워크트리 — ACP 자식의 cwd 이자 쓰기 허용 경계. */
+  worktree: string;
+  /** 자식 env 의 원천(기본 process.env). 과금 키는 subscriptionReviewerSpawn 이 제거한다. */
+  env?: NodeJS.ProcessEnv;
+  /** cct 실행기가 `teamclaude env --no-mitm` 에서 읽은 프록시 주소. */
+  proxyBaseUrl?: string;
+  spec?: SubscriptionReviewerSpec;
+  /** 모델 별칭 — 지정 시 session/set_model 로 고정. */
+  model?: string;
+  /** 이어갈 ACP 세션 id — 주면 newSession 대신 loadSession 으로 이어간다. */
+  resumeSessionId?: string;
+  /** 구현 1턴 최대 대기(ms). 초과 시 cancel → throw. 기본 1_800_000. */
+  timeoutMs?: number;
+  /** spawn → initialize → session 준비까지의 단일 기한(ms). 기본 60_000. */
+  handshakeTimeoutMs?: number;
+  /** 테스트용 ACP 에이전트 생성기. */
+  createAgent?: (opts: AcpAgentOpts) => AcpAgent;
+}
+
+export interface AcpImplementerResult {
+  text: string;
+  sessionId: string;
+  allowed: number;
+  denied: number;
+}
+
+const OBS = 'agent-substrate.acp-implementer';
+
+export function makeAcpImplementer(opts: AcpImplementerOpts): (prompt: string) => Promise<AcpImplementerResult> {
+  return async (prompt) => {
+    const spawn = subscriptionReviewerSpawn(opts.spec ?? { provider: 'claude-acp' }, opts.env ?? process.env, opts.proxyBaseUrl);
+    const timeoutMs = opts.timeoutMs ?? 1_800_000;
+    const handshakeTimeoutMs = opts.handshakeTimeoutMs ?? 60_000;
+    let allowed = 0;
+    let denied = 0;
+    const agentOpts: AcpAgentOpts = {
+      backendId: 'claude',
+      backendSpec: spawn.backendSpec,
+      env: spawn.env,
+      cwd: opts.worktree,
+      log: (message) => debug.log(OBS, 'agent-log', { message }),
+      permissionApprover: async (req) => {
+        const verdict = decideImplementerPermission(req, opts.worktree);
+        if (verdict.decision === 'allow') allowed++; else denied++;
+        debug.log(OBS, 'permission', { ...verdict });
+        return verdict.decision === 'allow';
+      },
+    };
+    const agent = opts.createAgent ? opts.createAgent(agentOpts) : new AcpAgent(agentOpts);
+    let handshakeTimer: ReturnType<typeof setTimeout> | undefined;
+    const withinHandshake = <T>(step: Promise<T>): Promise<T> => Promise.race([step, new Promise<never>((_, reject) => {
+      handshakeTimer = setTimeout(() => reject(new Error(`ACP handshake timeout (${handshakeTimeoutMs}ms)`)), handshakeTimeoutMs);
+    })]).finally(() => { if (handshakeTimer) clearTimeout(handshakeTimer); });
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let timedOut = false;
+    let text = '';
+    try {
+      await withinHandshake(agent.start());
+      let sid: string;
+      if (opts.resumeSessionId) {
+        await withinHandshake(agent.loadSession({ sessionId: opts.resumeSessionId, cwd: opts.worktree }));
+        sid = opts.resumeSessionId;
+      } else {
+        sid = await withinHandshake(agent.newSession());
+      }
+      if (opts.model) await withinHandshake(agent.selectSessionModel(sid, opts.model));
+      debug.log(OBS, 'start', { cwd: opts.worktree, model: opts.model ?? '(default)', resumed: Boolean(opts.resumeSessionId) });
+      timer = setTimeout(() => { timedOut = true; agent.cancel(sid).catch(() => { /* noop */ }); }, timeoutMs);
+      await agent.prompt(sid, [{ type: 'text', text: prompt }], (u) => {
+        if (u.sessionUpdate === 'agent_message_chunk' && u.content.type === 'text' && u.content.text) text += u.content.text;
+      });
+      if (timedOut) throw new Error(`ACP 구현 타임아웃(${timeoutMs}ms)`);
+      debug.log(OBS, 'done', { chars: text.length, allowed, denied });
+      return { text, sessionId: sid, allowed, denied };
+    } catch (e) {
+      debug.log(OBS, 'error', { message: (e as Error).message, allowed, denied }, { level: 'error' });
+      throw e;
+    } finally {
+      if (timer) clearTimeout(timer);
+      try { await agent.stop(); } catch (e) {
+        debug.log(OBS, 'stop-fail', { message: (e as Error).message }, { level: 'error' });
+      }
+    }
+  };
+}