elanous 0.2.35 → 0.2.36

package/src/task-agent/task-parent-role-llm.ts

@@ -0,0 +1,36 @@
+/** Parent-only role selection for Task Agent launches. The child model is a separate axis. */
+import { parseRoleLlmFlags } from '../llm/role-llm-cli.js';
+import { isModelRole, parseRoleLlmEntry, roleLlmEnvName, type ModelRole, type RoleLlmSpec } from '../user-config.js';
+
+const PARENT_ROLES = new Set<ModelRole>(['planning', 'classify', 'audit', 'review']);
+
+export function taskParentRoleEnv(values: readonly string[]): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const value of values) {
+    const at = value.indexOf('=');
+    const role = value.slice(0, at);
+    if (at < 1 || !isModelRole(role) || !PARENT_ROLES.has(role)) {
+      throw new Error(`--role-llm 부모 역할이 아니다: ${JSON.stringify(value)}`);
+    }
+    let spec: RoleLlmSpec;
+    const raw = value.slice(at + 1);
+    if (raw.startsWith('{')) {
+      let parsed: unknown;
+      try { parsed = JSON.parse(raw); }
+      catch { throw new Error(`--role-llm JSON 을 읽을 수 없다: ${role}`); }
+      const entry = parseRoleLlmEntry(parsed);
+      if (!entry.ok) throw new Error(`--role-llm ${role}: ${entry.reason}`);
+      spec = entry.spec;
+    } else {
+      const parsed = parseRoleLlmFlags([value]);
+      if (!parsed.ok) throw new Error(`--role-llm ${parsed.message}`);
+      const selected = parsed.overrides[role];
+      if (!selected) throw new Error(`--role-llm 선택한 역할이 비었다: ${role}`);
+      spec = selected;
+    }
+    const name = roleLlmEnvName(role);
+    if (env[name] !== undefined) throw new Error(`--role-llm 같은 부모 역할을 두 번 고정했다: ${role}`);
+    env[name] = JSON.stringify(spec);
+  }
+  return env;
+}

package/src/task-agent/tier-split.ts

@@ -6,16 +6,19 @@
  * - 분해 규칙은 TC 몫 — 여기는 그 함수를 «주입 seam» 으로 받는다. 기본 seam 은 이 파일 한 곳(`DEFAULT_TIER_SIZED_DECOMPOSE`)에서만 정한다.
  * - 분해기 «미배선»(seam 에 undefined 명시) = `decomposer-unavailable` → 종전처럼 한 덩어리 발사 ⊕ 기록. 기본 seam 은 TC 함수다.
  * - 분해 «실패»(ok:false · throw · 불가피 이유 없는 상 조각 · 빈/잘못된 조각) → 발사 0 · 카드 failed(history `tier-split-failed`).
- * - 관측: `debug.log('task-agent.hand', 'tier-split', {cid, fromTier, outcome, reason?, slices, unavoidable})`.
+ * - 관측: `debug.log('task-agent.hand', 'tier-split', {cid, fromTier, outcome, reason?, slices, unavoidable,
+ *   countScope:'accepted-slices', totalSlices, highSlices, unavoidableCount, unavoidableReasons})`.
  */
 import { randomBytes } from 'node:crypto';
+import { resolve } from 'node:path';
 import { debug } from '../debug/log.js';
-import { handTask, TASK_CARD_PREFIX, type HandTaskOptions, type HandTaskResult } from './task-hand.js';
+import { handTask, nextMoveFor, parseChildLlm, taskAgentStatePath, updateTaskCard, writeTaskCards, TASK_CARD_PREFIX, type HandTaskOptions, type HandTaskResult, type TaskCard } from './task-hand.js';
 
 // 분해 규칙·타입 정본 = TC `src/self-implement/goal-author-decompose.ts`(TIER-SIZED-DECOMPOSE · #29987).
 import { decomposeToTierSizedSlices, type SizedSlice, type TierSizedDecomposeResult } from '../self-implement/goal-author-decompose.js';
+import { DEVICE_FIRST_STEP } from '../self-implement/device-first.js';
 export type { SizedSlice, TierSizedDecomposeResult };
-export type TierSizedDecompose = (goal: string, opts?: { signal?: AbortSignal }) => Promise<TierSizedDecomposeResult>;
+export type TierSizedDecompose = (goal: string, opts?: { signal?: AbortSignal; repositoryRoot?: string }) => Promise<TierSizedDecomposeResult>;
 
 /** 기본 분해기 — TC `decomposeToTierSizedSlices`. seam 에 undefined 를 명시하면 «미배선»(decomposer-unavailable). */
 export const DEFAULT_TIER_SIZED_DECOMPOSE: TierSizedDecompose | undefined = decomposeToTierSizedSlices;
@@ -40,7 +43,9 @@ export function composeSliceHandText(sliceGoal: string, parentText: string, mark
     const label = INHERITED_PARENT_LABELS.exec(line)?.[1];
     return label !== undefined && !sliceHas.has(label);
   });
-  if (inherited.length === 0) return sliceGoal;
+  // The slice marker also carries review scope. Device slices now own their
+  // completion boundary, so inherited can be empty while the marker is needed.
+  if (inherited.length === 0 && (marker.total < 2 || !sliceGoal.includes(`동작: ${DEVICE_FIRST_STEP}`))) return sliceGoal;
   const tag = `조각 ${marker.index}/${marker.total} — 부모 ${marker.cid ?? '(칸 없음)'}(${marker.fromTier}) 를 중 이하로 나눈 몫. 아래 계약·완료 경계는 부모 칸에서 물려받았다 — 이 조각 범위만 채운다.`;
   return [...sliceLines, tag, ...inherited].join('\n');
 }
@@ -58,6 +63,12 @@ export function planTierSplit(result: TierSizedDecomposeResult): TierSplitPlan {
     if (!slice.goal?.trim()) return { kind: 'blocked', reason: `empty-slice-goal: #${index + 1}` };
     if (slice.tier === '상' && !slice.unavoidable?.trim()) return { kind: 'blocked', reason: `unjustified-상-slice: #${index + 1}` };
   }
+  const deviceSlices = result.slices.filter((slice) => slice.deviceFirst === 'device-test');
+  if (deviceSlices.length === 0 && result.slices.some((slice) => slice.deviceFirst === 'feature'))
+    return { kind: 'blocked', reason: 'device-first-stage-missing' };
+  if (deviceSlices.length > 0 && (deviceSlices.length !== 1 || result.slices[0]?.deviceFirst !== 'device-test'
+    || result.slices.slice(1).some((slice) => slice.deviceFirst !== 'feature')))
+    return { kind: 'blocked', reason: 'device-first-order-invalid' };
   return { kind: 'split', slices: result.slices };
 }
 
@@ -78,6 +89,14 @@ function record(data: Record<string, unknown>): void {
   try { debug.log('task-agent.hand', 'tier-split', data); } catch { /* fail-soft */ }
 }
 
+function acceptedSliceCounts(slices: readonly SizedSlice[]) {
+  const unavoidableReasons = slices.filter((slice) => slice.tier === '상').map((slice) => slice.unavoidable!.trim());
+  // planTierSplit rejects every high slice without a reason, so the accepted
+  // high count and unavoidable count coincide. Keep both for the board axes.
+  return { countScope: 'accepted-slices' as const, totalSlices: slices.length, highSlices: unavoidableReasons.length,
+    unavoidableCount: unavoidableReasons.length, unavoidableReasons };
+}
+
 /**
  * `tasks hand` 의 발사 앞단. 분해는 `--live` ⊕ tier 상|특 일 때만 — 중·하·tier 없음·shadow 는 `handTask` 그대로(분해 호출 0).
  */
@@ -88,7 +107,7 @@ export async function handTaskWithTierSplit(opts: TierSplitHandOptions): Promise
   const decompose = 'decompose' in opts ? injected : DEFAULT_TIER_SIZED_DECOMPOSE;
   const cid = hand.checklistId ?? null;
   if (!decompose) {
-    record({ cid, fromTier, outcome: 'whole', reason: TIER_SPLIT_UNAVAILABLE, slices: [], unavoidable: [] });
+    record({ cid, fromTier, outcome: 'whole', reason: TIER_SPLIT_UNAVAILABLE, slices: [], unavoidable: [], ...acceptedSliceCounts([]) });
     return { kind: 'whole', result: await handTask(hand), reason: TIER_SPLIT_UNAVAILABLE };
   }
   let plan: TierSplitPlan;
@@ -96,24 +115,74 @@ export async function handTaskWithTierSplit(opts: TierSplitHandOptions): Promise
   let timer: ReturnType<typeof setTimeout> | undefined;
   const timedOut = new Promise<'timeout'>((resolve) => { timer = setTimeout(() => { controller.abort(); resolve('timeout'); }, decomposeTimeoutMs); });
   try {
-    const raced = await Promise.race([decompose(hand.text.trim(), { signal: controller.signal }), timedOut]);
+    const raced = await Promise.race([decompose(hand.text.trim(), { signal: controller.signal,
+      ...(hand.project ? { repositoryRoot: resolve(hand.project.target) } : {}) }), timedOut]);
     plan = raced === 'timeout' ? { kind: 'blocked', reason: `decompose-timeout: ${decomposeTimeoutMs}ms` } : planTierSplit(raced);
   } catch (error) {
     plan = { kind: 'blocked', reason: `decompose-threw: ${String((error as Error)?.message ?? error).slice(0, 200)}` };
   } finally { clearTimeout(timer); }
   if (plan.kind === 'blocked') {
-    record({ cid, fromTier, outcome: 'blocked', reason: plan.reason, slices: [], unavoidable: [] });
+    record({ cid, fromTier, outcome: 'blocked', reason: plan.reason, slices: [], unavoidable: [], ...acceptedSliceCounts([]) });
     return { kind: 'blocked', result: await handTask({ ...hand, tierSplitBlocked: plan.reason }), reason: plan.reason };
   }
   const group = `${TASK_CARD_PREFIX}split-${randomBytes(4).toString('hex')}`;
   const total = plan.slices.length;
-  const unavoidable = plan.slices.filter((slice) => slice.tier === '상').map((slice) => slice.unavoidable!.trim());
+  const counts = acceptedSliceCounts(plan.slices);
+  const unavoidable = counts.unavoidableReasons;
   // 조각은 새 카드다 — 호출자 id·pr·goalId 를 조각마다 복제하면 «PR: #N» 조회·수확이 엇갈린다. 버린 것은 기록에 남긴다.
   const dropped = { ...(hand.id ? { id: hand.id } : {}), ...(hand.cardFields?.pr !== undefined ? { pr: hand.cardFields.pr } : {}), ...(hand.cardFields?.goalId !== undefined ? { goalId: hand.cardFields.goalId } : {}) };
-  record({ cid, fromTier, outcome: 'split', group, ...(Object.keys(dropped).length ? { dropped } : {}), slices: plan.slices.map((s) => ({ tier: s.tier, files: s.files, behaviours: s.behaviours })), unavoidable });
+  record({ cid, fromTier, outcome: 'split', group, ...(Object.keys(dropped).length ? { dropped } : {}), slices: plan.slices.map((s) => ({ tier: s.tier, files: s.files, behaviours: s.behaviours })), unavoidable: [...unavoidable],
+    ...counts });
   const { id: _wholeId, cardFields, ...rest } = hand;
   const base = { ...rest, ...(cardFields?.handed !== undefined ? { cardFields: { handed: cardFields.handed } } : {}) };
   const slices: TierSplitSliceOutcome[] = [];
+  // Device-first plans use the existing mission advance engine: only the test/device card starts.
+  // Feature cards carry an explicit `after` edge and `tasks advance` requires a merged PR before launch.
+  if (plan.slices[0]?.deviceFirst === 'device-test') {
+    const now = (hand.now ?? (() => new Date()))().toISOString();
+    const ids = plan.slices.map((_slice, index) => `${group}-${index + 1}`);
+    const mission: TaskCard = { id: group, text: hand.text, createdAt: now, status: 'handed', history: [],
+      pieces: ids, splitSource: 'device-first-tier-split', ...(hand.checklistId ? { checklistId: hand.checklistId } : {}),
+      ...(hand.seat ? { seat: hand.seat } : {}) };
+    const drafts: TaskCard[] = plan.slices.map((slice, index) => ({
+      id: ids[index]!, text: composeSliceHandText(slice.goal, hand.text, { index: index + 1, total, fromTier, cid }),
+      createdAt: now, status: 'handed', history: [], mission: group,
+      after: index === 0 ? [] : [ids[0]!], tier: slice.tier,
+      tierSplit: { group, fromTier, index: index + 1, total, ...(slice.tier === '상' ? { unavoidable: slice.unavoidable!.trim() } : {}) },
+      ...(hand.checklistId ? { checklistId: hand.checklistId } : {}),
+      ...(hand.seat ? { seat: hand.seat } : {}),
+      ...(hand.project ? { project: hand.project } : {}),
+      ...(hand.completion ? { completion: hand.completion } : {}),
+      ...(hand.taLand ? { taLand: true as const } : {}),
+      ...(hand.childLlm ? { childLlm: parseChildLlm(hand.childLlm, hand.childLlmEffort) } : {}),
+      ...(hand.parentRoleLlm?.length ? { parentRoleLlm: [...hand.parentRoleLlm] } : {}),
+    }));
+    writeTaskCards(hand.statePath ?? taskAgentStatePath(), [mission, ...drafts]);
+    const markFirstLaunchFailure = (reason: string) => {
+      updateTaskCard(hand.statePath ?? taskAgentStatePath(), group, (card) => card ? {
+        ...card, status: 'failed', history: [...card.history, { at: new Date().toISOString(),
+          event: 'device-first-launch-failed', detail: reason }],
+      } : undefined);
+    };
+    for (const [index, slice] of plan.slices.entries()) {
+      if (index > 0) {
+        slices.push({ slice, result: { card: drafts[index]!, move: nextMoveFor(drafts[index]!), mode: hand.live ? 'live' : 'shadow', launched: false } });
+        continue;
+      }
+      try {
+        const result = await handTask({ ...base, id: ids[0], text: drafts[0]!.text, tier: slice.tier,
+          mission: group, after: [], tierSplit: drafts[0]!.tierSplit });
+        slices.push({ slice, result });
+        if (hand.live && !result.launched) markFirstLaunchFailure(`first card not launched: ${result.card.status}`);
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        slices.push({ slice, error: reason });
+        markFirstLaunchFailure(reason);
+      }
+    }
+    record({ cid, fromTier, outcome: 'device-first-deferred', group, first: ids[0], blockedUntilLanded: ids.slice(1) });
+    return { kind: 'split', group, fromTier, slices };
+  }
   for (const [index, slice] of plan.slices.entries()) {
     try {
       const result = await handTask({ ...base, text: composeSliceHandText(slice.goal, hand.text, { index: index + 1, total, fromTier, cid }), tier: slice.tier,

package/src/task-orchestrator/surfaces/pod-account-broker.ts

@@ -126,8 +126,17 @@ export function planPodAccounts(
 export function planOwnerCodexMirrorCandidates(candidates: readonly RotationCandidate[], options: {
   accountOrder: readonly string[];
   thresholdPercentByAccount?: Readonly<Record<string, unknown>>;
+  creditsAllowed?: boolean;
+  creditReserve?: number;
 }): RotationCandidate[] {
   const usable = new Set(planPodAccounts(candidates, { thresholdPercentByAccount: options.thresholdPercentByAccount }).usable);
+  // The parent has to install an access mirror before the remote Pod can use its
+  // credit fallback. Only a measured balance above the reserve admits that mirror.
+  if (usable.size === 0 && options.creditsAllowed) {
+    const reserve = typeof options.creditReserve === 'number' && Number.isFinite(options.creditReserve) && options.creditReserve >= 0
+      ? options.creditReserve : CODEX_CREDIT_RESERVE_DEFAULT;
+    return creditCandidatesByBalance(candidates, reserve);
+  }
   const rank = (name: string): number => {
     const index = options.accountOrder.indexOf(name);
     return index < 0 ? options.accountOrder.length : index;

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

@@ -0,0 +1,146 @@
+import { decidePodReuseCleanup } from './pod-reuse-cleanup.js';
+import type { WarmWorkerKey } from './pod-warm-worker-protocol.js';
+
+/** An admitted si-v1 worker is identified by the pool, never by a Job name alone. */
+export interface ChildPodLease {
+  workerId: string;
+  podUid: string;
+  leaseId: string;
+  generation: number;
+  key: WarmWorkerKey;
+  sourceSha: string;
+}
+
+export interface ChildPodReuseCommandResult {
+  status: number | null;
+  stdout?: string;
+}
+
+export interface ChildPodCleanupReceipt {
+  clean: boolean;
+  reason: string;
+  /** Known residual lower bound; null means unmeasured surfaces and no observed residue. */
+  observedResidue: number | null;
+}
+
+/** Operations execute inside the admitted worker, after its child result and artifacts have been collected. */
+export interface ChildPodReuseOperations {
+  stopChildProcesses: (lease: ChildPodLease) => Promise<{ remaining: number }>;
+  git: (lease: ChildPodLease, args: readonly string[]) => Promise<ChildPodReuseCommandResult>;
+  removeRunCredentials: (lease: ChildPodLease) => Promise<{ remaining: number }>;
+  returnLease: (lease: ChildPodLease, receipt: ChildPodCleanupReceipt) => Promise<void>;
+  quarantine: (lease: ChildPodLease, receipt: ChildPodCleanupReceipt) => Promise<void>;
+  observe: (event: 'return-decision' | 'clean-failed' | 'quarantine-failed', data: Record<string, unknown>) => void;
+}
+
+export interface ChildPodReturnResult {
+  outcome: 'returned' | 'quarantined';
+  reason: string;
+}
+
+/**
+ * A completed child may return to the pool only after all four independent
+ * checks succeed. A missing return-decision observation also blocks return;
+ * the worker stays out of the lease pool until quarantine succeeds.
+ */
+export async function cleanAndReturnChildPod(
+  lease: ChildPodLease,
+  ops: ChildPodReuseOperations,
+): Promise<ChildPodReturnResult> {
+  const facts = { workerId: lease.workerId, podUid: lease.podUid,
+    leaseId: lease.leaseId, generation: lease.generation };
+  const log = (event: Parameters<ChildPodReuseOperations['observe']>[0], data: Record<string, unknown>) => {
+    try { ops.observe(event, { ...facts, ...data }); } catch { /* logging must not return an unsafe lease */ }
+  };
+  let reason = '';
+  let observedResidue = 0;
+  let processMeasured = false;
+  let gitMeasured = false;
+  let credentialsMeasured = false;
+  let credentialsRemoved = false;
+  try {
+    if (!lease.workerId || !lease.podUid || !lease.leaseId || !lease.key
+      || !Number.isSafeInteger(lease.generation) || lease.generation < 1
+      || !lease.key.context || !lease.key.architecture
+      || !/^sha256:[0-9a-f]{64}$/.test(lease.key.imageDigest)
+      || !/^[0-9a-f]{64}$/.test(lease.key.lockHash)
+      || !/^[0-9a-f]{40}$/.test(lease.sourceSha)) {
+      reason = 'invalid-lease';
+    } else {
+      const stopped = await ops.stopChildProcesses(lease);
+      if (Number.isSafeInteger(stopped.remaining) && stopped.remaining >= 0) {
+        observedResidue += stopped.remaining;
+        processMeasured = true;
+      }
+      if (!Number.isSafeInteger(stopped.remaining) || stopped.remaining !== 0) {
+        reason = 'child-processes-remain';
+      } else {
+        const plan = decidePodReuseCleanup({ base: lease.sourceSha, resetExitCode: 0,
+          cleanExitCode: 0, statusExitCode: 0, statusPorcelain: '' });
+        const reset = await ops.git(lease, plan.resetArgs);
+        if (reset.status !== 0) reason = 'reset-failed';
+        else {
+          const clean = await ops.git(lease, plan.cleanArgs);
+          if (clean.status !== 0) reason = 'clean-failed';
+          else {
+            const status = await ops.git(lease, plan.statusArgs);
+            if (status.status === 0 && typeof status.stdout === 'string') {
+              observedResidue += status.stdout.split('\0').filter(Boolean).length;
+              gitMeasured = true;
+            }
+            const decision = decidePodReuseCleanup({ base: lease.sourceSha,
+              resetExitCode: reset.status, cleanExitCode: clean.status,
+              statusExitCode: status.status, statusPorcelain: status.stdout ?? '' });
+            if (status.status === 0 && typeof status.stdout !== 'string') reason = 'status-unavailable';
+            else if (decision.outcome !== 'reuse') reason = decision.reason ?? 'worktree-not-clean';
+          }
+        }
+      }
+    }
+  } catch (error) {
+    reason = `cleanup-error:${error instanceof Error ? error.message : String(error)}`;
+  }
+  // A failed process or Git check never skips credential revocation.
+  try {
+    const credentials = await ops.removeRunCredentials(lease);
+    credentialsRemoved = credentials.remaining === 0;
+    if (Number.isSafeInteger(credentials.remaining) && credentials.remaining >= 0) {
+      observedResidue += credentials.remaining;
+      credentialsMeasured = true;
+    }
+    if (!credentialsRemoved && !reason) reason = 'credentials-remain';
+  } catch (error) {
+    const credentialReason = `credential-revoke-error:${error instanceof Error ? error.message : String(error)}`;
+    reason = reason ? `${reason};${credentialReason}` : credentialReason;
+  }
+  if (!reason && credentialsRemoved) {
+    try {
+      // Git clean and credential revocation can reveal child processes that appeared after the
+      // pre-cleanup survey. A lease returns clean only when the re-survey immediately before
+      // returnLease also reports zero remaining processes.
+      const resurvey = await ops.stopChildProcesses(lease);
+      if (!Number.isSafeInteger(resurvey.remaining) || resurvey.remaining !== 0) {
+        reason = 'child-processes-resurfaced';
+        if (Number.isSafeInteger(resurvey.remaining) && resurvey.remaining > 0) observedResidue += resurvey.remaining;
+      } else {
+        // Eligibility is observed only after the final process re-survey succeeds.
+        ops.observe('return-decision', { ...facts, outcome: 'eligible' });
+        await ops.returnLease(lease, { clean: true, reason: 'clean', observedResidue: 0 });
+        log('return-decision', { outcome: 'returned' });
+        return { outcome: 'returned', reason: 'clean' };
+      }
+    } catch (error) {
+      reason = `return-or-observation-error:${error instanceof Error ? error.message : String(error)}`;
+    }
+  }
+  log('clean-failed', { reason });
+  try { await ops.quarantine(lease, { clean: false, reason,
+    observedResidue: observedResidue > 0 || (processMeasured && gitMeasured && credentialsMeasured)
+      ? observedResidue : null }); }
+  catch (error) {
+    log('quarantine-failed', { reason, error: error instanceof Error ? error.message : String(error) });
+    throw error;
+  }
+  log('return-decision', { outcome: 'quarantined', reason });
+  return { outcome: 'quarantined', reason };
+}

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

@@ -5,7 +5,7 @@
 // codex·elanous 자격 파일은 이 Job 에 없다. 격리 관문(호스트 넥서스에 닿으면 종료)은 기존 Job 과 같다.
 // 명령 인자는 셸 문자열로 이어붙이지 않고 `"$@"` 로 따로 인용한다.
 
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
@@ -229,12 +229,18 @@ export interface PodCommandJobInput {
   /** W5 — emptyDir{medium: Memory} sizeLimit mounted at {@link POD_TMPFS_MOUNT_PATH} ⊕ `TMPDIR` (release gate shards only). Omitted = image `/tmp`. */
   tmpfsSizeLimit?: string;
   source?: PodSource;
+  /** Verified producer files, delivered into this Job's own source tree. */
+  warmFiles?: readonly string[];
   deadlineSeconds: number;
   runId?: string;
   /** GATE-WARM-BOOT-NO-INIT fallback: the node-side hand-over did not run, so a root init container hands the hostPath dirs to uid 1000. */
   hostDirsInit?: boolean;
 }
 
+function warmSourceName(name: string, launch: string): string {
+  return `${name.slice(0, 50).replace(/-+$/, '')}-${launch}`;
+}
+
 function bashSingleQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -282,6 +288,10 @@ export function podCommandJobManifest(o: PodCommandJobInput): Record<string, unk
     ...(o.clone
       ? ['export GH_TOKEN="$(cat /creds/gh-token)" && gh auth setup-git', podSourceScript(o.source ?? { kind: 'default' }, o.repoUrl)]
       : ['mkdir -p ~/work && cd ~/work']),
+    ...(o.warmFiles?.length ? [
+      `if [ "$(git rev-parse HEAD)" != ${bashSingleQuote(o.source?.kind === 'commit' ? o.source.sha : '')} ]; then echo '[warm-source] commit mismatch'; exit 5; fi`,
+      ...o.warmFiles.map((path, i) => `install -m 644 -D /warm-source/file-${i} ${bashSingleQuote(`./${path}`)} || exit 5\nprintf 'ELANOUS_WARM_SOURCE %s %s %s\\n' ${bashSingleQuote(path)} "$(sha256sum ${bashSingleQuote(`./${path}`)} | cut -d ' ' -f1)" "$(git rev-parse HEAD)"`),
+    ] : []),
     ...(hostDirMounts.length ? [podHostDirsCheckScript(hostDirMounts)] : []),
     ...(bunCache ? [bunCache.shellPrefix] : []),
     `set -- ${quotedArgs}`,
@@ -325,14 +335,16 @@ export function podCommandJobManifest(o: PodCommandJobInput): Record<string, unk
               ...(provenance?.env ?? []),
               ...(tmpfs ? [{ name: 'TMPDIR', value: POD_TMPFS_MOUNT_PATH }] : []),
             ],
-            ...(secretKeys || o.hostMirror || hostDirMounts.length || tmpfs ? { volumeMounts: [
+            ...(secretKeys || o.hostMirror || hostDirMounts.length || tmpfs || o.warmFiles?.length ? { volumeMounts: [
+              ...(o.warmFiles?.length ? [{ name: 'warm-source', mountPath: '/warm-source', readOnly: true }] : []),
               ...(secretKeys ? [{ name: 'creds', mountPath: '/creds', readOnly: true }] : []),
               ...(o.hostMirror ? [{ name: 'host-mirror', mountPath: '/host-mirror', readOnly: true }] : []),
               ...hostDirMounts,
               ...tmpfsMounts,
             ] } : {}),
           }],
-          ...(secretKeys || o.hostMirror || hostDirMounts.length || tmpfs ? { volumes: [
+          ...(secretKeys || o.hostMirror || hostDirMounts.length || tmpfs || o.warmFiles?.length ? { volumes: [
+            ...(o.warmFiles?.length ? [{ name: 'warm-source', configMap: { name: warmSourceName(o.name, o.launch ?? 'source') } }] : []),
             ...(secretKeys ? [{ name: 'creds', secret: { secretName: `${o.name}-creds`, defaultMode: 0o400 } }] : []),
             ...(o.hostMirror ? [{ name: 'host-mirror', hostPath: { path: o.hostMirror, type: 'Directory' } }] : []),
             ...(bunCache ? [bunCache.volume] : []),
@@ -422,6 +434,8 @@ export interface RunPodCommandOptions {
   /** POD7: 호출부가 «네트워크 스킬만 쓰는 명령»이라고 말할 때만 lite 이미지 ⊕ 2Gi. */
   lite?: boolean;
   source?: PodSource;
+  /** Opt-in handoff from an existing producer Pod in the same namespace. */
+  warmProducer?: { pod: string; podUid: string; context: string; image: string; commit: string; files: readonly [string, string] };
   ghToken?: () => string;
   deadlineSeconds?: number;
   namespace?: string;
@@ -553,6 +567,12 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
   const sleep = options.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
   const namespace = options.namespace ?? 'elanous-test';
   const image = options.image ?? podCommandImageFor(skills, options.clone === true, options.lite === true);
+  if (options.warmProducer && (!options.clone || options.source?.kind !== 'commit' || options.source.sha !== options.warmProducer.commit || options.image !== options.warmProducer.image || options.imageCommit !== options.warmProducer.commit)) {
+    throw new Error('pod warm source: consumer image and source commit must match producer');
+  }
+  if (options.warmProducer && (!/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(options.warmProducer.pod) || !options.warmProducer.podUid || typeof options.warmProducer.context !== 'string' || !/^[0-9a-f]{40}$/.test(options.warmProducer.commit) || options.warmProducer.files.length !== 2 || options.warmProducer.files.some((path) => !path || path.startsWith('/') || path.split('/').some((part) => !part || part === '.' || part === '..' || !/^[\w.-]+$/.test(part))))) {
+    throw new Error('pod warm source: invalid producer identity, commit or file path');
+  }
   if (options.shelfImage && (options.image !== options.shelfImage || !options.imageCommit || !options.clone || options.source?.kind !== 'commit' || options.source.sha !== options.imageCommit)) {
     throw new Error('pod shelf: image and source commit must match');
   }
@@ -615,6 +635,9 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
   const kubectlRaw: Kubectl = (args, stdin) => baseKubectl(context ? ['--context', context, ...args] : [...args], stdin);
   const kubectl: Kubectl = (args, stdin) => { ensureLive(); const result = kubectlRaw(args, stdin); ensureLive(); return result; };
   const cleanupSecret = () => { kubectlRaw(['-n', namespace, 'delete', 'secret', '-l', own, '--ignore-not-found']); };
+  const cleanupWarmSource = () => {
+    if (options.warmProducer) kubectlRaw(['-n', namespace, 'delete', 'configmap', '-l', own, '--ignore-not-found']);
+  };
   const artifactRoot = options.artifactsRoot ?? `${effectiveInstanceRoot()}/pod-artifacts`;
   const artifactsDir = `${artifactRoot}/${name}`;
   let jobApplied = false;
@@ -648,7 +671,11 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
       const localSkillsDigest = options.kubectl ? null : image === POD_LITE_IMAGE
         ? podSkillsDigest(POD_NETWORK_SKILLS, resolve(import.meta.dir, '../../../skills')).digest
         : podSkillsDigest(resolvePodSkills(env).skills).digest;
-      if (options.shelfImage) {
+      if (options.warmProducer) {
+        // The leased producer is already running this immutable image on the selected pool.
+        // Do not replace it with the host's independently synchronized commit tag.
+        member = { ...member, imageRef: options.warmProducer.image };
+      } else if (options.shelfImage) {
         const found = (options.shelfLookup ?? registryImageRef)(member, imageCommit);
         if (found !== options.shelfImage) throw new Error(`pod shelf: selected image unavailable on ${member.context}`);
         member = { ...member, imageRef: found };
@@ -671,6 +698,33 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
         .catch((error: unknown) => ({ host: member!.sshHost!, ok: false, ms: 0, detail: String(error).slice(0, 300) })), options.signal);
       log('pod.command-job', 'mirror-seed', { host: member.sshHost, commit: options.source.sha, ok: seed?.ok ?? false, ms: seed?.ms ?? 0, ...(seed?.detail ? { detail: seed.detail } : {}) });
     }
+    // Only a matching, live producer may hand its two source files to this Job; no other Pod's tree is trusted.
+    const warmHashes: Record<string, string> = {};
+    if (options.warmProducer) {
+      const producer = options.warmProducer;
+      if (context !== producer.context || (imageRef && imageRef !== producer.image)) throw new Error('pod warm source: selected pool or image differs from producer');
+      const got = kubectl(['-n', namespace, 'get', 'pod', producer.pod, '-o', 'json']);
+      if (got.status !== 0) throw new Error('pod warm source: producer Pod unavailable');
+      let pod: { metadata?: { name?: string; uid?: string }; spec?: { containers?: Array<{ name?: string; image?: string }> } };
+      try { pod = JSON.parse(got.stdout); } catch { throw new Error('pod warm source: invalid producer Pod'); }
+      if (pod.metadata?.name !== producer.pod || pod.metadata?.uid !== producer.podUid || pod.spec?.containers?.find((container) => container.name === 'child')?.image !== producer.image) {
+        throw new Error('pod warm source: producer Pod identity or image mismatch');
+      }
+      // kubectl exec starts in the image working directory; podSourceScript cloned
+      // `repo` there, then changed directory only in the original Job shell.
+      const head = kubectl(['-n', namespace, 'exec', producer.pod, '-c', 'child', '--', 'bash', '-c', 'git -C repo rev-parse HEAD']);
+      if (head.status !== 0 || head.stdout.trim() !== producer.commit) throw new Error('pod warm source: producer commit mismatch');
+      const binaryData: Record<string, string> = {};
+      for (const [i, path] of producer.files.entries()) {
+        const read = kubectl(['-n', namespace, 'exec', producer.pod, '-c', 'child', '--', 'bash', '-c', `base64 -w0 ${bashSingleQuote(`repo/${path}`)}`]);
+        if (read.status !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(read.stdout.trim())) throw new Error(`pod warm source: producer file unavailable: ${path}`);
+        binaryData[`file-${i}`] = read.stdout.trim();
+        warmHashes[path] = createHash('sha256').update(Buffer.from(binaryData[`file-${i}`]!, 'base64')).digest('hex');
+      }
+      const config = { apiVersion: 'v1', kind: 'ConfigMap', metadata: { name: warmSourceName(name, launch), namespace, labels: { 'elanous.job': name, 'elanous.launch': launch } }, binaryData };
+      const applied = kubectl(['apply', '-f', '-'], JSON.stringify(config));
+      if (applied.status !== 0) throw new Error(applied.stderr.trim() || 'pod warm source: ConfigMap apply failed');
+    }
     // GATE-WARM-BOOT-NO-INIT (10-15): the hostPath dirs the uid-1000 child writes are handed over on the node itself, once per
     // member·paths in this process (no init container). Best effort: a failure only logs; the child then falls back.
     const hostDirPaths = [...(bunCache ? [bunCache] : []), ...(installSlots ? [installSlots] : [])];
@@ -701,7 +755,7 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
       provenance: options.provenance, provenanceGate: options.provenanceGate,
       ...(imageRef ? { imagePullPolicy: 'IfNotPresent' as const } : {}),
       repoUrl, command, skills, ...(options.returnLogs ? { returnLogs: true } : {}), ...(llm ? { llm } : {}), ...(options.clone ? { clone: true } : {}),
-      ...(options.source ? { source: options.source } : {}), ...(hostMirror ? { hostMirror } : {}), ...(bunCache ? { bunCache } : {}), ...(installSlots ? { installSlots } : {}), ...(memoryLimit ? { memoryLimit } : {}), ...(options.cpu ? { cpu: options.cpu } : {}), ...(options.tmpfsSizeLimit ? { tmpfsSizeLimit: options.tmpfsSizeLimit } : {}), deadlineSeconds,
+      ...(options.source ? { source: options.source } : {}), ...(options.warmProducer ? { warmFiles: options.warmProducer.files } : {}), ...(hostMirror ? { hostMirror } : {}), ...(bunCache ? { bunCache } : {}), ...(installSlots ? { installSlots } : {}), ...(memoryLimit ? { memoryLimit } : {}), ...(options.cpu ? { cpu: options.cpu } : {}), ...(options.tmpfsSizeLimit ? { tmpfsSizeLimit: options.tmpfsSizeLimit } : {}), deadlineSeconds,
       ...(options.runId ? { runId: options.runId } : {}),
       ...(hostDirsInit ? { hostDirsInit: true } : {}),
     });
@@ -718,6 +772,12 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
     let markerRc: number | null = null;
     const appliedAt = Date.now();
     for (;;) {
+      // PRLAND-SHADOW-HOST-TIMEOUT: a Pending Pod poll never ends by itself — the host wall-clock deadline ends the
+      // loop here (before another status read) and leaves exactly one timeout record (deadline time ⊕ final state).
+      if (options.hostDeadlineAtMs !== undefined && nowMs() >= options.hostDeadlineAtMs) {
+        log('pod.command', 'host-timeout', { job: name, context, hostDeadlineAtMs: options.hostDeadlineAtMs, nowMs: nowMs(), finalState: 'timeout', waitedMs: nowMs() - appliedAt });
+        throw new Error('pod shadow: host timeout');
+      }
       ensureLive();
       const got = kubectl(['-n', namespace, 'get', 'job', name, '-o', 'jsonpath={.status.conditions[*].type}']);
       const finished = jobFinished(got.stdout);
@@ -744,6 +804,18 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
       await awaitPodCommandAbort(sleep(options.pollMs ?? 15_000), options.signal);
     }
     ensureLive();
+    if (options.warmProducer) {
+      const found = kubectl(['-n', namespace, 'get', 'pods', '-l', `job-name=${name}`, '-o', 'json']);
+      let pods: { items?: Array<{ metadata?: { name?: string }; spec?: { containers?: Array<{ name?: string; image?: string }> } }> };
+      try { pods = JSON.parse(found.stdout); } catch { throw new Error('pod warm source: consumer Pod unavailable'); }
+      // A retried Job can leave an older Pod in the list. Never attribute the
+      // warm-source proof to an arbitrary Pod when the consumer is ambiguous.
+      const consumer = pods.items?.length === 1 ? pods.items[0] : undefined;
+      if (found.status !== 0 || !consumer?.metadata?.name || consumer.metadata.name === options.warmProducer.pod || consumer.spec?.containers?.find((container) => container.name === 'child')?.image !== (imageRef ?? image)) {
+        throw new Error('pod warm source: consumer Pod identity or image mismatch');
+      }
+      log('pod.command-job', 'warm-source-linked', { producerPod: options.warmProducer.pod, consumerPod: consumer.metadata.name, image: imageRef ?? image, commit: options.warmProducer.commit, files: [...options.warmProducer.files] });
+    }
     let logsResult = kubectl(['-n', namespace, 'logs', `job/${name}`, '-c', 'child']);
     // Marker path returns before the Job condition — a full-log read can hit the same transient window the tail read
     // already survived (container log rotation · API hiccup). Retry it a little before calling the artifacts lost.
@@ -761,6 +833,13 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
     }
     const logsFailed = logsResult.status !== 0;
     const logs = logsFailed ? '' : splitPodResultMarker(logsResult.stdout, launch).logs;
+    if (options.warmProducer) {
+      if (logsFailed) throw new Error(`pod warm source: consumer logs unavailable: ${logsResult.stderr.trim() || logsResult.status}`);
+      for (const path of options.warmProducer.files) {
+        const marker = `ELANOUS_WARM_SOURCE ${path} ${warmHashes[path]} ${options.warmProducer.commit}`;
+        if (logs.split(/\r?\n/).filter((line) => line === marker).length !== 1) throw new Error(`pod warm source: consumer file or commit mismatch: ${path}`);
+      }
+    }
     const artifactDir = artifactRoot;
     let artifacts: PodArtifactCollection;
     if (logsFailed) {
@@ -796,6 +875,7 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
     // Marker path: the rc the child printed (the Pod's terminated state may lag like the condition). Condition path: unchanged.
     const exitCode = markerRc ?? exitCodeFromPod(kubectl, namespace, name, state);
     cleanupSecret();
+    cleanupWarmSource();
     log('pod.command', 'job-finished', {
       job: name,
       exitCode,
@@ -815,6 +895,7 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
       catch { /* preserve the cancellation reason */ }
     }
     cleanupSecret();
+    cleanupWarmSource();
     throw err;
   } finally {
     if (member && pool) pool.release(member);