elanous 0.2.41 → 0.2.43

package/src/pty-shell/tui-run-state.ts

@@ -12,7 +12,7 @@
 // 판독(CLI 쪽): `describePtyRunState` 가 행 ⊕ 설치본 기록 ⊕ (체크아웃이면) 그 뿌리의 HEAD 로 판정한다.
 
 import { spawn } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -30,6 +30,7 @@ import {
   updatePtyManifestAbortRequested, updatePtyManifestBuild, updatePtyManifestProgress, updatePtyManifestTurn,
   type PtyBuildIdentity, type PtyManifestRow, type PtyTurnState,
 } from './pty-manifest.js';
+import { ptyEventLogDbPath, readPtyEventsAfterAt } from './pty-event-log.js';
 
 const CODE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
@@ -496,6 +497,139 @@ export function judgeTurnProgress(input: TurnProgressInput): TurnProgressJudgmen
   return 'progressing';
 }
 
+// ── TUI-SEAT-PILOT-2H-COMPARE — 좌석 대조 판정 신호 한 줄 ──
+//
+// 완료 경계는 «실행 명령·runId·시작/끝 시각·두 표면의 원장 행·산출 바이트·오류 수·결과» 를
+// `seat-state/OP/tools/sim-log.sh` 한 줄로 남기라고 한다. 그 한 줄의 «형식» 은 순수 함수가 정하고,
+// 두 표면의 원장 행은 각자의 생산 원장에서 읽는다 — tui-run-state 는 pty_manifest 행, pty-event-log 는
+// `pty_events` 의 그 표면 행이다. ⛔ 재지 못한 항목은 «미측정» 으로 남긴다 — 측정된 `0` 과 섞지 않는다(null ≠ 0).
+
+/** 재지 못한 항목의 직렬화 값. 측정된 `0`·빈 문자열과 구별된다. */
+export const SEAT_COMPARE_UNMEASURED = '미측정';
+
+/** 한 표면의 원장 요약. `rows === null` 은 «못 읽었다» 이지 «0행» 이 아니다. */
+export interface SeatCompareLedgerSummary {
+  readonly surface: string;
+  readonly rows: number | null;
+  readonly lastSeq: number | null;
+  readonly lastState: string | null;
+}
+
+/** 판정 신호 입력 — 완료 경계가 이름으로 요구한 항목 그대로. */
+export interface SeatCompareSignalInput {
+  readonly runId: string | null;
+  readonly command: string | null;
+  readonly startedAt: number | null;
+  readonly endedAt: number | null;
+  /** 이 TUI 좌석 표면의 원장 행 요약(pty_manifest 턴 행). */
+  readonly tuiRunState: SeatCompareLedgerSummary;
+  /** 비교 상대 표면의 원장 행 요약(`pty_events`). */
+  readonly ptyEventLog: SeatCompareLedgerSummary;
+  readonly outputBytes: number | null;
+  readonly errors: number | null;
+  readonly result: string | null;
+}
+
+function seatCompareText(value: string | null | undefined): string {
+  if (value === null || value === undefined) return SEAT_COMPARE_UNMEASURED;
+  // 한 줄 계약 — 값 안의 개행·연속 공백은 접어서 줄을 쪼개지 못하게 한다.
+  const flat = value.replace(/\s+/g, ' ').trim();
+  return flat.length > 0 ? flat : SEAT_COMPARE_UNMEASURED;
+}
+
+function seatCompareCount(value: number | null | undefined): string {
+  if (value === null || value === undefined || !Number.isFinite(value)) return SEAT_COMPARE_UNMEASURED;
+  return String(value);
+}
+
+function seatCompareAt(ms: number | null | undefined): string {
+  if (ms === null || ms === undefined || !Number.isFinite(ms)) return SEAT_COMPARE_UNMEASURED;
+  return new Date(ms).toISOString();
+}
+
+function seatCompareLedger(summary: SeatCompareLedgerSummary): string {
+  return [
+    `ledger:${seatCompareText(summary.surface)}`,
+    `rows=${seatCompareCount(summary.rows)}`,
+    `lastSeq=${seatCompareCount(summary.lastSeq)}`,
+    `lastState=${seatCompareText(summary.lastState)}`,
+  ].join(' ');
+}
+
+/** 판정 신호 한 줄 — 새 줄 없이 ` · ` 로 잇는다. 못 잰 항목은 «미측정» 으로 남는다. */
+export function buildSeatCompareSignalLine(input: SeatCompareSignalInput): string {
+  return [
+    `run=${seatCompareText(input.runId)}`,
+    `cmd=${seatCompareText(input.command)}`,
+    `start=${seatCompareAt(input.startedAt)}`,
+    `end=${seatCompareAt(input.endedAt)}`,
+    seatCompareLedger(input.tuiRunState),
+    seatCompareLedger(input.ptyEventLog),
+    `bytes=${seatCompareCount(input.outputBytes)}`,
+    `errors=${seatCompareCount(input.errors)}`,
+    `result=${seatCompareText(input.result)}`,
+  ].join(' · ');
+}
+
+/** 생산 이음매 — `pty_events` 원장에서 이 표면의 행을 실제로 읽어 요약한다. 못 읽으면 rows=null(미측정). */
+export function readPtyEventLogLedger(surfaceId: string, dbPath: string = ptyEventLogDbPath()): SeatCompareLedgerSummary {
+  const surface = 'pty-event-log';
+  const read = readPtyEventsAfterAt(dbPath, 0, { surfaceId });
+  if (read.status !== 'ok') return { surface, rows: null, lastSeq: null, lastState: null };
+  const last = read.rows.length > 0 ? read.rows[read.rows.length - 1] : undefined;
+  return { surface, rows: read.rows.length, lastSeq: last ? last.seq : 0, lastState: last?.state ?? null };
+}
+
+/** 기본 기록 위치 — 셸 도구와 같은 파일(`seat-state/OP/tools/sim-log.log`). `ELANOUS_SEAT_COMPARE_LOG` 로 바꾼다. */
+export const SEAT_COMPARE_LOG_PATH = join(CODE_ROOT, 'seat-state', 'OP', 'tools', 'sim-log.log');
+
+export interface SeatCompareWriteDeps {
+  readonly path?: string;
+  /** append 이음매 — 시험이 임시 파일·메모리로 바꾼다. */
+  readonly append?: (path: string, line: string) => void;
+}
+
+/** 판정 신호 한 줄을 sim-log 에 append 한다. 실패(권한 등)는 false — 종료 경로를 깨지 않는다. */
+export function appendSeatCompareSignalLine(line: string, deps: SeatCompareWriteDeps = {}): boolean {
+  const path = deps.path ?? (process.env.ELANOUS_SEAT_COMPARE_LOG?.trim() || SEAT_COMPARE_LOG_PATH);
+  try {
+    if (deps.append) {
+      deps.append(path, line);
+    } else {
+      mkdirSync(dirname(path), { recursive: true });
+      appendFileSync(path, `${line}\n`, 'utf8');
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 생산 진입점 스위치 — `ELANOUS_SEAT_COMPARE_RUN_ID` 가 있을 때만 좌석 대조 원장을 켠다.
+ * 없으면 `null` = 녹음기가 그 한 줄을 안 남긴다(«미실행은 미측정»).
+ */
+export function seatCompareDepsFromEnv(env: NodeJS.ProcessEnv = process.env): TuiSeatCompareDeps | null {
+  const runId = env.ELANOUS_SEAT_COMPARE_RUN_ID?.trim();
+  if (!runId) return null;
+  const command = env.ELANOUS_SEAT_COMPARE_COMMAND?.trim() || [process.execPath, ...process.argv.slice(1)].join(' ');
+  return { runId, command };
+}
+
+/** 좌석 대조 판정 신호를 켜는 손잡이 — 주면 녹음기 종료 경로가 두 표면 원장을 읽어 한 줄을 남긴다. */
+export interface TuiSeatCompareDeps {
+  readonly runId: string | null;
+  readonly command?: string | null;
+  /** 산출 바이트 — 녹음기가 못 재면 생략(«미측정»). */
+  readonly outputBytes?: number | null;
+  /** 결과 판정 문구 — 생략하면 종료 시 마지막 턴 상태. */
+  readonly result?: string | null;
+  /** 원장 요약 읽기 이음매(시험: 가짜 원장). 생략하면 실 `pty_events`. */
+  readonly readLedger?: (surfaceId: string) => SeatCompareLedgerSummary;
+  /** 기록 이음매(시험: 메모리). 생략하면 sim-log 파일 append. */
+  readonly write?: (line: string) => boolean;
+}
+
 // ── 기록(TUI) ──
 
 export interface TuiRunStateRecorderDeps {
@@ -524,6 +658,11 @@ export interface TuiRunStateRecorderDeps {
    * 생략하면 감시를 안 건다 — 이 축을 켜는 것은 호출자(생산 진입점)의 결정이다.
    */
   readonly selfRestart?: TuiSelfRestartDeps;
+  /**
+   * TUI-SEAT-PILOT-2H-COMPARE 좌석 대조 판정 신호. 주면 종료 경로가 두 표면(pty_manifest 턴 행 ⊕
+   * `pty_events`)의 원장행을 읽어 «한 줄» 을 sim-log 에 남긴다. 생략하면 아무것도 안 남긴다(미실행=미측정).
+   */
+  readonly seatCompare?: TuiSeatCompareDeps;
 }
 
 interface ActiveRecorder {
@@ -550,9 +689,29 @@ const defaultLog = (event: string, data: Record<string, unknown>): void => { deb
 export function startTuiRunStateRecorder(surfaceId: string, deps: TuiRunStateRecorderDeps = {}): () => void {
   const now = deps.now ?? Date.now;
   const log = deps.log ?? defaultLog;
-  const writeTurn = deps.writeTurn ?? updatePtyManifestTurn;
+  const writeTurnBase = deps.writeTurn ?? updatePtyManifestTurn;
   const writeProgress = deps.writeProgress ?? updatePtyManifestProgress;
   const writeAbortRequested = deps.writeAbortRequested ?? updatePtyManifestAbortRequested;
+  // 좌석 대조 신호가 켜졌을 때만 턴 행 수·쓰기 실패를 센다 — 꺼져 있으면 판정 신호 비용 0.
+  const seatCompare = deps.seatCompare ?? null;
+  // 시작 시각도 신호가 켜졌을 때만 잰다 — 꺼져 있으면 종전과 같이 now() 를 한 번도 더 부르지 않는다.
+  const seatCompareStartedAt = seatCompare ? now() : 0;
+  let seatCompareTurnRows = 0;
+  let seatCompareWriteFailures = 0;
+  const writeTurn = seatCompare
+    ? (id: string, turn: PtyTurnState, at: number): boolean => {
+      let ok = false;
+      try {
+        ok = writeTurnBase(id, turn, at);
+      } catch (error) {
+        seatCompareWriteFailures += 1;
+        throw error;
+      }
+      if (ok) seatCompareTurnRows += 1;
+      else seatCompareWriteFailures += 1;
+      return ok;
+    }
+    : writeTurnBase;
   // 기본 신고기는 기본 manifest 쓰기와 짝일 때만. writeTurn 주입(시험)은 herdr 를 안 만든다.
   const herdr = deps.herdr !== undefined
     ? deps.herdr
@@ -564,6 +723,7 @@ export function startTuiRunStateRecorder(surfaceId: string, deps: TuiRunStateRec
   if (build) {
     const ok = (() => { try { return (deps.writeBuild ?? updatePtyManifestBuild)(surfaceId, build); } catch { return false; } })();
     log(ok ? 'build-recorded' : 'build-write-failed', { ptyId: surfaceId, sha: build.sha, version: build.version, source: build.source });
+    if (!ok) seatCompareWriteFailures += 1;
   }
   // 기동 순서: 판 → manifest 초기 idle → herdr 신고. herdr start 가 idle 을 신고하므로 초기 idle 을 turn 으로 다시 안 보낸다.
   const recorder: ActiveRecorder = { surfaceId, now, writeTurn, writeProgress, writeAbortRequested, log, herdr, herdrLast: herdr ? 'idle' : undefined };
@@ -662,6 +822,32 @@ export function startTuiRunStateRecorder(surfaceId: string, deps: TuiRunStateRec
     try { unwatch(); } catch { /* 종료 경로를 깨지 않는다 */ }
     try { unguard(); } catch { /* 종료 경로를 깨지 않는다 */ }
     if (herdr) { try { herdr.release(); } catch { /* 종료 경로를 깨지 않는다 */ } }
+    // 좌석 대조 판정 신호 — 두 표면의 원장 행을 «여기서» 읽어 한 줄로 남긴다.
+    if (seatCompare) {
+      try {
+        const readLedger = seatCompare.readLedger ?? readPtyEventLogLedger;
+        const line = buildSeatCompareSignalLine({
+          runId: seatCompare.runId,
+          command: seatCompare.command ?? null,
+          startedAt: seatCompareStartedAt,
+          endedAt: now(),
+          tuiRunState: {
+            surface: 'tui-run-state',
+            rows: seatCompareTurnRows,
+            lastSeq: null,
+            lastState: recorder.last ?? null,
+          },
+          ptyEventLog: readLedger(surfaceId),
+          outputBytes: seatCompare.outputBytes ?? null,
+          errors: seatCompareWriteFailures,
+          result: seatCompare.result ?? recorder.last ?? null,
+        });
+        const written = (seatCompare.write ?? appendSeatCompareSignalLine)(line);
+        log(written ? 'seat-compare-signal' : 'seat-compare-signal-write-failed', { ptyId: surfaceId, line });
+      } catch (error) {
+        log('seat-compare-signal-failed', { ptyId: surfaceId, error: error instanceof Error ? error.message : String(error) });
+      }
+    }
     if (active === recorder) active = null;
   };
 }

package/src/registry/catalog-server.ts

@@ -0,0 +1,232 @@
+import { createPublicKey, sign, verify, type KeyObject } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { debug } from '../debug/log.js';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+import type { ModelSpec, ProviderRegistration } from './types.js';
+
+export const CATALOG_SERVER_URL = 'https://storage.googleapis.com/elanous-catalog/v1/catalog.json';
+export const CATALOG_REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const CATALOG_STARTUP_TIMEOUT_MS = 2_000;
+
+export interface SignedCatalogPayload {
+  catalogVersion: number;
+  generatedAt: string;
+  providers: ProviderRegistration[];
+  models: ModelSpec[];
+}
+
+export interface SignedCatalogDocument extends SignedCatalogPayload {
+  signature: string;
+}
+
+export interface VerifiedCatalog {
+  payload: SignedCatalogPayload;
+  stale: boolean;
+}
+
+function catalogVersionFromFile(path: string): number | undefined {
+  try {
+    const match = readFileSync(path, 'utf8').match(/^catalogVersion:\s*(\d+)\s*$/m);
+    const version = match ? Number(match[1]) : NaN;
+    return Number.isSafeInteger(version) && version >= 1 ? version : undefined;
+  } catch { return undefined; }
+}
+
+function bundledCatalogVersion(): number | undefined {
+  let current = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 8; depth += 1) {
+    const candidate = join(current, 'catalog', 'meta', 'catalogVersion.yaml');
+    if (existsSync(candidate)) return catalogVersionFromFile(candidate);
+    current = dirname(current);
+  }
+  return undefined;
+}
+
+export function catalogCachePath(): string {
+  const override = process.env.ELANOUS_CATALOG_SERVER_CACHE?.trim();
+  if (override) return override;
+  return join(getElanousConfigDir(), 'catalog', 'cache.json');
+}
+
+function bundledPublicKeyPath(): string {
+  const override = process.env.ELANOUS_CATALOG_PUBLIC_KEY_FILE?.trim();
+  if (override) return override;
+  let current = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 8; depth += 1) {
+    const candidate = join(current, 'catalog', 'signing', 'catalog-signing-public.pem');
+    if (existsSync(candidate)) return candidate;
+    current = dirname(current);
+  }
+  return join(dirname(fileURLToPath(import.meta.url)), '../../catalog/signing/catalog-signing-public.pem');
+}
+
+export function canonicalCatalogPayload(payload: SignedCatalogPayload): string {
+  return JSON.stringify({
+    catalogVersion: payload.catalogVersion,
+    generatedAt: payload.generatedAt,
+    providers: payload.providers,
+    models: payload.models,
+  });
+}
+
+export function signCatalogPayload(payload: SignedCatalogPayload, privateKey: string | Buffer | KeyObject): SignedCatalogDocument {
+  return { ...payload, signature: sign(null, Buffer.from(canonicalCatalogPayload(payload)), privateKey).toString('base64') };
+}
+
+function parsePayload(value: unknown): SignedCatalogPayload | null {
+  if (!value || typeof value !== 'object') return null;
+  const raw = value as Record<string, unknown>;
+  if (!Number.isSafeInteger(raw.catalogVersion) || (raw.catalogVersion as number) < 1) return null;
+  if (typeof raw.generatedAt !== 'string' || !Number.isFinite(Date.parse(raw.generatedAt))) return null;
+  if (!Array.isArray(raw.providers) || !Array.isArray(raw.models)) return null;
+  if (!raw.providers.every((p) => p && typeof p === 'object' && typeof (p as Record<string, unknown>).id === 'string')) return null;
+  if (!raw.models.every((m) => m && typeof m === 'object'
+    && typeof (m as Record<string, unknown>).id === 'string'
+    && typeof (m as Record<string, unknown>).provider === 'string')) return null;
+  return {
+    catalogVersion: raw.catalogVersion as number,
+    generatedAt: raw.generatedAt,
+    providers: raw.providers as ProviderRegistration[],
+    models: raw.models as ModelSpec[],
+  };
+}
+
+export function verifyCatalogDocument(
+  value: unknown,
+  publicKeyPem: string,
+): SignedCatalogPayload | null {
+  if (!value || typeof value !== 'object') return null;
+  const raw = value as Record<string, unknown>;
+  if (typeof raw.signature !== 'string') return null;
+  const payload = parsePayload(raw);
+  if (!payload) return null;
+  try {
+    const signature = Buffer.from(raw.signature, 'base64');
+    return verify(null, Buffer.from(canonicalCatalogPayload(payload)), createPublicKey(publicKeyPem), signature)
+      ? payload
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readVerifiedCatalogCache(opts: {
+  cachePath?: string;
+  publicKeyPem?: string;
+  now?: number;
+} = {}): VerifiedCatalog | null {
+  const path = opts.cachePath ?? catalogCachePath();
+  try {
+    const key = opts.publicKeyPem ?? readFileSync(bundledPublicKeyPath(), 'utf8');
+    const payload = verifyCatalogDocument(JSON.parse(readFileSync(path, 'utf8')), key);
+    if (!payload) return null;
+    const age = Math.max(0, (opts.now ?? Date.now()) - Date.parse(payload.generatedAt));
+    const stale = age > CATALOG_REFRESH_INTERVAL_MS;
+    debug.log('registry.catalog', 'catalog.source', { source: 'server-cache', stale, catalogVersion: payload.catalogVersion });
+    if (stale) debug.log('registry.catalog', 'catalog.stale', { source: 'server-cache', stale: true, ageMs: age, catalogVersion: payload.catalogVersion }, { level: 'warn' });
+    return { payload, stale };
+  } catch {
+    return null;
+  }
+}
+
+export type RefreshCatalogResult =
+  | { ok: true; payload: SignedCatalogPayload }
+  | { ok: false; reason: 'key-unavailable' | 'fetch-failed' | 'http-error' | 'invalid-json' | 'signature-rejected' | 'version-rejected' | 'cache-write-failed' };
+
+export async function refreshServerCatalog(opts: {
+  fetchImpl?: typeof fetch;
+  url?: string;
+  cachePath?: string;
+  publicKeyPem?: string;
+  timeoutMs?: number;
+} = {}): Promise<RefreshCatalogResult> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const cachePath = opts.cachePath ?? catalogCachePath();
+  const timeoutMs = opts.timeoutMs ?? CATALOG_STARTUP_TIMEOUT_MS;
+  let key: string;
+  try {
+    key = opts.publicKeyPem ?? readFileSync(bundledPublicKeyPath(), 'utf8');
+  } catch (error) {
+    debug.log('registry.catalog', 'catalog.refresh-failed', { source: 'server', reason: 'key-unavailable', message: error instanceof Error ? error.message : String(error) }, { level: 'warn' });
+    return { ok: false, reason: 'key-unavailable' };
+  }
+  const previous = readVerifiedCatalogCache({ cachePath, publicKeyPem: key });
+  let response: Response;
+  try {
+    response = await fetchImpl(opts.url ?? CATALOG_SERVER_URL, { signal: AbortSignal.timeout(timeoutMs) });
+  } catch (error) {
+    debug.log('registry.catalog', 'catalog.refresh-failed', { source: 'server', reason: 'fetch-failed', message: error instanceof Error ? error.message : String(error) }, { level: 'warn' });
+    return { ok: false, reason: 'fetch-failed' };
+  }
+  if (!response.ok) return { ok: false, reason: 'http-error' };
+  let document: unknown;
+  try { document = await response.json(); }
+  catch { return { ok: false, reason: 'invalid-json' }; }
+  const payload = verifyCatalogDocument(document, key);
+  if (!payload) {
+    debug.log('registry.catalog', 'catalog.signature-rejected', { source: 'server', reason: 'invalid-signature-or-schema' }, { level: 'warn' });
+    return { ok: false, reason: 'signature-rejected' };
+  }
+  // A cold install has no signed server receipt yet, so the packaged catalog is its rollback floor.
+  const versionFloor = Math.max(previous?.payload.catalogVersion ?? 0,
+    bundledCatalogVersion() ?? 0);
+  if (payload.catalogVersion < versionFloor) {
+    debug.log('registry.catalog', 'catalog.version-rejected', {
+      source: 'server', reason: 'version-rollback', currentVersion: versionFloor, receivedVersion: payload.catalogVersion,
+    }, { level: 'warn' });
+    return { ok: false, reason: 'version-rejected' };
+  }
+  const signedDocument = document as SignedCatalogDocument;
+  try {
+    mkdirSync(dirname(cachePath), { recursive: true });
+    const temporary = `${cachePath}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(signedDocument, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(temporary, cachePath);
+  } catch (error) {
+    debug.log('registry.catalog', 'catalog.refresh-failed', { source: 'server', reason: 'cache-write-failed', message: error instanceof Error ? error.message : String(error) }, { level: 'warn' });
+    return { ok: false, reason: 'cache-write-failed' };
+  }
+  const ageMs = Math.max(0, Date.now() - Date.parse(payload.generatedAt));
+  debug.log('registry.catalog', 'catalog.source', {
+    source: 'server', stale: ageMs > CATALOG_REFRESH_INTERVAL_MS, catalogVersion: payload.catalogVersion,
+  });
+  return { ok: true, payload };
+}
+
+let scheduledRefresh: Promise<void> | null = null;
+let lastRefreshAttempt = 0;
+let refreshTimer: ReturnType<typeof setTimeout> | null = null;
+
+/** Kick remote refresh behind startup; the callback rebuilds the catalog only after a verified cache write. */
+export function scheduleServerCatalogRefresh(onUpdated: () => void): void {
+  if (process.env.NODE_ENV === 'test') return;
+  if (scheduledRefresh || refreshTimer) return;
+  const now = Date.now();
+  const cached = readVerifiedCatalogCache();
+  const cacheAgeMs = cached ? Math.max(0, now - Date.parse(cached.payload.generatedAt)) : Number.POSITIVE_INFINITY;
+  const untilCacheStale = cached && !cached.stale ? Math.max(1_000, CATALOG_REFRESH_INTERVAL_MS - cacheAgeMs) : 0;
+  const untilRetry = Math.max(0, CATALOG_REFRESH_INTERVAL_MS - (now - lastRefreshAttempt));
+  const delay = Math.max(untilCacheStale, untilRetry);
+  if (delay > 0) {
+    refreshTimer = setTimeout(() => {
+      refreshTimer = null;
+      scheduleServerCatalogRefresh(onUpdated);
+    }, delay);
+    refreshTimer.unref?.();
+    return;
+  }
+  lastRefreshAttempt = now;
+  scheduledRefresh = refreshServerCatalog().then((result) => {
+    if (result.ok) onUpdated();
+  }).finally(() => {
+    scheduledRefresh = null;
+    refreshTimer = setTimeout(() => {
+      refreshTimer = null;
+      scheduleServerCatalogRefresh(onUpdated);
+    }, CATALOG_REFRESH_INTERVAL_MS);
+    refreshTimer.unref?.();
+  });
+}

package/src/registry/loader.ts

@@ -31,6 +31,8 @@ import type {
 } from './types.js';
 import { PROVIDER_CAPABILITIES_NONE } from './types.js';
 import { readDiscoveryCache, type DiscoverySnapshot } from './discovery/cache.js';
+import { debug } from '../debug/log.js';
+import { readVerifiedCatalogCache, scheduleServerCatalogRefresh } from './catalog-server.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -85,6 +87,15 @@ function listYamlFiles(dir: string): string[] {
     .map((e) => join(dir, e));
 }
 
+function readCatalogVersion(builtinDir: string): number {
+  const path = join(builtinDir, 'meta', 'catalogVersion.yaml');
+  if (!existsSync(path)) return 1;
+  const raw = safeReadYaml(path) as { catalogVersion?: unknown } | null;
+  return Number.isSafeInteger(raw?.catalogVersion) && (raw?.catalogVersion as number) >= 1
+    ? raw?.catalogVersion as number
+    : 1;
+}
+
 // ── Provider parse + validate ─────────────────────────────────────────
 
 function parseProvider(raw: unknown, source: string): ProviderRegistration | null {
@@ -282,11 +293,13 @@ let cachedCatalog: Catalog | null = null;
 
 function buildCatalog(): Catalog {
   const builtinDir = resolveBuiltinCatalogDir();
+  const catalogVersion = readCatalogVersion(builtinDir);
   const globalDir = resolveGlobalCatalogDir();
 
   const providers = new Map<string, ProviderRegistration>();
   const models = new Map<string, ModelSpec>();
   const patterns = new Map<string, ModelPatternFallback>();
+  const sourceLayers = ['package'];
   let fileCount = 0;
 
   // --- builtin tier ---
@@ -326,12 +339,36 @@ function buildCatalog(): Catalog {
     }
   }
 
+  // --- signed server catalog; package YAML remains available if cache is absent/stale-invalid ---
+  // Keep isolated tests hermetic; an explicit cache path opts a test into the signed-server layer.
+  const serverCatalog = isolatedCatalogTestUniverse() && !process.env.ELANOUS_CATALOG_SERVER_CACHE?.trim()
+    ? null
+    : readVerifiedCatalogCache();
+  if (serverCatalog) {
+    sourceLayers.push('server-cache');
+    for (const raw of serverCatalog.payload.providers) {
+      const provider = parseProvider(raw, 'signed-server-catalog');
+      if (!provider) continue;
+      const base = providers.get(provider.id);
+      providers.set(provider.id, base ? mergeProviders(base, provider) : provider);
+      fileCount++;
+    }
+    for (const raw of serverCatalog.payload.models) {
+      const model = parseModel(raw, 'signed-server-catalog');
+      if (!model) continue;
+      models.set(model.id, model);
+      fileCount++;
+    }
+  }
+
   // --- global tier overlay ---
   const globalProviderDir = join(globalDir, 'providers');
+  let hasUserOverlay = false;
   for (const path of listYamlFiles(globalProviderDir)) {
     const raw = safeReadYaml(path);
     const overlay = parseProvider(raw, path);
     if (!overlay) continue;
+    hasUserOverlay = true;
     fileCount++;
     const base = providers.get(overlay.id);
     providers.set(overlay.id, base ? mergeProviders(base, overlay) : overlay);
@@ -359,6 +396,7 @@ function buildCatalog(): Catalog {
         }
         const model = parseModel(raw, path);
         if (model) {
+          hasUserOverlay = true;
           // global wins on dup id (RFC §6.4 — single-value fields replace).
           models.set(model.id, model);
           fileCount++;
@@ -370,9 +408,14 @@ function buildCatalog(): Catalog {
   // --- discovery fold (대표 2026-09-23 «파생한다») ---
   const folded = foldDiscoveredModels(providers, models, loadFoldSnapshot());
   for (const m of folded) models.set(m.id, m);
+  if (hasUserOverlay) sourceLayers.push('user');
+  if (folded.length > 0) sourceLayers.push('live-discovery');
+  debug.log('registry.catalog', 'catalog.source', {
+    source: 'merged', layers: sourceLayers, ...(serverCatalog ? { stale: serverCatalog.stale } : {}),
+  });
 
   return {
-    catalogVersion: 1,
+    catalogVersion,
     providers,
     models,
     patterns,
@@ -435,6 +478,7 @@ export function foldDiscoveredModels(
 export function getCatalog(): Catalog {
   if (cachedCatalog) return cachedCatalog;
   cachedCatalog = buildCatalog();
+  scheduleServerCatalogRefresh(() => { cachedCatalog = buildCatalog(); });
   return cachedCatalog;
 }
 

package/src/registry/types.ts

@@ -196,8 +196,7 @@ export interface ModelPatternFallback {
 // ── Top-level catalog (loader output) ─────────────────────────────────
 
 export interface Catalog {
-  /** Schema version — bumps when ProviderRegistration / ModelSpec
-   *  shape changes in a non-backwards-compat way. */
+  /** Catalog release version from catalog/meta/catalogVersion.yaml. */
   catalogVersion: number;
   /** Indexed by provider id. */
   providers: Map<string, ProviderRegistration>;

package/src/release-loop/checklist-target-path-hint.ts

@@ -0,0 +1,13 @@
+export interface TargetPathHintLine {
+  readonly fragments: readonly string[];
+  readonly labelMissing: boolean;
+}
+
+/** Parse the first declared target-path line shared by checklist storage and ask preflight. */
+export function parseTargetPathHintLine(text: string): TargetPathHintLine {
+  const firstLine = text.split(/\r?\n/).find((line) => line.trim() !== '');
+  if (firstLine === undefined) return { fragments: [], labelMissing: true };
+  const match = /^\s*(?:대상\s*경로|target\s*paths?)\s*[:：]\s*(.*)$/i.exec(firstLine);
+  if (!match) return { fragments: [], labelMissing: true };
+  return { fragments: match[1]!.split(/[·,;]/), labelMissing: false };
+}

package/src/release-loop/checklist.ts

@@ -5,6 +5,9 @@ import { isAbsolute, join } from 'node:path';
 import * as store from './feature-store.js';
 import { debug } from '../debug/log.js';
 import { CliUserError } from '../cli/cli-user-error.js';
+import { parseTargetPathHintLine } from './checklist-target-path-hint.js';
+export { parseTargetPathHintLine } from './checklist-target-path-hint.js';
+export type { TargetPathHintLine } from './checklist-target-path-hint.js';
 
 export type ChecklistStatus = 'green' | 'yellow' | 'red' | 'done';
 export type ChecklistDisposition = 'move' | 'known-issue' | 'block';
@@ -248,6 +251,11 @@ export function isMergeOrTypecheckOnlyEvidence(value: string): boolean {
   return signal;
 }
 
+/** Parsed target path fragments, preserving order and raw path spelling while trimming separator whitespace. */
+export function parseChecklistTargetPaths(text: string): string[] {
+  return parseTargetPathHintLine(text).fragments.map((fragment) => fragment.trim().replace(/^`+|`+$/g, ''));
+}
+
 /** Shadow check at checklist authorship. Callers supply the origin/main file probe and merged-PR file reader. */
 export function inspectChecklistTargetPaths(input: {
   title: string; evidence?: string; refs?: readonly string[]; dispatchKind?: ChecklistDispatchKind;
@@ -256,7 +264,7 @@ export function inspectChecklistTargetPaths(input: {
 } {
   const lines = input.title.split(/\r?\n/);
   const first = /^대상 경로:\s*(.*)$/.exec(lines[0] ?? '');
-  const rawTargets = first?.[1]?.split(' · ').map((path) => path.trim()) ?? [];
+  const rawTargets = parseChecklistTargetPaths(lines[0] ?? '');
   const validPath = (path: string): boolean => path.length > 0 && path.length < 4096
     && !path.startsWith('/') && !path.includes('\\') && !/[\u0000-\u001f\u007f]/u.test(path)
     && path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');