elanous 0.2.32 → 0.2.35

package/src/task-orchestrator/generator-prompt.ts

@@ -10,10 +10,13 @@
  */
 import type { DecomposeInput } from './generator.js';
 import type { ProposalValidationError } from './generator-schema.js';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
 
 export type DecomposePromptProfile = 'goal-author-coarse';
 
-export const GOAL_AUTHOR_COARSE_MAX_SLICES = 6;
+/** TaskGenerator's safety ceiling, not an authoring target; goal-author splits by slice size. */
+export const GOAL_AUTHOR_SIZE_SAFETY_MAX_SLICES = 15;
 
 export interface BuildPromptOptions {
   maxTasks: number;
@@ -39,6 +42,35 @@ const CODING_GOAL_KINDS: ReadonlySet<string> = new Set([
   'agentic',
 ]);
 
+/** Read the existing device sources at authoring time; the LLM has no file tools in this phase. */
+let deviceInventoryCache: string[] | undefined;
+function deviceInventory(): string[] {
+  if (deviceInventoryCache) return deviceInventoryCache;
+  const root = resolve(import.meta.dir, '../..');
+  const fallback = ['- Device inventory unavailable in this installation; verify a named device before claiming it exists.'];
+  if (!existsSync(resolve(root, 'src/ux-sim'))) return deviceInventoryCache = fallback;
+  try {
+    const files = readdirSync(resolve(root, 'src/ux-sim'))
+      .filter((name) => name.endsWith('.ts') && !name.endsWith('.test.ts')).sort();
+    const monkey = readFileSync(resolve(root, 'src/ux-sim/event-monkey.ts'), 'utf8');
+    const kinds = monkey.match(/export const EVENT_MONKEY_KINDS = \[([\s\S]*?)\] as const;/)?.[1]
+      ?.match(/'[^']+'/g)?.map((kind) => kind.slice(1, -1)) ?? [];
+    let rows: string[] = [];
+    try {
+      const manual = readFileSync(resolve(root, 'docs/manual/MANUAL-ux-simulation-devices-2026-08-23.md'), 'utf8');
+      rows = manual.split('\n').filter((line) => line.startsWith('|') && line.includes('`src/ux-sim/'));
+    } catch { /* Published packages omit docs/manual; source catalog still applies. */ }
+    return deviceInventoryCache = [
+      `- src/ux-sim files: ${files.join(', ')}`,
+      `- event-monkey kinds: ${kinds.join(', ')}`,
+      ...(rows.length ? [] : ['- manual §1 table unavailable in this installation; use the source files and event kinds above.']),
+      ...rows.map((row) => `- manual §1: ${row.replace(/\s*\|\s*/g, ' · ').slice(0, 500)}`),
+    ];
+  } catch {
+    return deviceInventoryCache = fallback;
+  }
+}
+
 export function buildDecomposePrompt(
   input: DecomposeInput,
   opts: BuildPromptOptions
@@ -53,7 +85,7 @@ export function buildDecomposePrompt(
   lines.push(
     'You are the monad-agent Task Orchestrator decomposition planner.',
     isGoalAuthorCoarse
-      ? `Break the objective into 1-${GOAL_AUTHOR_COARSE_MAX_SLICES} larger, concrete implementation slices.`
+      ? 'Break the objective into implementation slices that a low or medium tier model can finish. Split by slice size, not a target number of slices; the task count limit is only a safety ceiling.'
       : 'Break the objective into 3-7 concrete, single-responsibility tasks.',
     '',
     '## Output (STRICT JSON)',
@@ -119,9 +151,10 @@ export function buildDecomposePrompt(
     '- ★ Complete dependsOn contracts: if a phase CONSUMES another phase\'s output, that producing phase MUST be in this phase\'s `dependsOn` (by index). A consumer with no dependsOn on its producer looks like an ungrounded/orphan dependency to the critique. Trace every consumed symbol to either grounding (exists) or a dependsOn phase (produced this mission).',
     ...(isGoalAuthorCoarse
       ? [
-        '- Coarse scope: permit a larger implementation slice when its related definition, tests, and runtime wiring are necessary for an executable end-to-end path; do not split those related concerns into sibling tasks.',
-        '- One implementation run can complete a large multi-file slice, including its tests, so do not split work that fits in one run.',
-        '- Keep a coarse slice focused on one executable outcome, but it may combine related implementation concerns and exceed the default small-scope LOC guidance.',
+        '- Goal-author size: each slice should touch at most 4 target files, change at most 2 behaviors, and create at most 2 files. Count tests and runtime wiring among target files.',
+        '- Prefer low tier (at most 2 files, 1 behavior, 1 new file), then medium tier (at most 4 files, 2 behaviors, 2 new files). Do not make a high tier slice merely to reduce the number of slices.',
+        '- Keep the executable dependency path through dependsOn; split oversized work into dependent slices rather than hiding multiple behaviors in one title.',
+        '- A high tier slice is allowed only when it cannot be split further without breaking an inseparable operation. State its unavoidable reason in the rationale.',
       ]
       : [
         '- Small scope: keep each task ≈≤250 LOC of change. If a step is bigger, split it into sibling tasks or defer to a recursive decompose (depth) rather than one giant task.',
@@ -155,13 +188,29 @@ export function buildDecomposePrompt(
   if (isGoalAuthorCoarse) {
     lines.push(
       '',
-      '## Goal-author coarse slicing (follow strictly)',
-      '- Prefer fewer, larger implementation slices over small single-concern tasks; use the task budget as a ceiling, not a target.',
-      '- Keep related definition, tests, and runtime wiring together when they are required to make one implementation slice executable end-to-end.',
-      '- A slice may cover multiple related concerns and a larger change scope when splitting them would leave a definition unwired or an execution path incomplete.',
-      '- Every slice title MUST name at least one actual file path or function name because only the title is passed to the next stage; coarse slices must remain grounded and verifiable.',
+      '## Goal-author size-bounded slicing (follow strictly)',
+      '- Use the task budget as a safety ceiling, not a target. Add dependent slices whenever one slice would exceed medium size.',
+      '- Give each slice an executable outcome with tests or runtime wiring inside its size limit; place further wiring in a dependent slice.',
+      '- Every slice title MUST name at least one actual file path or function name because only the title is passed to the next stage; slices must remain grounded and verifiable.',
+      '- Every task JSON must include files, behaviours, newFiles and tier. Example: {"index":0,"title":"대상 경로: src/a.ts · 동작: 연결","files":1,"behaviours":1,"newFiles":0,"tier":"low","surface":{"kind":"llm-direct","prompt":"wire src/a.ts"}}.',
+      '- Only the title reaches the sizing fallback: start it with "대상 경로:" and name all touched paths; add one "동작:" clause per changed behavior and "신규 경로:" for each new file. Keep the title within 80 characters by splitting oversized work.',
       '- Fold non-code investigation or design into the implementation slice that needs it; do not emit it as a standalone slice.',
-      '- Use dependsOn only for genuine ordering between independently completable slices; do not split related definition and runtime wiring merely to create sibling tasks.',
+      '- Use dependsOn for genuine ordering between independently completable slices, including definition before dependent runtime wiring.',
+    );
+    // ── 장치 우선 분해 (DEVICE-FIRST-AUTHORING · 대표 10-21 18:1x 골 저작 지침) ──
+    // 골 저작의 검증 계획(TDD) 절이 무대·층을 고를 때 그 시험에 필요한 mock 장치·주입 사건 정의의
+    // 존재를 먼저 확인하게 한다. 장치가 없으면 «실물 없음»으로 초록이 막히므로 첫 조각이 장치 조각이 된다.
+    lines.push(
+      '',
+      '## Device-first decomposition (DEVICE-FIRST-AUTHORING — follow strictly)',
+      '### Existing device inventory (read from this checkout; use these names before proposing a new device)',
+      ...deviceInventory(),
+      '- The objective\'s verification plan (검증 계획/TDD) section picks a stage and ladder tier (무대·층) — e.g. a `src/ux-sim/*` stage at L2 (fake-llm·fake-bin·fake-clock). BEFORE writing slices, CHECK whether the mock device or injected event definition that this verification plan needs ALREADY EXISTS: look in `src/ux-sim/*`, the §1 device table of `docs/manual/MANUAL-ux-simulation-devices-2026-08-23.md`, and the event-monkey event kinds.',
+      '- Two branches — exactly one applies per needed device:',
+      '  - Device EXISTS: its name MUST go into the verification plan wording — the slice that tests the feature carries the device\'s exact name (device file / §1 table row / event kind) in its acceptance criteria and reuses the device; never re-create it.',
+      '  - Device MISSING: the FIRST slice MUST be a device slice that develops that device feature first — the mock device or injected event definition under `src/ux-sim/*` — and every slice that tests the feature depends on it (구현할 때 해당 시험 mock 장치나 이벤트 정의가 있나 확인하고, 없으면 그 장치 피처를 먼저 개발).',
+      '- Do NOT create the device itself here beyond emitting that device slice (장치 자체는 만들지 않는다 — 조각으로 내보낼 뿐); consumer slices reference it only via dependsOn.',
+      '- Device slices obey the same size bounds and acceptance bar as every other slice — the size rules (TIER-SIZED-DECOMPOSE) and the green-judgment rules are UNCHANGED.',
     );
   }
 

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

@@ -17,6 +17,17 @@ export type PodProviderPlan =
   | { provider: 'grok'; excluded: PodAccountPlan['excluded']; grokSubscriptionEligible: boolean }
   | { provider: null; reasons: string[]; grokSubscriptionEligible: boolean };
 
+/** Effective cap used by the Pod broker; callers carrying an owner-approved selection must carry this same value. */
+export function podAccountThresholdPercent(name: string, options: {
+  excludeAt?: number;
+  thresholdPercentByAccount?: Readonly<Record<string, unknown>>;
+} = {}): number {
+  return codexAccountThresholdPercent(name, {
+    thresholdPercent: options.excludeAt ?? POD_ACCOUNT_EXCLUDE_AT_PERCENT,
+    thresholdPercentByAccount: options.thresholdPercentByAccount,
+  });
+}
+
 /** Pod 의 codex → grok 선택. 자격 종류는 과금 동의와 별도로 판단한다. */
 export function planPodProvider(input: {
   codexCandidates: readonly RotationCandidate[];
@@ -85,9 +96,7 @@ export function planPodAccounts(
   const known: RotationCandidate[] = [];
   const unknown: RotationCandidate[] = [];
   for (const c of candidates) {
-    const threshold = typeof options === 'number'
-      ? excludeAt
-      : codexAccountThresholdPercent(c.name, { thresholdPercent: excludeAt, thresholdPercentByAccount });
+    const threshold = typeof options === 'number' ? excludeAt : podAccountThresholdPercent(c.name, { excludeAt, thresholdPercentByAccount });
     if (c.reached === true) { excluded.push({ name: c.name, why: 'quota reached' }); continue; }
     if (c.usedPercent !== undefined && c.usedPercent >= threshold) { excluded.push({ name: c.name, why: `used ${c.usedPercent}% ≥ ${threshold}%` }); continue; }
     (c.usedPercent === undefined ? unknown : known).push(c);
@@ -113,6 +122,66 @@ export function planPodAccounts(
   return { usable, excluded };
 }
 
+/** HQ selects one owner account before remote-parent launch; keep the configured rotation order. */
+export function planOwnerCodexMirrorCandidates(candidates: readonly RotationCandidate[], options: {
+  accountOrder: readonly string[];
+  thresholdPercentByAccount?: Readonly<Record<string, unknown>>;
+}): RotationCandidate[] {
+  const usable = new Set(planPodAccounts(candidates, { thresholdPercentByAccount: options.thresholdPercentByAccount }).usable);
+  const rank = (name: string): number => {
+    const index = options.accountOrder.indexOf(name);
+    return index < 0 ? options.accountOrder.length : index;
+  };
+  return candidates.map((candidate, index) => ({ candidate, index })).filter(({ candidate }) => usable.has(candidate.name))
+    .sort((a, b) => rank(a.candidate.name) - rank(b.candidate.name) || a.index - b.index)
+    .map(({ candidate }) => candidate);
+}
+
+/** Remote owner-mirror runs may plan against exactly the account HQ selected and its measured usage. */
+export function ownerCodexMirrorCandidate(candidates: readonly RotationCandidate[], account: string, usedPercent?: number): RotationCandidate[] {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(account)) return [];
+  return candidates.filter((candidate) => candidate.name === account).map((candidate) => {
+    const ownerCandidate = { ...candidate };
+    delete ownerCandidate.usedPercent;
+    ownerCandidate.reached = false;
+    const measured = usedPercent !== undefined && Number.isFinite(usedPercent) ? usedPercent : undefined;
+    return { ...ownerCandidate, reached: false, ...(measured !== undefined ? { usedPercent: measured } : {}) };
+  });
+}
+
+export interface OwnerCodexMirrorAccount { account: string; usedPercent: number | null; thresholdPercent: number; expiresAt: number }
+
+/** The remote may rotate only across the accounts HQ actually installed in this launch snapshot. */
+export function parseOwnerCodexMirrorAccounts(raw: string): OwnerCodexMirrorAccount[] {
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw); } catch { throw new Error('HQ Codex 미러 계정 목록이 잘못됐다'); }
+  if (!Array.isArray(parsed) || parsed.length === 0 || parsed.length > 16) throw new Error('HQ Codex 미러 계정 목록이 잘못됐다');
+  const seen = new Set<string>();
+  return parsed.map((item: unknown) => {
+    if (!item || typeof item !== 'object') throw new Error('HQ Codex 미러 계정 항목이 잘못됐다');
+    const value = item as Record<string, unknown>;
+    const { account, usedPercent, thresholdPercent, expiresAt } = value;
+    if (typeof account !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(account) || seen.has(account)
+      || (usedPercent !== null && (typeof usedPercent !== 'number' || !Number.isFinite(usedPercent) || usedPercent < 0 || usedPercent > 100))
+      || typeof thresholdPercent !== 'number' || !Number.isFinite(thresholdPercent) || thresholdPercent <= 0 || thresholdPercent > 100
+      || typeof expiresAt !== 'number' || !Number.isFinite(expiresAt) || expiresAt <= 0)
+      throw new Error('HQ Codex 미러 계정 항목이 잘못됐다');
+    seen.add(account);
+    return { account, usedPercent: usedPercent as number | null, thresholdPercent, expiresAt };
+  });
+}
+
+/** Do not plan a Pod against an access token that might expire while it starts and runs. */
+export function freshOwnerCodexMirrorAccounts(accounts: readonly OwnerCodexMirrorAccount[], now = Date.now()): OwnerCodexMirrorAccount[] {
+  return accounts.filter(({ expiresAt }) => expiresAt > now + 3 * 60 * 60 * 1000);
+}
+
+export function selectOwnerCodexMirrorCandidates(candidates: readonly RotationCandidate[], accounts: readonly OwnerCodexMirrorAccount[]): RotationCandidate[] {
+  const selected = accounts.flatMap(({ account, usedPercent }) => ownerCodexMirrorCandidate(candidates, account, usedPercent ?? undefined));
+  if (selected.length !== accounts.length) throw new Error('HQ Codex 미러 계정 일부가 원격 auth-store 후보에 없다');
+  return selected;
+}
+
 /** Job 마다 다음 계정 — 잔량 순으로 돌려 가며. 쓸 계정이 없으면 만들 때 이유를 대고 던진다. */
 export function makePodAccountBroker(plan: PodAccountPlan): () => string {
   if (plan.usable.length === 0) {

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

@@ -9,7 +9,7 @@
  */
 // BEDROCK-PROVIDER ② (0.2.24) — bedrock 은 «이름 있는 AWS Secret» 이 클러스터에 있을 때만 뜬다(pod-bedrock-child.ts · 발사 전 거부).
 // ZAI-POD-CHILD (0.2.24) — glm 은 Z.ai GLM Coding Plan(정액 구독) · «이름 있는 ZAI Secret» 이 클러스터에 있을 때만 뜬다(pod-zai-child.ts · 발사 전 거부 · 동시 상한 넘치면 정책대로).
-export const POD_CHILD_PROVIDERS = ['openai-codex', 'grok', 'openrouter', 'anthropic', 'bedrock', 'glm'] as const;
+export const POD_CHILD_PROVIDERS = ['openai-codex', 'grok', 'openrouter', 'opengateway', 'anthropic', 'bedrock', 'glm'] as const;
 export type PodChildProvider = typeof POD_CHILD_PROVIDERS[number];
 
 /** 사람이 쓰는 별칭 → 정식 이름. */

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

@@ -17,9 +17,10 @@ import { getDefaultLogStore, type LogStore } from '../../mss/logging/log-store.j
 import { podBunCacheVolume } from './pod-bun-cache.js';
 import { POD_JOB_TTL_AFTER_FINISHED_SECONDS } from './pod-lease.js';
 import { podHostDirsCheckScript, podInstallSlotsVolume, prepareHostDirsOnce, type HostDirsPrepResult, podHostDirsScript } from './pod-install-slots.js';
-import { type PodPoolMember, PodPoolScheduler, resolvePodPoolSpec, parsePodPool, checkPodPool, syncPoolImages, type PoolKubectl } from './pod-pool.js';
+import { type PodPoolMember, PodPoolScheduler, resolvePodPoolSpec, parsePodPool, checkPodPool, syncPoolImages, registryImageRef, type PoolKubectl } from './pod-pool.js';
 import { podSkillsDigest, readSkillEnvFiles, resolvePodSkills } from './pod-skills.js';
 import { podSourceScript, type PodSource } from './pod-source-receive.js';
+import { podProvenanceMetadata, type PodProvenance } from './pod-provenance.js';
 import { seedMirrorOnce, type MirrorSeedResult } from './pod-mirror-seed.js';
 import {
   POD_CHILD_REQUESTS,
@@ -201,6 +202,8 @@ if [ -d "$HOME/outbox" ]; then
 fi`;
 
 export interface PodCommandJobInput {
+  provenance?: Partial<PodProvenance>;
+  provenanceGate?: boolean;
   /** POD1 — this launch's own label; cleanup selects by it, never by name alone. */
   launch?: string;
   name: string;
@@ -236,8 +239,21 @@ function bashSingleQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+function assertGateProvenanceException(gate: boolean | undefined, provenance: Partial<PodProvenance> | undefined,
+  clone: boolean | undefined, source: PodSource | undefined): void {
+  if (!gate) return;
+  const shardEntrance = process.env.ELANOUS_RELEASE_ENTRANCE?.trim() || 'release-run';
+  const shard = provenance?.kind === 'gate-shard' && provenance.entrance === shardEntrance;
+  const recheck = provenance?.kind === 'gate-recheck' && provenance.entrance === 'release-recheck';
+  if (!(shard || recheck) || clone !== true || source?.kind !== 'commit') {
+    throw new Error('pod provenance gate exception requires a release shard/recheck commit Job');
+  }
+}
+
 /** 명령 Job 매니페스트. `skills`·`llm` 을 안 주면 Secret 키를 하나도 참조하지 않는다. */
 export function podCommandJobManifest(o: PodCommandJobInput): Record<string, unknown> {
+  assertGateProvenanceException(o.provenanceGate, o.provenance, o.clone, o.source);
+  const provenance = podProvenanceMetadata(o.provenance, o.provenanceGate);
   const skillNames = [...new Set(o.skills.map((s) => s.trim()).filter(Boolean))];
   for (const name of skillNames) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(name)) throw new Error(`pod command skill name rejected: ${name}`);
@@ -284,13 +300,13 @@ export function podCommandJobManifest(o: PodCommandJobInput): Record<string, unk
   return {
     apiVersion: 'batch/v1',
     kind: 'Job',
-    metadata: { name: o.name, namespace: o.namespace, labels: { 'elanous.substrate': 'pod', 'elanous.job': o.name, 'elanous.kind': 'command', ...(o.launch ? { 'elanous.launch': o.launch } : {}) } },
+    metadata: { name: o.name, namespace: o.namespace, labels: { 'elanous.substrate': 'pod', 'elanous.job': o.name, 'elanous.kind': 'command', ...(o.launch ? { 'elanous.launch': o.launch } : {}), ...provenance?.labels }, ...(provenance ? { annotations: provenance.annotations } : {}) },
     spec: {
       backoffLimit: 0,
       ttlSecondsAfterFinished: POD_JOB_TTL_AFTER_FINISHED_SECONDS,
       activeDeadlineSeconds: o.deadlineSeconds,
       template: {
-        metadata: { labels: { 'elanous.job': o.name, 'elanous.kind': 'command', ...(o.launch ? { 'elanous.launch': o.launch } : {}) } },
+        metadata: { labels: { 'elanous.job': o.name, 'elanous.kind': 'command', ...(o.launch ? { 'elanous.launch': o.launch } : {}), ...provenance?.labels }, ...(provenance ? { annotations: provenance.annotations } : {}) },
         spec: {
           restartPolicy: 'Never',
           securityContext: { runAsUser: 1000, fsGroup: 1000 },
@@ -306,6 +322,7 @@ export function podCommandJobManifest(o: PodCommandJobInput): Record<string, unk
               ...(o.runId ? [{ name: 'ELANOUS_RUN_ID', value: o.runId }] : []),
               { name: 'ELANOUS_SUBSTRATE', value: 'pod' },
               { name: 'ELANOUS_POD_NAME', valueFrom: { fieldRef: { fieldPath: 'metadata.name' } } },
+              ...(provenance?.env ?? []),
               ...(tmpfs ? [{ name: 'TMPDIR', value: POD_TMPFS_MOUNT_PATH }] : []),
             ],
             ...(secretKeys || o.hostMirror || hostDirMounts.length || tmpfs ? { volumeMounts: [
@@ -382,6 +399,9 @@ export interface PodCommandResult {
 }
 
 export interface RunPodCommandOptions {
+  provenance?: Partial<PodProvenance>;
+  /** Release gate keeps availability: missing required identity becomes unknown and emits a warning. */
+  provenanceGate?: boolean;
   command: readonly string[];
   /** pod run opt-in; other runPodCommand callers keep their existing Job script. */
   returnLogs?: boolean;
@@ -434,6 +454,9 @@ export interface RunPodCommandOptions {
   checkPool?: typeof checkPodPool;
   syncImages?: typeof syncPoolImages;
   imageCommit?: string | null;
+  /** Shelf: require this exact registry tag; never fall back to a mutable local image. */
+  shelfImage?: string;
+  shelfLookup?: typeof registryImageRef;
   readSkillEnv?: (skills: readonly string[]) => Record<string, string>;
   grokCredentials?: () => { grokAuth?: string; grokApiKey?: string; ghToken: string };
   artifactsRoot?: string;
@@ -510,6 +533,9 @@ function awaitPodCommandAbort<T>(pending: Promise<T>, signal?: AbortSignal): Pro
 
 /** 풀 자리 · 이미지 판 · Job 적용 · 완료 대기 · 산출 회수 · Secret 정리. */
 export async function runPodCommand(options: RunPodCommandOptions): Promise<PodCommandResult> {
+  // A non-gate Job must have its owner before a pool lease, Secret, or Job is created.
+  assertGateProvenanceException(options.provenanceGate, options.provenance, options.clone, options.source);
+  const provenance = podProvenanceMetadata(options.provenance, options.provenanceGate);
   const nowMs = options.nowMs ?? Date.now;
   const ensureLive = () => {
     if (options.signal?.aborted) throw options.signal.reason ?? new Error('pod command aborted');
@@ -521,11 +547,15 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
   const skills = [...new Set((options.skills ?? []).map((s) => s.trim()).filter(Boolean))];
   const llm = options.llm;
   const log = options.log ?? ((c, e, d) => debug.log(c, e, d));
+  if (provenance.missing.length) log('pod.provenance', 'missing-gate-fields', { missing: provenance.missing });
   const baseKubectl = options.kubectl ?? ((args: readonly string[], input?: string) =>
     defaultKubectl(args, input, options.signal ? POD_COMMAND_CANCEL_KUBECTL_TIMEOUT_MS : undefined));
   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.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');
+  }
   const memoryLimit = options.memoryLimit ?? (image === POD_LITE_IMAGE ? POD_LITE_MEMORY_LIMIT : undefined);
   const repoUrl = options.repoUrl ?? 'https://github.com/ElanvitalAI/elanous';
   const deadlineSeconds = options.deadlineSeconds ?? POD_COMMAND_DEADLINE_SECONDS;
@@ -579,6 +609,7 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
     if (member && pool) pool.release(member);
     ensureLive();
   }
+  if (options.shelfImage && !member) throw new Error('pod shelf: remote pool member required');
   const currentContext = member || options.kubectl ? null : baseKubectl(['config', 'current-context']);
   const context = member?.context ?? (currentContext?.status === 0 ? currentContext.stdout.trim() : '');
   const kubectlRaw: Kubectl = (args, stdin) => baseKubectl(context ? ['--context', context, ...args] : [...args], stdin);
@@ -592,7 +623,8 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
     if (!context && !options.kubectl) throw new Error('pod command: kubectl context 를 확인할 수 없다');
     let grokAuth: string | undefined;
     if (llm === 'grok') {
-      const creds = (options.grokCredentials ?? (() => hostGrokCredentials({ env, apiKeyOptIn: false })))();
+      // POD-GROK-VALIDITY-FIT — this Job's deadline is not fitted to the token, so the copy must outlive the whole Job.
+      const creds = (options.grokCredentials ?? (() => hostGrokCredentials({ env, apiKeyOptIn: false, minValidityMs: deadlineSeconds * 1000 })))();
       if (!creds.grokAuth) throw new Error('grok: 구독 자격 없음 · API 키 opt-in 꺼짐 또는 키 없음');
       let parsed: unknown;
       try { parsed = JSON.parse(creds.grokAuth); } catch { throw new Error('grok: Pod 구독 자격 JSON 이 아니다'); }
@@ -616,10 +648,16 @@ 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;
-      const syncs = await awaitPodCommandAbort((options.syncImages ?? syncPoolImages)([member], image, imageCommit, { localSkillsDigest }), options.signal);
-      const synced = syncs.get(member.context);
-      if (synced && !synced.ok) throw new Error(`pod command: 이미지 판을 못 맞췄다: ${synced.detail}`);
-      if (synced?.imageRef) member = { ...member, imageRef: synced.imageRef };
+      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 };
+      } else {
+        const syncs = await awaitPodCommandAbort((options.syncImages ?? syncPoolImages)([member], image, imageCommit, { localSkillsDigest }), options.signal);
+        const synced = syncs.get(member.context);
+        if (synced && !synced.ok) throw new Error(`pod command: 이미지 판을 못 맞췄다: ${synced.detail}`);
+        if (synced?.imageRef) member = { ...member, imageRef: synced.imageRef };
+      }
     }
     const imageRef = member?.imageRef;
     if (!imageRef) log('pod.command-job', 'image-fallback-local', { reason: !member ? 'no-pool-member' : !imageCommit ? 'image-commit-unavailable' : 'registry-tag-unavailable' });
@@ -660,6 +698,7 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
     }
     const manifest = podCommandJobManifest({
       name, namespace, launch, image: imageRef ?? image,
+      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,

package/src/task-orchestrator/surfaces/pod-image-source.ts

@@ -14,9 +14,12 @@
  *   이미지는 표준판(elanous-harness)만 — 이 발사 경로는 lite 를 쓰지 않는다.
  */
 import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { SPAWN_SYNC_MAX_BUFFER } from '../../util/spawn-sync-output.js';
 import { debug } from '../../debug/log.js';
-import { memberHasRegistry, registryImageRef, type RemoteRun } from './pod-pool.js';
+import { memberHasRegistry, registryImageRef, syncPoolImages, parsePodPool, type PodPoolMember, type RemoteRun } from './pod-pool.js';
 
 const POD_IMAGE = 'elanous-harness';
 
@@ -59,6 +62,91 @@ export function resolvePodImageSource(
   return { kind: 'pinned', ref: podImageRef(registry, commit), commit, registry };
 }
 
+export interface PodShelfImage { readonly commit: string; readonly image: string; readonly action: 'fresh' | 'built' }
+
+export function resolvePodShelfRef(ref: string, cwd = process.cwd(), exec = spawnSync): string {
+  const requested = ref.trim();
+  if (!requested || requested.startsWith('-') || /[\s\x00-\x1f]/u.test(requested)) throw new Error('pod shelf: invalid ref');
+  const spec = /^#?(\d+)$/u.exec(requested);
+  if (spec) {
+    const pr = exec('gh', ['pr', 'view', spec[1]!, '--json', 'headRefOid', '--jq', '.headRefOid'], { cwd, encoding: 'utf8', timeout: 30_000 });
+    const sha = String(pr.stdout ?? '').trim().toLowerCase();
+    if (pr.status !== 0 || !/^[0-9a-f]{40}$/u.test(sha)) throw new Error(`pod shelf: PR head unavailable: ${requested}`);
+    return sha;
+  }
+  const git = exec('git', ['rev-parse', '--verify', `${requested}^{commit}`], { cwd, encoding: 'utf8', timeout: 30_000 });
+  const sha = String(git.stdout ?? '').trim().toLowerCase();
+  if (git.status !== 0 || !/^[0-9a-f]{40}$/u.test(sha)) throw new Error(`pod shelf: ref unavailable: ${requested}`);
+  return sha;
+}
+
+/** Checkout only the requested commit; syncPoolImages retains its per-host build lock and SHA12 registry check. */
+export async function putPodShelfImage(ref: string, pool: string, deps: {
+  resolve?: (ref: string) => string;
+  sync?: typeof syncPoolImages;
+  checkout?: (commit: string, dir: string) => void;
+  tempDir?: () => string;
+  remove?: (dir: string) => void;
+  hasRegistry?: (member: PodPoolMember) => boolean;
+} = {}): Promise<PodShelfImage> {
+  const members = parsePodPool(pool);
+  if (members.length !== 1 || !members[0]!.sshHost) throw new Error('pod shelf: one remote registry pool member is required');
+  const member: PodPoolMember = members[0]!;
+  if (!(deps.hasRegistry ?? memberHasRegistry)(member)) throw new Error('pod shelf: remote registry unavailable');
+  const commit = (deps.resolve ?? resolvePodShelfRef)(ref);
+  if (!/^[0-9a-f]{40}$/u.test(commit)) throw new Error('pod shelf: full commit required');
+  const registry = member.registry ?? podImageRegistry();
+  const image = podImageRef(registry, commit);
+  if (!deps.sync && registryImageRef(member, commit) === image) return { commit, image, action: 'fresh' };
+  const dir = (deps.tempDir ?? (() => mkdtempSync(join(tmpdir(), 'pod-shelf-'))))();
+  try {
+    if (deps.checkout) deps.checkout(commit, dir);
+    else {
+      const clone = spawnSync('git', ['clone', '-q', '--no-checkout', process.cwd(), dir], { encoding: 'utf8', timeout: 120_000, maxBuffer: SPAWN_SYNC_MAX_BUFFER });
+      if (clone.status !== 0) throw new Error(`pod shelf: clone failed: ${clone.stderr}`);
+      const fetch = spawnSync('git', ['-C', dir, 'fetch', '-q', 'origin', commit], { encoding: 'utf8', timeout: 120_000, maxBuffer: SPAWN_SYNC_MAX_BUFFER });
+      if (fetch.status !== 0) {
+        const remote = spawnSync('git', ['remote', 'get-url', 'origin'], { encoding: 'utf8', timeout: 10_000, maxBuffer: SPAWN_SYNC_MAX_BUFFER });
+        if (remote.status !== 0) throw new Error(`pod shelf: fetch failed: ${fetch.stderr}`);
+        const fromOrigin = spawnSync('git', ['-C', dir, 'fetch', '-q', String(remote.stdout).trim(), commit], { encoding: 'utf8', timeout: 120_000, maxBuffer: SPAWN_SYNC_MAX_BUFFER });
+        if (fromOrigin.status !== 0) throw new Error(`pod shelf: fetch failed: ${fromOrigin.stderr}`);
+      }
+      const checkout = spawnSync('git', ['-C', dir, 'checkout', '--detach', commit], { encoding: 'utf8', timeout: 120_000, maxBuffer: SPAWN_SYNC_MAX_BUFFER });
+      if (checkout.status !== 0) throw new Error(`pod shelf: checkout failed: ${checkout.stderr}`);
+    }
+    const sync = deps.sync ?? syncPoolImages;
+    const results = await sync([member], 'elanous-harness:local', commit, {
+      buildScript: join(dir, 'docker/harness/build.sh'),
+      ...(deps.sync ? {} : { ship: () => ({ ok: false, action: 'failed' as const, detail: 'shelf build failed; local image fallback prohibited' }) }),
+      remoteBuild: deps.sync ? undefined : async (host, cluster, registry) => {
+        const { spawn } = await import('node:child_process');
+        return new Promise((done) => {
+          const child = spawn('bash', [join(dir, 'docker/harness/build.sh')], { env: { ...process.env, ELANOUS_BUILD_REMOTE: host, ELANOUS_L2_CLUSTER: cluster, ...(registry ? { ELANOUS_BUILD_REGISTRY: registry } : {}) }, stdio: ['ignore', 'pipe', 'pipe'] });
+          let output = '';
+          child.stdout.on('data', (chunk) => { output += chunk; });
+          child.stderr.on('data', (chunk) => { output += chunk; });
+          child.on('close', (code) => done({ ok: code === 0, detail: output.slice(-300) }));
+          child.on('error', (error) => done({ ok: false, detail: error.message }));
+        });
+      },
+    });
+    const result = results.get(member.context);
+    if (!result?.ok || result.imageRef !== image) throw new Error(`pod shelf: image unavailable: ${result?.detail ?? image}`);
+    return { commit, image, action: result.action === 'fresh' ? 'fresh' : 'built' };
+  } finally { (deps.remove ?? ((path) => rmSync(path, { recursive: true, force: true })))(dir); }
+}
+
+export function listPodShelfImages(pool: string, run: RemoteRun): string[] {
+  const member = parsePodPool(pool)[0];
+  if (!member?.sshHost) throw new Error('pod shelf: remote pool member required');
+  const registry = member.registry ?? podImageRegistry();
+  const port = registry.slice(registry.lastIndexOf(':') + 1);
+  const result = run(member.sshHost, `curl -fsS --max-time 5 http://localhost:${port}/v2/elanous-harness/tags/list 2>/dev/null`);
+  if (result.status !== 0) throw new Error(`pod shelf: registry unavailable: ${result.stderr}`);
+  const tags: unknown = JSON.parse(result.stdout).tags;
+  return Array.isArray(tags) ? tags.filter((tag): tag is string => typeof tag === 'string' && /^[0-9a-f]{12}$/u.test(tag)).map((tag) => `${registry}/elanous-harness:${tag}`) : [];
+}
+
 export function podImageMissingMessage(ref: string): string {
   return `기준 이미지 ${ref} 가 레지스트리에 없다 — 레일이 굽기 전이다`;
 }

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

@@ -236,6 +236,10 @@ export interface ExternalGitHubProbe {
   githubHttps: boolean | null;
   measuredAt: string | null;
   reason: string | null;
+  /** Name of the disposable Pod for matching this reading with its Kubernetes logs. */
+  podName?: string;
+  /** Unmodified stdout from `kubectl logs` for this Pod (only present when readable). */
+  podLog?: string;
 }
 const DNS_CACHE_MS = 10 * 60_000;
 const DNS_STALE_OK_MS = 30 * 60_000;
@@ -261,9 +265,11 @@ export function probePoolGitHub(context: string, kubectl: PoolKubectl = leaseKub
       if (typeof record?.at !== 'number' || now() < record.at || now() - record.at >= 60_000) return null;
       if (typeof record.measuredAt !== 'string' || ![true, false].includes(record.externalDns as boolean) ||
           ![true, false, null].includes(record.githubHttps as boolean | null) ||
-          !(record.reason === null || typeof record.reason === 'string')) return null;
+          !(record.reason === null || typeof record.reason === 'string') ||
+          typeof record.podName !== 'string' || typeof record.podLog !== 'string') return null;
       return { externalDns: record.externalDns as boolean, githubHttps: record.githubHttps as boolean | null,
-        measuredAt: record.measuredAt, reason: record.reason as string | null };
+        measuredAt: record.measuredAt, reason: record.reason as string | null,
+        podName: record.podName, podLog: record.podLog };
     } catch { return null; }
   };
   const fresh = cached();
@@ -285,6 +291,7 @@ export function probePoolGitHub(context: string, kubectl: PoolKubectl = leaseKub
     const shared = cached();
     if (shared) return shared;
     const result = runPoolGitHubProbe(context, kubectl, new Date(now()).toISOString());
+    debug.log('pod.lease', 'github-egress-probe', { context, ...result });
     if (result.measuredAt !== null) {
       const temp = `${cache}.${randomUUID()}.tmp`;
       try { writeFileSync(temp, JSON.stringify({ ...result, at: now() }), { mode: 0o600 }); renameSync(temp, cache); }
@@ -300,16 +307,18 @@ export function probePoolGitHub(context: string, kubectl: PoolKubectl = leaseKub
 function runPoolGitHubProbe(context: string, kubectl: PoolKubectl, measuredAt: string): ExternalGitHubProbe {
   const name = `elanous-egress-${randomUUID().slice(0, 12)}`;
   const base = ['--context', context, '--request-timeout=15s'];
-  const unknown = (reason: string): ExternalGitHubProbe => ({ externalDns: null, githubHttps: null, measuredAt: null, reason });
   let created = false;
+  const unknown = (reason: string): ExternalGitHubProbe => ({ externalDns: null, githubHttps: null, measuredAt: null, reason,
+    ...(created ? { podName: name } : {}) });
   try {
     const manifest = JSON.stringify({ apiVersion: 'v1', kind: 'Pod', metadata: { name, namespace: 'elanous-test', labels: { 'elanous.probe': 'github-egress' } }, spec: {
       restartPolicy: 'Never', activeDeadlineSeconds: 35, automountServiceAccountToken: false,
       containers: [{ name: 'probe', image: 'busybox:1.36', command: ['sh', '-c',
-        'if nslookup github.com >/dev/null 2>&1; then echo EXTERNAL_DNS_OK; if wget -q -T 8 -O /dev/null https://github.com/; then echo GITHUB_HTTPS_OK; else echo GITHUB_HTTPS_FAILED; fi; else echo EXTERNAL_DNS_FAILED; fi'],
+        'if nslookup github.com 2>&1; then echo EXTERNAL_DNS_OK; if wget -T 8 -O /dev/null https://github.com/ 2>&1; then echo GITHUB_HTTPS_OK; else echo GITHUB_HTTPS_FAILED; fi; else echo EXTERNAL_DNS_FAILED; fi'],
       resources: { requests: { cpu: '0', memory: '16Mi' }, limits: { cpu: '100m', memory: '64Mi' } } }],
     } });
-    if (kubectl([...base, 'create', '-f', '-'], manifest).status !== 0) return unknown('probe create failed');
+    const createdPod = kubectl([...base, 'create', '-f', '-'], manifest);
+    if (createdPod.status !== 0) return unknown(`probe create failed${createdPod.stderr.trim() ? `: ${createdPod.stderr.trim().split('\n').pop()!.slice(0, 160)}` : ''}`);
     created = true;
     const waited = kubectl([...base, '-n', 'elanous-test', 'wait', '--for=jsonpath={.status.phase}=Succeeded', `pod/${name}`, '--timeout=25s']);
     const podResult = kubectl([...base, '-n', 'elanous-test', 'get', `pod/${name}`, '-o', 'json']);
@@ -327,10 +336,10 @@ function runPoolGitHubProbe(context: string, kubectl: PoolKubectl, measuredAt: s
     const httpsOk = markers.includes('GITHUB_HTTPS_OK');
     const httpsFail = markers.includes('GITHUB_HTTPS_FAILED');
     if (dnsFail && !dnsOk && !httpsOk && !httpsFail)
-      return { externalDns: false, githubHttps: null, measuredAt, reason: 'external DNS failed' };
+      return { externalDns: false, githubHttps: null, measuredAt, reason: 'external DNS failed', podName: name, podLog: logs.stdout };
     if (dnsOk && !dnsFail && httpsOk !== httpsFail)
-      return { externalDns: true, githubHttps: httpsOk, measuredAt, reason: httpsFail ? 'GitHub HTTPS failed' : null };
-    return unknown(waited.status === 0 ? 'probe output unavailable' : 'probe timeout');
+      return { externalDns: true, githubHttps: httpsOk, measuredAt, reason: httpsFail ? 'GitHub HTTPS failed' : null, podName: name, podLog: logs.stdout };
+    return { ...unknown(waited.status === 0 ? 'probe output unavailable' : 'probe timeout'), podLog: logs.stdout };
   } catch { return unknown('probe failed'); }
   finally {
     if (created) try { kubectl([...base, '-n', 'elanous-test', 'delete', `pod/${name}`, '--ignore-not-found=true', '--wait=false']); }