elanous 0.2.20 → 0.2.21

package/src/ops/overview.ts

@@ -0,0 +1,223 @@
+/**
+ * OPS-OVERVIEW-CLI 첫 조각 — 흐름 한 장의 «순수» 층(판정 · 이유 사슬 · 사람 표기).
+ * 설계 = 내부 문서 `RFC-ops-overview-flow-health-cli-2026-10-08` §A1·A2.
+ *
+ * ⛔ 이 파일은 I/O 를 하지 않는다 — 수집은 `overview-collect.ts`, 자리 시대 임시 원천은 `overview-seat-era.ts`.
+ * ⛔ «못 잼»은 `value:null` ⊕ `reason` 이다 — 절대 0 으로 읽지 않는다(판정도 그렇다).
+ */
+
+export type CellStatus = 'ok' | 'unmeasured' | 'partial';
+export interface Cell<T> {
+  value: T | null;
+  source: string;
+  observedAt: string | null;
+  status: CellStatus;
+  reason?: string;
+}
+
+export function okCell<T>(value: T, source: string, observedAt: string | null): Cell<T> {
+  return { value, source, observedAt, status: 'ok' };
+}
+export function unmeasured<T>(source: string, reason: string, observedAt: string | null = null): Cell<T> {
+  return { value: null, source, observedAt, status: 'unmeasured', reason };
+}
+export function measured(cell: Cell<unknown>): boolean {
+  return cell.status !== 'unmeasured' && cell.value !== null;
+}
+
+/** 닫힌 판정 어휘 — 배열 순서가 곧 우선순위(위가 이긴다 · RFC §A1). */
+export const VERDICTS = ['unobservable', 'blocked', 'loop-down', 'saturated', 'supply-empty', 'degraded', 'flowing'] as const;
+export type Verdict = typeof VERDICTS[number];
+export const VERDICT_LABEL: Record<Verdict, string> = {
+  unobservable: '관측 불가', blocked: '막힘', 'loop-down': '루프 정지', saturated: '자원 포화',
+  'supply-empty': '공급 부족', degraded: '흐름 저하', flowing: '흐름 정상',
+};
+
+export interface ReleaseRunInfo {
+  runId: string; status: string; currentNode: string | null; startedAt: string | null;
+  /** approval · freeze · gate · process-gone · none */
+  waitingOn: 'approval' | 'gate' | 'process-gone' | 'none';
+  elapsedMinutes: number | null;
+}
+export interface ScheduleInfo { cutAt: string; landBy: string | null; publishAt: string | null; freezeNow: boolean }
+export interface ChecklistCounts { green: number; yellow: number; red: number; done: number; p0Yellow: number }
+export interface OwnerTaskRow { handed: number; launched: number; prBound: number; failed: number; launchFailed: number }
+export interface LaunchableInfo {
+  count: number; ids: string[];
+  skipped: { noTargetPath: number; predecessorOpen: number; alreadyHanded: number };
+  /** 오케스트레이터의 «발사 가능» 술어가 아직 export 되지 않아 overview 가 임시로 계산했다(OVW-DISPATCH-LEDGER 가 대체). */
+  interim: true;
+}
+export interface CapacityInfo { podUsed: number; podTarget: number; localUsed: number; localMax: number; free: number }
+export interface MachineLoad { load1: number; load5: number; load15: number; cpuCount: number; freeGb: number; totalGb: number; ageSeconds: number }
+export interface MachineRow { name: string; load: Cell<MachineLoad> }
+export interface PodMemberRow { context: string; capacity: number; occupied: Cell<number> }
+export interface ParentsInfo { count: number; staleOver6h: number; oldestHours: number | null }
+export interface LoopRow {
+  name: string;
+  /** product = 제품 원장 · seat-era = 자리 시대 원천(제품 밖 · 임시) */
+  era: 'product' | 'seat-era';
+  beat: Cell<{ lastAt: string; ageSeconds: number; alive: boolean | null }>;
+  /** 이 주기 이상 박동이 없으면 정지로 본다. null = 주기를 모른다 → 판정에서 뺀다(«죽었다»로 읽지 않는다). */
+  staleAfterSeconds: number | null;
+}
+
+export interface OverviewSnapshot {
+  generatedAt: string;
+  instanceRoot: string;
+  since: string;
+  release: {
+    version: Cell<string>;
+    run: Cell<ReleaseRunInfo | 'none'>;
+    schedule: Cell<ScheduleInfo | 'none'>;
+    checklist: Cell<ChecklistCounts>;
+  };
+  tasks: {
+    byOwner: Cell<Record<string, OwnerTaskRow>>;
+    done: Cell<number>;
+    launchable: Cell<LaunchableInfo>;
+    capacity: Cell<CapacityInfo>;
+  };
+  machines: {
+    hosts: MachineRow[];
+    pods: PodMemberRow[];
+    parents: Cell<ParentsInfo>;
+  };
+  landings: Cell<{ count: number; recent: string[] }>;
+  loops: LoopRow[];
+}
+
+export interface VerdictResult { verdict: Verdict; reasons: string[]; nextActions: string[] }
+
+/** 부하/코어가 이 값을 넘으면 «기계 압박»(흐름 저하의 사유). 디스크 I/O 신호는 OVW-MACHINE-HB 전까지 없다. */
+export const LOAD_PER_CORE_PRESSURE = 3;
+
+export function computeVerdict(s: OverviewSnapshot): VerdictResult {
+  const hits = new Map<Verdict, { reasons: string[]; actions: string[] }>();
+  const hit = (v: Verdict, reason: string, action?: string): void => {
+    const row = hits.get(v) ?? { reasons: [], actions: [] };
+    row.reasons.push(reason);
+    if (action) row.actions.push(action);
+    hits.set(v, row);
+  };
+
+  // 관측 불가 — 판·공급·용량 셋 중 하나라도 못 잼.
+  const core: Array<[string, Cell<unknown>]> = [
+    ['판(발행 런)', s.release.run], ['판(체크리스트)', s.release.checklist],
+    ['공급(발사 가능 칸)', s.tasks.launchable], ['용량(빈 자리)', s.tasks.capacity],
+  ];
+  for (const [name, cell] of core) {
+    if (!measured(cell)) hit('unobservable', `${name} 못 잼(${cell.reason ?? '사유 없음'}) · 원천 ${cell.source}`, `계측 누락 칸: ${name}`);
+  }
+
+  // 막힘 — 발행 런이 승인을 기다리거나 동결 창.
+  const run = s.release.run.value;
+  if (run && run !== 'none' && run.waitingOn === 'approval') {
+    hit('blocked', `발행 런 ${run.runId.slice(0, 8)} 노드 ${run.currentNode ?? '?'} 승인 대기${run.elapsedMinutes !== null ? ` ${run.elapsedMinutes}분` : ''}`, '결정 카드 확인 — `elanous decisions list`');
+  }
+  const sched = s.release.schedule.value;
+  if (sched && sched !== 'none' && sched.freezeNow) hit('blocked', `동결 창 안(${s.release.version.value ?? '?'})`, '동결 해제 시각까지 착지 보류');
+
+  // 루프 정지 — 주기를 아는 루프의 박동이 끊김 · 프로세스 부재.
+  for (const loop of s.loops) {
+    const beat = loop.beat.value;
+    if (!beat) continue; // 못 잼은 «죽었다»가 아니다
+    const tag = loop.era === 'seat-era' ? ' [자리 시대 원천]' : '';
+    if (beat.alive === false) hit('loop-down', `${loop.name} 프로세스 없음(마지막 ${beat.lastAt})${tag}`, `${loop.name} 재기동`);
+    else if (loop.staleAfterSeconds !== null && beat.ageSeconds > loop.staleAfterSeconds) {
+      hit('loop-down', `${loop.name} 박동 ${Math.round(beat.ageSeconds / 60)}분 없음(한계 ${Math.round(loop.staleAfterSeconds / 60)}분)${tag}`, `${loop.name} 재기동`);
+    }
+  }
+
+  // 자원 포화 / 공급 부족 — 같은 스냅숏의 두 칸으로만.
+  const launchable = s.tasks.launchable.value;
+  const capacity = s.tasks.capacity.value;
+  if (launchable && capacity) {
+    if (launchable.count > 0 && capacity.free <= 0) {
+      hit('saturated', `발사 가능 칸 ${launchable.count} · 빈 자리 0 (Pod ${capacity.podUsed}/${capacity.podTarget} · 로컬 ${capacity.localUsed}/${capacity.localMax})`, '발사 늦추기 · 저우선 칸 보류(오케스트레이터)');
+    } else if (launchable.count === 0 && capacity.free > 0) {
+      const k = launchable.skipped;
+      hit('supply-empty', `빈 자리 ${capacity.free} · 발사 가능 칸 0 — 대상 경로 없음 ${k.noTargetPath} · 선행 미완 ${k.predecessorOpen} · 이미 넘김 ${k.alreadyHanded}`, '노란 칸 접지(대상 경로 채우기) — 스튜어드');
+    }
+  }
+
+  // 흐름 저하 — 묵은 부모 · 기계 압박.
+  const parents = s.machines.parents.value;
+  if (parents && parents.staleOver6h > 0) hit('degraded', `6시간 넘은 하니스 부모 ${parents.staleOver6h}(최고 ${parents.oldestHours}h)`, '고아 정리 — reaper');
+  for (const host of s.machines.hosts) {
+    const l = host.load.value;
+    if (l && l.cpuCount > 0 && l.load5 / l.cpuCount > LOAD_PER_CORE_PRESSURE) {
+      hit('degraded', `${host.name} 부하 ${l.load5.toFixed(0)}/${l.cpuCount}코어(5분)`, `${host.name} 로컬 레인 닫기 검토`);
+    }
+  }
+
+  for (const v of VERDICTS) {
+    const row = hits.get(v);
+    if (!row) continue;
+    // 이유 사슬: 이긴 판정의 사유 먼저, 그 밑에 진 판정들의 사유도 «부가»로 남긴다(한 사슬에 두 원인이 보이게).
+    const rest = VERDICTS.filter((o) => o !== v && hits.has(o)).flatMap((o) => hits.get(o)!.reasons.map((r) => `(+${VERDICT_LABEL[o]}) ${r}`));
+    return { verdict: v, reasons: [...row.reasons, ...rest], nextActions: row.actions };
+  }
+  return { verdict: 'flowing', reasons: [], nextActions: [] };
+}
+
+/** exit code — flowing·degraded 0 · 그 밖의 판정 3(수집기 자체 실패 1 은 호출자 몫). */
+export function verdictExitCode(v: Verdict): number {
+  return v === 'flowing' || v === 'degraded' ? 0 : 3;
+}
+
+export function unmeasuredCells(s: OverviewSnapshot): string[] {
+  const out: string[] = [];
+  const visit = (name: string, cell: Cell<unknown>): void => { if (cell.status === 'unmeasured') out.push(`${name}: ${cell.reason ?? ''}`); };
+  visit('release.version', s.release.version); visit('release.run', s.release.run);
+  visit('release.schedule', s.release.schedule); visit('release.checklist', s.release.checklist);
+  visit('tasks.byOwner', s.tasks.byOwner); visit('tasks.done', s.tasks.done);
+  visit('tasks.launchable', s.tasks.launchable); visit('tasks.capacity', s.tasks.capacity);
+  for (const h of s.machines.hosts) visit(`machines.${h.name}`, h.load);
+  for (const p of s.machines.pods) visit(`pods.${p.context}`, p.occupied);
+  visit('machines.parents', s.machines.parents); visit('landings', s.landings);
+  for (const l of s.loops) visit(`loops.${l.name}`, l.beat);
+  return out;
+}
+
+/** 사람 표기의 한 칸 — 못 잼은 `못 잼(<사유>)`. */
+export function show<T>(cell: Cell<T>, fmt: (v: T) => string): string {
+  if (cell.status === 'unmeasured' || cell.value === null) return `못 잼(${cell.reason ?? '사유 없음'})`;
+  return fmt(cell.value) + (cell.status === 'partial' && cell.reason ? ` (${cell.reason})` : '');
+}
+
+function kst(iso: string | null | undefined): string {
+  if (!iso) return '?';
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return iso;
+  const d = new Date(t + 9 * 3600_000);
+  return `${String(d.getUTCMonth() + 1).padStart(2, '0')}-${String(d.getUTCDate()).padStart(2, '0')} ${String(d.getUTCHours()).padStart(2, '0')}:${String(d.getUTCMinutes()).padStart(2, '0')}`;
+}
+
+export function renderOverview(s: OverviewSnapshot, v: VerdictResult, meta: { elapsedMs: number }): string {
+  const lines: string[] = [];
+  const mark = v.verdict === 'flowing' ? '✅' : v.verdict === 'degraded' ? '⚠️' : '⛔';
+  lines.push(`${mark} ${VERDICT_LABEL[v.verdict]} (${v.verdict})`);
+  for (const r of v.reasons) lines.push(`   ↳ ${r}`);
+  for (const a of v.nextActions) lines.push(`   → 다음 행동(제안): ${a}`);
+  const rel = s.release;
+  const runText = show(rel.run, (r) => r === 'none' ? '런 없음' : `런 ${r.runId.slice(0, 8)} ${r.status} · 노드 ${r.currentNode ?? '-'} · 대기 ${r.waitingOn}${r.elapsedMinutes !== null ? ` · ${r.elapsedMinutes}분` : ''}`);
+  const schedText = show(rel.schedule, (x) => x === 'none' ? '컷 미정' : `컷 ${kst(x.cutAt)} · 착지 마감 ${kst(x.landBy)}${x.publishAt ? ` · 발행 ${kst(x.publishAt)}` : ''}${x.freezeNow ? ' · 동결 중' : ''}`);
+  const clText = show(rel.checklist, (c) => `초록 ${c.green} 노랑 ${c.yellow} 빨강 ${c.red} · P0 노랑 ${c.p0Yellow}`);
+  lines.push(`판     ${show(rel.version, (x) => x)} · ${runText}`);
+  lines.push(`       ${schedText} · ${clText}`);
+  const owners = show(s.tasks.byOwner, (rows) => Object.entries(rows).sort().map(([o, r]) => `${o} 넘김 ${r.handed} 발사 ${r.launched}(PR ${r.prBound}) 실패 ${r.failed + r.launchFailed}`).join(' · ') || '오늘 카드 0');
+  lines.push(`일꾼   ${owners} · 끝 ${show(s.tasks.done, String)}`);
+  lines.push(`       발사 가능 ${show(s.tasks.launchable, (l) => `${l.count}${l.interim ? '(임시 술어)' : ''} · 대상 경로 없음 ${l.skipped.noTargetPath} · 선행 미완 ${l.skipped.predecessorOpen} · 이미 넘김 ${l.skipped.alreadyHanded}`)}`);
+  lines.push(`       빈 자리 ${show(s.tasks.capacity, (c) => `${c.free} (Pod ${c.podUsed}/${c.podTarget} · 로컬 ${c.localUsed}/${c.localMax})`)} [${s.tasks.capacity.source}]`);
+  const hosts = s.machines.hosts.map((h) => `${h.name} ${show(h.load, (l) => `${l.load1.toFixed(0)}/${l.cpuCount}코어 여유 ${l.freeGb.toFixed(0)}/${l.totalGb.toFixed(0)}GB (${l.ageSeconds}s 전)`)}`);
+  lines.push(`기계   ${hosts.join(' · ') || '못 잼(하트비트 원장 비어 있음)'}`);
+  lines.push(`       Pod ${s.machines.pods.map((p) => `${p.context} ${show(p.occupied, String)}/${p.capacity}`).join(' · ') || '못 잼(풀 설정 없음)'}`);
+  lines.push(`       하니스 부모(이 기계) ${show(s.machines.parents, (p) => `${p.count} · 6h 넘음 ${p.staleOver6h}${p.oldestHours !== null ? ` · 최고 ${p.oldestHours}h` : ''}`)}`);
+  lines.push(`착지   ${s.since} ${show(s.landings, (l) => `${l.count}`)} [${s.landings.source}]`);
+  for (const l of s.loops) {
+    lines.push(`루프   ${l.name}${l.era === 'seat-era' ? ' [자리 시대 원천]' : ''} ${show(l.beat, (b) => `${kst(b.lastAt)} (${Math.round(b.ageSeconds / 60)}분 전)${b.alive === null ? '' : b.alive ? ' 살아 있음' : ' 프로세스 없음'}${l.staleAfterSeconds === null ? ' · 주기 미상(판정 제외)' : ''}`)}`);
+  }
+  lines.push(`우주 ${s.instanceRoot} · ${kst(s.generatedAt)} KST · ${meta.elapsedMs}ms`);
+  return lines.join('\n');
+}

package/src/release-loop/gate-shards.ts

@@ -86,6 +86,9 @@ export interface GateShardsSummary {
   waitReasons: Array<{ reason: string; count: number }>;
   /** 남은 분 추정 — 계획 분이 모자라면 null(«추정 불가»). */
   etaMin: number | null;
+  /** 끝났지만 rc≠0 인 조각 수 — 쓰는 쪽의 `done` 은 «조각 끝»일 뿐 «통과»가 아니다(판정은 게이트 노드가 기존/새로 가른다).
+   *  0.2.20 컷 실측: 끝난 넷이 모두 rc 1 인데 화면이 «통과»로 읽었다. */
+  doneWithFailures: number;
   /** 도는 조각 중 계획 분을 가장 많이 넘긴 분(없으면 0). 넘겼으면 etaMin 은 «하한»일 뿐이라 화면이 그렇게 말한다
    *  — canary 10-07 실측: 계획 0.1분 · 실제 22분 → 넘김을 안 보이면 내내 «남은 약 0분». */
   overrunMin: number;
@@ -130,6 +133,7 @@ export function summarizeShards(file: GateShardsFile, now: number = Date.now()):
     total: file.shards.length,
     counts,
     waitReasons: [...reasons].map(([reason, count]) => ({ reason, count })).sort((a, b) => b.count - a.count),
+    doneWithFailures: file.shards.filter((s) => s.state === 'done' && s.rc !== undefined && s.rc !== 0).length,
     etaMin: estimate(file.shards, now),
     overrunMin: Math.floor(overrun),
     staleMin: stale === null ? null : Math.floor(stale),
@@ -137,7 +141,7 @@ export function summarizeShards(file: GateShardsFile, now: number = Date.now()):
 }
 
 export const SHARD_WORD: Record<ShardState, string> = {
-  pending: '대기', running: '돌기', done: '통과', retry: '재시도', timeout: '잘림', failed: '실패',
+  pending: '대기', running: '돌기', done: '끝', retry: '재시도', timeout: '잘림', failed: '실패',
 };
 
 /** 외출 알림·/release 한 줄 — «조각 24 · 돌기 5 · 대기 8(CPU 부족 8) · 잘림 2 · 통과 9 · 남은 약 40분». */
@@ -149,7 +153,8 @@ export function shardsLine(summary: GateShardsSummary): string {
     if (!n) continue;
     const why = state === 'pending' && summary.waitReasons.length
       ? `(${summary.waitReasons.slice(0, 2).map((w) => `${w.reason} ${w.count}`).join(' · ')})` : '';
-    parts.push(`${SHARD_WORD[state]} ${n}${why}`);
+    const reported = state === 'done' && summary.doneWithFailures ? `(실패 보고 ${summary.doneWithFailures})` : '';
+    parts.push(`${SHARD_WORD[state]} ${n}${why}${reported}`);
   }
   if (summary.overrunMin >= 1) parts.push(`계획보다 ${summary.overrunMin}분 넘게 도는 중 — 남은 시간 추정 불가`);
   else parts.push(summary.etaMin === null ? '남은 시간 추정 불가(계획 분 없음)' : `남은 약 ${summary.etaMin}분`);

package/src/self-dev/ask-launch-flow.ts

@@ -852,7 +852,7 @@ export async function runAskLaunchFlow(
   if (launchPreflight === false) return { kind: 'stopped-before-authoring' };
 
   await deps.beforeAuthoring?.();
-  const authorAndPreflight = async (authorAskText: string = input.askText): Promise<{
+  const authorAndPreflight = async (authorAskText: string = input.askText, machineSuggestedTargetPaths: readonly string[] = []): Promise<{
     readonly goalFile: string;
     readonly decision: ReturnType<typeof decideAskPreflight>;
   }> => {
@@ -950,6 +950,8 @@ export async function runAskLaunchFlow(
         recentChangeWindowDays: input.recentChangeWindowDays,
         openPrsLimit: OPEN_PR_LIMIT,
         ...(askOutsidePathHints.length > 0 ? { askOutsidePathHints } : {}),
+        // AUTO-TARGET: paths injected by the candidate search (not written in the ask) — a NOT-GROUNDED goal stops on them.
+        ...(machineSuggestedTargetPaths.length > 0 ? { machineSuggestedTargetPaths } : {}),
         declaredPathsRoot: deps.cwd(),
       },
       preflightDeps,
@@ -1032,7 +1034,7 @@ export async function runAskLaunchFlow(
     }
     authored = await authorAndPreflight(selectedPaths.length > 0
       ? `대상 경로: ${selectedPaths.join(' · ')}\n${input.askText}`
-      : input.askText);
+      : input.askText, selectedPaths);
     deps.log('ask-auto-reauthor', {
       candidatePathCount: candidates.paths.length,
       firstGoalFile: first.goalFile,

package/src/self-dev/ask-launch-io.ts

@@ -97,7 +97,7 @@ function inspectLaunchingTree(cwd: string): LaunchingTreeProbe {
 
 /** 발사 전 검사가 쓰는 조회 구현 — ⛔ 이 «한 벌»을 모든 표면이 공유한다. */
 export async function buildAskPreflightDeps(options: BuildAskPreflightDepsOptions = {}): Promise<AskPreflightDeps & { inspectLaunchingTree(cwd: string): LaunchingTreeProbe }> {
-  const [{ tracedPathReferences, verbatimOriginalAsk }, { loadRunLedger, queryFederatedCompletedRunLedgers, queryFederatedInterruptedRunLedgers, queryFederatedUnfinishedRunLedgers }] = await Promise.all([
+  const [{ tracedPathReferences, verbatimOriginalAsk, isNotGroundedWithoutPersistentEvidence }, { loadRunLedger, queryFederatedCompletedRunLedgers, queryFederatedInterruptedRunLedgers, queryFederatedUnfinishedRunLedgers }] = await Promise.all([
     import('../self-implement/goal-author.js'),
     import('../self-implement/run-ledger.js'),
   ]);
@@ -166,6 +166,8 @@ export async function buildAskPreflightDeps(options: BuildAskPreflightDepsOption
     //   ⛔ ask 표지가 없으면 빈 배열 — 그때는 표시가 «안 붙는다»(지어내지 않는다).
     askTargetPaths: (document: string) => parseAskTargetPathHints(verbatimOriginalAsk(document) ?? ''),
     askTargetPathRejections: (document: string) => parseAskTargetPathHintsResult(verbatimOriginalAsk(document) ?? '').rejected,
+    // AUTO-TARGET: a NOT-GROUNDED goal (no persistent evidence) is a scope card — machine-suggested paths do not launch it.
+    notGroundedWithoutPersistentEvidence: isNotGroundedWithoutPersistentEvidence,
     // ⭐ 충돌 문면이 경로마다 「대상/근거」를 말하게 한다 — 판정은 «안» 바꾼다(문면만 는다).
     //   ⛔ TRACED PATHS 는 「바꿀 파일」과 「근거로 읽은 파일」을 섞는다(실측: TRACED 8 · 변경 3).
     //     ⇒ 사람이 막혔을 때 「그게 근거였네」를 «즉시» 알 수 있어야 한다.

package/src/self-dev/graph-journey-nodes.ts

@@ -0,0 +1,157 @@
+import { randomUUID } from 'node:crypto';
+import { debug } from '../debug/log.js';
+import { GRAPH_SPECS, GRAPH_TEMPLATES, GRAPH_TEMPLATES_SOURCE, pipelineNodeEntryPayload, templateForGoalType, type GraphTemplate } from '../self-implement/graph-templates.js';
+import type { GoalType } from '../self-implement/goal-author.js';
+
+/** ⭐ HARNESS-FULL-GRAPH (0.2.21 · 대표 10-08) — 하니스 «여정» 전 단계를 그래프 노드로 선언·관측한다.
+ *
+ *  🩸 계기: `내부 문서 `TECH-harness-map-2026-10-06`` 차트의 단계 중 «입구·대기열·발사 관문·배치·Pod 입장·
+ *    이미지 동기화·자격 선갱신·동결 검사·보류·회수·실패 쪽(결과 해석·수확·heal·다음 한 수)»이
+ *    그래프 밖의 «맨 코드»였다. 공개 문서는 「그래프 선언이 모든 걸음을 대조한다」고 말한다 — 거짓이 되지 않게.
+ *
+ *  ⛔ 이 모듈은 «관측»이다(1단계) — 흐름을 바꾸지 않는다. 진입은 기존 노드와 «같은 사건»
+ *    (`self-implement` / `pipeline-node-entry` · 같은 `pipelineNodeEntryPayload`)으로 남겨
+ *    그래프 권위의 declared/undeclared 판정과 원장 질의가 이 노드들을 «같은 자»로 본다.
+ *    출구는 `pipeline-node-exit`(결과 `outcome` 포함)로 남긴다.
+ *  ⛔ fail-soft — 관측이 발사·착지를 죽이지 않는다.
+ *
+ *  🔗 조인(런 id 가 없는 앞단): 입구에서 `ELANOUS_JOURNEY_KEY` 를 한 번 만들어 환경에 싣는다.
+ *    자식 프로세스는 그 값을 물려받고, 오케스트레이터의 모든 파이프라인 관측에도 `journeyKey` 가 실린다.
+ *    ⇒ `journeyKey` 로 「runId 없이 남은 앞단 걸음」과 「runId 가 있는 후반 걸음」을 한 질의로 묶는다.
+ *    대기열을 거친 발사는 부모·자식 프로세스가 다르다 — 그 자리는 `queueLaunchId`(=`ELANOUS_HARNESS_QUEUE_LAUNCH`)가 잇는다.
+ *    설계 = 내부 문서 `RFC-harness-full-journey-as-graph-2026-10-08` §4. */
+
+/** 여정 노드 — ⛔ id 는 원장의 조인 키이자 라이브 그래프 화면(HARNESS-RUN-LIVE-GRAPH)의 키다. 바꾸지 마라. */
+export const JOURNEY_NODE_IDS = [
+  'intake',
+  'queue',
+  'launch-gate',
+  'dispatch',
+  'pool-admit',
+  'image-sync',
+  'credential-refresh',
+  'freeze-check',
+  'hold',
+  'cleanup',
+  'result-parse',
+  'salvage',
+  'heal',
+  'next-move',
+  'stopped',
+] as const;
+export type JourneyNodeId = typeof JOURNEY_NODE_IDS[number];
+
+export const JOURNEY_KEY_ENV = 'ELANOUS_JOURNEY_KEY';
+const QUEUE_LAUNCH_ENV = 'ELANOUS_HARNESS_QUEUE_LAUNCH';
+const RUN_ID_ENV = 'ELANOUS_RUN_ID';
+
+/** 이 여정의 조인 키 — 없으면 만들어 환경에 싣는다(자식이 물려받는다). */
+export function ensureJourneyKey(env: NodeJS.ProcessEnv = process.env): string {
+  const existing = env[JOURNEY_KEY_ENV]?.trim();
+  if (existing) return existing;
+  const key = `jrn-${randomUUID()}`;
+  env[JOURNEY_KEY_ENV] = key;
+  return key;
+}
+
+/** 관측 자리마다 펼치는 조인 칸(있는 것만). */
+export function journeyJoinFields(env: NodeJS.ProcessEnv = process.env): { journeyKey?: string; queueLaunchId?: string } {
+  const journeyKey = env[JOURNEY_KEY_ENV]?.trim();
+  const queueLaunchId = env[QUEUE_LAUNCH_ENV]?.trim();
+  return {
+    ...(journeyKey ? { journeyKey } : {}),
+    ...(queueLaunchId ? { queueLaunchId } : {}),
+  };
+}
+
+/** 여정 노드를 선언한 템플릿 — 골 종류의 템플릿이 그 노드를 선언하면 그것, 아니면 구현 루프. */
+export function journeyTemplate(node: string, goalType?: GoalType | null): GraphTemplate {
+  const own = goalType ? templateForGoalType(goalType) : null;
+  if (own && own.nodes.some((n) => n.nodeId === node)) return own;
+  return GRAPH_TEMPLATES['self-implement'] as GraphTemplate;
+}
+
+export interface JourneyObservation {
+  readonly provenance: string;
+  readonly outcome?: string;
+  readonly runId?: string;
+  readonly goalType?: GoalType | null;
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+
+function emit(entry: boolean, node: JourneyNodeId, o: JourneyObservation): void {
+  try {
+    const template = journeyTemplate(node, o.goalType);
+    const runId = o.runId ?? process.env[RUN_ID_ENV]?.trim();
+    const fields = {
+      node,
+      round: 0,
+      phase: 'journey',
+      provenance: o.provenance,
+      ...(o.outcome === undefined ? {} : { outcome: o.outcome }),
+      ...(runId ? { runId } : {}),
+      ...(o.goalType ? { goalType: o.goalType } : {}),
+      ...journeyJoinFields(),
+      ...o.data,
+      graphTemplatesSource: GRAPH_TEMPLATES_SOURCE,
+    };
+    // ⛔ 진입은 «공용 payload» 를 그 호출 안에서 펼친다 — 우회 가드(graph-templates.ts)가 행 단위로 문다.
+    if (entry) debug.log('self-implement', 'pipeline-node-entry', { ...pipelineNodeEntryPayload(template, node), ...fields });
+    else debug.log('self-implement', 'pipeline-node-exit', { ...pipelineNodeEntryPayload(template, node), ...fields });
+  } catch { /* 관측은 fail-soft */ }
+}
+
+/** 노드 진입. */
+export function enterJourneyNode(node: JourneyNodeId, o: JourneyObservation): void {
+  emit(true, node, o);
+}
+
+/** 노드 출구 — `outcome` 이 그 노드에서 나간 간선의 라벨(YAML `map` 키)이다.
+ *  ⭐ 그 라벨이 선언에서 종결 노드 `stopped` 로 가면 `stopped` 진입도 남긴다 — 거절·포기 런이 «선언된 종결점»에서 끝난다.
+ *  `outcome: 'error'` = 노드 안 작업이 예외를 던졌다(예외는 호출자에게 그대로 간다). */
+export function exitJourneyNode(node: JourneyNodeId, o: JourneyObservation & { readonly outcome: string }): void {
+  emit(false, node, o);
+  if (node !== 'stopped' && journeyEdgeTarget(node, o.outcome) === 'stopped') {
+    const { outcome: _outcome, ...rest } = o;
+    emit(true, 'stopped', { ...rest, provenance: `${node}:${o.outcome}` });
+  }
+}
+
+/** 선언(기준 YAML)에서 `from` 의 `label` 간선이 가는 노드. 없으면 undefined. */
+export function journeyEdgeTarget(from: string, label: string): string | undefined {
+  try {
+    for (const edge of GRAPH_SPECS['self-implement']?.edges ?? []) {
+      if (edge.from === from && edge.map !== undefined && Object.hasOwn(edge.map, label)) return edge.map[label];
+    }
+  } catch { /* 관측 보조 — 실패해도 출구는 이미 남았다 */ }
+  return undefined;
+}
+
+/** 노드 안 작업을 감싼다 — 예외면 출구 `error` 를 남기고 다시 던진다(진입 뒤 출구가 빠지지 않게). */
+export function withJourneyNode<T>(node: JourneyNodeId, o: JourneyObservation, work: () => Promise<T>): Promise<T> {
+  const onError = (error: unknown): void => {
+    exitJourneyNode(node, { ...o, outcome: 'error', data: { ...o.data, error: error instanceof Error ? error.message : String(error) } });
+  };
+  let pending: Promise<T>;
+  try { pending = work(); }
+  catch (error) { onError(error); throw error; }
+  // ⛔ 같은 약속을 «그대로» 돌려준다 — async/await 로 감싸면 마이크로태스크가 늘어 호출자의 순서가 밀린다
+  //   (2판에서 self-implement-pod 시험이 그 차이를 잡았다). 관측은 곁가지(.then)로만 붙인다.
+  pending.then(undefined, onError);
+  return pending;
+}
+
+/** 동기 판. */
+export function withJourneyNodeSync<T>(node: JourneyNodeId, o: JourneyObservation, work: () => T): T {
+  try { return work(); }
+  catch (error) {
+    exitJourneyNode(node, { ...o, outcome: 'error', data: { ...o.data, error: error instanceof Error ? error.message : String(error) } });
+    throw error;
+  }
+}
+
+/** 진입·출구를 한 번에 — 판정만 하는 노드(대기 없는 관문)용. */
+export function passJourneyNode(node: JourneyNodeId, o: JourneyObservation & { readonly outcome: string }): void {
+  enterJourneyNode(node, o);
+  exitJourneyNode(node, o);
+}

package/src/self-dev/graph-journey-route.ts

@@ -0,0 +1,105 @@
+import { debug } from '../debug/log.js';
+import { GRAPH_SPECS } from '../self-implement/graph-templates.js';
+import { applyGraphOverlays, defaultOverlaysDir, loadGraphOverlays, selectOverlays, type GraphOverlaySpec } from '../self-implement/graph-overlay-yaml.js';
+import type { GraphTemplateSpec } from '../self-implement/graph-yaml.js';
+import { journeyJoinFields } from './graph-journey-nodes.js';
+
+/** ⭐ HARNESS-FULL-GRAPH 2판 — 「다음 노드」를 코드가 아니라 «그래프»가 정한다.
+ *
+ *  대표 10-08: *«그래프에 따라 실제 경로가 바뀌어야 한다. 기본은 풀세트, 환경 셋업·운영 방법에 따라 일부만 걷거나 생략.»*
+ *  ⇒ 코드는 «상태 값»(queue=queued|direct · substrate=local|pod · freeze=open|frozen …)만 낸다.
+ *    그 값으로 «어느 간선을 타나»는 YAML 의 `on:`/`map:`(⊕ `stage: launch` 오버레이)이 정한다.
+ *  ⛔ 기본 YAML 은 오늘 코드와 «같은 길»을 낸다 — 시험이 그 동치를 문다(graph-journey-route.test.ts).
+ *  ⛔ 그래프가 답을 못 내면(간선 없음·로드 실패) 코드 기본으로 간다 — 그 사실을 `source: 'code-default'` 로 남긴다.
+ *  🔎 관측: `self-implement` / `graph-edge-taken` { from, on, label, to, source, overlays } */
+
+export interface JourneyRoute {
+  readonly from: string;
+  readonly on: string | null;
+  readonly label: string;
+  /** 그래프가 고른 다음 노드. 못 고르면 null. */
+  readonly to: string | null;
+  readonly source: 'graph' | 'code-default';
+  readonly overlays: readonly string[];
+}
+
+/** ⛔ 캐시하지 않는다 — 여러 런을 처리하는 프로세스(데몬·대기열 tick)가 다음 발사에서 오버레이 변경을 봐야 한다.
+ *  여정 판정은 발사당 몇 번뿐이라 디렉터리 한 번 읽기가 싸다. */
+let overlaysForTesting: readonly GraphOverlaySpec[] | undefined;
+function launchOverlays(): readonly GraphOverlaySpec[] {
+  if (overlaysForTesting !== undefined) return overlaysForTesting;
+  try { return loadGraphOverlays(defaultOverlaysDir()).overlays; }
+  catch { return []; }
+}
+
+/** 시험 전용 — 오버레이 묶음을 고정한다(undefined 면 디스크에서 읽는다). */
+export function setJourneyOverlaysForTesting(overlays: readonly GraphOverlaySpec[] | undefined): void {
+  overlaysForTesting = overlays;
+}
+
+/** 상태 값으로 고른 «이 런의 여정 선언» — 기준 YAML ⊕ 조건이 맞는 launch 오버레이. */
+export function journeySpec(
+  state: Readonly<Record<string, unknown>>,
+  base: GraphTemplateSpec | undefined = GRAPH_SPECS['self-implement'],
+  overlays: readonly GraphOverlaySpec[] = launchOverlays(),
+): { readonly spec: GraphTemplateSpec | undefined; readonly applied: readonly string[] } {
+  if (base === undefined) return { spec: undefined, applied: [] };
+  try {
+    const { applied } = selectOverlays(overlays, { graphId: base.graphId, stage: 'launch', state });
+    if (applied.length === 0) return { spec: base, applied: [] };
+    const result = applyGraphOverlays(base, applied);
+    // ⛔ 거절된 오버레이는 길을 바꾸지 않는다 — 기준 선언으로 간다.
+    return result.ok ? { spec: result.template, applied: result.overlayIds } : { spec: base, applied: [] };
+  } catch {
+    return { spec: base, applied: [] };
+  }
+}
+
+/** `from` 노드에서 `label` 로 나가는 다음 노드를 그래프에서 «읽는다»(기록하지 않는다).
+ *  ⛔ 판독과 기록을 가른다 — 실제로 탄 간선은 전제 검사·실제 단계 경계 «뒤»에 `recordJourneyEdge` 로 남긴다. */
+export function readJourneyEdge(
+  from: string,
+  label: string,
+  state: Readonly<Record<string, unknown>> = {},
+  deps: { readonly base?: GraphTemplateSpec; readonly overlays?: readonly GraphOverlaySpec[] } = {},
+): JourneyRoute {
+  const { spec, applied } = journeySpec(state, deps.base ?? GRAPH_SPECS['self-implement'], deps.overlays ?? launchOverlays());
+  let route: JourneyRoute = { from, on: null, label, to: null, source: 'code-default', overlays: applied };
+  for (const edge of spec?.edges ?? []) {
+    if (edge.from !== from) continue;
+    if (edge.map !== undefined && Object.hasOwn(edge.map, label)) {
+      route = { from, on: edge.on ?? null, label, to: edge.map[label]!, source: 'graph', overlays: applied };
+      break;
+    }
+  }
+  return route;
+}
+
+/** 실제로 탄 간선을 남긴다 — `taken` 은 실제 다음 노드(그래프 답과 다르면 `honored: false` · 그 이유를 `reason` 에). */
+export function recordJourneyEdge(route: JourneyRoute, taken: string, reason?: string): void {
+  try {
+    debug.log('self-implement', 'graph-edge-taken', {
+      graphId: 'self-implement', ...route, taken, honored: route.to === null || route.to === taken,
+      ...(reason === undefined ? {} : { reason }), ...journeyJoinFields(),
+    });
+  } catch { /* 관측은 fail-soft */ }
+}
+
+/** 판독 ⊕ 그 자리에서 기록 — 판독 자리가 곧 실제 단계 경계일 때만 쓴다. */
+export function routeJourneyEdge(
+  from: string,
+  label: string,
+  state: Readonly<Record<string, unknown>> = {},
+  deps: { readonly base?: GraphTemplateSpec; readonly overlays?: readonly GraphOverlaySpec[] } = {},
+): JourneyRoute {
+  const route = readJourneyEdge(from, label, state, deps);
+  recordJourneyEdge(route, route.to ?? label);
+  return route;
+}
+
+/** 입구의 대기열 갈래 — 그래프가 고른 다음 노드로 정한다. 그래프가 답을 못 내면 코드 라벨을 따른다.
+ *  ⛔ `eligible`(자리 있음 · 대기열 자식 아님 · --no-queue 아님)은 그래프가 못 넘는 전제다. */
+export function intakeTakesQueue(label: 'queued' | 'direct', route: Pick<JourneyRoute, 'source' | 'to'>, eligible: boolean): boolean {
+  const graphQueues = route.source === 'graph' ? route.to === 'queue' : label === 'queued';
+  return graphQueues && eligible;
+}