elanous 0.2.0 → 0.2.5

package/src/launch-head/capability-check.ts

@@ -0,0 +1,162 @@
+/**
+ * 발사 앞 머리 ① — 골 문서만 보고 «Pod 로 가도 되나(any) · 이 기계에서만 되나(local-only)».
+ *
+ * 순수 함수다. 파일·네트워크·프로세스를 부르지 않는다. 입력은 인자로만 받는다.
+ * 요구 능력은 이 파일의 규칙 표 한 곳에서만 뽑는다.
+ */
+
+export type CapabilityOutcome = 'local-only' | 'any';
+
+export interface CapabilityCheckInput {
+  goalText: string;
+  /** 호출자가 이미 알고 있으면 넘긴다. 없으면 골 문서 첫 줄 `대상 경로:` 에서 읽는다. */
+  targetPaths?: readonly string[];
+}
+
+export interface CapabilityCheckResult {
+  outcome: CapabilityOutcome;
+  required: string[];
+  reasons: string[];
+}
+
+interface PathRule {
+  /** 경로 glob. `**` 는 슬래시를 포함한 나머지, `*` 는 슬래시를 제외한 한 조각. */
+  glob: string;
+  capability: string | null;
+}
+
+interface TextRule {
+  /** 골 문면에서 이 표지가 보이면 capability 를 요구한다. */
+  marker: string;
+  capability: string;
+}
+
+/**
+ * 대상 경로 → 요구 능력. `capability: null` 은 «이 경로는 요구가 없다»는 명시 규칙이다.
+ * 예: apps/ios/** → xcode · src/install/launchd* · **\/launchd*.ts → host-launchd · apps/pwa/** 는 요구 없음.
+ */
+export const PATH_CAPABILITY_RULES: readonly PathRule[] = [
+  { glob: 'apps/ios/**', capability: 'xcode' },
+  { glob: 'src/install/launchd*', capability: 'host-launchd' },
+  { glob: '**/launchd*.ts', capability: 'host-launchd' },
+  { glob: 'apps/pwa/**', capability: null },
+];
+
+/**
+ * 골 문면 표지 → 요구 능력.
+ * «라이브 TUI» · pty snapshot · --hold → live-tui
+ * «운영 우주» · ~/.elanous 에 쓰기 → host-universe
+ * 키체인 → host-keychain
+ */
+export const TEXT_CAPABILITY_RULES: readonly TextRule[] = [
+  { marker: '라이브 TUI', capability: 'live-tui' },
+  { marker: 'pty snapshot', capability: 'live-tui' },
+  { marker: '--hold', capability: 'live-tui' },
+  { marker: '운영 우주', capability: 'host-universe' },
+  { marker: '~/.elanous', capability: 'host-universe' },
+  { marker: '키체인', capability: 'host-keychain' },
+];
+
+/**
+ * Pod 가 가진 능력. 하나뿐인 상수.
+ *
+ * 빈 집합이다. 위 규칙이 이름으로 드는 능력(xcode · host-launchd · live-tui ·
+ * host-universe · host-keychain)은 전부 «이 기계에서만» 되는 호스트 능력이고,
+ * Pod 이미지 안에 없다고 이 골이 정한다. 요구가 하나도 없으면(규칙에 안 걸리는
+ * 경로 · apps/pwa/** 처럼 요구 없음으로 적힌 경로) 요구 ⊆ Pod 라 `any` 다.
+ * 요구가 하나라도 이 집합 밖이면 `local-only` 다.
+ */
+export const POD_CAPABILITIES: readonly string[] = [];
+
+const TARGET_PATHS_PREFIX = '대상 경로:';
+const NO_TARGET_PATHS_REASON = '대상 경로 없음';
+
+/** 골 문서 첫 줄 `대상 경로:` 를 `·` 로 갈라 읽는다. 표지가 없으면 빈 목록. */
+export function readTargetPaths(goalText: string): string[] {
+  const firstLine = goalText.split(/\r?\n/, 1)[0] ?? '';
+  const trimmed = firstLine.trim();
+  if (!trimmed.startsWith(TARGET_PATHS_PREFIX)) return [];
+  const rest = trimmed.slice(TARGET_PATHS_PREFIX.length).trim();
+  if (!rest) return [];
+  return rest.split('·').map((part) => part.trim()).filter((part) => part.length > 0);
+}
+
+function globToRegExp(glob: string): RegExp {
+  let source = '^';
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === '*' && glob[i + 1] === '*') {
+      source += '.*';
+      i++;
+      if (glob[i + 1] === '/') i++;
+    } else if (ch === '*') {
+      source += '[^/]*';
+    } else if (ch === '?') {
+      source += '[^/]';
+    } else if ('\\^$+?.()|{}[]'.includes(ch)) {
+      source += `\\${ch}`;
+    } else {
+      source += ch;
+    }
+  }
+  source += '$';
+  return new RegExp(source);
+}
+
+const PATH_RULE_REGEX: readonly { rule: PathRule; re: RegExp }[] = PATH_CAPABILITY_RULES.map((rule) => ({
+  rule,
+  re: globToRegExp(rule.glob),
+}));
+
+function capabilitiesForPath(targetPath: string): { capability: string; glob: string }[] {
+  const normalized = targetPath.replace(/\\/g, '/').replace(/^\.\//, '');
+  const hits: { capability: string; glob: string }[] = [];
+  for (const { rule, re } of PATH_RULE_REGEX) {
+    if (rule.capability && re.test(normalized)) hits.push({ capability: rule.capability, glob: rule.glob });
+  }
+  return hits;
+}
+
+export function checkCapability(input: CapabilityCheckInput): CapabilityCheckResult {
+  const goalText = input.goalText ?? '';
+  const explicit = input.targetPaths;
+  const fromDoc = readTargetPaths(goalText);
+  const targetPaths = explicit !== undefined ? [...explicit] : fromDoc;
+  const missingTargetPaths = targetPaths.length === 0;
+
+  const required: string[] = [];
+  const reasons: string[] = [];
+  const seen = new Set<string>();
+
+  const push = (capability: string, reason: string): void => {
+    if (!seen.has(capability)) {
+      seen.add(capability);
+      required.push(capability);
+    }
+    reasons.push(reason);
+  };
+
+  if (missingTargetPaths) reasons.push(NO_TARGET_PATHS_REASON);
+
+  for (const targetPath of targetPaths) {
+    for (const hit of capabilitiesForPath(targetPath)) {
+      push(hit.capability, `${targetPath} → ${hit.capability} (${hit.glob})`);
+    }
+  }
+
+  for (const rule of TEXT_CAPABILITY_RULES) {
+    if (goalText.includes(rule.marker)) {
+      push(rule.capability, `«${rule.marker}» → ${rule.capability}`);
+    }
+  }
+
+  const pod = new Set(POD_CAPABILITIES);
+  const blocked = required.filter((capability) => !pod.has(capability));
+  if (blocked.length === 0) {
+    return { outcome: 'any', required, reasons };
+  }
+  for (const capability of blocked) {
+    reasons.push(`${capability} 는 POD_CAPABILITIES 밖이라 local-only`);
+  }
+  return { outcome: 'local-only', required, reasons };
+}

package/src/launch-head/launch-head-cli.ts

@@ -0,0 +1,242 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { checkCapability, readTargetPaths, type CapabilityCheckResult } from './capability-check.js';
+import { rankMachines, type RankMachinesResult } from './load-balance.js';
+import type { ResourceView } from '../control-plane/ledger.js';
+
+export interface CapabilityCliIo {
+  readFile: (path: string) => string;
+  env: NodeJS.ProcessEnv;
+  log: (line: string) => void;
+  error: (line: string) => void;
+}
+
+export interface CapabilityCliOutcome {
+  code: number;
+  result?: CapabilityCheckResult;
+  error?: string;
+}
+
+const GRAPH_CONTEXT_ENV = 'ELANOUS_GRAPH_CONTEXT';
+
+function defaultIo(): CapabilityCliIo {
+  return {
+    readFile: (path) => readFileSync(path, 'utf8'),
+    env: process.env,
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+  };
+}
+
+function goalPathFromContext(raw: string): string | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined;
+  const input = (parsed as { input?: unknown }).input;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return undefined;
+  const goalPath = (input as { goal_path?: unknown }).goal_path;
+  return typeof goalPath === 'string' && goalPath.trim() ? goalPath : undefined;
+}
+
+/** 사람용 한 줄. JSON 은 호출자가 마지막 줄에 따로 찍는다. */
+export function formatCapabilityLine(result: CapabilityCheckResult): string {
+  const why = result.reasons.length > 0 ? result.reasons.join(' · ') : '(이유 없음)';
+  return `capability: ${result.outcome} (required: ${result.required.join(', ') || '없음'}) — ${why}`;
+}
+
+/**
+ * `elanous launch-head capability [--goal <경로>]`.
+ * `--goal` 이 없으면 `ELANOUS_GRAPH_CONTEXT` 파일의 `input.goal_path` 를 읽는다.
+ * 골 파일을 못 읽으면 rc 2 이고 `any` 를 내지 않는다.
+ */
+export function runCapabilityCheck(args: readonly string[], io: CapabilityCliIo = defaultIo()): CapabilityCliOutcome {
+  let goalFlag: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--goal') {
+      const value = args[i + 1];
+      if (!value || value.startsWith('--')) {
+        const error = 'launch-head capability: --goal 뒤에 골 경로가 없다';
+        io.error(error);
+        return { code: 2, error };
+      }
+      goalFlag = value;
+      i++;
+    } else if (arg.startsWith('--goal=')) {
+      const value = arg.slice('--goal='.length).trim();
+      if (!value) {
+        const error = 'launch-head capability: --goal 뒤에 골 경로가 없다';
+        io.error(error);
+        return { code: 2, error };
+      }
+      goalFlag = value;
+    }
+  }
+
+  let goalPath = goalFlag;
+  if (!goalPath) {
+    const contextPath = io.env[GRAPH_CONTEXT_ENV];
+    if (!contextPath || !contextPath.trim()) {
+      const error = `launch-head capability: --goal 이 없고 ${GRAPH_CONTEXT_ENV} 도 없다`;
+      io.error(error);
+      return { code: 2, error };
+    }
+    let contextRaw: string;
+    try {
+      contextRaw = io.readFile(contextPath);
+    } catch (error) {
+      const message = `launch-head capability: ${GRAPH_CONTEXT_ENV} 파일을 못 읽음 (${contextPath}): ${error instanceof Error ? error.message : String(error)}`;
+      io.error(message);
+      return { code: 2, error: message };
+    }
+    goalPath = goalPathFromContext(contextRaw);
+    if (!goalPath) {
+      const error = `launch-head capability: ${GRAPH_CONTEXT_ENV} 에 input.goal_path 가 없다`;
+      io.error(error);
+      return { code: 2, error };
+    }
+  }
+
+  let goalText: string;
+  try {
+    goalText = io.readFile(goalPath);
+  } catch (error) {
+    const message = `launch-head capability: 골 파일을 못 읽음 (${goalPath}): ${error instanceof Error ? error.message : String(error)}`;
+    io.error(message);
+    return { code: 2, error: message };
+  }
+
+  const result = checkCapability({ goalText, targetPaths: readTargetPaths(goalText) });
+  io.log(formatCapabilityLine(result));
+  io.log(JSON.stringify({ outcome: result.outcome, required: result.required, reasons: result.reasons }));
+  return { code: 0, result };
+}
+
+export interface BalanceCliIo extends CapabilityCliIo {
+  instanceRoot: () => string;
+  fetch: (input: string, init?: RequestInit) => Promise<Response>;
+  now: () => number;
+}
+
+export interface BalanceCliOutcome {
+  code: number;
+  result: RankMachinesResult;
+}
+
+function defaultBalanceIo(): BalanceCliIo {
+  return { ...defaultIo(), instanceRoot: effectiveInstanceRoot, fetch: globalThis.fetch, now: Date.now };
+}
+
+function requiredFromContext(raw: string): string[] {
+  const context: unknown = JSON.parse(raw);
+  if (!context || typeof context !== 'object' || Array.isArray(context)) throw new Error('outputs.capability.required 없음');
+  const outputs = (context as Record<string, unknown>).outputs;
+  if (!outputs || typeof outputs !== 'object' || Array.isArray(outputs)) throw new Error('outputs.capability.required 없음');
+  const capability = (outputs as Record<string, unknown>).capability;
+  if (!capability || typeof capability !== 'object' || Array.isArray(capability)) throw new Error('outputs.capability.required 없음');
+  const required = (capability as Record<string, unknown>).required;
+  if (!Array.isArray(required) || !required.every((value) => typeof value === 'string')) {
+    throw new Error('outputs.capability.required 없음 또는 잘못된 형식');
+  }
+  return required as string[];
+}
+
+/** `elanous launch-head balance [--json]`: the control ledger is the only machine source. */
+export async function runLoadBalance(_args: readonly string[], io: BalanceCliIo = defaultBalanceIo()): Promise<BalanceCliOutcome> {
+  const emit = (result: RankMachinesResult, code: number): BalanceCliOutcome => {
+    io.log(`balance: ${result.outcome} — ${result.reasons.join(' · ') || `후보 ${result.candidates.length}대`}`);
+    io.log(JSON.stringify(result));
+    return { code, result };
+  };
+  let required: string[];
+  try {
+    const contextPath = io.env[GRAPH_CONTEXT_ENV];
+    if (!contextPath) throw new Error(`${GRAPH_CONTEXT_ENV} 없음`);
+    required = requiredFromContext(io.readFile(contextPath));
+  } catch (error) {
+    const reason = `그래프 문맥 오류: ${error instanceof Error ? error.message : String(error)}`;
+    io.error(`launch-head balance: ${reason}`);
+    return emit({ outcome: 'skipped', candidates: [], reasons: [reason] }, 2);
+  }
+
+  let query: string;
+  let port: number;
+  try {
+    const tokens: unknown = JSON.parse(io.readFile(join(io.instanceRoot(), 'control', 'tokens.json')));
+    const value = tokens && typeof tokens === 'object' && !Array.isArray(tokens)
+      ? (tokens as Record<string, unknown>).query : undefined;
+    if (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value)) throw new Error('query token unavailable');
+    query = value;
+    port = Number(io.env.ELANOUS_CONTROL_PORT ?? 31413);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('invalid control port');
+  } catch {
+    const reason = '관제부 조회 설정 오류';
+    io.error(`launch-head balance: ${reason}`);
+    return emit({ outcome: 'skipped', candidates: [], reasons: [reason] }, 2);
+  }
+
+  const fail = (reason: string): BalanceCliOutcome => {
+    io.error(`launch-head balance: ${reason}`);
+    return emit({ outcome: 'skipped', candidates: [], reasons: [reason] }, 2);
+  };
+  let response: Response;
+  try {
+    response = await io.fetch(`http://127.0.0.1:${port}/v1/resources?kind=machine`, {
+      headers: { authorization: `Bearer ${query}` }, signal: AbortSignal.timeout(5_000),
+    });
+  } catch {
+    return emit({ outcome: 'skipped', candidates: [], reasons: ['관제부에 닿지 못함'] }, 0);
+  }
+  if (!response.ok) return fail(`관제부 HTTP 오류: ${response.status}`);
+
+  let text: string;
+  try {
+    text = await response.text();
+  } catch {
+    return emit({ outcome: 'skipped', candidates: [], reasons: ['관제부에 닿지 못함'] }, 0);
+  }
+  let body: unknown;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return fail('관제부 응답 형식 오류: JSON 파싱 실패');
+  }
+  if (!body || typeof body !== 'object' || !Array.isArray((body as Record<string, unknown>).resources) ||
+    !(body as { resources: unknown[] }).resources.every((row) =>
+      row && typeof row === 'object' && !Array.isArray(row) &&
+      (row as ResourceView).kind === 'machine' && typeof (row as ResourceView).machine === 'string' &&
+      typeof (row as ResourceView).observedAt === 'number' && typeof (row as ResourceView).ttlMs === 'number' &&
+      (row as ResourceView).attrs && typeof (row as ResourceView).attrs === 'object' && !Array.isArray((row as ResourceView).attrs))) {
+    return fail('관제부 응답 형식 오류: resources');
+  }
+  try {
+    return emit(rankMachines({ machines: (body as { resources: ResourceView[] }).resources, required, nowMs: io.now() }), 0);
+  } catch (error) {
+    return fail(`기계 순위 판정 오류: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export function registerLaunchHeadCommands(program: Command): void {
+  const launchHead = program.command('launch-head').description('발사 앞 머리 — 골이 Pod 로 가도 되는지 판정');
+  launchHead.command('capability')
+    .description('골 문서만 보고 any | local-only 를 정한다. 마지막 줄은 JSON.')
+    .option('--goal <path>', '골 문서 경로. 없으면 ELANOUS_GRAPH_CONTEXT 의 input.goal_path')
+    .action((opts: { goal?: string }) => {
+      const args = opts.goal ? ['--goal', opts.goal] : [];
+      const outcome = runCapabilityCheck(args);
+      if (outcome.code !== 0) process.exitCode = outcome.code;
+    });
+  launchHead.command('balance')
+    .description('관제부의 살아 있는 기계 둘 이상일 때 부하가 낮은 후보부터 정렬한다. 마지막 줄은 JSON.')
+    .option('--json', 'JSON 결과 (마지막 줄에 항상 출력)')
+    .action(async (_opts: { json?: boolean }) => {
+      const outcome = await runLoadBalance([]);
+      if (outcome.code !== 0) process.exitCode = outcome.code;
+    });
+}

package/src/launch-head/load-balance.ts

@@ -0,0 +1,81 @@
+import type { ResourceView } from '../control-plane/ledger.js';
+
+export interface RankMachinesInput {
+  machines: readonly ResourceView[];
+  required: readonly string[];
+  nowMs: number;
+  staleMs?: number;
+}
+
+export interface RankedMachine {
+  machine: string;
+  score: number | null;
+  loadPerCpu: number | null;
+  freeMemRatio: number | null;
+}
+
+export interface RankMachinesResult {
+  outcome: 'ranked' | 'skipped';
+  candidates: RankedMachine[];
+  reasons: string[];
+}
+
+const DEFAULT_STALE_MS = 3 * 60_000;
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function nonNegative(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+/** Pure ranking: only fresh, unexpired machine records count toward the multi-machine gate. */
+export function rankMachines({ machines, required, nowMs, staleMs = DEFAULT_STALE_MS }: RankMachinesInput): RankMachinesResult {
+  const live = machines.filter((row) => {
+    const age = nowMs - row.observedAt;
+    return row.kind === 'machine' && row.expired !== true &&
+      Number.isFinite(age) && age >= 0 && age <= staleMs && age < row.ttlMs;
+  });
+  if (live.length < 2) {
+    return { outcome: 'skipped', candidates: [], reasons: [`기계 ${live.length}대`] };
+  }
+
+  const reasons: string[] = [];
+  const candidates: RankedMachine[] = [];
+  for (const row of live) {
+    const attrs = record(row.attrs);
+    const capabilities = Array.isArray(attrs.capabilities) ? attrs.capabilities : [];
+    const missing = required.filter((capability) => !capabilities.includes(capability));
+    if (missing.length) {
+      reasons.push(`${row.machine}: 능력 없음 (${missing.join(', ')})`);
+      continue;
+    }
+
+    const load = record(attrs.load);
+    const loadAge = nowMs - (typeof load.observedAt === 'number' ? load.observedAt : row.observedAt);
+    const firstLoad = Array.isArray(load.loadAvg) ? nonNegative(load.loadAvg[0]) : null;
+    const cpuCount = nonNegative(load.cpuCount);
+    const loadPerCpu = loadAge >= 0 && loadAge <= staleMs && firstLoad !== null && cpuCount !== null && cpuCount > 0
+      ? firstLoad / cpuCount : null;
+    const freeMem = nonNegative(load.freeMem);
+    const totalMem = nonNegative(load.totalMem);
+    const freeMemRatio = freeMem !== null && totalMem !== null && totalMem > 0
+      ? freeMem / totalMem : null;
+    candidates.push({ machine: row.machine, score: loadPerCpu, loadPerCpu, freeMemRatio });
+  }
+  candidates.sort((a, b) => {
+    if (a.loadPerCpu === null && b.loadPerCpu !== null) return 1;
+    if (b.loadPerCpu === null && a.loadPerCpu !== null) return -1;
+    if (a.loadPerCpu !== null && b.loadPerCpu !== null && a.loadPerCpu !== b.loadPerCpu) {
+      return a.loadPerCpu - b.loadPerCpu;
+    }
+    if (a.freeMemRatio === null && b.freeMemRatio !== null) return 1;
+    if (b.freeMemRatio === null && a.freeMemRatio !== null) return -1;
+    if (a.freeMemRatio !== null && b.freeMemRatio !== null && a.freeMemRatio !== b.freeMemRatio) {
+      return b.freeMemRatio - a.freeMemRatio;
+    }
+    return a.machine.localeCompare(b.machine);
+  });
+  return { outcome: 'ranked', candidates, reasons };
+}

package/src/live/detail-switch.ts

@@ -0,0 +1,180 @@
+// Live 탭 «화려함 MAX» 스위치 — 상세 관측을 켜는 한 자리 (대표 2026-09-28 · 기획 #21443 §0c).
+//
+// 대표: «화려함의 드로백은 하니스의 부하 — 화려함 MAX(1차 마케팅 · 2차 상세 디버깅) ↔ 실용성 두 모드.
+//      상세 관측에는 비용이 드니 사용자가 스스로 알고 켠다.»
+// ⇒ 상세 판단 이벤트(`harness.decision`)는 이 스위치가 켜져 있을 때만 낸다. 기본은 꺼짐(실용성 모드).
+//
+// 상태 = `<state>/live/detail.json` `{ scope: 'all' | '<runId>', until: <epoch ms>, by?, since }`.
+//   - 넥서스(`/v1/live/detail`)가 쓰고, 하니스·런(다른 프로세스)은 파일을 읽는다 — 프로세스 경계를 넘는 가장 단순한 관.
+//   - `until` 이 지나면 꺼진 것이다(자동 꺼짐 · 파일을 지우는 사람이 없어도 된다).
+// ⛔ 읽기 실패·깨진 파일은 기본 «꺼짐» — 단 유효한 미래 ELANOUS_LIVE_DETAIL_UNTIL 은 전체 범위를 켠다.
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { debug } from '../debug/log.js';
+import { prodInstanceRoot } from '../instance/resolve.js';
+
+export const LIVE_DETAIL_DEFAULT_TTL_MIN = 30;
+export const LIVE_DETAIL_MAX_TTL_MIN = 240;
+const CACHE_MS = 5_000;
+
+export interface LiveDetailState {
+  readonly scope: 'all' | string;
+  readonly until: number;
+  readonly since: number;
+  readonly by?: string;
+}
+
+export function liveDetailPath(root: string = elanousStateRoot()): string {
+  return join(root, 'live', 'detail.json');
+}
+
+function parse(raw: string): LiveDetailState | null {
+  try {
+    const v = JSON.parse(raw) as Partial<LiveDetailState>;
+    if (typeof v.scope !== 'string' || !v.scope || typeof v.until !== 'number' || !Number.isFinite(v.until)) return null;
+    return { scope: v.scope, until: v.until, since: typeof v.since === 'number' ? v.since : v.until, ...(typeof v.by === 'string' ? { by: v.by } : {}) };
+  } catch { return null; }
+}
+
+/** 지금 켜져 있는 상태(없거나 지났으면 null). */
+export function readLiveDetail(opts: { path?: string; now?: number } = {}): LiveDetailState | null {
+  let raw: string;
+  try { raw = readFileSync(opts.path ?? liveDetailPath(), 'utf8'); } catch { return null; }
+  const state = parse(raw);
+  if (!state) return null;
+  return state.until > (opts.now ?? Date.now()) ? state : null;
+}
+
+/** 켠다(또는 끈다 — `ttlMin: 0`). 넥서스 끝점과 CLI 가 부른다. */
+export function writeLiveDetail(
+  input: { scope?: string; ttlMin?: number; by?: string },
+  opts: { path?: string; now?: number } = {},
+): LiveDetailState | null {
+  const now = opts.now ?? Date.now();
+  const path = opts.path ?? liveDetailPath();
+  const ttl = Math.min(LIVE_DETAIL_MAX_TTL_MIN, Math.max(0, input.ttlMin ?? LIVE_DETAIL_DEFAULT_TTL_MIN));
+  const scope = input.scope?.trim() || 'all';
+  const state: LiveDetailState = { scope, until: now + ttl * 60_000, since: now, ...(input.by ? { by: input.by } : {}) };
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state));
+  renameSync(tmp, path);
+  cache = null;
+  debug.log('live.detail', ttl > 0 ? 'enabled' : 'disabled', { scope, ttlMin: ttl, by: input.by ?? null });
+  return ttl > 0 ? state : null;
+}
+
+export interface LiveDetailSelection {
+  readonly state: LiveDetailState | null;
+  readonly source: 'local' | 'production' | null;
+  readonly path: string | null;
+}
+
+type DetailReadOptions = { now?: number; path?: string; prodPath?: string };
+let cache: { at: number; localPath: string; prodPath: string; selection: LiveDetailSelection } | null = null;
+
+/** 자기 우주에 파일이 존재하는 동안은 꺼짐/만료/깨진 상태도 운영 폴백을 가린다. */
+export function selectLiveDetail(opts: DetailReadOptions = {}): LiveDetailSelection {
+  const now = opts.now ?? Date.now();
+  const localPath = opts.path ?? liveDetailPath();
+  const prodPath = opts.prodPath ?? (opts.path ? localPath : liveDetailPath(prodInstanceRoot()));
+  if (cache && cache.localPath === localPath && cache.prodPath === prodPath && now >= cache.at && now - cache.at <= CACHE_MS) {
+    const { state, source, path } = cache.selection;
+    return { state: state && state.until > now ? state : null, source, path };
+  }
+  let source: LiveDetailSelection['source'] = 'local';
+  let path = localPath;
+  let raw: string | null = null;
+  try { raw = readFileSync(localPath, 'utf8'); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT' && prodPath !== localPath) {
+      source = 'production';
+      path = prodPath;
+      try { raw = readFileSync(prodPath, 'utf8'); }
+      catch (fallbackError) {
+        if ((fallbackError as NodeJS.ErrnoException).code === 'ENOENT') { source = null; path = ''; }
+      }
+    } else if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      source = null;
+      path = '';
+    }
+  }
+  const parsed = raw === null ? null : parse(raw);
+  const selection: LiveDetailSelection = { state: parsed, source, path: source ? path : null };
+  cache = { at: now, localPath, prodPath, selection };
+  return { ...selection, state: parsed && parsed.until > now ? parsed : null };
+}
+
+/** 이 런에 상세 관측이 켜져 있나 — 파일은 5초 캐시, env 만료는 매번 확인한다. */
+export function isLiveDetailOn(runId?: string, opts: DetailReadOptions = {}): boolean {
+  const now = opts.now ?? Date.now();
+  const state = selectLiveDetail({ ...opts, now }).state;
+  if (state) return matches(state, runId, now);
+  const rawUntil = process.env.ELANOUS_LIVE_DETAIL_UNTIL;
+  if (!rawUntil || !/^\d+$/.test(rawUntil)) return false;
+  const until = Number(rawUntil);
+  return Number.isSafeInteger(until) && until > now;
+}
+
+function matches(state: LiveDetailState | null, runId: string | undefined, now: number): boolean {
+  if (!state || state.until <= now) return false;
+  return state.scope === 'all' || (!!runId && state.scope === runId);
+}
+
+/** 판단 종류 — Live 탭 판단 그래프의 범례와 같다(기획 §0b). */
+export type DecisionKind = 'PLAN' | 'ROUTE' | 'VERIFY' | 'HEAL' | 'ESCALATE' | 'SHIP';
+
+export interface DecisionEvent {
+  readonly kind: DecisionKind;
+  /** 무엇을 판단했나(한 줄). */
+  readonly what: string;
+  /** 왜 — 근거(한 줄). */
+  readonly reason: string;
+  /** 무엇을 위해 — 목적(한 줄). */
+  readonly purpose: string;
+  /** 어디로 보냈나 — 다음 행선지(노드·계정·기계·사람). */
+  readonly target: string;
+  readonly runId?: string;
+  /** 검토한 선택지 수(판단 그래프 `PATHS`). */
+  readonly paths?: number;
+  /** Trace(v6) 연결 칸 — 부모 런(재발사·슈퍼바이저·Pod 자식의 부모). 없으면 `ELANOUS_PARENT_RUN_ID`. */
+  readonly parentRunId?: string;
+  /** 하니스 페이즈(author·decompose·dispatch·implement·gate·review·land). */
+  readonly phase?: 'author' | 'decompose' | 'dispatch' | 'implement' | 'gate' | 'review' | 'land';
+  /** 조각(하니스 공간 id). 없으면 `ELANOUS_HARNESS_SPACE_ID`. */
+  readonly shard?: string;
+  /** 증거로 가는 참조(L4) — PR 번호 · 커밋 · 계정 등. 값은 짧은 식별자만(비밀 금지). */
+  readonly refs?: Readonly<Record<string, string | number>>;
+}
+
+/**
+ * 판단 한 건을 낸다 — MAX 스위치가 켜져 있을 때만. 꺼져 있으면 아무것도 안 한다(부하 0).
+ * `runId` 를 안 주면 `ELANOUS_RUN_ID`(가장 바깥에서 찍은 런 id)를 쓴다.
+ */
+export function emitDecision(event: DecisionEvent, opts: DetailReadOptions = {}): boolean {
+  const runId = event.runId ?? process.env.ELANOUS_RUN_ID?.trim() ?? undefined;
+  if (!isLiveDetailOn(runId, opts)) return false;
+  // 같은 판단이 한 프로세스의 두 경로(조회·해석)에서 같은 순간 두 번 오면 한 번만 낸다(09-28 운영 실측 · 같은 ms 두 줄).
+  const now = opts.now ?? Date.now();
+  const key = `${event.kind}|${event.what}|${event.target}|${runId ?? ''}`;
+  const last = recent.get(key);
+  if (last !== undefined && now - last < DEDUPE_MS) return false;
+  recent.set(key, now);
+  if (recent.size > 256) for (const [k, t] of recent) if (now - t >= DEDUPE_MS) recent.delete(k);
+  const parentRunId = event.parentRunId ?? process.env.ELANOUS_PARENT_RUN_ID?.trim() ?? undefined;
+  const shard = event.shard ?? process.env.ELANOUS_HARNESS_SPACE_ID?.trim() ?? undefined;
+  debug.log('harness.decision', 'decision', {
+    ...event, runId: runId ?? null,
+    ...(parentRunId ? { parentRunId } : {}),
+    ...(shard ? { shard } : {}),
+  });
+  return true;
+}
+
+const DEDUPE_MS = 5_000;
+const recent = new Map<string, number>();
+
+/** 시험 전용 — 캐시를 비운다. */
+export function resetLiveDetailCacheForTesting(): void { cache = null; recent.clear(); }