elanous 0.2.6 → 0.2.7

package/src/cli/cli-user-error.ts

@@ -0,0 +1,25 @@
+import { HarnessCliInputError } from '../harness/harness-cli-command.js';
+
+const cliUserErrorBrand = Symbol.for('elanous.cli.CliUserError');
+const harnessCliInputErrorBrand = Symbol.for('elanous.cli.HarnessCliInputError');
+
+export class CliUserError extends Error {
+  constructor(message: string, public readonly hint?: string) {
+    super(message);
+    this.name = 'CliUserError';
+    Object.defineProperty(this, cliUserErrorBrand, { value: true });
+  }
+}
+
+export function isCliUserError(err: unknown): err is Error & { hint?: string } {
+  return err instanceof HarnessCliInputError || err instanceof CliUserError || (
+    err instanceof Error && (
+      (err.name === 'CliUserError' && Object.getOwnPropertyDescriptor(err, cliUserErrorBrand)?.value === true) ||
+      (err.name === 'HarnessCliInputError' && Object.getOwnPropertyDescriptor(err, harnessCliInputErrorBrand)?.value === true)
+    )
+  );
+}
+
+export function formatCliUserError(err: Error & { hint?: string }): string {
+  return `❌ ${err.message}${err.hint ? `\n  ↳ ${err.hint}` : ''}`;
+}

package/src/cli/codex-credit-plan-view.ts

@@ -0,0 +1,25 @@
+// Assembles the codex credit plan from disk for `provider codex status` and `usage` — policy file, the last
+// measured per-account balances and the balance history. No network.
+import { codexCreditPlan, readCreditHistory, type CodexCreditPlan } from '../budget/codex-credit-plan.js';
+import { quotaSignalDir } from '../budget/codex-reset-credit-state.js';
+import { inspectCodexRotation } from '../oauth/codex-account-store.js';
+import { loadLlmPolicy } from '../policy/llm-policy.js';
+
+export function codexCreditPlanFromDisk(now: number = Date.now()): CodexCreditPlan {
+  const s = inspectCodexRotation(process.env, { now });
+  const seen = new Set<string>();
+  const balances: Array<{ name: string; balance?: number }> = [];
+  const push = (key: string, name: string, balance: number | undefined) => {
+    if (seen.has(key)) return;
+    seen.add(key);
+    balances.push({ name, ...(balance === undefined ? {} : { balance }) });
+  };
+  push(s.current.storeKey, s.current.name, s.currentCreditBalance);
+  for (const c of s.candidates) push(c.storeKey, c.name, c.creditBalance);
+  return codexCreditPlan({
+    now,
+    balances,
+    credits: loadLlmPolicy({ now: new Date(now) }).policy.credits,
+    history: readCreditHistory(quotaSignalDir()),
+  });
+}

package/src/cli/dependence-gauge.ts

@@ -0,0 +1,237 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import type { Command } from 'commander';
+
+/** Attribution is evidence about the executor, not about the person who requested the work. */
+export type DependenceAttribution = 'claude-code' | 'elanous' | 'other' | 'unknown';
+export type DependenceAxis = 'positions' | 'executions' | 'changes' | 'decisions';
+export interface DependenceObservation {
+  at?: string;
+  runtime?: string;
+  agent?: string;
+  track?: string;
+  /** A direct attribution supplied by a source record; never inferred from the author. */
+  actor?: string;
+}
+export interface DependenceSource {
+  observations: readonly DependenceObservation[];
+  /** A missing source is different from an observed empty source. */
+  unmeasurable?: string;
+}
+export interface DependenceAxisResult {
+  status: 'measured' | 'unmeasurable';
+  total: number;
+  covered: number;
+  claudeCode: number;
+  elanous: number;
+  other: number;
+  unknown: number;
+  /** Records whose timestamp cannot place them inside or outside the requested window. Not in total. */
+  undated: number;
+  reason?: string;
+}
+export interface DependenceReport {
+  since: string;
+  until: string;
+  axes: Record<DependenceAxis, DependenceAxisResult>;
+}
+export interface DependenceGaugeDeps {
+  now?: () => Date;
+  readPositions?: () => DependenceSource;
+  readExecutions?: () => DependenceSource;
+  readChanges?: (window: { since: string; until: string }) => DependenceSource;
+  readDecisions?: () => DependenceSource;
+  out?: Pick<Console, 'log'>;
+}
+
+const axes = ['positions', 'executions', 'changes', 'decisions'] as const;
+const identity = (value: unknown): DependenceAttribution => {
+  if (typeof value !== 'string' || !value.trim()) return 'unknown';
+  const normalized = value.trim().toLowerCase();
+  if (normalized === 'claude-code' || normalized === 'claude code') return 'claude-code';
+  if (normalized === 'elanous') return 'elanous';
+  if (normalized === 'unknown') return 'unknown';
+  return 'other';
+};
+
+/** Explicit per-event runtime wins over an agent label, which wins over the seat default. */
+export function attributeDependence(row: DependenceObservation, positions: ReadonlyMap<string, DependenceAttribution>): DependenceAttribution {
+  if (row.actor?.trim()) return identity(row.actor);
+  if (row.runtime?.trim()) return identity(row.runtime);
+  if (row.agent?.trim()) return identity(row.agent);
+  return row.track ? (positions.get(row.track) ?? 'unknown') : 'unknown';
+}
+
+function instant(raw: string, label: string): Date {
+  // Date.parse silently normalizes impossible days (e.g. February 30), including timestamps.
+  const calendarDate = /^(\d{4}-\d{2}-\d{2})(?:T|$)/.exec(raw)?.[1];
+  if (calendarDate) {
+    const day = new Date(`${calendarDate}T00:00:00.000Z`);
+    if (!Number.isFinite(day.getTime()) || day.toISOString().slice(0, 10) !== calendarDate) {
+      throw new Error(`invalid ${label}: ${raw}`);
+    }
+  }
+  const date = new Date(calendarDate === raw ? `${raw}T00:00:00.000Z` : raw);
+  if (!Number.isFinite(date.getTime())) throw new Error(`invalid ${label}: ${raw}`);
+  return date;
+}
+
+function observationTime(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const match = /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.exec(raw);
+  if (!match) return undefined;
+  const day = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+  if (day.toISOString().slice(0, 10) !== raw.slice(0, 10)) return undefined;
+  const time = Date.parse(raw);
+  return Number.isFinite(time) ? time : undefined;
+}
+
+export function dependenceWindow(since: string | undefined, until: string | undefined, now: Date): { since: string; until: string } {
+  const end = until ? instant(until, '--until') : now;
+  if (!Number.isFinite(end.getTime())) throw new Error('invalid current date');
+  // Date-only --until includes that entire UTC day; relative lookback is anchored to its end.
+  const inclusiveEnd = until && /^\d{4}-\d{2}-\d{2}$/.test(until)
+    ? new Date(end.getTime() + 86_400_000 - 1) : end;
+  const match = /^(\d+)d$/.exec(since ?? '7d');
+  const start = match ? new Date(inclusiveEnd.getTime() - Number(match[1]) * 86_400_000)
+    : instant(since ?? '7d', '--since');
+  if (!Number.isFinite(start.getTime()) || start > inclusiveEnd) throw new Error('invalid --since: start must be at or before --until');
+  return { since: start.toISOString(), until: inclusiveEnd.toISOString() };
+}
+
+export function readSeatRegistry(): DependenceSource {
+  try {
+    const raw = JSON.parse(readFileSync(resolve(import.meta.dir, '../../scripts/coord-tracks.json'), 'utf8')) as { tracks?: unknown };
+    if (!Array.isArray(raw.tracks)) return { observations: [], unmeasurable: 'seat registry has no tracks' };
+    return { observations: raw.tracks.filter((track): track is { id: string; title: string; runtime?: string } =>
+      typeof track === 'object' && track !== null && typeof track.id === 'string' && typeof track.title === 'string')
+      .map(track => ({ track: track.id, runtime: track.runtime })) };
+  } catch (error) {
+    return { observations: [], unmeasurable: `seat registry unreadable: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
+function unknownSource(description: string): DependenceSource {
+  return { observations: [], unmeasurable: description };
+}
+
+function stringField(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function object(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+export function readRunExecutions(directory = join(elanousStateRoot(), 'run-ledger')): DependenceSource {
+  try {
+    if (!existsSync(directory)) return unknownSource('run-ledger directory absent');
+    const observations: DependenceObservation[] = [];
+    for (const name of readdirSync(directory).filter(name => name.endsWith('.jsonl')).sort()) {
+      const lines = readFileSync(join(directory, name), 'utf8').split('\n').filter(Boolean);
+      let launch: DependenceObservation | undefined;
+      for (const line of lines) {
+        const entry = object(JSON.parse(line));
+        if (entry.event === 'run-origin') {
+          const data = object(entry.data);
+          launch = { at: stringField(entry.timestamp), runtime: stringField(data.runtime),
+            agent: stringField(data.agent), track: stringField(data.track) };
+          break;
+        }
+        if (!launch) launch = { at: stringField(entry.timestamp) };
+      }
+      if (launch) observations.push(launch);
+    }
+    return { observations };
+  } catch (error) {
+    return unknownSource(`run-ledger unreadable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/** 이 저장소의 실제 표지 — `Co-Authored-By:` 트레일러(작성자·커미터는 전부 같은 사람이라 쓰지 않는다).
+ *  하니스 착지(`elanous pod child`) > codex > Claude 순 — 한 병합에 여러 표지면 실제로 코드를 쓴 쪽이 앞선다. */
+export function runtimeFromCoAuthors(body: string): string | undefined {
+  const names = [...body.matchAll(/^co-authored-by:[^\S\r\n]*([^<\r\n]*)/gim)].map(m => m[1]!.trim().toLowerCase());
+  if (names.some(n => n.includes('elanous'))) return 'elanous';
+  if (names.some(n => n.includes('codex'))) return 'codex';
+  if (names.some(n => n.includes('claude'))) return 'claude-code';
+  return undefined;
+}
+
+export function readChangeCommits(window: { since: string; until: string }, repo = resolve(import.meta.dir, '../..')): DependenceSource {
+  // Git object reads only: author and committer are deliberately NOT treated as the executor.
+  // 착지 = main 의 첫 부모 줄(스쿼시 병합 하나 = 착지 하나) — `--all` 은 가지의 중간 커밋까지 세어 부풀린다.
+  const result = spawnSync('git', ['log', 'origin/main', '--first-parent', '--format=%cI%x1f%B%x1e', `--since-as-filter=${window.since}`, `--until=${window.until}`], {
+    cwd: repo, encoding: 'utf8', timeout: 15_000, maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.status !== 0 || result.error) return unknownSource(`git history unreadable: ${result.error?.message ?? result.stderr ?? result.status}`);
+  if (result.stdout.length >= 16 * 1024 * 1024 - 1024) return unknownSource('git history exceeds gauge read limit');
+  const observations = result.stdout.split('\x1e').filter(record => record.includes('\x1f')).map(record => {
+    const [at, body] = record.trim().split('\x1f', 2);
+    const attribution = /(?:^|\n)(?:Executed-By|Agent-Runtime|Runtime):[^\S\r\n]*([^\r\n]*)/im.exec(body ?? '');
+    return { at, runtime: attribution?.[1]?.trim() ?? runtimeFromCoAuthors(body ?? '') };
+  });
+  return { observations };
+}
+
+/** No mutation of ledgers or state; absent attribution data is reported, never guessed from an author or requester. */
+export function measureDependence(deps: DependenceGaugeDeps = {}, options: { since?: string; until?: string } = {}): DependenceReport {
+  const window = dependenceWindow(options.since, options.until, (deps.now ?? (() => new Date()))());
+  const sources: Record<DependenceAxis, DependenceSource> = {
+    positions: (deps.readPositions ?? readSeatRegistry)(),
+    executions: (deps.readExecutions ?? readRunExecutions)(),
+    changes: (deps.readChanges ?? readChangeCommits)(window),
+    decisions: (deps.readDecisions ?? (() => unknownSource('decision actor cannot be measured from the available data')))(),
+  };
+  const positions = new Map<string, DependenceAttribution>();
+  for (const row of sources.positions.observations) {
+    if (row.track) positions.set(row.track, identity(row.runtime));
+  }
+  const result = {} as Record<DependenceAxis, DependenceAxisResult>;
+  for (const axis of axes) {
+    const source = sources[axis];
+    const counts: DependenceAxisResult = { status: source.unmeasurable ? 'unmeasurable' : 'measured', total: 0, covered: 0, claudeCode: 0, elanous: 0, other: 0, unknown: 0, undated: 0,
+      ...(source.unmeasurable ? { reason: source.unmeasurable } : {}) };
+    for (const row of source.observations) {
+      if (axis !== 'positions') {
+        const at = observationTime(row.at);
+        if (at === undefined) { counts.undated++; continue; }
+        if (at < Date.parse(window.since) || at > Date.parse(window.until)) continue;
+      }
+      counts.total++;
+      const attribution = attributeDependence(row, positions);
+      if (attribution === 'unknown') counts.unknown++;
+      else {
+        counts.covered++;
+        if (attribution === 'claude-code') counts.claudeCode++;
+        else if (attribution === 'elanous') counts.elanous++;
+        else counts.other++;
+      }
+    }
+    result[axis] = counts;
+  }
+  return { ...window, axes: result };
+}
+
+export function formatDependenceReport(report: DependenceReport): string {
+  return [
+    `Dependence · ${report.since} — ${report.until}`,
+    ...axes.map(axis => {
+      const row = report.axes[axis];
+      return `${axis}: ${row.status}${row.reason ? ` (${row.reason})` : ''} · coverage ${row.covered}/${row.total} · claude-code ${row.claudeCode} · elanous ${row.elanous} · other ${row.other} · unknown ${row.unknown} · undated ${row.undated}`;
+    }),
+  ].join('\n');
+}
+
+/** Register below the existing `self` command rather than creating a second top-level command. */
+export function registerDependenceCommand(self: Command, deps: DependenceGaugeDeps = {}): void {
+  self.command('dependence').description('Read-only attribution gauge (unknown is not zero)')
+    .option('--since <date>', 'UTC date or lookback period (default 7d)', '7d')
+    .option('--until <date>', 'UTC date or timestamp').option('--json', 'JSON output')
+    .action((options: { since?: string; until?: string; json?: boolean }) => {
+      const report = measureDependence(deps, options);
+      (deps.out ?? console).log(options.json ? JSON.stringify(report) : formatDependenceReport(report));
+    });
+}

package/src/cli/doctor-cli.ts

@@ -34,6 +34,7 @@ import { ADVISABLE_DOCTOR_FIX_IDS, adviseDoctorFixes, type DoctorAdvice } from '
 import { gitInstallPlan } from './git-install-plan.js';
 import { detectDistroFamily, parseOsRelease } from './doctor-distro.js';
 import { checkPythonEnv } from './python-cli.js';
+import { describeModes, formatModeLine, type DoctorMode } from './doctor-modes.js';
 
 function defaultCheckPythonEnv(): { status: 'ok' | 'fixable' | 'manual'; evidence: string; remedy?: string } {
   const c = checkPythonEnv(false);
@@ -99,6 +100,8 @@ export interface DoctorReport {
   externalCommands: DoctorExternalCommand[];
   requiredMissing?: string[];
   capabilitySummary?: DoctorCapabilitySummary;
+  /** Read-only configuration and chat-use status. Present on a successful report. */
+  modes?: DoctorMode[];
   /** F1 readiness. Present on a successful report. Absent when the report itself failed. */
   readiness?: ReadinessReport;
   reason?: string;
@@ -1044,6 +1047,7 @@ export function runDoctor(options: DoctorOptions = {}): DoctorReport {
       externalCommands: externalCommands.commands,
       requiredMissing,
       capabilitySummary: summarizeDoctorCapabilities(credentials),
+      modes: describeModes(resolutionOptions.userConfig),
       readiness: evaluateReadiness(readiness),
       retiredConfigKeys: findRetiredConfigKeysInFile(options.configPath, readFile),
       ...(resourceMetadata.available ? {} : { catalogMetadataUnavailable: true }),
@@ -1136,6 +1140,7 @@ export function formatDoctorReport(report: DoctorReport, options: { credentials?
     }),
     ...(report.externalCommandsCatalogUnavailable ? [`External commands catalog unavailable: ${report.externalCommandsCatalogReason ?? 'catalog/external-commands.yaml is unavailable.'}`] : []),
     ...formatCapabilitySummary(capabilitySummary),
+    ...(report.modes ? ['모드:', ...report.modes.map((row) => `  ${formatModeLine(row)}`)] : []),
   ].join('\n');
 }
 

package/src/cli/doctor-modes.ts

@@ -0,0 +1,48 @@
+import { DEFAULT_MODEL_TIER, isModelTier, type ModelTier } from '../model-tier/types.js';
+
+export interface DoctorMode {
+  id: 'model-tier' | 'auto-route' | 'fast-mode';
+  value: ModelTier | boolean | 'none';
+  source: 'config' | 'default' | 'none';
+  usedByChat: boolean;
+  note: string;
+}
+
+/** Report configured switches without changing them or implying they affect chat turns. */
+export function describeModes(cfg: { modelTier?: { llm?: unknown }; llm?: { autoRoute?: { enabled?: unknown } } }): DoctorMode[] {
+  const tier = cfg.modelTier?.llm;
+  const autoRoute = cfg.llm?.autoRoute?.enabled;
+  return [
+    {
+      id: 'model-tier',
+      value: isModelTier(tier) ? tier : DEFAULT_MODEL_TIER,
+      source: isModelTier(tier) ? 'config' : 'default',
+      usedByChat: false,
+      note: '대화 턴 모델 선택에 쓰이지 않는다(표시·전환 계획만)',
+    },
+    {
+      id: 'auto-route',
+      value: typeof autoRoute === 'boolean' ? autoRoute : false,
+      source: typeof autoRoute === 'boolean' ? 'config' : 'default',
+      usedByChat: false,
+      note: '오토파일럿 턴만 읽는다 · 켜기 = elanous config set llm.autoRoute.enabled true',
+    },
+    {
+      id: 'fast-mode',
+      value: 'none',
+      source: 'none',
+      usedByChat: false,
+      note: '스위치 없음(분류기 호출부 0)',
+    },
+  ];
+}
+
+export function formatModeLine(row: DoctorMode): string {
+  const label = {
+    'model-tier': 'smart·등급',
+    'auto-route': 'smart·자동 라우팅',
+    'fast-mode': '빠른 모드',
+  }[row.id];
+  const source = { config: '설정', default: '기본', none: '없음' }[row.source];
+  return `${label}: ${String(row.value)}(${source}) · 대화에 ${row.usedByChat ? '쓰임' : '안 쓰임'} — ${row.note}`;
+}

package/src/cli/intake-cli.ts

@@ -11,6 +11,7 @@ import { writeStdoutFully } from './stdout-flush.js';
 import { runGitCommand } from '../git-fs/runner.js';
 import { debug } from '../debug/log.js';
 import { getUserConfig } from '../user-config.js';
+import { registerIntakeSourceCommands } from './intake-source-cli.js';
 
 export interface IntakeToTasksCliDeps {
   root: string;
@@ -91,6 +92,7 @@ export function resolveIntakeCheckRoot(
 export function registerIntakeCommands(program: Command): void {
   // ── intake check — 바깥 사실을 elanous 현재와 대조 (태스크 등록 없음) ──
   const intakeCmd = program.command('intake').description('바깥 사실·문서를 elanous 현재와 대조하거나 태스크로 받는다');
+  registerIntakeSourceCommands(intakeCmd);
   intakeCmd.hook('preAction', async () => {
     try {
       const { registerStandaloneLogSink } = await import('../domains/standalone-log-sink.js');
@@ -217,7 +219,9 @@ export function registerIntakeCommands(program: Command): void {
       const { readPipedStdin } = await import('./piped-stdin.js');
       const text = opts.file ? readFileSync(opts.file, 'utf8') : (await readPipedStdin()) ?? '';
       const { raws, bad } = parseRawIntakeJsonl(text);
-      const result = ingestIntakeItems(effectiveInstanceRoot(), opts.source as (typeof INTAKE_SOURCES)[number], raws);
+      let result: ReturnType<typeof ingestIntakeItems>;
+      try { result = ingestIntakeItems(effectiveInstanceRoot(), opts.source as (typeof INTAKE_SOURCES)[number], raws); }
+      catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 2; return; }
       const out = { source: opts.source, inputLines: raws.length + bad, badInputLines: bad, ...result };
       if (opts.json) await writeStdoutFully(JSON.stringify(out, null, 2));
       else console.log(`흡수 원장 · ${opts.source}: 새 ${result.added} · 합침 ${result.merged} · 이미 끝난 것 ${result.seen} · 버림 ${result.skipped}${bad ? ` · 깨진 입력 ${bad}` : ''}${result.badLines ? ` · 깨진 원장 줄 ${result.badLines}` : ''}`);
@@ -228,14 +232,20 @@ export function registerIntakeCommands(program: Command): void {
     .description('흡수 원장 항목 보기 (최근 본 순)')
     .option('--status <status>', 'new | queued | absorbed | checked | routed | discarded | deferred')
     .option('--source <source>', '입력원으로 거르기')
+    .option('--seat <id>', '자리 id (별칭 허용; 자리 없는 옛 항목은 제외)')
     .option('--limit <n>', '최대 줄 수 (기본 30)')
     .option('--json', '구조화 출력')
-    .action(async (opts: { status?: string; source?: string; limit?: string; json?: boolean }) => {
+    .action(async (opts: { status?: string; source?: string; seat?: string; limit?: string; json?: boolean }) => {
       const { listIntakeItems } = await import('../intake-plane/items.js');
       const { effectiveInstanceRoot } = await import('../instance/resolve.js');
+      const { canonicalSeat } = await import('../intake-plane/intake-sources.js');
+      let seat: string | undefined;
+      try { seat = opts.seat === undefined ? undefined : canonicalSeat(opts.seat); }
+      catch (error) { console.error((error as Error).message); process.exitCode = 2; return; }
       const all = listIntakeItems(effectiveInstanceRoot(), {
         ...(opts.status ? { status: opts.status as never } : {}),
         ...(opts.source ? { source: opts.source as never } : {}),
+        ...(seat ? { seat } : {}),
       });
       const limit = Math.max(1, Number(opts.limit ?? 30) || 30);
       const shown = all.slice(0, limit);

package/src/cli/intake-source-cli.ts

@@ -0,0 +1,58 @@
+import type { Command } from 'commander';
+import { randomUUID } from 'node:crypto';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { addSource, canonicalSeat, dueSources, expiredSource, listSources, removeSource, runDue, type SourceKind } from '../intake-plane/intake-sources.js';
+
+export function registerIntakeSourceCommands(intake: Command, root: () => string = effectiveInstanceRoot): void {
+  const source = intake.command('source').description('자리별 흡수 원천과 주기 등록·조회·실행');
+  const fail = (error: unknown) => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 2; };
+  source.command('add')
+    .requiredOption('--seat <id>', '자리 id 또는 별칭')
+    .requiredOption('--kind <kind>', 'github-query | rss | command')
+    .requiredOption('--spec <spec>', 'GitHub 질의 · 피드 URL · 명령')
+    .requiredOption('--every <cadence>', 'Nh | Nd | Nw')
+    .option('--until <date>', '만료 시작 날짜 YYYY-MM-DD (UTC)')
+    .option('--why <reason>', '등록 이유')
+    .option('--id <id>', '원천 id')
+    .action((opts: { seat: string; kind: string; spec: string; every: string; until?: string; why?: string; id?: string }) => {
+      try {
+        const added = addSource({ id: opts.id ?? `src-${randomUUID().slice(0, 8)}`, seat: opts.seat, kind: opts.kind as SourceKind,
+          spec: opts.spec, every: opts.every, ...(opts.until ? { until: opts.until } : {}), ...(opts.why ? { why: opts.why } : {}) }, root());
+        console.log(`${added.id}  ${added.seat}  ${added.kind}  ${added.every}`);
+      } catch (error) { fail(error); }
+    });
+  source.command('list')
+    .option('--seat <id>', '자리 id 또는 별칭')
+    .option('--json', 'JSON 출력')
+    .action((opts: { seat?: string; json?: boolean }) => {
+      try {
+        const now = new Date();
+        const sources = listSources({ seat: opts.seat }, root()).map((entry) => ({ ...entry, expired: expiredSource(entry, now) }));
+        if (opts.json) console.log(JSON.stringify(sources));
+        else for (const entry of sources) console.log(`${entry.id}  ${entry.seat}  ${entry.kind}  ${entry.every}  ${entry.expired ? '만료' : '활성'}  ${entry.spec}`);
+      } catch (error) { fail(error); }
+    });
+  source.command('remove <id>').action((id: string) => {
+    try { if (!removeSource(id, root())) { console.error(`원천 id 없음: ${id}`); process.exitCode = 2; return; } console.log(`removed ${id}`); }
+    catch (error) { fail(error); }
+  });
+  source.command('run-due')
+    .option('--seat <id>', '자리 id 또는 별칭')
+    .option('--dry-run', '기한 원천 목록만 · 수집·원장·마지막 실행 시각 무변')
+    .option('--json', 'JSON 출력')
+    .action(async (opts: { seat?: string; dryRun?: boolean; json?: boolean }) => {
+      try {
+        const seat = opts.seat === undefined ? undefined : canonicalSeat(opts.seat);
+        if (opts.dryRun) {
+          const sources = dueSources(new Date(), root()).filter((entry) => seat === undefined || entry.seat === seat);
+          if (opts.json) console.log(JSON.stringify(sources));
+          else for (const entry of sources) console.log(`${entry.id}  ${entry.seat}  ${entry.kind}  ${entry.every}`);
+          return;
+        }
+        const result = await runDue({ seat, deps: { stateDir: root() } });
+        if (opts.json) console.log(JSON.stringify(result));
+        else for (const row of result.ran) console.log(`${row.id}  ${row.items}${row.error ? `  실패: ${row.error}` : ''}`);
+        if (result.ran.some((row) => row.error)) process.exitCode = 1;
+      } catch (error) { fail(error); }
+    });
+}

package/src/cli/machine-cli.ts

@@ -1,4 +1,6 @@
 import type { Command } from 'commander';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { loadMachineLedger, machineMarkdownPath, renderLedgerMarkdown, setMachineField } from '../machines/machine-ledger.js';
 import { MACHINE_NAME, resolveMachineName } from '../roles/machine-name.js';
 import { readMachineProfile, seatRank, validSeatRank, writeMachineProfile } from '../roles/machine-profile.js';
 
@@ -28,6 +30,27 @@ export function registerMachineCommands(program: Command, root?: string): void {
       writeMachineProfile({ id, duties, seats }, root);
       console.log(`machine · ${id} · ${duties.join(',') || '-'} · ${Object.entries(seats).map(([seat, value]) => `${seat}:${value.rank}`).join(',') || '-'}`);
     });
+  machine.command('render').description('YAML 원장에서 Markdown 생성·검증')
+    .option('--check', 'Markdown 과 YAML 동기화 검증')
+    .action((opts: { check?: boolean }) => {
+      const markdown = renderLedgerMarkdown(loadMachineLedger(process.cwd()));
+      const path = machineMarkdownPath(process.cwd());
+      if (opts.check) {
+        let current: string;
+        try { current = readFileSync(path, 'utf8'); } catch { throw new Error(`machine ledger Markdown missing: ${path}`); }
+        if (current !== markdown) throw new Error(`machine ledger Markdown stale: ${path}`);
+        console.log('machine render --check OK');
+      } else {
+        writeFileSync(path, markdown, 'utf8');
+        console.log(`machine render · ${path}`);
+      }
+    });
+  machine.command('ledger-set').description('YAML 보유 자원 필드 수정')
+    .argument('<id>').argument('<field>').argument('<value>')
+    .action((id: string, field: string, value: string) => {
+      setMachineField(process.cwd(), id, field, value);
+      console.log(`machine ledger-set · ${id} · ${field}`);
+    });
   machine.command('show').option('--json', 'JSON 출력')
     .action((opts: { json?: boolean }) => {
       const resolved = resolveMachineName({ root });

package/src/cli/msg-cli.ts

@@ -0,0 +1,137 @@
+import type { Command } from 'commander';
+import { canonicalSeatId, openMsgStore, type Message, type MsgStore } from '../msg/msg-store.js';
+
+export interface MsgCliDeps {
+  openStore?: () => MsgStore;
+  out?: Pick<Console, 'log' | 'error'>;
+  readStdin?: () => Promise<string>;
+  sleep?: (ms: number) => Promise<void>;
+  setExitCode?: (code: number) => void;
+  signal?: AbortSignal;
+}
+
+type CommonOptions = { json?: boolean };
+type RecipientOptions = CommonOptions & { to?: string; after?: string; limit?: string };
+
+function seat(raw: string | undefined, flag: string): string {
+  if (raw === undefined) throw new Error(`${flag} is required`);
+  return canonicalSeatId(raw);
+}
+
+function integer(raw: string | undefined, flag: string, fallback: number, min: number, max: number): number {
+  if (raw === undefined) return fallback;
+  if (!/^(0|[1-9]\d*)$/.test(raw)) throw new Error(`${flag} must be an integer between ${min} and ${max}`);
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`${flag} must be an integer between ${min} and ${max}`);
+  return value;
+}
+
+function formatMessage(message: Message): string {
+  return `#${message.id} ${message.createdAt} ${message.from} → ${message.to}${message.kind ? ` [${message.kind}]` : ''}: ${message.body}`;
+}
+
+/** Register the durable, recipient-addressed CLI. Reading never advances the acknowledgement cursor. */
+export function registerMsgCommands(program: Command, deps: MsgCliDeps = {}): void {
+  const open = deps.openStore ?? (() => openMsgStore());
+  const out = deps.out ?? console;
+  const readStdin = deps.readStdin ?? (() => Bun.stdin.text());
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
+  const setExitCode = deps.setExitCode ?? ((code: number) => { process.exitCode = code; });
+  const msg = program.command('msg').description('Durable seat-addressed messages');
+
+  const run = (action: () => void | Promise<void>) => async () => {
+    try { await action(); }
+    catch (error) {
+      out.error(`msg: ${error instanceof Error ? error.message : String(error)}`);
+      setExitCode(2);
+    }
+  };
+  const withStore = <T>(action: (store: MsgStore) => T): T => {
+    const store = open();
+    try { return action(store); }
+    finally { store.close(); }
+  };
+  const emit = (value: unknown, json: boolean | undefined, human: () => void) => {
+    if (json) out.log(JSON.stringify(value));
+    else human();
+  };
+
+  msg.command('post [body]').description('Post a message; use - or omit body to read stdin')
+    .option('--from <seat>').option('--to <seat>').option('--kind <kind>').option('--body <text>').option('--json')
+    .action((body: string | undefined, opts: CommonOptions & { from?: string; to?: string; kind?: string; body?: string }) => run(async () => {
+      const from = seat(opts.from, '--from');
+      const to = seat(opts.to, '--to');
+      if (body !== undefined && body !== '-' && opts.body !== undefined) throw new Error('provide body once (argument or --body)');
+      const text = opts.body ?? (body !== undefined && body !== '-' ? body : await readStdin());
+      const posted = withStore(store => store.post({ from, to, body: text, ...(opts.kind === undefined ? {} : { kind: opts.kind }) }));
+      emit(posted, opts.json, () => out.log(formatMessage(posted)));
+    })());
+
+  msg.command('list').description('List messages for one recipient without acknowledging them')
+    .option('--to <seat>').option('--after <id>', 'exclusive message ID (default: acknowledged cursor)')
+    .option('--limit <count>', 'maximum messages (1–1000)').option('--json')
+    .action((opts: RecipientOptions) => run(() => {
+      const to = seat(opts.to, '--to');
+      const limit = integer(opts.limit, '--limit', 100, 1, 1000);
+      const after = opts.after === undefined ? undefined : integer(opts.after, '--after', 0, 0, Number.MAX_SAFE_INTEGER);
+      const messages = withStore(store => store.list(to, after ?? store.getCursor(to), limit));
+      emit(messages, opts.json, () => {
+        if (!messages.length) out.log('No messages.');
+        for (const message of messages) out.log(formatMessage(message));
+      });
+    })());
+
+  msg.command('ack [id]').description('Explicitly acknowledge messages through this ID for one recipient')
+    .option('--to <seat>').option('--json')
+    .action((id: string | undefined, opts: CommonOptions & { to?: string }) => run(() => {
+      const to = seat(opts.to, '--to');
+      if (id === undefined) throw new Error('message ID is required');
+      const cursor = integer(id, 'message ID', 0, 0, Number.MAX_SAFE_INTEGER);
+      const acknowledged = withStore(store => store.ack(to, cursor));
+      emit({ recipient: to, cursor: acknowledged }, opts.json, () => out.log(`${to} acknowledged through #${acknowledged}`));
+    })());
+
+  msg.command('unread').description('Show recipients with unacknowledged messages')
+    .option('--to <seat>').option('--json')
+    .action((opts: CommonOptions & { to?: string }) => run(() => {
+      const to = opts.to === undefined ? undefined : seat(opts.to, '--to');
+      const rows = withStore(store => store.unread().filter(row => to === undefined || row.recipient === to));
+      emit(rows, opts.json, () => {
+        if (!rows.length) out.log('No unread messages.');
+        for (const row of rows) out.log(`${row.recipient}: ${row.count} unread`);
+      });
+    })());
+
+  msg.command('watch').description('Poll for new messages without acknowledging them (Ctrl-C to stop)')
+    .option('--to <seat>').option('--after <id>', 'exclusive message ID (default: acknowledged cursor)')
+    .option('--interval <ms>', 'poll interval in milliseconds', '1000')
+    .option('--once', 'poll once and exit').option('--json')
+    .action((opts: RecipientOptions & { interval?: string; once?: boolean }) => run(async () => {
+      const to = seat(opts.to, '--to');
+      const interval = integer(opts.interval, '--interval', 1000, 1, 60000);
+      const after = opts.after === undefined ? undefined : integer(opts.after, '--after', 0, 0, Number.MAX_SAFE_INTEGER);
+      const store = open();
+      try {
+        let cursor = after ?? store.getCursor(to);
+        do {
+          let messages: Message[];
+          do {
+            messages = store.list(to, cursor, 1000);
+            for (const message of messages) {
+              emit(message, opts.json, () => out.log(formatMessage(message)));
+              cursor = message.id;
+            }
+          } while (messages.length === 1000 && !deps.signal?.aborted);
+          if (opts.once || deps.signal?.aborted) break;
+          await sleep(interval);
+        } while (!deps.signal?.aborted);
+      } finally { store.close(); }
+    })());
+
+  // Commander reports option/argument errors before action handlers run. Scope their exit code
+  // to msg so unrelated commands keep their own error and help behavior.
+  for (const command of [msg, ...msg.commands]) {
+    const reportError = command.error.bind(command);
+    command.error = (message, options) => reportError(message, { ...options, exitCode: 2 });
+  }
+}