elanous 0.2.17 → 0.2.18

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

@@ -0,0 +1,235 @@
+/**
+ * TASK-AGENT 과제 넘기기 문 — `elanous task hand "<한 줄>"` (RFC-task-agent-any-task-to-completion §A9 표 1행 · R3).
+ *
+ * - 과제 카드를 실행부와 «같은» 상태 파일(`effectiveInstanceRoot()/task-agent-actions.json`)의 `tasks` 칸에 적는다.
+ *   종전 칸(landingDay·landingsToday·failureCounts)은 그대로 두고 덧붙이기만 한다(하위 호환 — 실행부 쓰기는 `...disk` 로 보존).
+ * - 첫 수는 «launch» = `harness say [--seat <자리>] --substrate pod --merge-by-host "<원문>"`.
+ * - 기본은 SHADOW: 카드와 명령만 남기고 아무것도 띄우지 않는다. `--live` 일 때만 주입된 launcher 로 띄운다.
+ * - 관측: `debug.log('task-agent', 'handed', {taskId, seat, checklistId, mode})`.
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { withFileLockSync } from '../storage/file-lock.js';
+
+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-';
+
+export interface TaskCardEvent { at: string; event: string; detail?: string }
+export interface TaskCardMove { kind: 'launch' | 'wait'; command?: string[]; reason: string }
+export interface TaskCard {
+  id: string;
+  text: string;
+  seat?: TaskSeat;
+  checklistId?: string;
+  createdAt: string;
+  /** launch-failed = 발사기가 띄우기에 실패했다(사유는 history 마지막 칸) — 다음 수는 다시 발사. */
+  status: 'handed' | 'launched' | 'launch-failed';
+  history: TaskCardEvent[];
+  /** 미션 카드만 — 조각 카드 id(순서대로) · 쪼갠 출처(`mission.ts` splitMission). */
+  pieces?: string[];
+  splitSource?: string;
+  /** 조각 카드만 — 소속 미션 카드 id · 먼저 착지해야 하는 조각 id(선후). */
+  mission?: string;
+  after?: string[];
+  /** 조각 카드만 — 착지 근거(② `tasks advance --pr|--goal`): 이 조각 런이 연 PR 번호 · 골 id(16자 · 런 원장 `pr-opened` 로 PR 을 찾는다). */
+  pr?: number;
+  goalId?: string;
+  /** 조각 카드만 — ② 가 선행 착지 뒤 넘겼다(한 번만 · 같은 잠금 안에서 먼저 적는다). */
+  handed?: { at: string; mode: 'shadow' | 'live'; claim?: string; error?: string };
+  /** 미션 카드만 — 모든 조각 착지 → 칸 green «제안»(체크리스트는 손대지 않는다 · OP/주인이 뒤집는다). */
+  greenProposal?: { at: string; checklistId: string | null; evidence: Record<string, string> };
+}
+
+interface TaskAgentStateFile { tasks?: Record<string, TaskCard>; [key: string]: unknown }
+
+export function taskAgentStatePath(): string {
+  return join(effectiveInstanceRoot(), 'task-agent-actions.json');
+}
+
+/** 상태 파일을 읽을 수 없거나(ENOENT 제외) 해석할 수 없다 — 덮어쓰기 전에 멈춘다. */
+export class TaskAgentStateError extends Error {
+  constructor(path: string, cause: unknown) {
+    super(`task-agent 상태 파일을 읽을 수 없다 — 덮어쓰지 않고 멈춘다: ${path} (${cause instanceof Error ? cause.message : String(cause)})`);
+    this.name = 'TaskAgentStateError';
+  }
+}
+
+/**
+ * 실행부·과제 넘기기 문이 함께 쓰는 상태 파일(`task-agent-actions.json`)의 엄격한 읽기.
+ * 파일이 «없음»(ENOENT)만 빈 상태다. 그 밖의 읽기·해석 오류(손상된 JSON · 객체 아님 · 권한)는
+ * 던진다 — 빈 상태로 읽고 다시 쓰면 failureCounts·착지 기록·과제 카드가 지워진다.
+ */
+export function readTaskAgentState<T extends object = TaskAgentStateFile>(path: string): T {
+  let raw: string;
+  try { raw = readFileSync(path, 'utf8'); } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return {} as T;
+    return stateError(path, error);
+  }
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw); } catch (error) { return stateError(path, error); }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return stateError(path, new Error('최상위가 객체가 아니다'));
+  return parsed as T;
+}
+
+function stateError(path: string, cause: unknown): never {
+  const error = new TaskAgentStateError(path, cause);
+  try { debug.log('task-agent', 'state-unreadable', { path, reason: error.message }); } catch { /* fail-soft */ }
+  throw error;
+}
+
+function readState(path: string): TaskAgentStateFile {
+  return readTaskAgentState<TaskAgentStateFile>(path);
+}
+
+/** 카드 여럿을 한 잠금 안에서 적는다(미션 ⊕ 조각) — 종전 칸은 `...disk` 로 보존. */
+export function writeTaskCards(path: string, cards: readonly TaskCard[]): void {
+  withFileLockSync(`${path}.lock`, () => {
+    const disk = readState(path);
+    mkdirSync(dirname(path), { recursive: true });
+    const tasks = { ...(disk.tasks ?? {}) };
+    for (const card of cards) tasks[card.id] = card;
+    writeFileSync(path, JSON.stringify({ ...disk, tasks }));
+  });
+}
+
+/** 카드 하나를 잠금 안에서 읽고 고쳐 쓴다 — `update` 가 undefined 를 돌려주면 쓰지 않는다. 쓴(또는 그대로인) 카드를 돌려준다. */
+export function updateTaskCard(path: string, id: string, update: (card: TaskCard | undefined, tasks: Readonly<Record<string, TaskCard>>) => TaskCard | undefined): TaskCard | undefined {
+  return withFileLockSync(`${path}.lock`, () => {
+    const disk = readState(path);
+    const current = disk.tasks?.[id];
+    const next = update(current, disk.tasks ?? {});
+    if (!next) return current;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify({ ...disk, tasks: { ...(disk.tasks ?? {}), [id]: next } }));
+    return next;
+  });
+}
+
+export function readTaskCard(id: string, path = taskAgentStatePath()): TaskCard | undefined {
+  return readState(path).tasks?.[id];
+}
+
+/** 첫 수의 elanous 인자(진입점·--config-dir 앞붙임은 launcher 몫). */
+export function launchArgs(card: Pick<TaskCard, 'text' | 'seat'>): string[] {
+  return ['harness', 'say', ...(card.seat ? ['--seat', card.seat] : []), '--substrate', 'pod', '--merge-by-host', card.text];
+}
+
+/**
+ * `landed` = 착지한 조각 id(② 감지가 채운다). 안 주면 «모른다» — 선행은 미착지로 보고(fail-closed)
+ * 이유에 «착지 미확인»을 단다(착지했다/안 했다를 단정하지 않는다).
+ * 미션 카드는 스스로 발사하지 않는다 · 아직 안 뜬 조각의 선행이 덜 착지했으면 `wait after <id>`.
+ */
+export function nextMoveFor(card: TaskCard, landed?: ReadonlySet<string>): TaskCardMove {
+  if (card.pieces) return { kind: 'wait', reason: `미션 — 조각 ${card.pieces.length}장이 선후대로 발사된다` };
+  const unmet = (card.after ?? []).filter((id) => !landed?.has(id));
+  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: '직전 발사 실패 — 다시 발사' };
+  return { kind: 'wait', reason: '발사됨 — 런 멈춤을 슈퍼바이저 그림자 판단(task-agent.shadow-move)이 받는다' };
+}
+
+export function shellQuote(arg: string): string {
+  return /^[A-Za-z0-9_./:=@%+-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
+}
+
+export type TaskLauncher = (args: string[]) => void | Promise<void>;
+
+export interface HandTaskOptions {
+  text: string;
+  seat?: TaskSeat;
+  checklistId?: string;
+  live?: boolean;
+  statePath?: string;
+  /** `--live` 일 때만 불린다. */
+  launcher?: TaskLauncher;
+  now?: () => Date;
+  id?: string;
+  /** 미션 조각으로 넘길 때 — 카드에 소속 미션·선후를 싣는다. */
+  mission?: string;
+  after?: string[];
+  /** 착지한 조각 id — `after` 가 모두 여기 있어야 발사한다(② 의 자리). */
+  landed?: ReadonlySet<string>;
+  /** 카드에 그대로 싣는 칸(② 의 넘김 표지·착지 근거) — handTask 가 카드를 새로 적을 때 지워지지 않게. */
+  cardFields?: Pick<TaskCard, 'pr' | 'goalId' | 'handed'>;
+  /**
+   * 있으면 카드 쓰기마다 잠금 안에서 디스크 카드를 보고 참일 때만 쓴다(② 의 claim 소유 확인).
+   * 거짓이면 쓰지 않고 `TaskCardSupersededError` — 다른 넘김이 그 카드를 가져갔다(발사 전이면 발사하지 않는다).
+   */
+  writeGuard?: (current: TaskCard | undefined) => boolean;
+}
+
+/** `writeGuard` 가 거짓 — 다른 넘김이 카드를 가져갔다. 카드는 건드리지 않았다. */
+export class TaskCardSupersededError extends Error {
+  constructor(id: string) {
+    super(`과제 카드를 다른 넘김이 가져갔다 — 쓰지 않았다: ${id}`);
+    this.name = 'TaskCardSupersededError';
+  }
+}
+
+/** `--live` 발사가 실패했다 — 카드는 launch-failed 로 남았다. */
+export class TaskLaunchError extends Error {
+  constructor(card: TaskCard, reason: string) {
+    super(`발사 실패 (${card.id} → launch-failed): ${reason}`);
+    this.name = 'TaskLaunchError';
+  }
+}
+
+export interface HandTaskResult { card: TaskCard; move: TaskCardMove; mode: 'shadow' | 'live'; launched: boolean }
+
+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}`);
+  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';
+  const path = opts.statePath ?? taskAgentStatePath();
+  const card: TaskCard = {
+    id, text,
+    ...(opts.seat ? { seat: opts.seat } : {}),
+    ...(opts.checklistId ? { checklistId: opts.checklistId } : {}),
+    createdAt: now.toISOString(),
+    status: 'handed',
+    history: [],
+    ...(opts.mission ? { mission: opts.mission, after: [...(opts.after ?? [])] } : {}),
+    ...(opts.cardFields ?? {}),
+  };
+  const move = nextMoveFor(card, opts.landed);
+  if (move.kind !== 'launch') throw new Error(`발사할 수 없는 과제다 — ${move.reason}`);
+  const guard = opts.writeGuard;
+  const writeCard = (target: string, next: TaskCard): void => {
+    if (!guard) { writeTaskCards(target, [next]); return; }
+    const owned = { ok: false };
+    // 착지 근거(pr·goalId)는 `recordPieceRef` 소유 — claim 뒤에 적힌 최신 근거를 디스크에서 이어 받는다.
+    updateTaskCard(target, next.id, (current) => {
+      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 } : {}) };
+    });
+    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 };
+  if (!opts.launcher) throw new Error('--live 인데 launcher 가 없다');
+  try {
+    await opts.launcher(move.command!);
+  } 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 }] };
+    writeCard(path, failed);
+    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(' ') }] };
+  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 };
+}

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

@@ -33,6 +33,8 @@ export function extractPodFailureReason(input: {
   containerReason?: string | null;
   jobReason?: string;
   deadlineSeconds?: number;
+  /** POD-NORESULT: the stage and PR from the child's parsed result row (disposition) — used only when no log line gives a readable reason. */
+  result?: { stage?: string | null; prUrl?: string | null; prNumber?: number | null } | null;
 }): string {
   if (input.jobReason === 'DeadlineExceeded') {
     return `DeadlineExceeded: Job 수명 상한 ${input.deadlineSeconds ?? 'unknown'}초 초과`;
@@ -72,6 +74,14 @@ export function extractPodFailureReason(input: {
   const errorLine = [...meaningful].reverse().find((line) => line.terminal || isError(line.text));
   const reason = errorLine?.text.replace(/\/home\/[^/\s]+\//gu, '~/').slice(0, 240);
   if (reason) return reason;
+  // POD-NORESULT: an unconverged child (exit 2 → BackoffLimitExceeded under backoffLimit 0) often leaves a result row
+  // with a stage and PR but no error text — report that instead of «unreadable».
+  const stage = input.result?.stage?.trim();
+  if (stage) {
+    const prNumber = input.result?.prNumber;
+    const pr = Number.isSafeInteger(prNumber) && prNumber! > 0 ? `PR #${prNumber}` : input.result?.prUrl ? `PR ${input.result.prUrl}` : '';
+    return pr ? `수확 가능(${stage}) · ${pr}` : `수렴 못 함(단계 ${stage})`;
+  }
   const why = input.logTailReason?.trim() || (input.logs.trim() ? '로그에 읽을 수 있는 오류 줄 없음' : '자식 로그 비어 있음');
   return `사유 못 읽음: ${why.replace(/\/home\/[^/\s]+\//gu, '~/').slice(0, 240)}`;
 }

package/src/task-orchestrator/surfaces/self-implement-pod.ts

@@ -33,6 +33,13 @@ export const POD_CONTROL_INBOX_DIR = '/tmp/elanous-control.inbox';
 /** Newest pod log bytes returned when the export passes the 5MB artifact limit (headroom under it). */
 export const POD_LOGS_KEEP_BYTES = 4_500_000;
 
+/** Re-emit the child's `{kind:"self", ok, result}` line as one flat `{...result, ok}` line at the end of /tmp/si.out.
+ *  POD-NORESULT ⓑ (10-07 · 28 failed rc=2 Jobs read back): every child printed its result line, but one
+ *  (si-task-71f68d57f6b7, image 0.2.15) had stderr lines (`[graph] collect fail`) after it, so the old
+ *  «last line only» check skipped the flatten and the host kept `ok:false` with no stage or PR number.
+ *  Scan back to the newest child result line instead; still append exactly one line. */
+const POD_RESULT_FLATTEN = `bun -e 'const fs=require("fs");const p="/tmp/si.out";const lines=fs.readFileSync(p,"utf8").trimEnd().split("\\n");for(let i=lines.length-1;i>=0;i--){const l=lines[i].trim();if(!l.startsWith("{"))continue;let o;try{o=JSON.parse(l)}catch{continue}if(!o||o.kind!=="self")continue;if(o.result&&typeof o.result==="object"&&!Array.isArray(o.result))fs.appendFileSync(p,"\\n"+JSON.stringify({...o.result,...(typeof o.ok==="boolean"?{ok:o.ok}:{})})+"\\n");break}'`;
+
 export const POD_JOB_DEADLINE_SECONDS = 10_800;
 
 /** 자식 컨테이너 «요청» — 🩸 2026-09-27: limits 만 두면 k8s 가 requests=limits(cpu 4)로 잡아, 32코어 노드에
@@ -147,6 +154,8 @@ export interface PodSpawnOptions {
   credentials?: (account: string) => { elanousAuth: string; codexAuth: string; ghToken: string };
   /** POD-TOKEN-PREREFRESH 시험 심 — «3시간 안 만료» 계정의 호스트 선갱신(기본 refreshCodexAccountHome). */
   codexPrerefresh?: (account: string) => Promise<{ ok: true; beforeH: number | null; afterH: number | null } | { ok: false; kind: string; message: string }>;
+  /** PREREFRESH-LOCK 시험 심 — 계정별 갱신 잠금 파일 경로(기본 = 그 계정 codexHome 옆). */
+  codexPrerefreshLockPath?: (account: string) => string | null;
   /** 시험 심 — 이 호스트가 본부 임대 보유자인가(기본 HQ 펜스 · kubectl 주입 시험이면 false). */
   hqLeaseHolder?: () => boolean | Promise<boolean>;
   grokCredentials?: () => { grokAuth?: string; grokApiKey?: string; ghToken: string };
@@ -186,17 +195,29 @@ export class PodCodexExpiringError extends Error {
   }
 }
 
-export type PodCredentialPrerefreshOutcome = 'refreshed' | 'still-expiring' | 'refresh-failed' | 'no-lease';
+export type PodCredentialPrerefreshOutcome =
+  | 'refreshed' | 'still-expiring' | 'refresh-failed' | 'no-lease'
+  // PREREFRESH-LOCK (10-06): a peer refreshed it while we waited for the lock · a failed refresh's one re-check.
+  | 'refresh-skipped-already-fresh' | 'refresh-failed-recheck-ok' | 'refresh-failed-recheck-failed'
+  // 갱신을 «시도하지 않았다» — 잠금 자리를 못 구했거나 잠금을 못 잡았다(갱신 실패와 가른다 · reason = no-lock-path|lock-timeout|lock-error).
+  | 'lock-unavailable';
 
 /** POD-TOKEN-PREREFRESH (10-06) — «3시간 안 만료» 계정은 거부만 하지 말고 선갱신을 한 번 시도한다.
  *  🩸 05:3x team · 09:47 third: 거부만 하고 다음 계정으로 안 넘어가 그 계정으로 뽑힌 Pod 런이 전부 pod-error.
  *  ⛔ 갱신은 본부(HQ) 임대 보유자 한 곳에서만 — refresh 토큰은 갱신마다 회전해 두 곳이 갱신하면 로그아웃된다.
+ *  ⭐ PREREFRESH-LOCK (10-06 · #24449 사후 리뷰): 같은 호스트의 두 런이 같은 계정을 «동시에» 고르면 갱신이 둘이 돌아
+ *     뒤엣것이 회전된 refresh 토큰으로 실패하고 그 계정을 버렸다. ⇒ 계정별 파일 잠금 안에서 ⑴ 먼저 다시 읽어
+ *     이미 신선하면 갱신하지 않고 ⑵ 갱신이 실패해도 한 번 다시 읽어(동료가 갱신했을 수 있다) 신선하면 쓴다.
  *  null = 이 계정은 후보에서 뺀다(호출자가 다음 계정으로). 만료 아닌 다른 자격 오류는 그대로 던진다. */
 export async function podCodexCredentialWithPrerefresh(account: string, deps: {
   credentials: (account: string) => { elanousAuth: string; codexAuth: string; ghToken: string };
   refresh: (account: string) => Promise<{ ok: true; beforeH: number | null; afterH: number | null } | { ok: false; kind: string; message: string }>;
   isLeaseHolder: () => boolean | Promise<boolean>;
   log?: (category: string, event: string, data: Record<string, unknown>) => void;
+  /** 계정별 갱신 잠금 파일(기본 = 그 계정 codexHome 옆 · `codexAccountRefreshLockPath`). null = 잠금 없음. */
+  lockPath?: (account: string) => string | null;
+  /** 잠금 대기 조정(시험 심) — 기본 CODEX_REFRESH_LOCK_OPTS. */
+  lockOpts?: { staleMs?: number; retryBusyMs?: number; maxTries?: number };
 }): Promise<{ elanousAuth: string; codexAuth: string; ghToken: string } | null> {
   const log = deps.log ?? ((category, event, data) => debug.log(category, event, data));
   try { return deps.credentials(account); }
@@ -209,17 +230,56 @@ export async function podCodexCredentialWithPrerefresh(account: string, deps: {
     let holder = false;
     try { holder = await deps.isLeaseHolder(); } catch { holder = false; }
     if (!holder) { observe('no-lease', null); return null; }
-    let refreshed: Awaited<ReturnType<typeof deps.refresh>>;
-    try { refreshed = await deps.refresh(account); }
-    catch { observe('refresh-failed', null, 'threw'); return null; }
-    if (!refreshed.ok) { observe('refresh-failed', null, refreshed.kind); return null; }
-    try {
-      const credential = deps.credentials(account);
+    /** One re-read: fresh credential, null when still expiring. Other credential errors throw. */
+    const reread = (): { elanousAuth: string; codexAuth: string; ghToken: string } | { expiringH: number } => {
+      try { return deps.credentials(account); }
+      catch (again) {
+        if (!(again instanceof PodCodexExpiringError)) throw again;
+        return { expiringH: again.hoursLeft };
+      }
+    };
+    const codex = await import('../../oauth/codex.js');
+    let lockPath: string | null = null;
+    let lockUnknown = false;
+    try { lockPath = (deps.lockPath ?? ((name: string) => codex.codexAccountRefreshLockPath(name)))(account); } catch { lockUnknown = true; }
+    // 이름 있는 계정인데 잠금 자리를 못 구하면 잠금 없이 갱신하지 않는다 — 막으려던 중복 갱신이 그 자리에서 재발한다.
+    // 갱신은 건너뛰고 한 번만 다시 읽는다(동료가 이미 갱신했으면 그대로 쓴다).
+    if (lockUnknown || (lockPath === null && account !== (await import('../../oauth/codex-account.js')).DEFAULT_CODEX_ACCOUNT)) {
+      const late = reread();
+      if (!('expiringH' in late)) { observe('refresh-skipped-already-fresh', null, 'no-lock-path'); return late; }
+      observe('lock-unavailable', null, 'no-lock-path');
+      return null;
+    }
+    const critical = async () => {
+      // ⑴ 잠금을 기다리는 사이 동료 런이 갱신했으면 그대로 쓴다 — 두 번째 갱신이 회전된 토큰으로 실패하는 자리.
+      const first = reread();
+      if (!('expiringH' in first)) { observe('refresh-skipped-already-fresh', null); return first; }
+      let refreshed: Awaited<ReturnType<typeof deps.refresh>> | null = null;
+      let failReason = 'threw';
+      try { refreshed = await deps.refresh(account); }
+      catch { refreshed = null; }
+      if (refreshed && !refreshed.ok) failReason = refreshed.kind;
+      if (!refreshed || !refreshed.ok) {
+        observe('refresh-failed', null, failReason);
+        // ⑵ 버리기 전에 한 번 다시 읽는다 — 다른 호스트 경로(사람 `account refresh`)가 방금 갱신했을 수 있다.
+        let recheck: ReturnType<typeof reread>;
+        try { recheck = reread(); } catch { observe('refresh-failed-recheck-failed', null, 'recheck-error'); return null; }
+        if (!('expiringH' in recheck)) { observe('refresh-failed-recheck-ok', null); return recheck; }
+        observe('refresh-failed-recheck-failed', recheck.expiringH);
+        return null;
+      }
+      const after = reread();
+      if ('expiringH' in after) { observe('still-expiring', after.expiringH); return null; }
       observe('refreshed', refreshed.afterH);
-      return credential;
-    } catch (again) {
-      if (!(again instanceof PodCodexExpiringError)) throw again;
-      observe('still-expiring', again.hoursLeft);
+      return after;
+    };
+    try { return await codex.withCodexAccountRefreshLock(lockPath, critical, deps.lockOpts ?? codex.CODEX_REFRESH_LOCK_OPTS); }
+    catch (lockError) {
+      if (!(lockError instanceof codex.CodexRefreshLockUnavailableError)) throw lockError;
+      // 잠금을 못 잡았다(대기 초과 · 잠금 파일 생성 실패) — 갱신은 하지 않고 한 번만 다시 읽는다.
+      const late = reread();
+      if (!('expiringH' in late)) { observe('refresh-skipped-already-fresh', null, lockError.reason); return late; }
+      observe('lock-unavailable', null, lockError.reason);
       return null;
     }
   }
@@ -688,11 +748,11 @@ export function podJobManifest(o: { name: string; namespace: string; image: stri
     ...(o.appCredential ? [podGithubWatchdogScript(o.githubStaleSeconds ?? POD_GH_STALE_SECONDS)] : []),
     // 마지막 줄 JSON 이 «맨 끝»이어야 한다(parseSelfImplementJson) — rollup 은 그 앞에.
     // ⛔ `--author-grade` 는 Pod 안 `elanous`(이미지에 깔린 판)가 모를 수 있어 넘기지 않는다 — 10-06 «unknown option» 즉사(#24445 되돌림).
-    // lite 는 지금 로컬 저작 전용이다. Pod 저작은 설정·기본(full)을 따른다.
+    // AUTHOR-LITE2-POD — 등급은 환경변수 `ELANOUS_AUTHOR_GRADE` 로 싣는다(옛 Pod elanous 는 모르는 환경변수를 무시하고 full 로 돈다).
     o.authorSentence
-      ? `echo "ELANOUS_AUTHOR_ON_POD started host=$(hostname) at=$(date -u +%Y-%m-%dT%H:%M:%SZ)"; author_t0=$(date +%s); elanous harness say --substrate local --json${quotedAsk} -- "$(cat /creds/feature)" > /tmp/si.out 2>&1; rc=$?; echo "ELANOUS_AUTHOR_ON_POD finished host=$(hostname) rc=$rc seconds=$(( $(date +%s) - author_t0 ))"; bun -e 'const fs=require("fs");const p="/tmp/si.out";const s=fs.readFileSync(p,"utf8");const line=s.trimEnd().split("\\n").at(-1);try{const o=JSON.parse(line);if(o.kind==="self"&&o.result&&typeof o.result==="object")fs.appendFileSync(p,"\\n"+JSON.stringify({...o.result,...(typeof o.ok==="boolean"?{ok:o.ok}:{})})+"\\n")}catch{}'`
+      ? `echo "ELANOUS_AUTHOR_ON_POD started host=$(hostname) at=$(date -u +%Y-%m-%dT%H:%M:%SZ)"; author_t0=$(date +%s); ${o.authorGrade === 'lite' || o.authorGrade === 'full' ? `ELANOUS_AUTHOR_GRADE=${o.authorGrade} ` : ''}elanous harness say --substrate local --json${quotedAsk} -- "$(cat /creds/feature)" > /tmp/si.out 2>&1; rc=$?; echo "ELANOUS_AUTHOR_ON_POD finished host=$(hostname) rc=$rc seconds=$(( $(date +%s) - author_t0 ))"; ${POD_RESULT_FLATTEN}`
       : goalPath
-      ? `elanous harness ask ${goalPath} --json${quotedAsk} > /tmp/si.out 2>&1; rc=$?; bun -e 'const fs=require("fs");const p="/tmp/si.out";const s=fs.readFileSync(p,"utf8");const line=s.trimEnd().split("\\n").at(-1);try{const o=JSON.parse(line);if(o.kind==="self"&&o.result&&typeof o.result==="object")fs.appendFileSync(p,"\\n"+JSON.stringify({...o.result,...(typeof o.ok==="boolean"?{ok:o.ok}:{})})+"\\n")}catch{}'`
+      ? `elanous harness ask ${goalPath} --json${quotedAsk} > /tmp/si.out 2>&1; rc=$?; ${POD_RESULT_FLATTEN}`
       : `export ${OLD_DOOR_STAMP_ENV}=self-implement; elanous self implement "$(cat /creds/feature)" --json ${quoted} > /tmp/si.out 2>&1; rc=$?`,
     'cat /tmp/si.out',
     '[ -f scripts/usage-rollup.ts ] && bun scripts/usage-rollup.ts --since 12h || echo "ELANOUS_USAGE_ROLLUP {\"measured\":false,\"reason\":\"no rollup script\"}"',
@@ -1054,6 +1114,9 @@ export function podSelfImplementSpawn(options: PodSpawnOptions = {}): SelfImplem
           credentials: accountCredentials,
           refresh: options.codexPrerefresh ?? (async (name: string) => (await import('../../oauth/codex.js')).refreshCodexAccountHome(name)),
           isLeaseHolder: options.hqLeaseHolder ?? (options.kubectl ? () => false : defaultHqLeaseHolder),   // kubectl 주입(=시험)이면 본부 임대를 묻지 않는다
+          // PREREFRESH-LOCK: 시험(kubectl 주입)은 정본 스토어를 읽어 잠금 경로를 풀지 않는다 — 임시 디렉터리의 계정별 잠금.
+          // 잠금 자리는 주입 여부와 무관하게 계정 홈 옆 하나 — 시험은 codexPrerefreshLockPath 로 명시한다(같은 계정이 서로 다른 잠금을 쓰지 않게).
+          ...(options.codexPrerefreshLockPath ? { lockPath: options.codexPrerefreshLockPath } : {}),
         };
         const candidates = grok ? [] : plannedCodexAccounts ?? [plannedAccount];
         const usable: Array<{ name: string; credential: ReturnType<typeof accountCredentials> }> = [];
@@ -1552,12 +1615,15 @@ export function podSelfImplementSpawn(options: PodSpawnOptions = {}): SelfImplem
           }
           const releaseHold = regate.failures[0]?.step === 'release-path-hold';
           const frozen = regate.status === 'frozen';
+          // FREEZE-POD: the host is the only merger of a Pod run, so its freeze check here is the one that holds it.
+          if (frozen) debug.log('self-implement.pod', 'merge-blocked-by-freeze', { job: name, runId: liveChildRunId, pr: prNumber ?? null, reason: 'landing-freeze' });
           disposition = { ...disposition, stage: frozen || releaseHold ? 'pr-opened' : regate.passed ? 'merged' : 'host-regate-failed', merged: regate.passed && !frozen, hostRegate: regate, ok: regate.passed || releaseHold || frozen };
         }
         const childFailure = state === 'failed' && !oomKilled && failedReason !== 'DeadlineExceeded'
           ? lastPodChildFailure(logs) : null;
         let noResultDiagnostic: string | null = null;
-        if (state === 'failed' && containerExitCode !== null && containerExitCode !== 0 && !disposition && !oomKilled && failedReason !== 'DeadlineExceeded' && failedReason !== 'BackoffLimitExceeded') {
+        // POD-NORESULT: the Job runs with backoffLimit 0, so any non-zero child exit is «BackoffLimitExceeded» — not a reason to skip the ledger.
+        if (state === 'failed' && containerExitCode !== null && containerExitCode !== 0 && !disposition && !oomKilled && failedReason !== 'DeadlineExceeded') {
           try { noResultDiagnostic = podNoResultDiagnostic(readFileSync(runLedgerPath(liveChildRunId, ledgerDir), 'utf8')); }
           catch { /* ledger not returned: do not invent a stage */ }
           noResultDiagnostic ??= 'child terminal result missing; last ledger stage=unknown; round=unknown; mustFix=unknown';
@@ -1568,7 +1634,9 @@ export function podSelfImplementSpawn(options: PodSpawnOptions = {}): SelfImplem
         }
         debug.log('self-implement.pod', 'job-finished', { job: name, ...(member ? { context: member.context } : {}), state, containerReason, stage: disposition?.stage ?? null, prUrl: disposition?.prUrl ?? null, childRunId: liveChildRunId, ledgerCompleteness,
           ...(state === 'failed' && !oomKilled && failedReason !== 'DeadlineExceeded'
-            ? { ...(childFailure ? { childStage: childFailure.stage } : {}), childError: childFailure?.error ?? 'no-result-line' } : {}) },
+            ? { ...(childFailure ? { childStage: childFailure.stage } : disposition?.stage ? { childStage: disposition.stage } : {}),
+              // POD-NORESULT: a parsed result row without error text is not a missing result line (UX 10-07 01:01: 28 of 28 exit-2 Jobs printed one).
+              childError: childFailure?.error ?? (disposition?.stage ? 'result-without-error' : 'no-result-line') } : {}) },
           state === 'failed' && !oomKilled && failedReason !== 'DeadlineExceeded' ? { compact: { stringMax: 500 } } : undefined);
         if (oomKilled && reattach && !oomRetried && (!reattachedMemoryLimit || memoryGi(reattachedMemoryLimit) === null)) {
           return { exitCode: 1, output: '', error: { code: 'pod-memory-unavailable', message: `Job ${name} 실제 메모리 한도를 확인할 수 없다` } };
@@ -1639,7 +1707,7 @@ export function podSelfImplementSpawn(options: PodSpawnOptions = {}): SelfImplem
           : disposition;
         const podExitCode = state === 'complete' && disposition?.stage !== 'host-regate-failed' && disposition?.ok !== false ? 0 : 1;
         // SCHED-CONTRACT: a failed child must say why outside the Pod, not «no error diagnostic».
-        const podReason = podExitCode === 1 ? extractPodFailureReason({ logs, logTailReason, containerReason, jobReason: failedReason || undefined, deadlineSeconds }) : undefined;
+        const podReason = podExitCode === 1 ? extractPodFailureReason({ logs, logTailReason, containerReason, jobReason: failedReason || undefined, deadlineSeconds, result: disposition ? { stage: disposition.stage, prUrl: disposition.prUrl ?? null, prNumber: disposition.prNumber ?? null } : null }) : undefined;
         if (podReason) debug.log('self-implement.pod', 'failure-reason', { job: name, reason: podReason });
         return {
           exitCode: podExitCode,
@@ -1651,7 +1719,7 @@ export function podSelfImplementSpawn(options: PodSpawnOptions = {}): SelfImplem
                 ? { error: { code: 'pod-gh-login-failed', message: `Job ${name} GitHub 앱 로그인 실패 (container=${containerReason ?? 'unknown'}/7, attempt=${ghLoginRetried ? 2 : 1}) — 새 토큰으로 ${ghLoginRetried ? '1회 재시도했으나 다시 실패' : '재시도 불가'}` } }
               : oomKilled
                 ? { error: { code: 'pod-oom-killed', message: `Job ${name} failed (OOMKilled/${containerExitCode ?? 'unknown'}, memoryLimit=${memoryLimit})${oomRetried || (memoryGi(reattachedMemoryLimit ?? memoryLimit) ?? 0) >= (memoryGi(podMemoryLimitFor(input.feature, { ...env, ELANOUS_POD_MEMORY_TIER: 'high' }).limit) ?? Infinity) ? ` — OOM · ${oomRetried ? retryTier : 'high'} 에서도` : ''}\n${formatLastMemSample(samples.at(-1))}` } }
-                : { error: { code: 'pod-job-failed', message: `Job ${name} failed${failedReason || containerReason ? ` (${[failedReason, containerReason ? `container=${containerReason}/${containerExitCode ?? 'unknown'}` : ''].filter(Boolean).join(', ')})` : ''}${childFailure ? ` — childStage=${childFailure.stage} · childError=${childFailure.error}` : ` — childError=no-result-line · reason=${podReason}`}${noResultDiagnostic ? ` · ${noResultDiagnostic}` : ''}` } }
+                : { error: { code: 'pod-job-failed', message: `Job ${name} failed${failedReason || containerReason ? ` (${[failedReason, containerReason ? `container=${containerReason}/${containerExitCode ?? 'unknown'}` : ''].filter(Boolean).join(', ')})` : ''}${childFailure ? ` — childStage=${childFailure.stage} · childError=${childFailure.error}` : disposition?.stage ? ` — childStage=${disposition.stage} · reason=${podReason}` : ` — childError=no-result-line · reason=${podReason}`}${noResultDiagnostic ? ` · ${noResultDiagnostic}` : ''}` } }
               : podReason && !childFailure?.error ? { error: { code: 'pod-child-failed', message: podReason } } : {}),
           ...(finishedDisposition ? { disposition: finishedDisposition } : {}),
         };

package/src/telegram-loops-command.ts

@@ -2,7 +2,7 @@ import { dashboardLoops } from './domains/dashboard-data.js';
 import { readSchedulesInventory } from './nexus/api/schedules-read.js';
 import { loadLoopRows, LOOP_SCHEDULES_PATH, LOOPS_PATH } from './loops/status-rows.js';
 
-interface LoopsSources {
+export interface LoopsSources {
   schedules: () => unknown;
   loops: () => unknown;
   now: () => number;

package/src/telegram.ts

@@ -82,6 +82,7 @@ import { attachTelegramProjectButtons } from './telegram-project-command.js';
 import { attachTelegramFabricPlan } from './telegram-fabric-plan.js';
 import { contextNow as readContextNow, type ContextNowDeps } from './context-bus/context-now.js';
 import { renderTelegramNow } from './context-bus/context-now-surfaces.js';
+import { createContextFirstGate, renderContextFirst } from './context-bus/context-first.js';
 
 export type TgAttachmentKind = 'photo' | 'voice' | 'audio' | 'document';
 
@@ -269,9 +270,6 @@ const EMPTY_ALLOWLIST_NOTICE_GAP_MS = 10 * 60 * 1000;
 // Tuned above a normal chat answer but below a real delegation (which
 // pays a multi-second session load before any work).
 const NOTIFY_AS_NEW_MSG_THRESHOLD_MS = 20_000;
-/** 같은 대화에서 이 간격 안이면 context-now 요약을 다시 보내지 않는다. */
-const CONTEXT_FIRST_GAP_MS = 6 * 60 * 60 * 1000;
-const CONTEXT_UNREADABLE = '맥락 못 읽음';
 
 interface ApiResponse<T> {
   ok: boolean;
@@ -365,10 +363,7 @@ export class TelegramBot {
   private readonly handleFabricPlan: (ctx: TgIncoming) => Promise<boolean>;
   private readonly readContextNow: typeof readContextNow;
   private readonly contextNowDeps?: ContextNowDeps;
-  /** 대화 키(chat+thread) → 그 대화의 마지막 사용자 발화 시각(요약 여부와 무관하게 매 발화마다 갱신). */
-  private readonly lastUtteranceAt = new Map<string, number>();
-  /** 첫 말이거나 6시간 이상 쉰 뒤라 요약이 «밀려 있는» 대화 키 — 다음 일반 답이 한 번 소비한다. */
-  private readonly contextFirstPending = new Set<string>();
+  private readonly contextFirstGate = createContextFirstGate({ now: () => this.nowImpl() });
   private seatAskTimer: ReturnType<typeof setInterval> | null = null;
   /** 앨범 id → `#현장` 행사 · 답장 디바운스. 태그된 앨범만 들어온다. */
   private readonly fieldGroups = new Map<string, {
@@ -432,27 +427,17 @@ export class TelegramBot {
 
   /** 허용된 모든 발화(명령 포함)마다 부른다 — 쉼은 마지막 발화부터 재고, 요약 전송과는 따로 기록한다. */
   private noteUtterance(ctx: TgIncoming): void {
-    const key = `${ctx.chatId}:${ctx.threadId ?? ''}`;
-    const now = this.nowImpl();
-    const previous = this.lastUtteranceAt.get(key);
-    this.lastUtteranceAt.set(key, now);
-    if (previous === undefined || now - previous >= CONTEXT_FIRST_GAP_MS) this.contextFirstPending.add(key);
+    this.contextFirstGate.note(`${ctx.chatId}:${ctx.threadId ?? ''}`);
   }
 
   /** 처음이거나 6시간 이상 쉰 대화의 첫 일반 답 앞에 context-now 요약 한 메시지를 보낸다. 실패해도 본 답은 막지 않는다. */
   private async maybeSendContextFirst(ctx: TgIncoming): Promise<void> {
     const key = `${ctx.chatId}:${ctx.threadId ?? ''}`;
-    if (!this.contextFirstPending.delete(key)) return;
+    if (!this.contextFirstGate.take(key)) return;
     const cfg = this.slashContext?.userConfig.telegram;
     if (cfg?.contextFirst === false) return;
-    let text = CONTEXT_UNREADABLE;
-    try {
-      text = renderTelegramNow(this.readContextNow({}, this.contextNowDeps));
-    } catch {
-      text = CONTEXT_UNREADABLE;
-    }
     try {
-      await this.sendMessage(ctx.chatId, text, { replyTo: ctx.messageId, threadId: ctx.threadId });
+      await this.sendMessage(ctx.chatId, renderContextFirst(this.readContextNow, this.contextNowDeps, renderTelegramNow), { replyTo: ctx.messageId, threadId: ctx.threadId });
     } catch (err) {
       this.log(`telegram context-first failed: ${err instanceof Error ? err.message : String(err)}`);
     }