elanous 0.2.22 → 0.2.24

package/src/task-orchestrator/surfaces/pod-pool.ts

@@ -23,7 +23,7 @@ import { debug } from '../../debug/log.js';
 import { PodLeaseAdmission, type PodLeasePredecessor, type PodLeaseRelease } from '../../pod-lease/admission.js';
 import { predecessorState, type PredecessorState } from '../../pod-lease/dependency-state.js';
 import { HostPoolLease, hostLeaseBaseDir, leaseHasPendingPod } from '../../pod-lease/host-lease.js';
-import { acquireLockSync } from '../../storage/file-lock.js';
+import { acquireLockAsync, acquireLockSync } from '../../storage/file-lock.js';
 import { harnessCpuSlotsBesideGate, measurePoolLease, recommendConcurrency, type PodLeaseMember, type PoolDnsProbe, type PoolLeaseRecommendation } from './pod-lease.js';
 
 export interface PodPoolMember {
@@ -31,6 +31,11 @@ export interface PodPoolMember {
   /** 원격 클러스터가 도는 기계(ssh 호스트). 없으면 이 기계의 docker 에 있다. */
   readonly sshHost?: string;
   readonly capacity: number;
+  /**
+   * POD-POOL-UNCAPPED-SPEC — 스펙에 `:N` 이 없어서 `capacity` 가 운영자 숫자가 아니라 `POD_POOL_DEFAULT_CAPACITY` 다.
+   * 발사 허가는 이 표시로 «풀 기본 상한이 막았다»(`limitedBy=pool-cap`)를 일반 `capacity` 와 갈라 말한다.
+   */
+  readonly capacityDefaulted?: boolean;
   /** k3d 클러스터 이름(이미지 반입용). 기본: 컨텍스트가 `k3d-<이름>` 이면 그 이름, 원격이면 `elanous-pool`. */
   readonly k3dCluster: string;
   /** 노드 로컬 레지스트리의 이미지(커밋 태그) — 있으면 Pod 가 이것을 pull 한다(델타 · 대표 2026-09-26). 없으면 반입된 로컬 이미지. */
@@ -99,6 +104,12 @@ export function registryImageRef(member: PodPoolMember, commit: string | null, r
   } catch { return null; }
 }
 
+/** IMAGE-ONE-SOURCE: 이 멤버의 노드에 레지스트리 컨테이너가 있나(syncPoolImages 의 판정과 같은 명령). 로컬 멤버는 false. */
+export function memberHasRegistry(member: PodPoolMember, run: RemoteRun = defaultRemoteRun): boolean {
+  if (!member.sshHost) return false;
+  return run(member.sshHost, `docker inspect ${memberRegistry(member).split(':')[0]} >/dev/null 2>&1`).status === 0;
+}
+
 /** 노드 이미지의 스킬 해시 라벨(`elanous.pod-skills`). */
 export function remoteImageSkillsDigest(member: PodPoolMember, image: string, run: RemoteRun = defaultRemoteRun): string | null {
   if (!member.sshHost) return null;
@@ -109,18 +120,23 @@ export function remoteImageSkillsDigest(member: PodPoolMember, image: string, ru
 
 const MEMBER = /^([A-Za-z0-9][A-Za-z0-9._-]*)(?:@([A-Za-z0-9][A-Za-z0-9._-]*))?(?::(\d+))?(?:#(k3d-[A-Za-z0-9][A-Za-z0-9._-]*):([1-9]\d{0,4}))?$/u;
 
+/** 상한 없는 풀 스펙(`:N` 없음)의 노드 상한 — 파일 머리 주석의 «기본 2» 정본(POD-POOL-UNCAPPED-SPEC). */
+export const POD_POOL_DEFAULT_CAPACITY = 2;
+
 export function parsePodPool(spec: string): PodPoolMember[] {
   const members = spec.split(',').map((s) => s.trim()).filter(Boolean).map((part) => {
     const m = MEMBER.exec(part);
     if (!m) throw new Error(`--pod-pool: 못 읽는 노드 「${part}」 — 형식 컨텍스트[@ssh호스트][:상한][#k3d-레지스트리:포트]`);
-    const capacity = m[3] === undefined ? 2 : Number(m[3]);
+    // `:N` 이 없으면 «상한 없음»이 아니라 기본 상한 2 다 — 그 사실(`capacityDefaulted`)을 멤버에 남긴다.
+    const capacityDefaulted = m[3] === undefined;
+    const capacity = capacityDefaulted ? POD_POOL_DEFAULT_CAPACITY : Number(m[3]);
     // POOL-LITE (10-07): `:0` means «this member is off» — a `node-c:0` entry once threw here and broke every launch.
     //   It is dropped below (never chosen); only a pool with no live member left is an error.
     if (!Number.isInteger(capacity) || capacity < 0) throw new Error(`--pod-pool: 상한은 1 이상 — 「${part}」`);
     if (m[5] && Number(m[5]) > 65535) throw new Error(`--pod-pool: 레지스트리 포트는 65535 이하 — 「${part}」`);
     const context = m[1]!;
     const k3dCluster = context.startsWith('k3d-') ? context.slice(4) : 'elanous-pool';
-    return { context, capacity, k3dCluster, ...(m[2] ? { sshHost: m[2] } : {}), ...(m[4] ? { registry: `${m[4]}:${m[5]}` } : {}) };
+    return { context, capacity, ...(capacityDefaulted ? { capacityDefaulted: true } : {}), k3dCluster, ...(m[2] ? { sshHost: m[2] } : {}), ...(m[4] ? { registry: `${m[4]}:${m[5]}` } : {}) };
   });
   if (members.length === 0) throw new Error('--pod-pool: 노드가 없다');
   if (new Set(members.map((m) => m.context)).size !== members.length) throw new Error('--pod-pool: 컨텍스트가 겹친다');
@@ -276,7 +292,14 @@ export class PodPoolScheduler {
       const decision = measured.recommended === null ? measured : { ...measured, recommended: Math.max(0, measured.recommended - others + (transferIsOther ? 1 : 0)) };
       // An unknown reading cannot erase permits already granted: on recovery,
       // the first healthy recommendation must still account for their slots.
-      if (decision.recommended === null) return decision;
+      // GATE-ADMIT-UNMEASURED(10-09 대표 «판 발행 문제없게»): 측정이 «?»(예: 부하 노드의 DNS 탐침)여도 게이트 조각은 하나씩 들어간다 —
+      //   게이트가 측정 복구를 기다리며 조각마다 승인 시간 초과를 물지 않게. 실제로 자리가 없으면 스케줄러가 Pending 으로 둔다(잃는 것 없음).
+      if (decision.recommended === null) {
+        if (!gate) return decision;
+        const active = this.gateAdmission.snapshot().active;
+        debug.log('pod.pool', 'gate-admit-unmeasured', { active, reason: decision.reason ?? null });
+        return { ...decision, recommended: active + 1 };
+      }
       // A new launch consumes a measured additional slot. Compare consecutive
       // measurements so repeated stale readings cannot grant that slot again.
       this.budget = Math.max(0, this.budget + decision.recommended - (this.initialized ? this.lastFree : 0));
@@ -324,7 +347,7 @@ export class PodPoolScheduler {
         const pendingJobs = this.lastRaw?.pendingJobs ?? [];
         const lease = transferred ?? (free !== null && free > 0 ? this.hostLease.tryReserve((others) =>
           others - this.hostLease.live().filter((r) => leaseHasPendingPod(r, pendingJobs) &&
-            (r.pid !== process.pid || r.startedAt !== this.hostLease.selfStart())).length < free) : null);
+            (r.pid !== process.pid || r.startedAt !== this.hostLease.selfStart())).length < free) : (gate && free === null ? this.hostLease.tryReserve(() => true) : null));
         if (lease) {
           let hostReleased = false;
           const releaseHost = () => { if (!hostReleased) { hostReleased = true; lease(); } };
@@ -629,7 +652,11 @@ export function syncPoolImage(member: PodPoolMember, image: string, localCommit:
     // The import phase gets its own stale window (the lock file's age restarts here).
     try { const now = new Date(); utimesSync(lockPath, now, now); } catch { /* lock gone · finish anyway */ }
     const imp = remote(host, `k3d image import ${image} -c ${member.k3dCluster}`);
-    if (imp.status !== 0) return { ok: false, action: 'failed', detail: `k3d import rc=${imp.status}: ${imp.stderr.slice(-300)}` };
+    // As in build.sh, only tools-node cleanup errors may follow a nonzero import rc.
+    // Ignore informational lines, but reject any other failure line (including WARN and untagged output).
+    const failures = imp.stderr.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !/^(?:INFO|DEBU|DEBUG|TRAC|TRACE)(?:\[|\s|:|$)/.test(line));
+    const cleanup = /^(?:(?:ERROR|ERRO|FATAL|FATA|WARNING|WARN|INFO)(?:\[[^\]]*\])?:?\s*)?(?:failed to import images: )?failed to delete tools node '[^']*': (?:Error response from daemon: )?(?:No such container: [A-Za-z0-9_.-]+|removal of container [A-Za-z0-9_.-]+ is already in progress)$/i;
+    if (imp.status !== 0 && (failures.length === 0 || !failures.every((line) => cleanup.test(line)))) return { ok: false, action: 'failed', detail: `k3d import rc=${imp.status}: ${imp.stderr.slice(-300)}` };
     const after = remoteImageCommit(member, image, remote);
     return after && (!localCommit || after === localCommit)
       ? { ok: true, action: 'shipped', detail: `${labelNow?.slice(0, 12) ?? '없음'} → ${after.slice(0, 12)}` }
@@ -719,11 +746,13 @@ function defaultRemoteBuild(script: string, image: string): RemoteBuild {
  *           📏 커밋이 바뀐 뒤 두 노드를 올리는 데 벽시계 55초(종전: 다시 굽기 1분 40초 ⊕ 4GB 차례 전송 5분 48초).
  *   실패하면 = 종전의 통째 전송(syncPoolImage)으로 떨어진다.
  */
-export async function syncPoolImages(members: readonly PodPoolMember[], image: string, localCommit: string | null, deps: { run?: RemoteRun; remoteBuild?: RemoteBuild; buildScript?: string | null; ship?: typeof syncPoolImage; localSkillsDigest?: string | null; waitIntervalMs?: number; waitMaxMs?: number; now?: () => number; sleep?: (ms: number) => Promise<void>; inspect?: LocalImageInspect; transfer?: ImageShip; pack?: PoolPack | null } = {}): Promise<Map<string, PoolImageSync>> {
+export async function syncPoolImages(members: readonly PodPoolMember[], image: string, localCommit: string | null, deps: { run?: RemoteRun; remoteBuild?: RemoteBuild; buildScript?: string | null; ship?: typeof syncPoolImage; localSkillsDigest?: string | null; waitIntervalMs?: number; waitMaxMs?: number; now?: () => number; sleep?: (ms: number) => Promise<void>; inspect?: LocalImageInspect; transfer?: ImageShip; pack?: PoolPack | null; lock?: ImageShipLockOptions } = {}): Promise<Map<string, PoolImageSync>> {
   const run = deps.run ?? defaultRemoteRun;
   const script = deps.buildScript === undefined ? podImageBuildScript() : deps.buildScript;
   const remoteBuild = deps.remoteBuild ?? (script ? defaultRemoteBuild(script, image) : null);
-  const ship = deps.ship ?? ((m: PodPoolMember, img: string, commit: string | null, remote: RemoteRun) => syncPoolImage(m, img, commit, { run: remote, inspect: deps.inspect, transfer: deps.transfer }));
+  // The registry-less build fallback below calls this ship path, including its remote import result check.
+  const ship = deps.ship ?? ((m: PodPoolMember, img: string, commit: string | null, remote: RemoteRun) =>
+    syncPoolImage(m, img, commit, { run: remote, inspect: deps.inspect, transfer: deps.transfer }));
   const results = new Map<string, PoolImageSync>();
   // pack 한 번 ⊕ 나눠 쓰기 — 원격 멤버가 둘 이상일 때만(하나뿐이면 종전대로 build.sh 가 스스로 pack 한다).
   //   주입된 remoteBuild(시험)에는 진짜 pack 을 붙이지 않는다 — pack 도 주입해야 쓴다.
@@ -734,22 +763,61 @@ export async function syncPoolImages(members: readonly PodPoolMember[], image: s
     const t0 = Date.now();
     if (!m.sshHost) { results.set(m.context, { ok: true, action: 'local', detail: 'this machine', ms: 0 }); return; }
     const before = remoteImageCommit(m, image, run);
-    // ⭐ «같은 판» = 커밋 ⊕ 스킬 해시 ⊕ (레지스트리 노드면) 레지스트리에 그 커밋 태그가 있다 — 스킬만 바뀌어도 다시 굽는다(대표 2026-09-26 «스킬 셋트 싱크»).
     const skillsNow = deps.localSkillsDigest;
-    const skillsSame = skillsNow == null || remoteImageSkillsDigest(m, image, run) === skillsNow;
     const refBefore = registryImageRef(m, localCommit, run, image);
     const hasRegistry = run(m.sshHost, `docker inspect ${memberRegistry(m).split(':')[0]} >/dev/null 2>&1`).status === 0;
-    if (localCommit && before === localCommit && skillsSame && (!hasRegistry || refBefore)) {
-      results.set(m.context, { ok: true, action: 'fresh', detail: before.slice(0, 12), ms: Date.now() - t0, ...(refBefore ? { imageRef: refBefore } : {}) });
+    const registrySkillsSame = (ref: string) => skillsNow == null || remoteImageSkillsDigest(m, `localhost:${memberRegistry(m).split(':')[1]}/${ref.slice(ref.indexOf('/') + 1)}`, run) === skillsNow;
+    const skillsSame = hasRegistry && refBefore ? registrySkillsSame(refBefore) : skillsNow == null || remoteImageSkillsDigest(m, image, run) === skillsNow;
+    if (hasRegistry && refBefore && skillsSame) {
+      debug.log('pod.pool', 'image-fresh-registry-tag', { context: m.context, host: m.sshHost, commit: localCommit, localLabel: before, imageRef: refBefore, waitedMs: 0 });
+      results.set(m.context, { ok: true, action: 'fresh', detail: localCommit!.slice(0, 12), ms: Date.now() - t0, imageRef: refBefore });
+      return;
+    }
+    if (!hasRegistry && localCommit && before === localCommit && skillsSame) {
+      results.set(m.context, { ok: true, action: 'fresh', detail: before.slice(0, 12), ms: Date.now() - t0 });
       return;
     }
     if (remoteBuild) {
-      // 같은 판이 아닌 멤버가 처음 여기 닿을 때 pack 한다(전부 fresh 면 pack 도 없다).
-      const shared = sharePack ? await (packed ??= sharePack()) : null;
-      if (shared && !shared.ok) debug.log('self-implement.pod', 'pool-image-pack-failed', { context: m.context, detail: shared.detail });
-      const b = shared && !shared.ok
-        ? { ok: false, detail: shared.detail }
-        : await remoteBuild(m.sshHost, m.k3dCluster, m.registry, shared?.tgz);
+      // Build and publish under a separate per-host lock: a failed build can then enter ship's synchronous lock.
+      const lockOpts = deps.lock ?? {};
+      const lockDir = lockOpts.dir ?? join(hostLeaseBaseDir(), 'image-ship');
+      const lockPath = `${imageShipLockPath(m.sshHost, lockDir)}.build`;
+      const retryMs = lockOpts.retryMs ?? 2_000;
+      const staleMs = lockOpts.staleMs ?? IMAGE_SHIP_TIMEOUT_MS + REMOTE_RUN_TIMEOUT_MS + 120_000;
+      const lockStarted = Date.now();
+      let b: { ok: boolean; detail: string };
+      try {
+        mkdirSync(lockDir, { recursive: true });
+        // Probe atomically rather than testing path existence: another process can acquire between that test and us.
+        let lock;
+        let waited = false;
+        try { lock = await acquireLockAsync(lockPath, { staleMs, retryBusyMs: 1, maxTries: 1 }); }
+        catch (error) {
+          if (!(error instanceof Error) || !error.message.startsWith('acquireLockAsync: timed out')) throw error;
+          waited = true;
+          debug.log('pod.pool', 'image-build-lock-wait', { context: m.context, host: m.sshHost, commit: localCommit, localLabel: before, imageRef: refBefore, waitedMs: Date.now() - lockStarted });
+          lock = await acquireLockAsync(lockPath, { staleMs, retryBusyMs: retryMs, maxTries: lockOpts.maxTries ?? Math.ceil(staleMs / retryMs) + 10 });
+        }
+        try {
+          if (waited && hasRegistry) {
+            const refNow = registryImageRef(m, localCommit, run, image);
+            if (refNow && registrySkillsSame(refNow)) {
+              debug.log('pod.pool', 'image-build-skipped-after-wait', { context: m.context, host: m.sshHost, commit: localCommit, localLabel: before, imageRef: refNow, waitedMs: Date.now() - lockStarted });
+              results.set(m.context, { ok: true, action: 'fresh', imageRef: refNow, detail: `${localCommit?.slice(0, 12)} (built by another process while waiting)`, ms: Date.now() - t0 });
+              return;
+            }
+          }
+          // 같은 판이 아닌 멤버가 처음 여기 닿을 때 pack 한다(전부 fresh 면 pack 도 없다).
+          const shared = sharePack ? await (packed ??= sharePack()) : null;
+          if (shared && !shared.ok) debug.log('self-implement.pod', 'pool-image-pack-failed', { context: m.context, detail: shared.detail });
+          b = shared && !shared.ok
+            ? { ok: false, detail: shared.detail }
+            : lock.stillHeld() ? await remoteBuild(m.sshHost, m.k3dCluster, m.registry, shared?.tgz) : { ok: false, detail: 'image build lock lost' };
+          if (!lock.stillHeld()) b = { ok: false, detail: 'image build lock lost' };
+        } finally { lock.release(); }
+      } catch (error) {
+        b = { ok: false, detail: `image build lock: ${error instanceof Error ? error.message : String(error)}` };
+      }
       const after = remoteImageCommit(m, image, run);
       const refAfter = registryImageRef(m, localCommit ?? after, run, image);
       // ⭐ 레지스트리 노드면 «이 판 커밋 태그가 레지스트리에 있나»로 판정한다 — Pod 는 그 커밋 태그를 pull 한다.

package/src/task-orchestrator/surfaces/pod-zai-child.ts

@@ -0,0 +1,101 @@
+/**
+ * ZAI-POD-CHILD (0.2.24 · MK) — glm 자식 Pod 를 Z.ai GLM Coding Plan(정액 구독 · #26048 `src/llm/zai-coding-plan.ts`)으로 돌린다.
+ *
+ * ⭐ 본보기 = BEDROCK-PROVIDER ②(`pod-bedrock-child.ts`) — 같은 길을 «재발명 없이» 간다:
+ *   · 자격은 클러스터에 미리 둔 «이름 있는 Secret»(`elanous-zai-coding-plan` · 키 `ZAI_API_KEY`)에서 `secretKeyRef` 로만 싣는다.
+ *     호스트는 그 Secret 의 «키 이름»만 읽는다(값은 kubectl 밖으로 안 나온다). 만들기 = `scripts/fleet/zai-pod-secret.ts`(승인 뒤).
+ *   · 이그레스는 이 라벨을 단 Pod 에만 연다(`docker/h1/policy-zai.yaml`).
+ *   · Secret 이 없거나 키가 없으면 «발사 전에» 거부한다(apply 0 · fail-closed).
+ *
+ * ⭐ 동시 상한 — `llm.zaiCodingPlan.maxConcurrent`(기본 3) 를 «동시에 도는 ZAI Pod 수» 로 읽는다.
+ *   근거 = `내부 문서 `devpack__usage-policy``: 동시 한도는 «숫자가 공개돼 있지 않고» 등급별 동적(Max > Pro > Lite) ·
+ *   권장은 «프로젝트 수»(Lite 1 · Pro 1–2 · Max 2 이상) · 넘치면 요청이 실패하거나 줄을 선다(`guides__overview__concept-param.md` «Concurrency Limits»).
+ *   Pod 하나 = 프로젝트 하나로 센다. 세는 단위 = 풀 멤버 클러스터들의 «끝나지 않은» ZAI Job(라벨) ⊕ 이 프로세스가 결정했지만 아직 apply 안 한 수.
+ *   ⚠️ 다른 호스트 프로세스와 «같은 순간» 결정하면 상한을 잠깐 넘을 수 있다(정확한 임대 = 둘째 조각).
+ * ⭐ 넘치면 — 정책(`llm.zaiCodingPlan.overage`)을 따른다: `openrouter`·`balance` → 그 Pod 는 기존 OpenRouter GLM 으로 ·
+ *   `stop`(기본 · 돈 0) → 발사 전 거부(아무것도 apply 하지 않는다).
+ * ⛔ 이 모듈은 가볍게 둔다(무거운 import 0).
+ */
+
+/** 클러스터(풀 노드마다)·네임스페이스(Pod 와 같은 곳)에 미리 둔 Secret 이름. */
+export const ZAI_POD_SECRET_NAME = 'elanous-zai-coding-plan';
+/** Secret 안의 키 이름 = Pod env 이름(`getZaiApiKey` 가 env 로 읽는다). */
+export const ZAI_POD_SECRET_KEY = 'ZAI_API_KEY';
+/** glm(ZAI) Pod 만 다는 라벨 — 이그레스 정책이 이 라벨에만 443 을 열고, 동시 상한이 이 라벨로 Job 을 센다. */
+export const ZAI_POD_EGRESS_LABEL = 'elanous.egress/zai';
+
+type KubectlLike = (args: string[], stdin?: string) => { status: number | null; stdout: string; stderr: string };
+
+/** Secret 의 «키 이름»만 뽑는 kubectl 인자 — go-template 이 값을 찍지 않는다. */
+export function zaiPodSecretKeyNamesArgs(namespace: string, secretName = ZAI_POD_SECRET_NAME): string[] {
+  return ['-n', namespace, 'get', 'secret', secretName, '-o', 'go-template={{range $k, $v := .data}}{{$k}}{{"\\n"}}{{end}}'];
+}
+
+export interface ZaiPodSpec { secretName: string }
+export type ZaiPodCheck = { ok: true; spec: ZaiPodSpec } | { ok: false; reason: string };
+
+/** 발사 «전» 판정 — Secret 이 있나 · `ZAI_API_KEY` 키가 있나. ⛔ 사유 문면에 값·stderr 원문을 싣지 않는다. */
+export function checkZaiPodSecret(kubectl: KubectlLike, namespace: string, secretName = ZAI_POD_SECRET_NAME): ZaiPodCheck {
+  const fix = `scripts/fleet/zai-pod-secret.ts 로 ${namespace}/${secretName} 을 만든다(승인 뒤)`;
+  const got = kubectl(zaiPodSecretKeyNamesArgs(namespace, secretName));
+  if (got.status !== 0) {
+    return { ok: false, reason: /not ?found/i.test(got.stderr) ? `pod: glm(ZAI) 자격 Secret 없음 — ${namespace}/${secretName} · ${fix}` : `pod: glm(ZAI) 자격 Secret 을 못 읽었다 — ${namespace}/${secretName} (kubectl rc=${got.status}) · 발사하지 않는다` };
+  }
+  const present = new Set(got.stdout.split('\n').map((line) => line.trim()).filter(Boolean));
+  if (!present.has(ZAI_POD_SECRET_KEY)) return { ok: false, reason: `pod: glm(ZAI) 자격 Secret ${namespace}/${secretName} 에 ${ZAI_POD_SECRET_KEY} 키가 없다 · ${fix}` };
+  return { ok: true, spec: { secretName } };
+}
+
+/** glm 자식 컨테이너 env — 키는 secretKeyRef 로만. */
+export function zaiPodEnv(spec: ZaiPodSpec): Array<Record<string, unknown>> {
+  return [{ name: ZAI_POD_SECRET_KEY, valueFrom: { secretKeyRef: { name: spec.secretName, key: ZAI_POD_SECRET_KEY } } }];
+}
+
+/** 라벨 붙은 Job 의 «이름 · 성공 수 · 실패 수» — 값·Secret 은 건드리지 않는다. */
+export function zaiActiveJobsArgs(namespace: string): string[] {
+  return ['-n', namespace, 'get', 'jobs', '-l', `${ZAI_POD_EGRESS_LABEL}=true`, '-o', 'jsonpath={range .items[*]}{.metadata.name} {.status.succeeded} {.status.failed}{"\\n"}{end}'];
+}
+
+/** 끝나지 않은 ZAI Job 수(Job 은 backoffLimit 0 — 성공·실패가 하나라도 있으면 끝났다). 못 읽으면 null(=«모른다» · 0 이 아니다). */
+export function countActiveZaiJobs(kubectl: KubectlLike, namespace: string): number | null {
+  const got = kubectl(zaiActiveJobsArgs(namespace));
+  if (got.status !== 0) return null;
+  let active = 0;
+  for (const line of got.stdout.split('\n')) {
+    const [name, succeeded, failed] = line.trim().split(/\s+/);
+    if (!name) continue;
+    if (Number(succeeded || 0) > 0 || Number(failed || 0) > 0) continue;
+    active++;
+  }
+  return active;
+}
+
+export type ZaiPodSlotDecision =
+  | { route: 'zai'; active: number; maxConcurrent: number }
+  | { route: 'openrouter'; active: number | null; maxConcurrent: number; reason: 'full' | 'unknown-count' }
+  | { route: 'refuse'; active: number | null; maxConcurrent: number; reason: string };
+
+/** 순수 판정 — 셀 수 없으면(null) «찼다»로 본다(구독 한도를 넘기는 쪽으로 기울지 않는다). */
+export function decideZaiPodSlot(input: { active: number | null; pending: number; maxConcurrent: number; overage: 'stop' | 'balance' | 'openrouter' }): ZaiPodSlotDecision {
+  const { maxConcurrent } = input;
+  const active = input.active === null ? null : input.active + input.pending;
+  if (active !== null && active < maxConcurrent) return { route: 'zai', active, maxConcurrent };
+  const why = active === null ? 'unknown-count' as const : 'full' as const;
+  if (input.overage === 'stop') {
+    return { route: 'refuse', active, maxConcurrent, reason: `pod: glm(ZAI) Pod 동시 상한 ${maxConcurrent} ${active === null ? '— 지금 수를 못 셌다' : `— 이미 ${active} 개`} · 정책 llm.zaiCodingPlan.overage=stop 이라 OpenRouter 로 넘기지 않는다(돈 0) · 넘치는 Pod 를 OpenRouter GLM 으로 보내려면 overage=openrouter` };
+  }
+  return { route: 'openrouter', active, maxConcurrent, reason: why };
+}
+
+/** 넘친 Pod 의 자식 인자 — `--child-llm-provider glm --child-llm-model <m>` → openrouter ⊕ OpenRouter GLM 모델. 다른 인자는 그대로.
+ *  ⚠️ effort 는 다루지 않는다 — `podChildLlmArgs` 가 effort 를 Pod 인자에 싣지 않기 때문이다(싣게 되면 여기도 본다). */
+export function zaiOverflowChildArgs(args: readonly string[], openrouterModel: string): string[] {
+  const out = [...args];
+  const p = out.indexOf('--child-llm-provider');
+  if (p < 0 || out[p + 1] !== 'glm') return out;
+  out[p + 1] = 'openrouter';
+  const m = out.indexOf('--child-llm-model');
+  if (m >= 0 && out[m + 1] !== undefined && !out[m + 1]!.startsWith('--')) out[m + 1] = openrouterModel;
+  else out.splice(p + 2, 0, '--child-llm-model', openrouterModel);
+  return out;
+}