elanous 0.2.38 → 0.2.41

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/lib/morning-report-options.ts

@@ -12,10 +12,9 @@
 //     경로(model 미지정 ⇒ providerFor(cfg))를 그대로 보존한다. 값이 없거나 빈 값이면
 //     parseArgv 오류를 던져 기본 모델로 조용히 실행되지 않도록 한다.
 //
-// ⛔ 의도된 경계(비연결 선언): 이 유닛은 «정의 + 단위시험» 에서 멈춘다.
-//   scripts/morning-report.ts 탑레벨(CLI 진입) → composeMorningReport(..., { model }) 배선은
-//   의존 형제 샤드(task:d0183079b142)의 몫이다. 지금 이 유닛을 실행 경로에서 부르는 곳은
-//   scripts/lib/morning-report-options.test.ts(bun test, in-process) 다.
+// ✅ 배선 완료(SWAP-BENCH-CRON): scripts/morning-report.ts 탑레벨(CLI 진입)이 이 파서를
+//   호출해 --narrative-model 값을 composeMorningReport(..., { model }) 로 넘긴다.
+//   배선 계약 시험은 test/morning-report.test.ts(mock 무대)가 누른다.
 
 import { parseArgv, type ArgvContract } from './argv.js';
 

package/scripts/lib/tui-regress-evidence.ts

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface TuiRegressFailureEvidence {
+  runId: string;
+  event: string;
+  verificationCommand: string;
+  artifactRoot: string;
+  configDir: string;
+  check: { id: string; title: string; role: string };
+  screens: Record<string, string>;
+  pty: { cols: number; rows: number; bootMs: number };
+  environment: {
+    driveTui: string;
+    nodeEnv: string | null;
+    credentialVariablesPresent: string[];
+  };
+  verdict: { ok: boolean; reason: string };
+}
+
+function redactConfig(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(redactConfig);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [
+      key,
+      /api.?key|token|secret|password|credential/i.test(key) ? '[REDACTED]' : redactConfig(child),
+    ]));
+  }
+  return value;
+}
+
+export function preserveTuiRegressFailure(input: TuiRegressFailureEvidence): string {
+  mkdirSync(input.artifactRoot, { recursive: true });
+  const artifactDir = mkdtempSync(join(input.artifactRoot, `${input.check.id}-`));
+  const screensDir = join(artifactDir, 'screens');
+  mkdirSync(screensDir);
+  for (const [name, screen] of Object.entries(input.screens)) writeFileSync(join(screensDir, `${name}.txt`), screen);
+
+  const configPath = join(input.configDir, 'config.json');
+  let effectiveConfig: unknown = { unavailable: !existsSync(configPath) };
+  if (existsSync(configPath)) {
+    try { effectiveConfig = redactConfig(JSON.parse(readFileSync(configPath, 'utf8'))); }
+    catch (error) { effectiveConfig = { parseError: String(error), bytes: readFileSync(configPath).byteLength }; }
+  }
+  writeFileSync(join(artifactDir, 'effective-config.json'), `${JSON.stringify(effectiveConfig, null, 2)}\n`);
+  writeFileSync(join(artifactDir, 'run.json'), `${JSON.stringify({
+    runId: input.runId,
+    event: input.event,
+    verificationCommand: input.verificationCommand,
+    check: input.check,
+    pty: input.pty,
+    environment: input.environment,
+    verdict: input.verdict,
+  }, null, 2)}\n`);
+  return artifactDir;
+}

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

package/scripts/measure-nl-routing-corpus.ts

@@ -208,6 +208,12 @@ function expectationsMet(expects: readonly NlRoutingToolExpectation[], breakdown
   return expects.every((expectation) => (breakdown[expectation.tool] ?? 0) >= (expectation.minCount ?? 1));
 }
 
+/**
+ * v5 채점의 최소 실행 턴 — 코퍼스 예산(CORPUS_BUDGETS) 과 «독립»인 채점 턴 정책 상수.
+ * 낮은 예산에서 복합 발화가 예산 부족만으로 거짓 실패하지 않게 한다.
+ */
+export const NL_ROUTING_V5_MIN_SCORING_TURNS = 6;
+
 /** v5 28문항을 «생산 runEvalPrompt seam» 으로 그대로 돌려 경로·복합 처리를 채점한다. */
 export async function scoreNlRoutingV5(opts: {
   runPrompt: typeof runEvalPrompt;
@@ -215,7 +221,7 @@ export async function scoreNlRoutingV5(opts: {
   cwd: string;
   maxTurns?: number;
 }): Promise<NlRoutingV5Score> {
-  const maxTurns = opts.maxTurns ?? 6;
+  const maxTurns = opts.maxTurns ?? NL_ROUTING_V5_MIN_SCORING_TURNS;
   const matched = new Set<string>();
   const failed: string[] = [];
   const patternMismatches: string[] = [];
@@ -401,7 +407,9 @@ export async function main(
   //   (다른 자로 재면 판정선과 비교 불가 · 형태 F3). 임계 미달은 «조용한 0» 이 아니라 거부다.
   let v5: NlRoutingV5Score | undefined;
   if (process.env.CORPUS_V5 === '1') {
-    v5 = await scoreNlRoutingV5({ runPrompt, surface, cwd: corpusCwd, maxTurns: budgets[0] });
+    // ⛔ 채점 턴 정책은 코퍼스 예산과 «독립»이다 — 예산은 코퍼스 생성 실행 횟수만 제어하고
+    //   채점 maxTurns 는 NL_ROUTING_V5_MIN_SCORING_TURNS 기본(또는 명시적 opts)에서만 온다.
+    v5 = await scoreNlRoutingV5({ runPrompt, surface, cwd: corpusCwd });
     console.log(`[v5] patterns ${v5.patterns} (path ${v5.pathPatterns} · compound ${v5.compoundPatterns}) · 문항 ${v5.questions} (path ${v5.pathQuestions} · compound ${v5.compoundQuestions}) · 채점 ${v5.scored} · 통과 ${v5.passed} · 실패 ${v5.failed.length ? v5.failed.join(',') : '(없음)'} · 실행 실패 ${v5.failedRuns} · masking-leak ${v5.maskingLeaks.length} ${v5.maskingLeaks.length ? v5.maskingLeaks.join(',') : '(없음)'} · pattern-mismatch ${v5.patternMismatches.length ? v5.patternMismatches.join(',') : '(없음)'} · 판정 ${v5.verdict}`);
     if (!v5.thresholdsMet) {
       throw new Error(

package/scripts/morning-report.ts

@@ -4,12 +4,14 @@
 //   bun run scripts/morning-report.ts --dry        # compose only (stdout, no send)
 //   bun run scripts/morning-report.ts --no-narrate # skip the LLM 시장서사 layer
 //   bun run scripts/morning-report.ts --no-upload  # skip S3 상세 업로드(로컬 미리보기)
+//   bun run scripts/morning-report.ts --narrative-model <model>  # 시장서사 LLM 모델 명시(A/B)
 
 import { composeMorningReport } from '../src/domains/morning-report.js';
 import { explainReportRoute, sendTelegramReport, sendReportPhoto } from '../src/telegram-report.js';
 import { getUserConfig } from '../src/user-config.js';
 import { getFirecrawlConfig } from '../src/registry/discovery/config.js';
 import { captureFinvizMapImageUrl } from '../src/domains/finviz-image.js';
+import { parseNarrativeModelArg } from './lib/morning-report-options.js';
 
 import { registerStandaloneLogSink } from '../src/domains/standalone-log-sink.js';
 
@@ -20,6 +22,8 @@ const dry = process.argv.includes('--dry');
 const cfg = getUserConfig();
 const narrate = cfg.finance.morningNarrative !== false && !process.argv.includes('--no-narrate');
 const upload = !process.argv.includes('--no-upload');
+// --narrative-model X / =X — 값이 없으면 parseNarrativeModelArg 가 throw(기본 모델로 조용히 대체하지 않는다).
+const model = parseNarrativeModelArg(process.argv.slice(2));
 
 // finviz S&P 히트맵 이미지 — HTML 상세 리포트에 임베드 + 텔레그램 포토로도 발송. 키 있을 때만.
 let heatmapImageUrl: string | undefined;
@@ -31,7 +35,7 @@ if (cfg.finance.morningHeatmapImage !== false) {
   } catch (e) { console.error(`[morning-report] heatmap capture error: ${e instanceof Error ? e.message : String(e)}`); }
 }
 
-const report = await composeMorningReport(new Date(), { narrate, heatmapImageUrl, upload });
+const report = await composeMorningReport(new Date(), { narrate, heatmapImageUrl, upload, model });
 
 if (dry) {
   console.log(report);

package/scripts/persona-teacher/weekly-lesson-node.ts

@@ -0,0 +1,172 @@
+/**
+ * SW-PERSONA-TEACHER-WEEKLY-FU (GoalId d68f0e7e17725cef) — weekly lesson node commands.
+ *
+ * 각 명령은 runner 가 심는 `ELANOUS_GRAPH_CONTEXT`(이번 노드의 input + 앞 노드들의 구조 산출)를 읽고
+ * 마지막 한 줄 JSON 으로 다음 간선의 `outcome` 을 낸다. 진도는 새 저장소를 만들지 않는다 —
+ * 첫 실행의 `record-progress` 산출이 그래프 런 원장(`graph-runs/weekly-lesson/<runId>.json`)에 남고,
+ * 다음 실행의 `read-progress` 가 그 원장을 그대로 읽어 다음 단원을 고른다.
+ */
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const SYLLABUS = ['unit-1', 'unit-2', 'unit-3', 'unit-4', 'unit-5'] as const;
+const WEEKLY_TIMEZONE = 'Asia/Seoul';
+const WEEKLY_CRON_WEEKDAY = 'Sun';
+const WEEKLY_CRON_HOUR = 20;
+
+type Lesson = (typeof SYLLABUS)[number] | string;
+
+interface StepOutput {
+  outcome?: string;
+  lesson?: string;
+  completed?: string[];
+  nextLesson?: string | null;
+  [key: string]: unknown;
+}
+
+interface GraphContext {
+  graphId?: string;
+  runId?: string;
+  nodeId?: string;
+  input?: unknown;
+  outputs?: Record<string, unknown>;
+}
+
+function emit(value: Record<string, unknown>): void {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+function asObject(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function parseStepOutput(value: unknown): StepOutput {
+  if (typeof value === 'string') {
+    const last = value.split('\n').map((line) => line.trim()).filter(Boolean).at(-1);
+    if (!last?.startsWith('{')) throw new Error('step output must end with a JSON object');
+    try { return JSON.parse(last) as StepOutput; }
+    catch (error) { throw new Error('step output ended with invalid JSON', { cause: error }); }
+  }
+  return asObject(value) as StepOutput;
+}
+
+function context(): { value: GraphContext; root: string } {
+  const path = process.env.ELANOUS_GRAPH_CONTEXT;
+  if (!path) throw new Error('ELANOUS_GRAPH_CONTEXT is required');
+  const stateRoot = process.env.ELANOUS_STATE_DIR;
+  if (!stateRoot) throw new Error('ELANOUS_STATE_DIR is required');
+  return { value: JSON.parse(readFileSync(path, 'utf8')) as GraphContext, root: resolve(stateRoot) };
+}
+
+/** 일요일 20:00 Asia/Seoul 인가 — 스케줄러가 주입한 tick 시각을 그 자리에서 검증한다. */
+function isWeeklySlot(scheduledAt: unknown): boolean {
+  if (typeof scheduledAt !== 'string' || !Number.isFinite(Date.parse(scheduledAt))) return false;
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone: WEEKLY_TIMEZONE, weekday: 'short', hour: '2-digit', minute: '2-digit', hour12: false,
+  }).formatToParts(new Date(scheduledAt));
+  const get = (type: string): string => parts.find((part) => part.type === type)?.value ?? '';
+  return get('weekday') === WEEKLY_CRON_WEEKDAY && Number(get('hour')) === WEEKLY_CRON_HOUR && Number(get('minute')) === 0;
+}
+
+/** 저장된 진도 = 앞선 런 원장의 성공한 `record-progress` 산출(lesson·completed). */
+function completedLessons(root: string): { completed: Lesson[]; runs: number } {
+  const dir = join(root, 'graph-runs', 'weekly-lesson');
+  let files: string[];
+  try { files = readdirSync(dir).filter((file) => file.endsWith('.json') && !file.endsWith('.decision.json')); }
+  catch { return { completed: [], runs: 0 }; }
+  const completed: Lesson[] = [];
+  let runs = 0;
+  for (const file of files) {
+    let state: { nodes?: Array<{ nodeId?: string; ok?: boolean; output?: unknown }> };
+    try { state = JSON.parse(readFileSync(join(dir, file), 'utf8')) as typeof state; }
+    catch { continue; }
+    runs += 1;
+    for (const node of state.nodes ?? []) {
+      if (node.nodeId !== 'record-progress' || node.ok !== true) continue;
+      const recorded = parseStepOutput(node.output);
+      for (const lesson of recorded.completed ?? []) if (typeof lesson === 'string' && !completed.includes(lesson)) completed.push(lesson);
+      if (typeof recorded.lesson === 'string' && !completed.includes(recorded.lesson)) completed.push(recorded.lesson);
+    }
+  }
+  return { completed, runs };
+}
+
+function nextLesson(completed: readonly string[]): Lesson | undefined {
+  return SYLLABUS.find((lesson) => !completed.includes(lesson));
+}
+
+function readProgress(): void {
+  const { value, root } = context();
+  const input = asObject(value.input);
+  if (!isWeeklySlot(input.scheduledAt)) {
+    emit({ outcome: 'fail', error: 'off-schedule: weekly ticks run Sunday 20:00 Asia/Seoul', scheduledAt: input.scheduledAt ?? null });
+    return;
+  }
+  const { completed, runs } = completedLessons(root);
+  emit({ outcome: 'ok', scheduledAt: input.scheduledAt, completed, nextLesson: nextLesson(completed) ?? null,
+    ledgerRuns: runs, source: runs === 0 ? 'empty-ledger' : 'run-ledger' });
+}
+
+function selectNext(): void {
+  const { value } = context();
+  const prior = parseStepOutput(value.outputs?.['read-progress']);
+  const completed = (prior.completed ?? []).filter((lesson): lesson is string => typeof lesson === 'string');
+  const lesson = typeof prior.nextLesson === 'string' ? prior.nextLesson : nextLesson(completed);
+  if (!lesson) {
+    emit({ outcome: 'fail', error: 'syllabus-complete', completed });
+    return;
+  }
+  emit({ outcome: completed.length === 0 ? 'baseline' : 'next', lesson, completed, scheduledAt: prior.scheduledAt ?? null,
+    requestedBy: { graphId: value.graphId ?? null, runId: value.runId ?? null } });
+}
+
+function packLesson(): void {
+  const { value, root } = context();
+  const selected = parseStepOutput(asObject(value.input)['select-next']);
+  if (typeof selected.lesson !== 'string') {
+    emit({ outcome: 'fail', error: 'lesson-pack requires a selected lesson' });
+    return;
+  }
+  if (!(SYLLABUS as readonly string[]).includes(selected.lesson)) {
+    emit({ outcome: 'fail', error: `lesson-pack received an unknown lesson: ${selected.lesson}` });
+    return;
+  }
+  const dir = join(root, 'lesson-pack', 'inbox');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${selected.lesson}.json`), `${JSON.stringify({
+    lesson: selected.lesson, scheduledAt: selected.scheduledAt ?? null,
+    requestedBy: asObject(selected.requestedBy), packedBy: { graphId: value.graphId ?? null, runId: value.runId ?? null },
+  }, null, 2)}\n`);
+  emit({ outcome: 'ok', lesson: selected.lesson, completed: selected.completed ?? [] });
+}
+
+function recordProgress(): void {
+  const { value } = context();
+  const selected = parseStepOutput(value.outputs?.['select-next']);
+  const packed = parseStepOutput(value.outputs?.['lesson-pack']);
+  const lesson = typeof packed.lesson === 'string' ? packed.lesson : typeof selected.lesson === 'string' ? selected.lesson : undefined;
+  if (!lesson) {
+    emit({ outcome: 'fail', error: 'record-progress requires the delivered lesson' });
+    return;
+  }
+  const completed = (selected.completed ?? []).filter((item): item is string => typeof item === 'string');
+  if (!completed.includes(lesson)) completed.push(lesson);
+  emit({ outcome: 'ok', lesson, completed, recordedAt: asObject(value.input).scheduledAt ?? null });
+}
+
+const commands: Record<string, () => void> = {
+  'read-progress': readProgress,
+  'select-next': selectNext,
+  pack: packLesson,
+  'record-progress': recordProgress,
+};
+
+if (import.meta.main) {
+  const command = process.argv[2] ?? '';
+  const run = commands[command];
+  if (!run) {
+    console.error(`unknown weekly-lesson command: ${command} (expected ${Object.keys(commands).join('|')})`);
+    process.exit(2);
+  }
+  run();
+}