elanous 0.2.19 → 0.2.21

package/src/ops/overview-collect.ts

@@ -0,0 +1,345 @@
+/**
+ * OPS-OVERVIEW-CLI 첫 조각 — 수집기(한 시점에 모은다 · RFC §A1 «같은 스냅숏»).
+ * ⛔ ssh 0 · kubectl 0 · GitHub 호출 0(호출 경로). 칸마다 실패는 그 칸만 «못 잼».
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import type { Checklist, ChecklistItem } from '../release-loop/checklist.js';
+import type { ReleaseSchedule } from '../release-loop/release-schedule.js';
+import type { ResourceView } from '../control-plane/ledger.js';
+import type { TaskCard } from '../task-agent/task-hand.js';
+import {
+  okCell, unmeasured, type Cell, type CapacityInfo, type ChecklistCounts, type LaunchableInfo, type LoopRow, type MachineRow,
+  type OverviewSnapshot, type OwnerTaskRow, type ParentsInfo, type PodMemberRow, type ReleaseRunInfo, type ScheduleInfo,
+} from './overview.js';
+import { SEAT_ERA_SOURCE, readDispatcherBeats, readDispatcherCapacity, readSeatEraHanded, seatEraFeederDir } from './overview-seat-era.js';
+
+const GB = 1024 ** 3;
+/** 하트비트 주기 30 s × 2 (RFC §A2 «낡음»). */
+const HEARTBEAT_STALE_S = 60;
+/** 디스패처 주기 ≈ 5.5 분 × 2. */
+const DISPATCHER_STALE_S = 11 * 60;
+const STALE_PARENT_S = 6 * 3600;
+const TARGET_PATH = /대상 경로:/;
+
+export interface CollectOptions {
+  version?: string;
+  sinceMs: number;
+  sinceLabel: string;
+  owner?: string;
+  now?: number;
+  root?: string;
+  seatEraDir?: string;
+}
+
+const iso = (ms: number): string => new Date(ms).toISOString();
+const errText = (error: unknown): string => (error instanceof Error ? error.message : String(error)).split('\n')[0]!.slice(0, 160);
+
+function pickVersion(explicit: string | undefined, schedules: ReleaseSchedule[], now: number): string | null {
+  if (explicit) return explicit;
+  const upcoming = schedules.filter((s) => Date.parse(s.cutAt) > now).sort((a, b) => a.cutAt.localeCompare(b.cutAt));
+  return upcoming[0]?.version ?? null;
+}
+
+export function countChecklist(items: readonly ChecklistItem[]): ChecklistCounts {
+  const c: ChecklistCounts = { green: 0, yellow: 0, red: 0, done: 0, p0Yellow: 0 };
+  for (const it of items) {
+    c[it.status]++;
+    if (it.status === 'yellow' && it.priority === 'P0') c.p0Yellow++;
+  }
+  return c;
+}
+
+/**
+ * ⚠️ 임시 «발사 가능» 술어 — 오케스트레이터가 아직 술어를 export 하지 않는다(OVW-DISPATCH-LEDGER).
+ * 노랑 ∧ 제목에 «대상 경로:» ∧ 아직 안 넘김(TASK-AGENT checklistId ⊕ 자리 시대 handed) ∧ 선행 모두 초록/끝.
+ */
+export function launchableCells(checklists: readonly Checklist[], handed: ReadonlySet<string>): LaunchableInfo {
+  const status = new Map<string, ChecklistItem['status']>();
+  for (const cl of checklists) for (const it of cl.items) if (!status.has(it.id)) status.set(it.id, it.status);
+  const ids: string[] = [];
+  const skipped = { noTargetPath: 0, predecessorOpen: 0, alreadyHanded: 0 };
+  for (const cl of checklists) for (const it of cl.items) {
+    if (it.status !== 'yellow') continue;
+    if (handed.has(it.id)) { skipped.alreadyHanded++; continue; }
+    if (!TARGET_PATH.test(it.title)) { skipped.noTargetPath++; continue; }
+    const open = (it.predecessors ?? []).some((p) => { const st = status.get(p); return st !== undefined && st !== 'green' && st !== 'done'; });
+    if (open) { skipped.predecessorOpen++; continue; }
+    ids.push(it.id);
+  }
+  return { count: ids.length, ids: ids.slice(0, 20), skipped, interim: true };
+}
+
+export function ownerRows(cards: readonly TaskCard[], sinceIso: string, ownerFilter?: string): Record<string, OwnerTaskRow> {
+  const rows: Record<string, OwnerTaskRow> = {};
+  for (const card of cards) {
+    if (!card || typeof card.createdAt !== 'string' || card.createdAt < sinceIso) continue;
+    const owner = card.seat ? `seat:${card.seat}` : 'unassigned';
+    if (ownerFilter && ownerFilter !== 'all' && owner !== ownerFilter && owner !== `seat:${ownerFilter}`) continue;
+    const row = rows[owner] ??= { handed: 0, launched: 0, prBound: 0, failed: 0, launchFailed: 0 };
+    if (card.status === 'handed') row.handed++;
+    else if (card.status === 'launched') row.launched++;
+    else if (card.status === 'failed') row.failed++;
+    else if (card.status === 'launch-failed') row.launchFailed++;
+    if ((card.history ?? []).some((h) => h.event === 'pr-bound')) row.prBound++;
+  }
+  return rows;
+}
+
+/** `[[dd-]hh:]mm:ss` → 초. */
+export function parseEtime(etime: string): number | null {
+  const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(etime.trim());
+  if (!m) return null;
+  return Number(m[1] ?? 0) * 86400 + Number(m[2] ?? 0) * 3600 + Number(m[3]) * 60 + Number(m[4]);
+}
+
+const HARNESS_PARENT = /elanous\.mjs .*\bharness (?:say|ask)\b/;
+
+/** `ps -axo etime=,command=` 출력 → 하니스 부모 요약(RFC §S «재는 명령»과 같은 술어). */
+export function summarizeParents(psOut: string): ParentsInfo {
+  let count = 0; let stale = 0; let oldest = -1;
+  for (const line of psOut.split('\n')) {
+    const m = /^\s*(\S+)\s+(.*)$/.exec(line);
+    if (!m || !HARNESS_PARENT.test(m[2]!)) continue;
+    const s = parseEtime(m[1]!);
+    count++;
+    if (s !== null) { if (s > STALE_PARENT_S) stale++; if (s > oldest) oldest = s; }
+  }
+  return { count, staleOver6h: stale, oldestHours: oldest < 0 ? null : Math.round(oldest / 360) / 10 };
+}
+
+function collectRelease(root: string, version: string | null, schedules: ReleaseSchedule[] | Error, now: number,
+  readRuns: (dir: string) => Array<{ runId: string; status: string; startedAt: string; version: string | null; nodes: Array<{ nodeId: string; ok: boolean | null; startedAt?: string }> }> | 'unavailable',
+  readList: (v: string) => Checklist): OverviewSnapshot['release'] {
+  const versionCell: Cell<string> = version ? okCell(version, 'release schedule(다음 컷)', iso(now)) : unmeasured('release schedule', schedules instanceof Error ? `스케줄 못 읽음: ${errText(schedules)}` : '앞으로의 컷이 없음 — --version 으로 지정');
+  let schedule: Cell<ScheduleInfo | 'none'>;
+  if (schedules instanceof Error) schedule = unmeasured('release schedule', errText(schedules));
+  else if (!version) schedule = okCell('none', 'release schedule', iso(now));
+  else {
+    const row = schedules.find((s) => s.version === version);
+    schedule = okCell(row ? {
+      cutAt: row.cutAt, landBy: row.landBy, publishAt: row.publishAt ?? null,
+      freezeNow: !!(row.freezeFrom && row.freezeUntil && Date.parse(row.freezeFrom) <= now && now < Date.parse(row.freezeUntil)),
+    } : 'none', 'release schedule', iso(now));
+  }
+  let checklist: Cell<ChecklistCounts>;
+  if (!version) checklist = unmeasured('release checklist', '판 미정');
+  else {
+    try { checklist = okCell(countChecklist(readList(version).items), `release checklist(${version})`, iso(now)); }
+    catch (error) { checklist = unmeasured(`release checklist(${version})`, errText(error)); }
+  }
+  const dir = join(root, 'graph-runs', 'release-loop');
+  let run: Cell<ReleaseRunInfo | 'none'>;
+  try {
+    const runs = readRuns(dir);
+    if (runs === 'unavailable') run = unmeasured(dir, 'runs-unavailable');
+    else if (runs.length === 0) run = okCell('none', dir, iso(now));
+    else {
+      const r = runs[0]!;
+      const current = r.nodes.find((n) => n.ok === null) ?? null;
+      let pidAliveFlag: boolean | null = null;
+      try {
+        const raw = JSON.parse(readFileSync(join(dir, `${r.runId}.json`), 'utf8')) as { pid?: unknown };
+        if (typeof raw.pid === 'number') { try { process.kill(raw.pid, 0); pidAliveFlag = true; } catch (e) { pidAliveFlag = (e as NodeJS.ErrnoException).code === 'EPERM'; } }
+      } catch { /* pid 모름 */ }
+      const node = current?.nodeId ?? null;
+      const waitingOn: ReleaseRunInfo['waitingOn'] = r.status !== 'running' ? 'none'
+        : node && /approv/i.test(node) ? 'approval'
+          : pidAliveFlag === false ? 'process-gone'
+            : node && /gate/i.test(node) ? 'gate' : 'none';
+      const startedMs = Date.parse(current?.startedAt ?? r.startedAt);
+      run = okCell({ runId: r.runId, status: r.status, currentNode: node, startedAt: r.startedAt, waitingOn,
+        elapsedMinutes: Number.isNaN(startedMs) ? null : Math.round((now - startedMs) / 60000) }, `release run ledger(${r.version ?? '?'})`, iso(now));
+    }
+  } catch (error) { run = unmeasured(dir, errText(error)); }
+  return { version: versionCell, run, schedule, checklist };
+}
+
+function collectMachines(root: string, ledgerRows: ResourceView[] | Error, poolSpec: string | null, psOut: string | Error, now: number): OverviewSnapshot['machines'] {
+  const expected = new Set<string>();
+  const pods: PodMemberRow[] = [];
+  if (poolSpec) {
+    for (const part of poolSpec.split(',').map((p) => p.trim()).filter(Boolean)) {
+      const m = /^([^@:#]+)(?:@([^:#]+))?(?::(\d+))?/.exec(part);
+      if (!m) continue;
+      if (m[2]) expected.add(m[2]);
+      pods.push({ context: m[1]!, capacity: m[3] === undefined ? 2 : Number(m[3]),
+        occupied: unmeasured('pod pool', '호출 경로 kubectl 금지 — 멤버별 점유는 데몬 백그라운드 측정기(OVW-API) 대기') });
+    }
+  }
+  const hosts: MachineRow[] = [];
+  if (ledgerRows instanceof Error) {
+    for (const name of expected) hosts.push({ name, load: unmeasured('control ledger', errText(ledgerRows)) });
+  } else {
+    const machines = ledgerRows.filter((r) => r.kind === 'machine');
+    for (const r of machines) expected.add(r.machine);
+    for (const name of [...expected].sort()) {
+      const row = machines.find((r) => r.machine === name);
+      const load = (row?.attrs as { load?: { loadAvg?: number[]; cpuCount?: number; freeMem?: number; totalMem?: number; observedAt?: number } } | undefined)?.load;
+      if (!row || !load || !Array.isArray(load.loadAvg)) { hosts.push({ name, load: unmeasured('control ledger heartbeat', '하트비트 없음') }); continue; }
+      const observed = typeof load.observedAt === 'number' ? load.observedAt : row.observedAt;
+      const [l1, l5, l15] = load.loadAvg;
+      const num = (x: unknown): x is number => typeof x === 'number' && Number.isFinite(x);
+      if (!num(l1) || !num(l5) || !num(l15) || !num(load.cpuCount) || load.cpuCount <= 0 || !num(load.freeMem) || !num(load.totalMem)) {
+        hosts.push({ name, load: unmeasured('control ledger heartbeat', '하트비트 항목 빠짐(loadAvg·cpuCount·freeMem·totalMem)', iso(observed)) });
+        continue;
+      }
+      const age = Math.max(0, Math.round((now - observed) / 1000));
+      const value = { load1: l1, load5: l5, load15: l15, cpuCount: load.cpuCount,
+        freeGb: load.freeMem / GB, totalGb: load.totalMem / GB, ageSeconds: age };
+      hosts.push({ name, load: age > HEARTBEAT_STALE_S
+        ? unmeasured('control ledger heartbeat', `낡음(${age}초)`, iso(observed))
+        : okCell(value, 'control ledger heartbeat', iso(observed)) });
+    }
+  }
+  const parents: Cell<ParentsInfo> = psOut instanceof Error
+    ? unmeasured(`ps(${hostname()})`, `ps-exec 실패: ${errText(psOut)}`)
+    : okCell(summarizeParents(psOut), `ps(${hostname()} 로컬만 — 다른 기계는 OVW-MACHINE-HB)`, iso(now));
+  void root;
+  return { hosts, pods, parents };
+}
+
+export interface CollectDeps {
+  listSchedules?: () => ReleaseSchedule[];
+  listChecklist?: (v: string) => Checklist;
+  readRuns?: (dir: string) => ReturnType<Parameters<typeof collectRelease>[4]>;
+  readCards?: () => TaskCard[];
+  ledger?: () => ResourceView[];
+  poolSpec?: () => string | null;
+  ps?: () => string;
+  gitLog?: (sinceIso: string) => { lines: string[]; observedAt: string } ;
+}
+
+async function defaultDeps(root: string): Promise<Required<CollectDeps>> {
+  const [{ listSchedules }, { listChecklist }, { readReleaseRuns }, { readTaskAgentState, taskAgentStatePath }, { ResourceLedger }, { getUserConfig }] = await Promise.all([
+    import('../release-loop/release-schedule.js'), import('../release-loop/checklist.js'), import('../nexus/api/ops-api.js'),
+    import('../task-agent/task-hand.js'), import('../control-plane/ledger.js'), import('../user-config.js'),
+  ]);
+  return {
+    listSchedules: () => listSchedules(),
+    listChecklist: (v) => listChecklist(v),
+    readRuns: (dir) => readReleaseRuns(null, dir),
+    readCards: () => {
+      const state = readTaskAgentState<{ tasks?: Record<string, TaskCard> | TaskCard[] }>(taskAgentStatePath());
+      const t = state.tasks ?? {};
+      return Array.isArray(t) ? t : Object.values(t);
+    },
+    ledger: () => new ResourceLedger(root).list({ kind: 'machine' }),
+    poolSpec: () => {
+      const c = getUserConfig() as { harness?: { podPool?: string }; pod?: { pool?: string } };
+      return process.env.ELANOUS_POD_POOL?.trim() || c.harness?.podPool || c.pod?.pool || null;
+    },
+    ps: () => execFileSync('ps', ['-axo', 'etime=,command='], { encoding: 'utf8', timeout: 1_500, maxBuffer: 32 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }),
+    gitLog: (sinceIso) => {
+      const c = getUserConfig() as { harness?: { defaultRepo?: string } };
+      const repo = c.harness?.defaultRepo;
+      if (!repo) throw new Error('harness.defaultRepo 없음');
+      let fetched: number;
+      try { fetched = statSync(join(repo, '.git', 'FETCH_HEAD')).mtimeMs; } catch { throw new Error(`FETCH_HEAD 없음(${repo})`); }
+      const out = execFileSync('git', ['-C', repo, 'log', 'refs/remotes/origin/main', `--since=${sinceIso}`, '--first-parent', '--format=%cI%x09%s'],
+        { encoding: 'utf8', timeout: 1_000, stdio: ['ignore', 'pipe', 'ignore'] });
+      return { lines: out.split('\n').filter(Boolean), observedAt: iso(fetched) };
+    },
+  };
+}
+
+/** 착지 원천(git origin/main)의 fetch 가 이보다 낡으면 «못 잼»(낡음). */
+const LANDINGS_STALE_S = 30 * 60;
+
+export async function collectOverview(opts: CollectOptions, injected: CollectDeps = {}): Promise<OverviewSnapshot> {
+  const now = opts.now ?? Date.now();
+  const root = opts.root ?? effectiveInstanceRoot();
+  const deps = { ...(await defaultDeps(root)), ...injected };
+  const seatDir = opts.seatEraDir ?? seatEraFeederDir();
+  const sinceIso = iso(now - opts.sinceMs);
+
+  let schedules: ReleaseSchedule[] | Error;
+  try { schedules = deps.listSchedules(); } catch (error) { schedules = error instanceof Error ? error : new Error(String(error)); }
+  const version = pickVersion(opts.version, schedules instanceof Error ? [] : schedules, now);
+  const release = collectRelease(root, version, schedules, now, deps.readRuns, deps.listChecklist);
+
+  // 일꾼 — 오늘(KST 0시) 이후 카드.
+  const kstMidnight = iso(Math.floor((now + 9 * 3600_000) / 86400_000) * 86400_000 - 9 * 3600_000);
+  let cards: TaskCard[] | Error;
+  try { cards = deps.readCards(); } catch (error) { cards = error instanceof Error ? error : new Error(String(error)); }
+  const byOwner: Cell<Record<string, OwnerTaskRow>> = cards instanceof Error
+    ? unmeasured('task-agent ledger', errText(cards))
+    : okCell(ownerRows(cards, kstMidnight, opts.owner), `task-agent ledger(오늘 KST · owner=seat 키)`, iso(now));
+  const done = unmeasured<number>('task-agent ledger', '착지 판정은 PR 조회가 필요 — owner 모델(OVW-OWNER)·card-evidence 연결 전');
+
+  // 발사 가능 — 열린 판(앞으로의 컷) 전부.
+  let launchable: Cell<LaunchableInfo>;
+  if (schedules instanceof Error) launchable = unmeasured('release checklist', `스케줄 못 읽음: ${errText(schedules)}`);
+  else if (cards instanceof Error) launchable = unmeasured('task-agent ledger', `넘김 목록 못 읽음: ${errText(cards)}`);
+  else {
+    try {
+      const open = schedules.filter((s) => Date.parse(s.cutAt) > now).map((s) => s.version);
+      if (version && !open.includes(version)) open.push(version);
+      const lists = open.map((v) => deps.listChecklist(v));
+      const handed = new Set<string>([...cards.map((c) => c.checklistId).filter((x): x is string => typeof x === 'string'), ...readSeatEraHanded(seatDir)]);
+      launchable = okCell(launchableCells(lists, handed), `release checklist(${open.join(',')}) ⊕ task-agent ⊕ ${SEAT_ERA_SOURCE} handed · 임시 술어`, iso(now));
+    } catch (error) { launchable = unmeasured('release checklist', errText(error)); }
+  }
+
+  // 빈 자리 — 자리 시대 디스패처 로그(임시) · 호출 경로 kubectl 0.
+  const capLine = readDispatcherCapacity(seatDir, now);
+  let capacity: Cell<CapacityInfo>;
+  if ('error' in capLine) capacity = unmeasured(SEAT_ERA_SOURCE, capLine.error);
+  else if (capLine.ageSeconds > DISPATCHER_STALE_S) capacity = unmeasured(SEAT_ERA_SOURCE, `낡음(${Math.round(capLine.ageSeconds / 60)}분)`, capLine.at);
+  else {
+    const free = Math.max(0, capLine.podTarget - capLine.podUsed) + Math.max(0, capLine.localMax - capLine.localUsed);
+    capacity = okCell({ podUsed: capLine.podUsed, podTarget: capLine.podTarget, localUsed: capLine.localUsed, localMax: capLine.localMax, free }, `${SEAT_ERA_SOURCE} dispatcher-OP.out`, capLine.at);
+  }
+  const tasks = { byOwner, done, launchable, capacity };
+
+  let ledgerRows: ResourceView[] | Error;
+  try { ledgerRows = deps.ledger(); } catch (error) { ledgerRows = error instanceof Error ? error : new Error(String(error)); }
+  let poolSpec: string | null = null;
+  try { poolSpec = deps.poolSpec(); } catch { poolSpec = null; }
+  let psOut: string | Error;
+  try { psOut = deps.ps(); } catch (error) { psOut = error instanceof Error ? error : new Error(String(error)); }
+  const machines = collectMachines(root, ledgerRows, poolSpec, psOut, now);
+
+  let landings: Cell<{ count: number; recent: string[] }>;
+  try {
+    const { lines, observedAt } = deps.gitLog(sinceIso);
+    const age = Math.round((now - Date.parse(observedAt)) / 1000);
+    landings = age > LANDINGS_STALE_S
+      ? unmeasured('git origin/main(로컬 fetch)', `fetch 낡음(${Math.round(age / 60)}분)`, observedAt)
+      : okCell({ count: lines.length, recent: lines.slice(0, 5).map((l) => l.split('\t')[1] ?? l) }, `git origin/main(로컬 fetch ${Math.round(age / 60)}분 전)`, observedAt);
+  } catch (error) { landings = unmeasured('git origin/main(로컬 fetch)', errText(error)); }
+
+  const loops: LoopRow[] = [];
+  const productBeat = (name: string, paths: string[]): void => {
+    let newest = -1;
+    for (const p of paths) {
+      try {
+        const st = statSync(p);
+        if (st.isDirectory()) { for (const f of readdirSync(p)) { try { newest = Math.max(newest, statSync(join(p, f)).mtimeMs); } catch { /* skip */ } } }
+        else newest = Math.max(newest, st.mtimeMs);
+      } catch { /* 없음 */ }
+    }
+    loops.push({ name, era: 'product', staleAfterSeconds: null,
+      beat: newest < 0 ? unmeasured(paths.join(','), '원장 없음(계측 없음 — «죽었다» 아님)')
+        : okCell({ lastAt: iso(newest), ageSeconds: Math.max(0, Math.round((now - newest) / 1000)), alive: null }, `${paths.join(',')} mtime`, iso(newest)) });
+  };
+  productBeat('orchestrator', [join(root, 'orchestrator')]);
+  productBeat('steward', [join(root, 'steward', 'readiness.jsonl'), join(root, 'steward', 'streak.json')]);
+  for (const b of readDispatcherBeats(seatDir, now)) {
+    loops.push({ name: `dispatcher-${b.seat}`, era: 'seat-era', staleAfterSeconds: b.seat === 'OP' ? DISPATCHER_STALE_S : null,
+      beat: okCell({ lastAt: b.lastAt, ageSeconds: b.ageSeconds, alive: b.alive }, `${SEAT_ERA_SOURCE} dispatcher-${b.seat}.pid`, b.lastAt) });
+  }
+
+  return { generatedAt: iso(now), instanceRoot: root, since: opts.sinceLabel, release, tasks, machines, landings, loops };
+}
+
+export function parseSince(raw: string | undefined): { ms: number; label: string } {
+  const v = (raw ?? '1h').trim();
+  const m = /^(\d+)\s*(m|h|d)$/.exec(v);
+  if (!m) throw new Error(`--since 형식: <n>m|h|d (받음: ${v})`);
+  const n = Number(m[1]);
+  return { ms: n * (m[2] === 'm' ? 60_000 : m[2] === 'h' ? 3_600_000 : 86_400_000), label: `최근 ${v}` };
+}

package/src/ops/overview-seat-era.ts

@@ -0,0 +1,90 @@
+/**
+ * ⚠️ 자리 시대 원천(제품 «밖») — OPS-OVERVIEW-CLI 첫 조각의 «임시» 읽기 전용 리더.
+ *
+ * RFC §A3 는 overview 의 원천을 제품 원장·API 로만 둔다. 그런데 디스패처의 박동·Pod 사용 수·넘김 목록은
+ * 아직 `~/elanous-hq/seat-state/OP/feeder/` 의 PID 파일·stdout 로그에만 있다(OVW-DISPATCH-LEDGER 가 원장으로 옮긴다).
+ * 그때까지 이 파일 «하나»에 가둬 두고, 출력에는 항상 «자리 시대 원천» 표지를 붙인다. 옮겨지면 이 파일을 지운다.
+ * ⛔ 쓰지 않는다 · ⛔ ssh 하지 않는다 · 파일이 없으면 «못 잼»(0 아님).
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const SEAT_ERA_SOURCE = '자리 시대 원천(feeder)';
+
+export function seatEraFeederDir(home: string = homedir()): string {
+  return join(home, 'elanous-hq', 'seat-state', 'OP', 'feeder');
+}
+
+export interface DispatcherBeat { seat: string; pid: number | null; alive: boolean | null; lastAt: string; ageSeconds: number }
+
+/** `dispatcher-<자리>.pid` 마다 하나 — 박동 시각은 `.out` 이 있으면 그 mtime, 없으면 PID 파일 mtime. */
+export function readDispatcherBeats(dir: string, now: number, isAlive: (pid: number) => boolean = pidAlive): DispatcherBeat[] {
+  let names: string[];
+  try { names = readdirSync(dir); } catch { return []; }
+  const out: DispatcherBeat[] = [];
+  for (const name of names) {
+    const m = /^dispatcher-([A-Za-z]+)\.pid$/.exec(name);
+    if (!m) continue;
+    const seat = m[1]!;
+    let pid: number | null = null;
+    try { const n = Number(readFileSync(join(dir, name), 'utf8').trim()); pid = Number.isInteger(n) && n > 0 ? n : null; } catch { /* 못 읽음 */ }
+    let mtime: number;
+    try { mtime = statSync(join(dir, `dispatcher-${seat}.out`)).mtimeMs; } catch {
+      try { mtime = statSync(join(dir, name)).mtimeMs; } catch { continue; }
+    }
+    out.push({ seat, pid, alive: pid === null ? null : isAlive(pid), lastAt: new Date(mtime).toISOString(), ageSeconds: Math.max(0, Math.round((now - mtime) / 1000)) });
+  }
+  return out.sort((a, b) => a.seat.localeCompare(b.seat));
+}
+
+export function pidAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch (error) { return (error as NodeJS.ErrnoException).code === 'EPERM'; }
+}
+
+export interface DispatcherCapacityLine { at: string; podUsed: number; podTarget: number; localUsed: number; localMax: number }
+
+/** 디스패처 로그의 마지막 «Pod a/b · 로컬 c/d» 줄. 줄 머리 `HH:MM:SS` 는 로그 파일 mtime 의 날짜(KST)로 읽는다. */
+export function parseDispatcherCapacity(text: string): Omit<DispatcherCapacityLine, 'at'> & { hhmmss: string } | null {
+  const lines = text.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const m = /^(\d{2}:\d{2}:\d{2}) .*Pod (\d+)(?:\/(\d+))? · 로컬 (\d+)(?:\/(\d+))?/.exec(lines[i]!);
+    if (!m || m[3] === undefined) continue;
+    return { hhmmss: m[1]!, podUsed: Number(m[2]), podTarget: Number(m[3]), localUsed: Number(m[4]), localMax: m[5] === undefined ? 0 : Number(m[5]) };
+  }
+  return null;
+}
+
+export function readDispatcherCapacity(dir: string, now: number = Date.now()): (DispatcherCapacityLine & { ageSeconds: number }) | { error: string } {
+  const path = join(dir, 'dispatcher-OP.out');
+  let text: string; let mtime: number;
+  try { text = readFileSync(path, 'utf8'); mtime = statSync(path).mtimeMs; } catch (error) { return { error: `디스패처 로그 없음(${(error as NodeJS.ErrnoException).code ?? 'read'})` }; }
+  const parsed = parseDispatcherCapacity(text);
+  if (!parsed) return { error: '디스패처 로그에 «Pod a/b» 줄 없음' };
+  const at = lineTime(parsed.hhmmss, mtime);
+  return { at: new Date(at).toISOString(), ageSeconds: Math.max(0, Math.round((now - at) / 1000)),
+    podUsed: parsed.podUsed, podTarget: parsed.podTarget, localUsed: parsed.localUsed, localMax: parsed.localMax };
+}
+
+/**
+ * 줄 머리 `HH:MM:SS`(KST)의 절대 시각 — 날짜는 로그 mtime 의 KST 날짜이고, 그 시각이 mtime 보다 뒤면 전날이다.
+ * ⛔ mtime 을 관측 시각으로 쓰지 않는다 — 용량 줄 뒤에 다른 줄이 붙으면 낡은 값이 새것처럼 보인다.
+ */
+export function lineTime(hhmmss: string, mtimeMs: number): number {
+  const [h, m, s] = hhmmss.split(':').map(Number) as [number, number, number];
+  const KST = 9 * 3600_000;
+  const dayStartKst = Math.floor((mtimeMs + KST) / 86400_000) * 86400_000 - KST;
+  let t = dayStartKst + ((h * 60 + m) * 60 + s) * 1000;
+  if (t > mtimeMs + 1000) t -= 86400_000;
+  return t;
+}
+
+/** 디스패처가 손으로 쌓는 넘김 목록(`handed.txt`) — «없음»(ENOENT)만 빈 집합, 그 밖의 읽기 실패는 던진다(넘김 여부를 모르면 발사 가능을 셀 수 없다). */
+export function readSeatEraHanded(dir: string): Set<string> {
+  let text: string;
+  try { text = readFileSync(join(dir, 'handed.txt'), 'utf8'); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return new Set();
+    throw new Error(`handed.txt 못 읽음(${(error as NodeJS.ErrnoException).code ?? 'read'})`);
+  }
+  return new Set(text.split(/\s+/).filter(Boolean));
+}

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');
+}