elanous 0.2.42 → 0.2.44

package/src/life/life-cli.ts

@@ -0,0 +1,168 @@
+/**
+ * `eln life` — LIFE-KINDS 의 생산 진입점(등록 지점 = `src/index.ts` 의 `registerLifeCommands(program)`).
+ *
+ * Situation: `life-kinds.ts` 의 종류·끝의 증거·반복 실행 시리즈는 라이브러리만 있으면
+ *   사람도 에이전트도 부를 수 없다(수용선: 새 코드는 생산 진입점에서 호출된다).
+ * Answer: Commander 명령 셋을 등록한다 — `kind` 목록 · 끝 판정 · 시리즈 기록·조회.
+ *   시계는 주입(`deps.now`)이라 시험은 가짜 시계로 같은 경로를 지난다.
+ */
+import type { Command } from 'commander';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { debug } from '../debug/log.js';
+import { writeStdoutJson } from '../cli/stdout-json.js';
+import {
+  createLifeRunSeries,
+  evaluateLifeEnd,
+  isLifeEndEvidenceKind,
+  isLifeKind,
+  LIFE_END_EVIDENCE_KINDS,
+  LIFE_KIND_SPECS,
+  LIFE_KINDS,
+  lifeKindSpec,
+  type LifeEndEvidence,
+  type LifeEndEvidenceKind,
+  type LifeEndVerdict,
+  type LifeKind,
+  type LifeRunSeriesEntry,
+} from './life-kinds.js';
+
+export interface LifeCliDeps {
+  /** 시계 주입 — 시험은 가짜 시계를 넣는다. */
+  now?: () => Date;
+  out?: Pick<Console, 'log' | 'error'>;
+}
+
+function requireLifeKind(raw: string): LifeKind {
+  if (!isLifeKind(raw)) throw new Error(`생애 종류가 아니다: ${raw} — ${LIFE_KINDS.join('|')} 중 하나여야 한다`);
+  return raw;
+}
+
+/**
+ * `--evidence pr:1234,artifact:out/report.md` 를 증거 목록으로 판다.
+ * 참조에는 쉼표가 들어갈 수 없고(`:`) 첫 콜론만 구분자다 — URL 의 `https://` 는 참조 쪽에 남는다.
+ */
+export function parseLifeEndEvidenceFlag(raw: string | undefined): LifeEndEvidence[] {
+  if (raw === undefined || raw.trim() === '') return [];
+  return raw.split(',').map((item) => {
+    const text = item.trim();
+    const separator = text.indexOf(':');
+    if (separator <= 0) throw new Error(`증거는 <종류>:<참조> 꼴이어야 한다: ${text}`);
+    const kind = text.slice(0, separator).trim();
+    const ref = text.slice(separator + 1).trim();
+    if (!isLifeEndEvidenceKind(kind)) throw new Error(`증거 종류가 아니다: ${kind} — ${LIFE_END_EVIDENCE_KINDS.join('|')} 중 하나여야 한다`);
+    if (ref === '') throw new Error(`증거 참조가 비었다: ${text}`);
+    return { kind: kind as LifeEndEvidenceKind, ref };
+  });
+}
+
+export function formatLifeEndVerdict(verdict: LifeEndVerdict): string {
+  const spec = lifeKindSpec(verdict.kind);
+  const state = verdict.satisfied ? '충족' : `미충족 · 빠짐 ${verdict.missing.join(',') || '-'}`;
+  return `${verdict.kind} · ${spec.label} · 필요 증거 ${verdict.required.join(',')} · ${state}`;
+}
+
+function parseStoredSeries(path: string, raw: string): LifeRunSeriesEntry[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`생애 시리즈 파일이 JSON 이 아니다: ${path}`);
+  }
+  if (!Array.isArray(parsed)) throw new Error(`생애 시리즈 파일은 배열이어야 한다: ${path}`);
+  const seenSequences = new Set<string>();
+  return parsed.map((item, index) => {
+    const row = item as Partial<LifeRunSeriesEntry> | undefined;
+    if (!row || typeof row !== 'object') throw new Error(`생애 시리즈 ${index + 1}번째 항목이 객체가 아니다: ${path}`);
+    if (typeof row.kind !== 'string' || !isLifeKind(row.kind)) throw new Error(`생애 시리즈 ${index + 1}번째 항목의 종류가 잘못됐다: ${path}`);
+    if (!Number.isInteger(row.seq) || (row.seq as number) < 1) throw new Error(`생애 시리즈 ${index + 1}번째 항목의 seq 가 잘못됐다: ${path}`);
+    const sequenceKey = `${row.kind}:${row.seq}`;
+    if (seenSequences.has(sequenceKey)) throw new Error(`생애 시리즈 ${index + 1}번째 항목의 중복 seq ${row.seq}: ${path}`);
+    seenSequences.add(sequenceKey);
+    if (typeof row.at !== 'string' || row.at === '') throw new Error(`생애 시리즈 ${index + 1}번째 항목의 at 이 비었다: ${path}`);
+    if (typeof row.satisfied !== 'boolean') throw new Error(`생애 시리즈 ${index + 1}번째 항목의 satisfied 가 잘못됐다: ${path}`);
+    const evidence = Array.isArray(row.evidence) ? row.evidence : [];
+    for (const entry of evidence) {
+      const item2 = entry as Partial<LifeEndEvidence> | undefined;
+      if (!item2 || typeof item2.kind !== 'string' || !isLifeEndEvidenceKind(item2.kind) || typeof item2.ref !== 'string') {
+        throw new Error(`생애 시리즈 ${index + 1}번째 항목의 증거가 잘못됐다: ${path}`);
+      }
+    }
+    return {
+      seq: row.seq as number,
+      kind: row.kind,
+      at: row.at,
+      ...(typeof row.note === 'string' ? { note: row.note } : {}),
+      evidence: evidence.map((entry) => ({ kind: (entry as LifeEndEvidence).kind, ref: (entry as LifeEndEvidence).ref })),
+      satisfied: row.satisfied as boolean,
+    };
+  });
+}
+
+export function registerLifeCommands(program: Command, deps: LifeCliDeps = {}): void {
+  const out = deps.out ?? console;
+  const now = deps.now ?? (() => new Date());
+  const lifeCmd = program.command('life').description('생애 종류 · 종류별 끝의 증거 · 반복 실행 시리즈');
+
+  lifeCmd.command('kinds')
+    .description('생애 종류(dev·run·ops·admin)와 종류별 끝의 증거를 보여 준다')
+    .option('--json', 'JSON 출력')
+    .action(async (opts: { json?: boolean }) => {
+      const rows = LIFE_KIND_SPECS.map((spec) => ({ kind: spec.kind, label: spec.label, endsWith: [...spec.endsWith] }));
+      await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('cli');
+      debug.log('life.cli', 'kinds-listed', { count: rows.length });
+      if (opts.json) {
+        await writeStdoutJson(JSON.stringify(rows) + '\n');
+        return;
+      }
+      for (const row of rows) out.log(`${row.kind} · ${row.label} · 끝의 증거 ${row.endsWith.join(',')}`);
+    });
+
+  lifeCmd.command('check <kind>')
+    .description('한 생애 종류의 끝이 증거로 충족되는지 판정한다')
+    .option('--evidence <list>', '끝의 증거 — <종류>:<참조> 를 쉼표로 잇는다(pr·artifact·state-measurement·proof)')
+    .option('--json', 'JSON 출력')
+    .action(async (rawKind: string, opts: { evidence?: string; json?: boolean }) => {
+      const kind = requireLifeKind(rawKind);
+      const verdict = evaluateLifeEnd(kind, parseLifeEndEvidenceFlag(opts.evidence));
+      if (!verdict.satisfied) process.exitCode = 1;
+      if (opts.json) {
+        await writeStdoutJson(JSON.stringify(verdict) + '\n');
+        return;
+      }
+      out.log(formatLifeEndVerdict(verdict));
+    });
+
+  lifeCmd.command('series <kind>')
+    .description('같은 종류의 반복 실행 시리즈를 기록하고 조회한다')
+    .option('--add <note>', '이번 실행을 시리즈에 덧붙인다(한 줄 메모)')
+    .option('--evidence <list>', '이번 실행의 끝의 증거 — <종류>:<참조> 를 쉼표로 잇는다')
+    .option('--file <path>', '시리즈를 이 JSON 파일에 이어 쓴다(없으면 그 자리에서만 산다)')
+    .option('--seq <n>', '그 종류의 한 칸만 본다')
+    .option('--json', 'JSON 출력')
+    .action(async (rawKind: string, opts: { add?: string; evidence?: string; file?: string; seq?: string; json?: boolean }) => {
+      const kind = requireLifeKind(rawKind);
+      const stored = opts.file && existsSync(opts.file) ? parseStoredSeries(opts.file, readFileSync(opts.file, 'utf8')) : [];
+      const series = createLifeRunSeries({ now, entries: stored });
+      if (opts.add !== undefined || opts.evidence !== undefined) {
+        series.append({ kind, ...(opts.add === undefined ? {} : { note: opts.add }), evidence: parseLifeEndEvidenceFlag(opts.evidence) });
+        if (opts.file) {
+          mkdirSync(dirname(opts.file), { recursive: true });
+          writeFileSync(opts.file, JSON.stringify(series.list(), null, 2) + '\n');
+        }
+      }
+      let rows = series.list(kind);
+      if (opts.seq !== undefined) {
+        const seq = Number(opts.seq);
+        if (!Number.isInteger(seq) || seq < 1) throw new Error('--seq must be a positive integer');
+        const found = series.lookup({ kind, seq });
+        rows = found === undefined ? [] : [found];
+        if (found === undefined) process.exitCode = 1;
+      }
+      if (opts.json) {
+        await writeStdoutJson(JSON.stringify(rows) + '\n');
+        return;
+      }
+      for (const row of rows) out.log(`${row.seq}. ${row.at} · ${row.kind} · ${row.satisfied ? '끝 충족' : '끝 미충족'}${row.note ? ` · ${row.note}` : ''}`);
+    });
+}

package/src/life/life-kinds.ts

@@ -0,0 +1,160 @@
+/**
+ * LIFE-KINDS (MK · 0.2.43 · RFC-harness-full-journey-as-graph §4a·§4c) —
+ * 생애(life) 종류 · 종류별 «끝의 증거» · 반복 실행 시리즈.
+ *
+ * Situation: 생애 원장(§4a)은 걸음을 시간순으로 쌓지만, «이 생애가 어떤 종류의 일이고
+ *   무엇이 있어야 끝인가»를 아는 단일 목록이 없었다. 개발(PR) · 실행(산출물) ·
+ *   운영 조치(상태 측정) · 행정(증빙)이 각자 다른 곳에서 그 종결을 판단했다.
+ * Answer: 종류 닫힌 목록(`LIFE_KINDS`)과 종류별 «끝의 증거»(`LIFE_KIND_SPECS`)를 한 곳에 두고,
+ *   주어진 종류에 대해 필요한 증거와 충족 여부를 판정한다(`evaluateLifeEnd`).
+ *   같은 종류의 반복 실행은 시리즈(`createLifeRunSeries`)로 순차 기록·조회한다 —
+ *   시각은 주입된 시계(`now`)에서만 얻으므로 가짜 시계로 그대로 시험할 수 있다.
+ *
+ * ⛔ 이 모듈은 순수하다 — 파일·환경·네트워크를 건드리지 않는다(생산 배선 = `life-cli.ts`).
+ */
+
+/** 생애 종류의 닫힌 목록 — 순서는 표시 순서이기도 하다. */
+export const LIFE_KINDS = ['dev', 'run', 'ops', 'admin'] as const;
+export type LifeKind = (typeof LIFE_KINDS)[number];
+
+/** 끝을 증명할 수 있는 증거의 닫힌 목록 — PR · 산출물 · 상태 측정 · 증빙. */
+export const LIFE_END_EVIDENCE_KINDS = ['pr', 'artifact', 'state-measurement', 'proof'] as const;
+export type LifeEndEvidenceKind = (typeof LIFE_END_EVIDENCE_KINDS)[number];
+
+/** 종류 하나의 표시명과, 그 종류의 «끝»을 증명하는 데 필요한 증거 종류. */
+export interface LifeKindSpec {
+  kind: LifeKind;
+  label: string;
+  endsWith: readonly LifeEndEvidenceKind[];
+}
+
+/** §4c 의 네 종류 — 기능(개발)은 PR, 실행은 산출물, 운영 조치는 상태 측정, 행정은 증빙으로 끝난다. */
+export const LIFE_KIND_SPECS: readonly LifeKindSpec[] = [
+  { kind: 'dev', label: '개발', endsWith: ['pr'] },
+  { kind: 'run', label: '실행 산출', endsWith: ['artifact'] },
+  { kind: 'ops', label: '운영 조치', endsWith: ['state-measurement'] },
+  { kind: 'admin', label: '행정', endsWith: ['proof'] },
+];
+
+const SPEC_BY_KIND: ReadonlyMap<LifeKind, LifeKindSpec> = new Map(LIFE_KIND_SPECS.map((spec) => [spec.kind, spec]));
+
+export function isLifeKind(value: string): value is LifeKind {
+  return (LIFE_KINDS as readonly string[]).includes(value);
+}
+
+export function isLifeEndEvidenceKind(value: string): value is LifeEndEvidenceKind {
+  return (LIFE_END_EVIDENCE_KINDS as readonly string[]).includes(value);
+}
+
+export function lifeKindSpec(kind: LifeKind): LifeKindSpec {
+  const spec = SPEC_BY_KIND.get(kind);
+  if (!spec) throw new Error(`생애 종류가 아니다: ${String(kind)} — ${LIFE_KINDS.join('|')} 중 하나여야 한다`);
+  return spec;
+}
+
+/** 주어진 종류의 «끝»을 증명하려면 있어야 하는 증거 종류 목록. */
+export function requiredEndEvidence(kind: LifeKind): readonly LifeEndEvidenceKind[] {
+  return lifeKindSpec(kind).endsWith;
+}
+
+/** 끝의 증거 한 건 — 종류와, 그것을 가리키는 참조(PR 번호·산출물 경로·측정 명령·증빙 id). */
+export interface LifeEndEvidence {
+  kind: LifeEndEvidenceKind;
+  ref: string;
+}
+
+export interface LifeEndVerdict {
+  kind: LifeKind;
+  required: readonly LifeEndEvidenceKind[];
+  /** 넘겨받은 증거 중 이 종류에 실제로 쓰인 것(빈 ref 는 세지 않는다). */
+  present: readonly LifeEndEvidence[];
+  missing: readonly LifeEndEvidenceKind[];
+  satisfied: boolean;
+}
+
+function hasUsableRef(evidence: LifeEndEvidence): boolean {
+  return typeof evidence.ref === 'string' && evidence.ref.trim().length > 0;
+}
+
+/**
+ * 종류별 «끝» 판정 — 필요한 증거 종류마다 ref 가 있는 증거가 하나 이상 있어야 충족이다.
+ * 필요한 종류가 아닌 증거는 `present` 에만 남고 판정을 바꾸지 않는다.
+ */
+export function evaluateLifeEnd(kind: LifeKind, evidence: readonly LifeEndEvidence[]): LifeEndVerdict {
+  const required = requiredEndEvidence(kind);
+  const present = evidence.filter((item) => hasUsableRef(item) && required.includes(item.kind));
+  const missing = required.filter((requiredKind) => !present.some((item) => item.kind === requiredKind));
+  return { kind, required, present, missing, satisfied: missing.length === 0 };
+}
+
+/** 반복 실행 시리즈의 한 칸 — 같은 종류의 몇 번째 실행인지(`seq`)와 그때의 끝 판정. */
+export interface LifeRunSeriesEntry {
+  seq: number;
+  kind: LifeKind;
+  /** 주입된 시계에서 얻은 ISO 시각. */
+  at: string;
+  note?: string;
+  evidence: readonly LifeEndEvidence[];
+  satisfied: boolean;
+}
+
+export interface LifeRunSeriesAppendInput {
+  kind: LifeKind;
+  note?: string;
+  evidence?: readonly LifeEndEvidence[];
+}
+
+export interface LifeRunSeriesLookup {
+  kind: LifeKind;
+  seq: number;
+}
+
+export interface LifeRunSeries {
+  /** 같은 종류의 다음 `seq` 로 한 칸을 덧붙인다(다른 종류의 seq 와 섞이지 않는다). */
+  append(input: LifeRunSeriesAppendInput): LifeRunSeriesEntry;
+  /** 종류를 주면 그 종류의 시리즈만, 안 주면 전체를 append 순서대로. */
+  list(kind?: LifeKind): readonly LifeRunSeriesEntry[];
+  /** 종류 + seq 로 한 칸을 찾는다 — 없으면 undefined. */
+  lookup(query: LifeRunSeriesLookup): LifeRunSeriesEntry | undefined;
+}
+
+export interface LifeRunSeriesOptions {
+  /** 시계 주입 — 가짜 시계로 시험한다. */
+  now: () => Date;
+  /** 이어받을 기존 시리즈(예: 파일에서 읽은 원장). */
+  entries?: readonly LifeRunSeriesEntry[];
+}
+
+export function createLifeRunSeries(options: LifeRunSeriesOptions): LifeRunSeries {
+  const entries: LifeRunSeriesEntry[] = [...(options.entries ?? [])].map((entry) => {
+    lifeKindSpec(entry.kind);
+    return { ...entry, evidence: [...entry.evidence] };
+  });
+
+  return {
+    append(input) {
+      lifeKindSpec(input.kind);
+      const previous = entries.filter((entry) => entry.kind === input.kind);
+      const seq = previous.reduce((max, entry) => Math.max(max, entry.seq), 0) + 1;
+      const evidence = [...(input.evidence ?? [])];
+      const verdict = evaluateLifeEnd(input.kind, evidence);
+      const entry: LifeRunSeriesEntry = {
+        seq,
+        kind: input.kind,
+        at: options.now().toISOString(),
+        ...(input.note === undefined ? {} : { note: input.note }),
+        evidence,
+        satisfied: verdict.satisfied,
+      };
+      entries.push(entry);
+      return entry;
+    },
+    list(kind) {
+      return kind === undefined ? entries.map((entry) => ({ ...entry })) : entries.filter((entry) => entry.kind === kind).map((entry) => ({ ...entry }));
+    },
+    lookup({ kind, seq }) {
+      const found = entries.find((entry) => entry.kind === kind && entry.seq === seq);
+      return found === undefined ? undefined : { ...found };
+    },
+  };
+}

package/src/live-supply/budget-consumer.ts

@@ -0,0 +1,78 @@
+import type { BudgetInputs } from '../self-implement/budget-gate.js';
+import { debug } from '../debug/log.js';
+import { freshSupplyAxis, loadLiveSupplySnapshot } from './read.js';
+import type { LiveSupplySnapshot } from './snapshot.js';
+
+function observe(event: string, data: Record<string, unknown>): void {
+  try { debug.log('live-supply', event, data); } catch { /* observation never blocks a child */ }
+}
+
+/** Apply only negative, measured facts. The direct budget read still owns preference, credits and provider policy. */
+export function budgetInputsWithLiveSupply(
+  direct: BudgetInputs,
+  snapshot: LiveSupplySnapshot | null = loadLiveSupplySnapshot(),
+  nowMs = Date.now(),
+): BudgetInputs {
+  const codex = freshSupplyAxis(snapshot, 'codex', nowMs);
+  const grok = freshSupplyAxis(snapshot, 'grok', nowMs);
+  if (codex.status !== 'fresh' && grok.status !== 'fresh') {
+    observe('snapshot-unavailable', {
+      site: 'pod-budget', codex: codex.reason, grok: grok.reason,
+    });
+    return direct;
+  }
+
+  let candidates = direct.codexCandidates;
+  if (codex.status === 'fresh' && Array.isArray(codex.value?.accounts)) {
+    const accounts = codex.value.accounts;
+    const sampled = new Map(accounts
+      .filter(account => account && typeof account.name === 'string' && account.name.length > 0)
+      .map(account => [account.name, account]));
+    if (sampled.size !== accounts.length) {
+      observe('snapshot-fallback', { site: 'pod-budget', axis: 'codex', sequence: codex.sequence, reason: 'malformed-accounts' });
+    } else {
+      let consumed = 0;
+      let unmatched = 0;
+      let invalid = 0;
+      candidates = direct.codexCandidates.map(candidate => {
+        const seen = sampled.get(candidate.name);
+        if (!seen) { unmatched++; return candidate; }
+        const used = typeof seen.usedPercent === 'number' && Number.isFinite(seen.usedPercent)
+          && seen.usedPercent >= 0 && seen.usedPercent <= 100 ? seen.usedPercent : undefined;
+        const available = typeof seen.available === 'boolean' ? seen.available : undefined;
+        if (used === undefined && available !== false) { invalid++; return candidate; }
+        consumed++;
+        const directUsed = typeof candidate.usedPercent === 'number' && Number.isFinite(candidate.usedPercent)
+          ? candidate.usedPercent : undefined;
+        return {
+          ...candidate,
+          ...(used !== undefined ? { usedPercent: Math.max(directUsed ?? 0, used) } : {}),
+          ...(available === false ? { reached: true } : {}),
+        };
+      });
+      if (consumed) observe('snapshot-consumed', { site: 'pod-budget', axis: 'codex', sequence: codex.sequence });
+      if (unmatched) observe('snapshot-fallback', { site: 'pod-budget', axis: 'codex', sequence: codex.sequence,
+        reason: 'no-matching-account', count: unmatched });
+      if (invalid) observe('snapshot-fallback', { site: 'pod-budget', axis: 'codex', sequence: codex.sequence,
+        reason: 'invalid-account', count: invalid });
+      if (!direct.codexCandidates.length) observe('snapshot-fallback', { site: 'pod-budget', axis: 'codex',
+        sequence: codex.sequence, reason: 'no-candidates' });
+    }
+  } else {
+    observe('snapshot-unavailable', { site: 'pod-budget', axis: 'codex',
+      reason: codex.status === 'fresh' ? 'malformed' : codex.reason });
+  }
+
+  let grokUsedPercent = direct.grokUsedPercent;
+  if (grok.status === 'fresh' && grok.value?.quota === 'exhausted') {
+    grokUsedPercent = 100;
+    observe('snapshot-consumed', { site: 'pod-budget', axis: 'grok', sequence: grok.sequence });
+  } else if (grok.status === 'fresh') {
+    observe('snapshot-fallback', { site: 'pod-budget', axis: 'grok', sequence: grok.sequence,
+      reason: grok.value?.quota === 'usable' ? 'quota-usable' : grok.value?.quota === 'unknown' ? 'quota-unknown' : 'malformed' });
+  } else {
+    observe('snapshot-unavailable', { site: 'pod-budget', axis: 'grok',
+      reason: grok.reason });
+  }
+  return { ...direct, codexCandidates: candidates, grokUsedPercent };
+}

package/src/live-supply/read.ts

@@ -0,0 +1,3 @@
+/** Compatibility entry for direct readers; hot paths import the snapshot module. */
+export { loadLiveSupplySnapshot, freshSupplyAxis } from './snapshot.js';
+export type { FreshSupplyAxis } from './snapshot.js';

package/src/live-supply/snapshot.ts

@@ -1,3 +1,7 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+
 /** Runtime resource facts shared by later harness decisions. No credential values enter this ledger. */
 export const SUPPLY_AXES = ['codex', 'grok', 'cost', 'pool', 'hostCredentials', 'parentHosts'] as const;
 export type SupplyAxis = typeof SUPPLY_AXES[number];
@@ -38,3 +42,44 @@ export interface SupplyEvent {
 }
 
 export type SupplyProbes = { [K in SupplyAxis]: () => Promise<SupplyValues[K]> | SupplyValues[K] };
+
+/** A decision process reads the collector's atomic pointer, never a partially appended JSONL row. */
+export function loadLiveSupplySnapshot(directory = join(getElanousConfigDir(), 'live-supply')): LiveSupplySnapshot | null {
+  try {
+    const row: unknown = JSON.parse(readFileSync(join(directory, 'latest.json'), 'utf8'));
+    if (!row || typeof row !== 'object') return null;
+    const snapshot = row as Partial<LiveSupplySnapshot>;
+    if (snapshot.version !== 1 || typeof snapshot.sequence !== 'number' || !Number.isSafeInteger(snapshot.sequence)
+      || snapshot.sequence < 1 || !snapshot.sources || !snapshot.values) return null;
+    if (typeof snapshot.observedAt !== 'string' || typeof snapshot.expiresAt !== 'string') return null;
+    if (!SUPPLY_AXES.every(axis => {
+      const source = snapshot.sources?.[axis];
+      return source && (source.status === 'measured' || source.status === 'stale' || source.status === 'unknown')
+        && (source.observedAt === null || typeof source.observedAt === 'string');
+    })) return null;
+    return snapshot as LiveSupplySnapshot;
+  } catch { return null; }
+}
+
+export type FreshSupplyAxis<K extends SupplyAxis> =
+  | { status: 'fresh'; sequence: number; observedAt: string; value: SupplyValues[K] }
+  | { status: 'unavailable'; reason: 'missing' | 'expired' | 'unmeasured' };
+
+/** Only a measured source within the snapshot TTL may influence a new launch. */
+export function freshSupplyAxis<K extends SupplyAxis>(snapshot: LiveSupplySnapshot | null, axis: K, nowMs = Date.now()): FreshSupplyAxis<K> {
+  if (!snapshot) return { status: 'unavailable', reason: 'missing' };
+  const expiry = Date.parse(snapshot.expiresAt);
+  const observed = Date.parse(snapshot.observedAt);
+  if (!Number.isFinite(expiry) || !Number.isFinite(observed) || observed > nowMs || expiry <= nowMs) {
+    return { status: 'unavailable', reason: 'expired' };
+  }
+  const source = snapshot.sources[axis];
+  const value = snapshot.values[axis];
+  const sourceObservedAt = source.observedAt;
+  const sourceObserved = typeof sourceObservedAt === 'string' ? Date.parse(sourceObservedAt) : Number.NaN;
+  if (source.status !== 'measured' || value === undefined || typeof sourceObservedAt !== 'string' || !Number.isFinite(sourceObserved) || sourceObserved > nowMs) {
+    return { status: 'unavailable', reason: 'unmeasured' };
+  }
+  if (sourceObserved + (expiry - observed) <= nowMs) return { status: 'unavailable', reason: 'expired' };
+  return { status: 'fresh', sequence: snapshot.sequence, observedAt: sourceObservedAt, value: value as SupplyValues[K] };
+}

package/src/llm/child-first-llm-observation.ts

@@ -0,0 +1,112 @@
+import type { RunLedgerEntry } from '../self-implement/run-ledger.js';
+import { redactSecretText } from '../debug/log.js';
+
+export interface ChildFirstLlmEvent {
+  readonly runId: string;
+  readonly event: 'child-first-llm-call' | 'child-first-tool-call';
+  readonly data: Record<string, unknown>;
+}
+
+export type ChildFirstLlmWriter = (event: ChildFirstLlmEvent) => void | Promise<void>;
+
+/** Appends one first-provider-call timeline per child run. The writer is fail-soft by contract. */
+export function createChildFirstLlmRecorder(write: ChildFirstLlmWriter) {
+  const started = new Set<string>();
+  const responded = new Set<string>();
+  const toolCalled = new Set<string>();
+  return {
+    async start(input: { runId: string; provider: string; model: string; accountName?: string; at?: string }): Promise<void> {
+      const runId = input.runId.trim();
+      if (!runId || started.has(runId)) return;
+      started.add(runId);
+      await write({
+        runId, event: 'child-first-llm-call',
+        data: { status: 'started', provider: input.provider, model: input.model,
+          accountName: input.accountName ?? null, startedAt: input.at ?? new Date().toISOString() },
+      });
+    },
+    async response(input: { runId: string; status: 'ok' | 'error'; httpStatus?: number; error?: unknown; at?: string }): Promise<void> {
+      const runId = input.runId.trim();
+      if (!runId || !started.has(runId) || responded.has(runId)) return;
+      responded.add(runId);
+      const raw = input.error instanceof Error ? input.error.message : input.error == null ? '' : String(input.error);
+      const firstLine = redactSecretText(raw.split(/\r?\n/u, 1)[0] ?? '').replace(/\s+/gu, ' ').slice(0, 240);
+      await write({
+        runId, event: 'child-first-llm-call',
+        data: { status: input.status, ...(input.httpStatus === undefined ? {} : { httpStatus: input.httpStatus }),
+          ...(firstLine ? { errorFirstLine: firstLine } : {}), respondedAt: input.at ?? new Date().toISOString() },
+      });
+    },
+    async firstToolCall(input: { runId: string; at?: string }): Promise<void> {
+      const runId = input.runId.trim();
+      if (!runId || !started.has(runId) || toolCalled.has(runId)) return;
+      toolCalled.add(runId);
+      await write({ runId, event: 'child-first-tool-call', data: { at: input.at ?? new Date().toISOString() } });
+    },
+  };
+}
+
+const defaultRecorder = createChildFirstLlmRecorder(async ({ runId, event, data }) => {
+  try {
+    const { appendRunLedgerEntry } = await import('../self-implement/run-ledger.js');
+    appendRunLedgerEntry({ timestamp: new Date().toISOString(), runId, event, data } satisfies RunLedgerEntry);
+  } catch { /* observation must never prevent an LLM call */ }
+});
+
+export function childRunIdForLlmObservation(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const runId = env.ELANOUS_RUN_ID?.trim();
+  return runId || undefined;
+}
+
+export function recordChildFirstLlmStart(input: { provider: string; model: string; accountName?: string }): Promise<void> {
+  const runId = childRunIdForLlmObservation();
+  return runId ? defaultRecorder.start({ runId, ...input }) : Promise.resolve();
+}
+
+export function recordChildFirstLlmResponse(input: { status: 'ok' | 'error'; httpStatus?: number; error?: unknown }): Promise<void> {
+  const runId = childRunIdForLlmObservation();
+  return runId ? defaultRecorder.response({ runId, ...input }) : Promise.resolve();
+}
+
+export function recordChildFirstToolCall(): Promise<void> {
+  const runId = childRunIdForLlmObservation();
+  return runId ? defaultRecorder.firstToolCall({ runId }) : Promise.resolve();
+}
+
+export interface ChildFirstLlmFact {
+  readonly status: 'started' | 'ok' | 'error';
+  readonly provider: string;
+  readonly model: string;
+  readonly accountName: string | null;
+  readonly startedAt: string;
+  readonly respondedAt?: string;
+  readonly httpStatus?: number;
+  readonly errorFirstLine?: string;
+  readonly firstToolCallAt?: string;
+}
+
+export function childFirstLlmFact(entries: readonly Pick<RunLedgerEntry, 'event' | 'data'>[]): ChildFirstLlmFact | undefined {
+  const start = entries.find((entry) => entry.event === 'child-first-llm-call' && entry.data.status === 'started');
+  if (!start || typeof start.data.provider !== 'string' || typeof start.data.model !== 'string' || typeof start.data.startedAt !== 'string') return undefined;
+  const response = entries.find((entry) => entry.event === 'child-first-llm-call' && (entry.data.status === 'ok' || entry.data.status === 'error'));
+  const tool = entries.find((entry) => entry.event === 'child-first-tool-call' && typeof entry.data.at === 'string');
+  const status = response?.data.status === 'ok' || response?.data.status === 'error' ? response.data.status : 'started';
+  return {
+    status, provider: start.data.provider, model: start.data.model,
+    accountName: typeof start.data.accountName === 'string' ? start.data.accountName : null,
+    startedAt: start.data.startedAt,
+    ...(typeof response?.data.respondedAt === 'string' ? { respondedAt: response.data.respondedAt } : {}),
+    ...(typeof response?.data.httpStatus === 'number' ? { httpStatus: response.data.httpStatus } : {}),
+    ...(typeof response?.data.errorFirstLine === 'string' ? { errorFirstLine: response.data.errorFirstLine } : {}),
+    ...(typeof tool?.data.at === 'string' ? { firstToolCallAt: tool.data.at } : {}),
+  };
+}
+
+export function childFirstLlmStatusLabel(fact: ChildFirstLlmFact): string {
+  return fact.status === 'error' && fact.httpStatus !== undefined ? `error(${fact.httpStatus})` : fact.status;
+}
+
+export function childFirstLlmReportFact(entries: readonly Pick<RunLedgerEntry, 'event' | 'data'>[]): (ChildFirstLlmFact & { readonly statusLabel: string }) | undefined {
+  const fact = childFirstLlmFact(entries);
+  return fact ? { ...fact, statusLabel: childFirstLlmStatusLabel(fact) } : undefined;
+}