elanous 0.2.40 → 0.2.41

package/graphs/demo/persona-teacher/weekly-lesson.yaml

@@ -0,0 +1,36 @@
+# SW-PERSONA-TEACHER-WEEKLY-FU · GoalId d68f0e7e17725cef · 0.2.41 칸
+#
+# 교사 페르소나의 주간 반복: 일요일 20:00 Asia/Seoul 스케줄이 저장된 진도(앞선 런 원장의 record-progress 산출)를 읽고
+# 다음 단원을 lesson-pack 유닛으로 넘긴다. 진도를 아직 아무것도 못 읽은 첫 실행은 «기준선»만 기록하고 끝나며,
+# 그 기록이 다음 실행의 단원 선택을 바꾼다. lesson-pack 을 넘긴 실행은 교사 승인(hitl)에서 멈춘다 —
+# 승인은 사람 결정만 claim 하는 graph-approval-card 경로를 그대로 쓴다.
+graph_id: weekly-lesson
+version: 1
+loop:
+  title: 주간 수업 준비 (교사 페르소나)
+  description: 일요일 20:00 KST 에 저장된 진도를 읽어 다음 단원을 lesson-pack 그래프로 넘기고 교사 승인에서 멈춘다
+  trigger:
+    cron: '0 20 * * 0'
+    timezone: Asia/Seoul
+entry_node: read-progress
+terminal_nodes: [done, failed]
+nodes:
+  - { node_id: read-progress, kind: agent, recipe: 'cmd:read-progress', max_visits: 1 }
+  - { node_id: select-next, kind: agent, recipe: 'cmd:select-next', max_visits: 1 }
+  - node_id: lesson-pack
+    kind: subgraph
+    recipe: none
+    max_visits: 1
+    call: lesson-pack@1
+    budget: { inner_steps: 3 }
+    contract: { inputs: [select-next], tools: state-write, outputs: [lesson] }
+  - { node_id: teacher-approval, kind: hitl, recipe: 'approval:teacher', max_visits: 1 }
+  - { node_id: record-progress, kind: agent, recipe: 'cmd:record-progress', max_visits: 1 }
+  - { node_id: done, kind: gate, recipe: none, max_visits: 1 }
+  - { node_id: failed, kind: gate, recipe: none, max_visits: 1 }
+edges:
+  - { from: read-progress, on: outcome, map: { ok: select-next, fail: failed, error: failed } }
+  - { from: select-next, on: outcome, map: { baseline: record-progress, next: lesson-pack, fail: failed } }
+  - { from: lesson-pack, on: outcome, map: { ok: teacher-approval, fail: failed } }
+  - { from: teacher-approval, on: outcome, map: { ok: record-progress, fail: failed } }
+  - { from: record-progress, on: outcome, map: { ok: done, fail: failed } }

package/graphs/overlays/stop-heal-ladder.yaml

@@ -5,8 +5,8 @@
 #   stop_class == main-sync          → rebase-regate
 #   stop_class == pod-died           → resume-from-salvage
 #   stop_class == evidence-uncovered → derive-evidence-rejudge
-# ⛔ 이 넷 밖의 갈래(review-repeat · review-out-of-scope · scope-escape · fabric · launch-failed · unclassified)는 선언이 «없다» —
-#   처방은 `needs-owner` 이고 그것은 코드 기본(`AUTOHEAL_ACTION_BY_CLASS`)이 말한다.
+#   stop_class == review-budget-exhausted → review-round-reauthor
+# ⛔ 일반 반복·범위 밖·scope-escape·fabric·launch-failed·gate-failed·unclassified는 `needs-owner`로 남긴다.
 #
 # 🔑 노드 id 가 곧 처방 이름이다. `src/self-implement/stop-autoheal.ts` 는 그 갈래에 얹힌 오버레이가 «더한 노드 id» 로
 #   처방을 고르고, 선언이 없거나 못 읽으면 코드 표로 간다(원장·관측의 `source` = graph | code-default).
@@ -103,3 +103,24 @@ patch:
   - op: add
     path: /edges/-
     value: { from: derive-evidence-rejudge, on: outcome, map: { healed: dispatch, needs-owner: stopped } }
+---
+overlay_id: stop-heal-ladder-review-budget-exhausted
+target: self-implement
+stage: heal
+applies_when: stop_class == review-budget-exhausted
+patch:
+  - op: add
+    path: /nodes/-
+    value:
+      nodeId: review-round-reauthor
+      kind: judge
+      recipe: review-round-reauthor
+      maxVisits: 1
+      journeyStage: recover
+      contract: { inputs: [goal, review-history], tools: read-only, outputs: [partial-landing, follow-up-goal] }
+  - op: add
+    path: /edges/-
+    value: { from: heal, on: stop_class, map: { review-budget-exhausted: review-round-reauthor } }
+  - op: add
+    path: /edges/-
+    value: { from: review-round-reauthor, on: outcome, map: { healed: dispatch, follow-up: stopped, needs-owner: stopped } }

package/graphs/release/release-loop.yaml

@@ -5,7 +5,9 @@ loop:
   title: 릴리스
   description: 승인된 판을 빌드·검증·게시한다
   trigger:
-    events: [manual]
+    events: [manual, release.cut.due]
+triggers:
+  schedule: { type: cron, cron: '* * * * *' }
 version: 1
 entry_node: version-release
 dry_run_await_approval: true

package/graphs/units/gate/gate.yaml

@@ -0,0 +1,20 @@
+graph_id: gate
+version: 1
+unit:
+  inputs: [goal, context, feedback, budget, checkpoint]
+  outputs: [gate-verdict, evidence]
+  exits: [pass, fail, sync, open]
+entry_node: gate
+terminal_nodes: [pass, fail, sync, open]
+nodes:
+  - node_id: gate
+    kind: gate
+    recipe: gate-stage
+    max_visits: 8
+    contract: { inputs: [goal, context, feedback, budget, checkpoint], tools: read-only, outputs: [gate-verdict, evidence] }
+  - { node_id: pass, kind: observe, recipe: none, max_visits: 1 }
+  - { node_id: fail, kind: observe, recipe: none, max_visits: 1 }
+  - { node_id: sync, kind: observe, recipe: none, max_visits: 1 }
+  - { node_id: open, kind: observe, recipe: none, max_visits: 1 }
+edges:
+  - { from: gate, on: outcome, map: { pass: pass, fail: fail, sync: sync, open: open } }

package/graphs/units/git/git.yaml

@@ -0,0 +1,26 @@
+graph_id: git
+version: 1
+unit:
+  inputs: [goal, context, feedback, budget, checkpoint]
+  outputs: [commit, pr-number, evidence]
+  exits: [to-regate, to-open-pr, to-merge]
+  entries: [main-sync, open-pr]
+entry_node: main-sync
+terminal_nodes: [to-regate, to-open-pr, to-merge]
+nodes:
+  - node_id: main-sync
+    kind: git
+    recipe: git-main-sync
+    max_visits: 2
+    contract: { inputs: [goal, context, feedback, budget, checkpoint], tools: external-write, outputs: [commit, evidence] }
+  - node_id: open-pr
+    kind: git
+    recipe: git-open-pr
+    max_visits: 1
+    contract: { inputs: [goal, context, feedback, budget, checkpoint], tools: external-write, outputs: [pr-number, evidence] }
+  - { node_id: to-regate, kind: observe, recipe: none, max_visits: 1 }
+  - { node_id: to-open-pr, kind: observe, recipe: none, max_visits: 1 }
+  - { node_id: to-merge, kind: observe, recipe: none, max_visits: 1 }
+edges:
+  - { from: main-sync, on: outcome, map: { to-regate: to-regate, to-open-pr: to-open-pr } }
+  - { from: open-pr, on: outcome, map: { to-merge: to-merge } }

package/graphs/units/implement/implement.yaml

@@ -0,0 +1,19 @@
+graph_id: implement
+version: 1
+unit:
+  inputs: [goal, context, feedback, budget, checkpoint]
+  outputs: [diff, evidence, result]
+  exits: [done, rework, failed]
+entry_node: implement
+terminal_nodes: [done, rework, failed]
+nodes:
+  - node_id: implement
+    kind: agent
+    recipe: implement-stage
+    max_visits: 6
+    contract: { inputs: [goal, context, feedback, budget, checkpoint], tools: external-write, outputs: [diff, evidence, result] }
+  - { node_id: done, kind: observe, recipe: none, max_visits: 1 }
+  - { node_id: rework, kind: observe, recipe: none, max_visits: 1 }
+  - { node_id: failed, kind: observe, recipe: none, max_visits: 1 }
+edges:
+  - { from: implement, on: outcome, map: { done: done, rework: rework, failed: failed } }

package/graphs/units/landing/landing.yaml

@@ -0,0 +1,18 @@
+graph_id: landing
+version: 1
+unit:
+  inputs: [goal, context, feedback, budget, checkpoint]
+  outputs: [merge-sha, evidence]
+  exits: [merged, refused]
+entry_node: merge
+terminal_nodes: [merged, refused]
+nodes:
+  - node_id: merge
+    kind: git
+    recipe: git-merge
+    max_visits: 1
+    contract: { inputs: [goal, context, feedback, budget, checkpoint], tools: external-write, outputs: [merge-sha, evidence] }
+  - { node_id: merged, kind: observe, recipe: none, max_visits: 1 }
+  - { node_id: refused, kind: observe, recipe: none, max_visits: 1 }
+edges:
+  - { from: merge, on: outcome, map: { merged: merged, refused: refused } }

package/graphs/units/review/review.yaml

@@ -0,0 +1,20 @@
+graph_id: review
+version: 1
+unit:
+  inputs: [goal, context, feedback, budget, checkpoint]
+  outputs: [verdict, must-fix, evidence]
+  exits: [pass, fail, sync, open]
+entry_node: review
+terminal_nodes: [pass, fail, sync, open]
+nodes:
+  - node_id: review
+    kind: judge
+    recipe: review-stage
+    max_visits: 8
+    contract: { inputs: [goal, context, feedback, budget, checkpoint], tools: read-only, outputs: [verdict, must-fix, evidence] }
+  - { node_id: pass, kind: observe, recipe: none, max_visits: 1 }
+  - { node_id: fail, kind: observe, recipe: none, max_visits: 1 }
+  - { node_id: sync, kind: observe, recipe: none, max_visits: 1 }
+  - { node_id: open, kind: observe, recipe: none, max_visits: 1 }
+edges:
+  - { from: review, on: outcome, map: { pass: pass, fail: fail, sync: sync, open: open } }

package/graphs/units/verbs/recipes.yaml

@@ -1,6 +1,9 @@
 make-doc-input:
   command: 'bun scripts/graph-units/verbs-envelope.ts make-doc-input'
   timeout_ms: 10000
+research:
+  command: 'bun scripts/graph-units/verbs/research.ts'
+  timeout_ms: 300000
 make-doc-output:
   command: 'bun scripts/graph-units/verbs-envelope.ts make-doc-output'
   timeout_ms: 10000

package/graphs/units/verbs/research.yaml

@@ -0,0 +1,20 @@
+graph_id: verb-research
+version: 1
+entry_node: research
+terminal_nodes: [done, failed]
+unit:
+  inputs: [ask]
+  outputs: [result, evidence]
+  exits: [done, failed]
+nodes:
+  - node_id: research
+    kind: agent
+    recipe: 'cmd:research'
+    max_visits: 1
+    contract: { inputs: [ask], tools: omni-crawl-research-write-edit-denied, outputs: [outcome, result, evidence] }
+  - { node_id: done, kind: gate, recipe: none, max_visits: 1, contract: { inputs: [], tools: none, outputs: [result, evidence] } }
+  - { node_id: failed, kind: observe, recipe: none, max_visits: 1, contract: { inputs: [], tools: none, outputs: [result, evidence] } }
+edges:
+  - from: research
+    on: outcome
+    map: { done: done, failed: failed }

package/graphs/work/research-report.yaml

@@ -2,9 +2,16 @@ graph_id: work-research-report-rehearsal
 version: 1
 # TASK-HAND-GRAPH-RUN — `tasks hand --completion research-report` 가 이 조합을 실제 graph run(runGraph)으로 발사한다.
 launcher: graph-run
-entry_node: make-doc
+entry_node: research
 terminal_nodes: [done, failed]
 nodes:
+  - node_id: research
+    kind: subgraph
+    recipe: none
+    max_visits: 1
+    call: verb-research@1
+    budget: { inner_steps: 4 }
+    contract: { inputs: [ask], tools: omni-crawl-research-write-edit-denied, outputs: [result, evidence] }
   - node_id: make-doc
     kind: subgraph
     recipe: none
@@ -22,6 +29,9 @@ nodes:
   - { node_id: done, kind: gate, recipe: none, max_visits: 1 }
   - { node_id: failed, kind: gate, recipe: none, max_visits: 1 }
 edges:
+  - from: research
+    on: outcome
+    map: { done: make-doc, failed: failed }
   - from: make-doc
     on: outcome
     map: { done: verify, rework: make-doc, needs-human: failed, failed: failed }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "elanous",
   "mcpName": "io.github.ElanvitalAI/elanous",
-  "version": "0.2.40",
+  "version": "0.2.41",
   "description": "Self-healing coding harness where eyes, hands, and memory all turn on one sentence — it authors its own goals, implements them in isolated worktrees, and reviews its own work.",
   "license": "Apache-2.0",
   "author": "Elanvital AI",

package/scripts/disk-steward.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env bun
+/**
+ * 디스크 관리자 손 실행 입구(DISK-STEWARD-CORE). 정식 CLI·넥서스 틱 배선은 후속 칸(WIRE·HOST-AGENT) 몫이다.
+ *
+ *   bun scripts/disk-steward.ts run [--apply] [--json] [--repo <dir>]
+ *   bun scripts/disk-steward.ts request <path> --kind <worktree|graph-context|pod-dir|tmp> [--owner o] [--reason r]
+ *
+ * ⭐ `run` 은 기본 dry-run 이다 — `--apply` 를 줘야 지운다.
+ */
+import { requestReclaim, RECLAIM_KINDS, type ReclaimKind } from '../src/disk-steward/ledger.js';
+import { defaultListOpenPrs, runDiskSteward } from '../src/disk-steward/steward.js';
+
+const argv = process.argv.slice(2);
+const flag = (name: string): string | undefined => {
+  const i = argv.indexOf(name);
+  return i >= 0 ? argv[i + 1] : undefined;
+};
+
+async function main(): Promise<number> {
+  const [sub, target] = argv;
+  if (sub === 'request') {
+    const kind = flag('--kind') as ReclaimKind | undefined;
+    if (!target || !kind || !(RECLAIM_KINDS as readonly string[]).includes(kind)) {
+      console.error(`usage: request <abs-path> --kind <${RECLAIM_KINDS.join('|')}>`);
+      return 2;
+    }
+    const r = requestReclaim({ path: target, kind, owner: flag('--owner'), reason: flag('--reason'), requester: 'cli:disk-steward' });
+    console.log(JSON.stringify(r));
+    return r.ok ? 0 : 1;
+  }
+  if (sub === 'run') {
+    const repo = flag('--repo') ?? process.cwd();
+    const r = await runDiskSteward({ apply: argv.includes('--apply') }, { listOpenPrs: () => defaultListOpenPrs(repo) });
+    if (argv.includes('--json')) console.log(JSON.stringify(r, null, 1));
+    else {
+      const { entries, ...summary } = r;
+      console.log(JSON.stringify(summary));
+      for (const e of entries) console.log(`${e.action}\t${e.kind}\t${e.path}\t${e.reason}`);
+    }
+    return r.outcome === 'pr-list-unavailable' || r.outcome === 'live-list-unavailable' || r.failed > 0 ? 1 : 0;
+  }
+  console.error('usage: disk-steward.ts run [--apply] [--json] [--repo <dir>] | request <path> --kind <kind>');
+  return 2;
+}
+
+process.exitCode = await main();

package/scripts/fleet/node-setup.sh

@@ -54,6 +54,56 @@ R true >/dev/null 2>&1 && ok "ssh" || { bad "ssh 불통 — 이 맥에서 ssh
 # 1b. 원격 OS — Linux(WSL Ubuntu 등)면 리눅스 갈래(scripts/fleet/node-setup-linux.sh · apt·docker-ce·k3d install.sh). 맥은 아래 종전 단계 그대로.
 NODE_OS="$(R 'uname -s' 2>/dev/null)"
 if [ "$NODE_OS" = Linux ]; then . "$ROOT/scripts/fleet/node-setup-linux.sh"; linux_base; else
+# 1c. 전용 서버 macOS 전원·재시작 기본값 — 이 스크립트는 gate·Pod 플릿 호스트 전용이다.
+#     --check 는 조회만 한다. sudo -n 이 안 되면 이 단계만 건너뛰고 경고하며, 나머지 셋업은 계속한다.
+if [ $CHECK = 1 ]; then
+  if R 'sudo -n true' >/dev/null 2>&1; then
+    POWER_SETTINGS="$(R 'sudo -n pmset -g custom' 2>/dev/null)"
+    RESTART_SETTINGS="$(R 'sudo -n systemsetup -getrestartpowerfailure' 2>/dev/null)"
+    UPDATE_INSTALL="$(R 'sudo -n defaults read /Library/Preferences/com.apple.SoftwareUpdate AutomaticInstallMacOSUpdates' 2>/dev/null)"
+    UPDATE_DOWNLOAD="$(R 'sudo -n defaults read /Library/Preferences/com.apple.SoftwareUpdate AutomaticDownload' 2>/dev/null)"
+    POWER_SOURCES_OK=0
+    if awk '
+      function check_source() {
+        if (autorestart != "1" || powernap != "0" || sleep_value != "0" || disksleep != "0") bad = 1
+      }
+      /^[[:space:]]*(Battery|AC) Power:[[:space:]]*$/ {
+        if (found) check_source()
+        found = 1
+        autorestart = powernap = sleep_value = disksleep = ""
+        next
+      }
+      found {
+        if ($1 == "autorestart") autorestart = $2
+        else if ($1 == "powernap") powernap = $2
+        else if ($1 == "sleep") sleep_value = $2
+        else if ($1 == "disksleep") disksleep = $2
+      }
+      END {
+        if (found) check_source()
+        if (!found || bad) exit 1
+      }
+    ' <<< "$POWER_SETTINGS"; then POWER_SOURCES_OK=1; fi
+    if [ "$POWER_SOURCES_OK" = 1 ] \
+      && [ "$RESTART_SETTINGS" = 'Restart After Power Failure: On' ] \
+      && [ "$UPDATE_INSTALL" = '0' ] \
+      && [ "$UPDATE_DOWNLOAD" = '0' ]; then
+      ok "macOS 서버 전원·재시작 기본값"
+    else todo "macOS 서버 전원·재시작 기본값 적용"; fi
+  else
+    printf '  ⚠ macOS 서버 전원 기본값 건너뜀 — sudo -n 사용 불가\n' >&2
+    todo "macOS 서버 전원·재시작 기본값 (sudo 필요)"
+  fi
+else
+  if R 'sudo -n true' >/dev/null 2>&1; then
+    if R 'sudo -n pmset -a autorestart 1 powernap 0 sleep 0 disksleep 0 && sudo -n systemsetup -setrestartpowerfailure on && sudo -n defaults write /Library/Preferences/com.apple.SoftwareUpdate AutomaticInstallMacOSUpdates -bool false && sudo -n defaults write /Library/Preferences/com.apple.SoftwareUpdate AutomaticDownload -bool false'; then
+      ok "macOS 서버 전원·재시작 기본값 적용"
+    else bad "macOS 서버 전원·재시작 기본값 적용 실패"; fi
+  else
+    printf '  ⚠ macOS 서버 전원 기본값 건너뜀 — sudo -n 사용 불가\n' >&2
+    todo "macOS 서버 전원·재시작 기본값 (sudo 필요)"
+  fi
+fi
 # 2. brew · docker(OrbStack)
 R 'command -v brew' >/dev/null && ok "brew" || bad "brew 없음 — https://brew.sh 로 먼저 설치(사람이)"
 if R 'docker info --format "{{.ServerVersion}}"' >/dev/null 2>&1; then ok "docker $(R 'docker info --format "{{.ServerVersion}} cpu={{.NCPU}} mem={{.MemTotal}}"')"; else bad "docker 없음·꺼짐 — OrbStack 을 설치·실행(사람이 · ⛔ OrbStack 내장 k8s 는 NetworkPolicy 를 집행 안 한다 · k3d 를 쓴다)"; fi

package/scripts/graph-units/verbs/research.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from 'node:fs';
+import { invokeResearch } from '../../../src/research-bridge/invoke.js';
+import type { ExternalResearchResult } from '../../../src/research-bridge/types.js';
+
+type GraphContext = { graphId: string; input: { ask?: unknown } };
+type ResearchInvoker = (topic: string) => Promise<ExternalResearchResult>;
+
+export interface ResearchUnitOutput {
+  outcome: 'done' | 'failed';
+  result: { result: { title: string; collectedAt: string; facts: string[]; sources: string[] }; evidence: Record<string, unknown> };
+  evidence: Record<string, unknown>;
+}
+
+/** Keep the independent search result and its source envelope together for the downstream document unit. */
+export async function researchUnitOutput(topic: string, search: ResearchInvoker = invokeResearch): Promise<ResearchUnitOutput> {
+  const query = topic.trim();
+  if (!query) throw new Error('verb-research input missing: ask');
+  const response = await search(query);
+  const sources = [...new Set((response.output.match(/https?:\/\/[^\s<>"']+/g) ?? [])
+    .map((value) => value.replace(/[),.;!?]+$/, ''))
+    .filter((value) => { try { new URL(value); return true; } catch { return false; } }))];
+  const complete = response.ok && response.output.trim().length > 0 && sources.length > 0;
+  const evidence = {
+    source: response.skill,
+    method: 'independent omni-crawl search',
+    query,
+    observedAt: response.finishedAt,
+    sources,
+    outcome: complete ? 'complete' : 'failed',
+    ...(response.error ? { limitations: response.error } : {}),
+  };
+  return {
+    outcome: complete ? 'done' : 'failed',
+    result: {
+      result: { title: query, collectedAt: response.finishedAt, facts: response.output.trim() ? [response.output.trim()] : [], sources },
+      evidence,
+    },
+    evidence,
+  };
+}
+
+async function run(): Promise<void> {
+  const contextPath = process.env.ELANOUS_GRAPH_CONTEXT;
+  if (!contextPath) throw new Error('ELANOUS_GRAPH_CONTEXT is required');
+  const context = JSON.parse(readFileSync(contextPath, 'utf8')) as GraphContext;
+  if (context.graphId !== 'verb-research') throw new Error('invalid verb-research graph context');
+  process.stdout.write(`${JSON.stringify(await researchUnitOutput(typeof context.input?.ask === 'string' ? context.input.ask : ''))}\n`);
+}
+
+if (import.meta.main) {
+  run().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/scripts/llm-cost-ledger.ts

@@ -10,6 +10,7 @@ import {
   estimateLlmCost,
   readLlmConfigPricing,
   type LlmCostUsage,
+  type LlmPricingUsd,
 } from '../src/budget/llm-cost.js';
 
 const PAGE_LIMIT = '100000';
@@ -38,6 +39,8 @@ export interface LlmCostLedgerSummary {
   partialModels: string[];
   incomplete: boolean;
   failure?: string;
+  /** 공급자 잔액 관측이 주어졌을 때만 — 없으면 원장 출력은 종전과 바이트 동일. */
+  reconcile?: LlmCostReconcile;
 }
 
 export interface UsageLogFetchResult {
@@ -48,6 +51,134 @@ export interface UsageLogFetchResult {
   signal?: NodeJS.Signals | null;
 }
 
+/** 경보 임계 — 측정액과 공급자 잔액 변화의 차이가 이 비율을 «초과» 하면 경보(10%). */
+export const RECONCILE_THRESHOLD_RATIO = 0.1;
+
+/** 대조에 필요한 잔액 관측 — 전일 잔액과 금일 잔액(공급자 보고 USD). */
+export interface LlmCostLedgerBalance {
+  beforeUsd: number;
+  afterUsd: number;
+  provider?: string;
+}
+
+export type LlmCostReconcileStatus = 'ok' | 'alert' | 'unmeasured';
+
+export type LlmCostReconcileReason = 'balance-increased' | 'no-balance-change';
+
+/** 일별 토큰×단가 합계와 공급자 잔액 변화의 대조 결과. */
+export interface LlmCostReconcile {
+  /** 호출자가 실제로 관측해 넘긴 공급자 이름만 — 모르면 필드 자체가 없다(합성 기본값 없음). */
+  provider?: string;
+  /** 대조에 넣은 달러 = known + partial (측정 가능분). */
+  measuredUsd: number;
+  knownUsd: number;
+  partialUsd: number;
+  /** 단가를 몰라 대조에서 빠진 잔여 — 0 USD 로 꾸미지 않고 칸으로 남긴다. */
+  unmeasuredRows: number;
+  unmeasuredModels: string[];
+  unmeasuredUsd: null;
+  balanceBeforeUsd: number;
+  balanceAfterUsd: number;
+  /** 전일 잔액 − 금일 잔액. */
+  balanceDeltaUsd: number;
+  /** 잔액이 줄지 않았으면(충전) 대조 불가 — null. */
+  diffUsd: number | null;
+  diffRatio: number | null;
+  thresholdRatio: number;
+  status: LlmCostReconcileStatus;
+  reason?: LlmCostReconcileReason;
+}
+
+export interface ReconcileLlmCostInput {
+  measuredUsd: number;
+  knownUsd?: number;
+  partialUsd?: number;
+  unmeasuredRows?: number;
+  unmeasuredModels?: readonly string[];
+  balanceBeforeUsd: number;
+  balanceAfterUsd: number;
+  provider?: string;
+  thresholdRatio?: number;
+}
+
+function reconcileNumber(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+/** 일별 토큰×단가 합계(measuredUsd)를 공급자 잔액 변화(before − after)와 대조한다.
+ *  ⛔ 새 비용 축을 만들지 않는다 — 단가 축은 `estimateLlmCost` 합계, 공급자 축은 잔액 관측 그대로다. */
+export function reconcileLlmCostVsBalance(input: ReconcileLlmCostInput): LlmCostReconcile {
+  const measuredUsd = reconcileNumber(input.measuredUsd, 0);
+  const knownUsd = reconcileNumber(input.knownUsd, 0);
+  const partialUsd = reconcileNumber(input.partialUsd, 0);
+  const unmeasuredRows = reconcileNumber(input.unmeasuredRows, 0);
+  const thresholdRatio = reconcileNumber(input.thresholdRatio, RECONCILE_THRESHOLD_RATIO);
+  const balanceBeforeUsd = reconcileNumber(input.balanceBeforeUsd, 0);
+  const balanceAfterUsd = reconcileNumber(input.balanceAfterUsd, 0);
+  const balanceDeltaUsd = balanceBeforeUsd - balanceAfterUsd;
+
+  let diffUsd: number | null = null;
+  let diffRatio: number | null = null;
+  let status: LlmCostReconcileStatus = 'ok';
+  let reason: LlmCostReconcileReason | undefined;
+  if (balanceDeltaUsd < 0) {
+    status = 'unmeasured';
+    reason = 'balance-increased';
+  } else if (balanceDeltaUsd === 0) {
+    diffUsd = measuredUsd;
+    if (measuredUsd > 0) {
+      status = 'alert';
+      reason = 'no-balance-change';
+    }
+  } else {
+    diffUsd = Math.abs(measuredUsd - balanceDeltaUsd);
+    diffRatio = diffUsd / balanceDeltaUsd;
+    if (diffRatio > thresholdRatio) status = 'alert';
+  }
+
+  const provider = typeof input.provider === 'string' ? input.provider.trim() : '';
+  return {
+    ...(provider ? { provider } : {}),
+    measuredUsd,
+    knownUsd,
+    partialUsd,
+    unmeasuredRows,
+    unmeasuredModels: [...(input.unmeasuredModels ?? [])].sort(),
+    unmeasuredUsd: null,
+    balanceBeforeUsd,
+    balanceAfterUsd,
+    balanceDeltaUsd,
+    diffUsd,
+    diffRatio,
+    thresholdRatio,
+    status,
+    ...(reason ? { reason } : {}),
+  };
+}
+
+function ratioText(value: number | null): string {
+  return value === null ? 'unmeasured' : String(Math.round(value * 1e6) / 1e6);
+}
+
+function formatReconcileLines(reconcile: LlmCostReconcile): string[] {
+  return [
+    `reconcileProvider ${reconcile.provider ?? '(unknown)'}`,
+    `reconcileMeasuredUsd ${reconcile.measuredUsd}`,
+    `reconcileKnownUsd ${reconcile.knownUsd}`,
+    `reconcilePartialUsd ${reconcile.partialUsd}`,
+    `reconcileUnmeasuredRows ${reconcile.unmeasuredRows}`,
+    `reconcileUnmeasuredModels ${reconcile.unmeasuredModels.join(',') || '(none)'}`,
+    `reconcileBalanceDeltaUsd ${reconcile.balanceDeltaUsd}`,
+    `reconcileDiffUsd ${reconcile.diffUsd === null ? 'unmeasured' : reconcile.diffUsd}`,
+    `reconcileDiffRatio ${ratioText(reconcile.diffRatio)}`,
+    `reconcileThreshold ${reconcile.thresholdRatio}`,
+    `reconcileStatus ${reconcile.status}${reconcile.reason ? ` ${reconcile.reason}` : ''}`,
+    ...(reconcile.status === 'alert'
+      ? [`alert reconcile-diff measuredUsd ${reconcile.measuredUsd} balanceDeltaUsd ${reconcile.balanceDeltaUsd} diffUsd ${reconcile.diffUsd} diffRatio ${ratioText(reconcile.diffRatio)} threshold ${reconcile.thresholdRatio}`]
+      : []),
+  ];
+}
+
 function asRecord(value: unknown): Record<string, unknown> | undefined {
   return value && typeof value === 'object' && !Array.isArray(value)
     ? value as Record<string, unknown>
@@ -246,11 +377,12 @@ export function formatLlmCostLedger(summary: LlmCostLedgerSummary): string {
     `rows ${summary.rows}`,
     `incomplete ${summary.incomplete ? 'true' : 'false'}`,
     ...(summary.failure ? [`failure ${summary.failure}`] : []),
+    ...(summary.reconcile ? formatReconcileLines(summary.reconcile) : []),
   ].join('\n');
 }
 
-function readUsageLogs(repoRoot: string): { lines: string[]; incomplete: boolean; failure?: string } {
-  return collectUsageLogPages((before) => {
+function spawnUsageLogPage(repoRoot: string): (before?: string) => UsageLogFetchResult {
+  return (before) => {
     const args = before ? [...LOGS_ARGS, '--before', before] : [...LOGS_ARGS];
     const result = spawnSync('bun', args, {
       cwd: repoRoot,
@@ -265,21 +397,60 @@ function readUsageLogs(repoRoot: string): { lines: string[]; incomplete: boolean
       error: result.error ?? null,
       signal: result.signal ?? null,
     };
-  });
+  };
+}
+
+/** 생산 진입점 테스트 시젠 — 로그 페이지 공급자·잔액 관측·출력 싱크를 주입한다. */
+export interface LlmCostLedgerDeps {
+  fetchPage?: (before?: string) => UsageLogFetchResult;
+  balance?: LlmCostLedgerBalance;
+  configPricing?: Readonly<Record<string, LlmPricingUsd>>;
+  out?: (line: string) => void;
 }
 
-export function main(repoRoot: string = join(import.meta.dir, '..')): LlmCostLedgerSummary {
-  const { lines, incomplete, failure } = readUsageLogs(repoRoot);
+/** `--balance-before <usd> --balance-after <usd> [--balance-provider <name>]` — 공급자 잔액 관측. */
+function cliBalance(argv: readonly string[]): LlmCostLedgerBalance | undefined {
+  const flag = (name: string): string | undefined => {
+    const index = argv.indexOf(name);
+    return index >= 0 ? argv[index + 1] : undefined;
+  };
+  const before = Number(flag('--balance-before'));
+  const after = Number(flag('--balance-after'));
+  if (!Number.isFinite(before) || !Number.isFinite(after) || before < 0 || after < 0) return undefined;
+  const provider = flag('--balance-provider');
+  return { beforeUsd: before, afterUsd: after, ...(provider ? { provider } : {}) };
+}
+
+export function main(
+  repoRoot: string = join(import.meta.dir, '..'),
+  deps: LlmCostLedgerDeps = {},
+): LlmCostLedgerSummary {
+  const { lines, incomplete, failure } = collectUsageLogPages(deps.fetchPage ?? spawnUsageLogPage(repoRoot));
+  const totals = summarizeLlmUsageRows(lines, deps.configPricing ?? readLlmConfigPricing());
+  const reconcile = deps.balance
+    ? reconcileLlmCostVsBalance({
+        measuredUsd: totals.measurableUsd,
+        knownUsd: totals.knownUsd,
+        partialUsd: totals.partialUsd,
+        unmeasuredRows: totals.unknownRows,
+        unmeasuredModels: totals.unknownModels,
+        balanceBeforeUsd: deps.balance.beforeUsd,
+        balanceAfterUsd: deps.balance.afterUsd,
+        ...(deps.balance.provider ? { provider: deps.balance.provider } : {}),
+      })
+    : undefined;
   const summary: LlmCostLedgerSummary = {
-    ...summarizeLlmUsageRows(lines),
+    ...totals,
     incomplete,
     ...(failure ? { failure } : {}),
+    ...(reconcile ? { reconcile } : {}),
   };
-  console.log(formatLlmCostLedger(summary));
+  (deps.out ?? console.log)(formatLlmCostLedger(summary));
   return summary;
 }
 
 if (import.meta.main) {
-  const summary = main();
+  const balance = cliBalance(process.argv.slice(2));
+  const summary = main(join(import.meta.dir, '..'), { ...(balance ? { balance } : {}) });
   if (summary.incomplete) process.exit(1);
 }