elanous 0.2.12 → 0.2.14

package/src/cli/decisions-cli.ts

@@ -1,6 +1,15 @@
-import type { Command } from 'commander';
+import { Option, type Command } from 'commander';
+import { hqCliWriteAllowed, type HqDeps } from '../hq/hq.js';
+import { fileLeaseStore } from '../hq/lease.js';
+import { isIsolatedLedgerWriteRoot } from '../hq/ledger-write-target.js';
+import { debug } from '../debug/log.js';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { join } from 'node:path';
+import { getElanousConfigDirOverride } from '../elanous-config-dir.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { getUserConfig } from '../user-config.js';
 import { projectDecisionsToLinear } from '../decisions/decision-linear-projection.js';
-import { DecisionLedger, importDecisionMarkdown, type DecisionCategory, type DecisionLedgerOptions, type DecisionOption, type DecisionTrack, type DecisionEntry } from '../decisions/decision-ledger.js';
+import { DecisionLedger, importDecisionMarkdown, type DecisionCategory, type DecisionLedgerOptions, type DecisionOption, type DecisionTrack, type DecisionEntry, type Seat, type SeatDecisionRecord } from '../decisions/decision-ledger.js';
 
 const repeat = (value: string, values: string[]) => [...values, value];
 function date(raw?: string): string | undefined {
@@ -46,13 +55,30 @@ export function formatDecisionDetail(e: DecisionEntry): string {
     ...(e.refs?.length ? [`참조: ${e.refs.join(' · ')}`] : [])].join('\n');
 }
 
-export function registerDecisionsCommands(program: Command, config: DecisionLedgerOptions = {}, out: Pick<Console, 'log'> = console): void {
-  const root = program.command('decisions').description('대표 결정 원장 · 로컬 전용');
+export function formatSeatDecisionRow(e: SeatDecisionRecord): string {
+  return `${e.id} · 결정: ${e.decidedAt ? kst(e.decidedAt) : '시각 미상'} · 기록: ${e.recordedAt ? kst(e.recordedAt) : '시각 미상'} · ${e.seat} 결정 · 사후 보고 · ${e.title} → ${e.decision} · 위임: ${e.delegation}${e.refs?.length ? ` · 참조: ${e.refs.join(' · ')}` : ''}`;
+}
+
+export function registerDecisionsCommands(program: Command, config: DecisionLedgerOptions = {}, out: Pick<Console, 'log'> = console, hqDeps: HqDeps = {}): void {
+  const noXcheck = new Option('--no-xcheck <이유>', '교차 확인 생략 이유');
+  // This flag takes a reason, not Commander's negated boolean default.
+  noXcheck.negate = false;
+  const root = program.command('decisions').description('대표 결정 원장 · 로컬 전용').option('--hq-override', '본부 임대 거부를 관측하며 수동 우회');
+  const mayWrite = (command: string, override?: boolean) => {
+    const ledgerRoot = config.stateDir ?? elanousStateRoot();
+    if (command !== 'linear-sync' && isIsolatedLedgerWriteRoot(ledgerRoot)) {
+      try { debug.log('hq.fence', 'skipped-isolated', { root: ledgerRoot, command: `decisions ${command}` }); } catch { /* observation is fail-soft */ }
+      return true;
+    }
+    return hqCliWriteAllowed(`decisions ${command}`, Boolean(override || root.opts().hqOverride),
+      (getElanousConfigDirOverride() || config.stateDir) && !hqDeps.store && !getUserConfig().hq?.arbiter ? { ...hqDeps, store: fileLeaseStore(join(config.stateDir ?? effectiveInstanceRoot(), 'hq', 'lease.json')), seenPath: join(config.stateDir ?? effectiveInstanceRoot(), 'hq', 'seen-generation'), localPath: join(config.stateDir ?? effectiveInstanceRoot(), 'hq', 'local.json') } : hqDeps);
+  };
   const emit = (value: unknown, json?: boolean, text?: string) => out.log(json ? JSON.stringify(value) : text ?? JSON.stringify(value));
   const fail = (action: () => void) => { try { action(); } catch (e) { throw new Error(`decisions: ${e instanceof Error ? e.message : String(e)}`); } };
   root.command('linear-sync').description('열린 결정을 COO Linear 프로젝트에 투영하고 닫힌 결정을 동기화한다')
-    .option('--dry-run').option('--json')
-    .action(async (o: { dryRun?: boolean; json?: boolean }) => {
+    .option('--dry-run').option('--json').option('--hq-override')
+    .action(async (o: { dryRun?: boolean; json?: boolean; hqOverride?: boolean }) => {
+      if (!o.dryRun && !mayWrite('linear-sync', o.hqOverride)) return;
       const result = await projectDecisionsToLinear({ stateDir: config.stateDir, dryRun: o.dryRun });
       emit(result, o.json, result.reason ?? `생성 ${result.created} · 닫음 ${result.closed} · 건너뜀 ${result.skipped} · 실패 ${result.failed}${result.plan?.length ? `\n${result.plan.map(p => `${p.action} ${p.decisionId}${p.issue ? ` ${p.issue}` : ''}`).join('\n')}` : ''}`);
     });
@@ -61,23 +87,56 @@ export function registerDecisionsCommands(program: Command, config: DecisionLedg
     .requiredOption('--s <text>').requiredOption('--c <text>').option('--q <text>').option('--a <text>')
     .requiredOption('--option <key=label:consequence>', '선택지 (두 번 이상)', repeat, [] as string[])
     .option('--recommend <key>').option('--why <text>').option('--skip-recommend <reason>')
+    .option('--xcheck <SEAT:메모>', '교차 확인 (반복)', repeat, [] as string[])
+    .addOption(noXcheck)
+    .option('--alternative <key>').option('--dissent <text>')
     .option('--track <track>').option('--agent <agent>').option('--session <id>')
     .option('--resume-question <qid>').option('--run <runId>')
     .option('--ref <url>', '참조 (반복)', repeat, [] as string[])
     .option('--due <when>', '기한 — UTC ISO(2026-10-04T09:00:00Z) 또는 +Nh(지금부터 N시간) · 기한 2시간 전 텔레그램·디스코드로 다시 알린다')
-    .option('--json')
-    .action((o: { due?: string; title: string; category: DecisionCategory; s: string; c: string; q?: string; a?: string; option: string[]; recommend?: string; why?: string; skipRecommend?: string; track?: DecisionTrack; agent?: string; session?: string; resumeQuestion?: string; run?: string; ref: string[]; json?: boolean }) => fail(() => {
+    .option('--json').option('--hq-override')
+    .action((o: { due?: string; title: string; category: DecisionCategory; s: string; c: string; q?: string; a?: string; option: string[]; recommend?: string; why?: string; skipRecommend?: string; xcheck: string[]; noXcheck?: string; alternative?: string; dissent?: string; track?: DecisionTrack; agent?: string; session?: string; resumeQuestion?: string; run?: string; ref: string[]; json?: boolean; hqOverride?: boolean }) => fail(() => {
       if (o.run !== undefined && o.resumeQuestion === undefined) throw new Error('--run requires --resume-question');
       if (o.skipRecommend !== undefined && (o.recommend !== undefined || o.why !== undefined)) throw new Error('choose recommendation or skip, not both');
       if (o.skipRecommend === undefined && (!o.recommend || !o.why)) throw new Error('--recommend and --why required, or --skip-recommend <reason>');
       const options: DecisionOption[] = o.option.map(parseOption);
+      if (o.xcheck.length && o.noXcheck !== undefined) throw new Error('choose --xcheck or --no-xcheck, not both');
+      const crossCheck = o.xcheck.map(raw => {
+        const match = /^([^:\s]+):(.+)$/.exec(raw);
+        if (!match || !match[2]!.trim()) throw new Error(`invalid --xcheck: ${raw} (expected SEAT:메모)`);
+        return { seat: match[1]!, at: new Date().toISOString(), note: match[2]!.trim() };
+      });
+      if (!crossCheck.length && o.noXcheck === undefined && getUserConfig().decisions?.requireCrossCheck) throw new Error('교차 확인 없음 — --xcheck SEAT:메모 또는 --no-xcheck 이유');
+      const who = agent(o.agent);
+      if (!mayWrite('raise', o.hqOverride)) return;
       const entry = new DecisionLedger(config).raise({ title: o.title, category: o.category, scqa: { s: o.s, c: o.c, ...(o.q ? { q: o.q } : {}), ...(o.a ? { a: o.a } : {}) }, options,
+        ...(crossCheck.length ? { crossCheck } : { crossCheckSkipped: o.noXcheck ?? 'missing' }),
+        ...(o.alternative !== undefined ? { alternative: o.alternative } : {}), ...(o.dissent !== undefined ? { dissent: o.dissent } : {}),
         recommendation: o.skipRecommend !== undefined ? { skipped: true, reason: o.skipRecommend } : { option: o.recommend!, why: o.why! },
-        raisedBy: { agent: agent(o.agent), ...(o.track ? { track: o.track } : {}), ...(o.session ? { session: o.session } : {}) }, ...(o.ref.length ? { refs: o.ref } : {}),
+        raisedBy: { agent: who, ...(o.track ? { track: o.track } : {}), ...(o.session ? { session: o.session } : {}) }, ...(o.ref.length ? { refs: o.ref } : {}),
         ...(o.resumeQuestion !== undefined ? { resume: { questionId: o.resumeQuestion, ...(o.run !== undefined ? { runId: o.run } : {}) } } : {}),
         ...(o.due ? { dueAt: dueAt(o.due) } : {}) });
+      if (entry.crossCheckSkipped === 'missing') console.error('교차 확인 없음 — --xcheck SEAT:메모 또는 --no-xcheck 이유');
       emit(entry, o.json, `올림: ${formatDecisionRow(entry)}`);
     }));
+  root.command('record-seat').description('위임 범위에서 이미 내린 자리 결정을 사후 보고로 원장에 기록 (대표 카드 아님)')
+    .requiredOption('--seat <OP|MK|TC|UX>').requiredOption('--title <text>')
+    .requiredOption('--decision <text>').requiredOption('--delegation <scope>')
+    .option('--at <UTC>', '알고 있는 결정 시각 (UTC ISO; 생략 시 결정 시각 미상)')
+    .option('--ref <source>', '조율 글 등의 출처 (반복)', repeat, [] as string[])
+    .option('--json').option('--hq-override')
+    .action((o: { seat: Seat; title: string; decision: string; delegation: string; at?: string; ref: string[]; json?: boolean; hqOverride?: boolean }) => fail(() => {
+      if (!mayWrite('record-seat', o.hqOverride)) return;
+      const entry = new DecisionLedger(config).recordSeatDecision({ seat: o.seat, title: o.title, decision: o.decision,
+        delegation: o.delegation, ...(o.at ? { decidedAt: o.at } : {}), ...(o.ref.length ? { refs: o.ref } : {}) });
+      emit(entry, o.json, formatSeatDecisionRow(entry));
+    }));
+  root.command('seat-report').description('밤사이 자리들의 사후 결정을 한 번에 조회 (기본 최근 24시간)')
+    .option('--since <date>', '조회 시작 UTC ISO 또는 Nd', '1d').option('--seat <OP|MK|TC|UX>').option('--json')
+    .action((o: { since: string; seat?: Seat; json?: boolean }) => fail(() => {
+      const rows = new DecisionLedger(config).seatReport({ since: date(o.since), seat: o.seat });
+      emit(rows, o.json, rows.length ? rows.map(formatSeatDecisionRow).join('\n') : '자리 결정 0건');
+    }));
   root.command('list').description('결정 목록 (기본 열린 것)')
     .option('--status <open|decided|all>', '기본 open', 'open').option('--since <date>').option('--version <version>')
     .option('--decided-by <human|auto>').option('--category <category>').option('--json')
@@ -88,11 +147,12 @@ export function registerDecisionsCommands(program: Command, config: DecisionLedg
   root.command('show <id>').description('SCQA · 선택지 · 권고 · 이력 · 판').option('--json')
     .action((id: string, o: { json?: boolean }) => fail(() => { const entry = new DecisionLedger(config).show(id); emit(entry, o.json, formatDecisionDetail(entry)); }));
   root.command('decide <id> <option>').description('사람 또는 AUTO 위임 결정 기록')
-    .option('--note <text>').option('--auto').option('--delegation <reason>').option('--track <track>').option('--agent <agent>').option('--json')
-    .action((id: string, choice: string, o: { note?: string; auto?: boolean; delegation?: string; track?: DecisionTrack; agent?: string; json?: boolean }) => fail(() => {
+    .option('--note <text>').option('--auto').option('--delegation <reason>').option('--track <track>').option('--agent <agent>').option('--json').option('--hq-override')
+    .action((id: string, choice: string, o: { note?: string; auto?: boolean; delegation?: string; track?: DecisionTrack; agent?: string; json?: boolean; hqOverride?: boolean }) => fail(() => {
       if (o.auto && !o.delegation?.trim()) throw new Error('--auto requires --delegation');
       if (!o.auto && (o.delegation || o.track || o.agent)) throw new Error('delegation/track/agent require --auto');
       const by = o.auto ? { kind: 'auto' as const, agent: agent(o.agent), delegation: o.delegation!, ...(o.track ? { track: o.track } : {}) } : { kind: 'human' as const };
+      if (!mayWrite('decide', o.hqOverride)) return;
       const { entry, delivery } = new DecisionLedger(config).decideWithDelivery(id, choice, by, o.note);
       if (delivery && !delivery.ok) {
         // The decision is recorded; only the answer to the waiting run failed — say so and how to retry, never «success».
@@ -103,22 +163,26 @@ export function registerDecisionsCommands(program: Command, config: DecisionLedg
       }
       emit(delivery ? { ...entry, delivery } : entry, o.json, `결정: ${formatDecisionDetail(entry)}`);
     }));
-  root.command('retry-answer <id>').description('기록된 결정의 대기 질문 답 전달만 재시도한다').option('--json')
-    .action((id: string, o: { json?: boolean }) => fail(() => {
+  root.command('retry-answer <id>').description('기록된 결정의 대기 질문 답 전달만 재시도한다').option('--json').option('--hq-override')
+    .action((id: string, o: { json?: boolean; hqOverride?: boolean }) => fail(() => {
+      if (!mayWrite('retry-answer', o.hqOverride)) return;
       const entry = new DecisionLedger(config).retryAnswer(id);
       emit(entry, o.json, `답 전달: ${entry.id} → ${entry.resume?.questionId}`);
     }));
   root.command('add-options <id>').description('선택지가 미기재된 과거 항목에 확인된 선택지를 추가')
     .requiredOption('--option <key=label:consequence>', '선택지 (두 번 이상)', repeat, [] as string[])
-    .option('--agent <agent>').option('--json')
-    .action((id: string, o: { option: string[]; agent?: string; json?: boolean }) => fail(() => {
-      const entry = new DecisionLedger(config).addOptions(id, o.option.map(parseOption), agent(o.agent));
+    .option('--agent <agent>').option('--json').option('--hq-override')
+    .action((id: string, o: { option: string[]; agent?: string; json?: boolean; hqOverride?: boolean }) => fail(() => {
+      const who = agent(o.agent);
+      if (!mayWrite('add-options', o.hqOverride)) return;
+      const entry = new DecisionLedger(config).addOptions(id, o.option.map(parseOption), who);
       emit(entry, o.json, formatDecisionDetail(entry));
     }));
-  root.command('withdraw <id>').description('결정 철회도 원장에 남긴다').requiredOption('--reason <reason>').option('--json')
-    .action((id: string, o: { reason: string; json?: boolean }) => fail(() => { const entry = new DecisionLedger(config).withdraw(id, o.reason); emit(entry, o.json, `철회: ${formatDecisionDetail(entry)}`); }));
-  root.command('import-markdown <file>').description('기존 대표 결정 문서 씨앗을 가져온다 (재실행 안전)').option('--json')
-    .action((file: string, o: { json?: boolean }) => fail(() => {
+  root.command('withdraw <id>').description('결정 철회도 원장에 남긴다').requiredOption('--reason <reason>').option('--json').option('--hq-override')
+    .action((id: string, o: { reason: string; json?: boolean; hqOverride?: boolean }) => fail(() => { if (!mayWrite('withdraw', o.hqOverride)) return; const entry = new DecisionLedger(config).withdraw(id, o.reason); emit(entry, o.json, `철회: ${formatDecisionDetail(entry)}`); }));
+  root.command('import-markdown <file>').description('기존 대표 결정 문서 씨앗을 가져온다 (재실행 안전)').option('--json').option('--hq-override')
+    .action((file: string, o: { json?: boolean; hqOverride?: boolean }) => fail(() => {
+      if (!mayWrite('import-markdown', o.hqOverride)) return;
       const result = importDecisionMarkdown(new DecisionLedger(config), file);
       emit(result, o.json, `가져옴 ${result.imported.length} · 기존 ${result.existing.length} · 불완전 ${result.incomplete.length} · 못 읽음 ${result.unread.length}${result.incomplete.length ? `\n${result.incomplete.join('\n')}` : ''}${result.unread.length ? `\n${result.unread.join('\n')}` : ''}`);
       if (result.unread.length) process.exitCode = 1;

package/src/cli/docs-cli.ts

@@ -6,6 +6,7 @@
 // 양쪽에서 잡는다. 임베딩 다운 시 키워드 단독으로 강등(fail-soft).
 
 import type { Command } from 'commander';
+import { registerRfcStatusCommand } from './rfc-status.js';
 import { existsSync, readFileSync } from 'node:fs';
 import { relative, resolve } from 'node:path';
 import { knowledgeDbPath, openKnowledgeDb, hybridQueryKnowledge } from '../domains/knowledge.js';
@@ -280,6 +281,7 @@ export async function runDocsStale(
 export function registerDocsCommands(program: Command): void {
   const docsCmd = program.command('docs')
     .description('문서 지식 검색/관리 — knowledge.db 벡터+BM25 하이브리드 (DocOps)');
+  registerRfcStatusCommand(docsCmd);
   docsCmd.command('search <query>')
     .description('하이브리드 검색(RRF) — 의미(임베딩)+키워드(FTS5) 융합. 임베딩 다운 시 키워드 단독')
     .option('--limit <n>', '최대 결과 (기본 8·최대 20)')

package/src/cli/flow-cli.ts

@@ -0,0 +1,11 @@
+import type { Command } from 'commander';
+import { flowCard, flowTick } from '../flow/cards.js';
+
+export function registerFlowCommands(program: Command): void {
+  const flow = program.command('flow').description('Wish 카드 → 칸 → 릴리스 판');
+  flow.command('tick').description('새 Wish 카드 한 장 처리 (크론용)')
+    .action(async () => { const result = await flowTick(); console.log(result ? result.text : '새 카드 없음'); });
+  flow.command('plan <cardId>').description('카드 분할·배치 미리보기 (쓰기 없음)')
+    .requiredOption('--dry-run', '판·결정·카드 원장에 쓰지 않는다')
+    .action(async (cardId: string) => { console.log(JSON.stringify(await flowCard(cardId, {}, true))); });
+}

package/src/cli/freeze-cli.ts

@@ -0,0 +1,45 @@
+import type { Command } from 'commander';
+import { debug } from '../debug/log.js';
+import { CliUserError } from './cli-user-error.js';
+import { awaitLandingMergesDrained, disableLandingFreeze, enableLandingFreeze, readLandingFreeze, landingFreezeMessage } from '../release-loop/landing-freeze.js';
+import { pendingFrozenMerges, sweepFrozenMerges } from '../self-implement/frozen-merges.js';
+
+export function registerFreezeCommands(program: Command): void {
+  const freeze = program.command('freeze').description('착지 동결 상태 on/off/status');
+  freeze.command('on').option('--reason <text>', '동결 이유').option('--until <timestamp>', '끝 시각(타임존 포함 ISO)')
+    .option('--wait-seconds <n>', '이미 동결 검사를 지난 병합이 끝나기를 기다릴 최대 초', '600')
+    .action(async (opts: { reason?: string; until?: string; waitSeconds: string }) => {
+      const waitSeconds = Number(opts.waitSeconds);
+      if (!/^\d+$/.test(opts.waitSeconds.trim()) || !Number.isSafeInteger(waitSeconds) || waitSeconds > 86_400) {
+        throw new CliUserError(`잘못된 --wait-seconds: ${opts.waitSeconds}`, '0 이상 86400 이하의 정수 초');
+      }
+      const state = enableLandingFreeze(opts);
+      debug.log('harness.merge', 'freeze-on', state);
+      const drained = await awaitLandingMergesDrained(undefined, { timeoutMs: waitSeconds * 1000 });
+      debug.log('harness.merge', 'freeze-drain', drained);
+      console.log(landingFreezeMessage(state));
+      if (!drained.drained) {
+        console.error(`⚠ 동결 전에 시작한 병합 ${drained.pending}건이 아직 진행 중 — 끝나면 더 이상 병합이 시작되지 않는다`);
+        process.exitCode = 2;
+      }
+    });
+  freeze.command('off').description('동결을 풀고 보류된 병합을 바로 이어 한다').action(async () => {
+    disableLandingFreeze();
+    debug.log('harness.merge', 'freeze-off', {});
+    console.log('동결 해제');
+    await resume();
+  });
+  freeze.command('resume').description('동결이 풀렸으면 보류된 병합을 지금 이어 한다').action(async () => { await resume(); });
+  freeze.command('status').option('--json', '상태 JSON').action((opts: { json?: boolean }) => {
+    const state = readLandingFreeze();
+    const pending = pendingFrozenMerges();
+    if (opts.json) console.log(JSON.stringify({ frozen: state !== null, freeze: state, pendingMerges: pending }));
+    else console.log(`${state ? landingFreezeMessage(state) : '동결 없음'} · 보류 병합 ${pending}건`);
+  });
+}
+
+async function resume(): Promise<void> {
+  const result = await sweepFrozenMerges();
+  debug.log('harness.merge', 'freeze-resume', result);
+  console.log(`보류 병합 이어 하기: 병합 ${result.merged}건 · 남음 ${result.pending}건`);
+}

package/src/cli/lesson-cli.ts

@@ -0,0 +1,108 @@
+import type { Command } from 'commander';
+import { resolve } from 'node:path';
+import { debug } from '../debug/log.js';
+import { importLessons, scanLessonDocs } from '../lessons/lesson-import.js';
+import { LessonInputError, LessonLedger, type LessonLedgerOptions, type LessonRow, type LessonDetail } from '../lessons/lesson-ledger.js';
+
+function actor(explicit?: string): string {
+  const by = explicit?.trim() || process.env.AI_AGENT?.trim();
+  if (!by) throw new LessonInputError('--by or AI_AGENT is required');
+  return by;
+}
+
+function reportError(command: string, message: string): void {
+  const escaped = message.replace(/\r/g, '\\r').replace(/\n/g, '\\n')
+    .replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+  process.stderr.write(`lesson ${command}: ${escaped}\n`);
+  process.exitCode = 1;
+}
+
+function handle<Args extends unknown[]>(command: string, action: (...args: Args) => void): (...args: Args) => void {
+  return (...args) => {
+    try { action(...args); }
+    catch (error) {
+      if (!(error instanceof LessonInputError)) throw error;
+      reportError(command, error.message);
+    }
+  };
+}
+
+function format(row: LessonRow): string {
+  return `${row.id} · ${row.status} · ${row.occurrence_count}회 · ${row.incident} · ${row.owner}`;
+}
+
+function detail(row: LessonDetail): string {
+  return [format(row), `원인: ${row.cause}`, `처방: ${row.remedy}`, `강제: ${row.enforced_by || '없음'}`,
+    ...(row.disproof ? [`반증: ${row.disproof}`] : []),
+    '발생:', ...row.occurrences.map(o => `  ${o.at} · ${o.source}${o.note ? ` · ${o.note}` : ''}`),
+    '이력:', ...row.history.map(h => `  ${h.at} · ${h.event} · ${h.by} · ${h.detail}`)].join('\n');
+}
+
+export function registerLessonCommands(program: Command, options: LessonLedgerOptions = {}, out: Pick<Console, 'log'> = console): void {
+  const root = program.command('lesson').description('사고 · 원인 · 처방 · 재발 교훈 원장');
+  const ledger = () => new LessonLedger(options);
+  const emit = (value: unknown, json: boolean | undefined, text: string) => out.log(json ? JSON.stringify(value) : text);
+  root.command('import').description('INCIDENT·FINDING 문서 교훈 미리 보기 (기본값); --apply 로 적재')
+    .option('--apply', '원장에 적재').option('--json', 'JSON 출력').option('--by <name>', '기록자 (기본 AI_AGENT)')
+    .action(handle('import', (o: { apply?: boolean; json?: boolean; by?: string }) => {
+      const by = actor(o.by);
+      const scan = scanLessonDocs(resolve(process.cwd()));
+      const imported = importLessons(ledger(), scan.items, { apply: !!o.apply, by });
+      const result = { files: scan.files, items: imported.items, skipped: [...scan.skipped, ...imported.skipped],
+        emptyCause: imported.items.filter(item => !item.cause).length,
+        emptyRemedy: imported.items.filter(item => !item.remedy).length, written: imported.written };
+      if (o.apply) debug.log('lessons.import', 'applied', { files: result.files, items: result.items.length,
+        skipped: result.skipped.length, written: result.written });
+      emit(result, o.json, `파일 ${result.files} · 넣을 교훈 ${result.items.length} · 건너뜀 ${result.skipped.length} · 빈 원인 ${result.emptyCause} · 빈 처방 ${result.emptyRemedy} · 기록 ${result.written}`);
+    }));
+  root.command('page').description('교훈 원장에서 핸드북 페이지 생성')
+    .option('--out <file>', '출력 파일').option('--json', 'JSON 출력')
+    .action(async (o: { out?: string; json?: boolean }) => {
+      try {
+        const { generateHandbookPage } = await import('../../scripts/lessons/handbook-page.js');
+        const result = generateHandbookPage({ stateDir: options.stateDir, out: o.out });
+        emit(result, o.json, 'skipped' in result
+          ? '교훈 페이지: 건너뜀(원장 비어 있음)'
+          : `교훈 페이지: ${result.out} · 총 ${result.total} · 강제 자리 없음 ${result.unenforced}`);
+      } catch (error) {
+        reportError('page', error instanceof Error ? error.message : String(error));
+      }
+    });
+  root.command('add <id>').requiredOption('--incident <text>').requiredOption('--cause <text>')
+    .requiredOption('--remedy <text>').requiredOption('--owner <name>').requiredOption('--source <path>')
+    .option('--enforced-by <paths>').option('--disproof <command>').option('--by <name>')
+    .action(handle('add', (id: string, o: { incident: string; cause: string; remedy: string; owner: string; source: string; enforcedBy?: string; disproof?: string; by?: string }) => {
+      const by = actor(o.by);
+      const row = ledger().add({ id, incident: o.incident, cause: o.cause, remedy: o.remedy, owner: o.owner,
+        source: o.source, by, ...(o.enforcedBy !== undefined ? { enforcedBy: o.enforcedBy } : {}),
+        ...(o.disproof !== undefined ? { disproof: o.disproof } : {}) });
+      emit(row, false, format(row));
+    }));
+  root.command('recur <id>').requiredOption('--source <path>').option('--note <text>').option('--by <name>')
+    .action(handle('recur', (id: string, o: { source: string; note?: string; by?: string }) => {
+      const row = ledger().recur(id, { source: o.source, note: o.note ?? '', by: actor(o.by) });
+      emit(row, false, format(row));
+    }));
+  root.command('enforce <id>').requiredOption('--enforced-by <paths>').option('--by <name>')
+    .action(handle('enforce', (id: string, o: { enforcedBy: string; by?: string }) => {
+      const row = ledger().enforce(id, { enforcedBy: o.enforcedBy, by: actor(o.by) });
+      emit(row, false, format(row));
+    }));
+  root.command('promote <id>').requiredOption('--rule <path>').option('--by <name>')
+    .action(handle('promote', (id: string, o: { rule: string; by?: string }) => {
+      const row = ledger().promote(id, { rulePath: o.rule, by: actor(o.by) });
+      emit(row, false, format(row));
+    }));
+  root.command('find <query>').option('--json').action(handle('find', (query: string, o: { json?: boolean }) => {
+    const rows = ledger().find(query);
+    emit(rows, o.json, rows.length ? rows.map(format).join('\n') : '교훈 0건');
+  }));
+  root.command('show <id>').option('--json').action(handle('show', (id: string, o: { json?: boolean }) => {
+    const row = ledger().get(id);
+    emit(row, o.json, detail(row));
+  }));
+  root.command('candidates').option('--json').action(handle('candidates', (o: { json?: boolean }) => {
+    const rows = ledger().candidates();
+    emit(rows, o.json, rows.length ? rows.map(format).join('\n') : '승격 후보 0건');
+  }));
+}

package/src/cli/logs-cli.ts

@@ -14,7 +14,7 @@
 // 같은 케이던스). 레벨 제어만 데몬 REST(/v1/logs/level — 런타임 상태라 프로세스
 // 경유 필수). 설계: 내부 문서 `PLAN-unified-log-fabric-2026-07-13` §LF3.
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import type { Command } from 'commander';
 import { homedir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
@@ -37,7 +37,7 @@ import { isRenderCategory, RENDER_ORIENTED_PREFIXES } from '../mss/logging/rende
 import { readScopedRenderLogs } from '../mss/logging/scoped-level.js';
 import { formatClock } from '../time/format.js';
 import { HARNESS_SPACE_KINDS } from '../harness/harness-space.js';
-import { LogCursorNotFoundError, STORE_SAFETY_MAX } from '../mss/logging/log-store.js';
+import { LOG_RETENTION_DEFAULTS, LogCursorNotFoundError, STORE_SAFETY_MAX } from '../mss/logging/log-store.js';
 import { resolveDaemonEndpoint } from '../nexus/daemon-endpoint.js';
 import { getElanousConfigDir } from '../elanous-config-dir.js';
 import { debug } from '../debug/log.js';
@@ -705,6 +705,74 @@ export function categoryCandidateWarning(
   return `안내: 지정한 카테고리 이름은 이 로그 스토어에서 관측된 적 없습니다: ${shown}${rest > 0 ? ` 외 ${rest}개` : ''}.`;
 }
 
+/** A child-observation query can miss Pod-only logs even when the local store was read successfully. */
+export function podObservationGapNotice(
+  query: Pick<LogQuery, 'categories' | 'exactCategories' | 'events'>,
+  podRuns: number,
+): string | null {
+  if (podRuns <= 0) return null;
+  const childCategory = (category: string): boolean => ['self-implement', 'self-dev', 'harness']
+    .some((prefix) => category.startsWith(prefix));
+  const categories = [...(query.categories ?? []), ...(query.exactCategories ?? [])];
+  if (!categories.some(childCategory) && !(categories.length === 0 && (query.events?.length ?? 0) > 0)) return null;
+  return `안내: 이 창에 Pod 에서 돈 런 ${podRuns}개 — Pod 자식의 관측은 이 logs.db 에 수집되지 않는다(POD-OBS). 원장으로 본다: elanous self run-ledger <runId>`;
+}
+
+/** Select ledger roots independently of DB existence; --all includes registered roots with no logs.db. */
+function podLedgerDirectories(opts: LogsCliOpts, targets: readonly LogTarget[], instances: readonly LogInstanceView[]): string[] {
+  const roots = targets.map(({ dbPath }) => dirname(dirname(dbPath)));
+  if (opts.all && !opts.instance) {
+    roots.push(dirname(dirname(prodTarget().dbPath)));
+    for (const instance of instances) {
+      if (instance.kind !== 'test' || opts.includeTest) roots.push(instance.stateDir);
+    }
+  }
+  return [...new Set(roots.map((root) => join(root, 'run-ledger')))];
+}
+
+/** Read-only run-ledger scan over the independently selected instance roots. */
+async function countPodRunLedgers(
+  directories: readonly string[],
+  query: Pick<LogQuery, 'sinceMs' | 'untilMs'>,
+): Promise<{ podRuns: number; unreadableLedgers: number }> {
+  const { loadRunLedger } = await import('../self-implement/run-ledger.js');
+  const untilMs = query.untilMs ?? Date.now();
+  const sinceMs = query.sinceMs ?? untilMs - LOG_RETENTION_DEFAULTS.maxAgeDays * 86_400_000;
+  let podRuns = 0;
+  let unreadableLedgers = 0;
+  for (const directory of directories) {
+    let files: string[];
+    try { files = readdirSync(directory); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') unreadableLedgers += 1;
+      continue;
+    }
+    for (const file of files) {
+      if (!/^run-[a-zA-Z0-9-]+\.jsonl$/.test(file)) continue;
+      try {
+        const stamp = statSync(join(directory, file));
+        if (!stamp.isFile() || stamp.mtimeMs < sinceMs) continue;
+        const ledger = loadRunLedger(file.slice(0, -'.jsonl'.length), directory);
+        if (!ledger) { unreadableLedgers += 1; continue; }
+        const origin = ledger.find((entry) => entry.event === 'run-origin');
+        if (!origin || typeof origin.data.hostname !== 'string' || !origin.data.hostname.startsWith('si-task-')) continue;
+        let start = Number.POSITIVE_INFINITY;
+        let end = Number.NEGATIVE_INFINITY;
+        for (const entry of ledger) {
+          const time = entry.timestamp === undefined ? NaN : Date.parse(entry.timestamp);
+          if (!Number.isFinite(time)) continue;
+          start = Math.min(start, time);
+          end = Math.max(end, time);
+        }
+        // Older ledgers may have no timestamp at all; their mtime is the only available window evidence.
+        if (start === Number.POSITIVE_INFINITY) { start = stamp.mtimeMs; end = stamp.mtimeMs; }
+        if (start <= untilMs && end >= sinceMs) podRuns += 1;
+      } catch { unreadableLedgers += 1; }
+    }
+  }
+  return { podRuns, unreadableLedgers };
+}
+
 // ── 0건 --event 안내: 이미 찍힌 기록에서만 답한다 ────────────────────────
 //
 // 갈림 ① 어느 범위에서 모으나 — **고정 24시간 관측 창**.
@@ -1480,9 +1548,25 @@ export async function runLogsCli(opts: LogsCliOpts, deps: RunLogsCliDeps = {}):
     : {};
   const queryStatus = registryScope.queryStatus;
   const unopenedStoreBanner = unopenedStores === undefined ? '안 본 스토어 수 미측정' : `안 본 스토어 ${unopenedStores}개`;
+  const podGap = !opts.topFailures && podObservationGapNotice(query, 1) !== null
+    ? await countPodRunLedgers(podLedgerDirectories(opts, resolved.targets, registryScope.instances), query)
+    : null;
+  const podNotice = podGap ? podObservationGapNotice(query, podGap.podRuns) : null;
+  const podGapMeta = podGap && (podNotice || podGap.unreadableLedgers > 0)
+    ? { _meta: { type: 'log-query-pod-observation-gap', ...podGap } }
+    : null;
+  const emitPodGap = (): void => {
+    if (!opts.json && podGap) {
+      if (podNotice) console.error(`${podNotice}${podGap.unreadableLedgers > 0 ? ` (못 읽은 원장 ${podGap.unreadableLedgers})` : ''}`);
+      else if (podGap.unreadableLedgers > 0) console.error(`안내: Pod 원장 조회 중 못 읽은 원장 ${podGap.unreadableLedgers}개 — Pod 런 수를 확정할 수 없다(POD-OBS).`);
+    }
+    if (podGapMeta && podGap) debug.log('logs.query', 'pod-observation-gap', podGap);
+  };
   if (opened.length === 0) {
     console.error(`elanous logs: 열 수 있는 로그 스토어 없음 — ${missing.join(' · ') || '타겟 0'} · scope=${JSON.stringify(scope)} · queryStatus=${JSON.stringify(queryStatus)}`);
     console.error('  스토어는 해당 인스턴스 데몬(LF0 이후)이 한 번은 떠야 생성됩니다.');
+    if (opts.json && podGapMeta) console.log(JSON.stringify(podGapMeta));
+    emitPodGap();
     return 1;
   }
   if (missing.length > 0) console.error(`elanous logs: 스킵 — ${missing.join(' · ')}`);
@@ -1666,6 +1750,7 @@ export async function runLogsCli(opts: LogsCliOpts, deps: RunLogsCliDeps = {}):
     // JSONL 소비자는 stdout만 읽는다. 결손·중복 성격·상한 메타도 별도 행으로 내어 행별 JSON 파싱을 보존한다.
     if (opts.json && multiSurfaceDuplicateMeta) outputLines.unshift(JSON.stringify(multiSurfaceDuplicateMeta));
     if (opts.json && unreadableMeta) outputLines.unshift(JSON.stringify(unreadableMeta));
+    if (opts.json && podGapMeta) outputLines.unshift(JSON.stringify(podGapMeta));
     if (unreadableInstances.length > 0 && !opts.json) {
       outputLines.unshift(`⚠️ 못 읽은 인스턴스 ${unreadableInstances.length}개: ${unreadableInstances.join(', ')}`);
     }
@@ -1676,6 +1761,7 @@ export async function runLogsCli(opts: LogsCliOpts, deps: RunLogsCliDeps = {}):
       const output = `${outputLines.join('\n')}\n`;
       await new Promise<void>((resolve, reject) => process.stdout.write(output, (error) => error ? reject(error) : resolve()));
     }
+    emitPodGap();
     const eventWarning = eventCategoryWarning(opts.event);
     if (eventWarning) {
       console.error(eventWarning);
@@ -1744,6 +1830,8 @@ export async function runLogsCli(opts: LogsCliOpts, deps: RunLogsCliDeps = {}):
   }
   seed.sort((a, b) => a.row.ts_ms - b.row.ts_ms || a.row.id - b.row.id);
   for (const m of seed.slice(-20)) emit(m.row, m.name, m.path);
+  if (opts.json && podGapMeta) console.log(JSON.stringify(podGapMeta));
+  emitPodGap();
   const cursors = new Map<string, number>();
   for (const { name, store } of opened) {
     try { cursors.set(name, store.maxId()); } catch { cursors.set(name, 0); }
@@ -1993,6 +2081,20 @@ logsCmd.command('durations')
     process.exit(runLogsToolDurations(merged));
   });
 
+logsCmd.command('model-input')
+  .description('최근 노드 종류별 모델 입력 토큰 기준선 (중앙값·p90·못 잼 별도 집계, 기본 3일)')
+  .option('--since <t>', '조회 시작 (기본 3d · 30s|15m|2h|7d 또는 ISO)')
+  .option('--json', '구조화 JSON 출력')
+  .option('--test', 'cwd 레포의 격리 테스트 인스턴스(.elanous-test/)')
+  .option('--instance <name>', '레지스트리 등록 인스턴스')
+  .option('--all', '등록된 모든 로그 인스턴스 연합 조회')
+  .option('--include-test', '--all 연합에 격리 test 인스턴스 포함')
+  .action(async (o: import('./logs-model-input.js').LogsModelInputOpts, cmd: { optsWithGlobals(): Record<string, unknown> }) => {
+    const merged = { ...cmd.optsWithGlobals(), ...o } as import('./logs-model-input.js').LogsModelInputOpts;
+    const { runLogsModelInput } = await import('./logs-model-input.js');
+    process.exitCode = runLogsModelInput(merged);
+  });
+
 logsCmd.command('degenerate')
   .description('수치 로그 필드의 always-same/all-zero/표본 부족 퇴화를 NDJSON으로 판정 (기본 표본 50)')
   .option('--category <prefix>', '카테고리 접두 필터 (복수는 쉼표)')