elanous 0.2.18 → 0.2.20

package/src/task-agent/task-hand.ts

@@ -7,9 +7,12 @@
  * - 기본은 SHADOW: 카드와 명령만 남기고 아무것도 띄우지 않는다. `--live` 일 때만 주입된 launcher 로 띄운다.
  * - 관측: `debug.log('task-agent', 'handed', {taskId, seat, checklistId, mode})`.
  */
+import { execFileSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { resolveDaemonHarnessTarget } from '../intake-plane/harness-target.js';
+import { HARNESS_RUN_ID_ENV, mintRunId, normalizeRunId } from '../harness/harness-space.js';
 import { debug } from '../debug/log.js';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { withFileLockSync } from '../storage/file-lock.js';
@@ -18,17 +21,35 @@ export const TASK_SEATS = ['OP', 'TC', 'MK', 'UX'] as const;
 export type TaskSeat = typeof TASK_SEATS[number];
 /** 과제 카드 id 접두 — `task show <id>` 가 이 접두로 TOX 태스크와 갈린다. */
 export const TASK_CARD_PREFIX = 'ta-';
+/**
+ * 과제 종결 종류(RFC-loop-agent-map §A4b③) — 비면 code-pr(PR 병합)로 읽는다.
+ * code-pr 밖의 종류는 «확인 증거»(`judge.ts` TaskJudgeInput.evidence)로 종결한다 — 증거를 만드는 일은 DEFAULT-HANDS 몫.
+ */
+export const COMPLETION_KINDS = ['code-pr', 'artifact', 'research-report', 'ops-action', 'content', 'watch-brief', 'decision-support'] as const;
+export type CompletionKind = typeof COMPLETION_KINDS[number];
 
-export interface TaskCardEvent { at: string; event: string; detail?: string }
+/** `run-bound`·`goal-bound`·`pr-bound` 은 runId(⊕ pr)를 싣는다 — 옛 카드의 칸은 at·event·detail 뿐이다. */
+export interface TaskCardEvent { at: string; event: string; detail?: string; runId?: string; pr?: number }
 export interface TaskCardMove { kind: 'launch' | 'wait'; command?: string[]; reason: string }
 export interface TaskCard {
   id: string;
   text: string;
   seat?: TaskSeat;
   checklistId?: string;
+  /** 종결 종류 — 비면 code-pr. */
+  completion?: CompletionKind;
+  /** 과제 대상 프로젝트(§A4b②) — target 은 절대 경로(git 이 아닐 수 있다). id 는 `task hand --project` 가 싣는다(옛 카드엔 없을 수 있다). */
+  project?: { id?: string; target: string };
+  /** 보드(§A4b① `board.ts`) 소속 — 목표 id · 이정표 id(`task hand --goal/--milestone`). 조각 카드의 `goalId`(골 sha 16자)와 다른 칸이다. */
+  goal?: string;
+  milestone?: string;
   createdAt: string;
-  /** launch-failed = 발사기가 띄우기에 실패했다(사유는 history 마지막 칸) — 다음 수는 다시 발사. */
-  status: 'handed' | 'launched' | 'launch-failed';
+  /**
+   * launch-failed = 발사기가 띄우기에 실패했다(사유는 history 마지막 칸) — 다음 수는 다시 발사.
+   * failed = 발사된 런이 PR·수확 가지 없이 죽었거나 끝내 안 떴다(TA-JUDGE-DEAD-RUN · `card-evidence.ts`) — 사유
+   * (`failed/needs-owner|needs-relaunch — …`)는 history 마지막 칸 · 자동 재발사하지 않는다(사람/판단부 몫).
+   */
+  status: 'handed' | 'launched' | 'launch-failed' | 'failed';
   history: TaskCardEvent[];
   /** 미션 카드만 — 조각 카드 id(순서대로) · 쪼갠 출처(`mission.ts` splitMission). */
   pieces?: string[];
@@ -36,17 +57,48 @@ export interface TaskCard {
   /** 조각 카드만 — 소속 미션 카드 id · 먼저 착지해야 하는 조각 id(선후). */
   mission?: string;
   after?: string[];
-  /** 조각 카드만 — 착지 근거(② `tasks advance --pr|--goal`): 이 조각 런이 연 PR 번호 · 골 id(16자 · 런 원장 `pr-opened` 로 PR 을 찾는다). */
-  pr?: number;
+  /**
+   * 이 카드 런이 연 PR · 골 id(16자). 두 출처가 한 칸을 쓴다(UX LOOP-INTERACT 계약 — card.runId → goalId):
+   * - 수동(② `tasks advance --pr|--goal` · 미션 조각만) — PR 은 번호(number) · `refSource: 'manual'`.
+   * - 런 원장 묶기(TA-CARD-RUN-LINK `card-evidence.ts`) — PR 은 `{number, url}` · 비어 있을 때만 «한 번» 채운다 · 수동 근거를 덮지 않는다.
+   * 번호는 `cardPrNumber` 로 읽는다(옛 카드의 number 도 그대로 읽힌다).
+   */
+  pr?: number | TaskCardPr;
   goalId?: string;
+  /** `manual` = pr/goalId 를 사람이 적었다(`recordPieceRef`) — 런 묶기가 건드리지 않는다. */
+  refSource?: 'manual';
   /** 조각 카드만 — ② 가 선행 착지 뒤 넘겼다(한 번만 · 같은 잠금 안에서 먼저 적는다). */
   handed?: { at: string; mode: 'shadow' | 'live'; claim?: string; error?: string };
+  /**
+   * TA-CARD-RUN-LINK — `--live` 발사가 발사기에 넘긴 런 id(`ELANOUS_RUN_ID` 상속 → 하니스 런이 그 id 로 돈다) ⊕ 발사 토큰.
+   * 발사기가 그 id 를 «받았다»고 돌려줄 때만 적는다(한 번만). 원장이 아직 없으면 그 런은 시작 전이거나 대기열로 갔다.
+   */
+  runId?: string;
+  launchId?: string;
+  /** Pod 런이면 PR 을 연 자식 런 id(런 묶기가 PR 과 함께 적는다). */
+  runChildId?: string;
   /** 미션 카드만 — 모든 조각 착지 → 칸 green «제안»(체크리스트는 손대지 않는다 · OP/주인이 뒤집는다). */
   greenProposal?: { at: string; checklistId: string | null; evidence: Record<string, string> };
+  /** TA-JUDGE-LIVE-SAFE — live `review` 수가 리뷰를 요청한 PR 머리들(머리마다 한 번 · 띄우기 실패면 error · 이력은 지우지 않는다). */
+  reviewRequests?: Array<{ pr: number; head: string; at: string; error?: string }>;
+}
+
+/** 런 원장에서 묶은 PR — url 은 원장(pr-opened · Pod job-finished)에 있을 때만(지어내지 않는다). */
+export interface TaskCardPr { number: number; url?: string }
+
+/** 카드의 PR 번호 — 수동(number)·묶음(`{number,url}`) 둘 다. */
+export function cardPrNumber(card: Pick<TaskCard, 'pr'>): number | undefined {
+  return typeof card.pr === 'number' ? card.pr : card.pr?.number;
 }
 
 interface TaskAgentStateFile { tasks?: Record<string, TaskCard>; [key: string]: unknown }
 
+function isGitWorkTree(path: string): boolean {
+  try {
+    return execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: path, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() === 'true';
+  } catch { return false; }
+}
+
 export function taskAgentStatePath(): string {
   return join(effectiveInstanceRoot(), 'task-agent-actions.json');
 }
@@ -130,6 +182,7 @@ export function nextMoveFor(card: TaskCard, landed?: ReadonlySet<string>): TaskC
   if (card.status !== 'launched' && unmet.length > 0) return { kind: 'wait', reason: `after ${unmet.join(', ')}${landed ? '' : ' · 착지 미확인'}` };
   if (card.status === 'handed') return { kind: 'launch', command: launchArgs(card), reason: '넘겨받은 과제 — 첫 발사' };
   if (card.status === 'launch-failed') return { kind: 'launch', command: launchArgs(card), reason: '직전 발사 실패 — 다시 발사' };
+  if (card.status === 'failed') return { kind: 'wait', reason: card.history.at(-1)?.detail ?? '런 실패 — PR·수확 가지 없음' };
   return { kind: 'wait', reason: '발사됨 — 런 멈춤을 슈퍼바이저 그림자 판단(task-agent.shadow-move)이 받는다' };
 }
 
@@ -137,12 +190,22 @@ export function shellQuote(arg: string): string {
   return /^[A-Za-z0-9_./:=@%+-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
 }
 
-export type TaskLauncher = (args: string[]) => void | Promise<void>;
+/** 발사기에 넘기는 연결 — env(`ELANOUS_RUN_ID`)를 자식 환경에 얹으면 하니스 런이 `runId` 로 돈다(`resolveRunIdentity` 상속). launchId 는 카드에만 남는 발사 토큰이다. */
+export interface TaskLaunchContext { runId: string; launchId: string; env: Record<string, string> }
+/** 발사기가 «이 런 id 로 띄웠다»고 돌려주는 영수증 — 없으면 카드에 런 id 를 적지 않는다(추측하지 않는다). */
+export interface TaskLaunchReceipt { runId?: string }
+export type TaskLauncher = (args: string[], cwd?: string, context?: TaskLaunchContext) => void | TaskLaunchReceipt | Promise<void | TaskLaunchReceipt>;
 
 export interface HandTaskOptions {
   text: string;
   seat?: TaskSeat;
   checklistId?: string;
+  completion?: TaskCard['completion'];
+  /** `--project <id> --target <dir>` — target 은 존재 확인 뒤 절대 경로로 바꿔 싣는다. */
+  project?: { id: string; target: string };
+  /** 보드 소속 목표·이정표 id — 카드에 그대로 싣는다. */
+  goal?: string;
+  milestone?: string;
   live?: boolean;
   statePath?: string;
   /** `--live` 일 때만 불린다. */
@@ -179,12 +242,31 @@ export class TaskLaunchError extends Error {
   }
 }
 
-export interface HandTaskResult { card: TaskCard; move: TaskCardMove; mode: 'shadow' | 'live'; launched: boolean }
+export interface HandTaskResult { card: TaskCard; move: TaskCardMove; mode: 'shadow' | 'live'; launched: boolean; cwd?: string }
 
 export async function handTask(opts: HandTaskOptions): Promise<HandTaskResult> {
   const text = opts.text.trim();
   if (!text) throw new Error('과제 한 줄이 비어 있다');
   if (opts.seat !== undefined && !TASK_SEATS.includes(opts.seat)) throw new Error(`자리는 ${TASK_SEATS.join('|')} 중 하나다: ${opts.seat}`);
+  if (opts.completion !== undefined && !COMPLETION_KINDS.includes(opts.completion)) throw new Error(`종결 종류는 ${COMPLETION_KINDS.join('|')} 중 하나다: ${opts.completion}`);
+  for (const [flag, value] of [['--goal', opts.goal], ['--milestone', opts.milestone]] as const) {
+    if (value !== undefined && (!value.trim() || /\p{Cc}/u.test(value))) throw new Error(`${flag} id 가 비었거나 제어 문자를 담았다: ${JSON.stringify(value)}`);
+  }
+  let project: TaskCard['project'];
+  let targetIsGit: boolean | null = null;
+  if (opts.project) {
+    if (!opts.project.id.trim()) throw new Error('--project id 가 비어 있다');
+    const target = resolve(opts.project.target);
+    let isDir = false;
+    try { isDir = statSync(target).isDirectory(); } catch { /* 없음 */ }
+    if (!isDir) throw new Error(`대상 디렉터리가 없습니다: ${target}`);
+    targetIsGit = isGitWorkTree(target);
+    // 코드 종결(code-pr · 비면 code-pr)은 git 대상만 — 그 밖의 종결 종류는 git 이 아닌 폴더도 받는다(같은 판정을 harness-target 과 공유).
+    const codeCompletion = (opts.completion ?? 'code-pr') === 'code-pr';
+    const selection = resolveDaemonHarnessTarget({ configured: target, cwd: target, isGitRepo: () => targetIsGit === true, allowNonGit: !codeCompletion });
+    if (!selection.ok) throw new Error(`코드 종결은 git 대상이 필요 — --completion 을 고르거나 git init: ${target}`);
+    project = { id: opts.project.id, target: selection.repo };
+  }
   const now = (opts.now ?? (() => new Date()))();
   const id = opts.id ?? `${TASK_CARD_PREFIX}${now.toISOString().slice(0, 10).replaceAll('-', '')}-${randomBytes(3).toString('hex')}`;
   const mode = opts.live ? 'live' : 'shadow';
@@ -193,6 +275,10 @@ export async function handTask(opts: HandTaskOptions): Promise<HandTaskResult> {
     id, text,
     ...(opts.seat ? { seat: opts.seat } : {}),
     ...(opts.checklistId ? { checklistId: opts.checklistId } : {}),
+    ...(opts.completion ? { completion: opts.completion } : {}),
+    ...(project ? { project } : {}),
+    ...(opts.goal ? { goal: opts.goal } : {}),
+    ...(opts.milestone ? { milestone: opts.milestone } : {}),
     createdAt: now.toISOString(),
     status: 'handed',
     history: [],
@@ -210,17 +296,21 @@ export async function handTask(opts: HandTaskOptions): Promise<HandTaskResult> {
       if (!guard(current)) return undefined;
       owned.ok = true;
       // next 의 옛 근거는 버리고 디스크의 근거로 «교체»한다 — 정정된 근거 옆에 옛 근거가 되살아나지 않게.
-      const { pr: _stalePr, goalId: _staleGoal, ...base } = next;
-      return { ...base, ...(current?.pr !== undefined ? { pr: current.pr } : {}), ...(current?.goalId !== undefined ? { goalId: current.goalId } : {}) };
+      const { pr: _stalePr, goalId: _staleGoal, refSource: _staleSource, ...base } = next;
+      return { ...base, ...(current?.pr !== undefined ? { pr: current.pr } : {}), ...(current?.goalId !== undefined ? { goalId: current.goalId } : {}), ...(current?.refSource ? { refSource: current.refSource } : {}) };
     });
     if (!owned.ok) throw new TaskCardSupersededError(next.id);
   };
   writeCard(path, card);
-  try { debug.log('task-agent', 'handed', { taskId: id, seat: card.seat ?? null, checklistId: card.checklistId ?? null, mode }); } catch { /* fail-soft */ }
-  if (mode === 'shadow') return { card, move, mode, launched: false };
+  try { debug.log('task-agent', 'handed', { taskId: id, seat: card.seat ?? null, checklistId: card.checklistId ?? null, mode, projectId: project?.id ?? null, targetIsGit }); } catch { /* fail-soft */ }
+  if (mode === 'shadow') return { card, move, mode, launched: false, ...(project ? { cwd: project.target } : {}) };
   if (!opts.launcher) throw new Error('--live 인데 launcher 가 없다');
+  const runId = mintRunId();
+  const launchId = `tl-${randomBytes(6).toString('hex')}`;
+  const context: TaskLaunchContext = { runId, launchId, env: { [HARNESS_RUN_ID_ENV]: runId } };
+  let receipt: void | TaskLaunchReceipt;
   try {
-    await opts.launcher(move.command!);
+    receipt = await opts.launcher(move.command!, project?.target, context);
   } catch (error) {
     const reason = error instanceof Error ? error.message : String(error);
     const failed: TaskCard = { ...card, status: 'launch-failed', history: [{ at: (opts.now ?? (() => new Date()))().toISOString(), event: 'launch-failed', detail: reason }] };
@@ -228,8 +318,25 @@ export async function handTask(opts: HandTaskOptions): Promise<HandTaskResult> {
     try { debug.log('task-agent', 'launch-failed', { taskId: id, seat: card.seat ?? null, reason }); } catch { /* fail-soft */ }
     throw new TaskLaunchError(failed, reason);
   }
-  const launched: TaskCard = { ...card, status: 'launched', history: [{ at: (opts.now ?? (() => new Date()))().toISOString(), event: 'launch', detail: move.command!.join(' ') }] };
+  const launchedAt = (opts.now ?? (() => new Date()))().toISOString();
+  const receivedRunId = receipt && typeof receipt.runId === 'string' ? receipt.runId.trim() : '';
+  // 넘긴 런 id 와 «같은» 영수증만 — 다른 id 면 env 로 넘긴 런과 카드가 어긋난다(묶지 않는다).
+  const boundRunId = receivedRunId && receivedRunId === runId && normalizeRunId(receivedRunId) === receivedRunId ? receivedRunId : undefined;
+  if (receivedRunId && !boundRunId) {
+    try { debug.log('task-agent', 'card-run-unbound', { card: id, launchId, expected: runId, received: receivedRunId }); } catch { /* fail-soft */ }
+  }
+  const launched: TaskCard = {
+    ...card, status: 'launched',
+    ...(boundRunId ? { runId: boundRunId, launchId } : {}),
+    history: [
+      { at: launchedAt, event: 'launch', detail: move.command!.join(' ') },
+      ...(boundRunId ? [{ at: launchedAt, event: 'run-bound', detail: boundRunId, runId: boundRunId }] : []),
+    ],
+  };
   writeCard(path, launched);
-  try { debug.log('task-agent', 'launched', { taskId: id, seat: card.seat ?? null }); } catch { /* fail-soft */ }
-  return { card: launched, move, mode, launched: true };
+  try { debug.log('task-agent', 'launched', { taskId: id, seat: card.seat ?? null, runId: boundRunId ?? null }); } catch { /* fail-soft */ }
+  if (boundRunId) {
+    try { debug.log('task-agent', 'card-run-bound', { card: id, runId: boundRunId, launchId }); } catch { /* fail-soft */ }
+  }
+  return { card: launched, move, mode, launched: true, ...(project ? { cwd: project.target } : {}) };
 }

package/src/task-orchestrator/surfaces/pod-command-job.ts

@@ -14,6 +14,7 @@ import { debug } from '../../debug/log.js';
 import { effectiveInstanceRoot } from '../../instance/resolve.js';
 import { collectPodArtifacts } from './pod-artifact-return.js';
 import { podBunCacheVolume } from './pod-bun-cache.js';
+import { podHostDirsInit, podInstallSlotsVolume } from './pod-install-slots.js';
 import { type PodPoolMember, PodPoolScheduler, resolvePodPoolSpec, parsePodPool, checkPodPool, syncPoolImages, type PoolKubectl } from './pod-pool.js';
 import { podSkillsDigest, readSkillEnvFiles, resolvePodSkills } from './pod-skills.js';
 import { podSourceScript, type PodSource } from './pod-source-receive.js';
@@ -37,6 +38,54 @@ export const POD_LITE_IMAGE = 'elanous-harness-lite:local';
 export const POD_LITE_MEMORY_LIMIT = '2Gi';
 
 /** 요청은 한도를 넘을 수 없다(쿠버네티스가 Job 을 거부한다) — lite 2Gi 처럼 한도가 기본 요청보다 작으면 한도로 맞춘다. */
+/** The command Job container's CPU limit when the caller names none (GATE-SPEED A3①: unchanged default). */
+export const POD_COMMAND_CPU_LIMIT_DEFAULT = '4';
+
+/** Container CPU request/limit override. Omitted fields keep the defaults (request `POD_CHILD_REQUESTS.cpu` · limit 4). */
+export interface PodCpu { request?: string; limit?: string }
+
+/** Kubernetes CPU quantity → millicores (`1` · `0.5` · `500m`); null when it is not a positive quantity we accept. */
+export function podCpuMillis(value: string): number | null {
+  const m = /^(?:(\d+(?:\.\d{1,3})?)|(\d+)m)$/.exec(value.trim());
+  if (!m) return null;
+  const millis = m[1] !== undefined ? Math.round(Number(m[1]) * 1000) : Number(m[2]);
+  return Number.isSafeInteger(millis) && millis > 0 ? millis : null;
+}
+
+/** Resolve a CPU override against the defaults; throws when a value is malformed or the request exceeds the limit (k8s would refuse the Job). */
+export function resolvePodCpu(cpu: PodCpu | undefined): { request: string; limit: string } {
+  const request = cpu?.request?.trim() || POD_CHILD_REQUESTS.cpu;
+  const limit = cpu?.limit?.trim() || POD_COMMAND_CPU_LIMIT_DEFAULT;
+  const r = podCpuMillis(request), l = podCpuMillis(limit);
+  if (r === null) throw new Error(`pod cpu request is not a positive CPU quantity: ${request}`);
+  if (l === null) throw new Error(`pod cpu limit is not a positive CPU quantity: ${limit}`);
+  if (r > l) throw new Error(`pod cpu request ${request} exceeds limit ${limit}`);
+  return { request, limit };
+}
+
+/** Config value → CPU override (release gate `release.loop.gatePodCpu`). A scalar (`2` · `"1500m"`) sets request = limit;
+ *  `{ request, limit }` sets either side. Absent/empty = undefined (request 1 / limit 4). Malformed values throw. */
+export function parsePodCpu(value: unknown, label = 'cpu'): PodCpu | undefined {
+  const text = (v: unknown): string | undefined => {
+    if (v === undefined || v === null || v === '') return undefined;
+    if (typeof v !== 'number' && typeof v !== 'string') throw new Error(`${label} must be a CPU quantity or { request, limit }`);
+    return String(v).trim() || undefined;
+  };
+  let cpu: PodCpu;
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    const { request, limit, ...rest } = value as Record<string, unknown>;
+    if (Object.keys(rest).length) throw new Error(`${label} has unknown keys: ${Object.keys(rest).join(', ')}`);
+    const r = text(request), l = text(limit);
+    cpu = { ...(r ? { request: r } : {}), ...(l ? { limit: l } : {}) };
+  } else {
+    const both = text(value);
+    cpu = both ? { request: both, limit: both } : {};
+  }
+  if (!cpu.request && !cpu.limit) return undefined;
+  resolvePodCpu(cpu);
+  return cpu;
+}
+
 export function memoryRequestWithin(limit: string | undefined): string {
   const gi = (value: string | undefined) => { const m = /^(\d+)Gi$/.exec(value ?? ''); return m ? Number(m[1]) : null; };
   const request = gi(POD_CHILD_REQUESTS.memory);
@@ -128,8 +177,12 @@ export interface PodCommandJobInput {
   clone?: boolean;
   hostMirror?: string;
   bunCache?: string;
+  /** GATE-INSTALL-CACHE — hostPath of the node-wide install tokens (release gate shards only · `pod-install-slots.ts`). */
+  installSlots?: string;
   /** 컨테이너 메모리 한도(기본 16Gi) — 게이트가 파일 하나 격리 Job 에 올린다. */
   memoryLimit?: string;
+  /** GATE-SPEED A3①: CPU request/limit override (release gate shards only). Omitted = request 1 / limit 4. */
+  cpu?: PodCpu;
   source?: PodSource;
   deadlineSeconds: number;
   runId?: string;
@@ -147,6 +200,10 @@ export function podCommandJobManifest(o: PodCommandJobInput): Record<string, unk
   }
   const grok = o.llm === 'grok';
   const bunCache = o.bunCache ? podBunCacheVolume(o.bunCache) : undefined;
+  const installSlots = o.installSlots ? podInstallSlotsVolume(o.installSlots) : undefined;
+  // hostPath directories the uid-1000 child writes: a root init container hands them over (DirectoryOrCreate is root 0755).
+  const hostDirMounts = [...(bunCache ? [bunCache.volumeMount] : []), ...(installSlots ? [installSlots.volumeMount] : [])];
+  const cpu = resolvePodCpu(o.cpu);
   const quotedArgs = o.command.map(bashSingleQuote).join(' ');
   const credLines = [
     ...(grok ? ['mkdir -p ~/.grok && install -m 600 /creds/grok-auth.json ~/.grok/auth.json'] : []),
@@ -182,26 +239,30 @@ export function podCommandJobManifest(o: PodCommandJobInput): Record<string, unk
         spec: {
           restartPolicy: 'Never',
           securityContext: { runAsUser: 1000, fsGroup: 1000 },
-          initContainers: [{ name: 'isolation-gate', image: o.image, imagePullPolicy: o.imagePullPolicy ?? 'Never', command: ['bash', '-c'], args: [GATE] }],
+          initContainers: [
+            { name: 'isolation-gate', image: o.image, imagePullPolicy: o.imagePullPolicy ?? 'Never', command: ['bash', '-c'], args: [GATE] },
+            ...(hostDirMounts.length ? [podHostDirsInit(o.image, o.imagePullPolicy ?? 'Never', hostDirMounts)] : []),
+          ],
           containers: [{
             name: 'child', image: o.image, imagePullPolicy: o.imagePullPolicy ?? 'Never',
-            resources: { requests: { ...POD_CHILD_REQUESTS, memory: memoryRequestWithin(o.memoryLimit) }, limits: { memory: o.memoryLimit ?? '16Gi', cpu: '4' } },
+            resources: { requests: { ...POD_CHILD_REQUESTS, cpu: cpu.request, memory: memoryRequestWithin(o.memoryLimit) }, limits: { memory: o.memoryLimit ?? '16Gi', cpu: cpu.limit } },
             command: ['bash', '-c'], args: [script],
             env: [
               ...(o.runId ? [{ name: 'ELANOUS_RUN_ID', value: o.runId }] : []),
               { name: 'ELANOUS_SUBSTRATE', value: 'pod' },
               { name: 'ELANOUS_POD_NAME', valueFrom: { fieldRef: { fieldPath: 'metadata.name' } } },
             ],
-            ...(secretKeys || o.hostMirror || bunCache ? { volumeMounts: [
+            ...(secretKeys || o.hostMirror || hostDirMounts.length ? { volumeMounts: [
               ...(secretKeys ? [{ name: 'creds', mountPath: '/creds', readOnly: true }] : []),
               ...(o.hostMirror ? [{ name: 'host-mirror', mountPath: '/host-mirror', readOnly: true }] : []),
-              ...(bunCache ? [bunCache.volumeMount] : []),
+              ...hostDirMounts,
             ] } : {}),
           }],
-          ...(secretKeys || o.hostMirror || bunCache ? { volumes: [
+          ...(secretKeys || o.hostMirror || hostDirMounts.length ? { volumes: [
             ...(secretKeys ? [{ name: 'creds', secret: { secretName: `${o.name}-creds`, defaultMode: 0o400 } }] : []),
             ...(o.hostMirror ? [{ name: 'host-mirror', hostPath: { path: o.hostMirror, type: 'Directory' } }] : []),
             ...(bunCache ? [bunCache.volume] : []),
+            ...(installSlots ? [installSlots.volume] : []),
           ] } : {}),
         },
       },
@@ -270,8 +331,12 @@ export interface RunPodCommandOptions {
   clone?: boolean;
   hostMirror?: string;
   bunCache?: string;
+  /** GATE-INSTALL-CACHE — hostPath of the node-wide install tokens (absolute). */
+  installSlots?: string;
   /** 컨테이너 메모리 한도(기본 16Gi · lite 면 2Gi). */
   memoryLimit?: string;
+  /** GATE-SPEED A3①: CPU request/limit override — only the release gate passes it. Omitted = request 1 / limit 4. */
+  cpu?: PodCpu;
   /** POD7: 호출부가 «네트워크 스킬만 쓰는 명령»이라고 말할 때만 lite 이미지 ⊕ 2Gi. */
   lite?: boolean;
   source?: PodSource;
@@ -284,6 +349,7 @@ export interface RunPodCommandOptions {
   name?: string;
   pollMs?: number;
   kubectl?: Kubectl;
+  /** A caller-owned scheduler is self-capped: acquires count only its own Jobs, never cluster occupancy (POOLGLOBAL-REG). */
   poolScheduler?: PodPoolScheduler;
   checkPool?: typeof checkPodPool;
   syncImages?: typeof syncPoolImages;
@@ -356,6 +422,10 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
   if (hostMirror && !isAbsolute(hostMirror)) throw new Error('pod.hostMirror must be an absolute directory path');
   const bunCache = options.bunCache?.trim() || undefined;
   if (bunCache && !isAbsolute(bunCache)) throw new Error('pod.bunCache must be an absolute directory path');
+  const installSlots = options.installSlots?.trim() || undefined;
+  if (installSlots && !isAbsolute(installSlots)) throw new Error('pod installSlots must be an absolute directory path');
+  // Fail before any Secret/Job is applied — a bad quantity must not reach the cluster.
+  if (options.cpu) resolvePodCpu(options.cpu);
 
   let member: PodPoolMember | null = null;
   let pool = options.poolScheduler;
@@ -366,12 +436,16 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
       const members = parsePodPool(spec);
       const checked = (options.checkPool ?? checkPodPool)(members, baseKubectl as PoolKubectl);
       if (!checked.ok) throw new Error('pod command: 풀의 노드가 하나도 준비되지 않았다');
-      pool = new PodPoolScheduler(checked.ready);
+      // Occupancy reads go through the same kubectl as the readiness check (an injected one included).
+      pool = new PodPoolScheduler(checked.ready, { kubectl: baseKubectl as PoolKubectl });
     }
   }
   if (pool) {
+    // POOLGLOBAL-REG: a caller that hands in its own scheduler (the release gate fans its shards over one) holds its own
+    // concurrency cap — its Jobs count against the spec caps, not the cluster's goal Pods (#24253 → 0.2.15 gate ran 1 shard).
+    const selfCapped = options.poolScheduler !== undefined;
     for (;;) {
-      member = await pool.tryAcquire();
+      member = await pool.tryAcquire(undefined, undefined, { selfCapped });
       if (member) break;
       await sleep(options.pollMs ?? 15_000);
     }
@@ -426,7 +500,7 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
       name, namespace, launch, image: imageRef ?? image,
       ...(imageRef ? { imagePullPolicy: 'IfNotPresent' as const } : {}),
       repoUrl, command, skills, ...(llm ? { llm } : {}), ...(options.clone ? { clone: true } : {}),
-      ...(options.source ? { source: options.source } : {}), ...(hostMirror ? { hostMirror } : {}), ...(bunCache ? { bunCache } : {}), ...(memoryLimit ? { memoryLimit } : {}), deadlineSeconds,
+      ...(options.source ? { source: options.source } : {}), ...(hostMirror ? { hostMirror } : {}), ...(bunCache ? { bunCache } : {}), ...(installSlots ? { installSlots } : {}), ...(memoryLimit ? { memoryLimit } : {}), ...(options.cpu ? { cpu: options.cpu } : {}), deadlineSeconds,
       ...(options.runId ? { runId: options.runId } : {}),
     });
     kubectl(['-n', namespace, 'delete', 'job', '-l', own, '--ignore-not-found']);

package/src/task-orchestrator/surfaces/pod-failure-reason.ts

@@ -1,3 +1,7 @@
+/** STOP-RECORD stop_class values used by the card terminal classifier. */
+export const STOP_CLASS_POD_FAILURE = 'pod-failure' as const;
+export const STOP_CLASS_NO_LAUNCH = 'no-launch' as const;
+
 /** Executor kinds of the dev child's `--json` result line (`src/index.ts` writeStdoutJson · DevExecutor.kind). */
 const CHILD_RESULT_KINDS = new Set(['self', 'external']);
 

package/src/task-orchestrator/surfaces/pod-install-slots.ts

@@ -0,0 +1,89 @@
+// GATE-INSTALL-CACHE (0.2.20) — a node-wide throttle for the release-gate shards' `bun install`.
+//
+// Cause, measured on the 0.2.19 gate (`elanous logs --category release-loop.gate --event pod-shard --all --include-test`):
+//   · no cache is «not» the cause — the harness image carries a warm Bun cache, and a Pod that installed alone
+//     (10-07 10:48–10:55 · 12:13 · 12:16) took 2.4–5.0 s with `pod-bun-cache source=none`;
+//   · the same install took 150–340 s when 24 shard Pods (or ~20 isolation Pods) started together on the one 32-CPU
+//     node-b node (09:3x round 1: 221–337 s · 11:4x round 3: 150–240 s · 10:34 isolation wave: 124–188 s).
+//   ⇒ concurrent installs thrash the node (24 × copying node_modules out of the image cache + CPU), so a shared
+//   hostPath Bun cache would not help (the bytes are already local) — fewer installs «at once» does.
+//
+// Concurrency safety: the hostPath holds only throttle tokens (`slot-<n>` directories), never packages. Each Pod still
+// installs into its own container (its own node_modules, its own image-local Bun cache), so correctness never depends on
+// the token: a lost token (Pod killed mid-install) only lowers throughput until it goes stale (`staleSeconds`), a doubled
+// token (two waiters reclaiming one stale slot in the same instant) only lets one extra install run, and a waiter that
+// cannot get a token within `waitSeconds` — or finds the directory unwritable — installs anyway (fail-open).
+// `mkdir` is atomic on one filesystem, and every Pod on a node sees the same hostPath directory.
+
+/** Default hostPath of the install tokens on each gate node. */
+export const POD_INSTALL_SLOTS_HOST_PATH = '/var/lib/elanous/gate-install-slots';
+/** Default concurrent installs per node (`release.loop.gatePodInstallSlots` · 0 = off). Alone ≈ 3–5 s ⇒ 24 shards ≈ 6 waves. */
+export const POD_INSTALL_SLOTS_DEFAULT = 4;
+export const POD_INSTALL_SLOTS_MOUNT = '/gate-install-slots';
+
+/** hostPath volume ⊕ mount for the tokens. `DirectoryOrCreate` makes a root-owned 0755 directory, so the Pod also needs
+ *  {@link podHostDirsInit} (the child runs as uid 1000). */
+export function podInstallSlotsVolume(hostPath: string = POD_INSTALL_SLOTS_HOST_PATH) {
+  return {
+    volume: { name: 'install-slots', hostPath: { path: hostPath, type: 'DirectoryOrCreate' } },
+    volumeMount: { name: 'install-slots', mountPath: POD_INSTALL_SLOTS_MOUNT, readOnly: false },
+  };
+}
+
+/**
+ * A root init container that hands the mounted hostPath directories to the child's uid. Without it a `DirectoryOrCreate`
+ * hostPath stays root:root 0755 and the child's `[ -w … ]` guard silently skips it (the Bun cache option was a no-op).
+ */
+export function podHostDirsInit(image: string, imagePullPolicy: string, mounts: ReadonlyArray<{ name: string; mountPath: string; readOnly: boolean }>) {
+  const paths = mounts.map((mount) => `'${mount.mountPath.replace(/'/g, `'\\''`)}'`).join(' ');
+  return {
+    name: 'host-dirs', image, imagePullPolicy,
+    securityContext: { runAsUser: 0 },
+    command: ['sh', '-c'],
+    // Never fails the Pod: an unchanged directory only means the child falls back (no cache · no throttle).
+    args: [`for d in ${paths}; do mkdir -p "$d" && chown 1000:1000 "$d" && chmod 0775 "$d" || echo "[host-dirs] could not prepare $d"; done; exit 0`],
+    volumeMounts: mounts.map((mount) => ({ ...mount })),
+  };
+}
+
+const int = (value: number, label: string) => {
+  if (!Number.isSafeInteger(value) || value < 1) throw new Error(`invalid ${label}: ${value}`);
+  return value;
+};
+
+/**
+ * Bash that defines `install_slot_acquire` / `install_slot_release`. Acquire waits for one of `slots` tokens under `dir`
+ * (polling every `pollSeconds`, default 2 s), reclaims a token older than `staleSeconds` (minute granularity), and gives up after `waitSeconds` (install runs anyway).
+ * It prints `[gate] install-slot <n> waited <s>s` or `[gate] install-slot none …` for the shard log.
+ */
+export function installSlotScript(o: { dir?: string; slots: number; waitSeconds?: number; staleSeconds?: number; pollSeconds?: number }): string {
+  const dir = `'${(o.dir ?? POD_INSTALL_SLOTS_MOUNT).replace(/'/g, `'\\''`)}'`;
+  const slots = int(o.slots, 'install slots');
+  const wait = int(o.waitSeconds ?? 600, 'install slot wait');
+  const poll = o.pollSeconds ?? 2;
+  if (!Number.isFinite(poll) || poll <= 0 || poll > 60) throw new Error(`invalid install slot poll: ${poll}`);
+  const staleMinutes = Math.max(1, Math.ceil(int(o.staleSeconds ?? 900, 'install slot stale age') / 60));
+  return [
+    'install_slot=',
+    'install_slot_acquire() {',
+    `  local d=${dir} t0 now n`,
+    '  t0=$(date +%s)',
+    '  if [ ! -d "$d" ] || [ ! -w "$d" ]; then echo "[gate] install-slot none (directory not writable)"; return 0; fi',
+    '  while :; do',
+    `    for n in $(seq 0 ${slots - 1}); do`,
+    '      if mkdir "$d/slot-$n" 2>/dev/null; then',
+    '        install_slot="$d/slot-$n"',
+    '        echo "[gate] install-slot $n waited $(( $(date +%s) - t0 ))s"; return 0',
+    '      fi',
+    // A token whose holder died (directory mtime older than the stale age · `find -mmin` is the same on GNU and BSD) is
+    // renamed away first (rename is atomic: one reclaimer wins) and the slot is tried again on the next pass.
+    `      if [ -n "$(find "$d/slot-$n" -maxdepth 0 -mmin +${staleMinutes} 2>/dev/null)" ]; then mv "$d/slot-$n" "$d/stale-$n-$$" 2>/dev/null && rm -rf "$d/stale-$n-$$"; fi`,
+    '    done',
+    '    now=$(date +%s)',
+    `    if [ $(( now - t0 )) -ge ${wait} ]; then echo "[gate] install-slot none (waited $(( now - t0 ))s)"; return 0; fi`,
+    `    sleep ${poll}`,
+    '  done',
+    '}',
+    'install_slot_release() { if [ -n "$install_slot" ]; then rm -rf "$install_slot"; install_slot=; fi; }',
+  ].join('\n');
+}