elanous 0.2.0 → 0.2.5

package/src/cli/role-cli.ts

@@ -0,0 +1,320 @@
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants, mkdtempSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import { interpretCasResult, isAbsentSaid, type CasOutcome } from '../roles/lease-cas.js';
+import { debug } from '../debug/log.js';
+import { getUserConfig } from '../user-config.js';
+import { readMachineProfile, seatRank, validSeatRank } from '../roles/machine-profile.js';
+import {
+  ROLE_LEASE_OBJECT_PATH, nextAccept, nextClaim, nextHandoff, nextRevert, parseRoleLease,
+  type RoleLeaseDoc,
+} from '../roles/role-lease.js';
+import { MACHINE_NAME, resolveMachineName, writeConfiguredMachine } from '../roles/machine-name.js';
+import { decideTick, initialWatchState, MIN_TAKEOVER_TICKS, type WatchState } from '../roles/role-watch.js';
+
+export type RoleObjectRead =
+  | { readonly kind: 'present'; readonly text: string; readonly gen: string }
+  | { readonly kind: 'absent' }
+  | { readonly kind: 'unmeasured'; readonly why: string };
+
+export interface RoleCliDeps {
+  read?: (bucket: string) => RoleObjectRead | Promise<RoleObjectRead>;
+  write?: (doc: RoleLeaseDoc, ifGen: string, bucket: string) => CasOutcome | Promise<CasOutcome>;
+  me?: string;
+  root?: string;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  out?: { log: (line: string) => void; error: (line: string) => void };
+  setExitCode?: (code: number) => void;
+}
+
+const machineName = MACHINE_NAME;
+const bucketName = /^gs:\/\/[a-z0-9][a-z0-9._-]{1,220}$/;
+
+export function resolveRoleBucket(option?: string): string {
+  const configured = getUserConfig().raw.roles;
+  const configBucket = configured && typeof configured === 'object' && !Array.isArray(configured)
+    ? (configured as { bucket?: unknown }).bucket : undefined;
+  const value = option ?? process.env.ELANOUS_BACKUP_BUCKET ?? configBucket;
+  if (value === undefined) throw new Error('roles.bucket 을 설정하라 (--bucket 또는 ELANOUS_BACKUP_BUCKET)');
+  if (typeof value !== 'string' || !bucketName.test(value)) throw new Error(`invalid bucket: ${String(value)}`);
+  return value;
+}
+
+const SYSTEM_GCLOUD_PATHS: readonly string[] = ['/opt/homebrew/bin/gcloud', '/usr/local/bin/gcloud', '/snap/bin/gcloud'];
+let systemGcloudPaths: readonly string[] = SYSTEM_GCLOUD_PATHS;
+/** 시험 전용 — 시스템 고정 경로를 바꾼다(`null` = 되돌림). 진짜 gcloud 가 깔린 맥에서 가짜 gcloud 시험이 진짜를 부르지 않게. */
+export function _setSystemGcloudPathsForTesting(paths: readonly string[] | null): void {
+  systemGcloudPaths = paths ?? SYSTEM_GCLOUD_PATHS;
+}
+
+export function gcloudSearchPaths(): string[] {
+  return [...systemGcloudPaths, `${process.env.HOME}/google-cloud-sdk/bin/gcloud`,
+    ...(process.env.PATH ?? '').split(':').filter(Boolean).map(dir => join(dir, 'gcloud'))];
+}
+const uri = (bucket: string) => `${bucket}/${ROLE_LEASE_OBJECT_PATH}`;
+
+export function gcloud(): string | null {
+  for (const path of gcloudSearchPaths()) {
+    try { accessSync(path, constants.X_OK); if (statSync(path).isFile()) return path; }
+    catch { /* try the next executable */ }
+  }
+  return null;
+}
+
+function runGcloud(args: string[]): { code: number | null; stdout: string; said: string } {
+  const binary = gcloud();
+  if (!binary) return { code: null, stdout: '', said: 'gcloud not found' };
+  const r = spawnSync(binary, args, { encoding: 'utf8', timeout: 120_000 });
+  return { code: r.status, stdout: r.stdout ?? '', said: `${r.stdout ?? ''}${r.stderr ?? ''}${r.error ?? ''}` };
+}
+
+function describe(bucket: string): { kind: 'present'; gen: string } | { kind: 'absent' } | { kind: 'unmeasured'; why: string } {
+  const r = runGcloud(['storage', 'objects', 'describe', uri(bucket), '--format=value(generation)']);
+  if (r.code !== 0) return r.code !== null && isAbsentSaid(r.said) ? { kind: 'absent' } : { kind: 'unmeasured', why: r.said.trim() };
+  const gen = r.stdout.trim();
+  return /^\d+$/.test(gen) ? { kind: 'present', gen } : { kind: 'unmeasured', why: 'invalid GCS generation' };
+}
+
+function liveRead(bucket: string): RoleObjectRead {
+  const before = describe(bucket);
+  if (before.kind !== 'present') return before;
+  const cat = runGcloud(['storage', 'cat', uri(bucket)]);
+  if (cat.code !== 0) return { kind: 'unmeasured', why: cat.said.trim() };
+  const after = describe(bucket);
+  if (after.kind !== 'present' || before.gen !== after.gen) return { kind: 'unmeasured', why: 'lease changed during read; retry' };
+  return { kind: 'present', text: cat.stdout, gen: before.gen };
+}
+
+function liveWrite(doc: RoleLeaseDoc, ifGen: string, bucket: string): CasOutcome {
+  const dir = mkdtempSync(join(tmpdir(), 'elanous-role-'));
+  try {
+    const file = join(dir, 'control-primary.json');
+    writeFileSync(file, `${JSON.stringify(doc)}\n`);
+    const r = runGcloud(['storage', 'cp', file, uri(bucket), `--if-generation-match=${ifGen}`]);
+    return interpretCasResult({ code: r.code, said: r.said });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function snapshot(read: RoleObjectRead): { doc: RoleLeaseDoc; gen: string } | { absent: true } {
+  if (read.kind === 'unmeasured') throw new Error(read.why);
+  if (read.kind === 'absent') return { absent: true };
+  const parsed = parseRoleLease(read.text);
+  if (parsed.kind !== 'present') throw new Error(parsed.kind === 'unmeasured' ? parsed.why : 'empty lease');
+  return { doc: parsed.doc, gen: read.gen };
+}
+
+export function registerRoleCommands(program: Command, overrides: RoleCliDeps = {}): void {
+  const deps = {
+    read: liveRead, write: liveWrite, me: undefined as string | undefined, now: Date.now,
+    sleep: (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)),
+    out: console, setExitCode: (code: number) => { process.exitCode = code; },
+    ...overrides,
+  };
+  const role = program.command('role').description('관제부 Primary 임대 조회 및 수동 넘김');
+  const bucket = resolveRoleBucket;
+  const me = () => {
+    const name = deps.me ?? resolveMachineName({ root: deps.root }).machine;
+    if (!machineName.test(name)) throw new Error(`invalid machine: ${name} — \`elanous role set-machine <식별자>\` 로 정한다`);
+    return name;
+  };
+  role.command('whoami').description('임대에서 이 기계가 쓰는 이름과 그 출처')
+    .action(() => execute(async () => {
+      const r = deps.me !== undefined ? { machine: deps.me, source: 'option' } : resolveMachineName({ root: deps.root });
+      deps.out.log(`${r.machine} · ${r.source}${machineName.test(r.machine) ? '' : ' · invalid'}`);
+      return machineName.test(r.machine) ? 0 : 1;
+    })());
+  role.command('set-machine <name>').description('임대 기계 이름을 명시(control/machine.json)')
+    .action((name: string) => execute(async () => {
+      writeConfiguredMachine(name, deps.root);
+      deps.out.log(`machine · ${name}`);
+      return 0;
+    })());
+  const observe = (event: 'claim' | 'handoff' | 'accept' | 'revert', from: string | undefined, to: string, generation: number, outcome: string) => {
+    debug.log('roles.lease', event, { from, to, generation, outcome });
+  };
+  const execute = (action: () => Promise<number>) => async () => {
+    try {
+      const code = await action();
+      if (code !== 0) deps.setExitCode(code);
+    } catch (e) {
+      deps.out.error(`role: ${e instanceof Error ? e.message : String(e)}`);
+      deps.setExitCode(e instanceof Error && e.message.includes('roles.bucket 을 설정하라') ? 2 : 1);
+    }
+  };
+  role.command('status').option('--json', 'JSON 출력').option('--bucket <bucket>', 'GCS 버킷')
+    .action((opts: { json?: boolean; bucket?: string }) => execute(async () => {
+      let lease: { doc: RoleLeaseDoc; gen: string } | { absent: true } | { unmeasured: string };
+      try {
+        const b = bucket(opts.bucket);
+        const read = await deps.read(b);
+        lease = read.kind === 'unmeasured' ? { unmeasured: read.why } : snapshot(read);
+      } catch (e) {
+        lease = { unmeasured: e instanceof Error ? e.message : String(e) };
+      }
+      const status = 'doc' in lease ? {
+        holder: lease.doc.holder, generation: lease.doc.generation, state: lease.doc.state,
+        ...(lease.doc.from ? { from: lease.doc.from } : {}),
+      } : 'absent' in lease ? { absent: true } : lease;
+      deps.out.log(opts.json ? JSON.stringify(status) : `role: ${JSON.stringify(status)}`);
+      return 'unmeasured' in status ? (status.unmeasured.includes('roles.bucket 을 설정하라') ? 2 : 1) : 'absent' in status ? 2 : 0;
+    })());
+  role.command('watch').description('부팅 시 Primary 임대를 관찰·갱신·인수')
+    // Every machine must use the same cadence: counting faster observer ticks can preempt a live holder.
+    .option('--interval <seconds>', '공통 틱 간격(초; 모든 기계에서 60)', '60')
+    .option('--takeover-ticks <count>', '변화 없는 관찰 틱 수', '5')
+    .option('--rank <n>', '이 기계의 control 자리 후보 순위(프로필 덮어쓰기)')
+    .option('--once', '한 틱만 실행')
+    .option('--bucket <bucket>', 'GCS 버킷')
+    .action((opts: { interval: string; takeoverTicks: string; rank?: string; once?: boolean; bucket?: string }) => execute(async () => {
+      const seconds = Number(opts.interval), ticks = Number(opts.takeoverTicks);
+      if (!Number.isSafeInteger(seconds) || seconds < 1) throw new Error('interval must be a positive integer (seconds)');
+      if (seconds !== 60) throw new Error('interval must be 60 seconds on every machine (shared renewal and takeover cadence)');
+      if (!Number.isSafeInteger(ticks) || ticks < MIN_TAKEOVER_TICKS) {
+        throw new Error(`takeover-ticks must be at least ${MIN_TAKEOVER_TICKS} (one missed renewal can precede a live holder)`);
+      }
+      const explicitRank = opts.rank === undefined ? undefined : Number(opts.rank);
+      if (opts.rank !== undefined && (!validSeatRank(explicitRank!) || !/^[0-9]+$/.test(opts.rank))) throw new Error('rank must be an integer from 1 to 99');
+      const b = bucket(opts.bucket), owner = me();
+      const tickRank = () => {
+        const profile = readMachineProfile(deps.root);
+        const currentId = profile?.id ?? (deps.me ?? resolveMachineName({ root: deps.root }).machine);
+        if (currentId !== owner) throw new Error(`machine id changed during watch: ${owner} → ${currentId}`);
+        return opts.rank === undefined ? seatRank(profile, 'control') : explicitRank;
+      };
+      let state: WatchState = initialWatchState;
+      do {
+        const rank = tickRank();
+        const read = await deps.read(b);
+        if (tickRank() !== rank) throw new Error('machine rank changed during lease read');
+        const decision = decideTick(state, read, { me: owner, rank, takeoverTicks: ticks, now: deps.now() });
+        state = decision.state;
+        let event: 'claim' | 'renew' | 'takeover' | 'accept' | 'observe' | 'cas-rejected' = decision.action;
+        if (decision.doc && decision.ifGen !== undefined) {
+          if (tickRank() !== rank) throw new Error('machine rank changed before lease write');
+          const result = await deps.write(decision.doc, decision.ifGen, b);
+          if (result.kind === 'unmeasured') throw new Error(`watch CAS unmeasured: ${result.why}`);
+          if (result.kind === 'lost') {
+            event = 'cas-rejected';
+            state = initialWatchState;
+          } else {
+            state = { generation: decision.doc.generation, unchangedTicks: 0, absentTicks: 0 };
+          }
+        }
+        const written = event !== 'cas-rejected' ? decision.doc : undefined;
+        const data = { holder: written?.holder ?? decision.holder ?? null, generation: written?.generation ?? decision.generation ?? null, me: owner, rank: rank ?? null, unchangedTicks: decision.state.unchangedTicks, absentTicks: decision.state.absentTicks };
+        debug.log('roles.lease', event, data);
+        debug.log('roles.watch', event, data);
+        deps.out.log(`watch: ${event} · holder ${data.holder ?? 'absent'} · gen ${data.generation ?? 'absent'} · unchangedTicks ${data.unchangedTicks}`);
+        if (opts.once) break;
+        await deps.sleep(seconds * 1_000);
+      } while (true);
+      return 0;
+    })());
+  role.command('claim').option('--bucket <bucket>', 'GCS 버킷')
+    .action((opts: { bucket?: string }) => execute(async () => {
+      const b = bucket(opts.bucket), owner = me(), current = snapshot(await deps.read(b));
+      const doc = nextClaim('absent' in current ? { kind: 'absent' } : { kind: 'present', doc: current.doc }, owner, deps.now());
+      const result = await deps.write(doc, 'absent' in current ? '0' : current.gen, b);
+      observe('claim', 'absent' in current ? undefined : current.doc.holder, owner, doc.generation, result.kind);
+      if (result.kind !== 'won') throw new Error(`claim CAS ${result.kind}`);
+      deps.out.log(`claim: ${owner} · gen ${doc.generation} · held`);
+      return 0;
+    })());
+  role.command('accept').option('--bucket <bucket>', 'GCS 버킷')
+    .action((opts: { bucket?: string }) => execute(async () => {
+      const b = bucket(opts.bucket), owner = me(), current = snapshot(await deps.read(b));
+      if ('absent' in current) throw new Error('lease absent');
+      const doc = nextAccept(current.doc, owner, deps.now());
+      const result = await deps.write(doc, current.gen, b);
+      observe('accept', current.doc.from, owner, doc.generation, result.kind);
+      if (result.kind !== 'won') throw new Error(`accept CAS ${result.kind}`);
+      deps.out.log(`accept: ${owner} · gen ${doc.generation} · held`);
+      return 0;
+    })());
+  role.command('handoff').requiredOption('--to <machine>', '대상 기계')
+    .option('--timeout <seconds>', '수락 제한 시간(초)', '120').option('--bucket <bucket>', 'GCS 버킷')
+    .action((opts: { to: string; timeout: string; bucket?: string }) => execute(async () => {
+      const b = bucket(opts.bucket), owner = me();
+      if (!machineName.test(opts.to)) throw new Error(`invalid target: ${opts.to}`);
+      const seconds = Number(opts.timeout);
+      if (!Number.isSafeInteger(seconds) || seconds < 1) throw new Error('timeout must be a positive integer (seconds)');
+      const current = snapshot(await deps.read(b));
+      if ('absent' in current) throw new Error('lease absent');
+      const pending = nextHandoff(current.doc, owner, opts.to, deps.now());
+      const result = await deps.write(pending, current.gen, b);
+      observe('handoff', owner, opts.to, pending.generation, result.kind);
+      if (result.kind !== 'won') throw new Error(`handoff CAS ${result.kind}`);
+      const start = deps.now();
+      const line = (outcome: string, gen: number) => deps.out.log(`handoff: ${owner} → ${opts.to} · gen ${gen} · ${outcome}`);
+      let lastPending: { doc: RoleLeaseDoc; gen: string } | undefined;
+      while (true) {
+        let observed: RoleObjectRead;
+        try { observed = await deps.read(b); }
+        catch (e) { observed = { kind: 'unmeasured', why: e instanceof Error ? e.message : String(e) }; }
+        if (observed.kind === 'present') {
+          let parsed: ReturnType<typeof snapshot> | undefined;
+          try { parsed = snapshot(observed); } catch { /* transient malformed read: retry until deadline */ }
+          if (parsed && !('absent' in parsed)) {
+            const doc = parsed.doc;
+            if (doc.state === 'held' && doc.holder === opts.to && doc.generation === pending.generation + 1) {
+              if (deps.now() - start >= seconds * 1_000) {
+                observe('revert', owner, opts.to, doc.generation, 'revert-failed');
+                line('revert-failed', doc.generation);
+                return 1;
+              }
+              observe('handoff', owner, opts.to, doc.generation, 'accepted');
+              line('accepted', doc.generation);
+              return 0;
+            }
+            if (doc.state !== 'handing-off' || doc.holder !== opts.to || doc.from !== owner || doc.generation !== pending.generation) {
+              observe('revert', owner, opts.to, doc.generation, 'revert-failed');
+              line('revert-failed', pending.generation);
+              return 1;
+            }
+            lastPending = { doc, gen: parsed.gen };
+          }
+        }
+        if (deps.now() - start >= seconds * 1_000) {
+          if (observed.kind !== 'present') {
+            let refreshed: RoleObjectRead;
+            try { refreshed = await deps.read(b); }
+            catch { refreshed = { kind: 'unmeasured', why: 'read failed' }; }
+            if (refreshed.kind === 'present') {
+              try {
+                const latest = snapshot(refreshed);
+                if (!('absent' in latest)) {
+                  const doc = latest.doc;
+                  if (doc.state === 'handing-off' && doc.holder === opts.to && doc.from === owner && doc.generation === pending.generation) {
+                    lastPending = { doc, gen: latest.gen };
+                  } else {
+                    observe('revert', owner, opts.to, doc.generation, 'revert-failed');
+                    line('revert-failed', pending.generation);
+                    return 1;
+                  }
+                }
+              } catch { /* retain the last confirmed generation for a CAS revert */ }
+            }
+          }
+          if (lastPending) {
+            const revert = nextRevert(lastPending.doc, deps.now());
+            let undone: CasOutcome;
+            try { undone = await deps.write(revert, lastPending.gen, b); }
+            catch (e) { undone = { kind: 'unmeasured', why: e instanceof Error ? e.message : String(e) }; }
+            observe('revert', opts.to, owner, revert.generation, undone.kind === 'won' ? 'timeout-reverted' : 'revert-failed');
+            line(undone.kind === 'won' ? 'timeout-reverted' : 'revert-failed', undone.kind === 'won' ? revert.generation : pending.generation);
+            return 1;
+          }
+          observe('revert', opts.to, owner, pending.generation, 'revert-failed');
+          line('revert-failed', pending.generation);
+          return 1;
+        }
+        try { await deps.sleep(Math.min(1_000, Math.max(1, seconds * 1_000 - (deps.now() - start)))); }
+        catch { /* keep polling or attempt a CAS revert at the deadline */ }
+      }
+    })());
+}

package/src/cli/schedule-cli.ts

@@ -0,0 +1,246 @@
+import { readFile } from 'node:fs/promises';
+import type { Database } from 'bun:sqlite';
+import type { Command } from 'commander';
+import * as ui from '../ui.js';
+import { writeStdoutJson } from './stdout-json.js';
+
+// ── cron (스케줄/크론 CRUD — claude code/codex 외부 접근용) ──
+// dispatchScheduleManage(전 표면 공유 구현) 재사용 → schedule_registry·crontab·surface_events
+// 메모리 루프까지 텔레그램/PWA와 동일 정합. schedules.db 직접 조작 금지(정합 깨짐).
+interface ScheduleOpts { id?: string; category?: string; cron?: string; command?: string; apm?: string; json?: boolean; dryRun?: boolean; from?: string; to?: string; yes?: boolean; only?: string }
+interface ScheduleRunsOpts { limit?: string; before?: string; json?: boolean }
+interface ScheduleRunRow {
+  run_id: string | null;
+  fired_at: string;
+  status: string;
+  exit: number | null;
+  duration_ms: number | null;
+  via: string;
+}
+export type ScheduleRunsReader = (id: string, opts: { limit: number; before?: string }) => ScheduleRunRow[];
+
+export type ScheduleDispatch = (args: Record<string, unknown>) => Promise<unknown>;
+type ScheduleExit = (code: number) => void;
+type SchedulePlanValue<T> = { found: T } | { missing: string };
+type ScheduleCreatePlan = {
+  schedule: SchedulePlanValue<string>;
+  commands: SchedulePlanValue<string[]>;
+  resultPath: SchedulePlanValue<string>;
+  cron: SchedulePlanValue<string>;
+};
+type ParsedScheduleCreatePlan = { from: string; plan: ScheduleCreatePlan } | { error: string };
+
+async function parseScheduleCreatePlan(from?: string): Promise<ParsedScheduleCreatePlan> {
+  if (!from) return { error: '명세 문서 경로를 --from으로 지정해야 합니다.' };
+
+  let specification: string;
+  try {
+    specification = await readFile(from, 'utf8');
+  } catch {
+    return { error: `명세 문서를 읽을 수 없음: ${from}` };
+  }
+
+  const schedule = specification.match(/^\s*-\s*\*\*주기:\*\*\s*(.+?)(?:\.|$)/m)?.[1]?.trim();
+  const commands = [...specification.matchAll(/^\s*bun bin\/elanous\.mjs\s+(.+)$/gm)].map(match => match[1].trim());
+  const resultPath = specification.match(/^(reports\/[^\s`]+)$/m)?.[1];
+  const cron = specification.match(/^\s*(?:-\s*)?cron\s*:\s*`?([^`\n]+)`?\s*$/mi)?.[1]?.trim();
+  return {
+    from,
+    plan: {
+      schedule: schedule ? { found: schedule } : { missing: '주기' },
+      commands: commands.length > 0 ? { found: commands } : { missing: '실행 명령' },
+      resultPath: resultPath ? { found: resultPath } : { missing: '결과 경로' },
+      cron: cron ? { found: cron } : { missing: '명세에 cron 식이 없음' },
+    },
+  };
+}
+
+export async function scheduleCreatePlan(opts: Pick<ScheduleOpts, 'dryRun' | 'from'>): Promise<unknown> {
+  const parsed = await parseScheduleCreatePlan(opts.from);
+  if ('error' in parsed) {
+    return { error: opts.from ? parsed.error : 'dry-run에는 명세 문서 경로를 --from으로 지정해야 합니다.' };
+  }
+  const { from, plan } = parsed;
+  if ('missing' in plan.schedule || 'missing' in plan.commands) {
+    return { error: '명세에 등록 계획의 필수 주기 또는 실행 명령이 없음', from, plan };
+  }
+  return {
+    dryRun: true,
+    from,
+    plan,
+    note: '명세에서 등록 계획만 산출했습니다. 스케줄 저장소와 crontab은 변경하지 않았습니다.',
+  };
+}
+
+export async function runSchedule(action: string, opts: ScheduleOpts, dispatch?: ScheduleDispatch, exit: ScheduleExit = process.exit): Promise<void> {
+  let result: unknown;
+  if (['migrate', 'adopt', 'release', 'delete'].includes(action) && opts.yes !== true) {
+    result = { dryRun: true, action, id: opts.id, note: '적용하려면 --yes 를 붙인다' };
+  } else if (action === 'retarget') {
+    const { retargetScheduleFolders } = await import('../domains/schedule-retarget-action.js');
+    result = retargetScheduleFolders({ from: opts.from, to: opts.to, yes: opts.yes === true, ...(opts.only ? { only: opts.only } : {}) });
+  } else if (action === 'create' && opts.dryRun) {
+    result = await scheduleCreatePlan(opts);
+  } else if (action === 'create' && opts.from) {
+    const parsed = await parseScheduleCreatePlan(opts.from);
+    if ('error' in parsed) {
+      result = parsed;
+    } else {
+      const requiredPlanFields = [
+        ['schedule', parsed.plan.schedule],
+        ['commands', parsed.plan.commands],
+        ['resultPath', parsed.plan.resultPath],
+        ['cron', parsed.plan.cron],
+      ] as const;
+      const missing = requiredPlanFields
+        .filter(([, value]) => 'missing' in value)
+        .map(([field]) => field);
+      if (missing.length > 0) {
+        result = { error: `명세 등록을 거부했습니다: ${missing.join(', ')}`, from: parsed.from, plan: parsed.plan };
+      } else if (
+        'found' in parsed.plan.schedule
+        && 'found' in parsed.plan.commands
+        && 'found' in parsed.plan.resultPath
+        && 'found' in parsed.plan.cron
+      ) {
+        result = await (dispatch ?? (await import('../domains/schedule-manage-tool.js')).dispatchScheduleManage)({
+          action,
+          id: opts.id,
+          category: opts.category,
+          cron: parsed.plan.cron.found,
+          command: parsed.plan.commands.found.map(command => `bun bin/elanous.mjs ${command}`).join(' && '),
+          schedule: parsed.plan.schedule.found,
+          resultPath: parsed.plan.resultPath.found,
+          yes: true,
+          ...(opts.apm ? { autopilotId: opts.apm } : {}),
+        });
+      } else {
+        result = { error: '명세 등록 계획을 읽을 수 없음', from: parsed.from, plan: parsed.plan };
+      }
+    }
+  } else {
+    result = await (dispatch ?? (await import('../domains/schedule-manage-tool.js')).dispatchScheduleManage)({
+      action, id: opts.id, category: opts.category, cron: opts.cron, command: opts.command,
+      // 오토파일럿 계보(AL2) — --apm 으로 미션에 fan-in 태깅(관측성). dispatch 가 setScheduleMission.
+      ...(opts.apm ? { autopilotId: opts.apm } : {}),
+      // wrap/unwrap(P3 관측성 래핑) — --yes 로 적용(기본 dry-run).
+      ...((opts as { yes?: boolean }).yes ? { yes: true } : {}),
+    });
+  }
+  const isErr = !!result && typeof result === 'object' && 'error' in (result as object);
+  if (opts.json) {
+    await writeStdoutJson(JSON.stringify(result, null, 2) + '\n');
+  } else if (isErr) {
+    ui.error(String((result as { error: string }).error));
+  } else if (action === 'list' && result && typeof result === 'object' && 'schedules' in result) {
+    const r = result as { schedules: Array<{ id: string; name: string; cron: string | null; interval_ms: number | null; category: string; enabled: boolean; run_via: string; last_run: string | null }>; count: number };
+    ui.header(`schedules (${r.count})`);
+    for (const s of r.schedules) {
+      const when = s.cron ?? (s.interval_ms ? `${Math.round(s.interval_ms / 1000)}s` : '?');
+      const flag = s.enabled ? '' : ' [disabled]';
+      console.log(`  ${s.id.padEnd(14)}  ${when.padEnd(18)}  [${s.category}·${s.run_via}]${flag}  ${s.name}`);
+      if (s.last_run) console.log(`              last_run ${s.last_run}`);
+    }
+  } else {
+    await writeStdoutJson(JSON.stringify(result, null, 2) + '\n');
+  }
+  exit(isErr ? 1 : 0);
+}
+
+export async function runScheduleRuns(
+  id: string,
+  opts: ScheduleRunsOpts,
+  read?: ScheduleRunsReader,
+): Promise<void> {
+  const limit = opts.limit === undefined ? 20 : Number(opts.limit);
+  if (!Number.isSafeInteger(limit) || limit < 1) throw new Error('--limit에는 양의 정수가 필요합니다.');
+  if (opts.before !== undefined) {
+    const match = /^(\d{4})-(\d\d)-(\d\d)T\d\d:\d\d:\d\d(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)$/.exec(opts.before);
+    const year = Number(match?.[1]);
+    const month = Number(match?.[2]);
+    const day = Number(match?.[3]);
+    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    if (!match || month < 1 || month > 12 || day < 1 || day > days[month - 1]! || !Number.isFinite(Date.parse(opts.before))) {
+      throw new Error('--before에는 유효한 ISO 시각이 필요합니다.');
+    }
+  }
+  let rows: ScheduleRunRow[];
+  if (read) {
+    rows = read(id, { limit, ...(opts.before !== undefined ? { before: opts.before } : {}) });
+  } else {
+    const { openSchedulesDb } = await import('../domains/schedule-registry.js');
+    const { listScheduleRuns } = await import('../domains/schedule-runs.js');
+    const db: Database = openSchedulesDb();
+    try {
+      rows = listScheduleRuns(db, id, { limit, ...(opts.before !== undefined ? { before: opts.before } : {}) });
+    } finally {
+      db.close();
+    }
+  }
+  if (opts.json) {
+    await writeStdoutJson(JSON.stringify(rows, null, 2) + '\n');
+    return;
+  }
+  ui.header(`schedule runs ${id} (${rows.length})`);
+  console.log('  KST                  상태    exit  소요      via       runId');
+  for (const row of rows) {
+    const kst = new Intl.DateTimeFormat('sv-SE', { timeZone: 'Asia/Seoul', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23' }).format(new Date(row.fired_at));
+    const exit = row.exit === null ? '-' : String(row.exit);
+    const duration = row.duration_ms === null ? '-' : `${row.duration_ms}ms`;
+    console.log(`  ${kst}  ${row.status.padEnd(6)}  ${exit.padEnd(4)}  ${duration.padEnd(8)}  ${row.via.padEnd(8)}  ${row.run_id ?? '-'}`);
+  }
+}
+
+export function registerScheduleCommands(program: Command): void {
+  const scheduleCmd = program.command('schedule')
+    .description('스케줄/크론 CRUD (registry·crontab·기억 정합). --json 으로 프로그래매틱 소비.');
+
+scheduleCmd.command('list').description('전체 크론 조회(category 필터)')
+  .option('--category <cat>', 'ingest|monitor|report|alert|digest|maintenance')
+  .option('--json', 'JSON 출력(프로그래매틱)')
+  .action((o: ScheduleOpts) => runSchedule('list', o));
+scheduleCmd.command('inspect <id>').description('상세 + 최근발송(surface_events 회상·S3 폐루프)')
+  .option('--json').action((id: string, o: ScheduleOpts) => runSchedule('inspect', { ...o, id }));
+scheduleCmd.command('runs <id>').description('스케줄 실행 이력(최신순)')
+  .option('--limit <N>', '최대 조회 수(기본 20)')
+  .option('--before <ISO>', '이 시각 이전 실행만 조회')
+  .option('--json', 'JSON 출력')
+  .action((id: string, o: ScheduleRunsOpts) => runScheduleRuns(id, o));
+scheduleCmd.command('create').description('신규 크론(cron 식 + command). 자동 백업·cd/bun/로그 보강.')
+  .option('--cron <expr>', 'cron 식(예: "0 7 * * *")')
+  .option('--command <cmd>', 'command(예: "scripts/foo.ts --x")')
+  .option('--dry-run', '명세에서 등록 계획만 산출하고 등록하지 않음')
+  .option('--from <path>', '명세 문서에서 등록 계획을 읽음(--dry-run이면 계획만 산출)')
+  .option('--apm <id>', '오토파일럿 미션 fan-in 태깅(관측성·autopilot_id)')
+  .option('--json').action((o: ScheduleOpts) => {
+    if (!o.dryRun && !o.from && (!o.cron || !o.command)) throw new Error('create에는 --cron과 --command가 필요합니다.');
+    return runSchedule('create', o);
+  });
+scheduleCmd.command('update <id>').description('cron 시간 변경')
+  .requiredOption('--cron <expr>', '새 cron 식').option('--json')
+  .action((id: string, o: ScheduleOpts) => runSchedule('update', { ...o, id }));
+scheduleCmd.command('enable <id>').description('잡 켜기').option('--json')
+  .action((id: string, o: ScheduleOpts) => runSchedule('enable', { ...o, id }));
+scheduleCmd.command('disable <id>').description('잡 끄기(주석)').option('--json')
+  .action((id: string, o: ScheduleOpts) => runSchedule('disable', { ...o, id }));
+scheduleCmd.command('delete <id>').description('삭제(자동 백업·복구 가능). 기본 dry-run·--yes 적용').option('--yes', '적용(기본 dry-run)').option('--json')
+  .action((id: string, o: ScheduleOpts) => runSchedule('delete', { ...o, id }));
+scheduleCmd.command('wrap [id]').description('★관측성 래핑 — bun .ts 크론을 cron-run.ts 로 감싸 파이어 시 3계층(logs.db·레지스트리·자기기억) 기록. id 생략=전 .ts 크론. 기본 dry-run·--yes 적용(백업 자동·unwrap-aware id 승계·가역)').option('--yes', '적용(기본 dry-run)').option('--json')
+  .action((id: string | undefined, o: ScheduleOpts) => runSchedule('wrap', { ...o, ...(id ? { id } : {}) }));
+scheduleCmd.command('unwrap [id]').description('관측성 래퍼 제거(가역) — id 생략=전 래핑 크론. 기본 dry-run·--yes 적용').option('--yes', '적용(기본 dry-run)').option('--json')
+  .action((id: string | undefined, o: ScheduleOpts) => runSchedule('unwrap', { ...o, ...(id ? { id } : {}) }));
+scheduleCmd.command('migrate <id>').description('fabric Schedule Trigger 로 이관(elanous 데몬 발화·Mission Fabric B안). 기본 dry-run·--yes 적용').option('--yes', '적용(기본 dry-run)').option('--json')
+  .action((id: string, o: ScheduleOpts) => runSchedule('migrate', { ...o, id }));
+scheduleCmd.command('adopt <id>').description('=migrate 별칭(schedule-runner 은퇴로 통합). 기본 dry-run·--yes 적용').option('--yes', '적용(기본 dry-run)').option('--json')
+  .action((id: string, o: ScheduleOpts) => runSchedule('adopt', { ...o, id }));
+scheduleCmd.command('release <id>').description('crontab 실행으로 복원. 기본 dry-run·--yes 적용').option('--yes', '적용(기본 dry-run)').option('--json')
+  .action((id: string, o: ScheduleOpts) => runSchedule('release', { ...o, id }));
+scheduleCmd.command('retarget').description('크론 cd <folder> 일괄 교체 — --from 폴더를 --to 폴더로. 기본 dry-run·--yes 적용(백업 자동). 대상 폴더가 없으면 에러.')
+  .option('--from <folder>', '바꿀 원본 폴더(cd 경로)')
+  .option('--to <folder>', '새 대상 폴더(존재해야 함)')
+  .option('--only <ids>', '이 잡들만(쉼표 구분 · schedule list 의 id 접두 또는 이름 · 각각 정확히 하나에 맞아야 함)')
+  .option('--yes', '적용(기본 dry-run)')
+  .option('--json')
+  .action((o: ScheduleOpts) => runSchedule('retarget', o));
+}